# 大模型直接调工具（MCP）

> tools/war3_mcp.py 是一个 MCP 服务器。Claude Code、Claude Desktop 或任何支持 MCP 的客户端挂上它，大模型就能直接看局面、下命令、在屏幕上跟玩家说话、弹卡片问玩家、截图看画面，不用先写代码。

来源: https://war3ai.com/docs/mcp/

`tools/war3_mcp.py` 是一个 **MCP 服务器**（stdio）。Claude Code、Claude Desktop、本地模型的 Agent 框架 —— 任何支持 MCP 的客户端挂上它，大模型就能**直接**看局面、下命令、在游戏屏幕上跟玩家说话、问玩家、截图看画面，不用先写代码。

写 Bot、当参谋、让单位说话之外，这是又一种接法：**大模型自己当工具的使用者**。

## 挂上

```bash
claude mcp add war3 -- python <仓库>\tools\war3_mcp.py --inst 9      # Claude Code；<仓库> 换成你的 openwar3 目录
```

别的客户端照这个格式写配置：

```json
{"mcpServers": {"war3": {"command": "python", "args": ["<仓库>\\tools\\war3_mcp.py", "--inst", "9"]}}}
```

第一次调工具时才去连游戏，所以游戏可以后开；游戏关了重开，下一次调用自动重连。加上 `--role` 限定大模型能做什么：

| 角色 | 能用 |
|---|---|
| `dev`（默认） | 全部工具，包括 `war3_jass` |
| `player --player N` | 只能指挥 N 号玩家的单位、只看得见它的视野（公平模式）；没有 JASS |
| `observer` | 只读，不能往屏幕上画、不能让单位说话；运行时直接拒绝它下的命令 |

`player` 角色和[网关](https://war3ai.com/docs/gateway/)的限制一样：拿不到结束游戏、改速度、暂停，拿不到看得见别人底牌的接口，带玩家号的查询只能查自己。

几个上限：一个工具结果最多 20 万个字符，超出的截断并提示怎么缩小范围；`war3_ask_player` 最多等 120 秒；截图的 `scale` 在 0.1 到 1 之间。

## 工具

| 工具 | 做什么 |
|---|---|
| `war3_overview` | 一页局面：时间、资源、人口、我方各兵种数、英雄（血、蓝、等级、冷却）、看得见的敌方兵种、生产。**先调它** |
| `war3_units` | 单位列表（`owner` 取 me / enemy / creep / all，`types` 过滤）；`addr` 用来下命令 |
| `war3_events` | 上次调用之后发生的事：死亡、升级、施法、生产完成、聊天、玩家点了按钮……（默认去掉刷屏的几种） |
| `war3_call` | 调任意公开接口（`move`、`attack_move`、`train`、`build`、`cast`、`learn`、`ui.button`、`canvas.text`……），单位写 `{"unit": addr}` |
| `war3_api` | 查接口：按关键字搜名字和说明 |
| `war3_toast` / `war3_say` | 屏幕上方一行字 / 单位头顶一句话 |
| `war3_ask_player` | 屏幕中间给玩家几张选项卡，等玩家点，返回选了哪个（可以暂停游戏） |
| `war3_screenshot` | 游戏画面截图（PNG；窗口被挡着也能截，不抢焦点） |
| `war3_jass` | 跑一段 JASS（只给 dev；改世界只在单人局） |

能玩出来的：

- **陪玩 / 教练**：`war3_overview` 看局面，`war3_toast` 在屏幕上给建议；
- **边打边问玩家**：`war3_ask_player` 弹三张卡片，玩家点哪张就按哪张来；
- **解说**：`war3_events` 读发生了什么，`war3_say` 让单位自己说出来；
- **直接指挥一支部队**：`player` 角色 + `war3_call`，只能动自己的单位；
- **看图调界面**：`war3_screenshot` 截一张，看自己画的按钮摆得对不对。

## 一次对话大概是这样

```text
你：看看现在局面，然后在屏幕上问我：下一步是开矿、爆兵还是升本？

→ war3_overview      {}
← 一页局面：游戏时间、金 500、人口 10/12、我方 htow 1 · hpea 5 · Hpal 1、没看见敌人、没有在生产的
→ war3_ask_player    {"question": "下一步？", "options": ["爆兵", "开矿", "升本"], "pause": true}
← {"picked": 1, "option": "开矿"}

模型：你选了开矿。我先用 war3_units 找一个空闲的农民，再看最近的金矿在哪……
```

## 实测

2026-09-25：

- 自己的 MCP 客户端连真实对局，7/7：握手 → 列工具（10 个）→ `war3_overview`（`htow` 1、`hpea` 5）→ `war3_units` → `war3_toast` → `war3_screenshot`（PNG 约 20 万字节）→ `war3_ask_player`（三张卡，模拟点第二张 → `{"picked": 1, "option": "开矿"}`）。
- Claude Code 2.1 实挂：它自己起服务器、握手，状态 `connected`，10 个工具都以 `mcp__war3__*` 出现在它的工具表里。

## 实现

- 换行分隔的 JSON-RPC 2.0（`initialize` / `tools/list` / `tools/call` / `ping`），协议版本 2025-06-18，兼容 2025-03-26 和 2024-11-05。
- 工具出错按 MCP 的规矩放在结果里（`isError: true`），不断开。
- 和 [网关](https://war3ai.com/docs/gateway/) 共用同一套角色白名单、单位参数格式和「一页局面」。
- 日志走 stderr，stdout 只有协议。