Metadata-Version: 2.4
Name: debug-doctor-mcp
Version: 0.1.0
Summary: Interactive diagnostic MCP server for debugging Agentic AI problems
Keywords: mcp,debugging,diagnostics,agent,rag,llm,ai-agents
Author: Ajitha G
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Debuggers
Classifier: Typing :: Typed
Requires-Dist: fastmcp>=4.2.1
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# 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`](https://docs.astral.sh/uv/).

```bash
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):

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

Or after `uv tool install`:

```json
{
  "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
