gitlab-mcp-server

Instructions

Implementation Reference

• src/index.ts:422-443 (handler)

  MCP tool handler for 'get_project_events': parses input, validates pagination, calls GitLabApi.getProjectEvents, and formats response.

  case "get_project_events": {
    // Parse and validate the arguments
    const args = GetProjectEventsSchema.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");
    }
  
    // Extract project_id and options
    const { project_id, ...options } = args;
  
    // Call the API function
    const events = await gitlabApi.getProjectEvents(project_id, options);
  
    // Format and return the response
    return formatEventsResponse(events);
  }

• src/gitlab-api.ts:425-472 (helper)

  Core GitLab API method that fetches project events from the GitLab REST API, handles query params, and parses response.

  async getProjectEvents(
    projectId: string,
    options: {
      action?: string;
      target_type?: string;
      before?: string;
      after?: string;
      sort?: "asc" | "desc";
      page?: number;
      per_page?: number;
    } = {}
  ): Promise<GitLabEventsResponse> {
    const url = new URL(
      `${this.apiUrl}/projects/${encodeURIComponent(projectId)}/events`
    );
  
    // 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 events = 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 GitLabEventsResponseSchema.parse({
      count: totalCount,
      items: events,
    });
  }

• src/schemas.ts:454-463 (schema)

  Zod schema defining input parameters for the get_project_events tool: project_id (required), optional filters and pagination.

  export const GetProjectEventsSchema = z.object({
    project_id: z.string(),
    action: z.string().optional(),
    target_type: z.string().optional(),
    before: z.string().optional(),
    after: z.string().optional(),
    sort: z.enum(['asc', 'desc']).optional(),
    page: z.number().optional(),
    per_page: z.number().optional()
  });

• src/index.ts:168-172 (registration)

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

  {
    name: "get_project_events",
    description: "Get recent events/activities for a GitLab project",
    inputSchema: createJsonSchema(GetProjectEventsSchema),
    readOnly: true