ml-lab-mcp

サーバー上にデプロイする MCP(Model Context Protocol)サービス。大モデルがこのマシンを 機械学習/強化学習のトレーニングリソースとして使えるようにする:

• コード同期 — sync_repo(repo_dir, ref?) はサーバー上の clone を fetch してから fast-forward し、commit/ブランチ/ダーティファイル/先行・遅延数を返す。ユーザーが GitHub にプッシュしたコードがそのまま実行されることを保証する。 ff のみで reset は行わず、分岐している場合はその旨を正直にエラー報告する。 get_repo_state は参照のみで変更しない

• 実験の提出 — submit_experiment は任意のシェルコマンドをバックグラウンドジョブとして 実行し(bash -lc、conda/venv などのログイン環境が有効)、一意の job_id を返す。 uv_project パラメータで、指定した uv プロジェクト自身の環境内でコマンドを実行 (uv run --project)。アルゴリズムプロジェクトごとにそれぞれの環境を使う。 ジョブメタデータには workdir の git commit/branch/dirty スナップショットを記録し、 後からコードバージョンを検証できる

• 進捗の監視 — 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 ファイルを直接解析して 「トレーニングの出来はどうか」に答える:まず各 run の scalar tag を列挙し、 次に指定した曲線を取得(均一ダウンサンプリング、latest/min/max を含む)。 TensorBoard プロセスを起動する必要はない

• TensorBoard サービス — start_tensorboard(logdir, port?, uv_project?) は 人間が閲覧するためのウェブ版を起動し、URL を返す。stop_tensorboard / list_tensorboards で管理

• 完了通知 — 実験は数時間かかることがある。終了を待つ方法は2つ: ① wait_for_job(job_id, timeout_seconds) はサーバー側のロングポーリングで、 ジョブ終了時に即座に返る。タイムアウト時は現在の状態を返すので続けて待てる—— これはクライアント→サーバーの通常の MCP アウトバウンド接続を使うため、 Claude を実行しているマシンに公網(パブリック IP)は不要; ② callback_url はジョブ終了後にサーバーが最終メタデータを POST する(3回リトライ)。 この URL はサーバーから到達可能でなければならないので、公網のない本機を 指さないこと。実際の用途は 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)を必須とし、 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>"

streamable HTTP をサポートする他の MCP クライアントも同様: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 が渡される。 実験スクリプトは規約に従って $PROGRESS_FILE に JSON を書き、 get_job_status はこの進捗を付けて返し、それに基づいて残り時間を推定する: (step, total_steps)、(timestep, total_timesteps)、(episode, total_episodes)、(epoch, total_epochs) のいずれかのペアを認識して線形外挿する。 スクリプトが直接 eta_seconds を自己申告することもできる。結果ファイルの書き込み先は 完全にコマンドライン引数で決まる。 examples/example_experiment.py を参照。

コールバックのペイロードは meta.json の内容(job_id、status、exit_code など)。 配信結果は callback_status フィールドに記録され、get_job_status で確認できる。 ntfy.sh などのサービスは任意の POST body を受け付け、登録不要で使える: callback_url に https://ntfy.sh/<任意のトピック名> を指定し、スマホに ntfy App を 入れて同じトピック名を購読すれば通知を受け取れる。

環境変数

セキュリティについて

• 認証は静的な Bearer token 1つ(定数時間比較)。公網デプロイでは HTTPS を推奨: 前面に nginx/caddy リバースプロキシを置いて TLS 終端を行う。token を平文で 公網に流すのは安全ではない。

• 設計上、token を持つ呼び出し元はサーバー上で任意のコマンド実行・任意のファイルの 読み取り/削除ができる(サービスプロセスのユーザー権限で)。token は厳重に管理し、 低権限の専用アカウントでサービスを実行することを検討すること。

• start_tensorboard はデフォルトで 0.0.0.0 にバインドするが、TensorBoard 自体には 認証がない——公網マシンでそのポートにアクセスできる人は誰でもトレーニング指標を 見られる。気になる場合はファイアウォールでポートを制限するか、TensorBoard を 開かずに read_tensorboard でモデルに伝えさせるか、SSH トンネルを使うこと。

拡張の方向性

• GPU スケジューリング/キューイング:JobManager.submit の前にキューと 並行数の上限を追加し、CUDA_VISIBLE_DEVICES を設定して GPU の割り当てを行う。

• 大ファイルの取得:read_file は1回で最大 200 KB(offset でページング可能)。 大きな checkpoint は rsync/scp か、別途ファイルダウンロードエンドポイントを立てる。

• 複数 token / 権限の階層化:BearerAuthMiddleware で単一 token を token テーブルに 置き換えるだけ。

• コールバック署名:偽造防止が必要なら、コールバックのリクエストヘッダーに HMAC 署名を付けて受信側で検証できるようにする。

テストの実行

uv run pytest