🧪 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