Skip to main content
Glama

clinic-mcp

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

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

MCPの理由

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

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

Related MCP server: tenant-scoped-crm

アーキテクチャ

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

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

フィールド

型

備考

clinic_id

string

必須

specialty

enum

general_practice

pediatrics

cardiology

dermatology

from_iso

string

ISO 8601 開始(含む)

to_iso

string

ISO 8601 終了(含まない)

duration_minutes

int

15〜120、デフォルト30

limit

int

1〜50、デフォルト10

book_appointment

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

フィールド

型

備考

clinic_id

string

必須

provider_id

string

clinic_id に属している必要がある

patient_id

string

clinic_id に属している必要がある

start_iso

string

ISO 8601

duration_minutes

int

15〜120、デフォルト30

reason

string

1〜500文字

idempotency_key

string

8〜128文字、呼び出し元が提供

{ appointment, idempotent_replay } を返します。

record_intake

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

フィールド

型

備考

clinic_id

string

必須

patient_id

string

clinic_id に属している必要がある

symptoms

string[]

1〜20エントリ

severity

int

1〜10、患者申告

onset_iso

string

ISO 8601

notes

string

オプション、最大2000文字

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

search_protocols

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

フィールド

型

備考

clinic_id

string

必須

query

string

1〜500文字

limit

int

1〜20、デフォルト5

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

escalate_to_oncall

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

フィールド

型

備考

clinic_id

string

必須

appointment_id

string

clinic_id に属している必要がある

reason

string

1〜500文字、予約の理由に追加

{ 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を参照してください。

Available Tools

5 tools
book_appointmentBook an appointmentB

Create an appointment for a patient with a provider. Requires an idempotency_key; repeated calls with the same key return the original appointment instead of double-booking.

Inputs: clinic_id (required), provider_id (required), patient_id (required), start_iso (required), +3 more.

escalate_to_oncallEscalate an appointment to the on-call providerC

Mark an existing appointment as urgent and reassign it to the clinic's on-call provider.

Inputs: clinic_id (required), appointment_id (required), reason (required).

find_available_slotFind available appointment slotsB

Return open appointment slots for a given specialty in a date range. Filters by clinic_id and skips conflicts with existing appointments.

Inputs: clinic_id (required), specialty (required), from_iso (required), to_iso (required), +2 more.

record_intakeRecord patient intakeB

Persist a structured intake note (symptoms, severity, onset) for a patient and assign a triage level (routine / elevated / urgent).

Inputs: clinic_id (required), patient_id (required), symptoms (required), severity (required), +2 more.

search_protocolsSearch clinic protocol documentsB

Keyword search over the clinic's protocol library. Returns ranked snippets the model can cite when answering.

Inputs: clinic_id (required), query (required), limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: booking appointments, escalating to on-call, finding slots, recording intake, and searching protocols. No two tools overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case, making it easy to predict the action and resource for each tool.

    Tool Count5/5

    With exactly 5 tools, the server is well-scoped for a clinic domain, covering core patient-facing and administrative workflows without being overly heavy or thin.

    Completeness3/5

    The set covers appointment creation, urgent escalation, slot availability, intake recording, and protocol search. However, it lacks read/update/delete for appointments and any patient or provider management, which are notable gaps.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A reference MCP server demonstrating safe agent access to multi-tenant CRM data with tenant isolation enforced in the data layer, role-based permissions, and human confirmation on writes.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server reference implementation adding enterprise layers (identity, authorization, audit) around MCP, with sample shipment status and delayed shipment tools over a stateless transport.
      Apache 2.0