Hated WoW MCP

Hated WoW MCP

一个用于编写《魔兽世界》插件的 MCP 服务。 免费且开源。

它为你的 AI 助手提供三样原本只能靠猜的内容：目标客户端的游戏内 Lua API、暴雪随游戏一同发布的 UI 源码，让它能查看游戏本身如何实现某些功能，以及游戏的美术和文件数据，确保纹理引用真实存在，而非凭空捏造。

共有 20 个工具。下方提供 Claude Code、Claude Desktop、Cursor、Cline、Antigravity、Codex 和 VS Code 的设置说明，任何支持 MCP 的其他客户端也都能使用。或者，你也可以在完全不使用 AI 的情况下，通过本地网页 UI 浏览。

☕ 支持此项目

Hated WoW MCP 免费，而且永远免费。如果它为你节省了时间，你可以请我喝杯咖啡——这确实有助于我在各个补丁周期中持续维护它。

buymeacoffee.com/rdygaming

这里的一切都与在客户端内部运行的代码有关。此服务不包含 Battle.net Web API——没有军械库查询，也没有拍卖行功能。

---

快速开始

需要 Node 20+。无需克隆，也无需构建。

Claude Code

claude mcp add wow -- npx -y hated-wow-mcp

添加 -s user，即可在所有项目中使用，而不只是当前项目。使用 claude mcp list 验证。

Claude Desktop

编辑配置文件：

操作系统	路径
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json

通过 Windows Store 安装？ 如果该路径不存在，请改为在 %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\ 下查找。

添加 mcpServers 代码块。如果文件中已有其他键，请保留它们—— 应将此内容合并到文件中，而不是替换整个文件：

{
  "mcpServers": {
    "wow": {
      "command": "npx",
      "args": ["-y", "hated-wow-mcp"],
      "env": {
        "WOW_DEFAULT_FLAVOR": "mainline"
      }
    }
  }
}

然后从系统托盘中完全退出 Claude Desktop，再重新打开——仅关闭窗口还不够，而且配置只会在启动时读取。

其他客户端

这是标准的 stdio MCP 服务，因此任何 MCP 客户端都可以运行它。不同之处在于配置格式。以下格式来自各客户端自己的文档。

客户端	位置	格式
Cursor	项目中的 .cursor/mcp.json，或 ~/.cursor/mcp.json	与上文相同的 mcpServers JSON
Cline	MCP Servers 面板，然后选择 Configure（CLI：~/.cline/mcp.json）	相同的 mcpServers JSON
Antigravity	~/.gemini/config/mcp_config.json，或 Settings、Customizations、Open MCP Config	相同的 mcpServers JSON。其文档要求使用绝对命令路径
Windsurf	其 MCP 配置文件	相同的 mcpServers JSON
VS Code	.vscode/mcp.json，或 MCP: Open User Configuration 命令	servers，而不是 mcpServers
Codex	~/.codex/config.toml	TOML，见下文

VS Code 使用的顶层键与其他客户端不同：

{
  "servers": {
    "wow": { "command": "npx", "args": ["-y", "hated-wow-mcp"] }
  }
}

Codex 读取的是 TOML，而不是 JSON。可以运行 codex mcp add wow -- npx -y hated-wow-mcp， 也可以将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.wow]
command = "npx"
args = ["-y", "hated-wow-mcp"]
env = { WOW_DEFAULT_FLAVOR = "mainline" }
startup_timeout_sec = 30

将 startup_timeout_sec 调高，超过 Codex 默认的 10。首次运行 npx 时必须下载软件包，在快速连接下耗时约 9 秒，连接较慢时则会超时。Claude Code 有相同的设置项 MCP_TIMEOUT。

在 Windows 上，某些客户端启动服务时不使用 shell，因此普通的 npx 会无法启动（ENOENT）。请用 cmd 包装：

{
  "mcpServers": {
    "wow": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "hated-wow-mcp"]
    }
  }
}

这样启动实时服务约需 4 秒。从克隆版本启动时，使用指向 dist/index.js 的 "command": "node"，只需半秒且无需联网。

工具审批。 20 个工具中有 19 个只读取本地数据，并对此作出声明（readOnlyHint），因此每次调用都会提示确认的客户端可以安全地跳过它们。例外是 wow_addon_scaffold。只有传入 write 时它才会写入文件，并且除非同时传入 overwrite，否则不会覆盖已有插件。如果使用自动审批，请不要将它加入列表。

请参阅此代码库中的 mcp-config.example.json，以此作为起始配置文件。

然后同步游戏数据

Lua API 索引已包含在软件包中，因此添加后即可立即使用 API 搜索、类型和事件查询、lint、TOC/XML 验证和脚手架工具——无需同步，也无需等待。

UI 源代码语料库以及美术资源/FileDataID 查询数据过于庞大，无法随包发布，因此这 9 个工具（包括 CVar 查询）需要执行一次性同步。PATH 中必须有 git：

npx -y hated-wow-mcp sync all

**同步前：**先在浏览器中打开一次 https://wago.tools/，并等待页面完全加载。wago.tools 位于机器人防护机制之后，先通过同一网络连接访问该网站，才能顺利下载图集。跳过此步骤可能导致图集下载失败并返回 HTTP 403。

这会获取 Blizzard UI 源代码的浅克隆（约 44 MB）和一个 listfile（约 149 MB）——首次运行需要几分钟。之后重新运行开销很小：未更改的 listfile 会重新验证，而不是重新下载，因此无操作同步约需两秒。

Classic 和 WoW Forever

不带参数执行 sync all（或 sync ui-source）会为默认客户端建立 UI 源码索引；除非你设置了 WOW_DEFAULT_FLAVOR，否则默认客户端为零售版。此外，还会为找到的所有已安装 WoW 客户端建立索引。如果已安装 _classic_beta_，则无需任何标志即可为 WoW Forever 建立索引。如果只安装了零售版，则不会下载其他内容。日志会说明选择了哪些客户端。

如需自行选择客户端，请指定它们。这会覆盖自动检测结果，并且每次同步都会添加到同一个索引，而不是替换它：

npx -y hated-wow-mcp sync ui-source -- forever   # WoW Forever (Camelot)
npx -y hated-wow-mcp sync ui-source -- classic   # Mists / Cata / Wrath / TBC
npx -y hated-wow-mcp sync ui-source -- vanilla   # Classic Era
npx -y hated-wow-mcp sync ui-source -- mainline  # retail only, skip the rest

每个客户端都需要单独检出约 46 MB，因此安装了全部四个客户端的机器，下载量约为只安装零售版时的四倍。

美术数据遵循相同规则。sync game-data 会为默认客户端以及所有已安装客户端构建纹理图集，你也可以用相同方式指定客户端（sync game-data -- forever）。图集很小，只有几 MB，因此所需空间远少于 UI 源码。所有客户端共用同一个文件索引，且只构建一次。

如果你询问的工具涉及尚未同步的客户端，它会说明这一点并提供相应命令。它不会回退到零售版源码，因为那样会返回该客户端上可能不存在的代码。

软件包中附带了全部四个客户端的 API 索引，因此无需执行任何同步，flavor: "forever" 也能用于 API 搜索、代码检查和 .toc 验证。有关上游尚未为其发布的内容，请参阅已知限制。

验证是否生效

询问你的助手：“使用 WoW MCP，C_Item.GetItemInfo 会返回什么？” 你应该会得到包含 18 个值的完整签名。或者直接运行服务：

npx hated-wow-mcp --list

这应该会打印全部 20 个工具。

数据存放位置

同步的数据绝不会放进软件包——这正是 npx 能正常工作的原因。数据会存放在操作系统的缓存目录中：

平台	位置
Windows	%LOCALAPPDATA%\hated-wow-mcp\Cache
macOS	~/Library/Caches/hated-wow-mcp
Linux	$XDG_CACHE_HOME/hated-wow-mcp，否则为 ~/.cache/hated-wow-mcp

设置 WOW_MCP_DATA_DIR 可覆盖此位置——例如，可将约 70 MB 的数据放到另一个驱动器，或让多个安装共用一次同步的数据。wow_data_status 始终会报告解析出的路径及原因。

---

从克隆版本运行

只有在需要修改服务，或使用本地 Web UI（不包含在已发布的软件包中）时才需要执行以下步骤。需要 Node 20+ 和 git。

git clone https://github.com/RdyGaming/hated-wow-mcp.git
cd hated-wow-mcp
npm install
npm run build
npm run sync-all
npm test

npm test 应报告 111 passed，0 failed。在 Windows 上，setup.cmd 会完成全部五个步骤，并打印你后续需要使用的绝对路径。

克隆版本会将同步的数据保存在源码旁的 data/ 目录中，而不是操作系统缓存目录中，因此在服务上进行开发不会影响你已有的 npx 安装。

将客户端指向构建后的入口文件，而不是使用 npx：

{
  "mcpServers": {
    "wow": {
      "command": "node",
      "args": ["C:\\absolute\\path\\to\\hated-wow-mcp\\dist\\index.js"]
    }
  }
}

在 Windows 上，JSON 中的反斜杠必须重复两次。在 macOS/Linux 上，使用普通路径即可，例如 /Users/you/hated-wow-mcp/dist/index.js。

提交 PR 前，请先阅读 CONTRIBUTING.md。

无需 AI 客户端即可浏览

每个工具都会在本地 Web UI 中运行——无需助手、API 密钥或令牌。 适合快速查找信息，或在将工具接入提示词之前检查其返回内容。

此功能需要克隆仓库；它不属于 npm 包。

npm run web

然后打开 http://localhost:3001。

从侧边栏选择一个工具，它就会为你生成表单：字段、字段类型和帮助文本都来自工具自身的架构，因此 UI 始终与工具实际接受的内容一致。结果会显示在 Monaco 编辑器中，并提供复制按钮。

此功能直接与工具通信——它不会使用 MCP 协议，因此不会干扰助手正在使用的服务。两者可以同时运行。

有两点值得注意：

• 请先运行 npm run sync-all。 UI 的完整程度取决于同步的数据；如果没有同步，UI 源码和游戏数据工具将不会返回任何内容。
• 美术工具显示的是路径，而不是图片。 wow_icon_search 等工具会返回 FileDataID 和纹理路径——不支持 BLP 解码（请参阅已知限制）。将 FileDataID 粘贴到 wago.tools 即可查看实际图片。

如果端口 3001 已被占用，请设置 PORT：

PORT=4000 npm run web

UI 的依赖项（express、cors）是开发依赖项——普通的 npm install 会安装它们，而 MCP 服务本身不会导入它们。

---

配置

所有设置均为可选项——请参阅 .env.example。

变量	用途
WOW_DEFAULT_FLAVOR	工具调用未指定客户端时要使用的客户端：mainline、mists、cata、wrath、tbc、vanilla、forever。默认为 mainline。
WOW_INSTALL_PATH	你的 WoW 文件夹。未设置时会自动检测。
WOW_ADDON_PATH	文件工具读取和写入的 AddOns 文件夹。将这些工具限制在该目录中。

---

数据内容

数据集	内容	来源
Lua API 索引	6,335 个函数、1,783 个事件、1,676 个枚举/结构体、6,704 个全局变量（正式服；Classic 和 Classic Era 分别建立索引）	Blizzard 自行生成的 /api 文档，镜像位于 Gethe/wow-ui-source
UI 源码	348 个 Blizzard_* 包中的 4,036 个文件——4,044 个可继承 XML 模板、3,488 个 mixin、26,859 个 mixin 方法	同一镜像
CVar	1,635 个控制台变量，包含默认值、类别、作用范围和 Blizzard 自行编写的说明；其中 451 个还包含来自 UI 源码的用法证据	Ketho/BlizzardInterfaceResources + UI 源码
UI 架构	Blizzard 的 UI.xsd，解析后用于验证元素和属性	同一镜像
文件索引	172,175 个界面文件，包括 36,624 个图标，并映射至 FileDataID	wowdev/wow-listfile
Atlas 索引	命名的 SetAtlas 元素，包含大小和坐标；每个客户端在精确构建版本下各有一个索引（正式服 17,467 个，WoW Forever 20,454 个）	wago.tools 的 DB2 导出

所有数据均由 src/sync/ 中的脚本从公共镜像同步，因此会随补丁更新，无需任何人手动维护列表。

---

工具

API 参考

工具	用途
wow_api_search	查找函数及其完整参数和返回值签名
wow_api_event_search	按顺序查找事件及其载荷参数
wow_api_type_search	查找 Enum.*、Constants.* 或结构体表
wow_api_diff	比较零售版 / Classic / Classic Era 的可用性
wow_api_stats	显示已加载的索引及其同步时间

Blizzard 的 UI 源码

工具	用途
wow_ui_template_search	查找可继承的 XML 模板及其继承链
wow_ui_mixin_search	按名称或方法查找 mixin
wow_cvar_search	查找 CVar：默认值、类别、作用范围、是否受保护，以及 Blizzard 如何使用它
wow_ui_grep	使用正则表达式搜索全部 4,036 个随游戏提供的 Lua/XML 文件
wow_ui_read_file	在上下文中读取随游戏提供的源文件
wow_ui_list_packages	列出 Blizzard_* 软件包

创作

工具	用途
wow_lua_lint	检查已移除 / 已迁移的 API、未知事件、污染和性能陷阱
wow_xml_validate	根据 Blizzard 的 UI.xsd 验证界面 XML
wow_toc_validate	验证 .toc：界面版本、版本后缀、文件列表
wow_addon_scaffold	生成可运行的插件骨架
wow_install_info	报告本地安装和已安装的插件

游戏数据和美术资源

工具	用途
wow_file_search	在路径和 FileDataID 之间双向查找
wow_icon_search	查找图标并获取两种可用的引用形式
wow_atlas_search	查找 SetAtlas 元素及其尺寸和坐标
wow_data_status	显示已同步的游戏数据集

---

为什么值得运行代码检查器

它基于按版本划分的索引构建，而不是依赖手写的弃用列表， 因此它知道哪些情况适用于你要面向的客户端：

$ wow_lua_lint --flavor mainline
local n = GetContainerNumSlots(0)

  1:9  warning  api/moved-to-namespace
      "GetContainerNumSlots" has moved into a namespace in Retail (Midnight)…
      -> C_Container.GetContainerNumSlots

同一段代码在 Classic 上没有问题，因为该全局变量在那里仍然存在。这种 区分来自 Blizzard 的数据，而非人工断言。

它还会捕获导致“因插件而导致界面操作失败”的污染错误——调用受保护函数、重新赋值 Blizzard 全局变量、 在战斗锁定期间接触安全框架。

实测误报率，通过对 Blizzard 自带的代码运行两个验证器进行检查：

• XML 验证器：1,091 个文件中有 0 个报告错误。
• Lua 代码检查器：2,551 个文件中有 48 个（1.9%），而且这些结果几乎都准确——它们是 Blizzard 自带的 Blizzard_Deprecated* 兼容垫片，存在的目的正是重新定义已移除的 API。

---

保持数据最新

应用补丁后重新运行。wow_api_stats 和 wow_data_status 会显示现有数据及其同步时间。

命令	获取内容	备注
npm run sync-api	所有三个客户端的 Lua API 索引	约 1,700 次小型 HTTPS 请求
npm run sync-ui-source	Blizzard UI 源代码（浅克隆，约 44 MB）	重新运行会快进更新
npm run sync-game-data	Listfile 和图集表	添加 --full 以获取模型／地图／声音
npm run sync-all	全部三项

这些命令适用于克隆的仓库。已安装的副本没有 package 脚本，因此要改用 sync 子命令：

npx -y hated-wow-mcp sync all
npx -y hated-wow-mcp sync game-data -- --full

sync-api 只能在检出仓库时使用——它会重新生成随软件包一起发布的数据，因此已安装的副本需要通过升级来获取更新的 API 索引，而不是进行同步。

数据来自公开的上游镜像，因此重新同步即可获取补丁变更，无需等待此处发布新版本。请注意，这些镜像通常会比线上补丁晚几小时到几天。

没有变更时，重新同步的成本很低。 149 MB 的 listfile 会通过其 ETag 重新验证，因此未变更时只需一次往返，而无需重新下载；索引也会保持不变，不会重新构建——空操作的 sync-game-data 约两秒即可完成。传入 --force 可忽略缓存并强制重新构建。

服务会在数据过期时告知你。 同步后的索引超过 30 天时，基于该索引的回答会附带一行警告，而 wow_data_status 会报告每组数据的时效。值得留意的是过期数据导致的失效：自信地回答一个补丁已移除的函数或纹理，比不回答更糟。

访问 wago.tools

运行 sync-game-data 或 sync-all 之前，请在浏览器中打开 https://wago.tools/ 并等待页面加载。 该网站设有机器人防护机制；从同一网络连接访问一次即可解除限制，方便随后下载图集。先执行此操作可避免大多数图集获取失败。

如果图集步骤仍报告 HTTP 403，则表示 wago.tools 正在拒绝连接——它会屏蔽许多数据中心、云服务和 VPN 的 IP 段。请在普通桌面网络连接下运行，并关闭所有 VPN。

这不会阻碍其余同步。同一脚本中的文件索引来自 GitHub，不受影响；只有 wow_atlas_search 依赖图集步骤，其余 19 个工具均不受影响。

---

目录结构

src/
  config.ts            flavors, interface versions, install detection
  wowapi/              API index loading, search, rendering
  uisource/            Blizzard UI source index, template/mixin/grep search
  gamedata/            listfile and atlas lookup
  lua/                 tokenizer, analyzer, rule tables
  xml/                 UI.xsd parser, XML validator
  toc/                 .toc parser and validator
  scaffold/            addon generator
  tools/               MCP tool definitions
  sync/                the three sync scripts, plus their shared entry point
  paths.ts             bundled vs. synced data locations
server.js              local web UI backend (npm run web)
index.html             local web UI frontend
test/smoke.mjs         111 end-to-end checks against real data
data/                  bundled API indexes, plus synced ones in a clone

---

已知限制

• 未对控件方法的继承关系建模。 可以找到 Frame:SetPoint，但服务端不知道 Button 继承了它。直接搜索方法名即可。
• 经典旧世进程版本共用一个索引。 Blizzard 会为实际运行的客户端发布生成的文档；Cata/Wrath/TBC 映射到经典旧世索引，因此相关回答只是近似结果。
• WoW Forever 缺少三个列表。 它的客户端基于正式服代码库构建（Blizzard 将游戏类型称为 camelot），因此有自己的索引；与其他客户端一样，API 文档和 UI 源代码也来自 Blizzard 自己的文件。但提供全局函数列表、事件列表和 CVar 注册表的社区资源仓库目前还没有对应分支。因此，在 forever 上会关闭未知函数 lint 检查（并附注说明，而不是将可用代码标记出来）；wow_api_diff 中的裸名称会显示“未记录”，而不是“不可用”；wow_cvar_search 只会显示 Blizzard 的 UI 使用到的 CVar，不包含默认值、描述或保护标志。上游为其添加分支后，只需在 src/sync/api.ts 的分支表中改一行即可获取这些数据。
• 图集按客户端构建，因此每个客户端都必须单独同步。 正式服和 WoW Forever 共享 16,788 个图集名称，但有 3,666 个仅存在于 Forever，另有 720 个仅存在于正式服。因此，wow_atlas_search 会根据你指定的客户端提供回答，并说明使用了哪个构建版本。尚未构建图集的客户端会说明情况并给出命令；它不会借用正式服的图集。
• 不支持解码 BLP。 美术工具会返回路径、FileDataID 和图集坐标，而不是渲染后的图像。要提取实际纹理，需要使用 wow.export 之类的 CASC 工具，并通过你自己的游戏安装目录进行操作。
• lint 的作用域模型只是近似实现。 它是带有作用域栈的词法分析器，并非完整的 Lua 解析器。遇到有歧义的代码时，它倾向于保持沉默。

---

故障排查

服务未显示在 Claude Desktop 中。 请从系统托盘彻底退出，而不只是关闭窗口。检查 JSON 是否有效，以及反斜杠是否已加倍。

“Cannot find module ... dist/index.js”。 这只适用于从克隆的仓库运行：你跳过了 npm run build，或者配置中的路径有误。路径必须是绝对路径。使用 npx 时，请使用 "command": "npx", "args": ["-y", "hated-wow-mcp"]，这样就没有路径会出错。

UI 源代码、美术或图标查询没有返回结果。 这些内容需要先进行一次同步。运行 npx -y hated-wow-mcp sync all（如果是从克隆的仓库运行，则执行 npm run sync-all），然后检查 wow_data_status——它会报告查询位置以及数据的构建时间。

同步失败。 UI 源代码步骤需要你的 PATH 中有 git。如果图集步骤遇到 HTTP 403，请参阅快速开始中的 wago.tools 说明。

更新后数据似乎过时。 npx 会缓存软件包。使用 npx -y hated-wow-mcp@latest 强制获取最新版本，或使用 npm cache clean --force 清除缓存。wow_api_stats 会显示当前实际加载的索引。

“Filename too long” / “Clone succeeded, but checkout failed”（Windows）。 有些 Blizzard 文件名本身就有 108 个字符，因此克隆路径过深可能会超过 Windows 的 260 个字符限制。同步脚本会向 git 传递 core.longpaths=true 来处理此问题。如果仍遇到问题，请克隆到更短的路径——尽量将路径控制在约 150 个字符以内（C:\dev\hated-wow-mcp 的长度绰绰有余）——或者在 Windows 中启用系统级长路径支持。

---

贡献

欢迎在 github.com/RdyGaming/hated-wow-mcp 提交问题和拉取请求。

CONTRIBUTING.md 介绍了开发环境的设置、两组数据的差异，以及添加工具前需要了解的事项。参与本项目须遵守 行为准则。

最有价值的报告是查找结果错误而非没有结果——我们为此提供了问题模板，要求说明如何验证实际行为，以便对照游戏检查修复效果。

发现安全问题？请私下报告——详见 SECURITY.md。

许可证

MIT——详见 LICENSE。

本项目与 Blizzard Entertainment 无关联，也未获其认可。World of Warcraft 是 Blizzard Entertainment, Inc. 的商标。所有游戏数据均在运行时从公开的社区镜像获取，本项目不再分发这些数据。