ml-lab-mcp

Ein auf einem Server bereitgestellter MCP-Dienst (Model Context Protocol), der es großen Sprachmodellen ermöglicht, diese Maschine als Ressource für maschinelles Lernen/Verstärkendes Lernen zu nutzen:

• Code-Synchronisierung — sync_repo(repo_dir, ref?) führt zuerst einen fetch und dann einen Fast-Forward des Clones auf dem Server durch und gibt commit/Branch/dirty-Dateien/Vorsprung-Rückstand-Zahlen zurück, um sicherzustellen, dass genau der Code ausgeführt wird, den der Benutzer auf GitHub gepusht hat; nur ff, kein reset, bei Divergenz wird ehrlich ein Fehler gemeldet. get_repo_state prüft nur, ändert nichts

• Experiment einreichen — submit_experiment führt beliebige Shell-Befehle als Hintergrundjob aus (bash -lc, conda/venv- und andere Login-Umgebungen greifen), gibt eine eindeutige job_id zurück; der Parameter uv_project lässt den Befehl in der Umgebung des angegebenen uv-Projekts laufen (uv run --project), verschiedene Algorithmusprojekte nutzen jeweils ihre eigene Umgebung; die Job-Metadaten enthalten einen git commit/branch/dirty-Snapshot des workdir, sodass die Codeversion später verifiziert werden kann

• Fortschrittsüberwachung — get_job_status(job_id) gibt elapsed_seconds (wie lange gelaufen), progress_ratio und eta_seconds zurück (wie lange noch, linear extrapoliert aus den vom Experiment selbst gemeldeten step/timestep/episode/epoch-Fortschritten, oder direkt das selbst gemeldete eta_seconds durchgereicht); get_job_logs zeigt das Log-Ende; bei mehreren parallelen Experimenten wird über job_id eindeutig zugeordnet, keine Verwechslung

• Trainingsmetriken — read_tensorboard(logdir, tag?) parst direkt die Event-Dateien und beantwortet "Wie läuft das Training": zuerst werden die Scalar-Tags der einzelnen Runs aufgelistet, dann wird die angegebene Kurve abgerufen (gleichmäßig heruntergesampelt, inklusive latest/min/max), ohne einen TensorBoard-Prozess zu starten

• TensorBoard-Dienst — start_tensorboard(logdir, port?, uv_project?) startet die Web-Version für Menschen, gibt die URL zurück; stop_tensorboard / list_tensorboards zur Verwaltung

• Abschlussbenachrichtigung — Experimente können mehrere Stunden laufen, zwei Wege, auf das Ende zu warten: ① wait_for_job(job_id, timeout_seconds) serverseitiges Long-Polling, kehrt sofort zurück, wenn der Job endet, bei Timeout wird der aktuelle Status zurückgegeben und man kann weiterwarten – dies läuft über die normale MCP-Ausgangsverbindung Client→Server, die Maschine, auf der Claude läuft, benötigt keine öffentliche IP; ② callback_url – nach Jobende POSTet der Server die endgültigen Metadaten (3 Wiederholungsversuche) – beachte, dass diese URL vom Server aus erreichbar sein muss, also nicht auf einen lokalen Rechner ohne öffentliche IP zeigen; ihr eigentlicher Zweck ist es, auf ntfy.sh / Bark / ServerChan und ähnliche Push-Dienste zu zeigen, um "Training abgeschlossen" auf dein Handy zu pushen

• Ergebnisse abholen — Der Speicherort der Ergebnisse wird vom Aufrufer bestimmt (in der Befehlszeile des eingereichten Befehls geschrieben), mit den allgemeinen list_files(path) / read_file(path) werden sie über den Pfad abgeholt; der Server sammelt und verwaltet keine Ergebnisdateien

• Beenden und Aufräumen — cancel_job sendet SIGTERM an die gesamte Prozessgruppe (force=True sendet stattdessen SIGKILL); delete_job löscht die Buchhaltung beendeter Jobs, delete_path löscht rekursiv vom Aufrufer angegebene Ergebnis-/Log- Verzeichnisse (verweigert /, das Home-Verzeichnis und die serverseitige Buchhaltungswurzel); Job-Metadaten werden auf der Festplatte gespeichert, nach einem Neustart des Dienstes ist der Verlauf weiterhin vorhanden

• Öffentliche Authentifizierung — Der HTTP-Transport erzwingt ein Bearer-Token (MLLAB_AUTH_TOKEN), Anfragen ohne oder mit falschem Token erhalten ausnahmslos 401

Schnellstart

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

Wenn MLLAB_AUTH_TOKEN nicht gesetzt ist, verweigert der HTTP-Dienst den Start (bei öffentlicher Bereitstellung ist Authentifizierung Pflicht).

Related MCP server: secure-cluster-mcp

Client-Anbindung

Claude Code:

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

Andere MCP-Clients, die streamable HTTP unterstützen, funktionieren analog: Die URL zeigt auf http://<server-ip>:8000/mcp, jede Anfrage trägt den Header Authorization: Bearer <token>. Für lokales Debugging kann stdio verwendet werden (ohne Authentifizierung): uv run mcp dev src/ml_lab_mcp/server.py.

Typischer Ablauf (aus Sicht des großen Sprachmodells, am Beispiel DRL-Training)

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)

Verzeichnisse und Konventionen

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

Der Job-Prozess erhält die Umgebungsvariablen JOB_ID, JOB_DIR, PROGRESS_FILE. Das Experiment-Skript schreibt gemäß Konvention JSON in $PROGRESS_FILE, und get_job_status liefert dann diesen Fortschritt mit und schätzt daraus die verbleibende Zeit: Es erkennt jedes Paar (step, total_steps), (timestep, total_timesteps), (episode, total_episodes), (epoch, total_epochs) und extrapoliert linear; das Skript kann auch direkt eta_seconds selbst melden. Wohin die Ergebnisdateien geschrieben werden, wird vollständig durch die Befehlszeilenargumente bestimmt, siehe examples/example_experiment.py.

Die Callback-Payload ist der Inhalt von meta.json (job_id, status, exit_code usw.), das Zustellungsergebnis wird im Feld callback_status festgehalten und kann über get_job_status überprüft werden. Dienste wie ntfy.sh akzeptieren beliebige POST-Bodies und sind ohne Registrierung nutzbar: callback_url auf https://ntfy.sh/<selbst gewähltes Thema> setzen, auf dem Handy die ntfy-App installieren und dasselbe Thema abonnieren, um Push-Benachrichtigungen zu erhalten.

Umgebungsvariablen

Sicherheitshinweise

• Die Authentifizierung ist ein statisches Bearer-Token (Vergleich in konstanter Zeit). Für öffentliche Bereitstellung wird zusätzlich HTTPS empfohlen: einen nginx/caddy-Reverse-Proxy für TLS-Terminierung davorstellen – ein Token im Klartext über das öffentliche Internet ist unsicher.

• Per Design kann ein Aufrufer mit gültigem Token auf dem Server beliebige Befehle ausführen und beliebige Dateien lesen/löschen (mit der Benutzeridentität des Dienstprozesses). Bewahre das Token sorgfältig auf und erwäge, den Dienst mit einem speziellen Konto mit geringen Rechten zu betreiben.

• start_tensorboard bindet standardmäßig an 0.0.0.0, und TensorBoard selbst hat keine Authentifizierung – auf einer öffentlich erreichbaren Maschine kann jeder, der auf diesen Port zugreifen kann, die Trainingsmetriken sehen. Falls das ein Problem ist, schränke den Port per Firewall ein, oder starte kein TensorBoard und nutze stattdessen read_tensorboard, damit das Modell die Werte wiedergibt, oder verwende einen SSH-Tunnel.

Erweiterungsmöglichkeiten

• GPU-Scheduling/Warteschlange: Vor JobManager.submit eine Warteschlange und ein Parallelitätslimit einfügen, CUDA_VISIBLE_DEVICES für die Karten-Zuweisung setzen.

• Große Dateien abholen: read_file liefert pro Aufruf maximal 200 KB (mit offset paginierbar); für große Checkpoints rsync/scp oder einen separaten Datei-Download-Endpunkt empfehlen.

• Mehrere Token / Berechtigungsstufen: In BearerAuthMiddleware das einzelne Token durch eine Token-Tabelle ersetzen.

• Callback-Signatur: Zur Fälschungssicherheit kann dem Callback-Request-Header eine HMAC-Signatur hinzugefügt werden, die der Empfänger verifizieren kann.

Tests ausführen

uv run pytest