🧪 lab-ops

一个跑在本地的 MCP server，把训练服务器上那些反复手写的 SSH 操作封装成工具，交给支持 MCP 的 AI 助手（Claude Code 等）直接调度：查 GPU、后台提交训练任务、追踪任务状态、看日志、传文件——不用再每次现场敲命令。

服务器侧不需要装任何东西，本地通过 SSH/SCP 远程操作，密钥认证，零额外服务常驻。

✨ 特性

🎮 GPU 状态一览 — 显存占用、利用率，一条命令看全部卡
🚀 后台任务提交 — 基于 tmux，关掉终端任务也不会断
🧠 提交前显存预检查 — 自动解析命令里的 CUDA_VISIBLE_DEVICES，显存不够直接拒绝提交，避免又一次眼睁睁看着 OOM
📊 任务状态追踪 — running / completed / failed，附带真实退出码，不用再靠肉眼翻 Traceback
📄 日志随时看 — 支持只看最后 N 行
📦 文件双向传输 — 上传/下载任意文件（checkpoint、推理结果图、脚本……）
🔒 目录白名单 — 所有远程路径操作限制在配置好的目录范围内，防止手滑

🛠️ 工具列表

工具	作用
`gpu_status()`	查看各 GPU 显存占用和利用率
`list_jobs()`	列出当前活跃的 tmux 任务 session
`submit_job(session_name, workdir, command, conda_env, min_free_mb=None, force=False)`	提交后台训练/评估任务，自带显存预检查
`job_status(session_name, log_lines=20)`	查看任务状态 + 退出码 + 最新日志
`kill_job(session_name)`	终止指定任务
`tail_log(log_path, lines=100)`	查看日志最后 N 行
`list_remote_files(remote_dir)`	列出远程目录文件（按修改时间排序）
`download_file(remote_path, local_path)`	下载远程文件到本地
`upload_file(local_path, remote_path)`	上传本地文件到远程

📋 环境要求

本地：Python 3.10+，能通过密钥免密 SSH 到目标服务器
远程：tmux、conda（或调整 config.py 里的激活逻辑换成你自己的环境管理方式）

🚀 快速开始

git clone <your-repo-url> lab-ops
cd lab-ops
pip install -r requirements.txt
cp config.example.json config.json

编辑 config.json，填入你自己的信息：

{
  "host": "your.server.ip",
  "user": "your_ssh_username",
  "conda_base": "/home/your_username/anaconda3",
  "ssh_timeout": 15,
  "default_min_free_mb": 2048,
  "remote_base_dirs": [
    "/home/your_username/your_project_dir"
  ]
}

⚠️ config.json 已被 .gitignore 忽略，不会被提交，放心填真实信息。

本地调试：

python server.py
# 或用 MCP inspector
mcp dev server.py

🔌 接入 Claude Code

claude mcp add lab-ops -- python /path/to/lab-ops/server.py

注册后运行 /mcp 确认 lab-ops 已连接，就可以直接用自然语言让助手帮你查 GPU、提交任务、看日志了。

🔐 安全说明

远程命令统一走 ssh -o BatchMode=yes，密钥认证失败会直接报错，不会卡住等密码输入
所有涉及路径的工具（workdir、remote_dir、remote_path、log_path）都会校验是否在 remote_base_dirs 白名单内
submit_job / kill_job 会先检查同名 session 是否存在，避免误覆盖或误杀正在跑的任务
本项目不存储、不上传任何密码；SSH 认证完全基于密钥

📄 License

MIT