# hospitalverse-mcp

Rule-based Layer 2 agent logic + Layer 1 tool surface for HospitalVerse AI,
matching the architecture in `HospitalVerse_Architecture.md`. This is
build-order **step 2** ("deterministic agents producing the same JSON
shape a real agent would") — swap in LangGraph + an LLM per module
(step 3) without touching the tool contracts, then MCP-ify (step 4).

## What's here vs. what's new

Everything in `src/` implements the tool surface from architecture §4.
Two things go beyond the original doc, from the review pass:

1. **Visible conflict resolution.** `coordinator.ts` doesn't just chain
   agent outputs — when the Bed Agent's top pick lands in an
   understaffed ward, or a doctor is over capacity, the Coordinator
   picks between two real options and records *both*: what it rejected,
   what it chose, and why. That's what `ActionStep.conflict` carries
   through to the Explainer prompt and the dashboard.
2. **A queryable audit trail.** `audit.resources.ts` exposes
   `audit://trail/{agent}` and `audit://trail/by-event/{eventId}` as MCP
   Resources, not just a database table. Every tool call already writes
   to the log via `withAudit()` in `state/dts.ts` — these resources are
   what let a judge (or a real compliance reviewer) query it live.

## Run it standalone (no MCP, no Studio)

```bash
npm install
npm run dev
```

`src/index.ts` runs a CLI demo: injects an ambulance surge, runs the
Coordinator, and prints the resulting action chain — including the
conflict-resolution step — plus the audit log size. Good for verifying
agent logic works before wiring up Studio.

## Wire it into NitroStack Studio

The folder layout here matches what `nitrostack-cli init` scaffolds
(`src/index.ts`, `app.module.ts`, `modules/*.tools.ts`), but doesn't
depend on `@nitrostack/core` yet — `src/lib/define-tool.ts` is a thin
stand-in. To go from "runs standalone" to "connects in Studio":

1. `nitrostack-cli init hospitalverse-mcp --template typescript-starter`
2. Copy this `src/` tree into the scaffolded project, replacing the
   starter's calculator example.
3. In `src/lib/define-tool.ts`, swap the plain `defineTool`/
   `defineResource` functions for whatever `@nitrostack/core` exports —
   every module here only imports from that one file.
4. `npm run dev`, then Studio → **Add Server → Nitro Project** → pick the
   folder (handbook §4). The Tools/Resources pages will list everything
   in `app.module.ts` automatically.
5. For the "no user typed a question" wow-moment: deploy, then connect
   to ChatGPT (handbook, "How to connect to ChatGPT") and call
   `sim.inject_event` from a ChatGPT chat instead of a dashboard button —
   proves the MCP surface is a real interop layer, not just internal
   plumbing for your own UI.

## Files

```
src/
├── index.ts                    # standalone CLI demo / bootstrap
├── app.module.ts                # registers every tool + resource
├── lib/define-tool.ts           # @nitrostack/core stand-in — swap here
├── state/
│   ├── dts.ts                   # Digital Twin State + event bus + audit hook
│   └── state.tools.ts           # state.get_snapshot, get_historical_trend
├── predict/predict.tools.ts     # predict.occupancy (Forecaster Agent)
├── beds/beds.tools.ts           # beds.*, patients.list_dischargeable
├── staff/staff.tools.ts         # staff.* (Staffing Agent)
├── equipment/equipment.tools.ts # equipment.* (Equipment Agent)
├── sim/sim.tools.ts             # sim.inject_event — demo trigger
├── audit/audit.resources.ts     # audit://trail/* — the new compliance surface
├── coordinator/
│   ├── coordinator.ts           # conflict-resolution logic, two cascades
│   └── explainer.prompts.ts     # Explainer Agent prompt + fallback
└── health/health.ts             # health check for Studio's Health page
```