Real-World-Evidenz & klinische Machbarkeit MCP-Server

Repository: Krv-Labs/how-to-train-your-dragon

Bewertet US-amerikanische Gesundheitsorganisationen nach erwarteten randomisierten Probanden pro 12 Monaten für ein Graves-Krankheitsprotokoll (NCT07570316) anhand von Längsschnittdaten (Komodo) und öffentlichen Registern (ClinicalTrials.gov), bereitgestellt als interaktiver Model Context Protocol (MCP)-Server für KI-Agenten.

Das Python-Paket heißt httyd; der MCP-Server registriert sich als real-world-mcp. CLI-Einstiegspunkte: httyd, realworld-mcp und how-to-train-your-dragon.

Warum dieser Name? Basierend auf Komodo-Health-Abrechnungsdaten – den Komodo-Drachen zähmen und trainieren, um umsetzbare Machbarkeitsmodelle zu erstellen.

1. Architektur & Paketstruktur

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

Datenhinweis: Komodo-Abrechnungs-CSVs sind in .gitignore ausgeschlossen. Nur data/nct07570316_sites.json (Ground-Truth-Fixture) ist eingecheckt. Platzieren Sie lizenzierte Datendateien lokal in data/, bevor Sie die Engine ausführen.

Methodik und Validierungsnachweise: docs/README.md.

2. Schnellstart

Installation

uv sync

Vorab berechneter Cache (empfohlen)

Ein vollständiger nationaler Score-Neuaufbau dauert ~90 Sekunden. Einmal vorab berechnen und wiederverwenden:

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

Tests ausführen

REALWORLD_CACHE_DIR=./cache uv run pytest

Einige Tests (Sensitivitäts-Neubewertung, Validierung) lösen einen vollständigen Neuaufbau aus und dauern insgesamt ~2 Minuten.

MCP-Server starten

# 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

Lokale Vorschau-Dashboard generieren

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

3. MCP-Tool-Oberfläche

real-world-mcp stellt 16 Tools in 6 Bereichen bereit:

A. Datensatz-Erkennung & -Inspektion

• list_datasets, describe_dataset, get_cohort_summary

B. Modell-Registry & Herkunft

• list_models, get_provenance

C. Standortsuche & Deep-Dive

• search_and_score_sites, get_site_details, explain_site_score

D. Räumliche Einzugsgebiete & Korb-Optimierung

• compute_basket_catchment, find_nearby_competitors

E. Akkrual-Prognose & Sensitivität

• simulate_accrual_timeline, update_interim_accrual, compute_sensitivity_rescore, match_trial_facility

F. Validierung & Einschränkungen

• run_model_validation, get_model_limitations

4. MCP-Agenten-Konfiguration

{
  "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-Interne Bereitstellung

Bereitstellung als interner ClusterIP-MCP-Dienst. Subagent-Pods authentifizieren sich mit Kubernetes-ServiceAccount-Tokens, die über die TokenReview-API validiert werden.

Architektur

• Transport: streamable-http auf Port 8080 unter /mcp

• Authentifizierung: Bearer-Token = projiziertes ServiceAccount-Token (audience: httyd)

• Autorisierung: ConfigMap ordnet system:serviceaccount:<ns>:<name> → Bereiche zu

• Netzwerk: NetworkPolicy erlaubt eingehenden Datenverkehr nur aus Namespaces mit Label httyd-client: "true"

Build und Bereitstellung

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

Registrieren Sie Subagent-ServiceAccounts in deploy/helm/httyd/scopes.yaml, bevor Sie bereitstellen.

Subagent-Pod-Konfiguration

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"

Umgebungsvariablen