# Deep Reasoning MCP Server

[![PyPI version](https://img.shields.io/pypi/v/deep-reasoning-mcp)](https://pypi.org/project/deep-reasoning-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/deep-reasoning-mcp)](https://pypi.org/project/deep-reasoning-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A [Model Context Protocol](https://modelcontextprotocol.io) server that turns Claude Code into a recursive analysis engine. Instead of linear reasoning, it builds **explorable decision trees** where every finding is traced as an IF/THEN chain, challenged with mitigations, and expanded into sub-findings at configurable depth.

## Why

Claude Code is excellent at reasoning, but complex problems — architecture reviews, production debugging, incident triage — benefit from **structured exploration**. Without structure, analysis tends to be shallow: the first plausible explanation wins, edge cases are missed, and mitigations are proposed without examining the risks they introduce.

Deep Reasoning forces a disciplined process:

1. **Scan** — Map the problem space, identify 3-7 critical areas
2. **Explore** — For each finding, trace the full consequence chain. Challenge every mitigation: "Does this fix introduce new problems?" Discover sub-findings.
3. **Synthesize** — Produce a prioritized action plan, residual risks, and decision log

The result is an analysis that is reproducible, auditable, and significantly more thorough than a single-pass review.

## How It Works

```
                    deep_scan             Initial reconnaissance
                        |                Identifies 3-7 key findings
                        v                May ask clarifying questions
                   deep_explore          Recursive what-if chains
                  /     |     \          Loops until max depth
             Branch  Branch  Branch      Each gets mitigations + sub-findings
                  \     |     /
                        v
                  deep_synthesize        Action plan, residual risks,
                                         decision log, quick wins
```

Sessions are persisted automatically. You can pause an analysis, close Claude Code, and resume days later with `deep_resume`.

## Execution Modes

| Mode | Cost | Requires | Best for |
|------|------|----------|----------|
| **orchestrator** | Zero extra | Any Claude Code plan | Interactive analysis where Claude Code reasons through the prompts itself |
| **autonomous** | API credits | `ANTHROPIC_API_KEY` | Batch analysis, CI/CD pipelines, non-Claude MCP clients |

**Auto-detection**: if `ANTHROPIC_API_KEY` is set, defaults to autonomous. Otherwise, defaults to orchestrator. You can override per-call with the `mode` parameter.

## Installation

### From PyPI

```bash
pip install deep-reasoning-mcp
```

### From source

```bash
git clone https://github.com/yourusername/deep-reasoning-mcp.git
cd deep-reasoning-mcp
uv sync
```

## Configuration

### Claude Code

Add to `~/.claude/settings.json`:

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

If installed from PyPI:

```json
{
  "mcpServers": {
    "deep-reasoning": {
      "command": "deep-reasoning-mcp"
    }
  }
}
```

### With autonomous mode

```json
{
  "mcpServers": {
    "deep-reasoning": {
      "command": "deep-reasoning-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ANTHROPIC_API_KEY` | _(none)_ | Enables autonomous mode. Not needed for orchestrator. |
| `DEEP_REASONING_MODEL` | `claude-opus-4-20250514` | Model for autonomous API calls |
| `DEEP_REASONING_MAX_TOKENS` | `4096` | Max tokens per autonomous API call |
| `DEEP_REASONING_MAX_CONCURRENT` | `3` | Max concurrent API calls (autonomous) |
| `DEEP_REASONING_COOLDOWN_MS` | `500` | Minimum delay between API calls in ms (autonomous) |

## Tools

### `deep_scan` — Initial Reconnaissance

Always call this first. Maps the problem space and identifies critical findings.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `description` | Yes | The problem, code, or architecture to analyze |
| `analysis_type` | No | `architecture`, `code_review`, `debugging`, `incident`, `brainstorming` (default: `architecture`) |
| `context` | No | Additional codebase/stack context |
| `depth` | No | Max exploration depth 1-5 (default: 3) |
| `language` | No | Output language code, e.g. `en`, `it`, `de` (default: `en`) |
| `mode` | No | `orchestrator` or `autonomous` (auto-detected) |
| `model` | No | Model override for autonomous mode |

### `deep_explore` — Recursive What-If Analysis

Explores specific branches of the reasoning tree. Call multiple times to deepen.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `tree` | Yes | Reasoning tree JSON from `deep_scan` or previous `deep_explore` |
| `branch_ids` | No | Specific finding IDs to explore (default: all pending) |
| `clarification_answers` | No | Answers to pending questions `{question_id: answer}` |
| `go_ahead` | No | Skip unanswered clarifications and proceed (default: `false`) |
| `mode` | No | `orchestrator` or `autonomous` (auto-detected) |
| `model` | No | Model override for autonomous mode |

### `deep_synthesize` — Final Report

Produces a prioritized action plan from the completed reasoning tree.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `tree` | Yes | Completed reasoning tree JSON |
| `language` | No | Report language (default: `en`) |
| `mode` | No | `orchestrator` or `autonomous` (auto-detected) |
| `model` | No | Model override for autonomous mode |

Returns a Markdown report with: Executive Summary, Critical Findings, Action Plan, Quick Wins, Residual Risks, Decision Log.

### `deep_list_sessions` — List Saved Sessions

| Parameter | Required | Description |
|-----------|----------|-------------|
| `analysis_type` | No | Filter by type |
| `status` | No | Filter by status (`pending`, `exploring`, `complete`) |
| `limit` | No | Max results 1-500 (default: 50) |

### `deep_resume` — Resume a Session

| Parameter | Required | Description |
|-----------|----------|-------------|
| `session_id` | Yes | Session ID (supports partial matching) |

### `deep_save_session` — Save Manually

| Parameter | Required | Description |
|-----------|----------|-------------|
| `tree` | Yes | Reasoning tree to save |
| `session_name` | No | Custom name (auto-generated if omitted) |

### `deep_delete_session` — Delete a Session

| Parameter | Required | Description |
|-----------|----------|-------------|
| `session_id` | Yes | Session ID to delete (exact match) |

## Usage Examples

### Architecture review

```
Analyze the payment callback flow for race conditions.
Stack: Django 4.2, PostgreSQL, Celery, RabbitMQ.
PSPs send HTTP POST callbacks that can arrive within milliseconds of each other.
```

### Production debugging

```
Payment callbacks timeout randomly after 30s under load.
Logs show the PSP responds in 2s. The issue started after last Thursday's deploy.
Stack: Django, Gunicorn (4 workers), PostgreSQL, Redis cache.
```

### Incident triage

```
Production: ticket validation failing for operator CTM for ~20 minutes.
No recent deploys. Health checks pass. Grafana shows normal latency
but elevated 500s on the /api/v2/validate/ endpoint.
```

### Brainstorming

```
We're evaluating migrating from Celery to Django-Q2 for async tasks.
We have ~50 Celery tasks, some with complex retry logic, beat scheduling,
and chain/chord patterns. What are the trade-offs?
```

## Session Persistence

Sessions are saved automatically to `~/.claude/deep-reasoning/sessions/`. Each session is a self-contained JSON file that captures the full reasoning tree.

```
~/.claude/deep-reasoning/
  sessions/
    20250409_152030_debugging_payment_callback.json
    20250408_091500_architecture_auth_flow.json
  index.json
```

Workflow:
1. Start: `deep_scan(...)` — session auto-saved
2. Pause: close Claude Code anytime
3. Resume: `deep_list_sessions()` then `deep_resume({session_id: "payment_callback"})`
4. Complete: `deep_synthesize(...)` — final report

## Reasoning Tree Structure

The JSON tree passed between tools:

```json
{
  "id": "a1b2c3d4",
  "version": "2.0",
  "analysis_type": "architecture",
  "max_depth": 3,
  "current_depth": 2,
  "status": "exploring",
  "language": "en",
  "description": "Original problem description",
  "findings": [
    {
      "id": "e5f6g7h8",
      "depth": 1,
      "status": "complete",
      "title": "Race condition on payment callback",
      "severity": "critical",
      "condition": "IF two callbacks arrive within 50ms for same transaction",
      "consequence": "THEN duplicate transaction record created",
      "mitigations": [
        {
          "action": "Add SELECT FOR UPDATE on transaction lookup",
          "where": "PaymentCallbackView.process_callback()",
          "risk_introduced": "Increased lock contention under high load",
          "effort": "medium"
        }
      ],
      "sub_findings": [
        {
          "id": "i9j0k1l2",
          "depth": 2,
          "status": "pending",
          "title": "Lock contention under peak load",
          "severity": "high",
          "condition": "IF >100 concurrent callbacks hit the same lock",
          "consequence": "THEN connection pool exhaustion, cascading timeouts"
        }
      ]
    }
  ],
  "metadata": {
    "total_findings": 5,
    "explored_findings": 3,
    "critical_count": 1,
    "high_count": 2
  }
}
```

## Comparison with sequential-thinking

| | sequential-thinking | deep-reasoning |
|---|---|---|
| Structure | Linear chain | Recursive tree |
| Depth | Single pass | Configurable 1-5 levels |
| Persistence | None | Auto-saved sessions |
| Best for | Quick orientation, simple problems | Thorough analysis, complex systems |
| Output | Thought stream | Structured report with action plan |

They complement each other: sequential-thinking identifies the area, deep-reasoning explores it.

## Project Structure

```
deep_reasoning_mcp/
  __init__.py      # Package entry point
  server.py        # MCP tool handlers
  models.py        # Pydantic models and enums
  tree.py          # Reasoning tree helpers
  session.py       # Session persistence
  prompts.py       # Analysis-type-specific prompts
  llm.py           # Anthropic API client with rate limiting
```

## Author

Maurizio Mocci — [mauriziomocci@gmail.com](mailto:mauriziomocci@gmail.com)

## License

MIT