<!-- 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 need to discover what files and directories exist in a repository before reading or editing them. This is the second-highest-traffic tool in the set (~580k calls). `list_repository_tree` returns the tree at a path/ref, optionally recursive, with pagination to bound large trees. It preserves the established public tool name. ## Scope and Non-Goals - **In scope:** list entries (files + subdirectories) at a path and ref; recursive traversal; pagination. - **Non-goals:** reading file contents (`get_repository_file`), diffs, writes. - **Follow-ups:** none; discrete collection reader. ## Data Shape and Context Engineering Recursive listings can be huge, so pagination (`first`/`after`, capped at 100) is the saturation guard. Each entry is metadata-only (path, type, mode, id) — never file content. - Input schema (example): ```json { "tool": "list_repository_tree", "description": "List files and directories in a GitLab repository at a given path and ref.", "parameters": { "url": "string (optional)", "project_id": "int | string (optional)", "path": "string (optional; subtree root)", "ref": "string (optional; branch/tag/commit, HEAD for default)", "recursive": "boolean (default: false)", "first": "integer (optional, 1-100, default: 20)", "after": "string (optional; cursor from the previous response's page_info.end_cursor)" } } ``` - Output schema (JSON example): ```json { "path": "app/", "ref": "main", "entries": [ { "id": "a1b2", "name": "models", "type": "tree", "path": "app/models" }, { "id": "c3d4", "name": "user.rb", "type": "blob", "path": "app/models/user.rb", "mode": "100644" } ], "page_info": { "has_next_page": true, "end_cursor": "eyJpZCI6..." } } ``` ### Resources (already implemented similar tools etc.) - Existing GraphQL field: `Query.project(fullPath:) { repository { paginatedTree(path:, ref:, recursive:) } }` — `Resolvers::PaginatedTreeResolver` (`app/graphql/resolvers/paginated_tree_resolver.rb`), `max_page_size: 100`, cursor pagination via `ExternallyPaginatedArrayExtension`. Arguments `path`, `ref`, `recursive`, `ref_type` cover this tool's `path`/`ref`/`recursive` exactly. - Output: `paginatedTree` yields `Types::Tree::TreeType` nodes, each exposing three connections — `trees` (directories), `blobs` (files), `submodules`. All three implement `Types::Tree::EntryType` (`app/graphql/types/tree/entry_type.rb`), which provides `id`, `sha`, `name`, `type` (`Tree::TypeEnum`: `tree`/`blob`/`commit`), `path`, `flatPath`; `Tree::BlobType` adds `mode`. Merge the three connections into the flat `entries` array client-side. - Resource resolution precedent: `Mcp::Tools::Concerns::ResourceFinder#find_parent_by_id_or_path!` (`app/services/mcp/tools/concerns/resource_finder.rb`) — the `project(fullPath:)` query only accepts a path, so resolve `project_id`/`url` to the project first (same as `list_merge_requests`). - 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 connection with cursor pagination. - 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::ListRepositoryTreeTool < Mcp::Tools::Base::GraphqlTool` and `Mcp::Tools::Repositories::ListRepositoryTreeService < Base::GraphqlService`. 2. Operation file: `app/graphql/queries/mcp/repositories/list_repository_tree.query.graphql`, calling `project(fullPath:) { repository { paginatedTree(path:, ref:, recursive:, first:, after:) { pageInfo { hasNextPage endCursor } nodes { trees { nodes { id sha name type path } } blobs { nodes { id sha name type path mode } } submodules { nodes { id sha name type path } } } } } }`. 3. `url`/`project_id` → `fullPath` via `find_parent_by_id_or_path!(:project, identifier)`. `path`/`ref`/`recursive` pass straight through; `ref` omitted → resolver defaults to `:head`. 4. Merge `trees` + `blobs` + `submodules` nodes into a single `entries` array in `process_result`, preserving `id`/`name`/`type`/`path` (+ `mode` for blobs). Unwrap any GID-shaped ids if present (tree entry `id` is a Gitaly OID string, not a GID — pass through as-is). 5. Pagination: `first`/`after`, returning `page_info.has_next_page`/`end_cursor` from `paginatedTree`'s `pageInfo`. 6. Register in `GRAPHQL_TOOLS` 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 mirroring `list_merge_requests_{tool,service}_spec.rb` — root tree, subpath, recursive, pagination, empty repository, missing/inaccessible project.