debug-doctor-mcp 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ajitha G
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,140 @@
1
+ Metadata-Version: 2.4
2
+ Name: debug-doctor-mcp
3
+ Version: 0.1.0
4
+ Summary: Interactive diagnostic MCP server for debugging Agentic AI problems
5
+ Keywords: mcp,debugging,diagnostics,agent,rag,llm,ai-agents
6
+ Author: Ajitha G
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Programming Language :: Python :: 3.14
16
+ Classifier: Topic :: Software Development :: Debuggers
17
+ Classifier: Typing :: Typed
18
+ Requires-Dist: fastmcp>=4.2.1
19
+ Requires-Python: >=3.12
20
+ Description-Content-Type: text/markdown
21
+
22
+ # Agent Debug Doctor MCP
23
+
24
+ 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.
25
+
26
+ ## Features
27
+
28
+ - **Structured decision trees** for six problem categories:
29
+ - `tool_failure` — tool selection, schema/argument validation, silent failure loops
30
+ - `mcp_connectivity` — STDIO crashes, HTTP/SSE transport, protocol negotiation
31
+ - `auth_error` — env var injection, OAuth token expiry, delegated user auth
32
+ - `orchestration` — state reducers, multi-agent handoffs, recursion loops
33
+ - `latency` — TTFT vs. streaming, context bloat, model routing
34
+ - `hallucination` — retrieval recall vs. weak context grounding
35
+ - **Fast-forward support** — pass `already_known_answers` to skip questions you've already confirmed from logs or code
36
+ - **Escape hatch** — `other_unlisted_issue` routes out-of-playbook symptoms to raw trace inspection instead of forcing a wrong guess
37
+ - Zero-config, in-memory sessions — runs locally over STDIO via `uv`
38
+
39
+ ## Installation
40
+
41
+ Requires Python >= 3.12 and [`uv`](https://docs.astral.sh/uv/).
42
+
43
+ ```bash
44
+ uv tool install debug-doctor-mcp
45
+ # or run directly from source:
46
+ uv --directory /path/to/debug-doctor-mcp run debug-doctor-mcp
47
+ ```
48
+
49
+ ## MCP Client Configuration
50
+
51
+ Add to your MCP client config (e.g., `mcp_config.json`, `.mcp.json`, Claude Desktop):
52
+
53
+ ```json
54
+ {
55
+ "mcpServers": {
56
+ "debug-doctor": {
57
+ "command": "uv",
58
+ "args": [
59
+ "--directory",
60
+ "/path/to/debug-doctor-mcp",
61
+ "run",
62
+ "debug-doctor-mcp"
63
+ ]
64
+ }
65
+ }
66
+ }
67
+ ```
68
+
69
+ Or after `uv tool install`:
70
+
71
+ ```json
72
+ {
73
+ "mcpServers": {
74
+ "debug-doctor": {
75
+ "command": "debug-doctor-mcp"
76
+ }
77
+ }
78
+ }
79
+ ```
80
+
81
+ ## Tools
82
+
83
+ ### `start_agent_diagnosis`
84
+
85
+ Start a structured diagnosis session.
86
+
87
+ | Parameter | Type | Description |
88
+ |---|---|---|
89
+ | `symptom_summary` | `str` (required) | Plain-language description of the problem |
90
+ | `problem_type` | `str` | `tool_failure`, `mcp_connectivity`, `auth_error`, `orchestration`, `latency`, `hallucination`, or `default` |
91
+ | `already_known_answers` | `dict[str, str]` | Map of `{node_id: option_key}` to skip already-answered questions |
92
+
93
+ Returns the first question with `valid_options`, an `ide_code_hint` for where to look in the codebase, and a `session_id`.
94
+
95
+ ### `submit_answer`
96
+
97
+ Advance the session by selecting one of the `valid_options`.
98
+
99
+ | Parameter | Type | Description |
100
+ |---|---|---|
101
+ | `session_id` | `str` (required) | Session ID from `start_agent_diagnosis` |
102
+ | `selected_option` | `str` (required) | One of the `valid_options` keys |
103
+
104
+ Returns either the next question or a final `diagnosis` with `root_cause` and `action_plan`.
105
+
106
+ ### `debug_latency` (prompt)
107
+
108
+ Slash-command prompt that kicks off a latency diagnosis.
109
+
110
+ ## Example Flow
111
+
112
+ ```
113
+ User: "The order_details tool intermittently returns HTTP 500 errors"
114
+
115
+ → start_agent_diagnosis(problem_type="tool_failure")
116
+ → Q: How is the tool call failing?
117
+ options: [llm_ignores_or_picks_wrong_tool,
118
+ argument_json_or_pydantic_validation_error,
119
+ tool_returns_empty_and_agent_loops,
120
+ other_unlisted_issue]
121
+ → submit_answer(selected_option="tool_returns_empty_and_agent_loops")
122
+ → Diagnosis: "Silent Tool Failure Loop"
123
+ Action plan: return structured STATUS strings on empty results,
124
+ add a call-signature cache to block duplicate invocations
125
+ ```
126
+
127
+ ## Project Structure
128
+
129
+ ```
130
+ src/debug_doctor_mcp/
131
+ ├── server.py # FastMCP server, session state, tool handlers
132
+ ├── playbook.json # Decision-tree nodes, options, diagnoses, action plans
133
+ └── __init__.py
134
+ ```
135
+
136
+ 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`.
137
+
138
+ ## License
139
+
140
+ MIT
@@ -0,0 +1,119 @@
1
+ # Agent Debug Doctor MCP
2
+
3
+ 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.
4
+
5
+ ## Features
6
+
7
+ - **Structured decision trees** for six problem categories:
8
+ - `tool_failure` — tool selection, schema/argument validation, silent failure loops
9
+ - `mcp_connectivity` — STDIO crashes, HTTP/SSE transport, protocol negotiation
10
+ - `auth_error` — env var injection, OAuth token expiry, delegated user auth
11
+ - `orchestration` — state reducers, multi-agent handoffs, recursion loops
12
+ - `latency` — TTFT vs. streaming, context bloat, model routing
13
+ - `hallucination` — retrieval recall vs. weak context grounding
14
+ - **Fast-forward support** — pass `already_known_answers` to skip questions you've already confirmed from logs or code
15
+ - **Escape hatch** — `other_unlisted_issue` routes out-of-playbook symptoms to raw trace inspection instead of forcing a wrong guess
16
+ - Zero-config, in-memory sessions — runs locally over STDIO via `uv`
17
+
18
+ ## Installation
19
+
20
+ Requires Python >= 3.12 and [`uv`](https://docs.astral.sh/uv/).
21
+
22
+ ```bash
23
+ uv tool install debug-doctor-mcp
24
+ # or run directly from source:
25
+ uv --directory /path/to/debug-doctor-mcp run debug-doctor-mcp
26
+ ```
27
+
28
+ ## MCP Client Configuration
29
+
30
+ Add to your MCP client config (e.g., `mcp_config.json`, `.mcp.json`, Claude Desktop):
31
+
32
+ ```json
33
+ {
34
+ "mcpServers": {
35
+ "debug-doctor": {
36
+ "command": "uv",
37
+ "args": [
38
+ "--directory",
39
+ "/path/to/debug-doctor-mcp",
40
+ "run",
41
+ "debug-doctor-mcp"
42
+ ]
43
+ }
44
+ }
45
+ }
46
+ ```
47
+
48
+ Or after `uv tool install`:
49
+
50
+ ```json
51
+ {
52
+ "mcpServers": {
53
+ "debug-doctor": {
54
+ "command": "debug-doctor-mcp"
55
+ }
56
+ }
57
+ }
58
+ ```
59
+
60
+ ## Tools
61
+
62
+ ### `start_agent_diagnosis`
63
+
64
+ Start a structured diagnosis session.
65
+
66
+ | Parameter | Type | Description |
67
+ |---|---|---|
68
+ | `symptom_summary` | `str` (required) | Plain-language description of the problem |
69
+ | `problem_type` | `str` | `tool_failure`, `mcp_connectivity`, `auth_error`, `orchestration`, `latency`, `hallucination`, or `default` |
70
+ | `already_known_answers` | `dict[str, str]` | Map of `{node_id: option_key}` to skip already-answered questions |
71
+
72
+ Returns the first question with `valid_options`, an `ide_code_hint` for where to look in the codebase, and a `session_id`.
73
+
74
+ ### `submit_answer`
75
+
76
+ Advance the session by selecting one of the `valid_options`.
77
+
78
+ | Parameter | Type | Description |
79
+ |---|---|---|
80
+ | `session_id` | `str` (required) | Session ID from `start_agent_diagnosis` |
81
+ | `selected_option` | `str` (required) | One of the `valid_options` keys |
82
+
83
+ Returns either the next question or a final `diagnosis` with `root_cause` and `action_plan`.
84
+
85
+ ### `debug_latency` (prompt)
86
+
87
+ Slash-command prompt that kicks off a latency diagnosis.
88
+
89
+ ## Example Flow
90
+
91
+ ```
92
+ User: "The order_details tool intermittently returns HTTP 500 errors"
93
+
94
+ → start_agent_diagnosis(problem_type="tool_failure")
95
+ → Q: How is the tool call failing?
96
+ options: [llm_ignores_or_picks_wrong_tool,
97
+ argument_json_or_pydantic_validation_error,
98
+ tool_returns_empty_and_agent_loops,
99
+ other_unlisted_issue]
100
+ → submit_answer(selected_option="tool_returns_empty_and_agent_loops")
101
+ → Diagnosis: "Silent Tool Failure Loop"
102
+ Action plan: return structured STATUS strings on empty results,
103
+ add a call-signature cache to block duplicate invocations
104
+ ```
105
+
106
+ ## Project Structure
107
+
108
+ ```
109
+ src/debug_doctor_mcp/
110
+ ├── server.py # FastMCP server, session state, tool handlers
111
+ ├── playbook.json # Decision-tree nodes, options, diagnoses, action plans
112
+ └── __init__.py
113
+ ```
114
+
115
+ 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`.
116
+
117
+ ## License
118
+
119
+ MIT
@@ -0,0 +1,33 @@
1
+ [project]
2
+ name = "debug-doctor-mcp"
3
+ version = "0.1.0"
4
+ description = "Interactive diagnostic MCP server for debugging Agentic AI problems"
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ requires-python = ">=3.12"
9
+ authors = [
10
+ { name = "Ajitha G" }
11
+ ]
12
+ keywords = ["mcp", "debugging", "diagnostics", "agent", "rag", "llm", "ai-agents"]
13
+ classifiers = [
14
+ "Development Status :: 4 - Beta",
15
+ "Intended Audience :: Developers",
16
+ "License :: OSI Approved :: MIT License",
17
+ "Programming Language :: Python :: 3",
18
+ "Programming Language :: Python :: 3.12",
19
+ "Programming Language :: Python :: 3.13",
20
+ "Programming Language :: Python :: 3.14",
21
+ "Topic :: Software Development :: Debuggers",
22
+ "Typing :: Typed",
23
+ ]
24
+ dependencies = [
25
+ "fastmcp>=4.2.1",
26
+ ]
27
+
28
+ [project.scripts]
29
+ debug-doctor-mcp = "debug_doctor_mcp.server:main"
30
+
31
+ [build-system]
32
+ requires = ["uv_build>=0.9.24,<0.10.0"]
33
+ build-backend = "uv_build"
@@ -0,0 +1 @@
1
+ """Agent Debug Doctor MCP server package."""
@@ -0,0 +1,210 @@
1
+ {
2
+ "flows": {
3
+ "tool_failure": "q1_tool_failure_stage",
4
+ "mcp_connectivity": "q1_mcp_transport",
5
+ "auth_error": "q1_auth_layer",
6
+ "orchestration": "q1_orchestration_bug",
7
+ "latency": "q1_latency_phase",
8
+ "hallucination": "q1_hallucination_source",
9
+ "default": "q0_triage_category"
10
+ },
11
+ "nodes": {
12
+ "q0_triage_category": {
13
+ "question": "Which layer of your agent system is failing right now?",
14
+ "code_hint": "Inspect error tracebacks, MCP configs, tool schemas, or graph state definitions in the workspace.",
15
+ "options": {
16
+ "tool_call_or_schema_failure": "q1_tool_failure_stage",
17
+ "mcp_server_connection_or_protocol": "q1_mcp_transport",
18
+ "auth_401_403_or_token_expiry": "q1_auth_layer",
19
+ "multi_agent_orchestration_or_state": "q1_orchestration_bug",
20
+ "rag_or_agent_latency": "q1_latency_phase",
21
+ "rag_hallucination_or_bad_retrieval": "q1_hallucination_source",
22
+ "other_unlisted_issue": "exit_escalate_raw_trace"
23
+ }
24
+ },
25
+
26
+ "q1_tool_failure_stage": {
27
+ "question": "How is the tool call failing: the LLM never picks the tool, arguments fail schema validation, or the tool executes and throws a runtime/loop error?",
28
+ "code_hint": "Check tool docstrings/descriptions, Pydantic/JSON schemas (especially Optional/Union types), and tool return values.",
29
+ "options": {
30
+ "llm_ignores_or_picks_wrong_tool": "fix_tool_selection_schema",
31
+ "argument_json_or_pydantic_validation_error": "fix_tool_arg_validation",
32
+ "tool_returns_empty_and_agent_loops": "fix_explicit_tool_errors",
33
+ "other_unlisted_issue": "exit_escalate_raw_trace"
34
+ }
35
+ },
36
+ "fix_tool_selection_schema": {
37
+ "diagnosis": "Ambiguous Tool Routing / Weak Tool Descriptions",
38
+ "root_cause": "Overlapping tool names, vague docstrings, or loading >15 tools at once causes the LLM to skip tools or pick the wrong one.",
39
+ "action_plan": [
40
+ "Rewrite each tool docstring to specify: (1) exact trigger condition, (2) required preconditions, and (3) what NOT to use the tool for.",
41
+ "Cap active tools per agent node to under 10–12; group domain tools behind a router or sub-agent.",
42
+ "Set `tool_choice='required'` on nodes where a tool call is mandatory."
43
+ ]
44
+ },
45
+ "fix_tool_arg_validation": {
46
+ "diagnosis": "Strict Schema Mismatch / Malformed Tool Arguments",
47
+ "root_cause": "Complex nested Pydantic models, `Union` types, or strict JSON schemas cause the LLM to emit invalid types or missing required fields.",
48
+ "action_plan": [
49
+ "Flatten nested input objects into top-level primitive arguments (`str`, `int`, `bool`, `list[str]`) with explicit `Field(description=...)` examples.",
50
+ "Catch `ValidationError` inside the tool wrapper and return the exact validation message back to the LLM as a `ToolMessage` so it can self-correct on the next turn instead of crashing."
51
+ ]
52
+ },
53
+ "fix_explicit_tool_errors": {
54
+ "diagnosis": "Silent Tool Failure Loop",
55
+ "root_cause": "Returning `[]`, `None`, or a raw stack trace causes the agent to retry the same tool repeatedly with slightly rephrased arguments.",
56
+ "action_plan": [
57
+ "Return structured status strings on empty/failed calls: e.g., `'STATUS: NO_RESULTS. Do not retry with similar parameters; try another source or answer the user.'`",
58
+ "Add a session-level call signature cache that blocks identical `(tool_name, args)` invocations."
59
+ ]
60
+ },
61
+
62
+ "q1_mcp_transport": {
63
+ "question": "Which MCP transport is failing: local STDIO (subprocess won't start/hangs) or remote HTTP/SSE (handshake, CORS, or timeout)?",
64
+ "code_hint": "Inspect `mcp.json` command/args, stdout `print()` statements in STDIO servers, or HTTP/SSE endpoint URLs and headers.",
65
+ "options": {
66
+ "stdio_server_crashes_or_hangs": "fix_mcp_stdio_corruption",
67
+ "remote_http_sse_handshake_or_timeout": "fix_mcp_remote_transport",
68
+ "tools_missing_or_schema_rejected_by_client": "fix_mcp_capability_negotiation",
69
+ "other_unlisted_issue": "exit_escalate_raw_trace"
70
+ }
71
+ },
72
+ "fix_mcp_stdio_corruption": {
73
+ "diagnosis": "MCP STDIO Stream Corruption or Environment Mismatch",
74
+ "root_cause": "Writing `print()` logs to `stdout` corrupts JSON-RPC framing, or the host IDE cannot resolve `uv`/`python` in its non-interactive PATH.",
75
+ "action_plan": [
76
+ "Remove all `print()` statements or redirect logging strictly to `sys.stderr` (`logging.basicConfig(stream=sys.stderr)`).",
77
+ "Use absolute paths for the executable in `mcp.json` (e.g., `/Users/name/.local/bin/uv` instead of `uv`) and pass `--directory` explicitly."
78
+ ]
79
+ },
80
+ "fix_mcp_remote_transport": {
81
+ "diagnosis": "Remote MCP Streamable HTTP / SSE Transport Failure",
82
+ "root_cause": "Reverse proxies (Nginx/Cloudflare) buffer SSE streams, drop idle connections, or block `Mcp-Session-Id` headers.",
83
+ "action_plan": [
84
+ "Disable proxy response buffering (`X-Accel-Buffering: no`) and increase proxy read timeouts above 300s for long-running tool calls.",
85
+ "Ensure CORS allows `Mcp-Session-Id` and `Authorization` headers if accessed from browser-based MCP clients."
86
+ ]
87
+ },
88
+ "fix_mcp_capability_negotiation": {
89
+ "diagnosis": "MCP Protocol Version or JSON Schema Incompatibility",
90
+ "root_cause": "Client and server negotiated mismatched protocol versions, or tool input schemas use unsupported JSON Schema keywords (e.g., `$ref`, `anyOf`).",
91
+ "action_plan": [
92
+ "Verify both client SDK and `fastmcp` versions support the same MCP spec revision and check `initialize` handshake logs.",
93
+ "Simplify tool parameter types to avoid recursive `$ref` definitions that strict MCP clients reject."
94
+ ]
95
+ },
96
+
97
+ "q1_auth_layer": {
98
+ "question": "Where is the 401/403 error occurring: calling the LLM/MCP server itself, or inside a downstream tool calling an external API on behalf of a user?",
99
+ "code_hint": "Check `env` blocks in `mcp.json`, OAuth token refresh logic, and how user credentials are passed into tool context.",
100
+ "options": {
101
+ "env_vars_not_loaded_in_mcp_or_worker": "fix_mcp_env_injection",
102
+ "downstream_user_oauth_token_expired_or_missing": "fix_delegated_user_auth",
103
+ "other_unlisted_issue": "exit_escalate_raw_trace"
104
+ }
105
+ },
106
+ "fix_mcp_env_injection": {
107
+ "diagnosis": "Missing Environment Variables in Subprocess Context",
108
+ "root_cause": "IDE-spawned MCP servers do not inherit shell `.zshrc`/`.bashrc` exports or `.env` files unless explicitly configured.",
109
+ "action_plan": [
110
+ "Declare required secrets inside the `\"env\": { \"API_KEY\": \"...\" }` block of `mcp.json`, or load `.env` via an explicit absolute path with `python-dotenv`."
111
+ ]
112
+ },
113
+ "fix_delegated_user_auth": {
114
+ "diagnosis": "Broken Per-User Token Propagation / Refresh",
115
+ "root_cause": "Static global API keys are used instead of per-request user tokens, or short-lived OAuth tokens expire mid-session without a refresh hook.",
116
+ "action_plan": [
117
+ "Pass user auth tokens via runtime configurable context (`RunnableConfig` / FastMCP request context) rather than global variables or LLM-visible tool arguments.",
118
+ "Wrap downstream API clients with an automatic 401 token-refresh interceptor."
119
+ ]
120
+ },
121
+
122
+ "q1_orchestration_bug": {
123
+ "question": "What is breaking in your agent workflow: state/memory getting overwritten or bloated, handoffs dropping context between agents, or premature termination?",
124
+ "code_hint": "Check state reducers (`Annotated[list, add]`), checkpointer persistence (`thread_id`), and handoff message filtering.",
125
+ "options": {
126
+ "state_overwritten_or_lost_across_turns": "fix_state_reducers_and_checkpointing",
127
+ "handoff_drops_context_or_bloats_history": "fix_multi_agent_handoff",
128
+ "infinite_agent_bouncing_or_recursion_error": "fix_loop_circuit_breaker",
129
+ "other_unlisted_issue": "exit_escalate_raw_trace"
130
+ }
131
+ },
132
+ "fix_state_reducers_and_checkpointing": {
133
+ "diagnosis": "Missing State Reducers or Thread Isolation Bug",
134
+ "root_cause": "Parallel nodes overwrite shared state keys instead of appending, or missing/shared `thread_id` leaks state across users.",
135
+ "action_plan": [
136
+ "Use explicit reducer annotations (e.g., `Annotated[list[AnyMessage], add_messages]`) so parallel branches merge outputs safely.",
137
+ "Enforce unique, tenant-scoped `thread_id` values in checkpointer configs (`{'configurable': {'thread_id': f'{tenant_id}:{session_id}'}}`)."
138
+ ]
139
+ },
140
+ "fix_multi_agent_handoff": {
141
+ "diagnosis": "Unfiltered History Bloat or Context Loss on Handoff",
142
+ "root_cause": "Passing full raw tool traces between sub-agents blows up context limits, while passing only the last message drops critical constraints.",
143
+ "action_plan": [
144
+ "Pass a structured `handoff_summary` object (goal, constraints, completed artifacts) to sub-agents instead of raw internal `ToolMessage` histories."
145
+ ]
146
+ },
147
+ "fix_loop_circuit_breaker": {
148
+ "diagnosis": "Unbounded Agent Routing Cycle",
149
+ "root_cause": "Supervisor/worker edges lack a step counter or stop condition when sub-agents disagree.",
150
+ "action_plan": [
151
+ "Track `hop_count` in graph state and route to a finalizer node once `hop_count >= 4` instead of letting `GraphRecursionError` crash the request."
152
+ ]
153
+ },
154
+
155
+ "q1_latency_phase": {
156
+ "question": "Where is the delay: before the first token arrives (TTFT), or slow streaming generation?",
157
+ "code_hint": "Check `stream=True`, `top_k`, rerankers, and whether heavy reasoning models are used for routing.",
158
+ "options": {
159
+ "before_first_word": "fix_ttft_pipeline",
160
+ "slow_generation_or_overkill_model": "fix_streaming_and_model_routing",
161
+ "other_unlisted_issue": "exit_escalate_raw_trace"
162
+ }
163
+ },
164
+ "fix_ttft_pipeline": {
165
+ "diagnosis": "High Pre-Generation Latency (TTFT)",
166
+ "root_cause": "Sequential retrieval/reranking calls, uncached repeated queries, or >5 chunks bloating prompt prefill.",
167
+ "action_plan": [
168
+ "Parallelize independent retrieval calls with asyncio.gather(), cap final chunks to 3–5, and cache repeated embeddings/retrievals."
169
+ ]
170
+ },
171
+ "fix_streaming_and_model_routing": {
172
+ "diagnosis": "Blocking Generation or Overkill Model Routing",
173
+ "root_cause": "Streaming is disabled or a flagship reasoning model is used for simple classification/formatting steps.",
174
+ "action_plan": [
175
+ "Enable stream=True on user-facing responses and route internal classification/formatting nodes to fast lightweight models."
176
+ ]
177
+ },
178
+ "q1_hallucination_source": {
179
+ "question": "Do the retrieved chunks contain the ground-truth answer before reaching the LLM?",
180
+ "code_hint": "Inspect retriever search type (dense-only vs. hybrid BM25) and prompt grounding instructions.",
181
+ "options": {
182
+ "chunks_missing_facts": "fix_hybrid_search_rrf",
183
+ "chunks_have_facts_but_llm_ignores": "fix_prompt_grounding",
184
+ "other_unlisted_issue": "exit_escalate_raw_trace"
185
+ }
186
+ },
187
+ "fix_hybrid_search_rrf": {
188
+ "diagnosis": "Dense-Only Retrieval Recall Failure",
189
+ "root_cause": "Pure vector search misses exact IDs, error codes, or domain keywords.",
190
+ "action_plan": [
191
+ "Combine BM25 lexical search with dense vector search via Reciprocal Rank Fusion (RRF) and filter stale docs via metadata."
192
+ ]
193
+ },
194
+ "fix_prompt_grounding": {
195
+ "diagnosis": "Weak Context Grounding",
196
+ "root_cause": "The LLM overrides retrieved context with parametric memory.",
197
+ "action_plan": [
198
+ "Wrap context in <context> tags, set temperature=0.0, and instruct the model to cite chunk IDs or refuse when evidence is absent."
199
+ ]
200
+ },
201
+ "exit_escalate_raw_trace": {
202
+ "diagnosis": "Out-of-Playbook Issue — Switch to Direct Stack-Trace Inspection",
203
+ "root_cause": "This symptom does not match the predefined decision branches. Do NOT force a playbook guess.",
204
+ "action_plan": [
205
+ "Ask the user to paste the exact error traceback, failing JSON-RPC/HTTP payload, or state dump.",
206
+ "Analyze the raw code and logs directly in the IDE rather than relying on canned playbook steps."
207
+ ]
208
+ }
209
+ }
210
+ }
@@ -0,0 +1,107 @@
1
+ import json
2
+ import uuid
3
+ from importlib.resources import files
4
+ from fastmcp import FastMCP
5
+
6
+ mcp = FastMCP("Agent Debug Doctor")
7
+
8
+ PLAYBOOK = json.loads(
9
+ files("debug_doctor_mcp").joinpath("playbook.json").read_text(encoding="utf-8")
10
+ )
11
+ SESSIONS: dict[str, dict] = {}
12
+
13
+
14
+ def _format_step(session_id: str, node_id: str) -> dict:
15
+ node = PLAYBOOK["nodes"][node_id]
16
+ if "diagnosis" in node:
17
+ return {
18
+ "status": "complete",
19
+ "session_id": session_id,
20
+ "diagnosis": node["diagnosis"],
21
+ "root_cause": node["root_cause"],
22
+ "action_plan": node["action_plan"],
23
+ "instruction": "Present this root cause and apply the action plan to the user's code.",
24
+ }
25
+ return {
26
+ "status": "in_progress",
27
+ "session_id": session_id,
28
+ "question": node["question"],
29
+ "valid_options": list(node["options"].keys()),
30
+ "ide_code_hint": node["code_hint"],
31
+ "instruction": (
32
+ "First inspect the user's workspace using `ide_code_hint`. "
33
+ "If the answer is obvious from their code, immediately call `submit_answer`. "
34
+ "Otherwise, ask the user `question` with the `valid_options`."
35
+ ),
36
+ }
37
+
38
+
39
+ @mcp.tool
40
+ def start_agent_diagnosis(
41
+ symptom_summary: str,
42
+ problem_type: str = "default",
43
+ already_known_answers: dict[str, str] | None = None,
44
+ ) -> dict:
45
+ """
46
+ Start a structured root-cause diagnosis for AI agent or RAG bugs.
47
+ - problem_type: 'tool_failure', 'mcp_connectivity', 'auth_error',
48
+ 'orchestration', 'latency', 'hallucination', or 'default'
49
+ - already_known_answers: optional map of {node_id: option_key} confirmed from user logs/code.
50
+ IMPORTANT: Never guess an option if uncertain; pass 'other_unlisted_issue' to inspect raw traces directly.
51
+ """
52
+
53
+ session_id = str(uuid.uuid4())[:8]
54
+ current_node = PLAYBOOK["flows"].get(problem_type.lower(), PLAYBOOK["flows"]["default"])
55
+ history = []
56
+
57
+ # Fast-forward past any questions already answered by the user's prompt
58
+ if already_known_answers:
59
+ while current_node in already_known_answers:
60
+ chosen = already_known_answers[current_node]
61
+ next_node = PLAYBOOK["nodes"][current_node].get("options", {}).get(chosen)
62
+ if not next_node:
63
+ break
64
+ history.append((current_node, chosen))
65
+ current_node = next_node
66
+
67
+ SESSIONS[session_id] = {
68
+ "symptom": symptom_summary,
69
+ "current_node": current_node,
70
+ "history": history,
71
+ }
72
+ return _format_step(session_id, current_node)
73
+
74
+
75
+
76
+ @mcp.tool
77
+ def submit_answer(session_id: str, selected_option: str) -> dict:
78
+ """Advance the MCP/Agent diagnostic session using one of the valid_options."""
79
+ session = SESSIONS.get(session_id)
80
+ if not session:
81
+ return {"error": "Session not found. Call `start_agent_diagnosis` first."}
82
+
83
+ node = PLAYBOOK["nodes"][session["current_node"]]
84
+ next_node = node.get("options", {}).get(selected_option)
85
+ if not next_node:
86
+ return {
87
+ "error": f"Invalid option '{selected_option}'.",
88
+ "valid_options": list(node.get("options", {}).keys()),
89
+ }
90
+
91
+ session["history"].append((session["current_node"], selected_option))
92
+ session["current_node"] = next_node
93
+ return _format_step(session_id, next_node)
94
+
95
+
96
+ @mcp.prompt
97
+ def debug_latency() -> str:
98
+ """Slash command to begin diagnosing latency."""
99
+ return "Run `start_agent_diagnosis` to inspect my MCP/AGENT pipeline and walk me through fixing latency."
100
+
101
+
102
+ def main() -> None:
103
+ mcp.run()
104
+
105
+
106
+ if __name__ == "__main__":
107
+ main()