random-pokemon-mcp

Offline TypeScript MCP server using @modelcontextprotocol/sdk and stdio. Node.js >=20. No backend, keys, telemetry or runtime API requests. Companion website: https://random-pokemon-generator.org

0.2.0 changelog: added real abilities (including hidden flags), independent legendary/mythical filtering, and learnable damaging-move type coverage from an offline PokeAPI snapshot. National Dex 1–1025, bundled English names, default forms only. Generation filters mean introduction generation; matchups use Gen VI+ types.

两种使用方式，让用户自己选

• 本地版（stdio）：使用下方 npx -y random-pokemon-mcp@0.2.0 安装配置；数据随包离线提供，无需 API 密钥。

• 托管版（网站 Worker）：支持远程 MCP 的客户端可使用 https://random-pokemon-generator.org/api/mcp，无需本地安装。托管服务独立开发、部署与更新，功能和数据版本可能与本地版不同。

Related MCP server: Pokemon Showdown MCP Server

Install and configure

After the package is manually published, run npx -y random-pokemon-mcp@0.2.0. Before publication use npm ci && npm run build, then configure node /absolute/path/random-pokemon-mcp/dist/index.js.

Claude Code:

claude mcp add random-pokemon -- npx -y random-pokemon-mcp@0.2.0

Cursor (.cursor/mcp.json) and Claude Desktop (claude_desktop_config.json):

{"mcpServers":{"random-pokemon":{"command":"npx","args":["-y","random-pokemon-mcp@0.2.0"]}}}

VS Code (.vscode/mcp.json):

{"servers":{"random-pokemon":{"type":"stdio","command":"npx","args":["-y","random-pokemon-mcp@0.2.0"]}}}

On Windows use npx.cmd if required by the client. stdout contains MCP protocol only.

Exactly five tools

Damage description and every success/error declare 未计入项：天气/场地/道具/特性/太晶、暴击、烧伤、墙、双打修正、特殊招式机制及逐步定点舍入. Estimates can differ from cartridge mechanics; this is not a battle simulator. Immunities yield zero damage. Shedinja's base HP rule is handled. No TCG, GO or Nuzlocke scope.

Data provenance

Base facts come from the companion site's local libs/pokemon/data/pokemon.json (1025 records: names, types, stats, introduction generation and image URLs). src/type-chart.ts retains its 18×18 Gen VI+ chart. Original source-byte hashes remain in data/source-sha256.json.

Additional snapshot: PokeAPI, fetched 2026-10-26, covering default Pokémon IDs 1–1025 through https://pokeapi.co/api/v2/pokemon/{id} and https://pokeapi.co/api/v2/pokemon-species/{id}. Referenced /api/v2/move/{id} responses supply type and damage class. data/pokeapi.json stores only abilities, separate classification flags and a sorted set of learnable non-status move types per species, plus provenance. Response SHA-256 hashes are in data/pokeapi-sha256.json. No move names/individual learnsets/version details are bundled: this keeps the package small but cannot validate submitted moves, game legality or infer battle roles. Roles remain explicitly unknown.

Reproduce with Python 3 + requests installed, then python3 scripts/snapshot-pokeapi.py [cache-directory] (default cache /tmp/random-pokemon-pokeapi-cache). Three workers, 200ms pause per request, up to five attempts with exponential backoff, cached raw responses and fail-on-error; output files are written only after every required response succeeds. Keep the cache for raw-data audits; it is excluded from npm. Runtime never calls PokeAPI. No image files are fetched or bundled; artwork stays URL-only. Pokémon names/artwork remain the property of their respective owners. MIT covers this project's code; no ownership of third-party Pokémon material is asserted.

Development and verification

npm ci
npm run build
npm run smoke
npm pack --dry-run --json > pack-dry-run.json
node scripts/validate-package.mjs

Smoke invokes the MCP Inspector CLI for tools/list and each tool, plus the SDK client for successful calls to all five tools, invalid inputs and recovery, deterministic seeds, chart/data invariants and damage declarations. Lockfile pins the dependency tree. Inspector is a development dependency only.

Manual release checklist (not executed)

1. Review the offline snapshot provenance, limitations and acceptance checks.

2. Check npm name ownership, run checks above; manually npm login, then npm publish --access public when ready.

3. Validate server.json against the official Registry schema; after npm publication follow official Registry publishing to verify io.github.yuren-dev ownership and publish with mcp-publisher. npm mcpName matches the manifest.

4. Manually submit/claim GitHub/package details on Glama and mcp.so after checking current submission requirements. No OAuth, registry publishing, directory claim or submission is performed by this repository's scripts.

License: MIT.