Tools

Pipeline Doctor exposes 9 tools that MCP clients can invoke. All tools accept an optional repo parameter in owner/repo format. When omitted, the repository is auto-detected from git remote or the --repo flag.

list_workflows

List all GitHub Actions workflows in a repository with their current status and last run info.

Parameter	Type	Required	Description
repo	string	No	Repository in owner/repo format

Example: "List all workflows in my-org/my-repo"

get_failed_runs

List recent failed workflow runs with branch, commit, duration, and actor info.

Parameter	Type	Required	Description
repo	string	No	Repository in owner/repo format
workflow_id	number	No	Filter by workflow ID
branch	string	No	Filter by branch name
limit	number	No	Max number of runs to return (default 10)

Example: "Show me the last 5 failed runs on the main branch"

get_run_details

Show jobs and steps for a workflow run with status, timing, and runner info.

Parameter	Type	Required	Description
repo	string	No	Repository in owner/repo format
run_id	number	Yes	GitHub Actions run ID

Example: "Show me the details of run 12345"

get_run_logs

Fetch and parse logs for a workflow run with error extraction and smart truncation. ANSI codes are stripped and error blocks are preserved during truncation.

Parameter	Type	Required	Description
repo	string	No	Repository in owner/repo format
run_id	number	Yes	GitHub Actions run ID
job_name	string	No	Filter to a specific job name
step_name	string	No	Filter to a specific step name

Example: "Get the logs for run 12345, just the build job"

analyze_failure

Pattern-match logs from a failed run against the failure classification database and return root cause analysis.

Parameter	Type	Required	Description
repo	string	No	Repository in owner/repo format
run_id	number	Yes	GitHub Actions run ID

Example: "Analyze the failure in run 12345"

Output includes:

• Failure category (dependency, environment, test, etc.)
• Matched pattern ID and description
• Confidence score (0-100%)
• Matched error lines from the log

suggest_fix

Analyze a failed run and provide actionable fix suggestions for each detected failure pattern.

Parameter	Type	Required	Description
repo	string	No	Repository in owner/repo format
run_id	number	Yes	GitHub Actions run ID

Example: "Suggest fixes for run 12345"

Some patterns provide dynamic fix suggestions that extract context from the error (e.g., the conflicting package name from an ERESOLVE error).

compare_runs

Compare two workflow runs side-by-side: timing deltas per job, new vs resolved failures.

Parameter	Type	Required	Description
repo	string	No	Repository in owner/repo format
run_id_a	number	Yes	First workflow run ID (baseline)
run_id_b	number	Yes	Second workflow run ID (comparison)

Example: "Compare runs 12345 and 12346"

validate_workflow

Validate a GitHub Actions workflow YAML for syntax errors, missing fields, circular dependencies, and best practices.

Parameter	Type	Required	Description
repo	string	No	Repository in owner/repo format
workflow_yaml	string	No	Raw workflow YAML content to validate
file_path	string	No	Path to the workflow file in the repo (e.g., .github/workflows/ci.yml)

Provide either workflow_yaml or repo + file_path.

Validates:

• YAML syntax errors
• Required fields (on, jobs, runs-on, steps)
• Valid runner labels
• needs references exist
• Circular dependency detection (DFS)
• Deprecated ::set-output / ::save-state commands
• Action version pinning (warns on @main / @master)

dry_run_workflow

Resolve matrix strategies and display the full execution plan for a workflow without running it.

Parameter	Type	Required	Description
repo	string	No	Repository in owner/repo format
workflow_yaml	string	No	Raw workflow YAML content
file_path	string	No	Path to the workflow file in the repo (e.g., .github/workflows/ci.yml)
event	string	No	Trigger event to simulate (default: push)

Output includes:

• Resolved matrix combinations (cartesian product)
• Job dependency graph (topological order)
• Conditional expressions per job
• Step listing per job
• Total job combination count