Real-World Evidence & Clinical Feasibility MCP Server

Репозиторий: Krv-Labs/how-to-train-your-dragon

Ранжирует медицинские организации США по ожидаемому числу рандомизированных субъектов за 12 месяцев для протокола по болезни Грейвса (NCT07570316) на основе продольных страховых требований (Komodo) и публичных реестров (ClinicalTrials.gov), предоставляя доступ через интерактивный сервер Model Context Protocol (MCP) для ИИ-агентов.

Пакет Python называется httyd; MCP-сервер регистрируется как real-world-mcp. Точки входа CLI: httyd, realworld-mcp и how-to-train-your-dragon.

Почему такое название? Создано на основе данных страховых требований Komodo Health — укрощение и обучение комодского дракона для создания применимых моделей осуществимости.

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

Примечание о данных: CSV-файлы страховых требований Komodo исключены из git. В репозиторий включён только 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 предоставляет 16 инструментов в 6 областях:

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-сервис. Поды субагентов аутентифицируются с помощью токенов Kubernetes ServiceAccount, проверяемых через TokenReview API.

Архитектура

• Транспорт: streamable-http на порту 8080 по пути /mcp

• Аутентификация: 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

Зарегистрируйте ServiceAccounts субагентов в deploy/helm/httyd/scopes.yaml перед развёртыванием.

Конфигурация пода субагента

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"

Переменные окружения