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