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. Inventory and extract de-identified clinical documents through the host agent.

2. Register source-grounded evidence with exact raw snippets, preserve source-faithful time, and append authorized source/de-identification/independence reviews.

3. Build the maximum reasonable mechanism-based differential for the phenotype and time course, explicitly select the working lead, then relate source-linked evidence using direct likelihood ratios only when a separate verified literature record establishes the quantitative calibration.

4. Treat unknowns as reasoning inputs and record each candidate's rationale, support/refutation/neutral evidence, discriminator, qualitative certainty, and bias.

5. Connect diagnostic reasoning to Fishbone and 5-Why, obtain an authorized HFACS-MES disposition for every cause, and run a conservative causation proof-obligation audit.

6. Produce a typed, machine-readable report with explicit source lineage and deterministic conformance results.

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.

For clinician-facing output, the built-in Markdown renderer supports Traditional Chinese explanatory prose while preserving canonical diagnosis, test, drug, device, and procedure names in English. Exact source quotations, units, IDs, codes, JSON/FHIR values, and custom-template language are never machine-translated.

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

MVP Status

The deterministic final-report boundary is implemented: nested report sections are typed, every report carries machine-readable conformance_checks[], and unsafe finalization is blocked for source, DDx, root-lineage, causation-disposition, reviewer, or integrity failures. Final snapshots carry a reviewer, timezone-aware time, recomputable SHA-256 hash, and recursively reject mutation.

DDx breadth is now explicit rather than inferred from a count: the Agent selects a syndrome-appropriate framework, reviews every canonical cell, and persists a PRIMARY breadth audit. REVIEWED_INSUFFICIENT_DATA retains unknowns and typed discriminators; NOT_ASSESSED blocks finalization. The audit establishes documented coverage, not clinical correctness.

Final conformance also carries the complete append-only source-review ledger and recomputes its final inventory projection, independence lineage, explicit leading-diagnosis selection, source-calibrated LR links, source-faithful temporal semantics, per-cause HFACS review, guidance/readiness facts, gap counts, and Why/root/causation lineage. Date, range, relative, and unknown time may remain in a valid final artifact but cannot be silently sorted or used to establish temporality.

Release 2.0.0a3 (2026-08-19) is still an engineering alpha, not a clinically validated Agent MVP. The public six-case corpus and runner are engineering references. A formal result requires at least 3 real Agent runtimes × 6 cases × 2 repeats, repository-external private case bundles, separately protected private holdout gold, filesystem isolation, trusted runtime/server MCP traces, and two blinded qualified clinical reviewers per job with adjudication of disagreement. That evaluation is currently AGENT_EVAL_NOT_ESTABLISHED. See MVP conformance and evaluation.

Why This Harness Saves Work

A general Agent can read every document and write a report in one long prompt. That approach works, but repeatedly spends context on tool schemas, prior facts, formatting, probability arithmetic, graph construction, completeness checks, and report prose. RootCause MCP moves those repeatable operations into deterministic code while leaving clinical judgment with the Agent.

Tokenizer-independent regression fixtures compare tool-profile schema bytes, duplicated text fallbacks, and deterministic report generation. Use the current CI artifacts as the source of truth because schema changes alter those measurements. These byte proxies are not promises about a specific model tokenizer. The Agent still must read the source extracts, generate clinically plausible hypotheses, choose defensible evidence relationships, and review the final artifact. A non-neutral LR requires a distinct verified LITERATURE calibration record. No uncalibrated prior/posterior may be presented as clinical probability or certainty; LR=1.0 means neutral/quantitatively unknown and does not count as support or refutation.

Multi-Loop Guidance for Lightweight (Flash) Models

Lightweight or fast models (such as Flash/mini variants) commonly struggle with complex clinical cases: they tend to jump to conclusions, stop after a single hypothesis (premature closure), neglect disconfirming tests, and skip cognitive reflections.

RootCause MCP acts as an active Reasoning State Machine:

• Every core tool call returns a structured guidance payload evaluating the case state.

• Stage Progression: Automatically tracks progress through EVIDENCE_COLLECTION → DIFFERENTIAL_EXPANSION → BAYESIAN_EVALUATION → COGNITIVE_AUDIT → READY_FOR_SYNTHESIS.

• Readiness Checklist: Requires verified source content, typed candidate labels, at least three unique diagnoses across two non-UNKNOWN mechanisms, an applicable must-not-miss diagnosis, evidence/test disposition for every active diagnosis, support plus contradiction or a typed rule-out plan for leading/must-not-miss diagnoses, and explicit uncertainty/bias review. These are deterministic finalization floors, not a clinical breadth target or cap.

• Next Prompt Directives: Provides explicit next_recommended_actions with exact tool names and Socratic push_questions in each response, allowing Flash agents to loop iteratively until the case is complete.

• Audit Tools: Agents or external orchestrators can call rc_audit_differential_breadth to persist every-cell framework coverage and rc_audit_reasoning_state to inspect remaining prerequisites before report generation.

Deterministic Provenance and Data Lineage

Inspired by data integration and ETL lineage architectures (such as Airbyte's stream/source verification models), RootCause MCP establishes deterministic, cryptographic evidence grounding without relying on probabilistic LLM memory:

• Verbatim Snippets & Lineage Anchors: Evidence records capture exact raw_snippet quotes, file paths, line locators, and SHA-256 digests.

• Deterministic Provenance Verification: The ProvenanceVerifier domain service scans physical raw files on disk (TXT, CSV, HL7, XML) to verify substring matches and line numbers without invoking an LLM.

• Tamper & Hallucination Detection: If an agent invents a quote, references an unavailable source, or presents a source whose bytes no longer match the pinned manifest, the server keeps the evidence unverified and returns audit diagnostics.

• Append-only Source Review: The pinned manifest and digest never change. Extraction, de-identification, and independent/derived lineage advance only through rc_adjudicate_source; every final source needs an allowlisted reviewer, time, reason, and stable adjudication ID.

• Clean Architecture Boundary: RootCause MCP focuses on reasoning contracts and provenance checks; it does not parse raw PDF, DOCX, image, scan, spreadsheet, or EHR-export batches.

The host agent or an approved extractor must produce citation-ready text/cells while preserving exact content, source locations, hashes, units, negation, time precision, OCR corrections, and extraction method. Send only structured atomic findings into RootCause MCP, and do not claim MCP verification for binary or inaccessible sources.

Protocol Resources, Templates & 4-Tier Anesthesia M&M Reasoning

The packaged YAML protocols and domain playbooks are versioned, non-normative retrospective DDx resources that the bundled agent harness tells agents to read. Markdown templates are deterministic rendering inputs. Runtime readiness thresholds and gap rules are still implemented in Python; editing a protocol YAML alone does not change those gates. These playbooks prompt retrospective mechanism review only; they do not provide active-care management, treatment/rescue instructions, or patient-specific dosing.

• Configurable SOP & Domain Playbooks (config/protocols/, config/domains/):

  • anesthesia_mm_rca_protocol.yaml: 4-Tier backward causal framework (Tier 0 Terminal Rhythm → Tier 1 ACLS 5H5T → Tier 2 Tri-stream Triggers [Patient baseline vs Surgical insult vs Anesthesia pharmacology] → Tier 3 HFACS Latent System Gaps).

  • perioperative_shock.yaml & toxicology_sedation.yaml: Non-normative retrospective DDx prompts for considering Dynamic LVOT Obstruction (SAM) and Propofol Infusion Syndrome (PRIS), not active-care protocols.

• Customizable Markdown Templates (config/templates/):

  • anesthesia_mm_rca_report_template.md: Specialized departmental M&M conference review format with deterministic slot filling.

  • clinical_reasoning_report_template.md: General clinical reasoning and patient safety action report.

Architecture

graph TB
    A[General-purpose AI Agent] -->|MCP SDK 2.0| T[8 facade or 25 / 24 / 46 discrete tools]
    D[Clinical documents] --> A

    subgraph Harness
        T --> S[ServerState / case aggregate]
        S --> O[ClinicalReasoningOrchestrator]
        O --> E[Evidence + provenance + hash]
        O --> H[Hypotheses + Bayesian updates]
        O --> R[ReasoningChain]
        O --> G[Clinical Guidance Engine]
        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]
    CR --> M[Deterministic Markdown]

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

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, source manifests, Fishbone diagrams, and Why Trees

Authentication, encryption-at-rest, tenant isolation, reviewer-role authorization, database migrations, and regulated deployment controls must be supplied by the deployment environment before clinical production use. See the PHI and clinical-data policy.

Quick Start & Automated Installation

🚀 One-Click Automated Setup

You can automatically detect uv, synchronize virtual environments, configure client MCP harnesses (Copilot-native .mcp.json, VS Code .vscode/mcp.json, Claude Desktop, and Cline), and run a production stdio diagnostic with a single command:

Windows PowerShell:

powershell -ExecutionPolicy Bypass -File scripts/setup.ps1

Linux / macOS / WSL:

chmod +x scripts/setup.sh
./scripts/setup.sh

The MCP command runs on the Agent or extension host that starts the server. If VS Code uses WSL, SSH, a Dev Container, or another remote host, install uv and run scripts/setup.sh in that remote integrated terminal. Running setup.ps1 on local Windows does not install uv on the remote host. Run Developer: Reload Window after setup.

Universal Python CLI:

uv run --locked python scripts/install.py --profile all --target all
uv run --locked python scripts/mcp_doctor.py --config all

🔬 Scripted Synthetic Case Regression

Run the six bundled synthetic scenarios (SAM, PRIS, transfusion hyperkalemia, post-operative PE, LVAD suction, and delayed diagnosis). This script is a developer regression/demo, not a substitute for the native manifest/finalization acceptance tests or clinical validation:

uv run python scripts/run_case_trial.py --case all

Agent Evaluation Scaffold

The public corpus dry-run checks runner/artifact mechanics only and deliberately returns AGENT_EVAL_NOT_ESTABLISHED:

eval_output="$(mktemp -d)"
uv run python scripts/run_agent_eval.py dry-run \
  --output-root "$eval_output" \
  --repeats 2

Formal runs must use repository-external private cases and separately protected private gold. Start with the fail-closed preflight:

uv run python scripts/run_agent_eval.py \
  --preflight \
  --matrix /secure/adapter-matrix.json \
  --corpus-file /secure/private-corpus/corpus.json \
  --gold-dir /secure/private-holdout \
  --attest-holdout-isolation \
  --authorize-provider-egress

See the evaluation protocol before any formal run. Egress authorization applies only to approved de-identified synthetic inputs, never real clinical records or PHI.

🛠️ Manual Installation & Server Launch

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

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

Copilot CLI and Agent Host read .mcp.json at the repository root directly:

{
  "mcpServers": {
    "rootcauseMcp": {
      "type": "local",
      "command": "uv",
      "args": ["run", "--locked", "rootcause-mcp"],
      "cwd": ".",
      "env": {
        "ROOTCAUSE_TOOL_PROFILE": "all",
        "ROOTCAUSE_RESPONSE_MODE": "compact"
      },
      "tools": ["*"]
    }
  }
}

The VS Code editor uses .vscode/mcp.json and forwards it to the active Agent Host:

{
  "servers": {
    "rootcauseMcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--locked",
        "--directory",
        "${workspaceFolder}",
        "rootcause-mcp"
      ],
      "cwd": "${workspaceFolder}",
      "env": {
        "ROOTCAUSE_TOOL_PROFILE": "all",
        "ROOTCAUSE_RESPONSE_MODE": "compact"
      }
    }
  }
}

Both files intentionally use the same rootcauseMcp server key so Agent Host does not create two MCP identities. Shared configuration uses the PATH-resolved uv name only. Never commit C:\...\uv.exe, ROOTCAUSE_DATA_DIR, or ROOTCAUSE_AUTHORIZED_REVIEWERS; provide protected runtime values in the host environment. Put unrelated MCP servers in VS Code user or remote-user config instead of committing personal executable and data paths to this repository.

Copilot Remote spawn ... uv.EXE ENOENT

This means the execution host cannot find the configured executable. In a WSL, SSH, or container Remote extension host, a common cause is forwarding a local Windows absolute path. In the VS Code remote terminal, run:

uv --version
uv sync --locked --all-extras
uv run --locked python scripts/install.py --profile all --target all \
  --skip-tests --skip-trial
uv run --locked python scripts/mcp_doctor.py --config all

The doctor should report PASS for both configs and their stdio handshakes. Then run Developer: Reload Window, restart rootcauseMcp from MCP: List Servers, and use MCP: Reset Cached Tools after a tool-catalog update. See the official VS Code MCP configuration reference and GitHub Copilot CLI MCP configuration.

Environment variables:

Agent Workflow

A compatible agent can use either the discrete tool workflow or the ultra-compact 8-facade workflow:

Discrete Tool Workflow

rc_start_session(source_manifest={...})
  -> rc_add_evidence(temporal={kind=..., raw_value=...})
  -> rc_adjudicate_source  # each manifest source; authorized append-only review
  -> rc_think_aloud / rc_identify_gaps / rc_challenge_assumption
  -> rc_propose_hypothesis(planned_tests=[...])
  -> rc_audit_differential_breadth(audit={...})
  -> rc_link_evidence_to_hypothesis(calibration_status=...,
                                     calibration_source_ref=...)
  -> rc_select_leading_hypothesis(reason=..., changed_by=...)
  -> rc_get_differential_diagnosis
  -> rc_get_reasoning_chain
  -> rc_detect_conflicts
  -> rc_create_checkpoint
  -> rc_init_fishbone / rc_add_cause / rc_confirm_classification
  -> rc_ask_why / rc_mark_root_cause
  -> rc_verify_causation  # conservative audit, not clinical causal proof
  -> rc_generate_contract_report(format="markdown", detail_level="standard",
                                  locale="zh-TW", audience="clinician", finalize=false)

Ultra-Compact Facade Workflow (8 Tools Profile)

rc_rca(action="session_start")
  -> rc_evidence(action="add")
  -> rc_rca(action="session_adjudicate_source")
  -> rc_thinking(action="think" / "gap" / "challenge" / "reflect")
  -> rc_hypothesis(action="propose" / "audit_breadth" / "link" / "select_leading" / "rank")
  -> rc_audit(action="stage_guidance" / "detect_conflicts")
  -> rc_checkpoint(action="create")
  -> rc_diagram(action="timeline" / "validate")
  -> rc_report(action="preview")

rc_propose_hypothesis (or rc_hypothesis(action="propose")) records mechanism_category, diagnostic_role, reasoning_basis, qualitative certainty, clinical rationale, alternatives, candidate-specific unknowns, and typed planned tests. Build the maximum reasonable distinct mechanisms; three diagnoses are a finalization floor, not the reasoning target or cap. These are explicit agent-authored records, not a dump of hidden model reasoning.

With the built-in renderer, locale="zh-TW" and audience="clinician" produce Traditional Chinese discussion with English canonical medical names and an expanded candidate-level evidence/unknown/test view. Custom templates retain their authored language; JSON and FHIR data are not translated.

See Agent Integration Guide for payload examples.

MCP SDK 2.0 Advanced Features

RootCause MCP leverages the full spectrum of MCP SDK 2.0 primitives to deliver maximum agent ergonomics:

1. 🧰 Tool Condensation (8 Unified Facade Tools)

When using ROOTCAUSE_TOOL_PROFILE=condensed, the advertised surface is consolidated into 8 polymorphic facade tools, reducing discovery/schema overhead. A few administrative operations remain discrete-only; the bundled harness lists the exact mapping and hands the same session to an appropriate profile instead of silently skipping them:

• rc_evidence: Add, get, or verify physical provenance.

• rc_hypothesis: Propose candidates, audit framework breadth, link evidence, explicitly select the lead, inspect, or exclude.

• rc_thinking: Record clinical rationale, reflect on cognitive bias, identify gaps, or challenge assumptions.

• rc_audit: Query multi-loop guidance, audit reasoning completeness, or detect contradictions/omissions.

• rc_report: Generate deterministic contract reports or export audit artifacts.

• rc_diagram: Render chronological event timelines, audit Mermaid syntax, or export graphs.

• rc_checkpoint: Create, list, or restore integrity-checked case state snapshots.

• rc_rca: Route session/source review plus traditional Fishbone (6M), 5-Why, and HFACS-MES workflows.

2. 📚 MCP Static & Dynamic Resources

Inspect domain knowledge and case states with 0 tool call overhead:

• Static Protocol & Template URIs (19 resources in the 2.0.0a3 snapshot):

  • clinical://contracts/case-input-manifest: canonical multi-source handoff schema.

  • clinical://contracts/case-analysis-report: canonical standardized output schema.

  • clinical://protocols/anesthesia-mm-rca-protocol: 4-Tier backward causal reasoning SOP.

  • clinical://protocols/clinical-reasoning-sop: Core diagnostic investigation playbook.

  • clinical://protocols/non-death-adverse-event-protocol: Near-miss and adverse-event barrier-analysis protocol.

  • clinical://protocols/timeline-patterns: Source-faithful temporal-pattern definitions.

  • clinical://templates/anesthesia-mm-rca-report-template: Markdown report template.

  • clinical://templates/clinical-reasoning-report-template: General clinical reasoning report template.

  • clinical://templates/clinician-ddx-discussion-zh-tw: Clinician-facing Traditional Chinese DDx discussion template.

  • clinical://templates/near-miss-adverse-event-rca-template: Swiss Cheese & barrier failure template.

  • clinical://domains/*: 9 non-normative retrospective DDx playbooks: anaphylaxis-crisis, anesthesia-perioperative-arrest, delayed-diagnosis-systems, difficult-airway-crisis, local-anesthetic-toxicity, lvad-mechanical-crisis, pediatric-opioid, perioperative-shock, and toxicology-sedation.

• Dynamic Case Resource Templates (4 in the 2.0.0a3 snapshot):

  • clinical://sessions/{session_id}/report: Current rendered case report.

  • clinical://sessions/{session_id}/timeline: Current chronological event timeline.

  • clinical://sessions/{session_id}/guidance: Live reasoning stage, checklist, and Socratic push questions.

  • clinical://sessions/{session_id}/conflicts: Live contradiction, paradox, and omission audit.

3. 🎯 MCP Pre-Configured Clinical Prompts (5)

Launch standardized clinical investigation workflows with one click in Claude Desktop, VS Code, or Cline:

• anesthesia_mm_investigation: 4-Tier Backward Anesthesia M&M investigation.

• perioperative_crisis_differential: Crisis differential expansion with 5H5T triage.

• near_miss_barrier_analysis: Swiss Cheese non-death adverse event barrier RCA.

• delayed_diagnosis_investigation: Diagnostic trajectory and cognitive bias investigation.

• clinician_ddx_discussion_zh_tw: General clinician-facing Traditional Chinese DDx discussion with maximum reasonable mechanism breadth, explicit unknowns, source-linked support/refutation/neutral evidence, discriminating tests, and qualitative certainty.

4. 🧠 Server-Level Instructions & Meta-Prompt

The server automatically supplies system-level meta-instructions during the MCP handshake, anchoring AI agents to rigorous source grounding, 4-tier backward causal reasoning, disconfirming hypothesis testing, and cognitive bias transparency.

Tool Catalog

Visualization Outputs

Quality Gates

The repository and CI define these engineering gates:

uv run pytest -W error::ResourceWarning
uv run ruff check .
uv run ruff format --check .
uv run mypy src --ignore-missing-imports
uv run bandit -c pyproject.toml -r src --severity-level low --confidence-level medium
uv run vulture src tests --min-confidence 80
uv export --frozen --no-dev --no-emit-project --no-hashes --quiet --output-file requirements-audit.txt
uvx --from "pip-audit==2.9.0" pip-audit --strict --requirement requirements-audit.txt
uv build
uvx --from "twine==6.2.0" twine check dist/*

Use the current CI run and release artifacts as the source of truth for test counts, coverage, security findings, and packaging results. These engineering gates validate software behavior; they do not establish Agent clinical performance or clinical validity.

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

• Bilingual documentation website

• Architecture

• Deep reasoning architecture

• MCP API reference

• Agent integration guide

• MVP conformance and Agent evaluation

• RootCause agent harness

• PHI and clinical-data policy

• Existing solutions research

• GitHub landscape: per-repository learning and citation reports

• Roadmap

• Changelog

Research and Attribution

The design references publicly available clinical-reasoning, RCA, FHIR, provenance, causal-inference, and Agent-evaluation work. The dated research survey states the product boundary; the per-repository reports record what can be learned, how a foundation package should be integrated and cited, and which license or data-use constraints prohibit direct reuse.

License

Apache License 2.0. See LICENSE.