real-world-mcp
実世界エビデンス&臨床実現可能性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.html3. 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"というラベルが付いたネームスペースからのイングレスのみを許可
スコープ | アクセス |
| 発見、検索、説明、来歴ツール |
| 患者登録シミュレーション、感度再スコア、バスケットキャッチメント |
ビルドとデプロイ
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=trueserviceAccountName: 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"環境変数
変数 | デフォルト | 目的 |
|
| K8sトークン認証を有効にする |
|
| OAuthリソース識別子 |
|
| SA → スコープマッピング |
|
| 期待されるトークンオーディエンス |
|
| 事前計算されたサイト/地理JSON |
|
| HTTPリッスンポート |
|
| HTTPバインドアドレス |
|
| ステートレスMCPセッション(K8s推奨) |
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Claims-grounded provider, market, and KOL intelligence for healthcare AI agents via Alpha Sophia
US healthcare data for AI agents: CMS, FDA adverse events, CDC, NPPES NPI. Keyless, real samples.
FDA 510(k)s, PMAs, recalls & trials, linked: predicate search and review-time stats for AI agents.
Governance for AI agents in health systems: inventory, scoped permissions, evidence, revocation.