gitlab-mcp-server

Instructions

Implementation Reference

• src/index.ts:346-350 (handler)

  MCP tool handler in the CallToolRequest switch statement. Parses input arguments using the schema and delegates to GitLabApi.searchProjects method, then returns JSON stringified results.

  case "search_repositories": {
    const args = SearchRepositoriesSchema.parse(request.params.arguments);
    const results = await gitlabApi.searchProjects(args.search, args.page, args.per_page);
    return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
  }

• src/schemas.ts:401-405 (schema)

  Zod input schema defining parameters for the search_repositories tool: required search query string, optional page and per_page numbers.

  export const SearchRepositoriesSchema = z.object({
    search: z.string(),
    page: z.number().optional(),
    per_page: z.number().optional()
  });

• src/index.ts:114-118 (registration)

  Tool registration entry in the ALL_TOOLS array used for ListToolsRequest response, specifying name, description, input schema, and read-only flag.

  {
    name: "search_repositories",
    description: "Search for GitLab projects",
    inputSchema: createJsonSchema(SearchRepositoriesSchema),
    readOnly: true

• src/gitlab-api.ts:334-362 (helper)

  GitLabApi class method implementing the core search logic: constructs API URL for /projects with search params, fetches data, parses response with output schema, and returns structured results.

  async searchProjects(
    query: string,
    page: number = 1,
    perPage: number = 20
  ): Promise<GitLabSearchResponse> {
    const url = new URL(`${this.apiUrl}/projects`);
    url.searchParams.append("search", query);
    url.searchParams.append("page", page.toString());
    url.searchParams.append("per_page", perPage.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();
    return GitLabSearchResponseSchema.parse({
      count: parseInt(response.headers.get("X-Total") || "0"),
      items: projects
    });
  }