Spaces:

MCP-1st-Birthday
/

healthcare-api-mcp

Running

App Files Files

healthcare-api-mcp / README.md

visproj

Update README.md

cf0dfc3 verified 19 days ago

preview code

raw

history blame

6.92 kB

metadata

title: Healthcare API MCP
emoji: 🏥
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
tags:
  - building-mcp-track-enterprise
  - building-mcp-track-research

Link to my LinkedIn post and video submission: https://www.linkedin.com/posts/activity-7399100966597476352-BwTv

Healthcare API MCP Server

A Model Context Protocol (MCP) server providing structured access to public healthcare data APIs using HTTP streaming .

🎯 Features

OpenFDA Provider (14 tools)

Drug adverse events (FAERS database)
FDA drug labels and recalls
NDC directory and Drugs@FDA
Device safety data
Food safety data

Clinical Guidelines Provider (5 tools)

USPSTF preventive care recommendations
CDC vaccine schedules
Evidence-based lifestyle recommendations
Care plan generation

CMS Pricing Provider (5 tools)

Medicare fee schedules
Procedure cost estimates
Facility cost comparisons
Out-of-pocket estimates

Total: 24 healthcare tools

📡 API Endpoints

List Tools

GET /mcp/tools

Returns all available tools with descriptions.

Call Tool (Standard)

POST /mcp/call
Content-Type: application/json

{
  "tool": "openfda_get_adverse_event_summary",
  "arguments": {
    "drug_name": "Aspirin"
  }
}

Stream Tool Results (HTTP Streaming)

POST /mcp/stream
Content-Type: application/json

{
  "tool": "openfda_fetch_adverse_events",
  "arguments": {
    "drug_name": "Aspirin",
    "limit": 100
  }
}

Returns newline-delimited JSON (NDJSON) stream with chunked transfer encoding.

🚀 Usage

With curl

# List tools
curl https://YOUR_USERNAME-healthcare-api-mcp.hf.space/mcp/tools

# Call a tool
curl -X POST https://YOUR_USERNAME-healthcare-api-mcp.hf.space/mcp/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "openfda_search_drug_recalls",
    "arguments": {"query": "Aspirin", "limit": 5}
  }'

# Stream results
curl -N -X POST https://YOUR_USERNAME-healthcare-api-mcp.hf.space/mcp/stream \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "openfda_fetch_adverse_events",
    "arguments": {"drug_name": "Metformin", "limit": 50}
  }'

With Python

import httpx
import json

# Call a tool
async with httpx.AsyncClient() as client:
    response = await client.post(
        "https://YOUR_USERNAME-healthcare-api-mcp.hf.space/mcp/call",
        json={
            "tool": "clinical_get_preventive_recommendations",
            "arguments": {"age": 55, "sex": "female"}
        }
    )
    result = response.json()
    print(result)

# Stream results
async with httpx.AsyncClient() as client:
    async with client.stream(
        "POST",
        "https://YOUR_USERNAME-healthcare-api-mcp.hf.space/mcp/stream",
        json={
            "tool": "openfda_fetch_adverse_events",
            "arguments": {"drug_name": "Simvastatin", "limit": 100}
        }
    ) as response:
        async for line in response.aiter_lines():
            if line:
                data = json.loads(line)
                print(data)

With JavaScript/Node.js

// Call a tool
const response = await fetch('https://YOUR_USERNAME-healthcare-api-mcp.hf.space/mcp/call', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    tool: 'cms_estimate_procedure_cost',
    arguments: {procedure_name: 'colonoscopy'}
  })
});
const result = await response.json();
console.log(result);

// Stream results
const streamResponse = await fetch('https://YOUR_USERNAME-healthcare-api-mcp.hf.space/mcp/stream', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    tool: 'openfda_fetch_adverse_events',
    arguments: {drug_name: 'Aspirin', limit: 50}
  })
});

const reader = streamResponse.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const {done, value} = await reader.read();
  if (done) break;

  const lines = decoder.decode(value).split('\n');
  for (const line of lines) {
    if (line.trim()) {
      const data = JSON.parse(line);
      console.log(data);
    }
  }
}

🏗️ Architecture

Protocol: HTTP with chunked transfer encoding (no SSE)
Format: JSON for requests/responses, NDJSON for streaming
Framework: FastAPI + Uvicorn
Transport: HTTP/1.1 streaming
Providers: Factory pattern with modular providers

🔧 Configuration

Environment variables (optional):

ENABLED_PROVIDERS: Comma-separated list (default: all)
OPENFDA_API_KEY: Optional for higher FDA rate limits
LOG_LEVEL: DEBUG, INFO, WARNING, ERROR

📚 Example Queries

Check Drug Safety:

curl -X POST .../mcp/call -H "Content-Type: application/json" \
  -d '{"tool": "openfda_get_adverse_event_summary", "arguments": {"drug_name": "Aspirin"}}'

Get Preventive Care Recommendations:

curl -X POST .../mcp/call -H "Content-Type: application/json" \
  -d '{"tool": "clinical_get_preventive_recommendations", "arguments": {"age": 50, "sex": "female"}}'

Estimate Medical Costs:

curl -X POST .../mcp/call -H "Content-Type: application/json" \
  -d '{"tool": "cms_estimate_procedure_cost", "arguments": {"procedure_name": "mri"}}'

📊 Available Tools

See /mcp/tools endpoint for complete list with descriptions.

OpenFDA (14 tools)

openfda_get_adverse_event_summary
openfda_fetch_adverse_events
openfda_top_reactions
openfda_search_drug_labels
openfda_search_ndc
openfda_search_drug_recalls
openfda_search_drugs_fda
openfda_search_device_events
openfda_search_device_recalls
openfda_search_device_classifications
openfda_search_510k
openfda_search_pma
openfda_search_food_recalls
openfda_search_food_events

Clinical Guidelines (5 tools)

clinical_get_preventive_recommendations
clinical_get_vaccine_schedule
clinical_search_guidelines
clinical_get_lifestyle_recommendations
clinical_generate_care_plan

CMS Pricing (5 tools)

cms_get_medicare_fee
cms_estimate_procedure_cost
cms_search_procedure_codes
cms_compare_facility_costs
cms_estimate_out_of_pocket

🔒 Security & Privacy

✅ Public APIs only (no PHI)
✅ No authentication required
✅ Rate limiting via OpenFDA API
✅ Stateless queries

📖 Documentation

🎉 Hackathon

Built for HuggingFace MCP 1st Birthday Hackathon - Track 1

Demonstrates:

HTTP streaming (no SSE)
Factory pattern architecture
Clean code principles
Production-ready error handling
Healthcare data integration

📝 License

HTTP Streaming | 24 Tools | No SSE | Production Ready