| | --- |
| | 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> |
| |
|
