# world-of-claudecraft-mcp

一个 **MCP server 适配器**，让 LLM agent（如 **OpenClaw**）完全接管并自己玩
[World of ClaudeCraft](https://github.com/levy-street/world-of-claudecraft)。

它把游戏官方的 headless 环境（`headless/env_server.ts`，NDJSON over stdio）包成一组
MCP 工具。LLM 当 **policy**：读状态 → 决策 → 执行动作，循环往复，直到一局结束。

- 游戏内核（Sim）是官方同一个，无需重写任何游戏逻辑。
- 观测向量（数值）被解码成 LLM 能读懂的文字：血量/蓝量/等级/朝向、当前目标、
  5 个最近怪物、可交互物、任务进度、每个技能的就绪/冷却。
- 动作是命名枚举（来自游戏的 `ACTIONS` 列表），LLM 直接选名字，不用猜整数。

---

## 1. 前置：构建游戏的 headless 环境

这个 MCP server 本身只是个"翻译层"，它要 spawn 游戏编译出的 `env_server.cjs`。
所以先在**你的机器（Mac 推荐）**上把游戏的环境构建出来：

```bash
git clone https://github.com/levy-street/world-of-claudecraft
cd world-of-claudecraft
npm install
npm run build:env          # 产出 dist-env/env_server.cjs
node dist-env/env_server.cjs --bench   # 可选：跑个吞吐基准验证能起来
```

## 2. 构建这个 MCP server

```bash
cd world-of-claudecraft-mcp
npm install
npm run build              # 产出 dist/index.js
```

## 3. 接进 OpenClaw 的 MCP 配置

把下面这段加进 OpenClaw 的 MCP servers 配置（路径改成你机器上的绝对路径）：

```json
{
  "mcpServers": {
    "world-of-claudecraft": {
      "command": "node",
      "args": ["/ABS/PATH/TO/world-of-claudecraft-mcp/dist/index.js"],
      "env": {
        "WOC_ENV_SERVER": "/ABS/PATH/TO/world-of-claudecraft/dist-env/env_server.cjs"
      }
    }
  }
}
```

也可以设环境变量 `WOC_ENV_SERVER` 指向 `env_server.cjs`，不写进配置。

---

## 4. 让 OpenClaw「自己玩」

LLM 就是玩家。给它这套**系统提示词 / 操作规程**，它就会自主循环：

> 你是 World of ClaudeCraft（类魔兽世界经典版的 MMO）的玩家。用 `wow_*` 工具自主游玩，
> 不要等人类一步步指令，自己读状态、自己决策、自己执行。
>
> **循环：**
> 1. 调用 `wow_reset` 开新的一局（可选 seed 以复现）。
> 2. 反复执行：调用 `wow_state` 读当前局面 → 决定接下来 1~10 个动作 →
>    用 `wow_play([...])` 一次性执行这批动作。
> 3. 当某次返回 `terminated=true` 或 `truncated=true` 时，这一局结束，
>    调用 `wow_reset` 开下一局，或调用 `wow_close` 收工。
>
> **生存本能：** HP 低（看 HP%）就 `eat_drink`；附近有敌对怪物就 `target_nearest`
> 然后 `attack`；技能就绪（`ability_N` 在 ready 列表里）且合适就放；
> 有可交互物（corpse/object/quest）就 `interact` 去拾取/接任务/交任务。
>
> **目标优先级：** 活着 > 完成/交付任务（升级拿 XP）> 击杀练级。
> `forward`/`turn_left`/`turn_right`/`strafe_*` 用来走位接近或拉开距离。

### 动作速查（来自 `wow_list_actions`）

| 动作 | 含义 |
|---|---|
| `noop` | 什么都不做 |
| `forward` / `back` | 前进 / 后退 |
| `turn_left` / `turn_right` | 转向（同时前进） |
| `strafe_left` / `strafe_right` | 横移 |
| `jump` | 跳（带前进） |
| `target_nearest` | 选最近的敌人 |
| `attack` | 开始自动攻击当前目标 |
| `ability_1` … `ability_N` | 按学会顺序施放技能（N 随职业不同） |
| `interact` | 拾取尸体 / 开物体 / 与任务 NPC 对话 |
| `stop` | 停止移动和攻击 |
| `eat_drink` | 吃喝回血/回蓝 |

---

## 5. 成本与收敛提醒

- 默认每个 env step = 5 个 sim tick（约每秒 4 次决策）。**每次 `wow_step` 都是一次 LLM 调用**。
  一局最长 8000 步 → 最多 8000 次调用，单局成本不低。
  **务必用 `wow_play([...])` 批量执行**（一次 LLM 调用推进多步），而不是一步步 `wow_step`。
- 想更省：可在 `wow_reset` 的 `config` 里调大 `frameSkip`（每步推进更多 tick，决策更稀疏），
  或调小 `maxSteps`。
- 环境是**确定性**的：同 `seed` + 同动作序列 = 完全可复现，方便调试 agent 行为。

## 6. 文件结构

```
world-of-claudecraft-mcp/
├── src/
│   ├── index.ts        # MCP server：暴露 wow_* 工具
│   ├── env_client.ts   # spawn env_server.cjs 的 NDJSON stdio 客户端
│   └── obs_decode.ts   # 把数值观测向量解码成 LLM 可读文字（依据 src/sim/obs.ts）
├── package.json
├── tsconfig.json
├── openclaw-mcp-config.json   # 直接抄进 OpenClaw MCP 配置
└── README.md
```

## 7. 本地冒烟测试（无需构建完整游戏）

想先验证适配器本身（客户端往返 + 观测解码）不依赖完整游戏，可用仓库里的 mock：

```bash
npm run build
WOC_ENV_SERVER="$(pwd)/mock_env.cjs" node test_run.mjs
```

它会打印解码后的可读状态，确认动作/目标/怪物/任务都被正确还原。

## 已知限制 / 可增强

- 技能在观测里是 `ability_1..N`（按学会顺序的槽位），没有映射成真实法术名
  （如 "Heroic Strike"）。想让 LLM 知道每个槽位是什么技能，可额外读
  `src/sim/content` 的职业技能表做一层名字映射。
- 仅接了 **headless 离线环境**（和真实 Sim 同源，但是单人对练，不是线上服）。
  想上 `worldofclaudecraft.com` 和真人同场，需要另写 WS/REST 客户端（并注意反 bot / ToS）。