開始使用
本頁目錄
文件 讓 AI 寫 Bot

LLM 直接呼叫工具（MCP）

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

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

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

掛上

claude mcp add war3 -- python <儲存庫>\tools\war3_mcp.py --inst 9      # Claude Code；<儲存庫> 換成你的 openwar3 目錄

其他用戶端照這個格式寫設定：

{"mcpServers": {"war3": {"command": "python", "args": ["<儲存庫>\\tools\\war3_mcp.py", "--inst", "9"]}}}

第一次呼叫工具時才會連線遊戲，所以遊戲可以晚點再開；遊戲關掉重開，下一次呼叫會自動重新連線。加上 --role 限定 LLM 能做什麼：

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

player 角色和閘道的限制一樣：拿不到結束遊戲、調整速度、暫停，拿不到看得見別人底牌的 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 截一張，看自己畫的按鈕擺得對不對。

一次對話大概是這樣

你：看看現在的局面，然後在螢幕上問我：下一步是開分礦、暴兵還是升級主城？

→ 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），不會斷線。
  • 和 閘道 共用同一套角色白名單、單位參數格式和「一頁局面」。
  • 日誌走 stderr，stdout 只有協定內容。