docs(scheduler-agent): add Claude Code integration guide to verification manual

New §5 in src/docs/chatbot-verification.md: how to connect Claude Code to
the scheduler-agent MCP server. Covers building the mcp-server binary,
`claude mcp add` CLI registration (verified against installed CLI
v2.1.220), the .mcp.json project config schema, the three scopes
(local/user/project), the first-run approval gate, verification commands,
and stdio/env gotchas. Original §5-§7 renumbered to §6-§8.

Co-Authored-By: Claude <noreply@anthropic.com>

src/docs/chatbot-verification.md

@@ -22,7 +22,7 @@
 | scheduler | `xce_scheduler` | t1 | 7890 |
 | worker | `xcecd` | t1 / t2 / t3 | — |
 
-**拓扑说明**：本次验证采用 **t1 单节点 controller**（3 节点 HA 选举因遗留 term 状态卡在 STANDBY，见 §6 已知问题）。单节点用 `--peers` 省略即可。
+**拓扑说明**：本次验证采用 **t1 单节点 controller**（3 节点 HA 选举因遗留 term 状态卡在 STANDBY，见 §7 已知问题）。单节点用 `--peers` 省略即可。
 
 ---
 
@@ -207,11 +207,93 @@ JOB=$(curl -s -X POST -H "Authorization: $KEY" -H "Content-Type: application/jso
 curl -s -H "Authorization: $KEY" "$BASE/xce/v1/jobs"
 ```
 
-**当前限制**：`hold/release/cancel`（job control）返回 **HTTP 500** —— apiserver 预存 bug（bug-1490），见 §6。
+**当前限制**：`hold/release/cancel`（job control）返回 **HTTP 500** —— apiserver 预存 bug（bug-1490），见 §7。
 
 ---
 
-## 5. schedulerclient / mcp-server 本地验证
+## 5. 接入 Claude Code
+
+让 Claude Code（终端里的 AI 助手）直接用自然语言操作集群。Claude Code 通过 MCP 协议连接我们的 `mcp-server`，后者再经 `schedulerclient` 调 apiserver。
+
+```
+Claude Code ──stdio/MCP──> mcp-server ──HTTP──> apiserver ──> controller
+                          (我们的二进制)
+```
+
+### 5.1 构建 mcp-server 二进制
+
+```bash
+cd /home/lchen/code/xce/src/frontend/mcp-server
+go build -o /tmp/xce-mcp ./cmd/main.go
+# 产物 ~12MB，CGO_ENABLED=0 纯静态（生产可放到 /usr/local/bin/xce-mcp）
+```
+
+> 前置：集群必须已在跑（见 §3），且有 `mcp_operator` API Key（见 §4.1）。
+
+### 5.2 方式 A：CLI 注册（推荐）
+
+`claude mcp add` 会写配置并校验语法（Claude Code v2.x 验证过的格式）：
+
+```bash
+claude mcp add xce-scheduler -s project \
+  -e XCE_API_URL=http://172.31.1.30:8080 \
+  -e XCE_API_KEY=<你的 mcp_operator key> \
+  -- /tmp/xce-mcp
+```
+
+- `xce-scheduler`：服务器名（Claude 看到的工具前缀）
+- `-s project`：写进项目根 `.mcp.json`（可随 git 共享给团队）。其他选项：`local`（默认，只在本机本项目）、`user`（本机所有项目）
+- `-e`：传给二进制两个环境变量（`XCE_API_URL` 是 apiserver 地址；`XCE_API_KEY` 必填，缺了 mcp-server 会 `log.Fatal`）
+- `--` 之后是二进制路径 + 参数；`-e/-s` 等标志必须在 `--` 之前
+- stdio 是默认传输，无需 `-t stdio`
+
+### 5.3 方式 B：手写 `.mcp.json`
+
+项目根 `.mcp.json`（当前是空的 `{"mcpServers": {}}`）填成：
+
+```json
+{
+  "mcpServers": {
+    "xce-scheduler": {
+      "type": "stdio",
+      "command": "/tmp/xce-mcp",
+      "args": [],
+      "env": {
+        "XCE_API_URL": "http://172.31.1.30:8080",
+        "XCE_API_KEY": "<你的 mcp_operator key>"
+      }
+    }
+  }
+}
+```
+
+- `"type": "stdio"` 必须（本地子进程服务器）；远程 HTTP 服务器用 `"type": "http"` + `"url"`
+- `command` 可以是绝对路径
+- `env` 支持 `${VAR}` 插值——**不要提交明文 key**，推荐写成 `"XCE_API_KEY": "${XCE_API_KEY}"`，启动 Claude Code 前 `export XCE_API_KEY=...`
+
+### 5.4 验证接入
+
+```bash
+claude mcp list                      # 列出所有服务器，带健康检查
+claude mcp get xce-scheduler         # 查看某服务器的详情（类型/命令/env/状态）
+claude mcp remove xce-scheduler      # 移除
+claude mcp reset-project-choices     # 重新触发审批
+```
+
+- 项目级（`.mcp.json`）服务器**首次需审批**：`claude mcp list` 显示 `⏸ Pending approval`，下次在项目里启动 `claude` 时接受即可。`local`/`user` 级无需审批。
+- 会话内可用 `/mcp` 命令查看/重连服务器，无需重启。
+- 审批通过后，Claude 就能用这些工具了。可以问：**"查看集群里有哪些作业在排队"**（走 `scheduler_list_jobs`）或 **"帮我提交一个 sleep 60 的作业"**（走 `scheduler_submit`，会先弹 review 卡确认）。
+
+### 5.5 注意事项
+
+- **stdio 约束**：mcp-server 只能往 stdout 写 MCP 协议消息；任何 `fmt.Println` 到 stdout 会损坏连接。本项目安全——`mcp-go` 的 `ServeStdio` 用 stdout 走协议，`main.go` 的 `log.Printf` 写 stderr。改代码时保持这个约定。
+- **`XCE_API_URL` 必须显式设**：不设默认 `https://localhost:8080`，生产环境几乎肯定不对。
+- **写操作默认要确认**：`scheduler_submit` 有 `dry_run` review 模式 + destructive 注解（Claude Code 会先弹确认）；cancel/hold/release 也会弹确认。这是设计文档 §4.5 的"require confirm"在 MCP 层的体现。
+- **当前 cancel/hold/release 不可用**：底层 apiserver control 链路有 bug（bug-1490，HTTP 500）。接入后 submit 可用，control 类工具会报错，直到 bug-1490 修复。
+
+---
+
+## 6. schedulerclient / mcp-server 本地验证
 
 在本地仓库（`chatbot` 分支）可独立运行 Go 测试（不需要集群）：
 
@@ -251,7 +333,7 @@ go run /tmp/demo.go
 
 ---
 
-## 6. 已知问题
+## 7. 已知问题
 
 | 问题 | 状态 | Bug |
 |------|------|-----|
@@ -263,7 +345,7 @@ go run /tmp/demo.go
 
 ---
 
-## 7. 快速参考
+## 8. 快速参考
 
 | 操作 | 命令 |
 |------|------|
@@ -273,4 +355,4 @@ go run /tmp/demo.go
 | apiserver 日志 | `sudo tail /opt/xce/apiserver/logs/apiserver_out.log` |
 | 停 controller | `sudo fuser -k 9990/tcp` |
 | 重启 apiserver | `kill $(fuser 8080/tcp); cd /opt/newxce && setsid ./run.sh apiserver -d /opt/xce/apiserver &` |
-| 本地 Go 测试 | 见 §5 |
+| 本地 Go 测试 | 见 §6 |