AI导哈

魔兽世界API工具集

一个完整的魔兽世界零售版API封装工具集，支持OAuth 2.1认证，可查询游戏数据和玩家档案，支持多区域和语言。

  • by brunofin
  • TypeScript
  • 本地部署
  • 11 星标
  • 更新于
在 GitHub 查看 brunofin/wow-mcp

使用说明

哇，麦克

包装MCP服务器 完整的魔兽世界零售API （游戏数据+配置文件）作为197个MCP工具。支持 OAuth 2.1身份验证 （授权码+用于ChatGPT的PKCE，用于CLI工具的客户端凭据）并且完全 区域不可知 --每个工具都可以接受 region 和 locale 作为可选参数，因此单个服务器实例可以查询任何区域。

快速开始

cp .env.example .env
# Fill in BNET_CLIENT_ID and BNET_CLIENT_SECRET

npm install
npm run build
npm start          # stdio transport

发展

npm run dev        # runs via tsx (no build step)
npm run inspect    # opens MCP Inspector UI
npm run lint       # type-check only
npm test           # run auth integration tests

API覆盖范围

所有196个零售工作说明书端点都注册为单独的MCP工具，外加一个自定义计算工具：

  • 游戏数据API --161种工具，涵盖成就、拍卖、azerite精华、连接领域、契约、生物、公会徽章、传家宝、物品、期刊、媒体、改良工艺、坐骑、神话基石、神话突袭排行榜、宠物、可玩职业、可玩种族、可玩专业、力量类型、职业、PvP赛季、PvP等级、任务、领域、地区、声誉、搜索端点、咒语、天赋、技术天赋、头衔、玩具和魔兽世界代币。
  • 简介API --35个工具，用于角色档案、成就、外观、收藏、地下城、遭遇战、装备、猎人宠物、媒体、神话基石档案、职业、PvP、任务、声誉、灵魂绑定、专业化、统计、头衔和公会端点。
  • 自定义 — wow_character_achievementsTimeline 构建一个按时间顺序排序的已完成成就时间表（计算得出，而不是暴雪的原始终点）。

地区和地区

每个工具都接受两个可选参数：

  • region — "us" （默认）， "eu", "kr"，或 "tw"
  • locale — "en_US" （默认）或目标区域支持的任何区域设置（例如。 "es_MX", "de_DE", "fr_FR", "ko_KR")

环境中不需要区域配置。相同的Battle.net凭据适用于所有地区。

环境变量

看 .env.example。只需要两个：

  • BNET_CLIENT_ID --Battle.net OAuth客户端ID
  • BNET_CLIENT_SECRET --Battle.net OAuth客户端密钥

可选身份验证（MCP HTTP端点的OAuth 2.1）：

  • MCP_AUTH_SECRET --启用OAuth的密码。用作登录 /authorize 页面（适用于ChatGPT/浏览器客户端），作为 client_secret 为了 client_credentials 赠款，直接作为静态 Bearer 用于简单客户端的令牌（Warp、curl等）。
  • MCP_TOKEN_TTL_SECONDS --访问令牌生存期（默认值： 3600)
  • DATABASE_URL --PostgreSQL连接字符串（例如。 postgresql://user:pass@host:5432/db).设置后，OAuth令牌、客户端和身份验证代码将保存在PostgreSQL中，以便它们在重启后仍然存在。如果不存在，则使用内存存储。这 docker-compose.yml 自动设置。

当 MCP_AUTH_SECRET 设置后，服务器将公开一个完整的OAuth 2.1提供程序：

  • GET /.well-known/oauth-protected-resource --RFC 9728元数据
  • GET /.well-known/oauth-authorization-server --RFC 8414元数据（包括 code_challenge_methods_supported: ["S256"])
  • POST /register --RFC 7591动态客户端注册
  • GET|POST /authorize --授权码+带密码登录的PKCE流
  • POST /token --支持 authorization_code （使用PKC）和 client_credentials 拨款

这 MCP_AUTH_SECRET 值也可以直接作为 Bearer 令牌（例如。 Authorization: Bearer <your-secret>)--对于像Warp这样不支持OAuth流的客户端很有用。

如果 MCP_AUTH_SECRET 如果未设置，服务器将在没有身份验证的情况下运行。

可选调整：

  • LOG_LEVEL --pino日志级别（默认值： info)
  • HTTP_TIMEOUT_MS --请求超时（默认值： 15000)
  • HTTP_RETRY_LIMIT --重试计数（默认值： 2)
  • CACHE_TTL_SECONDS --响应缓存TTL（默认值： 300)
  • CACHE_SIZE --最大缓存条目数（默认值： 500)

测试

npm test

集成测试使用Node的内置测试运行器(node:test)via tsx --没有额外的测试依赖关系。该套件使用测试凭据在随机端口上启动服务器，并端到端验证OAuth 2.1身份验证：

  • 供应 /.well-known/oauth-protected-resource 元数据
  • 供应 /.well-known/oauth-authorization-server S256元数据
  • 通过注册新客户端 POST /register
  • 拒绝 /mcp 没有令牌（401有 resource_metadata 提示）
  • 拒绝 client_credentials 错误的秘密（401）
  • 通过发行代币 client_credentials 正确的秘密（200）
  • 完成完整授权_代码+PKCE流程（注册→ 授权→ 令牌→ /mcp)
  • 允许 /mcp 随着 MCP_AUTH_SECRET 作为静态承载令牌（200）
  • 拒绝 /mcp 使用伪造令牌（401）

码头工人

docker compose build
docker compose up -d

秘密通过以下方式注入 .env 在主机上（未提交）。容器以非root用户身份运行，仅具有生产依赖关系。

compose堆栈包括一个用于持久OAuth令牌存储的PostgreSQL实例。PostgreSQL数据绑定挂载到 ./data/postgres/ 在主机上（映射到 /var/lib/postgresql/data 容器内部），因此它在容器重新创建、主机重新启动和Docker引擎升级过程中持续存在。 DATABASE_URL 自动预配置。

NAS/自托管注意事项： 确保 data/postgres/ 目录位于可靠的文件系统上。备份此文件夹以保留所有OAuth状态。

建筑

src/
  index.ts                          # entry point — loads env, starts server
  app.ts                            # HTTP server factory (all routes)
  auth.ts                           # OAuth 2.1 provider (metadata, registration, authorize, token, bearer validation)
  config/
    env.ts                          # zod env parsing (credentials + tuning)
    regions.ts                      # region enum, API hosts, OAuth URL
  store/
    types.ts                        # OAuthStore interface + record types
    memory.ts                       # in-memory store (default)
    postgres.ts                     # PostgreSQL store (when DATABASE_URL set)
    index.ts                        # factory — picks store based on env
  mcp/
    tools.ts                        # auto-registers all endpoints + custom tools
    schemas.ts                      # shared zod input schemas
  blizzard/
    tokenManager.ts                 # OAuth client-credentials + single-flight
    client.ts                       # got wrapper: bearer injection, cache, 401 retry
    endpoints/
      types.ts                      # EndpointDef interface, buildPath(), schema helpers
      gamedata.ts                   # 161 Game Data API endpoint definitions
      profileEndpoints.ts           # 35 Profile API endpoint definitions
    schemas/
      characterSchemas.ts           # zod response schemas
      achievementSchemas.ts
    dto/
      characterDto.ts               # normalized character DTO
      timeline.ts                   # achievement timeline builder
  util/
    http.ts                         # got defaults
    cache.ts                        # TTL cache
    logger.ts                       # pino (stderr)
test/
  auth.test.ts                      # OAuth2 auth integration tests

端点在中以声明方式定义 gamedata.ts 和 profileEndpoints.ts每个条目指定一个工具名称、路径模板、命名空间类型和zod输入模式。这 tools.ts 模块迭代注册表，并将每个条目自动注册为MCP工具，注入 region 和 locale 参数自动。

相关 MCP