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.
Badge for your README
Markdown
[](/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
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
- # Integration Assistant — MCP-Based Healthcare Workflow Simulator
- A local, synthetic healthcare integration workflow simulator built with the official
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) SDK. It exposes a real
- MCP server over stdio with **10 tools**, **3 read-only resources**, **1 patient resource
- template**, and **3 prompts**, plus a **separate human Admin CLI** for approval and
- rejection decisions.
- **This project is an educational prototype, not a production healthcare system.** Every
- patient, appointment, laboratory-style result, workflow, and integration system is
- fictional. It does not connect to real hospitals, hospital information systems, or
- external healthcare APIs; it does not access real patient records; it does not execute
- healthcare workflows; and it does not publish integrations. `APPROVED` is only a recorded
- human decision — nothing is ever run or deployed.
- See [data/README.md](data/README.md) for details on the synthetic dataset.
- ---
- ## Table of contents
- - [What problem this demonstrates](#what-problem-this-demonstrates)
- - [Key features](#key-features)
- - [Technology stack and requirements](#technology-stack-and-requirements)
- - [Architecture overview](#architecture-overview)
- - [MCP implementation](#mcp-implementation)
- - [Synthetic healthcare data](#synthetic-healthcare-data)
- - [Workflow lifecycle and business logic](#workflow-lifecycle-and-business-logic)
- - [Human-in-the-loop approval and Admin CLI](#human-in-the-loop-approval-and-admin-cli)
- - [Audit events](#audit-events)
- - [Installation and setup](#installation-and-setup)
- - [Running the project](#running-the-project)
- - [MCP client configuration](#mcp-client-configuration)
- - [Complete end-to-end example](#complete-end-to-end-example)
- - [Testing and quality assurance](#testing-and-quality-assurance)
- - [Project structure](#project-structure)
- - [Security, privacy, and limitations](#security-privacy-and-limitations)
- - [Design decisions and future improvements](#design-decisions-and-future-improvements)
- - [License and contribution](#license-and-contribution)
- ---
- ## What problem this demonstrates
- Healthcare integration work usually involves moving information between systems such as
- electronic health records, scheduling tools, laboratories, and referral systems. In a real
- environment that work is tightly regulated, uses sensitive data, and requires human
- oversight before changes are accepted.
- This simulator models that shape of problem safely:
- - An AI assistant (an **MCP client**) can inspect fictional patients, appointments, lab
- results, and workflows through a controlled set of read-only and lifecycle tools.
- - The assistant can assemble a workflow draft from real synthetic records, validate it,
- and submit it for **human review**.
- - The assistant deliberately **cannot** approve, reject, execute, or publish anything.
- Those decisions belong to a separate human process (the Admin CLI).
- - A small, explicit state machine and audit event log make the lifecycle observable.
- MCP is used because it provides a standard, transport-friendly way for an AI client to
- discover tools, resources, and prompts from a server. Here the transport is stdio: the
- client spawns the server as a child process and speaks JSON-RPC over its standard input
- and output. That makes the integration realistic without needing a network service,
- database, or cloud account.
- ---
- ## Key features
- - **Real MCP communication** — a real client connects to a real server process over
- stdio using the official SDK; no in-process shortcuts.
- - **Synthetic healthcare data** — fictional patients, appointments, lab-style results,
- and workflows stored as JSON files.
- - **Read-only data retrieval** — tools for patients, appointments, lab results, and
- workflows; resource reads never modify data.
- - **Workflow lifecycle** — create drafts, validate them read-only, submit valid drafts
- for approval, and revise rejected workflows back to `DRAFT`.
- - **Separate human Admin CLI** — `list`, `inspect`, `approve`, and `reject` run in a
- different process and are never registered as MCP tools.
- - **Audit events** — approvals and rejections are recorded in a separate event file.
- - **MCP Resources** — three static context documents and a `patient://{id}` resource
- template backed by real synthetic patient data.
- - **MCP Prompts** — reusable instruction templates for workflow creation, patient
- summarization, and draft review.
- - **Automated tests** — 94 tests across 7 files, including real stdio integration tests.
- - **Reproducible demonstration** — `npm run demo` drives the whole flow against an
- isolated temporary data directory.
- ---
- ## Technology stack and requirements
- All versions below are pinned in [package.json](package.json) and
- [package-lock.json](package-lock.json).
- | Technology | Version | Role |
- | --- | --- | --- |
- | Node.js | `>=18` runtime requirement | Hosts both the server and client processes; verified on Node 26 |
- | npm | bundled with Node | Installs local dependencies and runs the npm scripts |
- | TypeScript | `5.9.3` | Strictly typed source (`strict: true`, `noUnusedLocals`, `noUnusedParameters`) |
- | `@modelcontextprotocol/sdk` | `1.32.2` | Official MCP SDK: `McpServer`, `StdioServerTransport`, `ResourceTemplate`, client APIs |
- | Zod | `4.6.7` | Runtime validation of tool and prompt arguments |
- | Vitest | `5.1.1` | Test runner (dev dependency) |
- | tsx | `4.23.15` | Runs TypeScript directly during development/tests (dev dependency) |
- | `@types/node` | `26.6.6` | Node type definitions (dev dependency) |
- The project uses ESM (`"type": "module"`), `NodeNext` module resolution, and an ES2022
- target. See [tsconfig.json](tsconfig.json) and [tsconfig.build.json](tsconfig.build.json).
- **Development environment:** Node.js 18 or newer, npm, and a POSIX-like shell for the
- documented commands. The code itself uses only Node built-ins plus the dependencies
- above, so it is platform-independent; the shell examples assume `bash`/`zsh`. No global
- packages are required. Write access to a temporary directory is needed by the tests and
- demo, which copy fixtures into isolated directories.
- ---
- ## Architecture overview
- ```mermaid
- flowchart LR
- subgraph CLIENT["MCP Client process"]
- MC["MCP Client<br/>smoke.ts / demo / external client"]
- end
- subgraph SERVER["MCP Server process (src/server/index.ts)"]
- ST["StdioServerTransport<br/>stdout: JSON-RPC only<br/>stderr: diagnostics"]
- REG["McpServer registration<br/>10 tools / 3 resources<br/>1 template / 3 prompts"]
- SVC["Domain and services<br/>validation, lifecycle, lookup"]
- REPO["Repositories<br/>JSON read/write, atomic replace<br/>in-process write queue"]
- end
- subgraph DATA["Synthetic JSON data"]
- DB[("data/patients.json<br/>data/appointments.json<br/>data/lab-results.json<br/>data/workflows.json")]
- end
- subgraph ADMIN["Separate Admin CLI process"]
- CLI["src/admin/cli.ts<br/>list / inspect / approve / reject"]
- ASVC["admin.service.ts<br/>state checks, decisions"]
- AUD[("data/audit-events.json")]
- end
- MC -->|"JSON-RPC over stdin/stdout"| ST
- ST --> REG
- REG --> SVC
- SVC --> REPO
- REPO --> DB
- CLI --> ASVC
- ASVC --> REPO
- ASVC --> AUD
- ```
- **Responsibilities**
- | Component | Responsibility |
- | --- | --- |
- | MCP Client | Discovers capabilities, calls tools, reads resources, requests prompts |
- | MCP Server ([index.ts](src/server/index.ts)) | Creates `McpServer`, registers tools/resources/prompts, connects stdio transport, handles shutdown |
- | Tool modules ([src/server/tools/](src/server/tools/)) | Input schemas, descriptions, and conversion of service results into MCP `CallToolResult` |
- | Resources ([resources.ts](src/server/resources.ts)) | Static context documents and the read-only patient resource template |
- | Prompts ([prompts.ts](src/server/prompts.ts)) | Instruction templates returned to the client; no execution |
- | Services ([src/services/](src/services/)) | Validation, workflow lifecycle, lookups, admin decisions |
- | Repositories ([src/repositories/](src/repositories/)) | JSON file access, atomic writes, in-process serialization, audit event storage |
- | Admin CLI ([cli.ts](src/admin/cli.ts)) | Human approval/rejection in a separate process |
- **Why is the Admin CLI separate?** Approval and rejection are trust decisions. Keeping
- them out of the MCP server means an AI client has no path — no tool, resource, or prompt
- — that can approve or reject a workflow. The MCP server never imports the admin service
- or the audit repository; the CLI is the only caller. This boundary is intentional and is
- enforced by the code structure and by tests that check the live tool inventory.
- **Persistence:** all state lives in JSON files. The default directory is resolved
- relative to the repository module (so it works from `src/` and compiled `dist/`); setting
- `MCP_DATA_DIR` overrides it. Writes go to a temporary file and are renamed into place.
- See [json-store.ts](src/repositories/json-store.ts).
- ---
- ## MCP implementation
- MCP is a protocol that lets a client discover and use capabilities exposed by a server.
- In this project:
- - The **server** ([index.ts](src/server/index.ts)) constructs an `McpServer`, registers
- capabilities, and attaches a `StdioServerTransport`.
- - The **client** (for example [smoke.ts](src/client/smoke.ts) or
- [end-to-end-demo.ts](scripts/end-to-end-demo.ts)) spawns the server with
- `process.execPath`, performs the MCP `initialize` handshake, and closes it when done.
- - **stdio transport** means request/response JSON-RPC messages travel over the child
- process's stdin/stdout. Therefore **stdout is reserved exclusively for the protocol**:
- server-side code contains no `console.log` or `stdout.write`. Diagnostics use
- `console.error`, which writes to stderr. Tests verify the server runs as a distinct
- child process and that the compiled `dist/server/index.js` works from any working
- directory.
- ### MCP Tools
- Exactly 10 tools are registered. Inputs are validated with Zod at runtime. Successful
- results use a `{ "notice": "...", "data": ... }` JSON text envelope; failures use MCP
- `isError: true` with a readable message, never a stack trace or local path.
- | # | Tool | Purpose | Input parameters | Important behavior |
- | --- | --- | --- | --- | --- |
- | 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. |
- | 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. |
- | 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. |
- | 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. |
- | 5 | `get_workflow` | Inspect one workflow | `workflow_id` (required) | Returns status, steps, references, `last_validation`, and history. Unknown ID → error. Read-only. |
- | 6 | `list_workflows` | List workflows, optionally filtered | `status` (optional: `DRAFT`, `PENDING_APPROVAL`, `APPROVED`, `REJECTED`) | Returns an array, empty when nothing matches. Read-only. |
- | 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. |
- | 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. |
- | 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. |
- | 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. |
- Supported synthetic systems: `EHR_SYNTH`, `LAB_SYNTH`, `SCHEDULER_SYNTH`,
- `REFERRAL_SYNTH`. Supported templates: `INTAKE_HANDOFF`, `LAB_REVIEW`,
- `REFERRAL_COORDINATION`.
- **Approval and rejection are not MCP tools.** There is no `approve_workflow`,
- `reject_workflow`, `list_patients`, `publish_workflow`, or `execute_workflow` tool.
- ### MCP Resources
- Resources are read-only, URI-addressable context. Reading one never writes a JSON file
- or changes workflow state.
- | URI | Kind | Content |
- | --- | --- | --- |
- | `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 |
- | `workflow://templates` | Static | The three implemented templates with source/destination systems, steps, and a machine-readable catalog |
- | `workflow://states` | Static | The actual state machine, transition ownership, validation rules, and the fact that `APPROVED` does not mean executed or published |
- | `patient://{id}` | Resource template | One synthetic patient by ID, retrieved through the existing patient service; unknown IDs return a resource error |
- Static resources are registered at fixed URIs. The patient resource is a
- `ResourceTemplate`: its URI pattern is `patient://{id}`, its discovery callback lists
- only real patient IDs from the synthetic dataset, and a read callback fills in `{id}`
- through `getPatient`. All resources return Markdown with a machine-readable JSON section.
- ```ts
- // Example client-side usage
- const { resources } = await client.listResources();
- const { resourceTemplates } = await client.listResourceTemplates();
- const patient = await client.readResource({ uri: "patient://PAT-SYN-001" });
- ```
- ### MCP Prompts
- Prompts return instruction messages to the connected AI client. They are **advisory
- text**: they do not call tools, modify data, or enforce the behavior of an AI model.
- | Prompt | Arguments | Purpose |
- | --- | --- | --- |
- | `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. |
- | `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. |
- | `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. |
- Arguments are required and validated; missing or invalid arguments produce an MCP error.
- The creation prompt deliberately has **no extra user-confirmation gate** before
- `submit_workflow_for_approval`: after successful validation the sequence is
- `create_workflow_draft → validate_workflow → submit_workflow_for_approval → stop`.
- ---
- ## Synthetic healthcare data
- The committed dataset in [data/](data/) is entirely fictional:
- | File | Contents |
- | --- | --- |
- | [patients.json](data/patients.json) | 3 synthetic patients, ids `PAT-SYN-001` … `PAT-SYN-003` |
- | [appointments.json](data/appointments.json) | 5 appointments, `APT-SYN-001` … `APT-SYN-005`, each with a `patient_id` |
- | [lab-results.json](data/lab-results.json) | 5 lab-style results, `LAB-SYN-001` … `LAB-SYN-005`, each with a `patient_id` |
- | [workflows.json](data/workflows.json) | 4 workflows, `WF-SYN-001` … `WF-SYN-004`, referencing patients and related records |
- A representative patient record:
- ```json
- {
- "id": "PAT-SYN-001",
- "display_name": "Avery Cedarwood",
- "date_of_birth": "1988-04-12",
- "status": "active",
- "created_at": "2026-09-01T08:00:00Z"
- }
- ```
- Appointments and lab results link to patients through `patient_id`; workflows link through
- `patient_id` plus arrays of `appointment_ids` and `lab_result_ids`. The initial fixtures
- are `WF-SYN-001` (`DRAFT`), `WF-SYN-002` (`PENDING_APPROVAL`), `WF-SYN-003` (`DRAFT`),
- and `WF-SYN-004` (`REJECTED`, with a synthetic rejection note). There is no `APPROVED`
- fixture.
- Repositories read arrays from JSON files and filter in memory. Writes use a temporary
- file plus atomic rename, and workflow read-modify-write operations are serialized by an
- in-process promise queue ([workflow.repository.ts](src/repositories/workflow.repository.ts)).
- Validation checks referential integrity — every referenced patient, appointment, and lab
- result must exist, and related records must belong to the workflow's patient. Repository
- tests verify those relationships and that filters never mutate the source files.
- > **Warning:** do not replace these files with real patient data. The safety of this
- > project depends on all records being fictional. Lab values and reference ranges are
- > illustrative demonstration values, not clinical results or medical advice.
- ---
- ## Workflow lifecycle and business logic
- The state machine is deliberately small and explicit:
- ```text
- DRAFT
- |
- | validate successfully and submit
- v
- PENDING_APPROVAL
- |
- +--------------------+
- | |
- | approve | reject
- v v
- APPROVED REJECTED
- |
- | revise
- v
- DRAFT
- ```
- | State | Meaning |
- | --- | --- |
- | `DRAFT` | Initial state for new workflows. Can be validated, submitted, or revised back to after rejection. Cannot be approved or rejected by the CLI. |
- | `PENDING_APPROVAL` | Submitted for human review. MCP tools are read-only here; only the Admin CLI can decide. |
- | `APPROVED` | A human approved the draft. This is a state value only — no execution or publishing occurs. |
- | `REJECTED` | A human rejected the draft with a reason. Only this state can be revised. |
- ### Transition responsibilities
- | Transition | Responsible component | Tool / command |
- | --- | --- | --- |
- | — → `DRAFT` | MCP Server | `create_workflow_draft` |
- | `DRAFT` → `PENDING_APPROVAL` | MCP Server | `submit_workflow_for_approval` |
- | `PENDING_APPROVAL` → `APPROVED` | Admin CLI | `npm run admin -- approve ...` |
- | `PENDING_APPROVAL` → `REJECTED` | Admin CLI | `npm run admin -- reject ...` |
- | `REJECTED` → `DRAFT` | MCP Server | `revise_workflow_draft` |
- All other transitions are rejected with a clear error. There is no `VALIDATING` state,
- no transition out of `APPROVED`, and no automatic execution step.
- ### Important semantics
- - **Validation is read-only.** `validate_workflow` returns `{ valid, errors, warnings,
- workflow_id }` and writes nothing — no status change, no timestamp change, no stored
- validation result.
- - **Submission revalidates.** `submit_workflow_for_approval` reloads the latest persisted
- record and validates it from scratch, so a draft whose references became invalid after
- an earlier validation cannot be submitted.
- - **Invalid drafts stay `DRAFT`.** Submission errors are returned without changing state.
- - **Successful submission sets `PENDING_APPROVAL`**, updates the timestamp, stores the
- validation result in `last_validation`, and appends a history entry.
- - **Revision is `REJECTED` → `DRAFT` only.** It preserves the workflow id and creation
- timestamp, updates the modification timestamp, clears stale validation information,
- retains the rejection note and history, validates the new content, and **does not
- submit automatically**. A revised workflow must be explicitly validated and submitted
- again as separate operations.
- ---
- ## Human-in-the-loop approval and Admin CLI
- Human approval exists to keep consequential decisions out of automated tool calls. The
- MCP server can prepare and submit work, but a person must decide whether a pending
- workflow is acceptable.
- The Admin CLI is a separate process ([cli.ts](src/admin/cli.ts)) using Node's built-in
- `node:util` `parseArgs` — no CLI framework dependency. It reuses domain types,
- repositories, and persistence, but is never imported or registered by the MCP server.
- ```bash
- npm run admin -- list
- npm run admin -- inspect WF-SYN-002
- npm run admin -- approve WF-SYN-002 --actor "admin@example.com"
- npm run admin -- reject WF-SYN-002 --actor "admin@example.com" --reason "Missing integration details"
- ```
- | Command | Behavior |
- | --- | --- |
- | `list` | Prints workflows in `PENDING_APPROVAL` with status and basic details |
- | `inspect <id>` | Prints fields, status, validation metadata, history, and audit events |
- | `approve <id> --actor <label>` | Transitions `PENDING_APPROVAL` → `APPROVED` only |
- | `reject <id> --actor <label> --reason <text>` | Transitions `PENDING_APPROVAL` → `REJECTED` only; requires a non-empty reason |
- Both decisions require a non-empty `--actor`. Invalid commands, missing IDs, empty
- arguments, and invalid transitions print a readable error and exit non-zero.
- **`--actor` is a self-declared audit label — not authentication or authorization.**
- Anyone who can run the CLI can supply any label. There is no identity verification,
- role check, signature, or multi-user access control. CLI output always states that the
- decision does not execute or publish the workflow.
- ---
- ## Audit events
- Each successful Admin CLI approval or rejection produces one event in
- `data/audit-events.json` (or under `MCP_DATA_DIR`). The file is separate from the
- workflow fixtures and ignored by Git ([.gitignore](.gitignore)).
- An event contains:
- | Field | Description |
- | --- | --- |
- | `workflow_id` | The affected workflow |
- | `action` | `APPROVED` or `REJECTED` |
- | `actor` | The self-declared `--actor` label |
- | `timestamp` | ISO 8601 timestamp |
- | `reason` | Present only for rejections |
- The repository ([audit.repository.ts](src/repositories/audit.repository.ts)) reads all
- existing events, appends the new one, and atomically rewrites the JSON file. Inspecting a
- workflow with the CLI shows its recorded events.
- **Limitations — be precise:** this is an *append-style* log implemented by read-all plus
- atomic rewrite, **not** strict append-only storage. There is no cryptographic hash chain,
- no tamper-detection guarantee, no cross-process file locking, and no durability guarantee
- beyond a local JSON file write. A crash between the workflow write and the audit write can
- leave the two inconsistent. Atomic rename alone does not guarantee full crash durability.
- ---
- ## Installation and setup
- ```bash
- 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.
- ---
- ## Running the project
- | Command | Process | Behavior |
- | --- | --- | --- |
- | `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. |
- | `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. |
- | `npm run admin -- list` | Terminates automatically | Prints pending workflows; then exits. |
- | `npm run admin -- inspect WF-SYN-002` | Terminates automatically | Prints one workflow's details; then exits. |
- | `npm run admin -- approve WF-SYN-002 --actor "admin@example.com"` | Terminates automatically | Records approval if the workflow is pending; then exits. |
- | `npm run admin -- reject WF-SYN-002 --actor "admin@example.com" --reason "..."` | Terminates automatically | Records rejection with reason if pending; then exits. |
- | `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. |
- The compiled server at `dist/server/index.js` behaves identically to the TypeScript entry
- point and can be launched from any working directory after `npm run build`.
- ---
- ## MCP client configuration
- The server launch itself has been verified with a real MCP client over stdio (including
- the compiled `dist` entry point from a different working directory). A configuration for
- a desktop MCP client is shown below as an **example** — this specific client application
- has not been tested by this project.
- Build first so the compiled entry point exists:
- ```bash
- npm run build
- ```
- Example configuration (replace the absolute path with your own checkout):
- ```json
- {
- "mcpServers": {
- "integration-assistant": {
- "command": "node",
- "args": [
- "/absolute/path/to/Integration-Assistant-MCP-Based-Healthcare-Workflow-Simulator/dist/server/index.js"
- ]
- }
- }
- }
- ```
- Notes:
- - Use the absolute path to `dist/server/index.js`; the client spawns `node` directly.
- - No working-directory setting is required because data paths are module-relative.
- - stdio is implicit in this configuration; the server speaks MCP JSON-RPC on stdout.
- - Restart the MCP client after changing its configuration.
- - Verify the connection by listing tools: you should see exactly the 10 tools named in
- the [MCP Tools](#mcp-tools) table, along with 3 resources, 1 template, and 3 prompts.
- ---
- ## Complete end-to-end example
- The reproducible version is `npm run demo`, which runs
- [scripts/end-to-end-demo.ts](scripts/end-to-end-demo.ts). It copies the fixtures into a
- temporary directory, so production data is untouched. Representative output from an
- actual run:
- ```text
- ===== 1-3. Connect, list tools, read the three static resources =====
- MCP tools (10): create_workflow_draft, get_lab_results, get_patient, ...
- Read integration://systems / workflow://templates / workflow://states
- ===== 4-5. Discover the patient template and read a synthetic patient =====
- Resource templates: patient://{id}
- { "id": "PAT-SYN-001", "display_name": "Avery Cedarwood", ... }
- ===== 6-8. Retrieve appointments/labs, create, validate and submit =====
- patient PAT-SYN-001: 2 appointments, 2 lab results
- created: WF-SYN-005 status=DRAFT
- validate: valid=true errors=0 warnings=0
- submit: WF-SYN-005 status=PENDING_APPROVAL
- ===== 9-12. Admin CLI list/inspect, approve; verify APPROVED =====
- $ npm run admin -- list
- Workflows awaiting approval (2):
- WF-SYN-002 PENDING_APPROVAL ...
- WF-SYN-005 PENDING_APPROVAL ...
- $ npm run admin -- inspect WF-SYN-005
- Workflow WF-SYN-005
- $ npm run admin -- approve WF-SYN-005 --actor "admin@example.com"
- APPROVED workflow WF-SYN-005 ...
- after approval: WF-SYN-005 status=APPROVED
- ```
- The demo inspects the **same runtime-generated id** returned by `create_workflow_draft`
- and asserts the CLI output contains it; `WF-SYN-005` above is only what that particular
- run produced.
- The second half demonstrates rejection and revision in the same isolated dataset:
- ```text
- ===== 13. Rejection and revision path =====
- created+submitted workflow: WF-SYN-006 status=PENDING_APPROVAL
- $ npm run admin -- reject WF-SYN-006 --actor "admin@example.com" --reason "Synthetic demo: handoff details need revision"
- REJECTED workflow WF-SYN-006 ...
- after rejection: WF-SYN-006 status=REJECTED
- revised: WF-SYN-006 status=DRAFT idPreserved=true createdAtPreserved=true
- updatedAtChanged=true lastValidationCleared=true
- rejectionNoteKept=true lastHistory=REJECTED->DRAFT
- revalidate: valid=true; resubmit (separate call): status=PENDING_APPROVAL
- ===== 14. Audit events =====
- APPROVED WF-SYN-005 actor=admin@example.com at=...
- REJECTED WF-SYN-006 actor=admin@example.com at=... reason="Synthetic demo: ..."
- ```
- Step by step, the flow is: connect client and server → read the three static resources →
- read `patient://PAT-SYN-001` → retrieve that patient's appointments and lab results →
- `create_workflow_draft` → `validate_workflow` → `submit_workflow_for_approval` → confirm
- `PENDING_APPROVAL` → Admin CLI `list` and `inspect` the new workflow → Admin CLI `approve`
- → confirm `APPROVED` → create and submit a second workflow → Admin CLI `reject` with a
- reason → `revise_workflow_draft` → confirm `DRAFT` and that nothing was auto-submitted →
- explicit `validate_workflow` and `submit_workflow_for_approval` → read audit events.
- Timestamps and generated ids differ between runs; no workflow is executed or published.
- ---
- ## Testing and quality assurance
- Run the full suite:
- ```bash
- npm test # Vitest
- npm run typecheck # strict TypeScript, no emit
- npm run build # production build to dist/
- npm run smoke # real stdio handshake and ping
- npm run demo # full end-to-end demonstration
- ```
- At the time of writing, `npm test` reports **7 test files and 94 passing tests** (0 skipped,
- 0 failing). Test files and what they verify:
- | Test area | What it proves |
- | --- | --- |
- | [tests/repositories/data.test.ts](tests/repositories/data.test.ts) | Fixture integrity, referential consistency, filters, empty results, and errors that never expose local paths |
- | [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 |
- | [tests/smoke/stdio.test.ts](tests/smoke/stdio.test.ts) | A distinct child process answers a real MCP ping |
- | [tests/smoke/tools.test.ts](tests/smoke/tools.test.ts) | Exact 10-tool inventory, tool schemas, unknown-id errors, and read-only behavior |
- | [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 |
- | [tests/admin/admin-cli.test.ts](tests/admin/admin-cli.test.ts) | CLI commands, validation rules, audit events, and survival across process restarts |
- | [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 |
- Tests use isolated temporary data directories and do not depend on execution order. They
- prove protocol behavior, state transitions, persistence, and validation logic. They do
- **not** prove security, production reliability, performance at scale, or the behavior of
- an arbitrary AI model consuming the prompts.
- ---
- ## Project structure
- ```text
- .
- ├── data/ Synthetic JSON fixtures (see data/README.md)
- │ ├── patients.json
- │ ├── appointments.json
- │ ├── lab-results.json
- │ └── workflows.json
- ├── src/
- │ ├── domain/ Entity types, lifecycle policy, result types, timestamps
- │ ├── repositories/ JSON access, atomic writes, write queue, audit events
- │ ├── services/ Validation, lifecycle, lookups, admin decisions
- │ ├── server/
- │ │ ├── index.ts Server entry point and capability registration
- │ │ ├── resources.ts Static resources + patient resource template
- │ │ ├── prompts.ts Three instruction prompts
- │ │ └── tools/ Ten MCP tool definitions and result formatting
- │ ├── client/smoke.ts Real MCP client smoke test
- │ └── admin/cli.ts Separate human Admin CLI (parseArgs)
- ├── tests/ Automated tests (see table above)
- │ └── support/mcp-client.ts Isolated-data stdio client helper
- ├── scripts/end-to-end-demo.ts Reproducible full demonstration
- ├── package.json / package-lock.json
- ├── tsconfig.json / tsconfig.build.json
- ├── .gitignore Ignores dist, node_modules, runtime audit log
- └── LICENSE MIT License
- ```
- ---
- ## Security, privacy, and limitations
- - **Synthetic data only.** No real patient records, identifiers, or clinical data exist
- here; all names, values, and reference ranges are invented for demonstration.
- - **No real integrations.** No hospital system, external healthcare API, or network
- request is involved.
- - **No workflow execution or publishing.** `APPROVED` records a human decision only.
- - **No CLI identity controls.** `--actor` is self-declared; there is no authentication or
- authorization and no multi-user access model.
- - **Basic local persistence.** JSON files with atomic rename and an in-process write
- queue; there is no database and no cross-process locking.
- - **Audit limitations.** Append-style read/rewrite, no hash chain or tamper detection, and
- possible inconsistency between workflow and audit writes after a crash.
- - **Advisory prompts.** Prompt text guides a client; it does not enforce tool permissions
- or guarantee model behavior.
- - **Prototype scope.** No production deployment guarantees, scalability claims, or
- regulatory/HIPAA compliance.
- ---
- ## Design decisions and future improvements
- **Why MCP?** It gives an AI client a standard way to discover capabilities and keeps the
- transport simple (stdio) and local. Tools, resources, and prompts separate operations,
- read-only context, and instructions cleanly.
- **Why JSON files?** For an MVP they are transparent, dependency-free, and easy to inspect
- and reset. Tests copy them into temporary directories for isolation.
- **Why is approval outside MCP?** Consequential decisions should require a human process
- that an AI client cannot call. The Admin CLI is that process.
- **Why is validation read-only and repeated on submission?** A validation result is a
- point-in-time observation. Revalidating the latest persisted record at submission time
- prevents stale validation from authorizing an invalid workflow.
- **Why an explicit state machine?** A small, enumerated set of states and transitions makes
- invalid operations obvious and testable, and prevents accidental execution semantics.
- ### Possible future improvements — NOT IMPLEMENTED
- - Database-backed persistence with transactions
- - Cross-process locking and stronger crash durability
- - Stronger audit integrity (hash chains, signing, tamper evidence)
- - Real authentication and role-based authorization
- - More extensive integration and fuzz testing
- - Production-grade healthcare API integrations (out of scope by design)
- - Observability and structured logging
- ---
- ## License and contribution
- Released under the MIT License. See [LICENSE](LICENSE) (Copyright © 2026 MOEIN-Bozorgi).
- Contributions are welcome in the ordinary GitHub workflow: fork the repository, create a
- feature branch, make your change, run `npm run typecheck`, `npm run build`, `npm test`, and
- `npm run smoke`, then open a pull request describing the change. Keep all data synthetic
- and preserve the MCP/Admin CLI separation and the explicit workflow state machine.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.