GitHub Enterprise MCP Server

Implementation Reference

• server/index.ts:1239-1317 (registration)

  Tool registration including input schema (zod) and handler function that calls ActionsAPI.listWorkflowRuns

  server.tool(
    "list-workflow-runs",
    {
      owner: z.string().min(1).describe("Repository owner"),
      repo: z.string().min(1).describe("Repository name"),
      workflow_id: z.union([z.string(), z.number()]).optional().describe("Workflow ID or file name"),
      branch: z.string().optional().describe("Filter by branch name"),
      status: z.enum(['completed', 'action_required', 'cancelled', 'failure', 'neutral', 'skipped', 'stale', 'success', 'timed_out', 'in_progress', 'queued', 'requested', 'waiting']).optional().describe("Filter by run status"),
      page: z.number().int().positive().optional().describe("Page number"),
      perPage: z.number().int().positive().optional().describe("Items per page")
    },
    async ({ owner, repo, workflow_id, branch, status, page, perPage }) => {
      try {
        // Parameter validation
        if (!owner || typeof owner !== 'string' || owner.trim() === '') {
          return {
            content: [
              {
                type: "text",
                text: "Repository owner is required."
              }
            ]
          };
        }
  
        if (!repo || typeof repo !== 'string' || repo.trim() === '') {
          return {
            content: [
              {
                type: "text",
                text: "Repository name is required."
              }
            ]
          };
        }
  
        const response = await context.actions.listWorkflowRuns(owner, repo, {
          workflow_id,
          branch,
          status,
          page,
          per_page: perPage
        });
        
        if (!response.workflow_runs || response.workflow_runs.length === 0) {
          return {
            content: [
              {
                type: "text",
                text: workflow_id
                  ? `No workflow runs found for workflow '${workflow_id}' in repository '${owner}/${repo}'.`
                  : `No workflow runs found in repository '${owner}/${repo}'.`
              }
            ]
          };
        }
  
        const formattedRuns = response.workflow_runs.map(formatWorkflowRun);
  
        return {
          content: [
            {
              type: "text",
              text: `${workflow_id ? `Workflow '${workflow_id}'` : 'Workflow'} runs in repository '${owner}/${repo}' (${response.total_count}):\n\n${JSON.stringify(formattedRuns, null, 2)}`
            }
          ]
        };
      } catch (error: any) {
        return {
          content: [
            {
              type: "text",
              text: `Error listing workflow runs: ${error.message}`
            }
          ]
        };
      }
    }
  );

• api/actions/actions.ts:55-74 (helper)

  ActionsAPI.listWorkflowRuns: core method that makes the GitHub API request for workflow runs

  async listWorkflowRuns(owner: string, repo: string, options: {
    workflow_id?: number | string;
    actor?: string;
    branch?: string;
    event?: string;
    status?: 'completed' | 'action_required' | 'cancelled' | 'failure' | 'neutral' | 'skipped' | 'stale' | 'success' | 'timed_out' | 'in_progress' | 'queued' | 'requested' | 'waiting';
    created?: string;
    page?: number;
    per_page?: number;
  } = {}): Promise<GitHubWorkflowRunListResponse> {
    const endpoint = options.workflow_id
      ? `repos/${owner}/${repo}/actions/workflows/${options.workflow_id}/runs`
      : `repos/${owner}/${repo}/actions/runs`;
  
    const { workflow_id, ...params } = options;
  
    return this.client.get<GitHubWorkflowRunListResponse>(endpoint, {
      params
    });
  }

• server/index.ts:132-148 (helper)

  formatWorkflowRun: utility function to format workflow run data for user-friendly output

  function formatWorkflowRun(run: any) {
    return {
      id: run.id,
      name: run.name,
      workflow_id: run.workflow_id,
      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,
      head_branch: run.head_branch,
      head_sha: run.head_sha,
      run_attempt: run.run_attempt
    };
  }

• server/index.ts:1242-1249 (schema)

  Zod input schema for the list-workflow-runs tool parameters

    owner: z.string().min(1).describe("Repository owner"),
    repo: z.string().min(1).describe("Repository name"),
    workflow_id: z.union([z.string(), z.number()]).optional().describe("Workflow ID or file name"),
    branch: z.string().optional().describe("Filter by branch name"),
    status: z.enum(['completed', 'action_required', 'cancelled', 'failure', 'neutral', 'skipped', 'stale', 'success', 'timed_out', 'in_progress', 'queued', 'requested', 'waiting']).optional().describe("Filter by run status"),
    page: z.number().int().positive().optional().describe("Page number"),
    perPage: z.number().int().positive().optional().describe("Items per page")
  },