GitHub MCP Server

Instructions

Implementation Reference

• src/tools.ts:230-276 (handler)

  Implements the core logic for listing issues in a GitHub repository using the Octokit client. Handles input parameters (owner, repo, state, limit), fetches issues via GitHub API, formats response as JSON, and handles errors.

  const listIssues = async (args: ListIssuesArgs) => {
    const { owner, repo, state = "open", limit = 10 } = args;
    
    try {
      const response = await octokit.rest.issues.listForRepo({
        owner,
        repo,
        state,
        per_page: limit,
      });
      
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              response.data.map(issue => ({
                number: issue.number,
                title: issue.title,
                state: issue.state,
                created_at: issue.created_at,
                updated_at: issue.updated_at,
                user: issue.user?.login,
                labels: issue.labels.map(label => 
                  typeof label === 'string' ? label : label.name
                ),
                url: issue.html_url,
                comments: issue.comments,
              })),
              null,
              2
            ),
          },
        ],
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
      return {
        content: [
          {
            type: "text",
            text: `Error listing issues: ${errorMessage}`,
          },
        ],
      };
    }
  };

• src/tools.ts:51-77 (schema)

  Tool metadata and input schema definition for 'list-issues', specifying parameters, types, descriptions, enums, and required fields.

  "list-issues": {
    name: "list-issues",
    description: "List issues in a GitHub repository",
    inputSchema: {
      type: "object",
      properties: {
        owner: {
          type: "string",
          description: "Repository owner (username or organization)",
        },
        repo: {
          type: "string",
          description: "Repository name",
        },
        state: {
          type: "string",
          enum: ["open", "closed", "all"],
          description: "Issue state",
        },
        limit: {
          type: "number",
          description: "Maximum number of issues to return",
        }
      },
      required: ["owner", "repo"],
    },
  },

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

  Maps the 'list-issues' tool name to its handler function (listIssues) in the toolHandlers export object, enabling dispatch by the MCP server.

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

• src/tools.ts:125-130 (helper)

  TypeScript interface defining the expected argument structure for the listIssues handler, matching the input schema.

  type ListIssuesArgs = {
    owner: string;
    repo: string;
    state?: "open" | "closed" | "all";
    limit?: number;
  };