gitlab-mcp-server

Instructions

Implementation Reference

• src/gitlab-api.ts:372-415 (handler)

  Core handler function in GitLabApi class that lists projects in a group by calling GitLab API /groups/{groupId}/projects, applies options as query params, parses response using GitLabGroupProjectsResponseSchema.

  async listGroupProjects(
    groupId: string,
    options: {
      archived?: boolean;
      visibility?: 'public' | 'internal' | 'private';
      order_by?: 'id' | 'name' | 'path' | 'created_at' | 'updated_at' | 'last_activity_at';
      sort?: 'asc' | 'desc';
      search?: string;
      simple?: boolean;
      include_subgroups?: boolean;
      page?: number;
      per_page?: number;
    } = {}
  ): Promise<GitLabGroupProjectsResponse> {
    const url = new URL(`${this.apiUrl}/groups/${encodeURIComponent(groupId)}/projects`);
  
    // Add query parameters
    Object.entries(options).forEach(([key, value]) => {
      if (value !== undefined) {
        url.searchParams.append(key, value.toString());
      }
    });
  
    const response = await fetch(url.toString(), {
      headers: {
        "Authorization": `Bearer ${this.token}`
      }
    });
  
    if (!response.ok) {
      throw new McpError(
        ErrorCode.InternalError,
        `GitLab API error: ${response.statusText}`
      );
    }
  
    const projects = await response.json();
    const totalCount = parseInt(response.headers.get("X-Total") || "0");
  
    return GitLabGroupProjectsResponseSchema.parse({
      count: totalCount,
      items: projects
    });
  }

• src/schemas.ts:441-452 (schema)

  Zod input schema defining parameters for list_group_projects tool: group_id (required), and optional filters like archived, visibility, order_by, etc.

  export const ListGroupProjectsSchema = z.object({
    group_id: z.string(),
    archived: z.boolean().optional(),
    visibility: z.enum(['public', 'internal', 'private']).optional(),
    order_by: z.enum(['id', 'name', 'path', 'created_at', 'updated_at', 'last_activity_at']).optional(),
    sort: z.enum(['asc', 'desc']).optional(),
    search: z.string().optional(),
    simple: z.boolean().optional(),
    include_subgroups: z.boolean().optional(),
    page: z.number().optional(),
    per_page: z.number().optional()
  });

• src/index.ts:162-167 (registration)

  Tool registration in ALL_TOOLS array, defining name, description, inputSchema from ListGroupProjectsSchema, marked as readOnly.

  {
    name: "list_group_projects",
    description: "List all projects (repositories) within a specific GitLab group",
    inputSchema: createJsonSchema(ListGroupProjectsSchema),
    readOnly: true
  },

• src/index.ts:415-420 (handler)

  MCP server tool dispatch handler: parses input with ListGroupProjectsSchema, destructures args, calls gitlabApi.listGroupProjects, returns JSON stringified results.

  case "list_group_projects": {
    const args = ListGroupProjectsSchema.parse(request.params.arguments);
    const { group_id, ...options } = args;
    const results = await gitlabApi.listGroupProjects(group_id, options);
    return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
  }