openEHR助手MCP服务器

![PR validation](https://github.com/cadasto/openehr-assistant-mcp/actions/workflows/pr-validation.yml) ](https://github.com/cadasto/openehr-assistant-mcp/actions/workflows/release.yml) ![License: MIT](https://opensource.org/licenses/MIT) ](https://www.php.net/) ![MCP](https://modelcontextprotocol.io/)

MCP服务器协助终端用户处理各种 openEHR 相关任务和API。

这模型上下文协议（MCP）是一个开放标准，使人工智能助手能够以安全和标准化的方式连接到外部数据源和工具。MCP服务器充当AI客户端（如Claude Desktop、Cursor或LibreChat）与特定领域API、数据库或知识库之间的桥梁。

这 openEHR助手MCP服务器 将这种能力引入医疗信息学领域，特别是针对openEHR建模者和开发人员。使用openEHR原型、模板和规范通常涉及导航复杂的API、搜索临床知识经理（CKM）知识库，理解复杂类型系统，并确保符合ADL语法规则。其中许多工作流程，如原型设计、模板组合、术语解析和语法验证，都是重复的、耗时的，有时过于复杂而无法自动化。

该服务器通过为AI助手提供对openEHR资源、术语服务和CKM API的直接访问来增强这些工作流程，使他们能够协助完成原型探索、语义解释、语言翻译、语法纠正和设计审查等任务。

注：此项目目前处于预发布状态。预计在1.0版本之前，架构和功能集将频繁更新，并可能发生重大变化。

特性

适用于Claude Desktop、Cursor、LibreChat等MCP客户端。
公开openEHR原型和规格的工具。
引导式提示有助于编排多步骤工作流。
远程运行（端点URL:https://openehr-assistant-mcp.apps.cadasto.com/)或本地（传输：可流式传输HTTP和stdio）

实施方面

使用PHP 8.4编写；符合PSR的代码库
基于属性的MCP工具发现（通过https://github.com/mcp/sdk)使用基于文件的缓存
基于属性的MCP提示发现（复杂任务的种子对话）和基于文件的缓存
MCP资源模板和完成提供程序，以改善MCP客户端的用户体验
传输：可流式传输的HTTP和stdio（用于开发）
用于生产和开发的Docker镜像
使用Monolog进行结构化日志记录

______________________________________________________________________

可用的MCP元件

工具

临床知识经理

ckm_archetype_search -从CKM服务器中列出符合搜索条件的原型
ckm_archetype_get -通过标识符获取CKM原型
ckm_template_search -从CKM服务器列出符合搜索条件的模板（OET/OPT）
ckm_template_get -通过标识符获取CKM模板（OET/OPT）

openEHR术语

terminology_resolve -将openEHR术语概念ID解析到其量规中，或跨组查找给定量规的ID。

指南（型号可达）

guide_search -通过查询搜索捆绑的指南，并返回带有规范的简短片段openehr://guidesURI。
guide_get -默认情况下，通过URI或（类别、名称）使用分块部分检索指南内容。
guide_adl_idiom_lookup -从备忘单中查找有针对性的ADL习语片段，以了解常见的建模模式。

示例（精选文物）

examples_search -按查询搜索捆绑的示例工件（AQL查询、FLAT/STRUCTURED JSON有效载荷、ADL原型），并返回带有规范的简短片段openehr://examplesURI。
examples_get -通过URI或（种类、名称）检索示例工件。Markdown示例（AQL/FLAT/STRUCTURED）将查询/有效载荷包装在一个带有元数据头+围栏代码块的文件中；原型示例(kind=archetypes)是本地人 .adl 担任 text/plain.

openEHR型号规格

type_specification_search -列出符合搜索条件的捆绑openEHR类型规格。
type_specification_get -检索openEHR类型规范（作为BMM JSON）。

提示

可选提示，指导AI助手使用上述工具完成常见的openEHR和CKM工作流。

ckm_archetype_explorer -通过发现和获取定义（ADL/XML/Mindmap），使用 ckm_archetype_search 和 ckm_archetype_get 工具。
ckm_template_explorer -通过发现和获取定义（OET/OPT）来探索CKM模板，使用 ckm_template_search 和 ckm_template_get 工具。
type_specification_explorer -使用以下命令发现和获取openEHR类型规范（作为BMM JSON） type_specification_search 和 type_specification_get 工具。
terminology_explorer -使用术语资源发现和检索openEHR术语定义（组和代码集）。
guide_explorer -使用以下工具查找和检索openEHR实施指南 guide_search, guide_get，以及 guide_adl_idiom_lookup 工具。
explain_archetype -解释原型的语义（受众、元素、约束）。
explain_template -解释openEHR模板语义。
explain_aql -解释AQL查询的意图、结构和语义（包含、原型路径、过滤器、部署的OPT假设）。
translate_archetype_language -通过安全检查在语言之间翻译原型的术语部分。
fix_adl_syntax -在不改变语义的情况下纠正或改进原型语法；提供前后和注释。
design_or_review_archetype -具有结构化输出的特定概念/RM类的设计或审查任务。
design_or_review_template -openEHR模板（OET）的设计或审查任务。
design_or_review_aql -使用AQL指南（原则、语法、习语、检查表）为AQL查询设计或审查任务。
design_or_review_simplified_format -使用简化格式指南设计或查看平面或结构化（简化）格式实例。
explain_simplified_format -解释平面或结构化JSON有效负载的上下文、路径和数据元素。

完工供应商

完成提供者在调用工具或资源时在MCP客户端中提供参数建议。

Guides -建议指南 {name} 类别值 archetypes, templates, aql, simplified_formats, specs，以及 howto （资源URI openehr://guides/{category}/{name})
Examples -举个例子 {name} 不同种类的值 aql, flat, structured, archetypes （资源URI openehr://examples/{kind}/{name})
SpecificationComponents -建议 {component} 基于目录的值 resources/bmm 资源URI

资源

MCP服务器资源通过以下方式公开 #[McpResource] 带注释的方法，MCP客户端可以使用 openehr://... URI。它们用于提供对openEHR资源（指南、规范、术语）的访问，并编排复杂的工作流程。

指南（Markdown）

URI模板： openehr://guides/{category}/{name}
磁盘映射： resources/guides/{category}/{name}.md
模型访问：使用 guide_search 和 guide_get 以简短的、与任务相关的块检索指南内容。
示例：

- openehr://guides/archetypes/checklist - openehr://guides/archetypes/adl-syntax - openehr://guides/aql/principles - openehr://guides/aql/syntax - openehr://guides/simplified_formats/rules - openehr://guides/specs/rm-ehr --每份文档的openEHR规范摘要（250-900字） - openehr://guides/howto/spec-lookup --工具链操作指南

示例（精选文物）

URI模板： openehr://examples/{kind}/{name}
磁盘映射： resources/examples/{kind}/{name}.{md|adl}
种类： aql （参考AQL查询——Markdown）， flat / structured （成对的简化格式JSON有效载荷——Markdown）， archetypes （金标准CKM发布的ADL文件——原生 .adl).
模型访问：使用 examples_search 和 examples_getMarkdown示例包含元数据头（模式、演示、相关规范/指南）+围栏代码块。ADL原型被用作 text/plain --原型自身 description 部分是其嵌入的元数据。
示例：

- openehr://examples/aql/latest_blood_pressure_per_ehr - openehr://examples/flat/vital_signs_blood_pressure - openehr://examples/structured/vital_signs_blood_pressure - openehr://examples/archetypes/openEHR-EHR-OBSERVATION.blood_pressure.v2

类型规范（BMM JSON）

URI模板： openehr://spec/type/{component}/{name}
磁盘映射： resources/bmm/{COMPONENT}/{NAME}.bmm.json
示例：

- openehr://spec/type/RM/COMPOSITION - openehr://spec/type/AM/ARCHETYPE - openehr://spec/type/AM2/ARCHETYPE_HRID

术语（JSON）

URI： openehr://terminology 包含所有术语组和代码集
提供对术语组（概念/量规）和代码集的访问。
磁盘映射： resources/terminology/openehr_terminology.xml

______________________________________________________________________

运输

MCP传输用于与MCP客户端通信。

streamable-http （默认）：HTTPS（端口443）；dev安装程序公开了一个额外的HTTP端口 8343 通过卡迪。
stdio：适用于基于流程的MCP客户或本地开发。

- 开始选项：通过 --transport=stdio 到 public/index.php.

______________________________________________________________________

快速开始

要开始使用，请使用以下选项之一：

无本地设置（最快）： 使用我们的托管端点。
通过Docker本地（推荐给贡献者）： 使用以下命令运行服务器 docker compose.
通过stdio本地： 对于更喜欢stdio的MCP客户端，作为进程运行。

______________________________________________________________________

选项1：使用我们的托管服务器（无需安装）

如果您只想以最少的设置使用此MCP服务器，请从这里开始。

直接在您的客户端中使用此MCP服务器URL：

网址： https://openehr-assistant-mcp.apps.cadasto.com/
运输： streamable-http

MCP配置示例：

{
  "mcpServers": {
    "openehr-assistant-remote": {
      "type": "streamable-http",
      "url": "https://openehr-assistant-mcp.apps.cadasto.com/"
    }
  }
}

详见下文特定客户端配置.

______________________________________________________________________

选项2：使用Docker在本地运行（建议贡献者使用）

在编辑工具/提示/资源并希望立即获得反馈时使用此功能。

先决条件

Docker+Docker组合
Git

1）克隆存储库

git clone https://github.com/cadasto/openehr-assistant-mcp.git
cd openehr-assistant-mcp

2）准备环境

cp .env.example .env

提示：默认值适用于大多数用户。你通常只需要编辑 .env 如果您想更改域、日志记录或CKM端点。

3）启动开发容器

docker compose --env-file .env -f .docker/docker-compose.yml -f .docker/docker-compose.dev.yml up -d --build --force-recreate
# or
make up-dev

4）安装Composer依赖项

docker compose --env-file .env -f .docker/docker-compose.yml -f .docker/docker-compose.dev.yml exec -u 1000:1000 app composer install
# or
make install

5）连接您的MCP客户端

默认本地终结点（可流式传输HTTP）： https://openehr-assistant-mcp.local/；在宿主文件中也设置此名称，并用 127.0.0.1 openehr-assistant-mcp.local.
开发端点（带开发覆盖）： http://localhost:8343/

如果 openehr-assistant-mcp.local 无法在您的计算机上解决，请使用下面的开发设置并连接到 http://localhost:8343/.

或者，当您希望MCP客户端直接启动服务器进程时，可以通过运行与以下类似的命令来使用stdio。

docker compose --env-file .env -f .docker/docker-compose.yml -f .docker/docker-compose.dev.yml exec app php public/index.php --transport=stdio

______________________________________________________________________

选项3：通过stdio在本地运行

当您的MCP客户端直接启动服务器进程时，请使用stdio。

确保您的MCP客户端支持stdio传输，并运行以下命令之一。

1）来自开发容器

docker compose --env-file .env -f .docker/docker-compose.yml -f .docker/docker-compose.dev.yml exec app php public/index.php --transport=stdio

2）来自已发布的Docker镜像

docker run --rm -i ghcr.io/cadasto/openehr-assistant-mcp:latest php public/index.php --transport=stdio

______________________________________________________________________

常见客户端配置

典型配置

在大多数情况下，添加一以下服务器配置：

{
  "mcpServers": {
    "openehr-assistant-mcp": {
      "type": "streamable-http",
      "url": "https://openehr-assistant-mcp.apps.cadasto.com/"
    },
    "openehr-assistant-mcp-stdio": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "ghcr.io/cadasto/openehr-assistant-mcp:latest",
        "php", "public/index.php", "--transport=stdio"
      ]
    },
    "openehr-assistant-mcp-http": {
      "type": "streamable-http",
      "url": "http://host.docker.internal:8343/"
    }
  }
}

克劳德桌面(`mcpServers`)

添加远程URL https://openehr-assistant-mcp.apps.cadasto.com/ 在“功能表>设置>连接器>添加自定义连接器”中。

或者，使用菜单 → 开发者 → 编辑配置 要添加服务器配置之一，请参阅上文。

LibreChat（可流式传输HTTP）

mcpServers:
  openehr-assistant-mcp:
    type: streamable-http
    url: http://host.docker.internal:8343/

光标

打开 光标设置 → 主控程序.
添加新的MCP服务器。
选择以下连接选项之一：

- 托管: type=streamable-http, url=https://openehr-assistant-mcp.apps.cadasto.com/ - 本地开发人员: type=streamable-http, url=http://host.docker.internal:8343/ - 本地标准：使用Docker运行——见上文。

IntelliJ 六月

打开 设置/首选项 → 工具 → 六月 → MCP服务器 （措辞可能因版本而异）。
使用以下任一方式添加服务器：

- 可流式传输的HTTP URL(https://openehr-assistant-mcp.apps.cadasto.com/ 或 http://host.docker.internal:8343/)，或 - Stdio命令 （上面的Docker命令）。

保存配置并刷新/重新启动Junie，以便发现工具。

______________________________________________________________________

开发技巧

MCP检查员

运行MCP检查器以检查请求/响应和调试行为：

make inspector

终端可能会显示 http://0.0.0.0:6274/；打开它 http://localhost:6274/ （或您的机器IP）在浏览器中。

生成文件快捷方式

构建图像： make build （prod）或 make build-dev （dev）
启动服务： make up （prod）或 make up-dev （使用实时卷挂载进行开发覆盖）
准备 .env: make env
在开发容器中安装依赖项： make install
尾梁： make logs
在开发容器中打开shell： make sh
运行MCP服务器（stdio）： make run-stdio
运行MCP一致性（要求 make up-dev): make conformance
运行MCP检查器： make inspector
显示帮助： make help

环境变量

APP_ENV：应用程序环境(development/testing/production).违约： production
LOG_LEVEL：Monolog级别(debug, info, warning, error等等）。违约： info
CKM_API_BASE_URL：openEHR CKM REST API的基本URL。违约： https://ckm.openehr.org/ckm/rest
HTTP_TIMEOUT：HTTP客户端超时秒数（浮点数）。违约： 3.0
HTTP_SSL_VERIFY：设置为 false 禁用验证或提供CA包路径。违约： true
XDG_DATA_HOME：应用程序数据目录，包括缓存和会话。违约： /tmp （应用程序使用 XDG_DATA_HOME/app 或 /tmp/app)

注意：默认情况下不需要也不配置授权标头。如果需要向上游openEHR/CKM服务器添加身份验证，请在中扩展HTTP客户端 src/Apis 添加适当的标题。

测试和质量保证

单元测试： docker compose --env-file .env -f .docker/docker-compose.yml -f .docker/docker-compose.dev.yml exec app composer test （phtord 12）
覆盖测试： docker compose --env-file .env -f .docker/docker-compose.yml -f .docker/docker-compose.dev.yml exec app composer test:coverage
静态分析： docker compose --env-file .env -f .docker/docker-compose.yml -f .docker/docker-compose.dev.yml exec app composer check:phpstan

MCP合规性

这 MCP合规性测试框架根据MCP规范检查服务器。它通过以下方式与服务器通信 仅限HTTP （不是stdio）。某些场景需要测试工具（例如。 test_tool_with_logging)或此服务器未实现的可选功能；这些都列在 tests/conformance-baseline.yml 以便 make conformance 当只发生已知故障时退出0，并在新的回归中失败。要查看所有服务器场景，请执行以下操作： docker compose --env-file .env -f .docker/docker-compose.yml -f .docker/docker-compose.dev.yml run --rm node npx -y @modelcontextprotocol/conformance list --server。确保开发堆栈正在运行(make up-dev)，然后运行：

make conformance

这将在内部运行一致性套件 node Docker中的服务（Node+curl），因此您不需要主机上的Node。结果打印到终端并写入 conformance/ 在repo（子目录如 conformance/server--/ 随着 checks.json).运行单个场景或传递选项（例如。 --verbose)，使用：

docker compose --env-file .env -f .docker/docker-compose.yml -f .docker/docker-compose.dev.yml run --rm node npx -y @modelcontextprotocol/conformance server --url http://ingress:8343/mcp_openehr -o conformance --expected-failures tests/conformance-baseline.yml --scenario server-initialize --verbose

提示

你也可以 make sh 然后跑 composer test 在容器内以交互方式。

项目结构

public/index.php：MCP服务器入口点
resources/：服务器使用或暴露的各种资源
src/

- Tools/：MCP工具（定义、EHR、组合、查询） - Prompts/：MCP提示（包括 AbstractPrompt 用于加载基于Markdown的提示） - Resources/：MCP资源和资源模板 - CompletionProviders/：MCP完成提供商 - Helpers/：内部助手（例如，内容类型和ADL映射） - Apis/：内部API客户端 - constants.php：加载环境变量和默认值

.docker/：Docker资产-- docker-compose.yml, docker-compose.dev.yml, Dockerfile, Caddyfile，PHP/PHP-fpm配置
.docker/docker-compose.yml：服务(app, ingress)用于类似run的生产（Caddy on 443）
.docker/docker-compose.dev.yml：dev覆盖（端口8343， node npx/curl和MCP一致性服务）
.docker/Dockerfile：多阶段构建（开发、生产和 node 用于MCP一致性/npx+卷曲）
Makefile：方便的快捷方式
tests/：PHPUnit和PHPTan配置和测试

______________________________________________________________________

贡献

我们欢迎捐款！请阅读CONTRIBUTING.md，了解有关设置环境、编码风格、测试以及如何提出更改的指导方针。大多数常规任务都可以通过Makefile执行。

请参阅CHANGELOG.md以了解显著的更改，并在每次发布时进行更新。

许可证

MIT许可证-请参阅 LICENSE.

______________________________________________________________________

致谢

本项目的灵感来自并感谢：

原始的Python openEHR MCP服务器：https://github.com/deak-ai/openehr-mcp-server
塞雷夫·阿里坎, Sidharth Ramesh -关于MCP集成的启示
PHP MCP服务器框架：https://github.com/modelcontextprotocol/php-sdk
海洋卫生系统临床知识管理器（CKM）是openEHR社区的重要工具，可以实现原型和模板的协作开发和共享。
freshEHR CGEM框架（上下文情况、全球背景、事件评估、管理响应），它为我们的模板设计指南提供了关于拆分数据集和组合语义（CC-BY）的信息。
Silje 卢斯兰山 -对原型和语言相关指南的贡献。

MCP Openehr Assistant

快速接入

详细介绍

openEHR助手MCP服务器

目录

特性

实施方面

可用的MCP元件

工具

提示

完工供应商

资源

运输

快速开始

选项1：使用我们的托管服务器（无需安装）

选项2：使用Docker在本地运行（建议贡献者使用）

先决条件

1） 克隆存储库

2） 准备环境

3） 启动开发容器

4） 安装Composer依赖项

5） 连接您的MCP客户端

选项3：通过stdio在本地运行

1） 来自开发容器

2） 来自已发布的Docker镜像

常见客户端配置

典型配置

克劳德桌面(mcpServers)

LibreChat（可流式传输HTTP）

光标

IntelliJ 六月

开发技巧

MCP检查员

生成文件快捷方式

环境变量

测试和质量保证

MCP合规性

项目结构

贡献

许可证

致谢

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1）克隆存储库

2）准备环境

3）启动开发容器

4）安装Composer依赖项

5）连接您的MCP客户端

1）来自开发容器

2）来自已发布的Docker镜像

克劳德桌面(`mcpServers`)