ml-lab-mcp

서버에 배포되는 MCP(Model Context Protocol) 서비스로, 대형 언어 모델이 이 머신을 머신러닝/강화학습 학습 리소스로 사용할 수 있게 해줍니다:

• 코드 동기화 — sync_repo(repo_dir, ref?)는 먼저 fetch한 다음 서버의 clone을 fast-forward하고, commit/브랜치/더티 파일/앞서거나 뒤처진 수를 반환하여 실행되는 코드가 사용자가 GitHub에 푸시한 코드와 일치함을 보장합니다. ff만 수행하고 reset은 하지 않으며, 분기(fork) 시 정직하게 오류를 보고합니다. get_repo_state는 조회만 하고 변경하지 않습니다

• 실험 제출 — submit_experiment는 백그라운드 작업 방식으로 임의의 shell 명령어(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로 관리합니다

• 완료 알림 — 실험은 수 시간 실행될 수 있으며, 종료를 기다리는 두 가지 방법이 있습니다: ① wait_for_job(job_id, timeout_seconds) 서버 측 롱 폴링으로, 작업이 끝나면 즉시 반환하고, 타임아웃되면 현재 상태를 반환하여 이어서 기다릴 수 있습니다 — 이는 클라이언트→서버의 정상적인 MCP 아웃바운드 연결을 사용하므로, Claude를 실행하는 머신은 공인 IP가 필요 없습니다; ② callback_url은 작업 종료 후 서버가 최종 메타데이터를 POST합니다(3회 재시도) — 이 URL은 서버에서 접근 가능해야 하므로 공인 IP가 없는 로컬 머신을 가리키면 안 됩니다. 실제 용도는 ntfy.sh / Bark / Server酱 등 푸시 서비스를 가리켜 "학습 완료"를 휴대폰으로 받는 것입니다

• 결과 회수 — 결과 위치는 호출자가 결정하며(제출한 명령줄에 작성), 범용 list_files(path) / read_file(path)로 경로를 지정해 회수합니다. 서버는 결과 파일을 수집하거나 관리하지 않습니다

• 종료 및 정리 — cancel_job은 전체 프로세스 그룹에 SIGTERM을 보냅니다 (force=True는 SIGKILL로 변경). delete_job은 종료된 작업의 부기(bookkeeping)를 삭제하고, 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: secure-cluster-mcp

클라이언트 연동

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를 참조하세요.

콜백 payload는 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(상수 시간 비교) 한 겹입니다. 공개망 배포 시 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