---
title: MedGuard
emoji: 🏥
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 4.44.1
app_file: app.py
pinned: true
license: mit
short_description: AI Medication Safety with Multi-Agent MCP
tags:
  - healthcare
  - mcp
  - agents
  - drug-interactions
  - medication-safety
  - hackathon
  - pharmacogenomics
  - clinical-decision-support
  - langgraph
  - multi-agent
  - mcp-in-action-track-enterprise
  - building-mcp-track-enterprise
---

# 🏥 MedGuard – AI-Powered Medication Safety Platform

## Welcome to our submission for the Hugging Face GenAI Agents & MCP Hackathon!

This project showcases a **production-grade multi-agent system** powered by **LangGraph** and the **Model Context Protocol (MCP)**, designed to analyze medication safety, detect dangerous drug interactions, and provide clinical decision support.

🎬 **[Live Demo Video](https://www.loom.com/share/1b71f296ce10451f8de60a00c33d4d82)** | 🔗 **[GitHub Repository](https://github.com/SmartGridsML/mcp1stbirthday_hack)** | 🤖 **[Claude Desktop Integration](https://github.com/SmartGridsML/mcp1stbirthday_hack/blob/main/MCP_INTEGRATION.md)**

**[X POST](https://x.com/BilalS700/status/1995189560008151331?s=20)**
---

## 🏆 Hackathon Tracks

| Track | Target | Status |
|-------|--------|--------|
| **Track 1: Building MCP** | $10,000 | ✅ 10 MCP Tools + 3 Resources |
| **Track 2: Consumer Use** | $10,000 | ✅ Claude Desktop Integration |
| **Track 3: Agentic Use** | $10,000 | ✅ Multi-Agent LangGraph System |
| **Blaxel Choice Award** | $2,500 | ✅ Full Blaxel Platform Integration |

---

## 🚨 Why This Matters: The Problem We're Solving

<table>
<tr>
<td width="50%">

### 💀 The Reality of Medication Errors

- **7,000-9,000** Americans die annually from medication errors
- **$42 billion** spent annually on preventable adverse drug events
- **1.5 million** patients harmed yearly by medication errors
- **Polypharmacy** (5+ medications) affects 40% of seniors
- **Drug interactions** cause 125,000+ deaths annually in the US

</td>
<td width="50%">

### ✅ How MedGuard Helps

- **Real-time DDI detection** from 25+ curated interactions
- **Pharmacogenomic analysis** for personalized dosing
- **Beers Criteria** screening for elderly patients
- **Clinical guideline compliance** (AHA/ACC/ADA)
- **Cost optimization** with generic alternatives

</td>
</tr>
</table>

---

## 🌐 Project Overview

MedGuard leverages **5 autonomous AI agents** that collaborate to perform comprehensive medication safety analysis:

| Agent | Role | Key Features |
|-------|------|--------------|
| 🔍 **Drug Interaction Agent** | Analyzes DDIs using knowledge graphs | CYP enzyme conflicts, PubMed enhancement, severity scoring |
| 👤 **Personalization Agent** | Patient-specific adjustments | Renal/hepatic dosing, pharmacogenomics, Beers Criteria |
| 📋 **Guideline Agent** | Clinical compliance checking | AHA/ACC, ADA, ESC guidelines with evidence levels |
| 💰 **Cost Agent** | Formulary optimization | Generic substitutions, therapeutic alternatives |
| 📝 **Explanation Agent** | Synthesis and communication | Prioritized recommendations, patient-friendly summaries |

---

## 🔄 LangGraph Orchestration Architecture

```
┌────────────────────────────────────────────────────────────────────────────┐
│                     MedGuard Multi-Agent Orchestrator                       │
│                                                                            │
│   START                                                                    │
│     │                                                                      │
│     ▼                                                                      │
│   ┌─────────────────────────────┐                                          │
│   │  Drug Interaction Agent     │◄── Entry point (always runs first)       │
│   │  • 25+ known DDIs           │                                          │
│   │  • CYP enzyme analysis      │                                          │
│   │  • ML severity prediction   │                                          │
│   └───────────┬─────────────────┘                                          │
│               │                                                            │
│               ▼                                                            │
│   ┌─────────────────────────────┐                                          │
│   │   CONDITIONAL ROUTER        │◄── Severity-based intelligent routing    │
│   │   Based on risk level       │                                          │
│   └───────────┬─────────────────┘                                          │
│               │                                                            │
│    ┌──────────┼──────────┐                                                 │
│    │          │          │                                                 │
│    ▼          ▼          ▼                                                 │
│ "critical" "parallel" "low_risk"                                           │
│    │          │          │                                                 │
│    ▼          │          │                                                 │
│ ┌────────┐    │          │                                                 │
│ │ Human  │    │          │                                                 │
│ │ Review │    │          │                                                 │
│ │ FLAG   │    │          │                                                 │
│ └───┬────┘    │          │                                                 │
│     │    ┌────┴────┐     │                                                 │
│     │    │Parallel │     │                                                 │
│     │    │Execution│     │                                                 │
│     │    └────┬────┘     │                                                 │
│     ▼         ▼          ▼                                                 │
│   ┌─────────────────────────────┐                                          │
│   │ Personalization Agent       │                                          │
│   │ Guideline Compliance Agent  │◄── Run in parallel for efficiency        │
│   │ Cost Optimization Agent     │                                          │
│   └───────────┬─────────────────┘                                          │
│               │                                                            │
│               ▼                                                            │
│   ┌─────────────────────────────┐                                          │
│   │    Explanation Agent        │◄── Final synthesis & prioritization      │
│   │    • Safety score (0-100)   │                                          │
│   │    • Prioritized actions    │                                          │
│   │    • Patient-friendly text  │                                          │
│   └───────────┬─────────────────┘                                          │
│               │                                                            │
│               ▼                                                            │
│             END                                                            │
└────────────────────────────────────────────────────────────────────────────┘
```

---

## 🛠️ MCP Server Integration (10 Tools + 3 Resources)

### MCP Tools

| # | Tool | Description | Parameters |
|---|------|-------------|------------|
| 1 | `analyze_medication_safety` | Full 5-agent pipeline | `patient_id`, `query` |
| 2 | `check_drug_interactions` | DDI detection via Neo4j | `medications[]`, `allergies[]` |
| 3 | `get_personalized_dosing` | Patient-specific dosing | `patient_id`, `medication`, `indication` |
| 4 | `check_guideline_compliance` | Clinical guideline check | `patient_id`, `condition` |
| 5 | `optimize_medication_costs` | Generic alternatives | `medications[]`, `insurance_type` |
| 6 | `get_patient_profile` | Demographics & history | `patient_id` |
| 7 | `search_clinical_guidelines` | BioBERT vector search | `query`, `limit` |
| 8 | `explain_medication_decision` | Patient-friendly text | `analysis`, `reading_level` |
| 9 | `search_pubmed_literature` | PubMed via MCP Search | `query`, `study_types[]` |
| 10 | `search_fda_safety_alerts` | FDA alerts via MCP Search | `drug_name`, `years` |

### MCP Resources

| URI | Description |
|-----|-------------|
| `guidelines://clinical-practice` | Clinical practice guidelines database |
| `database://drug-interactions` | Drug interaction knowledge graph |
| `alerts://fda-safety` | FDA safety communications |

---

## 🗂️ Data Sources & Medical Knowledge Bases

Our platform uses **real, authoritative, evidence-based medical data sources**:

### 1. 💊 DrugBank – Drug Interaction Database

- **Purpose**: Curated drug-drug interactions with mechanisms and management
- **Coverage**: 25+ high-risk interaction pairs (expandable to 3,000+)
- **Data**: Severity, mechanism, clinical effect, management strategy, evidence level
- **Usage**: Core DDI detection for all medication safety analysis

### 2. 🧬 Pharmacogenomics Database (PharmGKB)

- **Purpose**: Genetic variants affecting drug metabolism
- **Enzymes Covered**: CYP2D6, CYP2C9, CYP2C19, CYP3A4, CYP1A2
- **Phenotypes**: Poor metabolizer, intermediate, normal, ultrarapid
- **Usage**: Personalized dosing recommendations based on genetic markers

### 3. 👴 AGS Beers Criteria (2023)

- **Purpose**: Potentially inappropriate medications in older adults
- **Coverage**: 30+ medication classes to avoid in elderly
- **Source**: American Geriatrics Society
- **Usage**: Automatic flagging for patients ≥65 years

### 4. 📋 Clinical Practice Guidelines

| Organization | Guidelines Included |
|--------------|---------------------|
| **AHA/ACC** | Heart Failure, AFib, CAD, Hypertension |
| **ADA** | Type 2 Diabetes Standards of Care 2024 |
| **ESC** | European cardiovascular guidelines |
| **KDIGO** | Chronic Kidney Disease 2024 |

### 5. 🔬 PubMed/MEDLINE (via MCP Search)

- **Purpose**: Literature search for clinical evidence
- **API**: MCP Search protocol integration
- **Usage**: Enhance recommendations with recent research citations

### 6. ⚠️ FDA Safety Communications

- **Purpose**: Drug safety alerts, recalls, black box warnings
- **API**: MCP Search protocol integration
- **Usage**: Real-time safety alert checking

---

## 📦 Technology Stack

| Layer | Technology | Purpose |
|-------|------------|---------|
| **MCP Server** | Python `mcp` SDK | 10 tools, 3 resources, stdio transport |
| **Orchestration** | LangGraph StateGraph | Conditional routing, parallel execution |
| **LLM** | Claude 4 Sonnet / GPT-4o / Gemini 2.0 | Medical analysis, synthesis |
| **Knowledge Graph** | Neo4j | Drug interaction network |
| **Vector Search** | Qdrant + BioBERT | Semantic guideline search |
| **API** | FastAPI | REST endpoints, HIPAA audit logging |
| **Frontend** | Gradio | Interactive demo UI |
| **Databases** | PostgreSQL, Redis | Patient data, session management |
| **Cloud** | Blaxel Platform | Serverless deployment, observability |

---

## 🧩 Core Components

### 🔍 Drug Interaction Agent (`drug_interaction_agent_enhanced.py`)

- **Role**: Primary safety analysis entry point
- **Capabilities**:
  - Known interaction database lookup (DrugBank)
  - CYP enzyme metabolic conflict detection
  - ML-based novel interaction prediction
  - PubMed literature enhancement
  - Severity classification (minor → moderate → major → critical)

### 👤 Personalization Agent (`personalization_agent.py`)

- **Role**: Patient-specific safety adjustments
- **Capabilities**:
  - Renal dose adjustments (eGFR-based)
  - Hepatic impairment considerations
  - Pharmacogenomic analysis (CYP variants)
  - Beers Criteria screening (age ≥65)
  - Polypharmacy detection (5+/10+ meds)

### 📋 Guideline Compliance Agent (`guideline_compliance_agent.py`)

- **Role**: Evidence-based standard verification
- **Capabilities**:
  - Condition-specific therapy checks
  - Missing therapy identification
  - Guideline citation with evidence levels
  - Therapeutic class mapping

### 💰 Cost Optimization Agent (`cost_optimization_agent.py`)

- **Role**: Formulary and cost efficiency
- **Capabilities**:
  - Brand → generic substitution
  - Therapeutic class alternatives
  - Insurance formulary optimization
  - Annual savings calculation

### 📝 Explanation Agent (`explanation_agent.py`)

- **Role**: Clinical synthesis and communication
- **Capabilities**:
  - Safety score calculation (0-100)
  - Prioritized recommendation list
  - Executive summary for clinicians
  - Patient-friendly explanations (adjustable reading level)

---

## 🧑‍⚕️ Demo Patients

| ID | Patient | Age | Key Demonstration |
|----|---------|-----|-------------------|
| **P001** | John Smith | 67 | Warfarin + Aspirin (major bleeding risk), CKD Stage 3, CYP2C9*3 |
| **P002** | Maria Garcia | 45 | Sertraline + Tramadol (serotonin syndrome risk) |
| **P003** | Robert Chen | 72 | 8 medications, hyperkalemia risk, HF + COPD + CKD |
| **P004** | Sarah Johnson | 55 | Simvastatin + Amlodipine (CYP3A4 interaction, myopathy risk) |
| **P005** | James Wilson | 78 | 6 Beers Criteria violations, CYP2D6 poor metabolizer |

---

## 🚀 Deployment Options

### Option 1: Hugging Face Spaces (This Demo)
```bash
# Already deployed! Just use the Gradio interface above
```

### Option 2: Claude Desktop Integration
```json
{
  "mcpServers": {
    "healthcare-multi-agent": {
      "command": "python",
      "args": ["-m", "src.mcp.healthcare_mcp_server"],
      "cwd": "/path/to/mcp1stbirthday_hack"
    }
  }
}
```

### Option 3: Blaxel Platform
```bash
cd my-agent && bl deploy
bl run agent healthcare-multi-agent-system --data '{"inputs": "Analyze patient P001"}'
```

### Option 4: Docker Compose
```bash
docker-compose up -d
# API: http://localhost:8000
# UI: http://localhost:7860
```

---

## 📊 Example Analysis Output

```
🏥 MedGuard Analysis Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Patient: John Smith (P001) | Age: 67 | Medications: 4

⚠️ SAFETY SCORE: 55/100 (MODERATE RISK)
⚠️ REQUIRES CLINICAL REVIEW

━━━ CRITICAL FINDINGS ━━━

🔴 MAJOR DRUG INTERACTION: Warfarin + Aspirin
   Mechanism: Additive antiplatelet/anticoagulant effects
   Effect: Significantly increased bleeding risk (GI, intracranial)
   Management: Monitor INR closely, add PPI, use 81mg aspirin only
   Evidence: Established (PMID: 27432982)

🟠 RENAL ADJUSTMENT NEEDED: Metformin
   eGFR: 58 mL/min (threshold: 30)
   Action: Monitor renal function; avoid if eGFR <30

🟠 PHARMACOGENOMIC ALERT: Warfarin + CYP2C9*3
   Phenotype: Intermediate metabolizer
   Action: May require 20-30% lower warfarin dose

━━━ RECOMMENDATIONS ━━━

1. [CRITICAL] Review warfarin + aspirin combination
2. [HIGH] Add PPI for gastroprotection
3. [MODERATE] Consider CYP2C9 genotype-guided dosing
4. [LOW] Generic substitution available: Save $285/month
```

---

## 🧑‍💻 Authors

**MedGuard Team** – MCP 1st Birthday Hackathon Submission

- Built with ❤️ for patient safety
- Leveraging state-of-the-art AI agent orchestration
- Production-ready architecture for healthcare applications

---

## 📝 License

This project is licensed under the **MIT License** – see [LICENSE](LICENSE) for details.

---

## 🙏 Acknowledgments

- **Anthropic** for Claude and the MCP protocol
- **Hugging Face** for hosting and the hackathon
- **Blaxel** for serverless AI infrastructure
- **DrugBank**, **PharmGKB**, **AGS**, **AHA/ACC/ADA** for medical knowledge
- The healthcare AI community for inspiration

---

<p align="center">
  <b>Built for the MCP 1st Birthday Hackathon</b><br>
  <i>Making medication safety accessible through AI agents</i><br>
  🏥 💊 🤖 🔬 💚
</p>