开始使用
本页目录
文档 让 AI 写 Bot

大模型直接调工具（MCP）

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

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

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

挂上

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 限定大模型能做什么：

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

player 角色和网关的限制一样：拿不到结束游戏、改速度、暂停，拿不到看得见别人底牌的接口，带玩家号的查询只能查自己。

几个上限：一个工具结果最多 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 截一张，看自己画的按钮摆得对不对。

一次对话大概是这样

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

→ 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 只有协议。