Smart EHR MCP 服务器 (Bun 实现)

是否一直希望你的 AI 工具能够安全地窥探电子健康记录 (EHR)？这个项目让它成为现实！它是一个模型上下文协议 (MCP) 服务器，使用 SMART on FHIR 的强大功能将 AI 代理和其他 MCP 客户端连接到 EHR。

可以把它想象成 EHR 数据的通用适配器和工具包。

它能做什么？

• 连接到（几乎）任何 EHR： 如果 EHR 支持标准的 SMART on FHIR 协议（并且大多数现代 EHR 都支持），那么这个服务器很可能可以与它通信。它使用 SMART App Launch 标准处理安全握手。
• 获取完整的故事： 它不仅仅获取过敏史和药物信息。它会提取各种结构化的 FHIR 数据（病症、观察结果、程序等），并且还会深入挖掘链接的临床笔记和附件（例如 DocumentReference 或其他资源中找到的 PDF、文本文件、RTF、HTML）。它甚至会尽力从这些附件中提取纯文本，以便你的工具可以读取它们。
• 提供强大的工具： 获取数据后，它提供三个方便的 MCP 工具来处理数据：
  • grep_record：用于搜索所有内容的首选工具 - 结构化数据和笔记文本 - 查找关键字或模式（使用文本或正则表达式）。在任何地方查找提及的“糖尿病”或“阿司匹林”。
  • query_record：适用于 SQL 爱好者。直接对结构化的 FHIR 数据运行只读 SELECT 查询（这些数据会被加载到临时 SQLite 数据库中）。
  • eval_record：高级用户的选择。借助 Lodash，直接在获取的数据（FHIR 资源 + 附件）上执行自定义 JavaScript 代码片段。非常适合复杂的分析或数据处理。

魔法是如何发生的？（两种方式）

你可以通过两种主要方式运行此服务器，具体取决于你希望如何连接和获取数据：

1. 一体化服务器（通过 index.ts 的 SSE 传输）

• 最适合： 能够很好地处理 OAuth 的 Web 应用程序或 MCP 客户端。
• 工作原理： 这是功能齐全的服务器。当你的 MCP 客户端想要连接时，它会启动 OAuth 2.0 流程。用户会被发送到他们的 EHR 登录页面。一旦他们批准访问，此服务器会在给出最终 MCP 连接绿灯（通过服务器发送事件，或 SSE）之前获取所有 EHR 数据。数据保留在内存中，随时可以通过实时 SSE 连接进行工具调用。
• 数据获取： 在连接设置期间自动发生。

sequenceDiagram
    participant Client [MCP 客户端]
    participant Server [完整服务器 (index.ts)]
    participant Browser [用户浏览器]
    participant EHR

    Client->>Server: 让我们连接！ (OAuth /authorize)
    Server->>Browser: EHR 登录时间！
    Browser->>EHR: 用户验证并批准
    EHR->>Browser: 好的，这是一个代码
    Browser->>Server: 收到代码！
    Server->>EHR: 将代码交换为令牌？
    EHR->>Server: 令牌已授予！ (+ 患者 ID)
    Server->>EHR: 正在获取所有患者数据...
    EHR->>Server: 这是数据！
    Server->>Server: 将数据存储在内存中
    Server->>Client: 连接已批准 (MCP 令牌)
    Client->>Server: MCP 连接已打开 (SSE)
    Client->>Server: 使用工具：grep_record(...)
    Server->>Server: 在内存数据上运行工具
    Server->>Client: 这是结果！ (SSE)

2. 命令行助手（通过 src/cli.ts 的 Stdio 传输）

• 最适合： 本地工具（如 Cursor）、测试，或者当你希望首先将数据保存在本地时。
• 工作原理： 这是一个两步过程：
  1. 首先获取： 使用 --create-db 运行脚本。它会启动一个迷你 Web 服务器，你在浏览器中登录到你的 EHR，并将所有获取的数据保存到本地 SQLite 文件中。
  2. 运行服务器： 再次运行脚本，将其指向 SQLite 文件 (--db path)。它将数据从文件加载到内存中，然后等待通过你的标准终端输入/输出 (stdio) 发送的 MCP 工具命令。
• 数据获取： 在启动实际的 MCP 服务器部分之前完成。

sequenceDiagram
    participant User
    participant CLI_CreateDB [CLI (--create-db)]
    participant Browser [用户浏览器]
    participant EHR
    participant SQLiteDB [SQLite 数据库文件]
    participant CLI_Stdio [CLI (--db)]
    participant MCPClient

    Note over User, CLI_CreateDB: 步骤 1：获取数据
    User->>CLI_CreateDB: bun src/cli.ts --create-db --db ./my_ehr.sqlite
    CLI_CreateDB->>User: 转到 http://localhost:8088/start
    User->>Browser: 打开链接
    Browser->>CLI_CreateDB: 请求 /start
    CLI_CreateDB->>Browser: 显示 EHR 登录页面 (ehretriever.html)
    Browser->>Browser: 用户输入 EHR 详细信息
    Browser->>EHR: SMART 身份验证流程
    EHR->>Browser: 用户验证/授权
    Browser->>EHR: 将代码交换为令牌
    EHR->>Browser: 令牌已授予
    Browser->>EHR: 获取 FHIR 数据...
    EHR->>Browser: 这是数据
    Browser->>Browser: 处理笔记/附件
    Browser->>CLI_CreateDB: 发送数据 (POST /ehr-data)
    CLI_CreateDB->>SQLiteDB: 将数据保存到文件
    CLI_CreateDB->>User: 完成！服务器已停止。

    Note over User, MCPClient: 步骤 2：使用数据
    User->>MCPClient: 配置服务器命令（例如，在 Cursor 中）
    MCPClient->>CLI_Stdio: bun src/cli.ts --db ./my_ehr.sqlite
    CLI_Stdio->>SQLiteDB: 从文件加载数据...
    CLI_Stdio->>MCPClient: 准备就绪！ (通过 stdio)
    MCPClient->>CLI_Stdio: 使用工具：grep_record(...)
    CLI_Stdio->>CLI_Stdio: 在内存数据上运行工具
    CLI_Stdio->>MCPClient: 这是结果！ (通过 stdio)

入门：设置

它非常标准：

1. 需要 Bun： 确保你已安装 Bun 运行时。如果没有：curl -fsSL https://bun.sh/install | bash
2. 获取代码： 如果你还没有克隆此存储库，请克隆它。

   git clone <repository-url>
   cd <repository-directory>
   

3. 安装依赖：

   bun install
   

选项 1：运行完整服务器 (index.ts)

将此用于 SSE/OAuth 方法。

1. 配置：
   • 将 config.json.example 复制到 config.json。
   • 编辑 config.json：你必须提供你的 ehr.clientId（从你的 EHR 开发者门户获取）以及你要连接的 EHR 的 ehr.fhirBaseUrl。
   • 检查 server.port（默认为 3000）。
2. 运行：

   bun run index.ts
   

   它将启动并等待 MCP 客户端启动连接过程。

选项 2：使用 CLI (src/cli.ts)

将此用于 stdio 方法（例如与 Cursor 一起使用）。

步骤 1：创建数据库文件

对于你要加载的每个患者/会话，运行此命令一次：

# 这会启动一个临时服务器，需要你在浏览器中进行交互
bun run src/cli.ts --create-db -d ./data/my_patient_data.sqlite

# 如果 ./data/my_patient_data.sqlite 已经存在，添加 --force-overwrite
# bun run src/cli.ts --create-db -d ./data/my_patient_data.sqlite --force-overwrite

# 需要不同的端口？使用 --port
# bun run src/cli.ts --create-db -d ./data/my_patient_data.sqlite --port 8089

按照它打印的说明进行操作：

1. 在你的浏览器中打开 http://localhost:<port>/start 链接。
2. 输入 EHR 的 FHIR URL 和你的客户端 ID。
3. 在出现提示时登录到 EHR。
4. 等待浏览器获取数据并将其发回。
5. CLI 会将其保存到 my_patient_data.sqlite（或你选择的路径）并停止。

步骤 2：通过 Stdio 运行 MCP 服务器

现在你有了数据文件：

# 将 CLI 指向你的数据库文件
bun run src/cli.ts --db ./data/my_patient_data.sqlite

它会加载数据并准备好通过 stdin/stdout 接收 MCP 命令。

步骤 3：连接你的客户端（例如，Cursor）

在你的客户端的 MCP 服务器配置中（例如 Cursor 的 .mcp/servers.json），将其设置为运行 CLI 命令：

{
  "mcpServers": {
    "local-ehr": {
      "name": "本地 EHR 搜索",
      "command": "bun", // 或 /path/to/bun
      "args": [
          // 使用 cli.ts 的 *绝对路径*
          "/home/user/projects/smart-mcp/src/cli.ts",
          "--db",
          // 使用你的数据库文件的 *绝对路径*
          "/home/user/projects/smart-mcp/data/my_patient_data.sqlite"
      ],
      // 可选：如果需要，取消注释
      // "cwd": "/home/user/projects/smart-mcp"
    }
  }
}

关键： 在客户端配置中使用 src/cli.ts 和你的 .sqlite 数据库文件的绝对路径！

工具的更多细节

• grep_record:
  • 输入：{ "query": "搜索词或 /regex/", "resource_types": ["Condition", "Observation"] }（省略 resource_types 或使用 [] 搜索所有内容。使用 ["Attachment"] 仅搜索笔记/附件文本）。
  • 输出：{ "results": "..." }（带有匹配项的 JSON 字符串）。
• query_record:
  • 输入：{ "sql": "SELECT json FROM fhir_resources WHERE resource_type = 'Patient'" }（表 fhir_resources 具有 resource_type、resource_id、json。表 fhir_attachments 具有附件详细信息）。
  • 输出：{ "results": "..." }（结果数组的 JSON 字符串）。
• eval_record:
  • 输入：{ "code": "return _.filter(fullEhr.fhir['Condition'], { clinicalStatus: { coding: [{ code: 'active'}] } });" }（你的 JS 代码获取 fullEhr、console、_ (lodash)、Buffer。必须使用 return）。
  • 输出：{ "results": "..." }（JSON 字符串：{ result: your_returned_value, logs: [], error?: "..." }）。

完整服务器附加功能（仅限 index.ts）

完整服务器 (index.ts) 还为需要它们的客户端提供标准的 OAuth 2.0 端点： /authorize、/token、/register、/revoke、/.well-known/oauth-authorization-server。

配置文件详细信息（index.ts 的 config.json）

(本节解释了完整服务器模式的设置)

示例 config.json

将 config.json.example 复制到 config.json 并进行编辑。

{
  "ehr": {
    "clientId": "your-client-id", // 必需
    "fhirBaseUrl": "https://ehr.example.com/fhir", // 必需
    // 以下可选 - 如果可能，将自动发现
    "authUrl": "https://ehr.example.com/oauth/authorize",
    "tokenUrl": "https://ehr.example.com/oauth/token",
    "requiredScopes": [ "openid", "fhirUser", "launch/patient", "patient/*.read" ]
  },
  "server": {
    "port": 3000, // 必需
    // 以下可选
    "baseUrl": "http://localhost:3000", // 如果省略，则自动派生
    "ehrCallbackPath": "/ehr-callback",
    "https": { "enabled": false, "certPath": "", "keyPath": "" }
  },
  "persistence": { // 可选 - 用于在完整服务器中缓存会话
    "enabled": false,
    "directory": "./data"
  },
  "security": { // 可选
    "disableClientChecks": false // 除非测试，否则保持 false！
  }
}

必需的配置

只有以下字段是完整服务器所必需的：

{
  "ehr": {
    "clientId": "your-client-id",
    "fhirBaseUrl": "https://ehr.example.com/fhir"
  },
  "server": {
    "port": 3000
  }
}