MedExplainer Pro - AI Diagnostic Agent for Medical Reports

AI-powered lab report explainer using MCP + FHIR. Converts raw test values into risk scores, clinical insights & recommended actions — with LLM reasoning.

Comment

Inspiration

Every day, millions of patients receive lab reports they simply don't understand. A Hemoglobin of 10.2 g/dL. A Glucose of 180 mg/dL. Numbers with no story attached.

Most people leave the clinic confused, anxious, and waiting days for a doctor to "explain the results." In underserved communities, that explanation never comes at all.

We believed AI could close that gap — not by replacing doctors, but by giving patients and care teams a clear, structured, plain-language bridge between raw data and human understanding.

That belief became MedExplainer Pro MCP.

What it does

MedExplainer Pro is a clinical lab explanation engine powered by MCP (Model Context Protocol) and aligned to FHIR R4 healthcare standards.

It accepts:

  • 📄 Plain-text lab reports — paste raw text like "Glucose: 180 mg/dL (High)"
  • 🗂️ Structured patient JSON — send demographics + observations as a payload
  • 🏥 Real FHIR resources — Bundle, Patient, and Observation resources from live EHR systems

And returns a fully structured health intelligence report:

{
  "health_risk_score": 62,
  "risk_level": "HIGH",
  "trend_analysis": "Glucose trending upward across 3 visits. Hemoglobin declining.",
  "clinical_insight": "Elevated glucose combined with low hemoglobin suggests 
   possible uncontrolled diabetes with concurrent anemia.",
  "recommended_actions": [
    "Schedule follow-up within 7 days.",
    "Repeat CBC and fasting glucose.",
    "Evaluate for iron-deficiency anemia."
  ],
  "reasoning_mode": "llm_groq",
  "ai_reasoning_enabled": true
}

Key capabilities:

  • 🔢 0–100 Health Risk Score with LOW / MODERATE / HIGH / CRITICAL levels
  • 📈 Longitudinal trend detection across multiple historical reports
  • 🤖 Hybrid reasoning — deterministic offline mode + optional Groq/OpenAI LLM
  • 🔌 Full MCP server with 6 reusable medical-analysis tools
  • 🏥 SHARP-style FHIR integration via request headers for live EHR context
  • 🖥️ Built-in frontend UI served directly from the MCP server — zero extra deployment

How we built it

We designed MedExplainer Pro around a deterministic 5-step agentic pipeline so it works reliably with or without an LLM:

Step 1 — Input Normalization (fhir.py)
Any input format — plain text, JSON, or a real FHIR Bundle — is parsed and normalized into an internal FHIR-aligned FHIRPatient model with typed FHIRObservation objects.

Step 2 — Lab Value Extraction (extract_lab_values_tool)
Numeric observations are extracted with units and reference ranges resolved from the patient model.

Step 3 — Abnormal Value Analysis (analyze_values_tool)
Each value is classified as LOW / NORMAL / HIGH. Deviation percentages and severity weights are calculated. Critical parameters — Hemoglobin, Potassium, Troponin, Sodium, Glucose — carry higher risk weights than moderate ones like Cholesterol and HbA1c.

Step 4 — Risk Scoring (compute_risk_tool)
A deterministic 0–100 Health Risk Score is computed from weighted abnormal findings and mapped to four clinical risk levels.

Step 5 — Explanation & Reasoning (generate_explanation_tool)
Clinical insights and recommended actions are generated. In offline mode, deterministic rule-based logic produces medically sensible outputs with zero API cost. With a Groq or OpenAI key, a remote LLM (LLaMA 3 70B) generates richer, narrative-grade explanations. The reasoning_mode field in every response makes it fully transparent which path was used.

Trend Analysis (analyze_trends_tool)
When multiple historical reports are provided, reports are sorted chronologically and worsening or improving patterns are surfaced across visits.

Tech stack:
Python 3.11 · FastMCP 3.2+ · MCP SDK · Starlette · HTTPX · Uvicorn · Groq (LLaMA 3 70B) · FHIR R4 · Pytest · Vanilla HTML/CSS/JS

Challenges we ran into

🔬 Plain-text lab parsing is a jungle.
Lab reports have no universal format. Some use colons, some use dashes, some embed statuses like "(High)" in parentheses or "[Low]" in brackets. We built a multi-pattern defensive parser that handles real-world variability without crashing on edge cases — and degrades gracefully when a value just can't be parsed.

🏥 FHIR is powerful but complex.
Implementing a pragmatic FHIR R4 subset that handles Bundle, Patient, and Observation resources — while staying simple enough to be hackathon-runnable — required careful scope decisions. We focused on the data shapes that matter most for lab result interpretation and skipped the parts that don't.

🔒 PHI safety demanded real discipline.
In healthcare AI, a logging mistake isn't just a bug — it's a potential HIPAA violation. We gated all pipeline payload traces behind explicit environment flags (DEBUG, MEDEXPLAINER_DEBUG) and designed the system so the safe behavior is the default, with unsafe behavior requiring deliberate opt-in.

⚙️ FastMCP version compatibility.
Advertising the SHARP fhir_context_required capability required patching FastMCP internals that aren't part of the public API. We hardened this with try/except so that any future FastMCP version change degrades gracefully instead of crashing server startup.

🤖 Making deterministic output feel intelligent.
Without an LLM, generating clinically sensible explanations from pure logic is genuinely hard. We spent significant time tuning the rule-based reasoning layer so that offline mode output sounds credible and useful, not robotic — because for many real-world deployments, an API key won't be available.

Accomplishments that we're proud of

✅ A fully compliant MCP server exposing 6 medical-analysis tools, callable by any MCP-compatible AI client including Claude Desktop.

✅ Offline-first architecture that produces medically sensible, structured results with zero API dependencies — ready to run in air-gapped clinical environments.

✅ Real FHIR R4 support — not just JSON parsing, but actual FHIR Bundle, Patient, and Observation resource handling with live SHARP-style EHR integration via request headers.

✅ Longitudinal trend detection across multiple historical patient reports — a capability most hackathon health tools simply skip.

✅ Transparent AI disclosure — every response includes reasoning_mode and ai_reasoning_enabled so judges, clinicians, and patients always know exactly how the answer was generated.

✅ Zero-friction demo — the frontend UI, REST API, and MCP server all run from a single python mcp_server.py command. No Docker, no separate build step, no environment setup beyond pip install.

What we learned

🧠 MCP is the right abstraction for healthcare AI tools.
Exposing medical analysis as discrete, composable MCP tools rather than a monolithic API makes the system far more useful — any AI agent, any client, any workflow can call individual steps or the full pipeline.

🏥 FHIR R4 is both a standard and a spectrum.
"FHIR-compliant" means something different depending on whether you're reading from a SMART on FHIR endpoint, a HAPI FHIR test server, or a hospital's proprietary EHR adapter. Defensive parsing and graceful fallbacks are non-negotiable.

🔐 Privacy-first design changes how you architect everything.
When PHI is in the picture, you can't treat logging, caching, or error messages as an afterthought. Every layer of the stack needs a privacy posture before the first line of code is written.

⚖️ The line between "educational support" and "medical advice" is architectural, not just legal.
We embedded the safety disclaimer into the data model itself (AgentConfig.safety_disclaimer) rather than just adding it to the UI — so it propagates through every output path automatically, including MCP tool responses and raw API calls.

What's next for MedExplainer Pro - AI Diagnostic Agent for Medical Reports

🚀 SMART on FHIR OAuth2 — Full authentication flow for direct EHR integration, enabling one-click patient context loading from Epic, Cerner, and other SMART-enabled systems.

💊 Medication interaction analysis — Cross-reference lab findings with active medications to surface interactions that could explain abnormal values.

📊 Clinician dashboard — A multi-patient view with trend alerts, flagging deteriorating cases for care team review.

🌍 Multilingual explanations — Most patients in underserved communities don't speak medical English. LLM-powered translation of clinical insights into regional languages is the next unlock for real health equity impact.

🏗️ HL7 v2 message parsing — Hospital-grade lab interfaces still predominantly use HL7 v2 pipe-delimited messages. Adding this parser makes MedExplainer Pro compatible with the vast majority of real clinical lab feeds.

☁️ HIPAA-compliant cloud deployment — Containerized, audit-logged, encrypted-at-rest production deployment with full access controls — making MedExplainer Pro ready for real clinical adoption, not just demos.

Share this project:

Updates