GitHub MCP Server

Instructions

Implementation Reference

• operations/projectsV2.ts:354-423 (handler)

  The main handler function that executes a GraphQL query to fetch and return the list of items (issues/PRs) in a GitHub ProjectV2, including pagination and field values.

  export async function listProjectV2Items(
    projectId: string,
    first: number = 20,
    after?: string
  ) {
    try {
      const query = `
        query($projectId: ID!, $first: Int!, $after: String) {
          node(id: $projectId) {
            ... on ProjectV2 {
              items(first: $first, after: $after) {
                pageInfo {
                  hasNextPage
                  endCursor
                }
                nodes {
                  id
                  content {
                    ... on Issue {
                      id
                      title
                      number
                      state
                    }
                    ... on PullRequest {
                      id
                      title
                      number
                      state
                    }
                  }
                  fieldValues(first: 20) {
                    nodes {
                      ... on ProjectV2ItemFieldTextValue {
                        field { ... on ProjectV2FieldCommon { name id } }
                        text
                      }
                      ... on ProjectV2ItemFieldDateValue {
                        field { ... on ProjectV2FieldCommon { name id } }
                        date
                      }
                      ... on ProjectV2ItemFieldSingleSelectValue {
                        field { ... on ProjectV2FieldCommon { name id } }
                        name
                      }
                    }
                  }
                }
              }
            }
          }
        }
      `;
  
      const variables = { projectId, first, after };
      const response = await graphqlRequest(query, variables);
  
      return response.data.node.items;
    } catch (error) {
      if (error instanceof GitHubError) {
        throw error;
      }
  
      throw new GitHubError(
        `Failed to list project v2 items: ${(error as Error).message}`,
        500,
        { error: (error as Error).message }
      );
    }
  }

• operations/projectsV2.ts:43-47 (schema)

  Zod schema defining the input parameters: projectId (required), first (optional number), after (optional cursor).

  export const ListProjectV2ItemsSchema = z.object({
    projectId: z.string().describe("The node ID of the project"),
    first: z.number().optional().describe("Number of items to fetch (max 100)"),
    after: z.string().optional().describe("Cursor for pagination")
  });

• index.ts:296-298 (registration)

  Tool registration in the list of available tools, specifying name, description, and input schema converted to JSON schema.

  name: "list_project_v2_items",
  description: "List items in a GitHub project V2 using GraphQL API",
  inputSchema: zodToJsonSchema(projectsV2.ListProjectV2ItemsSchema),

• index.ts:792-802 (registration)

  Dispatcher case in the main switch statement that parses arguments using the schema and delegates to the listProjectV2Items handler function.

  case "list_project_v2_items": {
    const args = projectsV2.ListProjectV2ItemsSchema.parse(request.params.arguments);
    const result = await projectsV2.listProjectV2Items(
      args.projectId,
      args.first,
      args.after
    );
    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
    };
  }