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 文件。