GitLab MCP Server

Instructions

Implementation Reference

• src/api/issues.ts:13-77 (handler)

  The main handler function for list_issues tool, responsible for fetching issues from GitLab API with optional pagination support.

  export async function listIssues(
    projectId: string,
    options: {
      state?: "opened" | "closed" | "all";
      labels?: string;
      milestone?: string;
      assignee_id?: number;
      author_id?: number;
      search?: string;
      created_after?: string;
      created_before?: string;
      updated_after?: string;
      updated_before?: string;
      sort?: string;
      order_by?: "asc" | "desc";
      page?: number;
      per_page?: number;
      with_labels_details?: boolean;
    } = {}
  ): Promise<GitLabIssue[]> {
    if (!projectId?.trim()) {
      throw new Error("Project ID is required");
    }
  
    const endpoint = `/projects/${encodeProjectId(projectId)}/issues`;
  
    // If user explicitly provides page parameter, use single page request
    if (options.page !== undefined) {
      const params = buildSearchParams(options);
      const rawIssues = await gitlabGet<any[]>(endpoint, params);
      return z.array(GitLabIssueSchema).parse(rawIssues);
    }
  
    // Otherwise, fetch all pages automatically
    const allIssues: any[] = [];
    let currentPage = 1;
    const perPage = options.per_page || 100; // Use max page size for efficiency
  
    while (true) {
      const params = buildSearchParams({
        ...options,
        page: currentPage,
        per_page: perPage
      });
  
      const response = await gitlabGetWithHeaders<any[]>(endpoint, params);
      const pageIssues = response.data;
  
      if (pageIssues.length === 0) {
        break; // No more issues
      }
  
      allIssues.push(...pageIssues);
  
      // Check if there's a next page
      const nextPage = response.headers["x-next-page"];
      if (!nextPage) {
        break; // No more pages
      }
  
      currentPage = parseInt(nextPage, 10);
    }
  
    return z.array(GitLabIssueSchema).parse(allIssues);
  }

• src/schemas.ts:391-418 (schema)

  Validation schema for the arguments passed to the list_issues tool.

  export const ListIssuesSchema = z.object({
    project_id: z.string().describe("Project ID or URL-encoded path"),
    state: z.enum(["opened", "closed", "all"]).optional().describe("Filter issues by state"),
    labels: z.string().optional().describe("Comma-separated list of label names"),
    milestone: z.string().optional().describe("Milestone title"),
    assignee_id: z.number().optional().describe("User ID of assignee"),
    author_id: z.number().optional().describe("User ID of author"),
    search: z.string().optional().describe("Search against title and description"),
    created_after: z.string().optional().describe("Return issues created after date (ISO 8601)"),
    created_before: z.string().optional().describe("Return issues created before date (ISO 8601)"),
    updated_after: z.string().optional().describe("Return issues updated after date (ISO 8601)"),
    updated_before: z.string().optional().describe("Return issues updated before date (ISO 8601)"),
    sort: z
      .enum([
        "created_at",
        "updated_at",
        "priority",
        "due_date",
        "relative_position",
        "label_priority",
        "milestone_due",
        "popularity",
        "weight"
      ])
      .optional()
      .describe("Sort issues"),
    order_by: z.enum(["asc", "desc"]).optional().describe("Sort order"),
    page: z