Update README.md

README.md

@@ -1,157 +1,275 @@
-# Healthcare API MCP
-
-A Model Context Protocol (MCP) server providing access to public healthcare data APIs including FDA adverse events, clinical guidelines, and Medicare pricing information.
-
-## Features
-
-### OpenFDA Provider (14 tools)
-- **Drug Adverse Events**: Query FAERS database for medication safety information
-- **Drug Labels**: Search FDA-approved drug labeling information
-- **Drug Recalls**: Find drug recall and enforcement reports
-- **NDC Directory**: Look up National Drug Codes
-- **Drugs@FDA**: Search approved drug products
-- **Device Events & Recalls**: Medical device adverse events and recalls
-- **Device Classifications**: Device classification database
-- **510(k) & PMA**: Device clearances and approvals
-- **Food Recalls & Events**: Food safety information
-
-### Clinical Guidelines Provider (5 tools)
-- **Preventive Recommendations**: USPSTF evidence-based screening guidelines
-- **Vaccine Schedule**: CDC immunization recommendations
-- **Search Guidelines**: Find guidelines by condition or screening type
-- **Lifestyle Recommendations**: Evidence-based wellness guidance
-- **Care Plan Generator**: Comprehensive 6-month care planning
-
-### CMS Pricing Provider (5 tools)
-- **Medicare Fee Schedule**: Get reimbursement rates by HCPCS code
-- **Procedure Cost Estimates**: Typical cost ranges by procedure
-- **Search Procedure Codes**: Find HCPCS/CPT codes
-- **Facility Cost Comparison**: Compare prices across facilities
-- **Out-of-Pocket Estimates**: Calculate patient responsibility
-
-## Installation
-
-```bash
-pip install -r requirements.txt
-```
-
-## Configuration
-
-Set environment variables to configure the server:
-
-```bash
-# Enable specific providers (comma-separated)
-export ENABLED_PROVIDERS="openfda,clinical_guidelines,cms_pricing"
-
-# Optional: OpenFDA API key for higher rate limits
-export OPENFDA_API_KEY="your_api_key_here"
-
-# Logging level
-export LOG_LEVEL="INFO"
-```
-
-## Usage
-
-### Run as MCP Server (stdio)
-
-```bash
-python -m healthcare_api_mcp
-```
-
-### Use with Claude Desktop
-
-Add to your Claude Desktop config (`claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "healthcare-api": {
-      "command": "python",
-      "args": ["-m", "healthcare_api_mcp"],
-      "env": {
-        "ENABLED_PROVIDERS": "openfda,clinical_guidelines,cms_pricing"
-      }
-    }
-  }
-}
-```
-
-### Filter Providers
-
-Run only specific providers:
-
-```bash
-# Only FDA data
-ENABLED_PROVIDERS=openfda python -m healthcare_api_mcp
-
-# Only clinical guidelines
-ENABLED_PROVIDERS=clinical_guidelines python -m healthcare_api_mcp
-
-# FDA and CMS pricing
-ENABLED_PROVIDERS=openfda,cms_pricing python -m healthcare_api_mcp
-```
-
-## Tool Naming
-
-All tools are namespaced by provider:
-- OpenFDA: `openfda_*` (e.g., `openfda_search_adverse_events`)
-- Clinical Guidelines: `clinical_*` (e.g., `clinical_get_vaccine_schedule`)
-- CMS Pricing: `cms_*` (e.g., `cms_get_medicare_fee`)
-
-## Example Queries
-
-### Check Drug Safety
-```
-Agent: "Check if Simvastatin has any FDA recalls"
-→ Uses: openfda_search_drug_recalls
-```
-
-### Get Preventive Care Recommendations
-```
-Agent: "What screenings does a 55-year-old female need?"
-→ Uses: clinical_get_preventive_recommendations
-```
-
-### Estimate Procedure Cost
-```
-Agent: "How much does a colonoscopy cost with Medicare?"
-→ Uses: cms_estimate_procedure_cost, cms_estimate_out_of_pocket
-```
-
-## Data Sources
-
-- **OpenFDA**: Real-time access to FDA's public APIs
-- **Clinical Guidelines**: Evidence-based recommendations from USPSTF, CDC, AHRQ
-- **CMS Pricing**: Sample data based on Medicare fee schedules (2024)
-
-## Architecture
-
-```
-healthcare_api_mcp/
-├── server.py                    # Main MCP server with stdio
-├── config.py                    # Configuration management
-├── core/
-│   ├── base_provider.py         # Abstract provider base class
-│   ├── decorators.py            # @safe_json_return, @with_retry
-│   └── http_client.py           # Shared HTTP client factory
-└── providers/
-    ├── openfda_provider.py      # FDA APIs
-    ├── clinical_guidelines_provider.py
-    └── cms_pricing_provider.py
-```
-
-## Benefits
-
-✅ **Zero duplication**: Shared utilities across all providers
-✅ **Proper JSON returns**: All tools return JSON strings (no dict inconsistencies)
-✅ **Modular**: Enable only the providers you need
-✅ **Agent-friendly**: Standard MCP stdio protocol
-✅ **Production-ready**: Error handling, retry logic, logging
-
-## License
-
-Copyright (c) 2025. All Rights Reserved.
-
-## HuggingFace MCP 1st Birthday Hackathon
-
-This project is submitted for Track 1 of the HuggingFace MCP 1st Birthday Hackathon.
+---
+title: Healthcare API MCP
+emoji: 🏥
+colorFrom: blue
+colorTo: green
+sdk: docker
+app_port: 7860
+---
+
+# Healthcare API MCP Server
+
+A Model Context Protocol (MCP) server providing structured access to public healthcare data APIs using **HTTP streaming** (no SSE).
+
+## 🎯 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
+```bash
+GET /mcp/tools
+```
+
+Returns all available tools with descriptions.
+
+### Call Tool (Standard)
+```bash
+POST /mcp/call
+Content-Type: application/json
+
+{
+  "tool": "openfda_get_adverse_event_summary",
+  "arguments": {
+    "drug_name": "Aspirin"
+  }
+}
+```
+
+### Stream Tool Results (HTTP Streaming)
+```bash
+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
+
+```bash
+# 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
+
+```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
+
+```javascript
+// 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:**
+```bash
+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:**
+```bash
+curl -X POST .../mcp/call -H "Content-Type: application/json" \
+  -d '{"tool": "clinical_get_preventive_recommendations", "arguments": {"age": 50, "sex": "female"}}'
+```
+
+**Estimate Medical Costs:**
+```bash
+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
+
+- [GitHub Repository](https://github.com/YOUR_USERNAME/healthcare_mcps)
+- [Full Documentation](https://github.com/YOUR_USERNAME/healthcare_mcps/tree/main/healthcare_api_mcp)
+
+## 🎉 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
+
+Copyright (c) 2025. All Rights Reserved.
+
+---
+
+**HTTP Streaming | 24 Tools | No SSE | Production Ready**