# LLM 直接呼叫工具（MCP）

> tools/war3_mcp.py 是一個 MCP 伺服器。Claude Code、Claude Desktop 或任何支援 MCP 的用戶端掛上它，LLM 就能直接看局面、下命令、在螢幕上跟玩家說話、跳出卡片詢問玩家、截圖看畫面，不必先寫程式碼。

來源: https://war3ai.com/zh-tw/docs/mcp/

`tools/war3_mcp.py` 是一個 **MCP 伺服器**（stdio）。Claude Code、Claude Desktop、本機模型的 Agent 框架 —— 任何支援 MCP 的用戶端掛上它，LLM 就能**直接**看局面、下命令、在遊戲螢幕上跟玩家說話、詢問玩家、截圖看畫面，不必先寫程式碼。

除了寫 Bot、當參謀、讓單位說話，這是另一種接入方式：**LLM 自己當工具的使用者**。

## 掛上

```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` 限定 LLM 能做什麼：

| 角色 | 能用 |
|---|---|
| `dev`（預設） | 全部工具，包括 `war3_jass` |
| `player --player N` | 只能指揮 N 號玩家的單位、只看得見它的視野（公平模式）；沒有 JASS |
| `observer` | 唯讀，不能在螢幕上繪製、不能讓單位說話；執行環境直接拒絕它下的命令 |

`player` 角色和[閘道](https://war3ai.com/zh-tw/docs/gateway/)的限制一樣：拿不到結束遊戲、調整速度、暫停，拿不到看得見別人底牌的 API，帶玩家編號的查詢只能查自己。

幾個上限：一個工具結果最多 20 萬個字元，超出的部分會截斷並提示怎麼縮小範圍；`war3_ask_player` 最多等 120 秒；截圖的 `scale` 在 0.1 到 1 之間。

## 工具

| 工具 | 做什麼 |
|---|---|
| `war3_overview` | 一頁局面：時間、資源、人口、我方各兵種數量、英雄（血量、魔力、等級、冷卻）、看得見的敵方兵種、生產。**先呼叫它** |
| `war3_units` | 單位清單（`owner` 取 me / enemy / creep / all，`types` 過濾）；`addr` 用來下命令 |
| `war3_events` | 上次呼叫之後發生的事：死亡、升級、施法、生產完成、聊天、玩家點了按鈕……（預設去掉會洗版的幾種） |
| `war3_call` | 呼叫任意公開 API（`move`、`attack_move`、`train`、`build`、`cast`、`learn`、`ui.button`、`canvas.text`……），單位寫成 `{"unit": addr}` |
| `war3_api` | 查詢 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/zh-tw/docs/gateway/) 共用同一套角色白名單、單位參數格式和「一頁局面」。
- 日誌走 stderr，stdout 只有協定內容。