MCP: name-based resolution for Projects fields

[veralizeth]

Summary

Let agents address Project v2 fields, options, and item values by name (read +write) instead of pre-resolved IDs. Resolution happens in the wrapper; the mutation stays ID-typed.

Why

Today an agent that wants to update a project field has to assemble several opaque IDs (project, item, field, single-select option) before it can write. The MCP update_project_item tool is only partly there, it accepts owner login, project number, and issue number, but the write still demands the field ID and item ID and does no option-name resolution.

update_project_item demands field ID + item ID and does no option-name resolution. Reads are ID-bound too: list_project_items returns only Title, so reading a field value needs a list_project_fields. This forces a list-and-filter dance, burns context, and invites mis-bound IDs.

The important part: this is a surfacing gap, not a platform gap. The GraphQL API already resolves names projectV2.field(name:), ProjectV2SingleSelectField.options(names:), ProjectV2Item.fieldValueByName(name:), plus top-level lookups by login / owner+name / project number. A single nested read can fetch every ID the write needs. The agent surface simply doesn't pass those resolvers through.

Closes #3430

What changed

• Write: update_project_item accepts a field via updated_field.name, resolves the single-select option by name, and resolves the item by item_owner + item_repo + issue_number when item_id is omitted. {id}/{name} mutually exclusive.
• Read: new optional field_names on get_project_item / list_project_items no list_project_fields preflight.
• Errors: name failures return typed, self-correctable JSON (field_not_found, field_ambiguous, option_not_found, item_not_in_project, …) with candidates. Backward compatible, existing ID paths unchanged; new inputs additive/optional.

Follow-up

• Pagination: item resolution reads projectItems(first: 50), bound and paginate Project item read payloads so an agent can pull field values for a large board without overflowing its buffer or burning context. #3332.

MCP impact

• No tool or API changes
• Tool schema or behavior changed
• New tool added

Prompts tested (tool changes only)

Security / limits

• No security or limits impact
• Auth / permissions considered
• Data exposure, filtering, or token/size limits considered

Schema token delta, measured with o200k_base:

Tool	Before	After	Δ
projects_get	307	397	+90
projects_list	359	449	+90
projects_write	845	958	+113
TOTAL	1,511	1,804	+293

How this was measured

Used mcpcurl schema to dump the tools/list payload (name + description +inputSchema) on main vs. this branch, tokenized both with tiktoken (o200k_base encoding), and diffed.

Prompts tested

• Set Status = "In Progress" on issue # 1 in project "veralizeth-test-p" by name.
• Read Status/Priority via field_names no field-ID preflight.
• Two "Status" fields → field_ambiguous with candidates.
• field_names: ["Statuss"] → field_not_found with candidates.

Tool renaming

• I am renaming tools as part of this PR (e.g. a part of a consolidation effort)
  • I have added the new tool aliases in deprecated_tool_aliases.go
• I am not renaming tools as part of this PR

Note: if you're renaming tools, you must add the tool aliases. For more information on how to do so, please refer to the official docs.

Lint & tests

• Linted locally with ./script/lint
• Tested locally with ./script/test

Docs

• Not needed
• Updated (README / docs / examples)

[Copilot]

Pull request overview

This PR enhances the Projects v2 MCP surface so agents can read and update project item field values using human-readable field/option names, with server-side resolution to the ID-typed REST/GraphQL operations that ultimately perform the write.

Changes:

• Add field_names support to get_project_item / list_project_items, resolving names to field IDs server-side.
• Extend update_project_item to accept updated_field by {name, value} (including single-select option-name resolution) and to resolve item_id from (item_owner, item_repo, issue_number) when omitted.
• Introduce structured, machine-readable resolution errors (field_not_found, field_ambiguous, option_not_found, item_not_in_project, etc.) and update docs/toolsnaps accordingly.

Show a summary per file

File	Description
README.md	Documents new field_names inputs and expanded update_project_item parameter behavior.
pkg/github/projects.go	Wires field_names into list/get flows and adds name-based item/field resolution for updates.
pkg/github/projects_resolver.go	New GraphQL-based resolvers for project field and item ID resolution by name/issue number.
pkg/github/projects_resolver_test.go	Adds unit/acceptance tests for name resolution and structured error behavior.
pkg/github/toolsnaps/projects_write.snap	Updates snapshot to reflect update_project_item schema/description changes.
pkg/github/toolsnaps/projects_list.snap	Updates snapshot to reflect field_names addition and updated fields description.
pkg/github/toolsnaps/projects_get.snap	Updates snapshot to reflect field_names addition and updated fields description.
pkg/errors/error.go	Adds StructuredResolutionError type + helpers for JSON error payloads.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 4
• Review effort level: Low

[zwick]

fields and field_names both resolve to field IDs, and the "use one or the other" rule only lives in the description text. This same pair shows up four times in the PR — the get_project_item and list_project_items schema blocks in projects.go, plus both .snap fixtures — so whatever we decide needs to apply the same way in all of them (README too).

Right now nothing stops a caller from sending both, and if they do, the handler quietly appends the resolved names onto fields (fields = append(fields, resolvedIDs...)) — which none of the four descriptions mention.

Two ways to go:

1. Put the constraint in the schema. It sits next to properties, at the inputSchema level (not inside a property), roughly:

   "inputSchema": {
     "properties": {
       "fields":      { "type": "array", "items": { "type": "string" }, "description": "..." },
       "field_names": { "type": "array", "items": { "type": "string" }, "description": "..." }
     },
     "oneOf": [
       { "not": { "required": ["fields", "field_names"] } },
       { "required": ["fields"],      "not": { "required": ["field_names"] } },
       { "required": ["field_names"], "not": { "required": ["fields"] } }
     ],
     "required": ["method"],
     "type": "object"
   }

   Two catches, and they hit every copy: neither field is required, so you need that first "neither" branch just to keep the common case legal; and these props are shared across methods on each tool (get_project_field/get_project_item, and the list methods), so a top-level oneOf would wrongly constrain the others. Doing it right means gating per method (if method == get_project_item ...) in all four spots — a lot of schema for what it buys.

2. Leave it in prose but enforce it once in the handler — reject when both are set with a structured error, exactly like updated_field already does for {id}+{name}. One check covers both read methods, and we just make the descriptions symmetric (field_names currently says nothing about the both-set case).

I'd go with 2 — the write path already draws this line in code, so matching it on the read path keeps things consistent, avoids repeating awkward schema in four places, and the fix lives in one spot instead of four. Open to 1 if we think the schema-level guarantee is worth the per-method branching.

[zwick]

We may want to follow-up on this PR with some extra field types.

Issue Fields and Issue Field Values attached to a Project Item have their own Node type that resolves slightly differently than standard project fields.

• One of the Memex teams has been working on MultiSelect fields which I believe recently started shipping to customers. It would be cool to get support for those in place as well (if they are ready, we should confirm first)

These are not blockers, I think this PR is already covering a lot of ground but would be great follow-ups to expand our coverage for different enum types