<!-- mcp-tool-guidance-callout --> > [!note] > **Before picking up this work:** this issue adds an MCP tool. Please follow the [Adding a new tool](https://docs.gitlab.com/development/duo_agent_platform/mcp/#adding-a-new-tool) guidance first. That includes creating an MCP Tool Proposal, using `verb_object` naming (`get_` / `list_` / `save_` / `delete_`), and the shared resource-identification input base classes. ## Problem Statement / Use Case Agents and users constantly need to read the contents of a single file from a GitLab repository (to understand code, quote it, or edit it). This is the highest-traffic tool in the migration set (~1.7M calls, ~28k users), so its shape directly drives context cost across the whole platform. `get_repository_file` returns the contents of one file at a given ref, with line-range pagination so large files never blow the context window. It preserves the established public tool name and the shipped `offset`/`limit` line-pagination behavior rather than retrofitting a `detail` enum (which only fits diffs, not file content). ## Scope and Non-Goals - **In scope:** read one file's contents at a ref; line-range windowing via `offset`/`limit`. - **Non-goals:** directory listing (that's `list_repository_tree`), diffs (`get_commit`), writing files (`create_commit`), binary rendering. - **Follow-ups:** none planned; this stays a discrete standalone reader (file-scoped, not commit-scoped). ## Data Shape and Context Engineering Line pagination is the context-saturation guard: default `limit` caps returned lines, and metadata tells the model how many lines remain and how to fetch the next window. No `detail` knob here (file content has no `stats`/`full_patch` variants). - Input schema (example): ```json { "tool": "get_repository_file", "description": "Read the contents of a single file from a GitLab repository at a given ref, with optional line-range windowing.", "parameters": { "url": "string (optional; GitLab file URL, encodes project + path)", "project_id": "int | string (optional; numeric ID or URL-encoded path)", "file_path": "string (e.g. lib/class.rb)", "ref": "string (branch/tag/commit; HEAD for default branch)", "offset": "integer (optional, >=0; 0-indexed start line)", "limit": "integer (optional, >=1; lines from offset)" } } ``` - Output schema (JSON example): ```json { "path": "app/models/user.rb", "ref": "main", "metadata": { "total_lines": 450, "returned_lines": { "start": 1, "end": 100 }, "truncated": true, "size_bytes": 15234 }, "content": "First 100 lines of content here", "system_instruction": "File truncated. Remaining lines: 350. To view more, call again with {\"offset\": 100, \"limit\": 100}." } ``` ### Resources (already implemented similar tools etc.) The file-content fetch maps to the existing GraphQL blob API — no need to read `repository.blob_at` directly via `Base::CustomService`. The `offset`/`limit` line-windowing and the Duo context-exclusion check are a thin custom layer *on top of* a GraphQL fetch, not a reason to skip the API for the base data path. - Existing GraphQL field: `Query.project(fullPath:) { repository { blobs(ref:, paths:) } }` — `Resolvers::BlobsResolver` (`app/graphql/resolvers/blobs_resolver.rb`), typed `Types::Repository::BlobType` (`RepositoryBlob`, `app/graphql/types/repository/blob_type.rb`). Pass a single-element `paths: [file_path]` for the one-file case. - Field mapping on `RepositoryBlob`: `rawBlob` (`method: :data`, the same raw content the old `blob_at` call returned) → `content` source; `size` → `size_bytes`; `rawSize` → full size; `storedExternally`/`externalStorage` → LFS handling; `rawTextBlob`/`plainData` → plaintext; `simpleViewer { fileType }` (`Types::BlobViewerType`) → binary detection (no direct `binary` boolean on the type). `name`/`path` for identity. - Resource resolution: `Mcp::Tools::Concerns::ResourceFinder#find_parent_by_id_or_path!` + `Mcp::Tools::Concerns::UrlParser` (`parse_blob_url`) — the `project(fullPath:)` query only accepts a path, so resolve `project_id`/`url` to the project first. - Reference shape: `list_merge_requests` (`app/services/mcp/tools/merge_requests/list_merge_requests_{tool,service}.rb`) — GraphQL-backed reader resolving a project + selecting a nested field. - MCP dev guidelines: `doc/development/duo_agent_platform/mcp/_index.md`; `gitlab-mcp-tool-builder` skill's build recipe — verify a GraphQL field exists before writing a custom one. ### Implementation Plan 1. Two classes: `Mcp::Tools::Repositories::GetRepositoryFileTool < Mcp::Tools::Base::GraphqlTool` and `Mcp::Tools::Repositories::GetRepositoryFileService < Base::GraphqlService` (not `Base::CustomService`). 2. Operation file: `app/graphql/queries/mcp/repositories/get_repository_file.query.graphql`, selecting `project(fullPath:) { repository { blobs(ref:, paths:) { nodes { rawBlob rawTextBlob size rawSize storedExternally externalStorage name path simpleViewer { fileType } } } } }`. 3. Resolve `url`/`project_id` + `file_path`/`ref` via `ResourceFinder`/`UrlParser` (keep the existing URL cross-validation), then pass `fullPath`, `ref`, and `paths: [file_path]`. 4. **Custom layer, kept in `process_result` (not a reason for CustomService):** - Line-windowing: slice `rawBlob.lines[offset, limit]`, build `metadata` (`total_lines`, `returned_lines`, `truncated`, `size_bytes` from `size`) and the `system_instruction` next-window hint. Unchanged from the current behavior. - Duo context exclusion: keep the EE pre-check (`duo_context_exclusion_settings`) — `BlobsResolver` does not apply it, so it stays a guard in the tool (EE override). - Binary/LFS: return the binary error when `simpleViewer.fileType` indicates non-text (or `rawTextBlob` is null); return the LFS error when `storedExternally` is true. - Not-found: `blobs` returns an empty connection for a missing path — map that to the existing "file not found" message; distinguish a bad ref (resolver error / `repository` check) from a missing path. 5. **Confirm the size cap matches:** the previous `blob_at(..., limit: MAX_DATA_DISPLAY_SIZE)` cap must line up with how `rawBlob`/`data` is loaded via `blobs_at`, so `truncated`/`size_bytes` metadata stays accurate. Verify during implementation. 6. Register in `GRAPHQL_TOOLS` (CE) / the EE manager as appropriate in `app/services/mcp/tools/manager.rb`. 7. Specs: `spec/graphql/all_queries_spec.rb` coverage comes free from the committed `.graphql` file; add Tool/Service specs for a normal file, offset/limit windowing, past-end offset, large/truncated file, binary, LFS, missing path, missing ref, and the context-exclusion path (EE).