openEHR MCP Server

openEHR MCP 服务

这是一个用于对接 openEHR REST API 的 MCP（Model Context Protocol）服务，专为 EHRbase 实现设计。
此服务可让 Claude Desktop 等 MCP 客户端为 openEHR 模板创建组合，并将其提交到服务端。
对于生产级 EHR 集成，必须使用能够确保数据隐私的 AI 模型。

如需了解更多 MCP 信息，请参阅 https://modelcontextprotocol.io/introduction。

版本

当前版本：0.1.0

本项目遵循语义化版本规范。有关版本策略的详细信息，请参阅 VERSIONING.md。

MCP 工具

• openehr_template_list：列出 EHRbase 服务端上所有可用的 openEHR 模板
• openehr_template_get：根据唯一标识符获取指定的 openEHR 模板
• openehr_template_example_composition：根据指定模板生成示例 openEHR 组合
• openehr_ehr_create：在系统中创建新的 EHR
• openehr_ehr_get：根据 ID 获取 EHR
• openehr_ehr_list：列出系统中所有可用的 EHR
• openehr_ehr_get_by_subject：根据受试者 ID 和命名空间获取 EHR
• openehr_composition_create：在电子健康记录中创建新的 openEHR 组合
• openehr_composition_get：根据唯一标识符获取现有的 openEHR 组合
• openehr_composition_update：更新电子健康记录中现有的 openEHR 组合
• openehr_composition_delete：从电子健康记录中删除现有的 openEHR 组合
• openehr_query_adhoc：对 openEHR 服务端执行临时 AQL 查询

MCP 提示词

• vital_signs_capture：为指定的 EHR ID 采集生命体征

MCP 资源

尚未实现

使用 Docker 快速入门

最简单的入门方式是使用 Docker Hub 上提供的预构建 Docker 镜像。

1. 前提条件

确保你有正在运行的 EHRbase 服务端。如需在本地运行，请参阅下文。

2. 配置 Claude Desktop

编辑 Claude Desktop 配置文件（claude_desktop_config.json），并在 "mcpServers" 部分中添加 "openEHR" 配置块。

此文件通常位于以下位置：

• macOS：~/Library/Application Support/Claude
• Windows：%APPDATA%\Claude

{
  "mcpServers": {
    "openEHR": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network=host",
        "-e","EHRBASE_URL=http://localhost:8080/ehrbase/rest",
        "-e","EHRBASE_JSON_FORMAT=wt_flat",
        "ctodeakai/openehr-mcp-server:latest"
      ]
    }
  }
}

你可以将 EHRBASE_URL 指向自己的 EHRbase 服务端，也可以使用提供的 docker-compose 设置。

JSON 格式配置

此 MCP 服务支持不同的 JSON 序列化格式，用于与 EHRbase API 交互。你可以使用可选的 EHRBASE_JSON_FORMAT 环境变量配置格式：

"-e", "EHRBASE_JSON_FORMAT=wt_flat"

可用格式选项：

• wt_flat（默认）：使用基于扁平 Web 模板格式的简化数据类型（SDT）
• canonical：在所有操作中统一使用规范的 openEHR JSON 格式
• wt_structured：使用基于结构化 Web 模板格式的 SDT（目前无法正常工作）

有关如何将 Claude Desktop 配置为使用 MCP 服务的更多信息，请参阅 https://modelcontextprotocol.io/quickstart/user。

设置

前提条件

要使此 MCP 服务正常工作，目前需要：

• 一个 ehrbase 服务端
  • 此处提供了示例服务端：docker-compose.yml
• 一个 openEHR 模板
  • 此处提供了示例模板：vital_signs_basic.opt
  • 你可以使用脚本 upload_template.py 上传模板
• 此服务端中的一个 EHR 及其对应的 EHR ID
  • 你可以使用脚本 create_ehr.py 创建一个

本地 EHRBase 设置

前提条件

• 可正常使用的 Docker 安装
• Python 3（本项目使用 Python 3.12 构建，较早版本可能也可用）
• Python 虚拟环境（pip、conda 或 uv）
• 在 Python 环境中安装所需依赖：

  pip install -r requirements.txt
  

运行 EHRbase 服务

1. 进入 docker-compose 目录：

   cd docker-compose
   

2. 以分离模式启动 EHRbase 服务：

   docker compose up -d
   

3. 检查日志，确认服务正常运行：

   docker compose logs -f
   

4. EHRbase 服务将在 http://localhost:8080/ehrbase/ 上运行。

5. EHRBase API 文档位于此处：http://localhost:8080/ehrbase/swagger-ui/index.html

上传生命体征模板

设置好 EHRbase 服务和 Python 环境后，即可上传生命体征模板：

python scripts/upload_template.py

你也可以指定自定义模板或 EHRbase URL：

python scripts/upload_template.py --template path/to/template.opt --ehrbase-url http://custom-url:8080/ehrbase/rest

你应该会看到输出，确认模板已成功上传到 EHRbase 服务。

创建 EHR

上传模板后，你需要创建一个电子健康记录（EHR）来存储组合：

python scripts/create_ehr.py

此操作将创建一个带有随机生成的受试者 ID 的 EHR。你也可以指定自定义受试者 ID：

python scripts/create_ehr.py --subject-id "patient_12345"

脚本将输出 EHR ID，创建组合或使用 MCP 服务时需要用到该 ID。

运行集成测试

运行测试前，你需要先安装测试依赖项：

pip install -r requirements-test.txt

安装测试依赖项并上传模板后，即可运行测试：

python -m pytest tests/test_*.py -v

这将运行 tests 目录中的所有测试。

使用 Docker 运行 openEHR MCP 服务

构建 Docker 镜像

在项目根目录下构建 Docker 镜像：

docker build -t openehr-mcp-server .

运行 Docker 容器

docker run -i --rm --network=host openehr-mcp-server