gitlab-mcp-server

Instructions

Implementation Reference

• src/gitlab-api.ts:482-533 (handler)

  Core handler function in GitLabApi class that fetches and returns commits for a project using the GitLab API.

  async listCommits(
    projectId: string,
    options: {
      sha?: string;
      since?: string;
      until?: string;
      path?: string;
      all?: boolean;
      with_stats?: boolean;
      first_parent?: boolean;
      page?: number;
      per_page?: number;
    } = {}
  ): Promise<GitLabCommitsResponse> {
    const url = new URL(
      `${this.apiUrl}/projects/${encodeURIComponent(
        projectId
      )}/repository/commits`
    );
  
    // Add query parameters for filtering and pagination
    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}`
      );
    }
  
    // Parse the response JSON
    const commits = await response.json();
  
    // Get the total count from the headers
    const totalCount = parseInt(response.headers.get("X-Total") || "0");
  
    // Validate and return the response
    return GitLabCommitsResponseSchema.parse({
      count: totalCount,
      items: commits,
    });
  }

• src/index.ts:445-479 (handler)

  MCP server tool handler case for 'list_commits' that validates input, calls GitLabApi.listCommits, and formats the response.

  case "list_commits": {
    // Parse and validate the arguments
    const args = ListCommitsSchema.parse(request.params.arguments);
  
    // Additional validation for pagination parameters
    if (args.per_page && (args.per_page < 1 || args.per_page > 100)) {
      throw new Error("per_page must be between 1 and 100");
    }
  
    if (args.page && args.page < 1) {
      throw new Error("page must be greater than 0");
    }
  
    // Validate date formats if provided
    if (args.since && !isValidISODate(args.since)) {
      throw new Error(
        "since must be a valid ISO 8601 date (YYYY-MM-DDTHH:MM:SSZ)"
      );
    }
  
    if (args.until && !isValidISODate(args.until)) {
      throw new Error(
        "until must be a valid ISO 8601 date (YYYY-MM-DDTHH:MM:SSZ)"
      );
    }
  
    // Extract project_id and options
    const { project_id, ...options } = args;
  
    // Call the API function
    const commits = await gitlabApi.listCommits(project_id, options);
  
    // Format and return the response
    return formatCommitsResponse(commits);
  }

• src/schemas.ts:465-476 (schema)

  Zod schema defining the input parameters for the list_commits tool.

  export const ListCommitsSchema = z.object({
    project_id: z.string(),
    sha: z.string().optional(),
    since: z.string().optional(),
    until: z.string().optional(),
    path: z.string().optional(),
    all: z.boolean().optional(),
    with_stats: z.boolean().optional(),
    first_parent: z.boolean().optional(),
    page: z.number().optional(),
    per_page: z.number().optional()
  });

• src/index.ts:175-178 (registration)

  Tool registration in the ALL_TOOLS array, including name, description, input schema, and read-only flag.

  name: "list_commits",
  description: "Get commit history for a GitLab project",
  inputSchema: createJsonSchema(ListCommitsSchema),
  readOnly: true