clinic-mcp

診療予約およびインテークのためのリファレンスModel Context Protocolサーバーです。厳密な型定義、構造化されたエラー処理、データ層で強制されるテナント分離を備えたTypeScriptで構築されています。データは合成されたものであり、これは臨床用ソフトウェアではありません。

この目的は、データ分離と根拠のある出力を必要とする業種において、本番環境向けのMCPサーバーがどのような形をしているかを示すことです。これは私がRentiveで書いているコードと同じ形状であり、機密情報を漏洩させることなくパターンをレビューできるように、モックデータと異なるドメインを使用しています。

MCPの理由

LLMアプリケーションは、プロバイダーごとのアドホックな関数定義、独自の引数解析、共有トランスポートの欠如、一貫性のないエラーモデルなど、同じ配線を何度も作り直しています。MCPは、この配線層を修正するための小さなオープンプロトコルです。サーバーは型定義されたツールのリストをstdio（またはHTTP）経由で公開し、MCP対応のクライアント（Claude Desktop、IDE統合、カスタムエージェント）は同じ仕組みでそれらを発見し、呼び出すことができます。

ドメインバックエンドにとって、これはツールを一度書けばどこでも動作することを意味します。エージェントビルダーにとっては、ツールスキーマを手作業で作成するのをやめ、サーバーを構成し始めることを意味します。

Related MCP server: MCP Healthcare Server

アーキテクチャ

flowchart LR
    Client["MCP client<br/>(Claude Desktop, custom agent)"]
    Server["clinic-mcp server"]
    Tools["Tools<br/>find_available_slot<br/>book_appointment<br/>record_intake<br/>search_protocols<br/>escalate_to_oncall"]
    Store["ClinicStore<br/>tenant-scoped accessors"]
    Seed[("seed.json<br/>synthetic clinics, providers,<br/>patients, protocols")]

    Client -->|stdio JSON-RPC| Server
    Server --> Tools
    Tools --> Store
    Store --> Seed

すべてのツールは clinic_id を受け取り、ストアはすべての読み取りと書き込みがそのクリニックにスコープされることを強制します。テナント間アクセスは、誤った行を黙って返すのではなく、TenantMismatchError をスローします。これは、本番環境のPostgresで強制される行レベルセキュリティのパターンを反映しており、ここではアプリケーションコード内で表面化させることで、1つのファイル（src/store/index.ts）で保証をレビューできるようにしています。

ローカルでの実行

Node 20以上とpnpmが必要です。

git clone https://github.com/dominikstefanski/clinic-mcp.git
cd clinic-mcp
pnpm install
pnpm test          # 29 tests
pnpm typecheck
pnpm dev           # boots the server on stdio

サーバーは起動時に src/store/seed.json を読み込み、clinic_north（一般診療、循環器科、皮膚科）と clinic_west（小児科、一般診療）の2つの合成クリニックを提供します。

Claude Desktopへの接続

Claude Desktopの設定（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json）に以下を追加します。パスはローカルのクローン先に置き換えてください。

{
  "mcpServers": {
    "clinic-mcp": {
      "command": "npx",
      "args": ["-y", "tsx", "/absolute/path/to/clinic-mcp/src/server.ts"]
    }
  }
}

Claude Desktopを再起動します。接続メニューの下に5つのツールが表示されます。*「来週の月曜日の午前にclinic_northで一般診療の空きを見つけて」*のようなプロンプトを試してみてください。

ツールリファレンス

すべてのツールは、成功時に { ok: true, ...result } を、失敗時に { ok: false, error: { code, message } } を返します。入力はzodで検証されます。MCPレベルの引数エラーは、フィールドの詳細を含む validation エラーとして返されます。

find_available_slot

指定された期間内の専門分野の空き予約枠を検索し、競合をスキップします。

book_appointment

予約を作成します。呼び出し元が提供する idempotency_key が必要です。リプレイが発生した場合は、二重予約を防ぐために元の予約を返します。音声エージェントは再試行を行うため、これは必須です。

{ appointment, idempotent_replay } を返します。

record_intake

構造化されたインテークメモを保存し、トリアージレベルを割り当てます。

トリアージルール: 重症度 >= 8 は urgent、>= 5 は elevated、それ以外は routine。

search_protocols

クリニックのプロトコルライブラリをキーワード検索します。モデルが回答時に引用できるランク付けされたスニペットを返します。

現在の実装は、タイトル重み付け（3倍）を伴う単純なTFスコアです。これは検索ツールのインターフェースを実証するために存在します。本番環境では、バックエンドをベクトル検索に置き換えます（設計ノートを参照）。

escalate_to_oncall

既存の予約を緊急としてマークし、クリニックのオンコール担当プロバイダーに再割り当てします。

{ appointment, on_call_provider, reassigned } を返します。

設計ノート

テナント分離はツールではなくストアで強制されます。 ツールは clinic_id を受け取り、それを下位に渡します。ストアはすべてのアクセサーで所有権を検証し、不一致の場合は TenantMismatchError をスローします。明日新しいツールを追加しても、誤ってクリニック間でデータが漏洩することはありません。ストアがそれを許可しないからです。

書き込み時の冪等性。 book_appointment は idempotency_key を必要とします。実際の呼び出し元（音声エージェント、再試行ループ、ネットワークの不具合）はリクエストを繰り返すため、再試行に対して重複予約を作成する医療システムは、初日から信頼を失うシステムです。

スローされる文字列よりも構造化されたエラー。 すべてのドメイン障害は、安定した code を持つ型付きの DomainError サブクラスです。MCPラッパーはそれらを { ok: false, error: { code, message } } に変換します。クライアントは message を正規表現で解析する代わりに、code で分岐できます。

検索ツールは代用品です。 search_protocols はインメモリのTFスコアを使用しているため、外部サービスなしでリポジトリを実行できます。本番環境では、これはPinecone、pgvector、または選択した検索バックエンドを接続する継ぎ目となります。ツールの入出力コントラクトは変わりません。

時間処理は簡略化されています。 プロバイダーの勤務時間は、明確にするためにUTCで解釈されます。実際のデプロイメントでは、各クリニックのタイムゾーン（スキーマに既に存在）を尊重します。これは見落としではなく意図的なものであることをレビュー担当者に伝えるために明記しています。

これがそうではないもの

• 臨床用ソフトウェアではありません。トリアージルールは玩具であり、プロトコルコーパスは手書きの文章です。実際の患者に触れるものには使用しないでください。

• HIPAA準拠ではありません。データは偽物であり、ストレージはインメモリであり、監査ログもありません。本番環境では、それらすべてとそれ以上のものが必要になります。

• 完全なEMRや予約バックエンドではありません。ポイントはMCPサーバーの形状を示すことであり、クリニックシステムを出荷することではありません。

ライセンス

MIT。LICENSEを参照してください。