Workflow / GitHub Actions tool suite — list, inspect, trigger, retry, cancel

[nemolize]

Umbrella issue for adding a GitHub Actions workflow surface to the MCP server. Currently the server has no Actions tools at all; Claude.ai cannot answer "is CI green?" / "why did the last run fail?" / "rerun the failed job" / "what did the build produce?" without web fetch.

Proposed tools

Read

Tool	Octokit	Purpose
list_workflows	rest.actions.listRepoWorkflows	Workflows defined in the repo (name, state, path, id).
list_workflow_runs	rest.actions.listWorkflowRunsForRepo (or per-workflow)	Recent runs filtered by workflow / branch / event / status.
get_workflow_run	rest.actions.getWorkflowRun	Single run detail (status, conclusion, head_sha, html_url, run_attempt, triggering actor).
list_workflow_run_jobs	rest.actions.listJobsForWorkflowRun	Jobs within a run with per-step status. The "what failed?" primary lookup.
get_workflow_run_logs	rest.actions.downloadWorkflowRunLogs	Logs zip — surface as a tail-truncated text dump or per-job summary. Decide handling of binary / size cap during implementation.
list_workflow_run_artifacts	rest.actions.listWorkflowRunArtifacts	Artifacts produced by a run (name, size, expires_at, archive_download_url).
get_artifact	rest.actions.downloadArtifact	Download a single artifact zip. Same binary-handling concern as logs — likely surface as URL + size + a "preview" of small text artifacts, no auto-unzip of arbitrary binaries.

Write (gated; each call mutates repo state)

Tool	Octokit	Purpose
rerun_workflow_run	rest.actions.reRunWorkflow	Retry an entire failed run.
rerun_failed_jobs	rest.actions.reRunWorkflowFailedJobs	Retry only the failed jobs of a run.
cancel_workflow_run	rest.actions.cancelWorkflowRun	Stop an in-progress run.
trigger_workflow_dispatch	rest.actions.createWorkflowDispatch	Manually trigger a workflow_dispatch-enabled workflow with inputs.

Schema sketches (per tool, refine during implementation)

// list_workflow_runs
{
  ...RepoTarget,
  workflow_id: z.union([z.number().int().positive(), z.string()]).optional()
    .describe("Workflow filename (e.g. 'ci.yml') or numeric ID. Omit to list across all workflows."),
  branch: z.string().optional(),
  event: z.enum(["push","pull_request","workflow_dispatch","schedule","release","etc"]).optional(),
  status: z.enum(["queued","in_progress","completed","success","failure","cancelled","skipped"]).optional(),
  per_page: z.number().int().min(1).max(100).optional().default(20),
}

// trigger_workflow_dispatch
{
  ...RepoTarget,
  workflow_id: z.union([z.number().int().positive(), z.string()]),
  ref: z.string().min(1).describe("Branch or tag the workflow runs against."),
  inputs: z.record(z.string()).optional().describe("workflow_dispatch inputs."),
}

Order of implementation (suggested)

1. list_workflow_runs + get_workflow_run + list_workflow_run_jobs — covers "is CI green?" and "what failed?" without any write surface.
2. list_workflows + get_workflow_run_logs — completes the run inspection story.
3. list_workflow_run_artifacts + get_artifact — adds build-output visibility.
4. rerun_workflow_run + rerun_failed_jobs — the most useful write tools.
5. cancel_workflow_run + trigger_workflow_dispatch — round out the write surface.

Each phase can land as its own PR.

Concerns to resolve during design

• Log size: downloadWorkflowRunLogs returns a zip. Decide whether to unzip and dump the top-N lines per job, or just return URLs and rely on list_workflow_run_jobs step output to pinpoint failure.
• Artifact size / binary handling: downloadArtifact returns a zip too, often containing arbitrary binary content (built apps, screenshots, etc.). Default to URL + metadata; only auto-unzip when the artifact is small and clearly text. Mirror the logs decision.
• workflow_id polymorphism: string filename vs numeric id — pick one form and document it consistently across read + write.
• Permissions: write tools mutate CI, which can leak environment secrets or cancel in-progress work. Audit log (see Phase 1b: input size caps + structured audit log + known limitations #2) becomes more important once write tools land.

Acceptance

Independent acceptance per phase. Each phase:

• New tools registered, README table updated.
• pnpm type-check passes.
• Smoke-tested against this repo (nemolize/remote-mcp-github) — both successful and failed runs exist for CI/deploy.

[nemolize]

Real-world bump for Phase 1 priority 🎯

Hit this exact gap today: opened a PR (a tsconfig.json change enabling noPropertyAccessFromIndexSignature + verbatimModuleSyntax) entirely from a Claude.ai chat via this server — branch, commit, and PR all worked smoothly. But the moment I wanted to confirm CI status, the flow broke: there's no way to answer "did the type-check pass?" without leaving the chat for the PR's Checks tab.

This is especially relevant for the verbatimModuleSyntax change, which forces import type rewrites and is very likely to surface failing type-checks across existing code — exactly the case where seeing the failed job inline matters most.

So a concrete vote to land Phase 1 first (list_workflow_runs + get_workflow_run + list_workflow_run_jobs). The read-only "is CI green? / what failed?" loop is the highest-leverage slice — it closes the "PR → CI → fix" cycle inside the chat without touching the write surface. get_workflow_run_logs (Phase 2) would be a nice follow-up but the per-step status from list_workflow_run_jobs alone already pinpoints most failures.