ml-lab-mcp

Сервис MCP (Model Context Protocol), развёрнутый на сервере, который позволяет большой языковой модели использовать эту машину как ресурс для обучения машинному обучению / обучению с подкреплением:

• Синхронизация кода — sync_repo(repo_dir, ref?) сначала делает fetch, затем fast-forward клона на сервере, возвращает commit/ветку/грязные файлы/число опережений и отставаний, гарантируя, что запускается именно тот код, который пользователь запушил на GitHub; только ff, без reset, при расхождении честно сообщает об ошибке. get_repo_state только читает, ничего не меняет

• Отправка эксперимента — submit_experiment запускает произвольную shell-команду в фоновом режиме (bash -lc, действует окружение входа conda/venv и т.п.), возвращает уникальный job_id; параметр uv_project позволяет выполнять команду в окружении указанного uv-проекта (uv run --project), у разных алгоритмических проектов свои окружения; в метаданных задания фиксируется снимок git commit/ветки/грязных файлов рабочего каталога, по которому впоследствии можно проверить версию кода

• Мониторинг прогресса — get_job_status(job_id) возвращает elapsed_seconds (сколько уже выполняется), progress_ratio и eta_seconds (сколько осталось, линейная экстраполяция по самостоятельно сообщаемому экспериментом прогрессу step/timestep/episode/epoch, либо прямая передача самостоятельно сообщённого eta_seconds); get_job_logs показывает хвост логов; при параллельном запуске нескольких экспериментов они однозначно сопоставляются по job_id, без путаницы

• Метрики обучения — read_tensorboard(logdir, tag?) напрямую разбирает event-файлы и отвечает на вопрос «как идёт обучение»: сначала перечисляет scalar-теги каждого run, затем берёт указанную кривую (равномерная децимация, включая latest/min/max), без запуска процесса TensorBoard

• Сервис TensorBoard — start_tensorboard(logdir, port?, uv_project?) запускает веб-версию для просмотра человеком, возвращает URL; stop_tensorboard / list_tensorboards для управления

• Уведомление о завершении — эксперимент может выполняться несколько часов, есть два пути дождаться его окончания: ① wait_for_job(job_id, timeout_seconds) — длинный опрос на стороне сервера, при завершении задания возвращает результат немедленно, при таймауте возвращает текущий статус, можно продолжить ожидание — используется обычное исходящее MCP-соединение клиент→сервер, машине, на которой работает Claude, не нужен публичный IP; ② callback_url — после завершения задания сервер отправляет POST с финальными метаданными (3 повтора) — обратите внимание, что этот URL должен быть достижим с сервера, поэтому не указывайте локальную машину без публичного IP; его реальное назначение — указывать на push-сервисы вроде ntfy.sh / Bark / Server酱, чтобы доставить уведомление «обучение завершено» на ваш телефон

• Получение результатов — место результатов определяет вызывающая сторона (указывается в командной строке при отправке), забираются по пути через универсальные list_files(path) / read_file(path); сервер не собирает и не управляет файлами результатов

• Завершение и очистка — cancel_job отправляет SIGTERM всей группе процессов (force=True — вместо этого SIGKILL); delete_job удаляет учётные записи завершённых заданий, delete_path рекурсивно удаляет указанный вызывающей стороной каталог результатов/логов (отклоняет /, домашний каталог и корень учётных данных сервера); метаданные заданий сохраняются на диск, после перезапуска сервера история сохраняется

• Аутентификация в публичной сети — HTTP-транспорт принудительно требует Bearer token (MLLAB_AUTH_TOKEN), запросы без токена или с неверным токеном получают 401

Быстрый старт

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

Если не задан MLLAB_AUTH_TOKEN, HTTP-сервис откажется запускаться (при развёртывании в публичной сети аутентификация обязательна).

Related MCP server: colab-autopilot

Подключение клиента

Claude Code:

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

Аналогично для других MCP-клиентов, поддерживающих streamable HTTP: URL указывает на http://<server-ip>:8000/mcp, каждый запрос несёт заголовок Authorization: Bearer <token>. Для локальной отладки можно использовать stdio (без аутентификации): uv run mcp dev src/ml_lab_mcp/server.py.

Типичный сценарий использования (с точки зрения большой модели, на примере DRL-обучения)

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)

Каталоги и соглашения

$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            # 其运行日志

Процесс задания получает переменные окружения JOB_ID, JOB_DIR, PROGRESS_FILE. Скрипт эксперимента по соглашению пишет JSON в $PROGRESS_FILE, и get_job_status включает этот прогресс в ответ, а также оценивает по нему оставшееся время: распознаёт любую из пар (step, total_steps), (timestep, total_timesteps), (episode, total_episodes), (epoch, total_epochs) и делает линейную экстраполяцию; скрипт также может напрямую сообщить eta_seconds. Куда писать файлы результатов — полностью определяется аргументами командной строки, см. examples/example_experiment.py.

Payload колбэка — это содержимое meta.json (job_id, status, exit_code и т.д.), результат доставки записывается в поле callback_status, его можно проверить через get_job_status. Такие сервисы, как ntfy.sh, принимают произвольное тело POST и работают без регистрации: в callback_url укажите https://ntfy.sh/<выбранная вами тема>, установите на телефон приложение ntfy и подпишитесь на ту же тему — уведомления будут приходить.

Переменные окружения

Замечания по безопасности

• Аутентификация — это статический Bearer token (сравнение за константное время). При развёртывании в публичной сети рекомендуется добавить HTTPS: поставьте перед сервисом обратный прокси nginx/caddy для завершения TLS, передавать token открытым текстом через публичную сеть небезопасно.

• По замыслу, сторона, владеющая token, может выполнять на сервере произвольные команды, читать/удалять произвольные файлы (от имени пользователя, под которым работает сервис). Берегите token и рассмотрите запуск сервиса под отдельной учётной записью с минимальными правами.

• start_tensorboard по умолчанию привязывается к 0.0.0.0, а сам TensorBoard не имеет аутентификации — на машине с публичным IP любой, кто может достучаться до этого порта, увидит метрики обучения. Если это важно, ограничьте порт файрволом, либо не запускайте TensorBoard, а используйте read_tensorboard с пересказом через модель, либо ходите через SSH-туннель.

Направления развития

• Планирование GPU/очередь: добавьте очередь и лимит параллельности перед JobManager.submit, распределяйте карты через CUDA_VISIBLE_DEVICES.

• Получение больших файлов: read_file за один раз отдаёт не более 200 КБ (можно листать через offset); для больших checkpoint'ов рекомендуется rsync/scp или отдельная конечная точка загрузки файлов.

• Несколько токенов /分级 прав: в BearerAuthMiddleware замените один token на таблицу токенов.

• Подпись колбэков: для защиты от подделки можно добавить HMAC-подпись в заголовки колбэк-запроса, чтобы получатель мог её проверить.

Запуск тестов

uv run pytest