# Claude Code + MCP 演示指南（自然语言管理 HPC 集群）

> 相比录屏视频，直接在 **Claude Code** 里演示更直观：你用人话问，Claude 自动调用
> `xce-scheduler` MCP 工具查集群、查作业、诊断 PEND、提交/取消作业。

## 前置条件

| 项 | 要求 |
|---|---|
| MCP 二进制 | `/tmp/xce-mcp`（最新构建，Claude Code 通过它连 apiserver）|
| API key | 有效的 mcp_operator key（90 天）|
| 环境变量 | 启动 Claude Code **前** export `XCE_API_URL` + `XCE_API_KEY` |
| 集群 | t1/t2/t3 3 节点健康，无残留作业 |
| 项目目录 | 在 `/home/lchen/code/xce` 下启动（加载 `.mcp.json`）|

## 启动步骤

```bash
export XCE_API_URL='http://172.31.1.30:8080'
export XCE_API_KEY='<mcp_operator key，见 /tmp/xce_apikey>'  # 用当前有效 key
cd /home/lchen/code/xce
claude
```

启动后可用 `/mcp` 确认 `xce-scheduler` 已连接（工具 `scheduler_list_nodes`、`scheduler_submit` 等 15 个）。

**关键点**：`.mcp.json` 里 `XCE_API_KEY` 用的是 `${XCE_API_KEY}` 环境变量，所以必须在启动
Claude Code 的 shell 里 export。没 export 的话 MCP 工具会加载失败或报鉴权错。

## 演示流程（7 个场景，约 5 分钟）

按顺序输入以下自然语言即可（工具已预批准，写操作直接执行）：

| # | 提问（直接复制粘贴） | 触发工具 | 亮点 |
|---|---|---|---|
| 1 | 看看集群现在有哪些节点、资源怎么样 | list_nodes + cluster_metrics | 一句话看集群健康 |
| 2 | 列出当前所有作业，特别是排队的 | list_jobs | 作业队列 |
| 3 | 帮我看看 pending 的作业为什么还没跑 | pend_reasons | **核心**：PEND 原因直读 |
| 4 | 帮我在 xce 队列提交一个 sleep 20 的测试作业 | submit | 自然语言提交 |
| 5 | 等刚才那个作业跑完 | wait_job | 阻塞等待并汇报 |
| 6 | 我要跑一个科学计算，帮我看看需要多少资源 | suggest_resources | 结合实时负载给建议 |
| 7 | 把刚才那个测试作业取消掉 | cancel | 自然语言取消 |

## 给领导演示的讲解要点

1. **无需记命令**：作业查询/提交/取消都是日常高频操作，从"背命令+查文档"变成"一句话"。
2. **透明**：PEND 原因（配额/资源/匹配）、资源建议都有可读解释，不再黑盒。
3. **安全**：MCP 写工具走 RBAC（mcp_operator 角色），Claude Code 会话里也能看到每次工具调用。
4. **标准协议**：MCP 是开放标准，工具可扩展，未来可接更多集群运维能力。

## 注意事项

- **key 失效**：apiserver 重启会清空内存中的 key，需重新生成（admin JWT → POST /xce/v1/apikeys）。
- **演示前清理**：先删历史作业（场景 3 需要一个 PEND 作业才有看头——可临时提交一个超配额作业）。
- **模型选择**：当前会话模型为 `deepseek-v4-flash[1m]`（见状态栏），不影响 MCP 功能。
- **自动录屏版**：`/tmp/cc_demo_record.sh`（Xvfb + lxterminal + xdotool 自动驱动 7 场景，产出
  `/tmp/cc-mcp-demo-final.mp4`），适合无法现场演示时用。