π₯ AI-guided structured Root Cause Analysis for healthcare quality improvement
English | δΈζη
Enable AI Agents to guide clinical staff through structured, traceable, and learnable Root Cause Analysis.
RootCause MCP supports three categories of analysis models through Domain Cartridges:
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β RootCause MCP β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β βββββββββββββββ βββββββββββββββ βββββββββββββββ β
β β PROSPECTIVE β βRETROSPECTIVEβ β SYSTEMIC β β
β β Proactive β βInvestigationβ β Complexity β β
β βββββββββββββββ€ βββββββββββββββ€ βββββββββββββββ€ β
β β β’ HFMEA β β β’ HFACS β
β β β’ STAMP/STPAβ β
β β β’ HVA β β β’ 5-Whys β
β β β’ FRAM β β
β β β’ Bowtie β β β’ Fishboneβ
β β β’ AcciMap β β
β βββββββββββββββ βββββββββββββββ βββββββββββββββ β
β βΌ β
β βββββββββββββββββββββββββ β
β β Unified Graph API β β
β β (19 MCP Tools) β β
β βββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
| Feature | Description | Status |
|---|---|---|
| π Fishbone (6M) | Healthcare-specialized Ishikawa diagram | β 4 tools |
| π 5-Why Analysis | Deep cause exploration with Proximate/Ultimate classification | β 4 tools |
| π HFACS-MES | Human Factors Analysis auto-suggestion (5-level, 25 categories) | β 6 tools |
| β Causation Verify | Bradford Hill criteria-based verification | β 1 tool |
| π 6M-HFACS Mapping | Cross-reference between taxonomies | β 1 tool |
| πΎ Session Management | Persistent analysis sessions | β 4 tools |
- HFMEA - Healthcare Failure Mode and Effect Analysis
- HVA - Hazard Vulnerability Analysis
- Bowtie - Threat and consequence analysis
- STAMP/STPA - Control loop analysis
- FRAM - Functional Resonance Analysis Method
| Tool | Description |
|---|---|
rc_suggest_hfacs |
Auto-suggest HFACS codes from cause description |
rc_confirm_classification |
Confirm or override HFACS classification |
rc_get_hfacs_framework |
Get full HFACS-MES framework structure |
rc_list_learned_rules |
List learned classification rules |
rc_reload_rules |
Hot-reload YAML rules |
rc_get_6m_hfacs_mapping |
Get 6M-HFACS cross-reference table |
| Tool | Description |
|---|---|
rc_start_session |
Create new RCA session |
rc_get_session |
Get session details |
rc_list_sessions |
List all sessions |
rc_archive_session |
Archive completed session |
| Tool | Description |
|---|---|
rc_init_fishbone |
Initialize fishbone diagram |
rc_add_cause |
Add cause to 6M category |
rc_get_fishbone |
Get fishbone structure |
rc_export_fishbone |
Export as Mermaid/Markdown/JSON |
| Tool | Description |
|---|---|
rc_ask_why |
Progressive 5-Why questioning |
rc_get_why_tree |
Get Why tree structure |
rc_mark_root_cause |
Mark node as root cause |
rc_export_why_tree |
Export as Mermaid/Markdown/JSON |
| Tool | Description |
|---|---|
rc_verify_causation |
Verify causation with 4-criteria test |
# Install with uv (recommended)
uv pip install -e .
# Or development mode
uv pip install -e ".[dev]"
# Run MCP Server
python -m rootcause_mcp.interface.serverAdd to your .vscode/mcp.json:
{
"servers": {
"rootcause-mcp": {
"type": "stdio",
"command": "uv",
"args": ["run", "python", "-m", "rootcause_mcp.interface.server"],
"cwd": "${workspaceFolder}"
}
}
}rootcause-mcp/
βββ src/rootcause_mcp/
β βββ domain/ # Domain Layer (DDD)
β β βββ entities/ # Session, Cause, Fishbone, WhyNode
β β βββ value_objects/# HFACSCode, Scores, Identifiers
β β βββ repositories/ # Repository interfaces
β β βββ services/ # HFACSSuggester, CausationValidator
β βββ application/ # Application Layer
β β βββ session_progress_tracker.py
β β βββ guided_response_builder.py
β βββ infrastructure/ # Infrastructure Layer
β β βββ persistence/ # SQLite + SQLModel
β βββ interface/ # Interface Layer
β βββ tools/ # MCP Tool definitions
β βββ handlers/ # Tool handlers
β βββ server.py # MCP Server entry
βββ config/hfacs/ # YAML configurations
β βββ hfacs_mes.yaml # HFACS-MES framework
β βββ fishbone_6m.yaml # Healthcare 6M categories
β βββ keyword_rules.yaml# Classification rules
βββ tests/ # Test suites
βββ docs/ # Documentation
β βββ spec_v2.md # Full specification v2.5.0
βββ memory-bank/ # Project memory (for AI)
| MCP | Purpose | Integration |
|---|---|---|
| asset-aware-mcp | Data decomposition & table refactoring | Pre-processing |
| HHRAG MCP | Knowledge graph retrieval | Context enrichment |
| CGU MCP | Creative divergent thinking | Cause brainstorming |
- Full Specification - v2.5.0 (3700+ lines)
- Architecture - DDD layers
- Roadmap - Cartridge expansion plan
- Literature Review - HFACS-MES research
# Run tests
pytest tests/ -v
# Code linting
ruff check src tests
mypy src --strict
# Security scan
bandit -r src
# Dead code detection
vulture srcContributions welcome! Please see CONTRIBUTING.md.
Apache 2.0 License - See LICENSE
Made with β€οΈ for Healthcare Quality Improvement