# Healthcare AI Superpower — MCP Server

> **Prompt Opinion · Agents Assemble Hackathon**
> Clinical decision-support tools for any AI agent, powered by FHIR R4 and the Model Context Protocol.

---

## What This Does

AI agents on the Prompt Opinion platform can call this MCP server to reason over live FHIR patient data without ever handling EHR credentials directly. The platform bridges the SMART on FHIR session into the server via the `ai.promptopinion/fhir-context` extension — the agent just asks a question, and this server handles the rest.

**Five clinical tools, one endpoint:**

| Tool | Clinical Use Case |
|------|-------------------|
| `fhir_query` | Raw FHIR R4 resource retrieval (any resource type) |
| `medication_review` | Drug interactions · Beers Criteria · duplicate therapy · missing safety labs |
| `summarize_clinical_notes` | Structured extraction from FHIR DocumentReference notes |
| `schedule_appointment` | List, create, or cancel FHIR Appointment resources |
| `identify_care_gaps` | HEDIS · CMS · USPSTF quality gap identification |

---

## Live Endpoints

| | URL |
|-|-----|
| **MCP Server** | `https://3a36e605-0c25-4400-ba89-a8f448f14c7b-00-3wj4nqft3ggq.sisko.replit.dev/api/mcp` |
| **Tools Listing** | `https://3a36e605-0c25-4400-ba89-a8f448f14c7b-00-3wj4nqft3ggq.sisko.replit.dev/api/mcp/tools` |
| **Health Check** | `https://3a36e605-0c25-4400-ba89-a8f448f14c7b-00-3wj4nqft3ggq.sisko.replit.dev/api/healthz` |
| **Demo Dashboard** | `https://3a36e605-0c25-4400-ba89-a8f448f14c7b-00-3wj4nqft3ggq.sisko.replit.dev/` |

---

## Architecture

```
Prompt Opinion Platform
        │
        │  initialize → detects ai.promptopinion/fhir-context extension
        │  tool/call  → injects X-FHIR-Server-URL, X-FHIR-Access-Token, X-Patient-ID
        ▼
┌─────────────────────────────────────────┐
│         Express API Server              │
│         POST /api/mcp                   │
│                                         │
│   ┌─────────────────────────────────┐   │
│   │   MCP Streamable HTTP Transport │   │
│   │   (JSON-RPC 2.0 · 2024-11-05)   │   │
│   └────────────────┬────────────────┘   │
│                    │                    │
│   ┌────────────────▼────────────────┐   │
│   │        MCP Tool Router          │   │
│   │  fhir_query                     │   │
│   │  medication_review              │   │
│   │  summarize_clinical_notes       │   │
│   │  schedule_appointment           │   │
│   │  identify_care_gaps             │   │
│   └────────────────┬────────────────┘   │
│                    │                    │
│   ┌────────────────▼────────────────┐   │
│   │         FHIR Client             │   │
│   │  Real (Bearer token) ──► EHR    │   │
│   │  Mock (no token)    ──► Demo    │   │
│   └─────────────────────────────────┘   │
└─────────────────────────────────────────┘
```

---

## Adding to Prompt Opinion

1. Go to **Configuration → MCP Servers** in your Prompt Opinion workspace.
2. Paste the MCP Server URL and click **Continue**.
   The platform sends an `initialize` request and reads the server's capabilities.
3. A **FHIR Context** toggle appears — enable it.
4. Review and authorize the SMART scopes your tools need.
5. Done. Every subsequent tool call will carry live FHIR credentials in the headers.

---

## Prompt Opinion FHIR Extension

The server advertises support in every `initialize` response:

```json
{
  "capabilities": {
    "extensions": {
      "ai.promptopinion/fhir-context": {
        "scopes": [
          { "name": "patient/Patient.rs",           "required": true  },
          { "name": "patient/MedicationRequest.rs", "required": false },
          { "name": "patient/Condition.rs",         "required": false },
          { "name": "patient/Observation.rs",       "required": false },
          { "name": "patient/DocumentReference.rs", "required": false },
          { "name": "patient/Appointment.crus",     "required": false }
        ]
      }
    }
  }
}
```

Once authorized, Prompt Opinion injects these headers on every tool call:

| Header | Description |
|--------|-------------|
| `X-FHIR-Server-URL` | FHIR server base URL — always present |
| `X-FHIR-Access-Token` | OAuth2 bearer token — present when EHR requires auth |
| `X-Patient-ID` | Active patient's FHIR ID — absent means system-level context |
| `X-FHIR-Refresh-Token` | Refresh token — only if `offline_access` scope granted |
| `X-FHIR-Refresh-Url` | Token refresh endpoint — only if `offline_access` scope granted |

When FHIR headers are absent the server falls back to built-in demo data, so tools always return a useful response.

---

## Tool Reference

### `fhir_query`
Raw FHIR R4 resource query for a patient.

```json
{
  "resourceType": "MedicationRequest",
  "patientId": "patient-001",
  "params": { "status": "active" }
}
```

Supported: `Patient` · `MedicationRequest` · `Condition` · `Observation` · `DocumentReference` · `Appointment`

---

### `medication_review`
Comprehensive medication safety analysis.

- Drug-drug interaction detection (severity: HIGH / MODERATE / LOW)
- High-risk medications via Beers Criteria
- Duplicate therapeutic class detection
- Missing safety lab flags (e.g. INR monitoring for Warfarin)
- Prioritized clinical recommendations

```json
{
  "patientId": "patient-001",
  "includeInactive": false
}
```

**Example finding:** Mary Johnson — `HIGH` Warfarin + Aspirin → increased bleeding risk, monitor INR closely.

---

### `summarize_clinical_notes`
Retrieve and structure FHIR `DocumentReference` clinical notes.

Extracts: vitals · labs · active diagnoses · current medications · care plan · follow-up items

```json
{
  "patientId": "patient-002",
  "noteType": "progress",
  "maxNotes": 5
}
```

---

### `schedule_appointment`
Manage FHIR `Appointment` resources.

```json
{
  "action": "create",
  "patientId": "patient-001",
  "newAppointment": {
    "startDateTime": "2026-06-01T10:00:00",
    "durationMinutes": 30,
    "serviceType": "Primary Care",
    "appointmentType": "FOLLOWUP",
    "providerName": "Dr. Sarah Mitchell",
    "reason": "Diabetes management follow-up"
  }
}
```

Actions: `list` · `create` · `cancel`

---

### `identify_care_gaps`
Open quality gap identification aligned with HEDIS, CMS, and USPSTF guidelines.

```json
{
  "patientId": "patient-001",
  "categories": ["all"]
}
```

Categories: `preventive` · `chronic_disease` · `medications` · `behavioral_health` · `all`

**Example output (Mary Johnson):** 11 open gaps including overdue HbA1c, missing annual diabetic eye exam, no flu vaccine on record, Warfarin without recent INR documentation.

---

## Demo Patients

Built-in mock data is available at all times without a FHIR server.

| Patient ID | Name | Profile | Clinical Highlight |
|------------|------|---------|-------------------|
| `patient-001` | Mary Johnson | 68F · DM2, HTN, AFib | **HIGH** Warfarin + Aspirin interaction · 11 care gaps |
| `patient-002` | Robert Chen | 52M · DM2, HTN | HbA1c 9.2% (poorly controlled) · overdue labs |
| `patient-003` | Sandra Williams | 40F · Depression, Chronic Pain | **HIGH** Sertraline + Tramadol serotonin syndrome risk |

---

## Quick Test (curl)

```bash
# 1. Verify the server is up
curl https://<domain>/api/healthz

# 2. Initialize and confirm the Prompt Opinion extension is declared
curl -X POST https://<domain>/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "test", "version": "1.0" }
    }
  }'

# 3. Run the medication review tool (uses mock data — no FHIR token needed)
curl -X POST https://<domain>/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Patient-ID: patient-003" \
  -d '{
    "jsonrpc": "2.0", "id": 2, "method": "tools/call",
    "params": {
      "name": "medication_review",
      "arguments": { "patientId": "patient-003" }
    }
  }'
```

---

## Project Structure

```
artifacts/
├── api-server/                       # MCP server (Node 24 · Express 5 · esbuild)
│   └── src/
│       ├── mcp/
│       │   ├── server.ts             # Factory + Prompt Opinion extension declaration
│       │   ├── fhir/
│       │   │   ├── client.ts         # FHIR HTTP client with mock fallback
│       │   │   └── mock-data.ts      # Realistic FHIR R4 demo data
│       │   └── tools/
│       │       ├── fhir-query.ts
│       │       ├── medication-review.ts
│       │       ├── clinical-notes.ts
│       │       ├── appointments.ts
│       │       └── care-gaps.ts
│       └── routes/
│           ├── mcp.ts                # Streamable HTTP transport + FHIR header extraction
│           └── health.ts
│
└── healthcare-demo/                  # Interactive demo dashboard (React 19 · Vite 7)
    └── src/
        ├── pages/Dashboard.tsx       # Patient selector + live tool runner
        ├── lib/mcp-client.ts         # MCP JSON-RPC client
        ├── App.tsx
        └── index.css                 # Clinical teal/navy theme
```

---

## Local Development

**Requirements:** Node.js 24 · pnpm 10+

```bash
# Install all workspace dependencies
pnpm install

# Run the MCP API server (proxied to /api by the Replit reverse proxy)
pnpm --filter @workspace/api-server run dev

# Run the demo dashboard (proxied to /)
pnpm --filter @workspace/healthcare-demo run dev

# Full TypeScript check across all packages
pnpm run typecheck
```

---

## Stack

| Layer | Technology |
|-------|------------|
| Runtime | Node.js 24 |
| Language | TypeScript 5.9 |
| MCP SDK | `@modelcontextprotocol/sdk` 1.29 |
| Transport | Streamable HTTP (MCP 2024-11-05) |
| API framework | Express 5 |
| Build | esbuild |
| Frontend | React 19 · Vite 7 · Tailwind CSS 4 |
| Monorepo | pnpm workspaces |

---

## Hackathon

Built for the **Prompt Opinion Agents Assemble Challenge** — a $25,000 prize pool competition focused on MCP, A2A, and FHIR interoperability in healthcare AI.

- Platform: [app.promptopinion.ai](https://app.promptopinion.ai)
- Docs: [docs.promptopinion.ai](https://docs.promptopinion.ai)
- Challenge: [Agents Assemble](https://www.promptopinion.ai/agents-assemble-challenge)
- Discord: [discord.gg/cCBxKpdS7j](https://discord.gg/cCBxKpdS7j)