pokeapi-mcp-server

---

概览

来自 PokéAPI 的 Pokémon 游戏数据：Pokémon、招式、特性、道具和性格。一次调用即可获取完整的 Pokémon 档案（属性、类型、特性、进化、图像），可按世代、类型、图鉴或蛋群筛选，并计算双属性克制关系。

工具

工具	描述
pokeapi_get_pokemon	一次调用即可获取去规范化的 Pokémon 档案 — 属性、类型、特性、进化链、图像和物种数据
pokeapi_get_type_matchups	计算某种类型或 Pokémon 的攻击和防御属性效果，并正确组合双属性克制关系
pokeapi_get_move	招式详情 — 类型、伤害类别、威力、命中率、PP、优先级、属性变化和效果文本
pokeapi_get_ability	特性详情 — 效果文本及拥有该特性的 Pokémon，并标明隐藏特性标记和槽位
pokeapi_get_item	道具详情 — 效果文本、类别、按版本区分的价格、投掷威力、属性和常见持有者
pokeapi_get_nature	性格详情 — 属性提升／降低情况和树果口味偏好；不带标识符调用时列出全部 25 种性格
pokeapi_find_pokemon	按世代、类型、图鉴或蛋群筛选 Pokémon，支持名称词元匹配和分页

资源

资源	描述
pokeapi://pokemon/{identifier}	按名称或 PokéAPI Pokémon 记录 ID 获取 Pokémon 档案 — 返回与 pokeapi_get_pokemon 相同的数据，但不包含招式
pokeapi://type/{typeName}	类型伤害关系 — 原始倍率表，包含攻击和防御关系

所有资源数据也可通过工具访问。

---

功能参考

pokeapi_get_pokemon _工具

• 接受小写连字符格式的名称或数字形式的 PokéAPI 宝可梦记录 ID 作为 identifier；未知条目会返回 not_found。种族名称会解析为其默认形态（deoxys 会返回 deoxys-normal，并附带 resolvedFromSpecies: "deoxys"）。
• 在一份档案中返回种族值、属性、特性效果、图像、进化链（包含每个 evolutionDetails 选项）、形态、捕获率和成长率、性别比例，以及传说和幻之宝可梦标记。
• include_moves（默认值为 false）会添加招式摘要；始终返回 moveCount。game_version 用于选择风味文本，若无匹配项则回退到最新的英文条目。

---

pokeapi_get_type_matchups _工具

• 必须且只能指定 type（属性名称）或 pokemon（名称或 PokéAPI 宝可梦记录 ID）之一；未知条目会返回 not_found。
• 种族名称会解析为其默认形态（deoxys 会使用 deoxys-normal）；resolvedPokemon 和 resolvedFromSpecies 会报告匹配结果，直接查询属性时则为 null。
• 返回 offensiveRelations（双属性宝可梦时为 null）和 defensiveMatchups；双属性防御效果会合并，免疫效果优先。
• composedMultipliers 按每种攻击属性列出 0、0.25、0.5、1、2 或 4 倍倍率；未列出的属性造成 1 倍伤害。

---

pokeapi_get_move _工具

• 接受小写连字符格式的招式名称或数字 ID；未知条目会返回 not_found。
• 返回属性、伤害类别、威力、命中率、PP、优先度、目标、能力阶级变化和追加效果几率，以及完整和简短的英文效果文本。
• include_learners（默认值为 false）会添加可以学会该招式的宝可梦列表。learnersIncluded 用于区分未请求该列表和已请求但没有已知学习者的情况。

---

pokeapi_get_ability _工具

• 接受小写连字符格式的特性名称或数字 ID。
• 返回完整和简短的英文效果文本、特性引入的世代，以及拥有该特性的所有宝可梦，并标明其隐藏特性标记和槽位。
• 若标识符未解析到任何特性，则返回 not_found。

---

pokeapi_get_item _工具

• 接受小写连字符格式的道具名称或数字 ID。
• 返回类别、投掷威力、属性（可携带、可消耗等）、图像 URL、效果文本，以及通常会携带该道具的宝可梦。
• prices 列出每个版本／货币条目（versionGroup、currency、purchasePrice、sellPrice）；null 表示该处不可购买或出售，空列表表示没有价格记录。cost 是旧版宝可币价格，或为 null。
• 若标识符未解析到任何道具，则返回 not_found。

---

pokeapi_get_nature _工具

• identifier（名称或 1–25 的 ID）为可选项；省略时会一次性返回全部 25 种性格（isListAll: true）。
• 每个条目都包含提升的能力值、降低的能力值，以及喜欢和讨厌的树果风味；5 种中性格性的这些值均为 null。
• 若提供的标识符未解析到任何性格，则返回 not_found。

---

pokeapi_find_pokemon _工具

• 必须至少指定 generation、type、pokedex 和 egg_group 之一，并以 AND 逻辑组合；query（最多 100 个字符）会在结果中按词匹配名称。无法识别的类别名称会返回 invalid_filter。
• 返回用于后续调用 pokeapi_get_pokemon 的 id 和 name 条目，并提供分页前的 totalCount。仅按属性搜索会包含形态；世代、图鉴和蛋组筛选则返回种族。ID 是 PokéAPI ID，而非图鉴编号。
• appliedFilters 会回显已应用的筛选条件、查询词、limit 和 offset。未指定类别的调用不会返回条目，并会提示必须指定一个类别。
• limit（默认值为 50）和 offset（默认值为 0）用于对筛选结果分页。若请求的页码超出最后一个匹配项，则保留 totalCount 并建议使用 offset: 0；若没有匹配项，则建议放宽筛选条件。

---

pokeapi://pokemon/{identifier} _资源

• 与 pokeapi_get_pokemon 的载荷相同，include_moves 固定为 false
• identifier 是名称或 PokéAPI Pokémon 记录 ID，包括形态 ID；种族名称会解析为其默认变种
• 当标识符与任何 Pokémon 记录或种族均不匹配时返回 not_found

---

pokeapi://type/{typeName} _资源

• 返回一种类型的原始进攻和防御伤害关系倍率表
• typeName 是 18 种标准 Pokémon 类型之一
• 当类型名称在 PokéAPI 中不存在时返回 not_found

---

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 追踪的结构化日志记录。

PokéAPI 专属功能：

• 无需密钥且只读——运行时无需 API 密钥、身份验证或配置
• 图遍历汇总——pokeapi_get_pokemon 在两个并行阶段中，通过 /pokemon、/pokemon-species、/evolution-chain 和 N 个 /ability 端点发起调用，并汇总为一个对象
• 积极缓存——PokéAPI 数据是静态游戏数据；响应会按可配置的 TTL（默认 6 h）缓存，以遵守 PokéAPI 的公平使用政策
• 输入规范化——接受小写连字符格式的名称或数字 ID；会去除首尾空白、转为小写，并将空白字符替换为连字符。空标识符或长度超过 100 个字符的标识符会返回 not_found（搜索筛选条件则返回 invalid_filter），且不会发起上游请求
• 优先使用英语——effect_entries 和 flavor_text_entries 始终筛选为 language.name === 'en'；缺少条目时显示为 null，而非其他语言的字符串

适合 Agent 使用的输出：

• 双属性组合——pokeapi_get_type_matchups 根据原始伤害关系计算有效的属性克制矩阵，让 Agent 获得直接答案，而不必自行对原始表格进行乘算
• 形态覆盖——pokeapi_get_pokemon 会列出所有形态变体，让 Agent 可以识别特定形态并再次调用（阿罗拉、伽勒尔、Mega、超极巨化）
• 可空详情——缺少的描述、精灵图、持有者和学习者会在文本和结构化结果中明确标示，而非省略

---

开始使用

公共托管实例

可使用公共实例 https://pokeapi.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

{
  "mcpServers": {
    "pokeapi-mcp-server": {
      "type": "streamable-http",
      "url": "https://pokeapi.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地运行

无需 API 密钥。将以下内容添加到 MCP 客户端配置文件中：

{
  "mcpServers": {
    "pokeapi-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/pokeapi-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "pokeapi-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/pokeapi-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "pokeapi-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/pokeapi-mcp-server:latest"
      ]
    }
  }
}

如需使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥——PokéAPI 完全公开。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/pokeapi-mcp-server.git

2. 进入目录：

cd pokeapi-mcp-server

3. 安装依赖：

bun install

4. 配置环境（可选）：

cp .env.example .env
# All vars are optional — the server works with defaults

---

配置

变量	说明	默认值
POKEAPI_BASE_URL	PokéAPI 基础 URL — 可覆盖为本地镜像或代理。	https://pokeapi.co/api/v2
POKEAPI_CACHE_TTL_SECONDS	PokéAPI 响应的缓存时长（秒）。	21600（6 小时）
POKEAPI_REQUEST_TIMEOUT_MS	每个请求的超时时间，单位为毫秒。	10000
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_SESSION_MODE	HTTP 会话模式：auto、stateful 或 stateless。	stateless
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录调用失败时的输入和结果，按键名脱敏，并限制为 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认 16384）字节。自由格式值中的机密不会脱敏。	false
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	OTLP 日志导出端点。	未设置

完整的可选覆盖项列表请参阅 .env.example。

面向高流量使用的自托管

PokéAPI 的公平使用政策要求使用方积极缓存，并建议高流量部署运行本地实例。此服务默认已将响应缓存 6 小时（POKEAPI_CACHE_TTL_SECONDS），足以满足大多数工作负载。对于托管或批量任务较多的部署，可在本地运行 PokéAPI 官方 Docker 镜像，并将 POKEAPI_BASE_URL 指向该实例 — 服务会自动切换。

---

运行服务

本地开发

• 构建并运行：

  bun run rebuild
  
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Offline Vitest suite with deterministic fetch fixtures
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t pokeapi-mcp-server .
docker run --rm -p 3010:3010 pokeapi-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/pokeapi-mcp-server。构建时使用 --build-arg OTEL_ENABLED=false 可省略 OpenTelemetry 对等依赖。

---

项目结构

路径	用途
src/index.ts	createApp() 入口 — 注册工具、资源并初始化服务。
src/config/	使用 Zod 解析服务专用环境变量（server-config.ts）。
src/mcp-server/tools/	工具定义（*.tool.ts）。
src/mcp-server/resources/	资源定义（*.resource.ts）。
src/services/pokeapi/	PokeApiService — 类型化的获取方法、缓存、重试和超时处理。
tests/	与 src/ 结构对应的 Vitest 测试套件。

---

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简而言之：

• 处理程序抛出错误，由框架捕获 — 仅捕获有类型的上游错误，并使用 ctx.fail(...) 映射为已声明的 errors[] 契约
• 使用 ctx.log 记录请求范围的日志，使用 ctx.state 存储租户范围的数据（并进行缓存）
• 在 src/index.ts 的 createApp() 数组中注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

---

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

---

许可证

Apache-2.0 — 详情请参阅 LICENSE。