Pok Mon Battle Simulation

神奇宝贝MCP：数据资源+战斗模拟

一个真正的MCP stdio服务器，将丰富的口袋妖怪数据作为MCP资源公开，并将确定性战斗模拟器作为MCP工具公开。内置TypeScript，适用于Windows上的Claude Desktop。

从这里开始：克劳德桌面（Windows）MCP连接

1. 构建并启动一次以验证stdio

npm install ; npm run build ; npm start
# Expect in the console (stderr): "Pokemon MCP Server is running (stdio)"
# Press Ctrl+C to stop after confirming

1. 自动配置克劳德桌面

npm run configure:claude

这写道 %APPDATA%\Claude\claude_desktop_config.json 指向您的绝对节点路径 dist/index.js.

1. 重新启动Claude Desktop并验证连接

• 询问：“列出可用工具”→ 预期 simulate_battle 和 natural_command.
• 问：“资源/列表”或“你公开了哪些宝可梦资源？”→ 你应该看看 pokemon://types, pokemon://list, pokemon://data/{name}, pokemon://stats/{name}, pokemon://moves/{name}.
• 可选：运行确定性战斗→ “战斗皮卡楚vs charizard种子12345级50”。

如果Claude显示JSON解析错误，请重建(npm run build)并确保服务器打印了上面的stdio横幅；日志记录已经路由到stderr，以保持MCP stdout的干净。

此仓库中的MCP连接和逻辑在哪里？

• MCP stdio服务器和连接： src/server.ts （注册资源/工具；使用动态传输解析器通过stdio连接）， src/index.ts （启动服务器）
• 第1部分（数据资源）： src/data/pokemonData.ts （PokeAPI+缓存+进化）， src/types/pokemon.ts （模式）；在中处理的资源URI src/server.ts
• 第2部分（作战工具）： src/battle/battleEngine.ts, src/battle/damageCalculator.ts, src/battle/typeEffectiveness.ts, src/battle/statusEffects.ts
• 确定性RNG+日志： src/utils/rng.ts, src/utils/logger.ts （仅限标准错误）
• 自然语言和CLI： src/utils/llm.ts, src/cli.ts
• Claude桌面配置助手（支持Windows/macOS/Linux）： scripts/configure-claude.js

概览

• 第1部分（数据资源）：宝可梦基础属性、类型、能力、移动（具有力量/精度/类型/PP/类别和常见状态效果）和进化信息；暴露通过 pokemon://... MCP资源已准备好用于LLM。
• 第2部分（战斗工具）：确定性模拟器，具有类型有效性、物理/特殊伤害、速度转弯顺序、状态效果（瘫痪、烧伤、中毒、睡眠、冻结、混乱、打火）、PP/准确性、每回合日志和明确的胜者；通过MCP工具暴露。

______________________________________________________________________

安装并运行

npm install ; npm run build ; npm start

预期：服务器打印到stderr

[info] Pokemon MCP Server is running (stdio)

按Ctrl+C停止。

可选CLI（自然语言）：

npm run build ; npm run cli -- "battle pikachu vs charizard" --level 50 --seed 12345 --maxTurns 200

______________________________________________________________________

第1部分：口袋妖怪数据资源

设计：MCP资源命名空间 pokemon:// LLM可以浏览和获取。实施于 src/server.ts 带着一个 PokemonDataService (src/data/pokemonData.ts)由PokeAPI和本地JSON缓存支持 data/pokemon-data-cache.json.

暴露了什么

• 基本统计数据：生命值、攻击、防御、特殊攻击、特殊防御、速度
• 类型：全套18种
• 能力：名称、隐藏标志（描述为占位符）
• 移动：最多12个更强/可靠的移动，带字段：名称、类型、类别、力量、准确性、pp、效果（烧伤/中毒/瘫痪/睡眠/冻结/混乱/退缩，当移动元可用时）
• 进化：通过物种的下一个进化目标和水平（如果存在）→ 进化链

资源

• pokemon://types → 所有口袋妖怪类型的JSON数组
• pokemon://list → JSON名称数组（默认前50个）
• pokemon://data/{name} → 完整的口袋妖怪JSON（统计数据、类型、能力、动作、进化、身高/体重/物种）
• pokemon://stats/{name} → 仅限基本统计数据
• pokemon://moves/{name} → 仅限选定的移动列表

观察到的MCP资源设计模式

• LLM的确定性URI和稳定模式
• resources/list 列举可用的“模板”和示例条目
• resources/read 返回单个JSON有效负载（mimeType application/json)

LLM查询示例

• “阅读pokemon://stats/pikachu比较速度。”
• “阅读pokemon://moves/charizard并选择一个强大的特殊火力动作。”
• “阅读pokemon://data/bulbasaur并总结进化信息。”
• “阅读pokemon://types并解释哪一个打败了火。”

开发人员指针

• 数据服务： src/data/pokemonData.ts
• 类型： src/types/pokemon.ts
• 资源路由：in src/server.ts 在...之下 resources/list 和 resources/read

可交付成果（第1部分）

• MCP服务器和神奇宝贝资源的源代码： src/server.ts, src/data/pokemonData.ts, src/types/*
• 描述公开数据和URI的文档（此README）
• LLM使用情况的查询示例

______________________________________________________________________

第2部分：作战模拟工具

设计：MCP工具 simulate_battle 它接受两个口袋妖怪和可选选项。已实施 BattleEngine 在……里面 src/battle/battleEngine.ts 并暴露于 src/server.ts 通过 tools/list 和 tools/call.

核心机制

• 类型有效性：完整的18种类型图表 src/battle/typeEffectiveness.ts 并应用于损坏
• 伤害：使用移动类别进行物理/特殊分割，按级别缩放；STAB包括
• 回合顺序：最快者优先（平局优先于第一个口袋妖怪）
• 状态效果：至少3个已实现（我们包括瘫痪、烧伤、中毒，加上睡眠、冻结、困惑、打火）
• 精度和PP：移动消耗PP；失误得到处理；当没有PP时，挣扎着后退
• 确定性RNG：用于可重复模拟的种子PRNG；结果种子暴露
• 日志：每回合、每行动的消息，以及每回合的HP摘要

工具架构

• 姓名： simulate_battle
• 输入架构：

- pokemon1：string - pokemon2：string - options （可选）： - level：数字（默认值50） - maxTurns：数字（默认值为300） - seed：string | number（用于确定性运行）

输出形状（JSON）

• winner：string |'draw'
• battleLog：转弯数组；每个回合都有动作和HP快照
• turns：模拟的总转弯数
• seed：使用了回声种子

示例（LLM/工具调用）

• 使用{pokemon1:“pikachu”，pokemon2:“charizard”，选项：{level:50，seed:12345}}调用simulate_battle
• “自然：战斗魔法与blastoise 70级种子42转200。”

开发人员指针

• 发动机： src/battle/battleEngine.ts
• 损坏： src/battle/damageCalculator.ts
• 状态： src/battle/statusEffects.ts
• 工具暴露： src/server.ts 在...之下 tools/list 和 tools/call

可交付成果（第2部分）

• 战斗工具的源代码遵循MCP工具规范： src/server.ts, src/battle/*
• 此自述文件包含依赖项安装、服务器启动步骤和使用示例
• 在本地和Claude Desktop中设置和测试的明确说明

______________________________________________________________________

克劳德桌面（Windows）设置

1. 构建并验证服务器

npm install ; npm run build ; npm start
# Expect in the console: "Pokemon MCP Server is running (stdio)"

1. 为MCP自动配置克劳德桌面

npm run configure:claude

这写道 %APPDATA%\Claude\claude_desktop_config.json 其中一个条目指向您的绝对节点路径 dist/index.js.

1. 重新启动Claude Desktop并测试

• 问：“列出可用工具”——你应该看到 simulate_battle 和 natural_command.
• 问：“战斗皮卡丘vs charizard种子12345 50级”-你会得到确定性的结果。
• 问：“移动bulbasaur”或“统计数据闪烁”。

故障排除

• 如果Claude报告“无效JSON”，请确保所有服务器日志都转到stderr（已配置），并且您使用 npm run build.
• 如果工具未出现，请重新运行 npm run configure:claude 并重新启动克劳德。

______________________________________________________________________

项目结构

src/
 battle/                 # engine, damage, statuses, type chart
 data/                   # PokeAPI service with caching and evolution
 utils/                  # rng, logger, llm parsing
 server.ts               # MCP server (resources + tools)
 index.ts                # entry point
 cli.ts                  # optional CLI for natural commands
tests/                    # jest tests (TypeScript)
scripts/                  # Windows Claude config helper

运行测试

npm test

备注

• 服务器使用stderr记录日志，以保持MCP stdout的纯净。
• 您可以通过以下方式调整引擎的移动选择池 MOVE_POOL_SIZE env-var（默认值8）。
• 数据缓存在 data/pokemon-data-cache.json 在第一次取回之后。