Medplum MCP

🚀 Medplum MCP Server

このプロジェクトは、Medplum FHIRサーバーとシームレスに連携するために設計された完全なモデルコンテキストプロトコル（MCP）サーバーを実装しています。MCPサーバーは標準化されたインターフェースを提供し、大規模言語モデル（LLM）が包括的なツールセットを通じて、さまざまなFHIRリソースに対する作成、読み取り、更新、検索（CRUDS）操作を実行できるようにします。これにより、ユーザーは任意のMCP互換クライアント（Claude Desktop、VS Code MCP拡張機能など）を通じて自然言語コマンドを使用して、Medplumに保存された医療データを管理することができます。

サーバーは完全なMCPプロトコル仕様を実装しており、33の包括的なFHIRリソース管理ツールを提供しています。これらのツールは、任意のMCPクライアントによって発見され、実行されることができます。ユーザーは、MCPツールを利用してFHIRサーバーに対してリクエストを実行するLLMと会話することで、患者情報、医療従事者、組織、診察、観察結果などを直感的に管理することができます。

✨ 現在の状況

🎉 MCPサーバーの実装完了！ 🎉

実装済みの機能:

• ✅ コアFHIRリソース管理ツール（患者、医療従事者、組織、診察、観察結果、薬剤など）
• ✅ MCPサーバープロトコルの実装 - stdioトランスポートを備えた完全なモデルコンテキストプロトコルサーバー
• ✅ LLMとの対話用の包括的なツールスキーマ（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サーバーは現在、さまざまなFHIRリソースを管理するための包括的な33のツールをサポートしています。

👥 患者管理（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スキーマを介してLLMに公開されており、専用のテストハーネス（src/llm-test-harness.ts）を通じて呼び出すことができます。これにより、堅牢なテストと統合が容易になります。

🔧 技術詳細

• ランタイム: Node.js
• 言語: TypeScript
• FHIRサーバーとのやり取り: @medplum/core, @medplum/fhirtypes
• LLM統合: OpenAI API（テストハーネスでは具体的にgpt-4o）
• テスト: Jest（統合テスト用）、テストハーネスを介した手動E2E
• リンティングとフォーマット: 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 # LLMツール呼び出しのテスト用スクリプト
│   └── test-connection.ts  # Medplum接続の基本テスト用スクリプト
├── tests/                # テストスイート
│   └── integration/      # ツールのJest統合テスト
├── .eslintrc.js
├── .gitignore
├── .prettierrc.js
├── .prettierignore
├── package.json
├── tsconfig.json
└── README.md

📦 インストール

1. 前提条件:

   • Node.js（エンジンの詳細はpackage.jsonを参照；LTSバージョンが推奨されます）
   • 稼働中のMedplumサーバーインスタンス（例：http://localhost:8103/のローカルDockerインスタンス）
   • 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ツールとの自然言語対話
• 🔧 自動ツール発見と実行
• 📋 組み込みのヘルプとサンプル
• 🔄 会話コンテキストの維持
• ⚡ リアルタイムのツール実行と結果

サンプルセッション:

🏥 You: Create a new patient Jane Smith born 1985-03-20
🤖 Assistant: I'll create a new patient record for Jane Smith...

🏥 You: Find all doctors named Stevens
🤖 Assistant: I found 2 practitioners with the name Stevens...

詳細な使用方法についてはCHAT_HARNESS_USAGE.mdを、開発の詳細についてはIMPLEMENTATION_PLAN.mdを参照してください。

▶️ MCPサーバーを直接実行する

npm start # stdioトランスポートでMCPサーバーを実行
npm run dev # ライブリロードを備えた開発モード

🧪 代替テスト方法

# MCPインスペクター（ウェブベースのツールテスト）
npx @modelcontextprotocol/inspector node dist/index.js

# レガシーOpenAI統合（非推奨）
npm run test:harness

✅ テスト

🔗 統合テスト

統合テストはJestを使用し、.envを介して構成された実稼働中のMedplumインスタンスとやり取りします。

すべての統合テストを実行するには：

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ファイルを参照してください。