ml-lab-mcp

Un servicio MCP (Model Context Protocol) desplegado en un servidor que permite a los grandes modelos de lenguaje usar esta máquina como recurso de entrenamiento de aprendizaje automático/aprendizaje por refuerzo:

• Sincronización de código — sync_repo(repo_dir, ref?) primero hace fetch y luego fast-forward del clon en el servidor, devuelve commit/rama/archivos sucios/número de commits por delante y por detrás, garantizando que lo que se ejecuta es exactamente el código que el usuario subió a GitHub; solo hace ff, no reset, y reporta el error con honestidad si hay divergencia. get_repo_state solo consulta, no modifica.

• Enviar experimento — submit_experiment ejecuta cualquier comando de shell como trabajo en segundo plano (bash -lc, los entornos de login como conda/venv están activos), devuelve un job_id único; el parámetro uv_project hace que el comando se ejecute en el entorno propio del proyecto uv especificado (uv run --project), cada proyecto de algoritmo usa su propio entorno; los metadatos del trabajo registran una instantánea del commit/rama/sucio de git del workdir, para poder verificar la versión del código posteriormente.

• Supervisar progreso — get_job_status(job_id) devuelve elapsed_seconds (cuánto tiempo lleva), progress_ratio y eta_seconds (cuánto queda, extrapolado linealmente a partir del progreso de step/timestep/episode/epoch que el experimento reporta, o pasando directamente el eta_seconds auto-reportado); get_job_logs muestra el final de los logs; cuando hay varios experimentos en paralelo, se corresponden uno a uno mediante job_id, sin confusión.

• Métricas de entrenamiento — read_tensorboard(logdir, tag?) analiza directamente los archivos de eventos para responder "¿cómo va el entrenamiento?": primero lista los tags escalares de cada run, luego obtiene la curva especificada (con submuestreo uniforme, incluyendo latest/min/max), sin necesidad de iniciar un proceso de TensorBoard.

• Servicio TensorBoard — start_tensorboard(logdir, port?, uv_project?) inicia la versión web para que la vean humanos, devuelve la URL; stop_tensorboard / list_tensorboards para gestionar.

• Notificación de finalización — los experimentos pueden durar horas; hay dos formas de esperar a que terminen: ① wait_for_job(job_id, timeout_seconds) hace long polling en el servidor, devuelve inmediatamente cuando el trabajo termina, y si hay timeout devuelve el estado actual y se puede seguir esperando — usa la conexión saliente MCP normal de cliente→servidor, la máquina que ejecuta Claude no necesita IP pública; ② callback_url: cuando el trabajo termina, el servidor hace POST de los metadatos finales (con 3 reintentos) — ten en cuenta que esta URL debe ser alcanzable desde el servidor, así que no apuntes a una máquina local sin IP pública; su uso real es apuntar a servicios de notificación como ntfy.sh / Bark / Server酱, para enviar "entrenamiento completado" a tu teléfono.

• Recuperar resultados — la ubicación de los resultados la decide quien llama (se escribe en la línea de comandos enviada); se recuperan por ruta con los genéricos list_files(path) / read_file(path); el servidor no recopila ni gestiona los archivos de resultados.

• Terminar y limpiar — cancel_job envía SIGTERM a todo el grupo de procesos (force=True cambia a SIGKILL); delete_job elimina el registro de trabajos finalizados, delete_path elimina recursivamente los directorios de resultados/logs especificados por quien llama (rechaza /, el directorio personal y la raíz de registros del servidor); los metadatos de los trabajos se persisten en disco, el historial permanece tras reiniciar el servicio.

• Autenticación en Internet público — el transporte HTTP exige un Bearer token (MLLAB_AUTH_TOKEN); las peticiones sin token o con token incorrecto reciben 401.

Inicio rápido

cd ml-lab-mcp
uv sync

# 生成一个 token
export MLLAB_AUTH_TOKEN=$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')

# 启动服务(默认 0.0.0.0:8000,streamable HTTP,路径 /mcp)
uv run ml-lab-mcp

Si no se establece MLLAB_AUTH_TOKEN, el servicio HTTP se niega a arrancar (la autenticación es obligatoria en despliegues en Internet público).

Related MCP server: secure-cluster-mcp

Conexión del cliente

Claude Code:

claude mcp add --transport http ml-lab http://<server-ip>:8000/mcp \
  --header "Authorization: Bearer <token>"

Lo mismo aplica a otros clientes MCP que soporten streamable HTTP: la URL apunta a http://<server-ip>:8000/mcp, cada petición lleva la cabecera Authorization: Bearer <token>. Para depuración local se puede usar stdio (sin autenticación): uv run mcp dev src/ml_lab_mcp/server.py.

Flujo de uso típico (desde la perspectiva del gran modelo, con entrenamiento DRL como ejemplo)

0. sync_repo(repo_dir="/data/proj", ref="main")
   → 确认返回的 commit 就是用户刚推送的那个;dirty/分叉会如实报告
1. submit_experiment(
       command="python train.py --total-timesteps 1000000 --logdir /data/proj/runs/exp7",
       workdir="/data/proj",            # 是 git 仓库 → 元数据记录 commit
       uv_project="/data/proj",         # 用该项目自己的 uv 环境
       name="ppo baseline",
       callback_url="https://ntfy.sh/my-train-topic")   # 可选:训练完推送到手机
   → 记下返回的 job_id
2. wait_for_job(job_id, timeout_seconds=60)   # 会话内等结束:超时就再调一次续等
   get_job_status(job_id)     # 跑了多久 elapsed_seconds / 还剩多久 eta_seconds
   get_job_logs(job_id)       # 看训练日志尾部
   read_tensorboard("/data/proj/runs/exp7")                          # 列 scalar tag
   read_tensorboard("/data/proj/runs/exp7", tag="rollout/ep_rew_mean")  # 看回报曲线
   start_tensorboard("/data/proj/runs/exp7", port=6006)              # 给人一个网页 URL
3. 作业结束(回调通知或轮询到 succeeded/failed)后:
   list_files("/data/proj/runs/exp7")
   read_file("/data/proj/runs/exp7/metrics.json")
4. 不要了就清理(先与用户确认):
   cancel_job(job_id, force=True)   # 若还在跑
   delete_job(job_id)               # 删簿记
   delete_path("/data/proj/runs/exp7")  # 删结果/TensorBoard 日志
   stop_tensorboard(6006)

Directorios y convenciones

$MLLAB_ROOT (默认 ~/ml-lab)
├── jobs/
│   └── <job_id>/             # 仅作业簿记,不存实验结果
│       ├── meta.json         # 命令、uv 项目、git 快照、状态、pid、时间戳、退出码
│       ├── output.log        # stdout+stderr 合并日志
│       └── progress.json     # 实验自己写入的进度(可选约定)
└── tensorboard/
    ├── <port>.json           # 托管 TensorBoard 的 pid/logdir/url
    └── <port>.log            # 其运行日志

El proceso del trabajo recibe las variables de entorno JOB_ID, JOB_DIR, PROGRESS_FILE. El script del experimento escribe JSON en $PROGRESS_FILE según la convención, y get_job_status incluirá ese progreso y estimará el tiempo restante a partir de él: reconoce cualquiera de los pares (step, total_steps), (timestep, total_timesteps), (episode, total_episodes), (epoch, total_epochs) para hacer extrapolación lineal; el script también puede reportar directamente eta_seconds. Dónde se escriben los archivos de resultados lo decide completamente el parámetro de la línea de comandos; ver examples/example_experiment.py.

El payload del callback es el contenido de meta.json (job_id, status, exit_code, etc.); el resultado de la entrega se registra en el campo callback_status, verificable mediante get_job_status. Servicios como ntfy.sh aceptan cualquier cuerpo POST y se pueden usar sin registro: rellena callback_url con https://ntfy.sh/<nombre de tema elegido>, instala la app ntfy en el móvil y suscríbete al tema con el mismo nombre para recibir las notificaciones.

Variables de entorno

Notas de seguridad

• La autenticación es una capa de Bearer token estático (comparación en tiempo constante). Para despliegues en Internet público se recomienda añadir HTTPS: pon un proxy inverso nginx/caddy delante para terminar TLS; enviar el token en claro por Internet no es seguro.

• Por diseño, quien tenga el token puede ejecutar comandos arbitrarios y leer/eliminar archivos arbitrarios en el servidor (con la identidad del usuario del proceso del servicio). Guarda bien el token y considera ejecutar el servicio con una cuenta dedicada de bajos privilegios.

• start_tensorboard se enlaza a 0.0.0.0 por defecto, y TensorBoard en sí no tiene autenticación — cualquiera que pueda acceder a ese puerto en una máquina con IP pública podrá ver las métricas de entrenamiento. Si te preocupa, restringe el puerto con el firewall, o no actives TensorBoard y usa read_tensorboard para que el modelo lo relate, o usa un túnel SSH.

Direcciones de extensión

• Planificación/cola de GPU: añade una cola y un límite de concurrencia antes de JobManager.submit, y establece CUDA_VISIBLE_DEVICES para asignar GPUs.

• Recuperación de archivos grandes: read_file admite como máximo 200 KB por llamada (se puede paginar con offset); para checkpoints grandes se recomienda rsync/scp o crear un endpoint de descarga de archivos aparte.

• Múltiples tokens / niveles de permisos: en BearerAuthMiddleware, basta con sustituir el token único por una tabla de tokens.

• Firma de callbacks: si necesitas evitar falsificaciones, puedes añadir una firma HMAC en la cabecera de la petición del callback para que el receptor la verifique.

Ejecutar pruebas

uv run pytest