GitLab MCP Server

Instructions

Implementation Reference

• src/tools.ts:655-694 (handler)

  Complete browse_repository tool definition including handler function that processes input, calls client.searchRepositoryFiles(), and formats the response with files and directories with web URLs

  const browseRepositoryTool: Tool = {
    name: 'browse_repository',
    title: 'Browse Repository',
    description: 'Browse repository files and folders - essential for exploring codebase structure',
    requiresAuth: false,
    requiresWrite: false,
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
    },
    inputSchema: withUserAuth(z.object({
      projectPath: z.string().describe('Full path of the project (e.g., "group/project-name")'),
      path: z.string().default('').describe('Directory path to browse (empty for root)'),
      ref: z.string().default('HEAD').describe('Git reference (branch, tag, or commit SHA)'),
    })),
    handler: async (input, client, userConfig) => {
      const credentials = input.userCredentials ? validateUserConfig(input.userCredentials) : userConfig;
      const result = await client.searchRepositoryFiles(input.projectPath, input.path, input.ref, credentials);
      const projectWebUrl = result.project.webUrl;
      const refParam = input.ref || 'HEAD';
      
      const files = result.project.repository.tree.blobs.nodes.map((f: any) => ({
        ...f,
        webUrl: `${projectWebUrl}/-/blob/${refParam}/${f.path}`
      }));
      const directories = result.project.repository.tree.trees.nodes.map((d: any) => ({
        ...d,
        webUrl: `${projectWebUrl}/-/tree/${refParam}/${d.path}`
      }));
      
      return {
        project: input.projectPath,
        path: input.path,
        ref: refParam,
        files,
        directories
      };
    },
  };

• src/tools.ts:666-670 (schema)

  Input schema definition using Zod with user authentication wrapper. Defines projectPath, path (directory), and ref (git reference) parameters with defaults and descriptions

  inputSchema: withUserAuth(z.object({
    projectPath: z.string().describe('Full path of the project (e.g., "group/project-name")'),
    path: z.string().default('').describe('Directory path to browse (empty for root)'),
    ref: z.string().default('HEAD').describe('Git reference (branch, tag, or commit SHA)'),
  })),

• src/gitlab-client.ts:1070-1108 (handler)

  Client-side implementation that executes the GraphQL query to fetch repository tree structure. Queries project.repository.tree with blobs (files) and trees (directories), using path and ref parameters

  async searchRepositoryFiles(
    projectPath: string, 
    path: string, 
    ref?: string, 
    userConfig?: UserConfig
  ): Promise<any> {
    const query = gql`
      query searchRepositoryFiles($projectPath: ID!, $path: String, $ref: String) {
        project(fullPath: $projectPath) {
          webUrl
          repository {
            tree(path: $path, ref: $ref, recursive: true) {
              blobs {
                nodes {
                  name
                  path
                  type
                  mode
                }
              }
              trees {
                nodes {
                  name
                  path
                  type
                }
              }
            }
          }
        }
      }
    `;
    
    return this.query(query, { 
      projectPath, 
      path: path || "", 
      ref: ref || "HEAD" 
    }, userConfig);
  }

• src/tools.ts:1324-1349 (registration)

  Tool registration - browseRepositoryTool is included in searchTools array (line 1334) which is then exported as part of the main tools array that gets registered with the MCP server

  export const searchTools: Tool[] = [
    globalSearchTool,
    searchProjectsTool,
    searchIssuesTool,
    searchMergeRequestsTool,
    getUserIssuesTool,
    getUserMergeRequestsTool,
    searchUsersTool,
    searchGroupsTool,
    searchLabelsTool,
    browseRepositoryTool,
    getFileContentTool,
    listGroupMembersTool,
  ];
  
  export const tools: Tool[] = [
    ...readOnlyTools,
    ...userAuthTools,
    ...writeTools,
    updateIssueTool,
    updateMergeRequestTool,
    resolvePathTool,
    getGroupProjectsTool,
    getTypeFieldsTool,
    ...searchTools,
  ];

• src/index.ts:83-96 (registration)

  MCP server registration handler that lists all available tools including browse_repository. The tools array is imported and mapped to the MCP tool format with schemas converted to JSON Schema

  private setupToolHandlers(server: Server): void {
    server.setRequestHandler(ListToolsRequestSchema, async () => {
      return {
        tools: tools.map(tool => ({
          name: tool.name,
          ...(tool.title && { title: tool.title }),
          description: tool.description,
          inputSchema: toJsonSchema(tool.inputSchema),
          ...(tool.outputSchema && { outputSchema: toJsonSchema(tool.outputSchema) }),
          ...(tool.annotations && { annotations: tool.annotations }),
          ...(tool.icon && { icon: tool.icon }),
        })),
      };
    });