gitlab-ci-mcp

Overview Schema Source Related Servers Discussions Admin

gitlab_list_repository_tree

Read-onlyIdempotent

List files and directories at any path in a GitLab repository, optionally recursing into subdirectories, to explore project structure and locate files by name or extension.

Instructions

List files and directories at a given path in the repository.

Examples: - "Show top-level files" → default call - "All .py files recursively" → recursive=True then filter on .py in path - Don't use for full-text content — use gitlab_get_file for that.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "project_path": "<project_path>"
    },
    "name": "gitlab_list_repository_tree"
  }
}

Input Schema

Name	Required	Description	Default
`ref`	No	Branch, tag or SHA.	master
`page`	No	1-based page number.
`path`	No	Directory path (empty for root).
`per_page`	No	Items per page (1–100).
`recursive`	No	Recurse into subdirectories.
`project_path`	Yes	GitLab project path (e.g. 'my-org/my-repo'). Required by default. For legacy deployments only, set GITLAB_ALLOW_DEFAULT_PROJECT=true to use GITLAB_PROJECT_PATH when omitted.

Output Schema

Name	Required	Description	Default
`ref`	Yes
`path`	Yes
`count`	Yes
`items`	Yes
`project`	Yes
`pagination`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.5.5Nov 5, 2026

removedInput schema / properties / project_path / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / project_path / default
```
Removed value: -null
```

changedInput schema / properties / project_path / description

Previous value: -"GitLab project path (e.g. 'my-org/my-repo'). When omitted, the default from GITLAB_PROJECT_PATH env var is used."New value: +"GitLab project path (e.g. 'my-org/my-repo'). Required by default. For legacy deployments only, set GITLAB_ALLOW_DEFAULT_PROJECT=true to use GITLAB_PROJECT_PATH when omitted."

addedInput schema / properties / project_path / minLength
```
Added value: +1
```
addedInput schema / properties / project_path / type
```
Added value: +"string"
```
addedInput schema / required
```
Added value: +[
+  "project_path"
+]
```

First observedv0.5.1Apr 17, 2026

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and mutability profile is fully supplied by structured data. The description's only extra behavioral signal is the negative constraint about not reading file contents, which is a usage boundary rather than operational detail. It says nothing about pagination behavior or result ordering, so it earns a moderate score rather than a high one.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single lead sentence followed by three short bullets, each earning its place by mapping a natural-language request to a call pattern. Nothing is repeated from the schema and the primary purpose is front-loaded before the examples.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value detail is not required, and the six parameters are fully described in-schema; the description fills the remaining gap of how to route between listing and content retrieval. Minor omissions such as pagination or large-recursive-result costs are covered by the schema's page/per_page fields, keeping this just short of complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all six parameters including ref, path, recursive, page and per_page are already documented, establishing a baseline of 3. The example showing 'recursive=True then filter on .py in path' adds practical meaning about how recursive output must be filtered client-side, but no syntax or value details beyond the schema are supplied.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List files and directories at a given path in the repository') and immediately distinguishes itself from the closest sibling by ruling out full-text lookup. An agent can identify scope and boundaries without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides three concrete routing rules: default call for top-level listing, recursive=True plus path filtering for nested extension searches, and an explicit exclusion pointing to gitlab_get_file for content retrieval. Both the when-to-use and when-not-to-use cases are covered with the named alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.