Skip to content
Back to search

Integration-Assistant-MCP-Based-Healthcare-Workflow-Simulator

An MCP server that simulates healthcare integration workflows (patient intake, lab orders, referrals) for demoing AI-assisted integration.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/moein-71--integration-assistant-mcp-based-healthcare-workflow-simulator/badge.svg)](/listings/moein-71--integration-assistant-mcp-based-healthcare-workflow-simulator)

HTML

<a href="/listings/moein-71--integration-assistant-mcp-based-healthcare-workflow-simulator"><img src="/api/listings/moein-71--integration-assistant-mcp-based-healthcare-workflow-simulator/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/moein-71/Integration-Assistant-MCP-Based-Healthcare-Workflow-Simulator.git
cd Integration-Assistant-MCP-Based-Healthcare-Workflow-Simulator

node --version   # must be >= 18
npm --version

npm install
npm run typecheck
npm run build
npm test

All scripts come from [package.json](package.json): `build`, `typecheck`, `test`, `smoke`, `server`, `admin`, and `demo`.

**Environment variables:** the source uses one — `MCP_DATA_DIR`. When set, all repositories read and write JSON files in that directory instead of the default `data/` directory. The default path is resolved relative to the repository module, so the server works regardless of the current working directory. Tests and the demo set `MCP_DATA_DIR` to isolated temporary copies so committed fixtures are never modified. No `.env` file is required.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 699 lines
  1. # Integration Assistant — MCP-Based Healthcare Workflow Simulator
  2. A local, synthetic healthcare integration workflow simulator built with the official
  3. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) SDK. It exposes a real
  4. MCP server over stdio with **10 tools**, **3 read-only resources**, **1 patient resource
  5. template**, and **3 prompts**, plus a **separate human Admin CLI** for approval and
  6. rejection decisions.
  7. **This project is an educational prototype, not a production healthcare system.** Every
  8. patient, appointment, laboratory-style result, workflow, and integration system is
  9. fictional. It does not connect to real hospitals, hospital information systems, or
  10. external healthcare APIs; it does not access real patient records; it does not execute
  11. healthcare workflows; and it does not publish integrations. `APPROVED` is only a recorded
  12. human decision — nothing is ever run or deployed.
  13. See [data/README.md](data/README.md) for details on the synthetic dataset.
  14. ---
  15. ## Table of contents
  16. - [What problem this demonstrates](#what-problem-this-demonstrates)
  17. - [Key features](#key-features)
  18. - [Technology stack and requirements](#technology-stack-and-requirements)
  19. - [Architecture overview](#architecture-overview)
  20. - [MCP implementation](#mcp-implementation)
  21. - [Synthetic healthcare data](#synthetic-healthcare-data)
  22. - [Workflow lifecycle and business logic](#workflow-lifecycle-and-business-logic)
  23. - [Human-in-the-loop approval and Admin CLI](#human-in-the-loop-approval-and-admin-cli)
  24. - [Audit events](#audit-events)
  25. - [Installation and setup](#installation-and-setup)
  26. - [Running the project](#running-the-project)
  27. - [MCP client configuration](#mcp-client-configuration)
  28. - [Complete end-to-end example](#complete-end-to-end-example)
  29. - [Testing and quality assurance](#testing-and-quality-assurance)
  30. - [Project structure](#project-structure)
  31. - [Security, privacy, and limitations](#security-privacy-and-limitations)
  32. - [Design decisions and future improvements](#design-decisions-and-future-improvements)
  33. - [License and contribution](#license-and-contribution)
  34. ---
  35. ## What problem this demonstrates
  36. Healthcare integration work usually involves moving information between systems such as
  37. electronic health records, scheduling tools, laboratories, and referral systems. In a real
  38. environment that work is tightly regulated, uses sensitive data, and requires human
  39. oversight before changes are accepted.
  40. This simulator models that shape of problem safely:
  41. - An AI assistant (an **MCP client**) can inspect fictional patients, appointments, lab
  42. results, and workflows through a controlled set of read-only and lifecycle tools.
  43. - The assistant can assemble a workflow draft from real synthetic records, validate it,
  44. and submit it for **human review**.
  45. - The assistant deliberately **cannot** approve, reject, execute, or publish anything.
  46. Those decisions belong to a separate human process (the Admin CLI).
  47. - A small, explicit state machine and audit event log make the lifecycle observable.
  48. MCP is used because it provides a standard, transport-friendly way for an AI client to
  49. discover tools, resources, and prompts from a server. Here the transport is stdio: the
  50. client spawns the server as a child process and speaks JSON-RPC over its standard input
  51. and output. That makes the integration realistic without needing a network service,
  52. database, or cloud account.
  53. ---
  54. ## Key features
  55. - **Real MCP communication** — a real client connects to a real server process over
  56. stdio using the official SDK; no in-process shortcuts.
  57. - **Synthetic healthcare data** — fictional patients, appointments, lab-style results,
  58. and workflows stored as JSON files.
  59. - **Read-only data retrieval** — tools for patients, appointments, lab results, and
  60. workflows; resource reads never modify data.
  61. - **Workflow lifecycle** — create drafts, validate them read-only, submit valid drafts
  62. for approval, and revise rejected workflows back to `DRAFT`.
  63. - **Separate human Admin CLI** — `list`, `inspect`, `approve`, and `reject` run in a
  64. different process and are never registered as MCP tools.
  65. - **Audit events** — approvals and rejections are recorded in a separate event file.
  66. - **MCP Resources** — three static context documents and a `patient://{id}` resource
  67. template backed by real synthetic patient data.
  68. - **MCP Prompts** — reusable instruction templates for workflow creation, patient
  69. summarization, and draft review.
  70. - **Automated tests** — 94 tests across 7 files, including real stdio integration tests.
  71. - **Reproducible demonstration** — `npm run demo` drives the whole flow against an
  72. isolated temporary data directory.
  73. ---
  74. ## Technology stack and requirements
  75. All versions below are pinned in [package.json](package.json) and
  76. [package-lock.json](package-lock.json).
  77. | Technology | Version | Role |
  78. | --- | --- | --- |
  79. | Node.js | `>=18` runtime requirement | Hosts both the server and client processes; verified on Node 26 |
  80. | npm | bundled with Node | Installs local dependencies and runs the npm scripts |
  81. | TypeScript | `5.9.3` | Strictly typed source (`strict: true`, `noUnusedLocals`, `noUnusedParameters`) |
  82. | `@modelcontextprotocol/sdk` | `1.32.2` | Official MCP SDK: `McpServer`, `StdioServerTransport`, `ResourceTemplate`, client APIs |
  83. | Zod | `4.6.7` | Runtime validation of tool and prompt arguments |
  84. | Vitest | `5.1.1` | Test runner (dev dependency) |
  85. | tsx | `4.23.15` | Runs TypeScript directly during development/tests (dev dependency) |
  86. | `@types/node` | `26.6.6` | Node type definitions (dev dependency) |
  87. The project uses ESM (`"type": "module"`), `NodeNext` module resolution, and an ES2022
  88. target. See [tsconfig.json](tsconfig.json) and [tsconfig.build.json](tsconfig.build.json).
  89. **Development environment:** Node.js 18 or newer, npm, and a POSIX-like shell for the
  90. documented commands. The code itself uses only Node built-ins plus the dependencies
  91. above, so it is platform-independent; the shell examples assume `bash`/`zsh`. No global
  92. packages are required. Write access to a temporary directory is needed by the tests and
  93. demo, which copy fixtures into isolated directories.
  94. ---
  95. ## Architecture overview
  96. ```mermaid
  97. flowchart LR
  98. subgraph CLIENT["MCP Client process"]
  99. MC["MCP Client<br/>smoke.ts / demo / external client"]
  100. end
  101. subgraph SERVER["MCP Server process (src/server/index.ts)"]
  102. ST["StdioServerTransport<br/>stdout: JSON-RPC only<br/>stderr: diagnostics"]
  103. REG["McpServer registration<br/>10 tools / 3 resources<br/>1 template / 3 prompts"]
  104. SVC["Domain and services<br/>validation, lifecycle, lookup"]
  105. REPO["Repositories<br/>JSON read/write, atomic replace<br/>in-process write queue"]
  106. end
  107. subgraph DATA["Synthetic JSON data"]
  108. DB[("data/patients.json<br/>data/appointments.json<br/>data/lab-results.json<br/>data/workflows.json")]
  109. end
  110. subgraph ADMIN["Separate Admin CLI process"]
  111. CLI["src/admin/cli.ts<br/>list / inspect / approve / reject"]
  112. ASVC["admin.service.ts<br/>state checks, decisions"]
  113. AUD[("data/audit-events.json")]
  114. end
  115. MC -->|"JSON-RPC over stdin/stdout"| ST
  116. ST --> REG
  117. REG --> SVC
  118. SVC --> REPO
  119. REPO --> DB
  120. CLI --> ASVC
  121. ASVC --> REPO
  122. ASVC --> AUD
  123. ```
  124. **Responsibilities**
  125. | Component | Responsibility |
  126. | --- | --- |
  127. | MCP Client | Discovers capabilities, calls tools, reads resources, requests prompts |
  128. | MCP Server ([index.ts](src/server/index.ts)) | Creates `McpServer`, registers tools/resources/prompts, connects stdio transport, handles shutdown |
  129. | Tool modules ([src/server/tools/](src/server/tools/)) | Input schemas, descriptions, and conversion of service results into MCP `CallToolResult` |
  130. | Resources ([resources.ts](src/server/resources.ts)) | Static context documents and the read-only patient resource template |
  131. | Prompts ([prompts.ts](src/server/prompts.ts)) | Instruction templates returned to the client; no execution |
  132. | Services ([src/services/](src/services/)) | Validation, workflow lifecycle, lookups, admin decisions |
  133. | Repositories ([src/repositories/](src/repositories/)) | JSON file access, atomic writes, in-process serialization, audit event storage |
  134. | Admin CLI ([cli.ts](src/admin/cli.ts)) | Human approval/rejection in a separate process |
  135. **Why is the Admin CLI separate?** Approval and rejection are trust decisions. Keeping
  136. them out of the MCP server means an AI client has no path — no tool, resource, or prompt
  137. — that can approve or reject a workflow. The MCP server never imports the admin service
  138. or the audit repository; the CLI is the only caller. This boundary is intentional and is
  139. enforced by the code structure and by tests that check the live tool inventory.
  140. **Persistence:** all state lives in JSON files. The default directory is resolved
  141. relative to the repository module (so it works from `src/` and compiled `dist/`); setting
  142. `MCP_DATA_DIR` overrides it. Writes go to a temporary file and are renamed into place.
  143. See [json-store.ts](src/repositories/json-store.ts).
  144. ---
  145. ## MCP implementation
  146. MCP is a protocol that lets a client discover and use capabilities exposed by a server.
  147. In this project:
  148. - The **server** ([index.ts](src/server/index.ts)) constructs an `McpServer`, registers
  149. capabilities, and attaches a `StdioServerTransport`.
  150. - The **client** (for example [smoke.ts](src/client/smoke.ts) or
  151. [end-to-end-demo.ts](scripts/end-to-end-demo.ts)) spawns the server with
  152. `process.execPath`, performs the MCP `initialize` handshake, and closes it when done.
  153. - **stdio transport** means request/response JSON-RPC messages travel over the child
  154. process's stdin/stdout. Therefore **stdout is reserved exclusively for the protocol**:
  155. server-side code contains no `console.log` or `stdout.write`. Diagnostics use
  156. `console.error`, which writes to stderr. Tests verify the server runs as a distinct
  157. child process and that the compiled `dist/server/index.js` works from any working
  158. directory.
  159. ### MCP Tools
  160. Exactly 10 tools are registered. Inputs are validated with Zod at runtime. Successful
  161. results use a `{ "notice": "...", "data": ... }` JSON text envelope; failures use MCP
  162. `isError: true` with a readable message, never a stack trace or local path.
  163. | # | Tool | Purpose | Input parameters | Important behavior |
  164. | --- | --- | --- | --- | --- |
  165. | 1 | `get_patient` | Retrieve one synthetic patient | `patient_id` (required, non-empty string) | Returns id, display name, date of birth, status, creation time. Unknown ID → not-found error. Does not include appointments or labs. |
  166. | 2 | `get_patient_summary` | Retrieve a patient with related records | `patient_id` (required) | Returns the patient, their appointments and lab results, an explicit `missing_information` list, and a data notice. Unknown ID → error. No clinical inference. |
  167. | 3 | `list_appointments` | List synthetic appointments | `patient_id` (optional), `status` (optional: `scheduled`, `completed`, `cancelled`) | Filters by patient and/or status; returns an array, empty when nothing matches. Never modifies appointments. |
  168. | 4 | `get_lab_results` | List lab-style results for one patient | `patient_id` (required) | Unknown patient → error; existing patient with no results → empty array. Values are illustrative, not diagnoses. |
  169. | 5 | `get_workflow` | Inspect one workflow | `workflow_id` (required) | Returns status, steps, references, `last_validation`, and history. Unknown ID → error. Read-only. |
  170. | 6 | `list_workflows` | List workflows, optionally filtered | `status` (optional: `DRAFT`, `PENDING_APPROVAL`, `APPROVED`, `REJECTED`) | Returns an array, empty when nothing matches. Read-only. |
  171. | 7 | `create_workflow_draft` | Create a new draft | Required: `name`, `patient_id`, `source_system`, `destination_system`, `template`, `steps`. Optional: `appointment_ids`, `lab_result_ids`, `description` | Validates patient, systems, template, unique non-empty steps, and every referenced record (including patient ownership) before saving. Creates `DRAFT` with a generated `WF-SYN-NNN` id. Never submits or executes. |
  172. | 8 | `validate_workflow` | Read-only workflow validation | `workflow_id` (required) | Returns `{ valid, errors, warnings, workflow_id }`. Separates blocking errors from warnings. Writes nothing; does not change status, timestamps, or stored validation. |
  173. | 9 | `submit_workflow_for_approval` | Submit a draft for human review | `workflow_id` (required) | `DRAFT` only. Reloads the latest persisted record and revalidates it; invalid drafts remain `DRAFT` with errors returned. Valid drafts become `PENDING_APPROVAL` with a history entry. Never approves, executes, or publishes. |
  174. | 10 | `revise_workflow_draft` | Revise a rejected workflow | `workflow_id` (required) plus the full editable fields (`name`, `patient_id`, `source_system`, `destination_system`, `template`, `steps`; optional `appointment_ids`, `lab_result_ids`, `description`, `revision_note`) | `REJECTED` only. Preserves id and creation time, updates modification time, clears stale validation, keeps rejection context in history, validates new content, and returns `DRAFT` **without** submitting. |
  175. Supported synthetic systems: `EHR_SYNTH`, `LAB_SYNTH`, `SCHEDULER_SYNTH`,
  176. `REFERRAL_SYNTH`. Supported templates: `INTAKE_HANDOFF`, `LAB_REVIEW`,
  177. `REFERRAL_COORDINATION`.
  178. **Approval and rejection are not MCP tools.** There is no `approve_workflow`,
  179. `reject_workflow`, `list_patients`, `publish_workflow`, or `execute_workflow` tool.
  180. ### MCP Resources
  181. Resources are read-only, URI-addressable context. Reading one never writes a JSON file
  182. or changes workflow state.
  183. | URI | Kind | Content |
  184. | --- | --- | --- |
  185. | `integration://systems` | Static | Simulated data domains, the four fictional integration systems, simulator capabilities, and explicit statements that no real hospital or external API is connected |
  186. | `workflow://templates` | Static | The three implemented templates with source/destination systems, steps, and a machine-readable catalog |
  187. | `workflow://states` | Static | The actual state machine, transition ownership, validation rules, and the fact that `APPROVED` does not mean executed or published |
  188. | `patient://{id}` | Resource template | One synthetic patient by ID, retrieved through the existing patient service; unknown IDs return a resource error |
  189. Static resources are registered at fixed URIs. The patient resource is a
  190. `ResourceTemplate`: its URI pattern is `patient://{id}`, its discovery callback lists
  191. only real patient IDs from the synthetic dataset, and a read callback fills in `{id}`
  192. through `getPatient`. All resources return Markdown with a machine-readable JSON section.
  193. ```ts
  194. // Example client-side usage
  195. const { resources } = await client.listResources();
  196. const { resourceTemplates } = await client.listResourceTemplates();
  197. const patient = await client.readResource({ uri: "patient://PAT-SYN-001" });
  198. ```
  199. ### MCP Prompts
  200. Prompts return instruction messages to the connected AI client. They are **advisory
  201. text**: they do not call tools, modify data, or enforce the behavior of an AI model.
  202. | Prompt | Arguments | Purpose |
  203. | --- | --- | --- |
  204. | `create_patient_integration_workflow` | `patient_id` (required) | Retrieve patient → appointments/labs → templates, create a draft, validate it; submit immediately on success and stop, or leave it in `DRAFT` on failure and stop. Never approve, execute, or publish. |
  205. | `summarize_patient_information` | `patient_id` (required) | Summarize only real synthetic tool data, distinguish missing information from negative findings, invent nothing clinical, and label everything as fictional. |
  206. | `review_workflow_draft` | `workflow_id` (required) | Retrieve workflow, status, validation, templates, and patient context; report errors and warnings separately; never modify, approve, execute, or publish. Human decisions happen in the Admin CLI. |
  207. Arguments are required and validated; missing or invalid arguments produce an MCP error.
  208. The creation prompt deliberately has **no extra user-confirmation gate** before
  209. `submit_workflow_for_approval`: after successful validation the sequence is
  210. `create_workflow_draft → validate_workflow → submit_workflow_for_approval → stop`.
  211. ---
  212. ## Synthetic healthcare data
  213. The committed dataset in [data/](data/) is entirely fictional:
  214. | File | Contents |
  215. | --- | --- |
  216. | [patients.json](data/patients.json) | 3 synthetic patients, ids `PAT-SYN-001` … `PAT-SYN-003` |
  217. | [appointments.json](data/appointments.json) | 5 appointments, `APT-SYN-001` … `APT-SYN-005`, each with a `patient_id` |
  218. | [lab-results.json](data/lab-results.json) | 5 lab-style results, `LAB-SYN-001` … `LAB-SYN-005`, each with a `patient_id` |
  219. | [workflows.json](data/workflows.json) | 4 workflows, `WF-SYN-001` … `WF-SYN-004`, referencing patients and related records |
  220. A representative patient record:
  221. ```json
  222. {
  223. "id": "PAT-SYN-001",
  224. "display_name": "Avery Cedarwood",
  225. "date_of_birth": "1988-04-12",
  226. "status": "active",
  227. "created_at": "2026-09-01T08:00:00Z"
  228. }
  229. ```
  230. Appointments and lab results link to patients through `patient_id`; workflows link through
  231. `patient_id` plus arrays of `appointment_ids` and `lab_result_ids`. The initial fixtures
  232. are `WF-SYN-001` (`DRAFT`), `WF-SYN-002` (`PENDING_APPROVAL`), `WF-SYN-003` (`DRAFT`),
  233. and `WF-SYN-004` (`REJECTED`, with a synthetic rejection note). There is no `APPROVED`
  234. fixture.
  235. Repositories read arrays from JSON files and filter in memory. Writes use a temporary
  236. file plus atomic rename, and workflow read-modify-write operations are serialized by an
  237. in-process promise queue ([workflow.repository.ts](src/repositories/workflow.repository.ts)).
  238. Validation checks referential integrity — every referenced patient, appointment, and lab
  239. result must exist, and related records must belong to the workflow's patient. Repository
  240. tests verify those relationships and that filters never mutate the source files.
  241. > **Warning:** do not replace these files with real patient data. The safety of this
  242. > project depends on all records being fictional. Lab values and reference ranges are
  243. > illustrative demonstration values, not clinical results or medical advice.
  244. ---
  245. ## Workflow lifecycle and business logic
  246. The state machine is deliberately small and explicit:
  247. ```text
  248. DRAFT
  249. |
  250. | validate successfully and submit
  251. v
  252. PENDING_APPROVAL
  253. |
  254. +--------------------+
  255. | |
  256. | approve | reject
  257. v v
  258. APPROVED REJECTED
  259. |
  260. | revise
  261. v
  262. DRAFT
  263. ```
  264. | State | Meaning |
  265. | --- | --- |
  266. | `DRAFT` | Initial state for new workflows. Can be validated, submitted, or revised back to after rejection. Cannot be approved or rejected by the CLI. |
  267. | `PENDING_APPROVAL` | Submitted for human review. MCP tools are read-only here; only the Admin CLI can decide. |
  268. | `APPROVED` | A human approved the draft. This is a state value only — no execution or publishing occurs. |
  269. | `REJECTED` | A human rejected the draft with a reason. Only this state can be revised. |
  270. ### Transition responsibilities
  271. | Transition | Responsible component | Tool / command |
  272. | --- | --- | --- |
  273. | — → `DRAFT` | MCP Server | `create_workflow_draft` |
  274. | `DRAFT` → `PENDING_APPROVAL` | MCP Server | `submit_workflow_for_approval` |
  275. | `PENDING_APPROVAL` → `APPROVED` | Admin CLI | `npm run admin -- approve ...` |
  276. | `PENDING_APPROVAL` → `REJECTED` | Admin CLI | `npm run admin -- reject ...` |
  277. | `REJECTED` → `DRAFT` | MCP Server | `revise_workflow_draft` |
  278. All other transitions are rejected with a clear error. There is no `VALIDATING` state,
  279. no transition out of `APPROVED`, and no automatic execution step.
  280. ### Important semantics
  281. - **Validation is read-only.** `validate_workflow` returns `{ valid, errors, warnings,
  282. workflow_id }` and writes nothing — no status change, no timestamp change, no stored
  283. validation result.
  284. - **Submission revalidates.** `submit_workflow_for_approval` reloads the latest persisted
  285. record and validates it from scratch, so a draft whose references became invalid after
  286. an earlier validation cannot be submitted.
  287. - **Invalid drafts stay `DRAFT`.** Submission errors are returned without changing state.
  288. - **Successful submission sets `PENDING_APPROVAL`**, updates the timestamp, stores the
  289. validation result in `last_validation`, and appends a history entry.
  290. - **Revision is `REJECTED` → `DRAFT` only.** It preserves the workflow id and creation
  291. timestamp, updates the modification timestamp, clears stale validation information,
  292. retains the rejection note and history, validates the new content, and **does not
  293. submit automatically**. A revised workflow must be explicitly validated and submitted
  294. again as separate operations.
  295. ---
  296. ## Human-in-the-loop approval and Admin CLI
  297. Human approval exists to keep consequential decisions out of automated tool calls. The
  298. MCP server can prepare and submit work, but a person must decide whether a pending
  299. workflow is acceptable.
  300. The Admin CLI is a separate process ([cli.ts](src/admin/cli.ts)) using Node's built-in
  301. `node:util` `parseArgs` — no CLI framework dependency. It reuses domain types,
  302. repositories, and persistence, but is never imported or registered by the MCP server.
  303. ```bash
  304. npm run admin -- list
  305. npm run admin -- inspect WF-SYN-002
  306. npm run admin -- approve WF-SYN-002 --actor "admin@example.com"
  307. npm run admin -- reject WF-SYN-002 --actor "admin@example.com" --reason "Missing integration details"
  308. ```
  309. | Command | Behavior |
  310. | --- | --- |
  311. | `list` | Prints workflows in `PENDING_APPROVAL` with status and basic details |
  312. | `inspect <id>` | Prints fields, status, validation metadata, history, and audit events |
  313. | `approve <id> --actor <label>` | Transitions `PENDING_APPROVAL` → `APPROVED` only |
  314. | `reject <id> --actor <label> --reason <text>` | Transitions `PENDING_APPROVAL` → `REJECTED` only; requires a non-empty reason |
  315. Both decisions require a non-empty `--actor`. Invalid commands, missing IDs, empty
  316. arguments, and invalid transitions print a readable error and exit non-zero.
  317. **`--actor` is a self-declared audit label — not authentication or authorization.**
  318. Anyone who can run the CLI can supply any label. There is no identity verification,
  319. role check, signature, or multi-user access control. CLI output always states that the
  320. decision does not execute or publish the workflow.
  321. ---
  322. ## Audit events
  323. Each successful Admin CLI approval or rejection produces one event in
  324. `data/audit-events.json` (or under `MCP_DATA_DIR`). The file is separate from the
  325. workflow fixtures and ignored by Git ([.gitignore](.gitignore)).
  326. An event contains:
  327. | Field | Description |
  328. | --- | --- |
  329. | `workflow_id` | The affected workflow |
  330. | `action` | `APPROVED` or `REJECTED` |
  331. | `actor` | The self-declared `--actor` label |
  332. | `timestamp` | ISO 8601 timestamp |
  333. | `reason` | Present only for rejections |
  334. The repository ([audit.repository.ts](src/repositories/audit.repository.ts)) reads all
  335. existing events, appends the new one, and atomically rewrites the JSON file. Inspecting a
  336. workflow with the CLI shows its recorded events.
  337. **Limitations — be precise:** this is an *append-style* log implemented by read-all plus
  338. atomic rewrite, **not** strict append-only storage. There is no cryptographic hash chain,
  339. no tamper-detection guarantee, no cross-process file locking, and no durability guarantee
  340. beyond a local JSON file write. A crash between the workflow write and the audit write can
  341. leave the two inconsistent. Atomic rename alone does not guarantee full crash durability.
  342. ---
  343. ## Installation and setup
  344. ```bash
  345. git clone https://github.com/moein-71/Integration-Assistant-MCP-Based-Healthcare-Workflow-Simulator.git
  346. cd Integration-Assistant-MCP-Based-Healthcare-Workflow-Simulator
  347. node --version # must be >= 18
  348. npm --version
  349. npm install
  350. npm run typecheck
  351. npm run build
  352. npm test
  353. ```
  354. All scripts come from [package.json](package.json): `build`, `typecheck`, `test`, `smoke`,
  355. `server`, `admin`, and `demo`.
  356. **Environment variables:** the source uses one — `MCP_DATA_DIR`. When set, all repositories
  357. read and write JSON files in that directory instead of the default `data/` directory. The
  358. default path is resolved relative to the repository module, so the server works regardless
  359. of the current working directory. Tests and the demo set `MCP_DATA_DIR` to isolated
  360. temporary copies so committed fixtures are never modified. No `.env` file is required.
  361. ---
  362. ## Running the project
  363. | Command | Process | Behavior |
  364. | --- | --- | --- |
  365. | `npm run server` | Long-running server | Starts the MCP server over stdio. Normally spawned by a client; it produces no human-readable stdout output. Stop with Ctrl+C. |
  366. | `npm run smoke` | Terminates automatically | Spawns the server as a child process, performs the MCP handshake and ping, then exits. Prints a one-line success message. |
  367. | `npm run admin -- list` | Terminates automatically | Prints pending workflows; then exits. |
  368. | `npm run admin -- inspect WF-SYN-002` | Terminates automatically | Prints one workflow's details; then exits. |
  369. | `npm run admin -- approve WF-SYN-002 --actor "admin@example.com"` | Terminates automatically | Records approval if the workflow is pending; then exits. |
  370. | `npm run admin -- reject WF-SYN-002 --actor "admin@example.com" --reason "..."` | Terminates automatically | Records rejection with reason if pending; then exits. |
  371. | `npm run demo` | Terminates automatically | Runs the complete end-to-end flow against an isolated temporary data directory; prints progress and audit events; then exits. |
  372. The compiled server at `dist/server/index.js` behaves identically to the TypeScript entry
  373. point and can be launched from any working directory after `npm run build`.
  374. ---
  375. ## MCP client configuration
  376. The server launch itself has been verified with a real MCP client over stdio (including
  377. the compiled `dist` entry point from a different working directory). A configuration for
  378. a desktop MCP client is shown below as an **example** — this specific client application
  379. has not been tested by this project.
  380. Build first so the compiled entry point exists:
  381. ```bash
  382. npm run build
  383. ```
  384. Example configuration (replace the absolute path with your own checkout):
  385. ```json
  386. {
  387. "mcpServers": {
  388. "integration-assistant": {
  389. "command": "node",
  390. "args": [
  391. "/absolute/path/to/Integration-Assistant-MCP-Based-Healthcare-Workflow-Simulator/dist/server/index.js"
  392. ]
  393. }
  394. }
  395. }
  396. ```
  397. Notes:
  398. - Use the absolute path to `dist/server/index.js`; the client spawns `node` directly.
  399. - No working-directory setting is required because data paths are module-relative.
  400. - stdio is implicit in this configuration; the server speaks MCP JSON-RPC on stdout.
  401. - Restart the MCP client after changing its configuration.
  402. - Verify the connection by listing tools: you should see exactly the 10 tools named in
  403. the [MCP Tools](#mcp-tools) table, along with 3 resources, 1 template, and 3 prompts.
  404. ---
  405. ## Complete end-to-end example
  406. The reproducible version is `npm run demo`, which runs
  407. [scripts/end-to-end-demo.ts](scripts/end-to-end-demo.ts). It copies the fixtures into a
  408. temporary directory, so production data is untouched. Representative output from an
  409. actual run:
  410. ```text
  411. ===== 1-3. Connect, list tools, read the three static resources =====
  412. MCP tools (10): create_workflow_draft, get_lab_results, get_patient, ...
  413. Read integration://systems / workflow://templates / workflow://states
  414. ===== 4-5. Discover the patient template and read a synthetic patient =====
  415. Resource templates: patient://{id}
  416. { "id": "PAT-SYN-001", "display_name": "Avery Cedarwood", ... }
  417. ===== 6-8. Retrieve appointments/labs, create, validate and submit =====
  418. patient PAT-SYN-001: 2 appointments, 2 lab results
  419. created: WF-SYN-005 status=DRAFT
  420. validate: valid=true errors=0 warnings=0
  421. submit: WF-SYN-005 status=PENDING_APPROVAL
  422. ===== 9-12. Admin CLI list/inspect, approve; verify APPROVED =====
  423. $ npm run admin -- list
  424. Workflows awaiting approval (2):
  425. WF-SYN-002 PENDING_APPROVAL ...
  426. WF-SYN-005 PENDING_APPROVAL ...
  427. $ npm run admin -- inspect WF-SYN-005
  428. Workflow WF-SYN-005
  429. $ npm run admin -- approve WF-SYN-005 --actor "admin@example.com"
  430. APPROVED workflow WF-SYN-005 ...
  431. after approval: WF-SYN-005 status=APPROVED
  432. ```
  433. The demo inspects the **same runtime-generated id** returned by `create_workflow_draft`
  434. and asserts the CLI output contains it; `WF-SYN-005` above is only what that particular
  435. run produced.
  436. The second half demonstrates rejection and revision in the same isolated dataset:
  437. ```text
  438. ===== 13. Rejection and revision path =====
  439. created+submitted workflow: WF-SYN-006 status=PENDING_APPROVAL
  440. $ npm run admin -- reject WF-SYN-006 --actor "admin@example.com" --reason "Synthetic demo: handoff details need revision"
  441. REJECTED workflow WF-SYN-006 ...
  442. after rejection: WF-SYN-006 status=REJECTED
  443. revised: WF-SYN-006 status=DRAFT idPreserved=true createdAtPreserved=true
  444. updatedAtChanged=true lastValidationCleared=true
  445. rejectionNoteKept=true lastHistory=REJECTED->DRAFT
  446. revalidate: valid=true; resubmit (separate call): status=PENDING_APPROVAL
  447. ===== 14. Audit events =====
  448. APPROVED WF-SYN-005 actor=admin@example.com at=...
  449. REJECTED WF-SYN-006 actor=admin@example.com at=... reason="Synthetic demo: ..."
  450. ```
  451. Step by step, the flow is: connect client and server → read the three static resources →
  452. read `patient://PAT-SYN-001` → retrieve that patient's appointments and lab results →
  453. `create_workflow_draft` → `validate_workflow` → `submit_workflow_for_approval` → confirm
  454. `PENDING_APPROVAL` → Admin CLI `list` and `inspect` the new workflow → Admin CLI `approve`
  455. → confirm `APPROVED` → create and submit a second workflow → Admin CLI `reject` with a
  456. reason → `revise_workflow_draft` → confirm `DRAFT` and that nothing was auto-submitted →
  457. explicit `validate_workflow` and `submit_workflow_for_approval` → read audit events.
  458. Timestamps and generated ids differ between runs; no workflow is executed or published.
  459. ---
  460. ## Testing and quality assurance
  461. Run the full suite:
  462. ```bash
  463. npm test # Vitest
  464. npm run typecheck # strict TypeScript, no emit
  465. npm run build # production build to dist/
  466. npm run smoke # real stdio handshake and ping
  467. npm run demo # full end-to-end demonstration
  468. ```
  469. At the time of writing, `npm test` reports **7 test files and 94 passing tests** (0 skipped,
  470. 0 failing). Test files and what they verify:
  471. | Test area | What it proves |
  472. | --- | --- |
  473. | [tests/repositories/data.test.ts](tests/repositories/data.test.ts) | Fixture integrity, referential consistency, filters, empty results, and errors that never expose local paths |
  474. | [tests/services/workflow-lifecycle.test.ts](tests/services/workflow-lifecycle.test.ts) | Draft creation, validation rules, submission revalidation, and exact revision semantics including preservation rules |
  475. | [tests/smoke/stdio.test.ts](tests/smoke/stdio.test.ts) | A distinct child process answers a real MCP ping |
  476. | [tests/smoke/tools.test.ts](tests/smoke/tools.test.ts) | Exact 10-tool inventory, tool schemas, unknown-id errors, and read-only behavior |
  477. | [tests/smoke/workflow-tools.test.ts](tests/smoke/workflow-tools.test.ts) | Lifecycle tools over stdio, persistence across server restarts, and rejection of invalid transitions |
  478. | [tests/admin/admin-cli.test.ts](tests/admin/admin-cli.test.ts) | CLI commands, validation rules, audit events, and survival across process restarts |
  479. | [tests/resources-and-prompts.test.ts](tests/resources-and-prompts.test.ts) | Resource/prompt inventories, content accuracy, argument validation, and no side effects from reads |
  480. Tests use isolated temporary data directories and do not depend on execution order. They
  481. prove protocol behavior, state transitions, persistence, and validation logic. They do
  482. **not** prove security, production reliability, performance at scale, or the behavior of
  483. an arbitrary AI model consuming the prompts.
  484. ---
  485. ## Project structure
  486. ```text
  487. .
  488. ├── data/ Synthetic JSON fixtures (see data/README.md)
  489. │ ├── patients.json
  490. │ ├── appointments.json
  491. │ ├── lab-results.json
  492. │ └── workflows.json
  493. ├── src/
  494. │ ├── domain/ Entity types, lifecycle policy, result types, timestamps
  495. │ ├── repositories/ JSON access, atomic writes, write queue, audit events
  496. │ ├── services/ Validation, lifecycle, lookups, admin decisions
  497. │ ├── server/
  498. │ │ ├── index.ts Server entry point and capability registration
  499. │ │ ├── resources.ts Static resources + patient resource template
  500. │ │ ├── prompts.ts Three instruction prompts
  501. │ │ └── tools/ Ten MCP tool definitions and result formatting
  502. │ ├── client/smoke.ts Real MCP client smoke test
  503. │ └── admin/cli.ts Separate human Admin CLI (parseArgs)
  504. ├── tests/ Automated tests (see table above)
  505. │ └── support/mcp-client.ts Isolated-data stdio client helper
  506. ├── scripts/end-to-end-demo.ts Reproducible full demonstration
  507. ├── package.json / package-lock.json
  508. ├── tsconfig.json / tsconfig.build.json
  509. ├── .gitignore Ignores dist, node_modules, runtime audit log
  510. └── LICENSE MIT License
  511. ```
  512. ---
  513. ## Security, privacy, and limitations
  514. - **Synthetic data only.** No real patient records, identifiers, or clinical data exist
  515. here; all names, values, and reference ranges are invented for demonstration.
  516. - **No real integrations.** No hospital system, external healthcare API, or network
  517. request is involved.
  518. - **No workflow execution or publishing.** `APPROVED` records a human decision only.
  519. - **No CLI identity controls.** `--actor` is self-declared; there is no authentication or
  520. authorization and no multi-user access model.
  521. - **Basic local persistence.** JSON files with atomic rename and an in-process write
  522. queue; there is no database and no cross-process locking.
  523. - **Audit limitations.** Append-style read/rewrite, no hash chain or tamper detection, and
  524. possible inconsistency between workflow and audit writes after a crash.
  525. - **Advisory prompts.** Prompt text guides a client; it does not enforce tool permissions
  526. or guarantee model behavior.
  527. - **Prototype scope.** No production deployment guarantees, scalability claims, or
  528. regulatory/HIPAA compliance.
  529. ---
  530. ## Design decisions and future improvements
  531. **Why MCP?** It gives an AI client a standard way to discover capabilities and keeps the
  532. transport simple (stdio) and local. Tools, resources, and prompts separate operations,
  533. read-only context, and instructions cleanly.
  534. **Why JSON files?** For an MVP they are transparent, dependency-free, and easy to inspect
  535. and reset. Tests copy them into temporary directories for isolation.
  536. **Why is approval outside MCP?** Consequential decisions should require a human process
  537. that an AI client cannot call. The Admin CLI is that process.
  538. **Why is validation read-only and repeated on submission?** A validation result is a
  539. point-in-time observation. Revalidating the latest persisted record at submission time
  540. prevents stale validation from authorizing an invalid workflow.
  541. **Why an explicit state machine?** A small, enumerated set of states and transitions makes
  542. invalid operations obvious and testable, and prevents accidental execution semantics.
  543. ### Possible future improvements — NOT IMPLEMENTED
  544. - Database-backed persistence with transactions
  545. - Cross-process locking and stronger crash durability
  546. - Stronger audit integrity (hash chains, signing, tamper evidence)
  547. - Real authentication and role-based authorization
  548. - More extensive integration and fuzz testing
  549. - Production-grade healthcare API integrations (out of scope by design)
  550. - Observability and structured logging
  551. ---
  552. ## License and contribution
  553. Released under the MIT License. See [LICENSE](LICENSE) (Copyright © 2026 MOEIN-Bozorgi).
  554. Contributions are welcome in the ordinary GitHub workflow: fork the repository, create a
  555. feature branch, make your change, run `npm run typecheck`, `npm run build`, `npm test`, and
  556. `npm run smoke`, then open a pull request describing the change. Keep all data synthetic
  557. and preserve the MCP/Admin CLI separation and the explicit workflow state machine.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.