# 🧪 lab-ops

一个跑在本地的 [MCP](https://modelcontextprotocol.io) 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` 里的激活逻辑换成你自己的环境管理方式）

## 🚀 快速开始

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

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

```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` 忽略，不会被提交，放心填真实信息。

本地调试：

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

## 🔌 接入 Claude Code

```bash
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