<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/engineering/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Close this issue](https://contributors.gitlab.com/manage-issue?action=close&projectId=278964&issueIid=632461) </details> <!--IssueSummary end--> ### Problem `get_work_item` identifies a work item by `url`, or by `work_item_iid` plus `project_id` or `group_id`. It has never had an `id` argument. Callers often send `id` anyway, meaning **the work item**, in one of these shapes: | Arguments sent | What `id` holds | Error | |---|---|---| | `{"id": "612377", "full_path": "gitlab-org/gitlab"}` | Work item IID, with the container in another key (`full_path`, `namespace_path`, `namespace`, `project`) | `Validation error: id is invalid, full_path is invalid` | | `{"id": "gid://gitlab/Epic/3779686"}` | Work item global ID | `Validation error: id is invalid` | These calls fail validation. Callers usually recover by retrying with `url`, at the cost of an extra round trip per lookup. #630772 skips every tool whose schema declares `work_item_iid`, because on those tools `id` usually means the work item, not the project. Nothing rewrites these calls today, and #630772 won't either. ### Steps to reproduce 1. Call `get_work_item` with `{"id": "<an issue IID>", "full_path": "gitlab-org/gitlab"}`. 2. The call fails with `Validation error: id is invalid, full_path is invalid`. 3. The same issue succeeds with `{"url": "https://gitlab.com/gitlab-org/gitlab/-/work_items/<iid>"}`. ### Proposal Add a second rewrite to the normalization step that #630772 adds to `API::Mcp::Handlers::CallTool#invoke`. It applies to the tools whose `input_schema` declares `work_item_iid`: `get_work_item`, `get_workitem_notes`, `link_work_items`, `save_note` and `save_work_item`. All five also declare `url`, `project_id` and `group_id`. | Caller sends | Rewrite | |---|---| | `id` holding `gid://gitlab/WorkItem/N` or `gid://gitlab/Issue/N` | Load work item `N`. If the current user can `read_work_item`, rewrite to `work_item_iid` plus the numeric `project_id`, or `group_id` for a group-level work item | | `id` holding `gid://gitlab/Epic/N` | Same, starting from the epic's work item (`epics.issue_id`). An Epic global ID holds the legacy epic ID, not the work item ID | | `id` plus `project` | `id` → `work_item_iid`, `project` → `project_id` | | `id` plus `full_path`, `namespace_path` or `namespace` | `id` → `work_item_iid`, and the path → `project_id` when a project has that path, otherwise `group_id` | Every other call passes through unchanged, including a bare numeric `id` with no container key. Make that validation error list the accepted ways to identify a work item (`url`, or `work_item_iid` with `project_id` or `group_id`), instead of only naming the rejected keys. Record each rewrite in the `normalized_arguments` log field from #630772, for example `["id:gid->work_item_iid"]` or `["id->work_item_iid", "full_path->project_id"]`. ### Constraints - Run in the same step as #630772, in `CallTool#invoke` before `track_start_event` and governance, for the reasons listed there. #630772 skips exactly the tools this rewrite covers, so the two never apply to the same call and their order doesn't matter. - Only rewrite a global ID when the current user can read the work item. `find_project!` and `find_group!` include the identifier in their "not found or inaccessible" message, so rewriting a work item the caller can't read would hand its container back to them. An unreadable global ID has to fail exactly like one that doesn't exist. - Governance needs no change. The rewritten `project_id` or `group_id` goes through the default `container_arguments`, so Deny rules on the work item's project or group still apply. - Read the schema from the fetched tool (`tool.input_schema`). Versioned tools define `input_schema` per instance, and there's no class-level one. - Don't advertise `id` in any schema. ### Acceptance criteria - [ ] `get_work_item` resolves a work item from each of `gid://gitlab/WorkItem/N`, `gid://gitlab/Issue/N` and `gid://gitlab/Epic/N`. - [ ] `id` with `full_path` resolves both a project-level and a group-level work item. - [ ] A global ID for a work item the caller can't read fails the same way as one that doesn't exist, and the error contains no path. - [ ] A Deny rule on the work item's project refuses a call that names the work item only by global ID. - [ ] `save_work_item` called with `id` and a container key updates that work item instead of creating a new one. - [ ] The rewrite runs on all five tools, and `normalized_arguments` records it. ### Out of scope - The legacy `id` → `project_id` mapping for other tools: #630772. - Other tools' parameter names.