GitHub Actions MCP Server

Instructions

Implementation Reference

• src/tools/list-workflows.ts:5-35 (handler)

  The handler function that implements the list_workflows tool logic, fetching workflows from GitHub using Octokit.

  const handleListWorkflows: ToolHandler = async (args, octokit: Octokit) => {
    const { owner, repo, page, perPage } = args;
    
    try {
      const response = await octokit.rest.actions.listRepoWorkflows({
        owner,
        repo,
        page,
        per_page: perPage
      });
  
      return {
        total_count: response.data.total_count,
        workflows: response.data.workflows.map(workflow => ({
          id: workflow.id,
          name: workflow.name,
          path: workflow.path,
          state: workflow.state,
          created_at: workflow.created_at,
          updated_at: workflow.updated_at,
          url: workflow.url,
          html_url: workflow.html_url,
          badge_url: workflow.badge_url
        }))
      };
    } catch (error: any) {
      throw new WorkflowError(`Failed to list workflows: ${error.message}`, error.response?.data);
    }
  };
  
  export default handleListWorkflows;

• src/tools/tool-definitions.ts:22-35 (schema)

  The schema definition for the list_workflows tool, including input schema and description.

  {
    name: "list_workflows",
    description: "List workflows in a GitHub repository",
    inputSchema: {
      type: "object",
      properties: {
        owner: { type: "string", description: "Repository owner" },
        repo: { type: "string", description: "Repository name" },
        page: { type: "number", description: "Page number for pagination" },
        perPage: { type: "number", description: "Results per page (max 100)" }
      },
      required: ["owner", "repo"]
    }
  },

• src/tools/index.ts:14-25 (registration)

  Registration of the list_workflows handler in the toolHandlers map.

  export const toolHandlers: Record<string, ToolHandler> = {
    create_workflow: handleCreateWorkflow,
    list_workflows: handleListWorkflows,
    get_workflow: handleGetWorkflow,
    get_workflow_usage: handleGetWorkflowUsage,
    list_workflow_runs: handleListWorkflowRuns,
    get_workflow_run: handleGetWorkflowRun,
    get_workflow_run_jobs: handleGetWorkflowRunJobs,
    trigger_workflow: handleTriggerWorkflow,
    cancel_workflow_run: handleCancelWorkflowRun,
    rerun_workflow: handleRerunWorkflow,
  };

• src/tools/index.ts:4-4 (registration)

  Import of the list_workflows handler.

  import handleListWorkflows from './list-workflows.js';