GitHub MCP Server

Instructions

Implementation Reference

• operations/projectsV2.ts:65-110 (handler)

  Executes GraphQL query to list Projects V2 for a GitHub organization, handling pagination and errors.

  export async function listOrganizationProjectsV2(
    org: string,
    first: number = 20,
    after?: string,
    orderBy?: { field: string, direction: string }
  ) {
    try {
      const query = `
        query($org: String!, $first: Int!, $after: String, $orderBy: ProjectV2Order) {
          organization(login: $org) {
            projectsV2(first: $first, after: $after, orderBy: $orderBy) {
              pageInfo {
                hasNextPage
                endCursor
              }
              nodes {
                id
                title
                shortDescription
                url
                closed
                createdAt
                updatedAt
                number
              }
            }
          }
        }
      `;
  
      const variables = { org, first, after, orderBy };
      const response = await graphqlRequest(query, variables);
  
      return response.data.organization.projectsV2;
    } catch (error) {
      if (error instanceof GitHubError) {
        throw error;
      }
  
      throw new GitHubError(
        `Failed to list organization projects v2: ${(error as Error).message}`,
        500,
        { error: (error as Error).message }
      );
    }
  }

• operations/projectsV2.ts:6-14 (schema)

  Zod schema defining input parameters for the list_organization_projects_v2 tool.

  export const ListOrganizationProjectsV2Schema = z.object({
    org: z.string().describe("Organization name"),
    first: z.number().optional().describe("Number of projects to fetch (max 100)"),
    after: z.string().optional().describe("Cursor for pagination"),
    orderBy: z.object({
      field: z.enum(["CREATED_AT", "UPDATED_AT"]),
      direction: z.enum(["ASC", "DESC"])
    }).optional().describe("How to order the projects")
  });

• index.ts:270-274 (registration)

  Registers the tool in the MCP server's listTools response with name, description, and input schema.

  {
    name: "list_organization_projects_v2",
    description: "List projects V2 in a GitHub organization using GraphQL API",
    inputSchema: zodToJsonSchema(projectsV2.ListOrganizationProjectsV2Schema),
  },

• index.ts:735-746 (registration)

  Dispatches the tool call in the MCP server's callTool handler, parsing args and invoking the handler function.

  case "list_organization_projects_v2": {
    const args = projectsV2.ListOrganizationProjectsV2Schema.parse(request.params.arguments);
    const result = await projectsV2.listOrganizationProjectsV2(
      args.org,
      args.first,
      args.after,
      args.orderBy
    );
    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
    };
  }