🌉 HealthBridge MCP System

Cross-hospital patient safety intelligence powered by Model Context Protocol (MCP).

---

📖 Overview

HealthBridge is an intelligent healthcare orchestration system that exposes Model Context Protocol (MCP) tools and resources to detect patient safety issues across a distributed, multi-hospital network. By unifying patient histories, HealthBridge acts as a singular intelligence layer preventing drug interactions, allergy conflicts, and duplicated procedures when patients move between different healthcare facilities.

✨ Key Highlights

• Universal Patient Timeline: A centralized healthbridge://patients/{patient_id} MCP resource that aggregates visits, diagnoses, and prescriptions.
• Cross-Hospital Safety: Proactively detects buried drug conflicts and missed allergies from previous hospital visits.
• Intelligent Stock Routing: Checks medicine availability across facilities and automatically reroutes prescriptions or requests replenishments.
• Context-Aware Scheduling: Evaluates diagnosis severity to assign appropriate urgency tiers for follow-up appointments.

🚨 Problem Statement

Healthcare data is heavily siloed. When a patient visits multiple hospitals, clinics, or pharmacies, their medical history becomes fragmented. This fragmentation leads to:

• Adverse Drug Events (ADEs): Prescribing medications that interact dangerously with drugs prescribed at a different facility.
• Missed Allergies: Prescribing drugs a patient is allergic to because the allergy was recorded in another hospital's system.
• Resource Inefficiency: Ordering expensive duplicate tests (e.g., Lipid Panels, MRIs) simply because the previous results are inaccessible.
• Inventory Shortages: Pharmacies running out of stock without an automated fallback mechanism to nearby clinics.

💡 Our Solution

HealthBridge bridges these silos using the Model Context Protocol (MCP). Instead of relying on a centralized database that hospitals are reluctant to adopt, HealthBridge provides AI-driven agents with the tools to securely query cross-hospital histories, perform safety checks, and orchestrate inventory.

By exposing specialized MCP tools, HealthBridge empowers AI assistants to act as a universal safety net for healthcare providers.

---

🔄 Workflow

The typical workflow involves an AI agent utilizing HealthBridge tools during a patient encounter:

sequenceDiagram
    participant Doctor as Doctor (via AI Assistant)
    participant Agent as AI Agent
    participant HB as HealthBridge MCP
    
    Doctor->>Agent: "Prescribe Aspirin 100mg to PAT-001 at HOSP-B"
    
    rect rgb(30, 30, 30)
        Note over Agent,HB: 1. Safety Check Phase
        Agent->>HB: Call cross_hospital_safety_check(PAT-001, Aspirin)
        HB-->>Agent: ⚠️ HIGH RISK: Warfarin conflict (from HOSP-A)
    end
    
    Agent-->>Doctor: Warn about interaction. Doctor changes to safe alternative.
    
    rect rgb(30, 30, 30)
        Note over Agent,HB: 2. Inventory Phase
        Agent->>HB: Call medicine_availability_check(HOSP-B, SafeDrug)
        HB-->>Agent: 🔀 Rerouted to HOSP-C (In Stock)
    end
    
    rect rgb(30, 30, 30)
        Note over Agent,HB: 3. Logging & Follow-up Phase
        Agent->>HB: Call log_patient_visit(...)
        HB-->>Agent: Visit logged to global history
        Agent->>HB: Call followup_scheduler(PAT-001, severity)
        HB-->>Agent: 🟢 Routine follow-up scheduled (30 days)
    end
    
    Agent-->>Doctor: Prescription rerouted and visit logged successfully.

---

🏗️ Architecture

HealthBridge operates via an MCP server interacting with a static data layer, presenting a unified interface for AI clients and a visual widget.

graph TD
    Client[AI Client / Claude Desktop] -->|MCP Protocol| Server[HealthBridge FastMCP Server]
    Widget[Browser Widget] -->|HTTP/SSE| Server
    
    subgraph HealthBridge Core
        Server --> T1[log_patient_visit]
        Server --> T2[cross_hospital_safety_check]
        Server --> T3[medicine_availability_check]
        Server --> T4[followup_scheduler]
        Server --> R1[(Resource: patient_history)]
    end
    
    subgraph Data Layer
        T1 -.-> D1[patients.json]
        R1 -.-> D1
        T2 -.-> D2[drug_interactions.json]
        T3 -.-> D3[facility_stock.json]
        T2 -.-> D1
    end
    
    classDef tools fill:#2a4d69,stroke:#4b86b4,stroke-width:2px;
    classDef data fill:#1f2833,stroke:#66fcf1,stroke-width:2px;
    
    class T1,T2,T3,T4 tools;
    class D1,D2,D3 data;

---

🛠️ MCP Tools & Resources

Tools

Tool Name	Description
log_patient_visit	Records a new encounter into the shared patient history.
cross_hospital_safety_check	Detects drug interactions, allergy conflicts, and duplicate tests across all past visits.
medicine_availability_check	Checks stock, reroutes to nearby facilities if empty, or requests replenishment.
followup_scheduler	Assigns follow-up urgency tier with contextual escalation.

Resources

• healthbridge://patients/{patient_id}: Provides the full, cross-hospital timeline and aggregated allergy lists for a specific patient.

---

🚀 Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Run the MCP Server

# stdio mode (for standard MCP clients)
python server.py

# HTTP/SSE mode (for browser widget live wiring)
python server.py --http

3. Open the Dashboard Widget

The frontend widget allows you to visualize the timeline and tool orchestration.

start widget/index.html

(Ensure CONFIG.USE_MCP_API = true in app.js if running alongside the HTTP server)

4. Run Tests

Validate the system logic with the pytest suite:

python -m pytest tests/ -v

---

🧪 Demo Scenarios

HealthBridge comes with planted data (data/patients.json) to test various edge cases:

Scenario	Patient	Trigger	Expected Outcome
Buried Conflict	PAT-001 (Anil)	Prescribe aspirin	⚠️ Detects warfarin interaction from HOSP-A
Duplicate Test	PAT-003 (Priya)	View history	🔁 Identifies Lipid Panel at 2 hospitals within 8 days
Missed Allergy	PAT-005 (Ravi)	Prescribe amoxicillin	🚨 Flags penicillin cross-reactivity from 2024
Stock Reroute	Any at HOSP-B	Prescribe metformin	🔀 Reroutes to HOSP-C (Green Valley Clinic)
Out of Stock	Any	Prescribe atorvastatin	🔴 Out of Stock — Replenishment Requested
Urgent Care	PAT-007 (Meena)	severe AMI diagnosis	🔴 Urgent Follow-up — 3 days, doctor notified