GitHub Enterprise MCP Server

Instructions

Implementation Reference

• src/tools/repository.ts:312-362 (handler)

  The primary handler function that parses input using ListWorkflowRunsSchema, calls GitHub Actions API to list workflow runs (either for a specific workflow or all in repo), and formats the response.

  export async function listWorkflowRuns(args: unknown): Promise<any> {
    const { owner, repo, workflow_id, branch, status, page, perPage } = ListWorkflowRunsSchema.parse(args);
    const github = getGitHubApi();
  
    return tryCatchAsync(async () => {
      let data;
  
      if (workflow_id) {
        // List runs for a specific workflow
        const response = await github.getOctokit().actions.listWorkflowRuns({
          owner,
          repo,
          workflow_id,
          branch,
          status: status as any,
          page,
          per_page: perPage,
        });
        data = response.data;
      } else {
        // List all workflow runs
        const response = await github.getOctokit().actions.listWorkflowRunsForRepo({
          owner,
          repo,
          branch,
          status: status as any,
          page,
          per_page: perPage,
        });
        data = response.data;
      }
  
      return {
        total_count: data.total_count,
        workflow_runs: data.workflow_runs.map((run) => ({
          id: run.id,
          name: run.name,
          workflow_id: run.workflow_id,
          head_branch: run.head_branch,
          head_sha: run.head_sha,
          run_number: run.run_number,
          event: run.event,
          status: run.status,
          conclusion: run.conclusion,
          created_at: run.created_at,
          updated_at: run.updated_at,
          url: run.html_url,
        })),
      };
    }, 'Failed to list workflow runs');
  }

• src/utils/validation.ts:233-255 (schema)

  Zod schema for validating the input arguments to the listWorkflowRuns handler, extending OwnerRepoSchema with optional workflow_id, branch, status enum, page, and perPage.

  export const ListWorkflowRunsSchema = OwnerRepoSchema.extend({
    workflow_id: z.union([z.string(), z.number()]).optional(),
    branch: z.string().optional(),
    status: z
      .enum([
        'completed',
        'action_required',
        'cancelled',
        'failure',
        'neutral',
        'skipped',
        'stale',
        'success',
        'timed_out',
        'in_progress',
        'queued',
        'requested',
        'waiting',
      ])
      .optional(),
    page: z.number().int().optional(),
    perPage: z.number().int().optional(),
  });

• src/server.ts:302-355 (registration)

  MCP tool registration entry in server.tools.add array, defining the tool name, description, and inputSchema matching the handler validation.

  {
    name: 'list-workflow-runs',
    description: 'List workflow runs in a GitHub repository',
    inputSchema: {
      type: 'object',
      properties: {
        owner: {
          type: 'string',
          description: 'Repository owner',
        },
        repo: {
          type: 'string',
          description: 'Repository name',
        },
        workflow_id: {
          type: ['string', 'number'],
          description: 'Workflow ID or file name',
        },
        branch: {
          type: 'string',
          description: 'Filter by branch name',
        },
        status: {
          type: 'string',
          enum: [
            'completed',
            'action_required',
            'cancelled',
            'failure',
            'neutral',
            'skipped',
            'stale',
            'success',
            'timed_out',
            'in_progress',
            'queued',
            'requested',
            'waiting',
          ],
          description: 'Filter by run status',
        },
        page: {
          type: 'integer',
          description: 'Page number',
        },
        perPage: {
          type: 'integer',
          description: 'Items per page',
        },
      },
      required: ['owner', 'repo'],
      additionalProperties: false,
    },
  },

• src/server.ts:1184-1186 (registration)

  Switch case in the CallToolRequestHandler that dispatches tool calls named 'list-workflow-runs' to the listWorkflowRuns handler function.

  case 'list-workflow-runs':
    result = await listWorkflowRuns(parsedArgs);
    break;