# Virtual Patient MCP App • OSCE Clinical Simulation Suite

A full-stack **Model Context Protocol (MCP) Application** designed for medical students and doctors to practice clinical consultations in an emergency / ward setting.

---

## Architecture Overview

```
+---------------------------------------------------------------------------------------+
|  HOST PLATFORM (e.g., Enterprise Agent Chat / McpAppContainer)                        |
|  • Renders <McpAppContainer resourceUri="http://localhost:5174" />                    |
|  • Listens to postMessage events (JSON-RPC 2.0 tools/call)                            |
+-------------------------------------------|-------------------------------------------+
                                            |
                         postMessage (JSON-RPC 2.0)
                                            |
+-------------------------------------------v-------------------------------------------+
|  CLIENT: THE MCP APP (http://localhost:5174)                                          |
|  • Real-time Animated HTML5 Canvas ECG Monitor (Sinus Tachycardia / STEMI rhythm)     |
|  • History Taking Chat (Anamnesis) with rapid clinical chips & custom inquiries       |
|  • Targeted Physical Examination Suite (Mitral Apex, JVP, Lung Bases, Chest Wall)     |
|  • Diagnostic Lab Center (12-Lead ECG strip, Troponin I STAT, CXR, CBC, BMP)          |
|  • Resuscitation & Rx Pad (Aspirin chewable, Sublingual Nitroglycerin, Oxygen)        |
|  • Official OSCE Scorecard (Letter grade, competency checklist, professor debrief)    |
+-------------------------------------------|-------------------------------------------+
                                            |
                              REST / SSE / stdio Transports
                                            |
+-------------------------------------------v-------------------------------------------+
|  SERVER: VIRTUAL PATIENT MCP SERVER (http://localhost:3001)                           |
|  • Model Context Protocol Server (@modelcontextprotocol/sdk)                          |
|  • Tools: converse_patient, examine_patient, order_investigation,                      |
|           administer_medication, submit_consultation, switch_case                     |
|  • Resources: patient://vitals, patient://chart                                       |
|  • Medical Cases Engine: loads cases from /cases/*.json                               |
+---------------------------------------------------------------------------------------+
```

---

## Getting Started

### 1. Run the Entire Suite (Server + Client)
```bash
npm run dev
```
- **MCP Server**: `http://localhost:3001` (SSE: `/sse`, REST: `/api/state`)
- **Interactive MCP App**: `http://localhost:5174`

### 2. Embedding inside `McpAppContainer`
In your agent chat interface, pass:
```javascript
<McpAppContainer
  resourceUri="http://localhost:5174"
  minHeight={650}
  onToolCallRequested={(call) => {
    console.log("MCP Tool Call from Virtual Patient UI:", call);
  }}
/>
```

---

## MCP Tools Reference

| Tool Name | Parameters | Description |
| :--- | :--- | :--- |
| `converse_patient` | `{ message: string, bedside_tone?: string }` | Conducts history-taking. Patient responds with emotional fidelity without leaking diagnosis. |
| `examine_patient` | `{ system: string, action: string, site?: string }` | Elicits physiological examination findings (auscultation sounds, palpation tenderness). |
| `order_investigation` | `{ test_name: string }` | Releases laboratory panels and imaging reports (12-lead ECG, Troponin I, CXR). |
| `administer_medication` | `{ drug_name: string, dose?: string, route?: string }` | Gives emergency pharmacotherapy and triggers immediate telemetry & pain updates. |
| `submit_consultation` | `{ primary_diagnosis: string, differentials: string[], treatment_plan: string }` | Concludes encounter and generates the comprehensive OSCE scorecard. |
| `switch_case` | `{ caseId: string }` | Switches between clinical cases (e.g. STEMI vs. Community-Acquired Pneumonia). |

---

## Included Clinical Cases
1. `case_01_stemi.json` — 58-year-old male with acute retrosternal crushing chest pain radiating to left arm/jaw (Acute STEMI).
2. `case_02_pneumonia.json` — 42-year-old female with high fever, rigors, rusty sputum, and pleuritic chest pain (Community-Acquired Pneumonia).