GitLab MCP Server

Instructions

Implementation Reference

• src/handlers/issues.ts:11-33 (handler)

  Core handler method in IssueHandlers class that builds query parameters from input, calls GitLab API to list issues, and returns formatted JSON response.

  async listIssues(args: ListIssuesParams) {
    const params = new URLSearchParams();
    
    if (args.state) params.append('state', args.state);
    if (args.labels) params.append('labels', args.labels);
    if (args.assignee_id) params.append('assignee_id', String(args.assignee_id));
    if (args.author_id) params.append('author_id', String(args.author_id));
    if (args.search) params.append('search', args.search);
    // Only add scope if explicitly provided by user
    if (args.scope) params.append('scope', args.scope);
    params.append('per_page', String(args.per_page || 20));
  
    const data = await this.client.get(`/projects/${encodeURIComponent(args.project_id)}/issues?${params.toString()}`);
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(data, null, 2),
        },
      ],
    };
  }

• src/tools/issues.ts:7-49 (schema)

  Input schema definition for the list_issues tool, specifying parameters, types, enums, defaults, and requirements.

  inputSchema: {
    type: 'object',
    properties: {
      project_id: {
        type: 'string',
        description: 'Project ID or path',
      },
      state: {
        type: 'string',
        enum: ['opened', 'closed', 'all'],
        description: 'Filter by issue state',
        default: 'opened',
      },
      labels: {
        type: 'string',
        description: 'Comma-separated list of labels',
      },
      assignee_id: {
        type: 'number',
        description: 'Filter by assignee user ID',
      },
      author_id: {
        type: 'number',
        description: 'Filter by author user ID',
      },
      search: {
        type: 'string',
        description: 'Search issues by title and description',
      },
      scope: {
        type: 'string',
        enum: ['created_by_me', 'assigned_to_me', 'all'],
        description: 'Return issues with the given scope (optional)',
      },
      per_page: {
        type: 'number',
        description: 'Number of results per page (max 100)',
        maximum: 100,
        default: 20,
      },
    },
    required: ['project_id'],
  },

• src/tools/issues.ts:4-50 (registration)

  Tool registration object defining name, description, and input schema, exported as part of issueTools array.

  {
    name: 'list_issues',
    description: 'List issues in a project',
    inputSchema: {
      type: 'object',
      properties: {
        project_id: {
          type: 'string',
          description: 'Project ID or path',
        },
        state: {
          type: 'string',
          enum: ['opened', 'closed', 'all'],
          description: 'Filter by issue state',
          default: 'opened',
        },
        labels: {
          type: 'string',
          description: 'Comma-separated list of labels',
        },
        assignee_id: {
          type: 'number',
          description: 'Filter by assignee user ID',
        },
        author_id: {
          type: 'number',
          description: 'Filter by author user ID',
        },
        search: {
          type: 'string',
          description: 'Search issues by title and description',
        },
        scope: {
          type: 'string',
          enum: ['created_by_me', 'assigned_to_me', 'all'],
          description: 'Return issues with the given scope (optional)',
        },
        per_page: {
          type: 'number',
          description: 'Number of results per page (max 100)',
          maximum: 100,
          default: 20,
        },
      },
      required: ['project_id'],
    },
  },

• src/server.ts:163-166 (registration)

  Dispatch registration in server tool call handler switch statement, routing list_issues calls to the issueHandlers.listIssues method.

  case "list_issues":
    return await this.issueHandlers.listIssues(
      args as unknown as ListIssuesParams
    );

• src/types.ts:215-224 (schema)

  TypeScript interface defining the parameters for listIssues handler.

  export interface ListIssuesParams {
    project_id: string;
    state?: 'opened' | 'closed' | 'all';
    labels?: string;
    assignee_id?: number;
    author_id?: number;
    search?: string;
    scope?: 'created_by_me' | 'assigned_to_me' | 'all';
    per_page?: number;
  }