real-world-mcp
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.mdDatenhinweis: 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 syncVorab 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 presentTests ausführen
REALWORLD_CACHE_DIR=./cache uv run pytestEinige 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/healthLokale Vorschau-Dashboard generieren
uv run python ui/build_dashboard.py
open output/site_feasibility.html3. 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-httpauf Port 8080 unter/mcpAuthentifizierung: Bearer-Token = projiziertes ServiceAccount-Token (
audience: httyd)Autorisierung: ConfigMap ordnet
system:serviceaccount:<ns>:<name>→ Bereiche zuNetzwerk: NetworkPolicy erlaubt eingehenden Datenverkehr nur aus Namespaces mit Label
httyd-client: "true"
Bereich | Zugriff |
| Erkennung, Suche, Erklärung, Herkunfts-Tools |
| Akkrual-Simulation, Sensitivitäts-Neubewertung, Korb-Einzugsgebiet |
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.0Registrieren Sie Subagent-ServiceAccounts in deploy/helm/httyd/scopes.yaml, bevor Sie bereitstellen.
Subagent-Pod-Konfiguration
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"Umgebungsvariablen
Variable | Standard | Zweck |
|
| K8s-Token-Authentifizierung aktivieren |
|
| OAuth-Ressourcenkennung |
|
| SA → Bereichszuordnung |
|
| Erwartete Token-Audience |
|
| Vorab berechnete Standort-/Geo-JSON |
|
| HTTP-Listen-Port |
|
| HTTP-Bind-Adresse |
|
| Zustandslose MCP-Sitzungen (für K8s empfohlen) |
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.