Medplum MCP

🚀 Medplum MCP 服务器

本项目实现了一个完整的模型上下文协议（MCP）服务器，旨在与 Medplum FHIR 服务器进行无缝交互。MCP 服务器提供了一个标准化接口，使大语言模型（LLM）能够通过一套全面的工具对各种 FHIR 资源执行创建、读取、更新和搜索（CRUDS）操作。这使用户能够通过任何与 MCP 兼容的客户端（如 Claude Desktop、VS Code MCP 扩展等），使用自然语言命令来管理存储在 Medplum 中的医疗数据。

服务器实现了完整的 MCP 协议规范，提供了 33 种全面的 FHIR 资源管理工具，任何 MCP 客户端都可以发现并执行这些工具。用户可以通过与使用 MCP 工具对 FHIR 服务器执行请求的大语言模型进行对话，直观地管理患者信息、从业者信息、组织信息、会诊信息、观察结果等。

🚀 快速开始

环境准备

1. 必备条件：

   • Node.js（具体版本参考 package.json 中的引擎要求，建议使用 LTS 版本）
   • 运行中的 Medplum 服务器实例（例如，本地 Docker 化实例，地址为 http://localhost:8103/）
   • Medplum 客户端凭证（客户端 ID 和客户端密钥）

2. 安装依赖：

git clone https://github.com/rkirkendall/medplum-mcp.git
cd medplum-mcp
npm install

3. 配置环境变量： 在项目根目录下创建一个 .env 文件，并填写你特定的 Medplum 服务器详细信息和 API 密钥：

MEDPLUM_BASE_URL=http://your-medplum-server-url/
MEDPLUM_CLIENT_ID=your_client_id
MEDPLUM_CLIENT_SECRET=your_client_secret
OPENAI_API_KEY=your_openai_api_key # 运行 llm-test-harness.ts 时需要

运行项目

💬 交互式聊天工具（推荐）

测试 MCP 服务器最友好的方式是通过交互式聊天界面：

# 构建并运行聊天工具
npm run chat

# 或者在开发模式下运行
npx ts-node src/llm-test-harness.ts

特性：

• 🗣️ 与所有 33 个 FHIR 工具进行自然语言交互
• 🔧 自动发现和执行工具
• 📋 内置帮助和示例
• 🔄 维护对话上下文
• ⚡ 实时执行工具并显示结果

示例会话：

🏥 你：创建一个新患者，名为 Jane Smith，出生于 1985-03-20
🤖 助手：我将为 Jane Smith 创建一个新的患者记录...

🏥 你：查找所有名为 Stevens 的医生
🤖 助手：我找到了 2 位名为 Stevens 的从业者...

详细使用说明请参考 CHAT_HARNESS_USAGE.md，开发细节请参考 IMPLEMENTATION_PLAN.md。

▶️ 直接运行 MCP 服务器

npm start # 使用标准输入输出传输运行 MCP 服务器
npm run dev # 开发模式，支持实时重新加载

🧪 其他测试方法

# MCP 检查器（基于 Web 的工具测试）
npx @modelcontextprotocol/inspector node dist/index.js

# 旧版 OpenAI 集成（已弃用）
npm run test:harness

✨ 主要特性

🎉 MCP 服务器已实现！🎉

已实现的功能：

• ✅ 核心 FHIR 资源管理工具（患者、从业者、组织、会诊、观察结果、药物等）
• ✅ MCP 服务器协议实现 - 具有标准输入输出传输的完整模型上下文协议服务器
• ✅ 用于与大语言模型交互的全面工具模式（33 个 FHIR 工具）
• ✅ 交互式聊天工具 - 具有自然语言界面的完整 MCP 客户端
• ✅ 所有工具的 Jest 集成测试
• ✅ Medplum FHIR 服务器连接和认证
• ✅ MCP 检查器测试和验证
• ✅ Claude Desktop 集成配置

已准备好使用：

• 🔄 MCP 服务器功能完整，可与 MCP 客户端集成
• ✅ 所有 33 个 FHIR 工具均已正确注册并正常工作
• 🔄 服务器成功与 Medplum 进行认证，并执行 FHIR 操作
• 🔄 交互式聊天工具可用 - 用自然语言测试所有工具
• 🔄 已通过 MCP 检查器测试 - 所有工具均可发现和执行
• 🔄 提供了 Claude Desktop 配置，可立即使用

当前能力：

• 通过自然语言对 FHIR 资源进行完整的 CRUD 操作
• 用于测试和开发的交互式聊天界面
• 与任何与 MCP 兼容的客户端（Claude Desktop、VS Code MCP 扩展等）无缝集成
• 全面的错误处理和日志记录
• 可用于生产环境的 MCP 协议实现

🌟 已实现的功能

MCP 服务器目前支持一套全面的 33 种工具，用于管理各种 FHIR 资源：

👥 患者管理（4 种工具） - src/tools/patientUtils.ts

• createPatient：创建包含人口统计信息、标识符和联系信息的新患者记录。
• getPatientById：通过患者的唯一 ID 检索完整的患者详细信息。
• updatePatient：修改现有患者信息，包括人口统计信息和联系详情。
• searchPatients：根据姓名、出生日期、标识符或其他标准查找患者。

👩‍⚕️ 从业者管理（5 种工具） - src/tools/practitionerUtils.ts

• createPractitioner：注册具有专业详细信息的新医疗从业者。
• getPractitionerById：通过从业者的唯一 ID 获取完整的从业者详细信息。
• updatePractitioner：更新从业者信息，包括资格和联系详情。
• searchPractitionersByName：使用从业者的名字或姓氏搜索从业者。
• searchPractitioners：根据多个标准对从业者进行高级搜索。

🏥 组织管理（4 种工具） - src/tools/organizationUtils.ts

• createOrganization：添加新的医疗组织（医院、诊所、部门）。
• getOrganizationById：通过组织的唯一 ID 检索完整的组织详细信息。
• updateOrganization：更新组织信息，包括联系详情和地址。
• searchOrganizations：按名称、类型或其他属性搜索组织。

🏥 会诊管理（4 种工具） - src/tools/encounterUtils.ts

• createEncounter：创建新的患者会诊（就诊、预约、住院）。
• getEncounterById：通过会诊的唯一 ID 检索完整的会诊详细信息。
• updateEncounter：更新会诊信息，包括状态、类别和参与者。
• searchEncounters：按患者、从业者、日期、状态或类别搜索会诊。

🔬 观察结果管理（4 种工具） - src/tools/observationUtils.ts

• createObservation：记录新的观察结果（实验室结果、生命体征、诊断结果）。
• getObservationById：通过观察结果的唯一 ID 检索完整的观察结果详细信息。
• updateObservation：修改现有观察结果，包括值、状态和解释。
• searchObservations：按患者、代码、日期或会诊搜索观察结果。

💊 药物请求管理（4 种工具） - src/tools/medicationRequestUtils.ts

• createMedicationRequest：创建包含剂量和说明的新药物请求（处方）。
• getMedicationRequestById：通过药物请求的唯一 ID 检索完整的药物请求详细信息。
• updateMedicationRequest：更新处方信息，包括状态、剂量和说明。
• searchMedicationRequests：按患者、药物或开处方者搜索药物请求。

💉 药物管理（3 种工具） - src/tools/medicationUtils.ts

• createMedication：创建包含代码、名称和配方的新药物资源。
• getMedicationById：通过药物的唯一 ID 检索完整的药物详细信息。
• searchMedications：按代码、名称或成分搜索药物。

📋 护理周期管理（4 种工具） - src/tools/episodeOfCareUtils.ts

• createEpisodeOfCare：创建新的护理周期，用于长期管理患者护理。
• getEpisodeOfCareById：通过护理周期的唯一 ID 检索完整的护理周期详细信息。
• updateEpisodeOfCare：更新护理周期信息，包括状态、时间段和管理组织。
• searchEpisodesOfCare：按患者、状态或管理组织搜索护理周期。

🔍 通用 FHIR 操作（1 种工具）

• generalFhirSearch：具有自定义参数的通用 FHIR 搜索，适用于任何资源类型，支持对所有 FHIR 资源进行高级查询。

每个工具都通过定义良好的 JSON 模式暴露给大语言模型，并可通过专用的测试工具（src/llm-test-harness.ts）调用，便于进行强大的测试和集成。

📚 详细文档

🛠️ 技术栈

• 运行时环境：Node.js
• 编程语言：TypeScript
• FHIR 服务器交互：@medplum/core，@medplum/fhirtypes
• 大语言模型集成：OpenAI API（测试工具中具体使用 gpt-4o）
• 测试：Jest（用于集成测试），通过测试工具进行手动端到端测试
• 代码检查和格式化：ESLint，Prettier
• 环境管理：dotenv
• HTTP 客户端（用于 Medplum SDK）：node-fetch

📁 项目结构

medplum-mcp/
├── src/                  # 源代码
│   ├── config/           # Medplum 客户端配置（medplumClient.ts）
│   ├── tools/            # FHIR 资源实用函数（patientUtils.ts 等）
│   ├── lib/              # 共享库（目前未使用）
│   ├── index.ts          # 主应用程序入口点
│   ├── llm-test-harness.ts # 用于测试大语言模型工具调用的脚本
│   └── test-connection.ts  # 用于基本 Medplum 连接测试的脚本
├── tests/                # 测试套件
│   └── integration/      # 工具的 Jest 集成测试
├── .eslintrc.js
├── .gitignore
├── .prettierrc.js
├── .prettierignore
├── package.json
├── tsconfig.json
└── README.md

✅ 测试

🔗 集成测试

集成测试使用 Jest 并与实时的 Medplum 实例进行交互（通过 .env 文件配置）。

运行所有集成测试：

npx jest tests/integration

运行特定的集成测试文件：

npx jest tests/integration/patient.integration.test.ts
npx jest tests/integration/practitioner.integration.test.ts
npx jest tests/integration/organization.integration.test.ts
# 根据需要添加其他特定测试文件

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。