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)

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