Skip to main content

Agent Debug Doctor MCP

An interactive diagnostic MCP server that walks you through root-cause analysis for AI agent and RAG pipeline problems. Instead of guessing, it asks targeted questions, narrows the failure to a specific layer, and returns a diagnosis with a concrete action plan.

Features

  • Structured decision trees for six problem categories:
    • tool_failure — tool selection, schema/argument validation, silent failure loops
    • mcp_connectivity — STDIO crashes, HTTP/SSE transport, protocol negotiation
    • auth_error — env var injection, OAuth token expiry, delegated user auth
    • orchestration — state reducers, multi-agent handoffs, recursion loops
    • latency — TTFT vs. streaming, context bloat, model routing
    • hallucination — retrieval recall vs. weak context grounding
  • Fast-forward support — pass already_known_answers to skip questions you've already confirmed from logs or code
  • Escape hatch — other_unlisted_issue routes out-of-playbook symptoms to raw trace inspection instead of forcing a wrong guess
  • Zero-config, in-memory sessions — runs locally over STDIO via uv

Installation

Requires Python >= 3.12 and uv.

uv tool install debug-doctor-mcp
# or run directly from source:
uv --directory /path/to/debug-doctor-mcp run debug-doctor-mcp

MCP Client Configuration

Add to your MCP client config (e.g., mcp_config.json, .mcp.json, Claude Desktop):

{
  "mcpServers": {
    "debug-doctor": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/debug-doctor-mcp",
        "run",
        "debug-doctor-mcp"
      ]
    }
  }
}

Or after uv tool install:

{
  "mcpServers": {
    "debug-doctor": {
      "command": "debug-doctor-mcp"
    }
  }
}

Tools

start_agent_diagnosis

Start a structured diagnosis session.

Parameter Type Description
symptom_summary str (required) Plain-language description of the problem
problem_type str tool_failure, mcp_connectivity, auth_error, orchestration, latency, hallucination, or default
already_known_answers dict[str, str] Map of {node_id: option_key} to skip already-answered questions

Returns the first question with valid_options, an ide_code_hint for where to look in the codebase, and a session_id.

submit_answer

Advance the session by selecting one of the valid_options.

Parameter Type Description
session_id str (required) Session ID from start_agent_diagnosis
selected_option str (required) One of the valid_options keys

Returns either the next question or a final diagnosis with root_cause and action_plan.

debug_latency (prompt)

Slash-command prompt that kicks off a latency diagnosis.

Example Flow

User: "The order_details tool intermittently returns HTTP 500 errors"

→ start_agent_diagnosis(problem_type="tool_failure")
→ Q: How is the tool call failing?
   options: [llm_ignores_or_picks_wrong_tool,
             argument_json_or_pydantic_validation_error,
             tool_returns_empty_and_agent_loops,
             other_unlisted_issue]
→ submit_answer(selected_option="tool_returns_empty_and_agent_loops")
→ Diagnosis: "Silent Tool Failure Loop"
   Action plan: return structured STATUS strings on empty results,
   add a call-signature cache to block duplicate invocations

Project Structure

src/debug_doctor_mcp/
├── server.py        # FastMCP server, session state, tool handlers
├── playbook.json    # Decision-tree nodes, options, diagnoses, action plans
└── __init__.py

The decision trees live entirely in playbook.json — add new nodes/options/diagnoses there without touching Python code. Node IDs referenced in flows and already_known_answers must match keys under nodes.

License

MIT

Metadata

Release files for debug-doctor-mcp 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for debug-doctor-mcp 0.1.0
File Size Uploaded Provenance Actions
debug_doctor_mcp-0.1.0.tar.gz 8.9 kB Without provenance Details for debug_doctor_mcp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for debug-doctor-mcp 0.1.0
File Interpreter ABI Platform Actions
debug_doctor_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for debug_doctor_mcp-0.1.0-py3-none-any.whl

Total release size: 20.0 kB

Release files / debug_doctor_mcp-0.1.0.tar.gz

Download URL debug_doctor_mcp-0.1.0.tar.gz
Size 8.9 kB
Tags Source
SHA-256 checksum
How to use checksums
bca5743c0c600cbd168a65a587c76942f6fdc9f8f4c2424757564713cb7872e2
BLAKE2b-256 checksum
How to use checksums
5fcaf0dfe0361e90b206d3e728adae62dce018b840480bef6be278a65e3129b1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.24 {"installer":{"name":"uv","version":"0.9.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / debug_doctor_mcp-0.1.0-py3-none-any.whl

Download URL debug_doctor_mcp-0.1.0-py3-none-any.whl
Size 11.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e1da9425dee790ef5dbbe3ec0faefe224bc3e99a68e5669fca339583a1ceeeb2
BLAKE2b-256 checksum
How to use checksums
24aacf5e6d8af8f8e648676d85f465d62fd1c8a83a1fe1b1f644e5851589bd2e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.24 {"installer":{"name":"uv","version":"0.9.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for debug-doctor-mcp 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page