RootCause MCP

Medical reasoning, differential diagnosis, and clinical RCA harness for any MCP-compatible AI agent.

English | 繁體中文

Mission

RootCause MCP enables general-purpose agents such as Claude Code, Codex, Cline, OpenCode, OpenClaw, and Z.ai agents to perform a specialized workflow:

1. Ingest clinical documents through the host agent.

2. Register source-grounded evidence and provenance.

3. Build and update differential diagnoses with likelihood ratios.

4. Record explicit rationales, alternatives, uncertainty, and possible bias.

5. Connect diagnostic reasoning to Fishbone, 5-Why, HFACS-MES, and causation checks.

6. Produce a machine-readable, auditable report.

The agent performs the reasoning. The MCP server does not inspect hidden model states or raw private chain-of-thought. It provides schemas, workflow constraints, persistence, calculations, and audit records for reasoning the agent explicitly chooses to externalize.

This project is not a medical device and must not autonomously diagnose or treat patients. Clinical use requires qualified human review, local governance, privacy controls, and independent verification of source documents.

Related MCP server: SafetyOps MCP Server

Architecture

graph TB
    A[General-purpose AI Agent] -->|MCP SDK 2.0| T[36 typed tools]
    D[Clinical documents] --> A

    subgraph Harness
        T --> S[ServerState / case aggregate]
        S --> O[ClinicalReasoningOrchestrator]
        O --> E[Evidence + provenance]
        O --> H[Hypotheses + Bayesian updates]
        O --> R[ReasoningChain]
        S --> C[ThinkingChain: explicit rationale records]
    end

    E --> DB[(SQLite / SQLModel)]
    H --> DB
    R --> DB
    C --> DB

    S --> CR[CONTRACT report]
    CR --> J[JSON]
    CR --> F[FHIR-compatible DiagnosticReport]

    T --> RCA[Fishbone / 5-Why / HFACS-MES / causation]

The dependency direction follows DDD:

Interface -> Application -> Domain <- Infrastructure

What Is Persisted

The SDK 2.0 server persists the medical reasoning aggregate in SQLite:

• Structured Evidence and source metadata

• Differential-diagnosis hypotheses and Bayesian update history

• Explicit ThinkingStep records supplied by the agent

• ReasoningStep audit records generated by the orchestrator

• RCA sessions and Fishbone diagrams

Known limitation: the legacy Why Tree repository remains in memory and is not yet rehydrated after process restart. Authentication, encryption-at-rest, tenant isolation, database migrations, and regulated deployment controls must be supplied by the deployment environment before clinical production use.

Quick Start

# Install the locked environment
uv sync --all-extras

# Run the MCP SDK 2.0 stdio server
uv run rootcause-mcp

VS Code .vscode/mcp.json:

{
  "servers": {
    "rootcause-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "rootcause-mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Environment variables:

Agent Workflow

A compatible agent should follow the sequence below instead of jumping directly to a diagnosis:

rc_start_session
  -> rc_add_evidence
  -> rc_think_aloud / rc_identify_gaps / rc_challenge_assumption
  -> rc_propose_hypothesis
  -> rc_link_evidence_to_hypothesis
  -> rc_get_differential_diagnosis
  -> rc_get_reasoning_chain
  -> rc_verify_causation
  -> rc_generate_contract_report

rc_propose_hypothesis requires the agent to provide clinical rationale, alternatives considered, supporting evidence, uncertainty factors, and confidence rationale. These are explicit agent-authored records, not a dump of hidden model reasoning.

See Agent Integration Guide for payload examples.

Tool Catalog

All tools expose an MCP SDK 2.0 input_schema and a structured output envelope. New medical-reasoning tools return structured domain data; legacy RCA tools retain human-readable text and also expose it through structured content.

Evidence and Causation Safety

• Evidence provenance records document, location, collector, and timestamps.

• Evidence quality uses an Oxford CEBM-inspired strength/reliability model.

• Likelihood ratios and their rationale are retained in hypothesis history.

• A causal claim without explicit counterfactual or mechanism support is not marked fully verified.

• Finalized reports include a SHA-256 content hash.

• Generated paths are confined under ROOTCAUSE_DATA_DIR/exports.

Quality Gates

Verified locally on Windows with Python 3.12:

uv run pytest
uv run ruff check src tests
uv run mypy --no-incremental src/rootcause_mcp
uv run bandit -r src/rootcause_mcp -ll -q
uv run vulture src/rootcause_mcp --min-confidence 80

Current baseline:

• 48 tests passing

• 80% branch-aware coverage gate passing

• Ruff passing

• Strict mypy passing for 71 source files

• Bandit medium/high-severity scan passing

• No vulture findings at 80% confidence

Project Layout

src/rootcause_mcp/
├── domain/          # Entities, value objects, repository contracts, services
├── application/     # Case aggregate, orchestration, progress guidance
├── infrastructure/  # SQLModel repositories and safe export paths
├── interface/       # MCP tool schemas and handlers
└── server_v2.py     # Sole MCP SDK 2.0 entry point

Documentation

• Architecture

• Deep reasoning architecture

• MCP API reference

• Agent integration guide

• Existing solutions research

• Roadmap

• Changelog

Research and Attribution

The design references publicly available work including MEDDxAgent, ClinClaw, HFACS-MES, Oxford CEBM concepts, FHIR conventions, and the MCP Python SDK. See the research survey for licenses and design notes.

License

Apache License 2.0. See LICENSE.