Servidor MCP

Jano incluye un servidor MCP local opcional para que agentes de IA puedan usar la librería a través de una superficie chica y explícita.

Esto sirve cuando querés que un agente:

  • inspeccione un dataset local,

  • infiera columnas candidatas de tiempo y target,

  • sugiera y valide una política de partición,

  • precalcule un plan walk-forward,

  • corra una simulación temporal,

  • ejecute un baseline simple,

  • y corra estudios temporales baseline sin escribir Python manualmente.

La primera superficie MCP es deliberadamente angosta. Se enfoca en el workflow más estable y más legible para agentes:

  • previsualizar e inspeccionar un dataset,

  • sugerir una política conservadora de partición,

  • validar una policy con plan() antes de correr modelos,

  • comparar estrategias de partición,

  • planificar una simulación walk-forward,

  • correr una simulación walk-forward,

  • correr un baseline sobre los mismos folds,

  • comparar policies de reentrenamiento,

  • evaluar ventanas de historia de entrenamiento,

  • monitorear decay con train fijo.

Por qué MCP además de la librería Python

Instalar una librería Python no alcanza para garantizar que un agente de IA la use correctamente.

La capa MCP le da al agente:

  • un conjunto chico de tools explícitas,

  • inputs y outputs estructurados,

  • y un workflow recomendado alineado con la superficie pública high-level de Jano.

Instalación

El servidor MCP depende del SDK oficial de MCP para Python y está pensado para entornos con Python 3.10+.

Instalalo con:

python -m pip install "jano[mcp]"

Cómo correr el servidor local

Corré el servidor MCP sobre stdio:

jano-mcp

O directamente vía módulo:

python -m jano.mcp_server

Tools MCP disponibles

preview_local_dataset

Lee un CSV local, un Parquet o un ZIP con CSV y devuelve una preview compacta.

inspect_local_dataset

Inspecciona schema, dtypes, nulos, ejemplos y columnas candidatas para time_col / target_col. Es la primera tool más segura cuando un agente recibe un archivo local nuevo.

suggest_temporal_partition_policy

Sugiere una policy inicial conservadora según la forma del dataset. Puede devolver una policy temporal walk-forward o una policy online basada en eventos según el objective pedido.

validate_temporal_partition_policy

Ejecuta plan() y devuelve diagnósticos antes de entrenar cualquier modelo. La respuesta marca folds vacíos, folds parciales, train/test demasiado chicos y ordenamientos sospechosos entre límites de train y test.

compare_temporal_partition_strategies

Compara varias configuraciones candidatas a nivel de plan. Sirve cuando un agente quiere elegir entre layouts diarios, semanales, rolling o expanding antes de correr código de modelo.

plan_walk_forward_simulation

Construye un plan() walk-forward y devuelve boundaries por iteración, conteos de filas y metadata del motor de particionado elegido.

run_walk_forward_simulation

Materializa una simulación walk-forward y devuelve un resumen compacto, metadata del motor de particionado elegido y el HTML renderizado.

run_walk_forward_baseline_model

Ejecuta un baseline incorporado sobre los folds walk-forward y devuelve datos del runner: resumen agregado, preview de folds, trayectoria de métricas, eventos de reentrenamiento y una preview acotada de predicciones opcional. Usá model="mean" para targets numéricos de regresión y model="majority_class" para targets de clasificación.

compare_retrain_policy_baselines

Ejecuta el mismo baseline sobre la misma geometría temporal cambiando la policy de reentrenamiento. Devuelve una fila de comparación por policy y previews por policy de folds y métricas.

find_train_history_window_baseline

Evalúa distintas ventanas de historia de entrenamiento contra un test fijo y devuelve la ventana más chica que queda dentro de la tolerancia configurada respecto del mejor score.

monitor_decay_baseline

Mantiene fijo el train, mueve el test hacia adelante y devuelve la primera ventana donde la métrica elegida cruza el umbral de degradación configurado.

Las tools de planning y ejecución aceptan engine con los mismos valores que la API Python: "auto", "pandas", "polars" o "numpy".

Workflow recomendado para agentes

Para un dataset nuevo, conviene usar esta secuencia MCP:

  1. inspect_local_dataset para identificar columnas candidatas de tiempo y target.

  2. suggest_temporal_partition_policy para obtener una policy inicial conservadora.

  3. validate_temporal_partition_policy para inspeccionar geometría de folds y warnings.

  4. compare_temporal_partition_strategies si hay varias policies plausibles.

  5. plan_walk_forward_simulation o run_walk_forward_simulation recién cuando la geometría de partición sea aceptable.

Ejemplo de validación de policy:

{
  "dataset_path": "data/flights.csv",
  "partition": {
    "layout": "train_test",
    "train_size": "30D",
    "test_size": "7D"
  },
  "step": "7D",
  "time_col": "scheduled_departure_at",
  "max_folds": 10
}

Ejemplo de baseline runner

{
  "dataset_path": "data/bts/bts_ontime_2024_01.zip",
  "partition": {
    "layout": "train_test",
    "train_size": "7D",
    "test_size": "1D"
  },
  "step": "1D",
  "time_col": "FL_DATE",
  "target_col": "arrival_state",
  "model": "majority_class",
  "retrain": "periodic",
  "retrain_interval": 2,
  "max_folds": 5
}

Esta tool es intencionalmente un baseline, no un ejecutor general de modelos arbitrarios. MCP JSON no puede transportar callables de Python, por lo que las corridas productivas con métricas deberían usar WalkForwardRunner directamente desde Python. Así la construcción del modelo, feature engineering y métricas custom quedan en código del usuario.

Ejemplos de estudios temporales

Comparar policies de reentrenamiento sobre la misma geometría:

{
  "dataset_path": "data/flights.csv",
  "partition": {
    "layout": "train_test",
    "train_size": "14D",
    "test_size": "1D"
  },
  "step": "1D",
  "time_col": "scheduled_departure_at",
  "target_col": "arrival_delay",
  "model": "mean",
  "policies": [
    {"name": "always", "retrain": "always"},
    {"name": "never", "retrain": "never"},
    {"name": "weekly", "retrain": "periodic", "retrain_interval": 7}
  ]
}

Buscar una ventana compacta de train history contra un test fijo:

{
  "dataset_path": "data/flights.csv",
  "time_col": "scheduled_departure_at",
  "cutoff": "2024-02-01",
  "train_sizes": ["7D", "14D", "30D"],
  "test_size": "3D",
  "target_col": "arrival_delay",
  "metric": "mae",
  "tolerance": 0.02
}

Monitorear decay con train fijo:

{
  "dataset_path": "data/flights.csv",
  "time_col": "scheduled_departure_at",
  "cutoff": "2024-02-01",
  "train_size": "30D",
  "test_size": "1D",
  "step": "1D",
  "target_col": "arrival_delay",
  "metric": "mae",
  "threshold": 0.10,
  "relative": true
}

Ejemplo de configuración del cliente MCP

Muchos clientes MCP aceptan una entrada de configuración como esta:

{
  "mcpServers": {
    "jano": {
      "command": "jano-mcp"
    }
  }
}

Si preferís un comando Python explícito:

{
  "mcpServers": {
    "jano": {
      "command": "python",
      "args": ["-m", "jano.mcp_server"]
    }
  }
}

Asistentes de código con IA

El servidor MCP está pensado para asistentes de código con soporte MCP, como Claude Code, Claude Desktop, Cursor, runtimes de Codex con MCP y otros entornos locales de agentes.

Jano siempre puede usarse directamente como librería Python. El servidor MCP sirve cuando querés que el asistente vea un conjunto chico de tools declaradas, en lugar de inferir imports y componer código Python desde cero.

Usá la misma configuración local en cualquier cliente compatible con MCP:

{
  "mcpServers": {
    "jano": {
      "command": "python",
      "args": ["-m", "jano.mcp_server"]
    }
  }
}

Modelo de privacidad

El servidor corre localmente. Lee archivos locales a través del proceso iniciado por tu cliente MCP. Jano no sube datasets a ningún lado por sí mismo.

El acceso a archivos depende del entorno del cliente y de los paths que le pases a las tools, así que conviene usar rutas dentro del proyecto y evitar dar acceso amplio a carpetas no relacionadas.

Alcance actual

La primera versión MCP no intenta exponer todas las primitives de Jano.

Empieza deliberadamente con:

  • preview de datasets,

  • planning,

  • simulación walk-forward,

  • ejecución de baselines,

  • estudios temporales baseline.

La composición low-level y las policies temporales más ligadas a modelos siguen disponibles en la librería Python.