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 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

Fetch recent failed workflow runs with metadata.

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

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

get_run_details

Get the full structural breakdown of a workflow run: all jobs, steps, statuses, and per-step timing.

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

Pull logs for a specific run with error extraction and smart truncation (50K char limit). 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 logs to a specific job
step_name	string	No	Filter logs to a specific step

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

analyze_failure

Pattern-match logs against the failure classification database (88 patterns across 9 categories). Returns root cause analysis with confidence scores.

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

Generate actionable fix suggestions based on failure analysis. Returns corrected YAML snippets, shell commands, or step-by-step remediation.

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

Diff two workflow runs side-by-side: timing deltas per job, new vs resolved failures, and overall duration change.

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

Example: "Compare runs 12345 and 12346"

validate_workflow

Validate a GitHub Actions workflow YAML against the spec. Checks syntax, required fields, runner labels, circular dependencies, action pinning, and deprecated commands.

Parameter	Type	Required	Description
repo	string	No	Repository in owner/repo format
workflow_yaml	string	No	Raw YAML content to validate
file_path	string	No	Path to workflow file in the repo

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 without running any jobs.

Parameter	Type	Required	Description
repo	string	No	Repository in owner/repo format
workflow_yaml	string	No	Raw YAML content
file_path	string	No	Path to workflow file in the repo
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