内容
<p align="center">
<img src="assets/brand/logo-512.png" alt="gw1-mcp logo — a golden scythe and an eight-slot skill bar" width="180" height="180">
</p>
<h1 align="center">gw1-mcp</h1>
<p align="center"><em>LLM 的 Guild Wars 1 构建编译器</em></p>
<p align="center">
<a href="https://codecov.io/gh/Graphmaxer/gw1-mcp"><img src="https://codecov.io/gh/Graphmaxer/gw1-mcp/branch/main/graph/badge.svg" alt="覆盖率"></a>
<a href="https://github.com/Graphmaxer/gw1-mcp/actions/workflows/ci.yml"><img src="https://github.com/Graphmaxer/gw1-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://github.com/Graphmaxer/gw1-mcp/releases/latest"><img src="https://img.shields.io/github/v/release/Graphmaxer/gw1-mcp" alt="最新版本"></a>
<a href="LICENSE"><img src="https://img.shields.io/github/license/Graphmaxer/gw1-mcp" alt="许可证"></a>
<a href="https://github.com/Graphmaxer/gw1-mcp/commits/main"><img src="https://img.shields.io/github/last-commit/Graphmaxer/gw1-mcp" alt="最后一次提交"></a>
<a href="https://gw1mcp.grafana.net/public-dashboards/9002ddf3fb784b46847a65f4afe889fa"><img src="https://img.shields.io/badge/usage-live%20dashboard-orange" alt="实时使用仪表盘"></a>
</p>
MCP（模型上下文协议）服务器，为任何兼容的LLM客户端（Claude，ChatGPT，Cursor…）提供可靠、确定的 **Guild Wars 1** 构建知识：技能数据查找、官方模板代码编码/解码和构建验证。
**MCP 是编译器，而不是大脑。** LLM 执行战略推理；该服务器执行必须准确的事情。
## 为什么不直接问 LLM？
如果没有这个服务器，向AI助手询问Guild Wars构建通常会得到：听起来很合理的技能栏，包含不存在的技能；属性分布超过预算；从十年前的平衡补丁中引用的统计数据；以及在游戏中粘贴时会产生垃圾的代码，因为代码是按位打包的，不能逐字符猜测。
连接 gw1-mcp 后，同一个助手查找 1484 个真实技能（当前与 Reforged 平衡，每周刷新），根据实际游戏规则验证构建，并为您提供 **由编码器生成的官方模板代码**，而不是由语言模型预测的代码。战略对话保持不变；事实不再错误。
## 工具
| 工具 | 用途 |
| --- | --- |
| `get_skill` | 获取一个技能的完整记录（按确切名称或模板 ID），并在输入错误时提供最接近的匹配建议 |
| `search_skills` | 过滤搜索：职业，属性，战役，精英，名称子字符串 |
| `decode_template` | 游戏内模板代码 → 职业，属性，8 个技能及其属性 |
| `encode_template` | 命名构建 → 验证的，官方的游戏内模板代码 |
| `validate_build` | GW1 规则检查：一个精英最多，一个职业/属性所有权，首要属性，重复项 |
| `get_hero` / `list_heroes` | 具有职业，战役和解锁说明的英雄 |
| `decode_pawned_team` | paw-ned2 团队 blob（PvXwiki 团队页面）→ 每个技能栏解码 |
资源：`gw1://guide/build-workflow`（LLM 方法论）和 `gw1://heroes`。
## 快速开始
```bash
pnpm install
pnpm -r test
pnpm --filter @gw1-mcp/gw-mcp dev # stdio 服务器
```
## 软件包
- `packages/gw-template` — 模板代码编解码器（零依赖；与游戏内/PvX 代码进行往返测试，并与 [@buildwars/gw-templates](https://github.com/build-wars/gw-templates) 进行差异模糊测试）
- `packages/gw-data` — 游戏数据（1484 个技能，与 Reforged 当前平衡一致），从 [build-wars/gw-skilldata](https://github.com/build-wars/gw-skilldata) （MIT）导入
编解码器通过四种方式验证：18 个覆盖所有 10 个主要职业和所有 5 个战役的黄金 fixtures（来源于 PvXwiki，gw1builds.com，官方 wiki 和 2007 年前的游戏内格式，其中一些在技能 ID 级别得到验证），模糊往返测试，与独立实现进行差异测试，以及错误输入拒绝测试。验证规则逐一在表中测试。`pnpm test:coverage` 获取相关指标。
- `packages/gw-mcp` — MCP 服务器（传输无关核心 + stdio 入口）
- `packages/gw-worker` — 流式 HTTP 包装器（Hono），在 Cloudflare Workers 和 Node 上运行
## 部署到 Cloudflare Workers
```bash
pnpm --filter @gw1-mcp/gw-worker check # 离线捆绑验证
pnpm --filter @gw1-mcp/gw-worker deploy # 需要 `wrangler login` 一次
```
服务器是无状态的（每个请求都有一个新的 McpServer 实例，基于捆绑数据），因此它适用于 Workers 模型，无需任何配置：无需 Durable Objects，无需 KV，无需密钥。免费计划足够使用。
## 连接
- **claude.ai / Claude 应用**：设置 → 连接器 → 添加自定义连接器 → `https://gw1-mcp.<your-subdomain>.workers.dev/mcp`
- **Claude 代码**：`claude mcp add --transport http gw1 https://…/mcp` 或在本地通过 stdio：`claude mcp add gw1 -- pnpm --filter @gw1-mcp/gw-mcp dev`
- **本地 HTTP，无 Cloudflare**：`pnpm --filter @gw1-mcp/gw-worker dev:node`，然后任意客户端指向 `http://localhost:8787/mcp`
## 更新游戏数据
```bash
pnpm --filter @gw1-mcp/gw-data update @buildwars/gw-skilldata --latest
pnpm --filter @gw1-mcp/gw-data run import:data
# 或者，要导入上游发布的发布文件（每周工作流执行的操作）：
pnpm --filter @gw1-mcp/gw-data run import:data -- https://build-wars.github.io/gw-skilldata
```
## GWToolbox 集成
`gwtoolbox-plugin/` 包含一个只读 GWToolbox 插件，添加 `/exportaccount`：它将您的帐户状态（英雄，已解锁技能）复制为 JSON 到剪贴板。在对话中粘贴它，并将 `unlockedAccountSkills` 传递给 `validate_build` / `encode_template` 作为 `unlockedSkillIds` — 提出的您不拥有的技能将被标记。Windows 构建说明在 [gwtoolbox-plugin/README.md](gwtoolbox-plugin/README.md)。
## 路线图
MCP 资源用于构建原型和英雄约束，从战役进度中获取英雄，以及将帐户导出整合到 GWToolbox 本身。有关完整架构的注释，请参见 `CLAUDE.md`。
---
_本项目与 ArenaNet 或 NCSoft 无关。Guild Wars 是 NCSoft Corporation 的商标。游戏数据由 [build-wars/gw-skilldata](https://github.com/build-wars/gw-skilldata) 项目（MIT）和 Guild Wars Wiki 上的格式文档提供。_
## 开发
```bash
pnpm install && pnpm -r test
```
Node >= 22，pnpm 11。没有任何内容构建到 dist — 导出指向 `.ts` 源代码和 wrangler 的工作器包。参见 [CONTRIBUTING.md](./CONTRIBUTING.md) 开始使用，并参见 [CLAUDE.md](./CLAUDE.md) 获取完整的架构、约定和已知债务登记。
## 许可证
MIT
