gitlab_list_repository_tree
Browse and list files and directories in a GitLab repository to explore project structure, with options for recursive listing and specific paths.
Instructions
Browse repository directory structure Returns: Array of files and directories Use when: Exploring repo structure, listing files Optional: Recursive listing, specific path
Example response: [{ "name": "src", "type": "tree", "path": "src", "mode": "040000" }, { "name": "README.md", "type": "blob", "path": "README.md", "mode": "100644" }]
Related tools:
gitlab_get_file_content: Read file contents
gitlab_search_in_project: Search in files
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Project identifier (auto-detected if not provided) Type: integer OR string Format: numeric ID or 'namespace/project' Optional: Yes - auto-detects from current git repository Examples: - 12345 (numeric ID) - 'gitlab-org/gitlab' (namespace/project path) - 'my-group/my-subgroup/my-project' (nested groups) Note: If in a git repo with GitLab remote, this can be omitted | |
| path | No | Directory path in repository Type: string Format: Relative path using forward slashes Default: '' (empty string for root) Examples: - '' (repository root) - 'src' (src directory) - 'src/components' (nested directory) - 'tests/unit/models' (deeply nested) Note: Don't include trailing slash | |
| ref | No | Git reference Type: string Format: branch name, tag name, or commit SHA Optional: Yes - defaults to project's default branch Examples: - 'main' (branch) - 'feature/new-login' (feature branch) - 'v2.0.0' (tag) - 'abc1234' (short commit SHA) - 'e83c5163316f89bfbde7d9ab23ca2e25604af290' (full SHA) Default: Project's default branch (usually 'main' or 'master') | |
| recursive | No | Include subdirectories Type: boolean Default: false Options: - true: Include all subdirectories recursively - false: Only immediate children Use case: true for full directory tree, false for folder contents |
Implementation Reference
- src/mcp_gitlab/tool_handlers.py:175-182 (handler)The main handler function that implements the core logic for the 'gitlab_list_repository_tree' tool. Extracts parameters, resolves project ID (with git detection fallback), and delegates to GitLabClient.get_repository_tree().
def handle_get_repository_tree(client: GitLabClient, arguments: Optional[Dict[str, Any]]) -> Dict[str, Any]: """Handle getting repository tree""" project_id = require_project_id(client, arguments) path = get_argument(arguments, "path", "") ref = get_argument(arguments, "ref") recursive = get_argument(arguments, "recursive", False) return client.get_repository_tree(project_id, path, ref, recursive) - src/mcp_gitlab/server.py:350-361 (schema)MCP Tool schema definition including input validation schema, properties (project_id, path, ref, recursive), and description reference.
name=TOOL_LIST_REPOSITORY_TREE, description=desc.DESC_LIST_TREE, inputSchema={ "type": "object", "properties": { "project_id": {"type": "string", "description": desc.DESC_PROJECT_ID}, "path": {"type": "string", "description": desc.DESC_TREE_PATH, "default": ""}, "ref": {"type": "string", "description": desc.DESC_REF}, "recursive": {"type": "boolean", "description": desc.DESC_RECURSIVE, "default": False} } } ), - src/mcp_gitlab/tool_handlers.py:1011-1011 (registration)Mapping of tool name constant to handler function in the TOOL_HANDLERS dictionary, used by server.call_tool() to dispatch executions.
TOOL_LIST_REPOSITORY_TREE: handle_get_repository_tree, - src/mcp_gitlab/server.py:1251-1253 (registration)Tool dispatch logic in MCP server.call_tool() that looks up handler by tool name from TOOL_HANDLERS and executes it.
handler = TOOL_HANDLERS.get(name) if not handler: raise ValueError(f"Unknown tool: {name}") - src/mcp_gitlab/constants.py:192-192 (helper)Constant definition for the tool name string 'gitlab_list_repository_tree', imported and used across handler registration, schema, and dispatch.
TOOL_LIST_REPOSITORY_TREE = "gitlab_list_repository_tree"