From 4a4ae16725cd574e6d364795a3418a184d747e89 Mon Sep 17 00:00:00 2001 From: "lei.chen" Date: Sun, 2 Aug 2026 04:26:23 +0000 Subject: [PATCH] docs(scheduler-agent): add Claude Code integration guide to verification manual MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .wolf/memory.md | 3 + src/docs/chatbot-verification.md | 94 ++++++++++++++++++++++++++++++-- 2 files changed, 91 insertions(+), 6 deletions(-) diff --git a/.wolf/memory.md b/.wolf/memory.md index 37c33110..c49ad2ca 100644 --- a/.wolf/memory.md +++ b/.wolf/memory.md @@ -7275,3 +7275,6 @@ | 06:53 | Synced /opt/newxce store (99 paths) + run.sh t1→t2,t3 (rsync, 929MB); cluster.bin built (sha 044f1b3a) + certs + workdir on t1 | t1/t2/t3 /opt/newxce | done | ~1k tok | | 08:59 | HA 3-node election deadlock (voted_for term residue + no-pool standbys) → switched to t1 single-node controller (omit --peers) per user; now CTRL_PRIMARY term=1 | t1 /opt/newxce | primary OK | ~1k tok | | 09:01 | Cluster up on t1: controller(9990, CTRL_PRIMARY) + apiserver(8080, RBAC OK) + scheduler + worker; t2/t3 workers launched | t1/t2/t3 | all daemons running | ~1k tok | +| 09:56 | Pushed chatbot branch to myxce (2e299f4..9fe14c1, 3 commits) | git push | done | ~0.2k tok | +| 09:58 | Wrote src/docs/chatbot-verification.md (cluster deploy + Phase 0-1 verify manual), added to design doc index, committed 56da673 + pushed | docs | done | ~1k tok | +| 04:26 | Added §5 "接入 Claude Code" to chatbot-verification.md (verified via claude-code-guide against installed CLI v2.1.220: claude mcp add / .mcp.json schema / scopes / approval gate) | src/docs/chatbot-verification.md | done | ~1k tok | diff --git a/src/docs/chatbot-verification.md b/src/docs/chatbot-verification.md index cf624f2d..6de5b17f 100644 --- a/src/docs/chatbot-verification.md +++ b/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 |