内容
# 魔兽世界 Wiki MCP
MCP 服务器，提供 LLMs 直接访问 [魔兽世界 Wiki](https://warcraft.wiki.gg) API 文档的功能——社区维护的 WoW API 行为笔记、限制和补丁历史的来源。
## 为什么需要这个服务器？
- **LLM 训练数据经常出错，适用于 WoW APIs。** 函数在补丁之间可能会被重命名、弃用或更改行为。训练数据滞后数月或数年。
- **仅 API 签名不足以应对。** 知道 `C_Spell.GetSpellCooldown()` 返回 `{ startTime, duration, ... }` 并不能告诉你，在 12.0.x 中，`startTime` 和 `duration` 是机密值，不能在 Lua 算术中使用。这些关键的行为背景在 Wiki 中。
- **没有工具就无法验证 API。** 没有实时查询，LLM 将自信地使用已弃用或不存在的 API 生成代码。
该服务器按需查询 Wiki 并返回干净的文本和结构化字段——不是原始 HTML：
- 描述、参数文档、返回值和代码示例
- 行为细节和使用注意事项
- 弃用通知
- 事件有效载荷部分
- Wiki 提供的限制和兼容性说明
- 补丁历史
- 结构化参数/返回值/有效载荷项，供代理使用
- 显式弃用和替换元数据（当 Wiki 公开时）
- 当弃用横幅和补丁历史记录不一致时的冲突信号
- 更安全的突发代理查询下的重试/限流行为
- 更安全的旧页面解析，优先选择干净的文本而不是误导性的伪结构
- 在广泛查询模糊时，搜索排名偏向当前命名空间 API
- 面向代理的编码说明、警告和相关事件信号，用于更安全的编码决策
- 一个解析器工具，将编码意图转换为排名 API/事件文档候选
它补充了结构化 API 工具（例如 [wow-api-mcp](https://github.com/Wutname1/wow-api-mcp)，它提供类型签名、枚举和事件定义），以及 Wiki 文档中特有的行为层。
服务器的范围故意限定为 API 和密切相关的技术文档。 它不是为一般魔兽世界 Wiki 文章浏览而设计的。
## 工具
| 工具 | 目的 | 示例输入 |
|------|---------|---------------|
| `wiki_lookup` | 获取特定的 API 函数、事件或确切的技术文档页面 | `C_Spell.GetSpellCooldown`，`SPELL_UPDATE_COOLDOWN` |
| `wiki_resolve` | 将编码意图转换为排名 API/事件候选，并提供下一次查询的指导 | `"track spell cooldown"`，`"listen for aura changes"` |
| `wiki_search` | 仅搜索 API/事件/技术文档页面 | `"spell cooldown"`，`"unit aura tracking"` |
| `wiki_namespace` | 列出命名空间前缀下的所有页面 | `C_Spell`，`C_Item`，`GetSpell` |
### wiki_lookup
获取特定的 API 函数、事件或确切的技术页面，并返回可读文本和结构化内容。
- **自动检测：** 函数名称会添加 `API_` 前缀作为 Wiki 页面标题（`C_Spell.GetSpellCooldown` -> `API_C_Spell.GetSpellCooldown`）。大写事件名称按原样使用（`SPELL_UPDATE_COOLDOWN`）。
- **章节过滤：** 可选的 `section` 参数将响应缩小到：`description`、`arguments`、`returns`、`payload`、`details`、`example`、`patch_changes`、`see_also`、`fields`、`members`、`values`、`related_events` 或 `all`（默认）。
- **弃用通知：** 自动提取和显示（如果存在）。
- **结构化输出：** 包括规范化字段，如 `pageKind`、`description`、`payload`、`patchChanges`、`relatedEvents`、`relatedEventsData`、`warnings`、`codingNotes`、`availableSections`、`deprecationInfo`，以及结构化章节数据，如 `argumentsData`、`returnsData` 和 `payloadData`。
- **冲突感知弃用元数据：** `deprecationInfo` 现在包括 `hasConflict`、`conflictDetails` 和 `recommendedState`，以便调用者可以检测到横幅文本和补丁历史记录不一致的情况。
- **编码指导：** 从 Wiki 正文中提取警告和信息注释，如弃用 API、nil 返回值、限制/机密行为和事件时序问题。
- **相关事件：** 从相关事件章节和行为注释中提取事件名称，以便调用者可以发现他们应该检查的下一个事件。
- **精简章节焦点：** 当提供 `section` 时，响应还包括 `selectedSection`、`selectedSectionText` 和 `selectedSectionData`。
### wiki_resolve
将面向编码的问题解决为可能 API、事件、枚举、控件或技术页面的短排名列表。
- **意图清理：** 删除常见的编码动词，如 "track"、"listen" 和 "detect"，以便代理可以搜索实际的 API 术语。
- **有针对性的重写：** 为常见的魔兽世界插件任务添加聚焦搜索，如冷却跟踪和光环更新。
- **代理交接：** 返回置信度、弃用状态、相关事件、警告、编码注释、可用章节和建议的后续 `wiki_lookup` 调用。
- **范围：** 仍然仅限于 API 和密切相关的技术文档；它不会浏览一般的 Wiki 文章。
### wiki_search
仅搜索魔兽世界 Wiki 技术文档。 一般的游戏玩法和随机的 Wiki 文章被过滤掉，以便代理专注于 API、事件、枚举、控件和密切相关的技术页面。 返回最多 20 个过滤结果，包含标题、页面类型、URL 和文本片段。
### wiki_namespace
列出所有与命名空间前缀匹配的 Wiki 页面。 通过追加尾随 `.` 来处理 C_ 命名空间范围 - 因此 `C_Spell` 匹配 `C_Spell.GetSpellCooldown` 但不匹配 `C_SpellBook.IsSpellKnown`。 支持多达 1,000 个结果的分页。
## 快速入门
**要求：** Node.js >= 18.0.0
```bash
git clone https://github.com/Direction6275/warcraft-wiki-mcp.git
cd warcraft-wiki-mcp
npm install
```
无需构建步骤，无需预索引，无需数据文件。 服务器实时查询 Wiki。
### 注册
将以下内容添加到您的项目的 `.mcp.json`（Claude Code）或等效的 MCP 配置中：
```json
{
"mcpServers": {
"warcraft-wiki": {
"command": "node",
"args": ["/path/to/warcraft-wiki-mcp/src/index.mjs"]
}
}
}
```
在添加配置后重启 Claude Code。
## 工作原理
所有数据均来自 [warcraft.wiki.gg](https://warcraft.wiki.gg)，通过其 MediaWiki API：
| 端点 | 使用者 | 返回内容 |
|----------|---------|-----------------|
| `action=parse&page={title}` | `wiki_lookup` | 完整的页面 HTML + 章节元数据 |
| `action=parse&page={title}` | `wiki_resolve` | 最终排名候选人的详细信息 |
| `action=query&list=search` | `wiki_search`、`wiki_resolve` | 匹配的页面和文本片段 |
| `action=query&list=allpages` | `wiki_namespace` | 所有与标题前缀匹配的页面 |
Wiki 返回 MediaWiki HTML。 解析器剥离噪音（导航、兼容性元数据表、信息框）、提取弃用通知、显示横幅与补丁冲突、拯救旧内联章节、在 `<h2>` 边界处分割内容成命名章节、派生相关事件和编码注释信号、并将 HTML 转换为干净的文本（代码块变成 Markdown 围栏、定义列表变成缩进文本、表格变成管道分隔的行）。
```
src/
index.mjs MCP 服务器入口点、工具定义、名称规范化
wiki-client.mjs warcraft.wiki.gg 的 HTTP 客户端、内存 TTL 缓存
html-parser.mjs MediaWiki HTML -> 结构化文本章节
```
**技术细节：** 4 小时内存缓存（每个条目的 TTL，无重启持久性）。每个请求超时 10 秒。实时 Wiki 调用时内置请求合并、限流和重试/回退。优雅的错误处理，适用于丢失页面和网络故障。默认情况下搜索范围限定为 API。
## 维护
内容源由于来自 Wiki，因此维护成本较低，但解析器仍需要偶尔维护，以防 Wiki 更改其 HTML 结构。
## 测试
使用以下命令运行解析器夹具和实时烟雾测试：
```bash
npm test
```
解析器测试检查结构化表格输出和编码注释提取的稳定本地夹具。烟雾测试通过 SDK 客户端启动本地 MCP 服务器，并针对实时 Wiki 数据验证代表性的查找、解析器和搜索行为。
| 症状 | 可能原因 | 修复方法 |
|---------|-------------|-----|
| 服务器无法启动 | 缺少依赖项 | 运行 `npm install` |
| 查找返回的文本乱码 | Wiki 更改了 HTML 模板结构 | 更新 `html-parser.mjs` 中的章节分割 |
| "获取失败" 错误 | Wiki 宕机或网络问题 | 暂时 - 稍后重试 |
| 输出中缺少章节 | Wiki 页面没有该章节 | 正常 - 解析器优雅地省略缺少的章节 |
**依赖项：** `@modelcontextprotocol/sdk`（MCP 框架）和 `node-html-parser`（HTML 解析）。
## 许可证
MIT
