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 loopsmcp_connectivity— STDIO crashes, HTTP/SSE transport, protocol negotiationauth_error— env var injection, OAuth token expiry, delegated user authorchestration— state reducers, multi-agent handoffs, recursion loopslatency— TTFT vs. streaming, context bloat, model routinghallucination— retrieval recall vs. weak context grounding
- Fast-forward support — pass
already_known_answersto skip questions you've already confirmed from logs or code - Escape hatch —
other_unlisted_issueroutes 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.