# Epic Patient API MCP Server

Fake Epic MCP server with file-based patient data and LLM-powered search.

## Features

- **Two-tier data access**: List summaries first, then fetch details by ID
- **15 MCP Tools** for querying patient data:
  - List tools (return IDs, dates, metadata only): `list_patient_allergies`, `list_patient_medications`, `list_patient_conditions`, `list_clinical_notes`, `list_lab_results`, `list_vitals`, `list_procedures`
  - Detail tools (require IDs, return full data): `get_allergy_details`, `get_medication_details`, `get_condition_details`, `get_clinical_note_details`, `get_lab_result_details`, `get_vital_details`, `get_procedure_details`
  - Attachment tool: `get_note_attachment`
  - Search tool: `search_patient_data` - Natural language search using LLM
- **Pluggable LLM**: Supports Gemini or OpenRouter for natural language search
- **File-based storage**: Patient data in YAML files under `patients/`

## Setup

1. Install: `uv pip install -e .`
2. Configure LLM in `.env`:
   - **Gemini** (default): `GEMINI_API_KEY=...` (get from https://aistudio.google.com/app/apikey)
   - **OpenRouter**: `LLM_PROVIDER=openrouter`, `OPENROUTER_API_KEY=...`, `OPENROUTER_MODEL=anthropic/claude-3.5-sonnet`
3. Run: `uv run python -m epic_mcp.server`

Server runs on `http://localhost:8000/sse`

## Usage Pattern

Two-tier access minimizes data transfer:

1. **List** to see what's available (IDs + metadata):
   ```json
   {"patient_id": "patient_001"}
   ```
   Returns: `[{"id": "allergy-1", "allergen": "Penicillin", "severity": "severe", "recorded_date": "2015-03-20"}]`

2. **Get details** for specific items:
   ```json
   {"patient_id": "patient_001", "allergy_id": "allergy-1"}
   ```
   Returns: `{"id": "allergy-1", "allergen": "Penicillin", "reaction": "Hives, difficulty breathing", "severity": "severe", "recorded_date": "2015-03-20"}`

## Claude Desktop Setup

1. Run server: `uv run python -m epic_mcp.server`
2. Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
   ```json
   {"mcpServers": {"epic-patient-api": {"url": "http://localhost:8000/sse"}}}
   ```
3. Restart Claude Desktop

## Available Patients

- `patient_001` - John Doe (58M) - Hypertension, Type 2 Diabetes
- `patient_002` - Jane Smith (32F) - Hypothyroidism, Pregnant
- `patient_003` - Robert Chen (56M) - Stage IV Colorectal Cancer