health-record-mcp - GitLite

KO | EN

gitlite — search

#claude-code #self-hosted #electron #ruby #anthropic #privacy #chatgpt #kotlin #list #rust

health-record-mcp

(★ 85)

Connect to an EHR and make clinical data available via MCP

File Explorer

ZIP Download

- - build-and-package.yml
- - .gitignore
  - 1
  - bun.lock
  - fix-client-v2.patch
  - fix-stop-comms.patch
  - index.ts
  - p
  - package.json
  - README.md
  - tsconfig.json
- - test-processors.ts
- - index.ts
- a2a_docs.md
- bun.lock
- package.json
- README.md
- tsconfig.json
- - authorize.html
  - index.html
  - install.html
  - intralib.js
  - portal.js
- - server.ts
- .gitignore
- bun.lock
- mcp.md
- package.json
- tsconfig.json
- build-ehretriever.ts
- test-fhirToPlaintext.ts
- test-grep.ts
- - dataFlow.test.ts
- cli.ts
- config.ts
- dbUtils.ts
- fhirSearchQueries.ts
- fhirToPlaintext.ts
- http.ts
- IntraBrowserTransport.ts
- oauth.ts
- README.md
- sessionUtils.ts
- sse.ts
- tools-browser-entry.ts
- tools.ts
- types.ts
- utils.ts
- - epic-sandbox.json
  - epic.json
  - index.html
  - process-brands.ts
  - user-access-brands-endpoint-bundle-epic-sandbox.json
  - user-access-brands-endpoint-bundle-epic.json
- db-picker.html
- db-picker.js
- ehretriever.html
- ehretriever_caller.html
- overview.png
.gitignore
bun.lock
clientFhirUtils.ts
clientTypes.ts
config.claude.json
config.epic-gh-pages.json
config.epicprod.json
config.epicsandbox.json
config.jmandel.json
config.smartsandbox.json
config.stdio.json
Dockerfile
ehretriever.ts
LICENSE.txt
opener.html
package.json
README.md
sample-config.json

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`bun run`

View Details ▼

Execute a JavaScript/TypeScript file, or a script from `package.json`.

bun run {{script_name}}

Run a script defined in `package.json`:

bun run {{path/to/file.ts}}

Run a JavaScript or TypeScript file directly:

bun run --watch {{path/to/file.ts}}

Run a file in "watch" mode (restarts automatically when the file changes):

# Project Badges

EHR Tools Overview

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

https://youtu.be/K0t6MRyIqZU?si=Mz4d65DcAD3i2YbO

This project acts as a specialized server providing tools for Large Language Models (LLMs) and other AI agents to interact with Electronic Health Records (EHRs). It leverages the **SMART on FHIR** standard for secure data access and the **Model Context Protocol (MCP)** to expose the tools.

Think of it as a secure gateway and toolkit enabling AI to safely access and analyze patient data from diverse EHR systems.

## The Core Idea

The system works in three main stages:

1.  **SMART on FHIR Client (Implemented within this project):** Connects securely to an EHR using the standard SMART App Launch framework. It extracts a wide range of patient information, including both structured data (like conditions, medications, labs) and unstructured clinical notes or attachments.
2.  **MCP Server (This Project):** Takes the extracted EHR data and makes it available through a set of powerful tools accessible via the Model Context Protocol. These tools allow external systems (like AI models) to query and analyze the data without needing direct access to the EHR itself.
3.  **AI / LLM Interface (External Consumer):** An AI agent or Large Language Model connects to the MCP Server and uses the provided tools to "ask questions" about the patient's record, perform searches, or run custom analyses.

## Available Tools

The MCP Server offers several tools for interacting with the loaded EHR data:

*   `grep_record`: Performs text or regular expression searches across *all* parts of the fetched record (structured FHIR data + text from notes/attachments). Ideal for finding keywords or specific mentions (e.g., "diabetes", "aspirin").
*   `query_record`: Executes read-only SQL `SELECT` queries directly against the structured FHIR data. Useful for precise lookups based on known FHIR resource structures (e.g., finding specific lab results by LOINC code).
*   `eval_record`: Executes custom JavaScript code directly on the fetched data (FHIR resources + attachments). Offers maximum flexibility for complex calculations, combining data from multiple sources, or custom formatting.

This setup allows AI tools to leverage comprehensive EHR data through a standardized and secure interface.

*(Developer setup and usage details can be found within the codebase and specific module documentation.)*

---

## Components & Usage

This project offers different ways to fetch EHR data and expose it via MCP tools:

### 1. Standalone SMART on FHIR Web Client

This project includes a self-contained web application that allows users to connect to their EHR via SMART on FHIR and fetch their data.

*   **Hosted Version:** You can use a publicly hosted version at: \
    [`https://mcp.fhir.me/ehr-connect#deliver-to-opener:$origin`](https://mcp.fhir.me/ehr-connect#deliver-to-opener:$origin) \
    (Replace `$origin` with the actual origin of the window that opens this link).
*   **Filtering Brands (`?brandTags`):** You can filter the list of EHR providers shown on the connection page by adding the `brandTags` query parameter to the URL. Provide a comma-separated list of tags. Only brands matching *all* provided tags (from their configuration in `brandFiles`) will be displayed.
    It supports both OR (comma-separated) and AND (caret `^` separated) logic, with AND taking precedence.
    *   `?brandTags=epic,sandbox`: Shows brands tagged with `epic` OR `sandbox`.
    *   `?brandTags=epic^dev`: Shows brands tagged with both `epic` AND `dev`.
    *   `?brandTags=epic^dev,sandbox^prod`: Shows brands tagged with (`epic` AND `dev`) OR (`sandbox` AND `prod`).
    *   If the parameter is omitted, it defaults to showing brands tagged with `prod`.
    *   Example: `.../ehr-connect?brandTags=hospital^us`: Shows brands tagged with `hospital` AND `us`.
*   **How it Works:** When opened, this page prompts the user to select their EHR provider. It then initiates the standard SMART App Launch flow, redirecting the user to their EHR's login page. After successful authentication and authorization, the client fetches a comprehensive set of FHIR resources (Patient, Conditions, Observations, Medications, Documents, etc.) and attempts to extract plaintext from any associated attachments (like PDFs, RTF, HTML found in `DocumentReference`).
*   **Data Output (`ClientFullEHR`):** Once fetching is complete, the client gathers all the data into a `ClientFullEHR` JSON object. This object contains:
    *   `fhir`: A dictionary where keys are FHIR resource types (e.g., "Patient") and values are arrays of the corresponding FHIR resources.
    *   `attachments`: An array of processed attachment objects, each including metadata (source resource, path, content type) and the content itself (`contentBase64` for raw data, `contentPlaintext` for extracted text).
*   **Data Delivery:** If opened with the `#deliver-to-opener:$origin` hash, the client will prompt the user for confirmation and then send the `ClientFullEHR` object back to the window that opened it using `window.opener.postMessage(data, targetOrigin)`.

### 2. Local MCP Server via Stdio (`src/cli.ts`)

This mode is ideal for running the MCP server locally, often used with tools like Cursor or other command-line AI clients.

*   **Two-Step Process:**
    1.  **Fetch Data to Database:** First, run the command-line interface with the `--create-db` and `--db` flags. This starts a temporary web server and uses the same SMART on FHIR web client logic described above to fetch data. Instead of sending the data via `postMessage`, it saves the `ClientFullEHR` data into a local SQLite database file.
        ```bash
        # Example: Fetch data and save to data/my_record.sqlite
        bun run src/cli.ts --create-db --db ./data/my_record.sqlite
        ```
        Follow the prompts (opening a link in your browser) to connect to your EHR.
    2.  **Run MCP Server:** Once the database file is created, run the CLI again, pointing only to the database file. This loads the data into memory and starts the MCP server, listening for commands on standard input/output.
        ```bash
        # Example: Start the MCP server using the saved data
        bun run src/cli.ts --db ./data/my_record.sqlite
        ```
    *   **Configuration (`config.*.json`):** This process relies on a configuration file (e.g., `config.epicsandbox.json`) which defines available EHR brands/endpoints in a `brandFiles` array. Each entry in this array specifies the brand's details, including:
        *   `url`: Path/URL to the brand definition file (like `static/brands/epic-sandbox.json`).
        *   `tags`: An array of strings (e.g., `["epic", "sandbox"]`) used for categorization or filtering.
        *   `vendorConfig`: Contains SMART on FHIR client details (`clientId`, `scopes`).
*   **Client Configuration (e.g., Cursor):** Configure your MCP client to execute this command. **Crucially, use absolute paths** for both `src/cli.ts` and the database file.
    ```json
    {
      "mcpServers": {
        "local-ehr": {
          "name": "Local EHR Search",
          "command": "bun", // Or the absolute path to bun
          "args": [
              "/home/user/projects/smart-mcp/src/cli.ts", // Absolute path to cli.ts
              "--db",
              "/home/user/projects/smart-mcp/data/my_record.sqlite" // Absolute path to DB file
            ]
        }
      }
    }
    ```

### 3. Full MCP Server via SSE (`src/sse.ts` / `index.ts`)

This mode runs a persistent server suitable for scenarios where multiple clients might connect over the network. It uses Server-Sent Events (SSE) for the MCP communication channel.

*   **Authentication:** Client authentication relies on OAuth 2.1, as specified by the Model Context Protocol. The server provides standard endpoints (`/authorize`, `/token`, `/register`, etc.).
*   **Data Fetch:** When a client initiates an OAuth connection, the server handles the SMART on FHIR flow *itself*, fetches the `ClientFullEHR` data *during* the authorization process, and keeps it in memory (or a persisted session) for the duration of the client's connection.
*   **Status:** While functional, the MCP specification for OAuth 2.1 client interaction is still evolving. Client support for this authentication method is **extremely limited** at present, making it difficult to test this mode with standard clients outside of specialized developer or debugging tools. This SSE mode should be considered **experimental**.