Skip to main content
Glama

実世界エビデンス&臨床実現可能性MCPサーバー

リポジトリ: Krv-Labs/how-to-train-your-dragon

米国の医療機関を、縦断的クレーム(Komodo)と公開レジストリ(ClinicalTrials.gov)から得たグレーブス病プロトコル(NCT07570316)の12か月あたりの予想ランダム化被験者数でランク付けし、AIエージェント向けのインタラクティブなModel Context Protocol (MCP) サーバーとして公開します。

Pythonパッケージはhttydです。MCPサーバーは**real-world-mcp**として登録されます。CLIエントリポイント:httyd、realworld-mcp、how-to-train-your-dragon。

名前の由来は? Komodo Healthのクレームデータに基づいて構築 — Komodoドラゴンを飼いならし、訓練して実用的な実現可能性モデルにします。


1. アーキテクチャとパッケージ構造

how-to-train-your-dragon/
├── httyd/                          # Main Python package
│   ├── models/                     # L1–L5 parameters, provenance registry, recruitment math
│   ├── analysis/                   # Scoring pipeline, catchment, accrual, site linkage
│   ├── data/                       # Dataset catalog, loaders, CTG fetch
│   ├── evaluations/                # Temporal holdout validation
│   ├── auth/                       # Kubernetes token auth & scope enforcement
│   ├── engine.py                   # In-memory FeasibilityEngine singleton
│   ├── cache.py                    # Precomputed site/geo cache loader
│   └── server.py                   # MCP server (16 tools, 4 resources, 2 prompts)
├── ui/                             # Local observation dashboard (offline HTML)
│   ├── build_dashboard.py
│   └── (writes to output/site_feasibility.html)
├── data/                           # Claims & registry assets (not committed — see below)
├── docs/                           # Methodology, scoring review, evidence
├── deploy/helm/httyd/      # GKE Helm chart
├── scripts/precompute.py           # Build startup cache (Docker + local dev)
├── tests/
├── pyproject.toml
└── README.md

データに関する注意: KomodoクレームCSVはgitignoreされています。コミットされているのはdata/nct07570316_sites.json(グラウンドトゥルースフィクスチャ)のみです。エンジンを実行する前に、ライセンスされたデータファイルをローカルのdata/に配置してください。

方法論と検証エビデンス: docs/README.md。


2. クイックスタート

インストール

uv sync

キャッシュの事前計算(推奨)

全国スコアの完全再構築には約90秒かかります。一度事前計算して再利用してください:

uv run python scripts/precompute.py
export REALWORLD_CACHE_DIR=./cache   # optional; defaults to ./cache when present

テストを実行

REALWORLD_CACHE_DIR=./cache uv run pytest

一部のテスト(感度再スコア、検証)は完全再構築をトリガーし、合計約2分かかります。

MCPサーバーを起動

# stdio transport (default — Claude Desktop, Cursor)
uv run httyd

# streamable-http (local dev)
AUTH_ENABLED=false REALWORLD_CACHE_DIR=./cache uv run httyd streamable-http
curl http://localhost:8080/health

ローカルプレビューダッシュボードを生成

uv run python ui/build_dashboard.py
open output/site_feasibility.html

3. MCPツールサーフェス

real-world-mcpは6つの領域にわたって16のツールを公開しています:

A. データセットの発見と検査

  • list_datasets、describe_dataset、get_cohort_summary

B. モデルレジストリと来歴

  • list_models、get_provenance

C. サイト検索と詳細調査

  • search_and_score_sites、get_site_details、explain_site_score

D. 空間的キャッチメントとバスケット最適化

  • compute_basket_catchment、find_nearby_competitors

E. 患者登録予測と感度分析

  • simulate_accrual_timeline、update_interim_accrual、compute_sensitivity_rescore、match_trial_facility

F. 検証と限界

  • run_model_validation、get_model_limitations


4. MCPエージェント設定

{
  "mcpServers": {
    "real-world-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/how-to-train-your-dragon",
        "run",
        "httyd"
      ],
      "env": {
        "REALWORLD_CACHE_DIR": "/path/to/how-to-train-your-dragon/cache"
      }
    }
  }
}

5. GKE内部デプロイメント

内部ClusterIP MCPサービスとしてデプロイします。サブエージェントPodは、TokenReview APIを介して検証されるKubernetes ServiceAccountトークンで認証します。

アーキテクチャ

  • トランスポート: ポート8080の/mcpでstreamable-http

  • 認証: Bearerトークン = 投影されたServiceAccountトークン(audience: httyd)

  • 認可: ConfigMapがsystem:serviceaccount:<ns>:<name>をスコープにマッピング

  • ネットワーク: NetworkPolicyはhttyd-client: "true"というラベルが付いたネームスペースからのイングレスのみを許可

スコープ

アクセス

feasibility:read

発見、検索、説明、来歴ツール

feasibility:simulate

患者登録シミュレーション、感度再スコア、バスケットキャッチメント

ビルドとデプロイ

docker build -t httyd:0.1.0 .

helm upgrade --install httyd deploy/helm/httyd \
  -n realworld --create-namespace \
  --set image.repository=REGION-docker.pkg.dev/PROJECT/REPO/httyd \
  --set image.tag=0.1.0

デプロイ前に、deploy/helm/httyd/scopes.yamlでサブエージェントのServiceAccountを登録してください。

サブエージェントPod設定

kubectl label namespace app httyd-client=true
serviceAccountName: subagent-feasibility-reader
volumes:
  - name: mcp-token
    projected:
      sources:
        - serviceAccountToken:
            audience: httyd
            expirationSeconds: 3600
            path: token
volumeMounts:
  - name: mcp-token
    mountPath: /var/run/secrets/tokens
    readOnly: true
env:
  - name: HTTYD_MCP_URL
    value: "http://httyd.httyd.svc:8080/mcp"
  - name: HTTYD_MCP_TOKEN_FILE
    value: "/var/run/secrets/tokens/token"

環境変数

変数

デフォルト

目的

AUTH_ENABLED

false(ローカル)/ true(コンテナ)

K8sトークン認証を有効にする

MCP_RESOURCE_URL

http://httyd.httyd.svc:8080

OAuthリソース識別子

MCP_SCOPE_CONFIG

/etc/mcp/scopes.yaml

SA → スコープマッピング

MCP_TOKEN_AUDIENCE

httyd

期待されるトークンオーディエンス

REALWORLD_CACHE_DIR

./cache

事前計算されたサイト/地理JSON

PORT

8080

HTTPリッスンポート

HOST

0.0.0.0

HTTPバインドアドレス

STATELESS_HTTP

true

ステートレスMCPセッション(K8s推奨)

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors