Servidor MCP de Evidencia del Mundo Real y Viabilidad Clínica

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

Clasifica organizaciones de salud de EE. UU. por sujetos aleatorizados esperados por 12 meses para un protocolo de enfermedad de Graves (NCT07570316) a partir de reclamaciones longitudinales (Komodo) y registros públicos (ClinicalTrials.gov), expuesto como un servidor de Model Context Protocol (MCP) interactivo para agentes de IA.

El paquete de Python es httyd; el servidor MCP se registra como real-world-mcp. Puntos de entrada de CLI: httyd, realworld-mcp y how-to-train-your-dragon.

¿Por qué el nombre? Construido sobre datos de reclamaciones de Komodo Health: domar y entrenar al dragón de Komodo para convertirlo en modelos de viabilidad accionables.

1. Arquitectura y estructura del paquete

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

Nota sobre los datos: Los CSV de reclamaciones de Komodo están en gitignore. Solo se confirma data/nct07570316_sites.json (fixture de verdad de referencia). Coloque los archivos de datos con licencia en data/ localmente antes de ejecutar el motor.

Metodología y evidencia de validación: docs/README.md.

2. Inicio rápido

Instalación

uv sync

Precalcular caché (recomendado)

Una reconstrucción completa de la puntuación nacional tarda ~90s. Precalcule una vez y reutilice:

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

Ejecutar pruebas

REALWORLD_CACHE_DIR=./cache uv run pytest

Algunas pruebas (rescore de sensibilidad, validación) desencadenan una reconstrucción completa y tardan ~2 minutos en total.

Iniciar el servidor 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

Generar panel de vista previa local

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

3. Superficie de herramientas MCP

real-world-mcp expone 16 herramientas en 6 áreas:

A. Descubrimiento e inspección de conjuntos de datos

• list_datasets, describe_dataset, get_cohort_summary

B. Registro de modelos y procedencia

• list_models, get_provenance

C. Búsqueda de sitios y análisis en profundidad

• search_and_score_sites, get_site_details, explain_site_score

D. Captación espacial y optimización de cesta

• compute_basket_catchment, find_nearby_competitors

E. Previsión de acumulación y sensibilidad

• simulate_accrual_timeline, update_interim_accrual, compute_sensitivity_rescore, match_trial_facility

F. Validación y limitaciones

• run_model_validation, get_model_limitations

4. Configuración del agente 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. Despliegue interno en GKE

Despliegue como un servicio MCP ClusterIP interno. Los pods de subagente se autentican con tokens de ServiceAccount de Kubernetes validados mediante la API TokenReview.

Arquitectura

• Transporte: streamable-http en el puerto 8080 en /mcp

• Autenticación: token Bearer = token de ServiceAccount proyectado (audience: httyd)

• Autorización: ConfigMap asigna system:serviceaccount:<ns>:<name> → alcances

• Red: NetworkPolicy permite el tráfico entrante solo desde namespaces etiquetados con httyd-client: "true"

Compilar y desplegar

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

Registre los ServiceAccounts de subagente en deploy/helm/httyd/scopes.yaml antes de desplegar.

Configuración del pod de subagente

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"

Variables de entorno