GitHub MCP Server

Instructions

Implementation Reference

• src/tools.ts:141-181 (handler)

  The main handler function for the 'search-repos' tool. It takes search arguments, queries the GitHub API using Octokit, maps the results to a simplified format, and returns them as JSON text content or an error message.

  const searchRepos = async (args: SearchReposArgs) => {
    const { query, sort = "stars", limit = 5 } = args;
    
    try {
      const response = await octokit.rest.search.repos({
        q: query,
        sort,
        per_page: limit,
      });
      
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              response.data.items.map(repo => ({
                name: repo.full_name,
                description: repo.description,
                stars: repo.stargazers_count,
                url: repo.html_url,
                language: repo.language,
                forks: repo.forks_count,
              })),
              null,
              2
            ),
          },
        ],
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
      return {
        content: [
          {
            type: "text",
            text: `Error searching repositories: ${errorMessage}`,
          },
        ],
      };
    }
  };

• src/tools.ts:10-32 (schema)

  Tool specification including name, description, and input schema defining the expected parameters (query required, sort enum, limit number).

  "search-repos": {
    name: "search-repos",
    description: "Search for GitHub repositories",
    inputSchema: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "Search query",
        },
        sort: {
          type: "string",
          enum: ["stars", "forks", "help-wanted-issues", "updated"],
          description: "Sort order",
        },
        limit: {
          type: "number",
          description: "Maximum number of results to return",
        }
      },
      required: ["query"],
    },
  },

• src/tools.ts:322-327 (registration)

  Maps the 'search-repos' name to its handler function (searchRepos) in the toolHandlers export, which is imported and used by the MCP server in handlers.ts to dispatch tool calls.

  export const toolHandlers = {
    "search-repos": searchRepos,
    "get-repo-info": getRepoInfo,
    "list-issues": listIssues,
    "create-issue": createIssue,
  };

• src/handlers.ts:22-31 (registration)

  Registers the generic tool call handler with MCP server using CallToolRequestSchema, which looks up and invokes the specific handler from toolHandlers based on the tool name 'search-repos'.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
      type ToolHandlerKey = keyof typeof toolHandlers;
      const { name, arguments: params } = request.params ?? {};
      const handler = toolHandlers[name as ToolHandlerKey];
  
      if (!handler) throw new Error("tool not found");
  
      type HandlerParams = Parameters<typeof handler>;
      return handler(params as any);
  })

• src/tools.ts:114-118 (schema)

  TypeScript type definition for the input arguments of the search-repos handler, matching the inputSchema.

  type SearchReposArgs = {
    query: string;
    sort?: "stars" | "forks" | "help-wanted-issues" | "updated";
    limit?: number;
  };