## Summary MCP server tools in `app/services/mcp/tools/` embed their GraphQL queries as inline Ruby `<<~GRAPHQL` HEREDOCs inside `build_query`/`build_mutation` class methods. We should move these into standalone `.graphql` files, the same way the frontend does (e.g. `app/assets/javascripts/pipeline_wizard/queries/create_commit.graphql`). A proof-of-concept on `CreateWorkItemNoteTool` confirms this works cleanly (details below). ## Why do this - **Automatic schema validation at build time.** `Gitlab::Graphql::Queries.all` recursively scans `app/graphql/queries`, and `spec/graphql/all_queries_spec.rb` validates every discovered `.graphql` file against `GitlabSchema`. Files placed under `app/graphql/queries/mcp/` get this for free — a class of "query drifted from the schema" bugs is caught in CI with **zero changes to validation infrastructure**. - **Readability.** Queries get real GraphQL syntax highlighting and lose Ruby-string indentation noise. The POC tool class dropped from 62 to 33 lines. - **Consistency.** Matches both the frontend convention and existing backend server-side queries already living in `app/graphql/queries/` (`repository/`, `pipelines/`, `snippet/`, `burndown_chart/`, …). - **No runtime cost.** The file is read once at class-load (inside `register_version`), stored as a frozen string in the version metadata, and reused on every call — the same memory/IO profile as the HEREDOC. ## Where files go Under `app/graphql/queries/mcp/`, mirroring the tool's subdirectory, using the frontend naming convention `*.query.graphql` / `*.mutation.graphql`: ``` app/graphql/queries/mcp/ work_items/create_note.mutation.graphql work_items/get_work_item_types.query.graphql merge_requests/create_note.mutation.graphql labels/search.query.graphql ``` `app/graphql/queries` is chosen over co-locating next to the tool because it is already a scanned root — co-locating under `app/services/mcp/tools/` would require editing the shared `Gitlab::Graphql::Queries.all` and would silently skip validation for any EE-located files. ## How to migrate a tool 1. Add a loader to the base class `Mcp::Tools::GraphqlTool` (`app/services/mcp/tools/graphql_tool.rb`): ```ruby QUERIES_ROOT = Rails.root.join('app/graphql/queries/mcp').freeze def self.load_graphql(relative_path) File.read(QUERIES_ROOT.join(relative_path)).freeze end ``` 2. Move the HEREDOC body verbatim into a `.graphql` file under `app/graphql/queries/mcp/<group>/<name>.{query,mutation}.graphql`. 3. Replace the `build_query`/`build_mutation` method and point the registration at the file, keeping `operation_name` unchanged: ```ruby register_version VERSIONS[:v0_1_0], { operation_name: 'createNote', graphql_operation: load_graphql('work_items/create_note.mutation.graphql') } ``` 4. Update the tool spec: drop the `.build_mutation`/`.build_query` assertions (the file is now validated by `all_queries_spec`); keep the `graphql_operation`/`operation_name` checks. **Use the direct `load_graphql(...)` form, not a lambda.** `graphql_operation_for_version` calls `.call` on callables every execute, so `-> { load_graphql(...) }` would re-read the file on every request. ### Operation naming convention Per [review feedback from @dstull](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/240899#note_3484840632): when extracting operations into `.graphql` files, use a **verb-first `get` prefix** for query operation names to match the existing convention in `app/graphql/queries/**`: - [`getBlobInfo`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/queries/repository/blob_info.query.graphql) - [`getProjectContainerRepositories`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/queries/container_registry/get_container_repositories.query.graphql) - `getPipelineDetails` The AIGW sibling tools also follow this pattern (e.g., `GetProjectWorkItemNotes`). So prefer `getMergeRequestNotes` over `MergeRequestNotes`, `getWorkItemTypes` over `WorkItemTypes`, etc. No eslint rule enforces this, but it keeps things consistent with neighbours. Mutations (e.g., `createNote`) already follow a verb-first pattern and don't need changes. ## Scope Migrate the 7 tools that use a static HEREDOC: - [x] `work_items/create_work_item_note_tool` (done as POC) - [ ] `work_items/link_work_items_tool` - [ ] `work_items/get_work_item_types_tool` - [ ] `work_items/get_saved_view_tool` - [ ] `work_items/get_work_item_notes_tool` - [ ] `merge_requests/create_merge_request_note_tool` - [ ] `labels/search_tool` (note: registers **no** `operation_name` — preserve that) **Out of scope:** `work_items/get_saved_view_work_items_tool`. Its query is composed at load time from `filter_definitions` + `widget_fragments` and **overridden by EE** via `prepend_mod`. A flat file would either break EE composition or need `#{…}` interpolation that fails schema validation — so it stays inline. <details> <summary>Proof-of-concept details &amp; verification</summary> Branch: [`mcp-graphql-files-poc`](https://gitlab.com/gitlab-org/gitlab/-/tree/mcp-graphql-files-poc) ([compare to master](https://gitlab.com/gitlab-org/gitlab/-/compare/master...mcp-graphql-files-poc)). Implemented on `CreateWorkItemNoteTool`. 5 files changed (+45 / −59): - `app/services/mcp/tools/graphql_tool.rb` — added `QUERIES_ROOT` + `load_graphql`. - `app/graphql/queries/mcp/work_items/create_note.mutation.graphql` (new) — the `CreateNote` mutation lifted verbatim. - `app/services/mcp/tools/work_items/create_work_item_note_tool.rb` — removed the `build_mutation` HEREDOC; registration now uses `load_graphql(...)`. - `spec/services/mcp/tools/work_items/create_work_item_note_tool_spec.rb` — removed the `.build_mutation` block; kept versioning assertions. - `spec/services/mcp/tools/graphql_tool_spec.rb` — added a `.load_graphql` spec (frozen string for a real file; `Errno::ENOENT` for a missing path). Verification — all green: - `bundle exec rspec spec/graphql/all_queries_spec.rb` → 1827 examples, 0 failures; the new file shows as `app/graphql/queries/mcp/work_items/create_note.mutation.graphql … is a valid query`. - `bundle exec rspec spec/services/mcp/tools/work_items/create_work_item_note_tool_spec.rb spec/services/mcp/tools/graphql_tool_spec.rb` → 49 examples, 0 failures. - `bundle exec rubocop` on the two changed Ruby files → no offenses. Safety: the path passed to `load_graphql` is a hardcoded developer constant, never user input, so there is no path-traversal vector; a wrong path raises `Errno::ENOENT` loudly at boot. This mirrors existing `File.read` usage in `app/helpers/startupjs_helper.rb` and `lib/gitlab/graphql/queries.rb`. </details>