# MCP Healthcare Server

A Model Context Protocol (MCP) server for clinical workflows, built per the
design in `deep-research-report.md`. The server exposes a governed set of
tools (patient lookup, appointment booking, prescription, drug-interaction
check, symptom triage, lab results, insurance eligibility, telehealth) and
enforces role-based access control and audit logging on every call.

This implementation is a **development scaffold**: data is held in memory
(seeded from `src/data/*.json`) and there is no real EHR/FHIR integration.
It is a safe environment to exercise the MCP surface and the security
enforcement layer.

## Quick start

```bash
npm install
npm run dev     # tsc-watch-style restart on src changes
# or
npm run build && npm start
```

The server speaks MCP over `stdio` and is ready to attach to any MCP-aware
client (Claude Desktop, MCP Inspector, custom agents).

## Tool surface

| Tool | Role required | Purpose |
|---|---|---|
| `search_patient` | any clinical | Look up a patient by MRN or name+DOB |
| `get_patient_history` | any clinical | Recent appointments, conditions, meds |
| `find_available_slots` | any clinical | Provider availability, filterable by specialty |
| `book_appointment` | clinician / admin | Schedule a new appointment |
| `reschedule_appointment` | clinician / admin | Move an existing appointment |
| `get_active_medications` | any clinical | Patient's current medication list |
| `check_drug_interaction` | clinician / pharmacist / admin | Pairwise interaction check |
| `create_prescription` | clinician / admin | Write a prescription, surfaces allergy + interaction warnings |
| `analyze_symptoms` | any clinical | Rule-based triage with urgency + specialty |
| `suggest_specialist` | any clinical | Recommend a specialty for a description |
| `get_recent_lab_results` | any clinical | Fetch lab data, filter by test name |
| `analyze_lab_results` | any clinical | Summarize, count abnormalities, flag criticals |
| `check_eligibility` | clinician / admin | Verify insurance coverage and copay |
| `create_prior_authorization_request` | clinician / admin | Submit a prior auth request |
| `create_telehealth_session` | clinician / admin | Create a video session, return URL |
| `send_telehealth_link` | clinician / admin | Queue session link for delivery (stub) |

Every tool call must include a `userId` from `src/data/users.json`. The
server resolves the user, checks role permissions, then runs the handler.
Denials and runtime errors are recorded in the audit log.

## Security model

- **Audit log** — one JSON line per call to `logs/audit-<YYYY-MM-DD>.log`.
  Captures timestamp, userId, tool, SHA-256 of the input (16 hex chars —
  avoids writing PHI in plaintext), outcome, and duration.
- **RBAC** — defined in `src/auth/rbac.ts`. Read tools accept any clinical
  role. Write tools require `clinician` or `admin`. Pharmacy tools also
  accept `pharmacist`. Unknown user → denial.
- **Input validation** — Zod schemas on every tool; the MCP SDK rejects
  malformed inputs before the handler runs.

## File layout

```
src/
  index.ts                 # bootstrap (stdio transport)
  server.ts                # createServer(): McpServer + audit + exit hooks
  config.ts                # env loading (LOG_DIR, DATA_DIR)
  types.ts                 # domain types
  audit/logger.ts          # append-only audit log
  auth/rbac.ts             # user lookup + role checks
  store/memoryStore.ts     # in-memory store + loadSeed()
  tools/
    registry.ts            # central tool context + module list
    patient.ts             # search_patient, get_patient_history
    appointment.ts         # find_available_slots, book, reschedule
    prescription.ts        # create_prescription, check_drug_interaction, get_active_medications
    symptoms.ts            # analyze_symptoms, suggest_specialist
    lab.ts                 # get_recent_lab_results, analyze_lab_results
    eligibility.ts         # check_eligibility, create_prior_authorization_request
    telehealth.ts          # create_telehealth_session, send_telehealth_link
  data/                    # seed JSON (patients, providers, drugs, labs, etc.)
logs/                      # audit log output (gitignored)
```

## Seed users (for testing)

| userId | name | role |
|---|---|---|
| `u-clin-1` | Dr. Aisha Khan | clinician |
| `u-clin-2` | Dr. Marcus Lee | clinician |
| `u-nurse-1` | Nurse Priya Shah | nurse |
| `u-recep-1` | Jordan Park | receptionist |
| `u-pharm-1` | Rita Chen, PharmD | pharmacist |
| `u-admin-1` | Sam Whittaker | admin |

## Out of scope (TODO for production)

- Real FHIR / HL7 / PACS / DICOM adapters
- OAuth2 / SMART-on-FHIR launch
- Persistent database (in-memory only)
- LLM-backed symptom analysis (rule-based placeholder)
- HIPAA-grade audit retention, encryption at rest, key rotation
- Rate limiting, network segmentation

## References

See `deep-research-report.md` for the full design rationale, architecture
options, compliance checklist, and roadmap that informed this implementation.