Pokémon VGC Damage Calculator MCP Server

# Pokémon VGC Damage Calculator MCP Server A server built using Model-Context Protocol (MCP) that provides AI agents a standardized interface for performing Pokémon damage calculations using the `@smogon/calc` package. <a href="https://glama.ai/mcp/servers/@jpbullalayao/pokemon-vgc-calc-mcp"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@jpbullalayao/pokemon-vgc-calc-mcp/badge" alt="Pokémon VGC Damage Calculator Server MCP server" /> </a> ## Features - **MCP-compliant server** with TypeScript and the official MCP SDK - **Accurate damage calculations** powered by the community-vetted `@smogon/calc` library - **Comprehensive input handling** for Pokémon stats, abilities, items, moves, and field conditions - **Error handling** for invalid Pokémon names, moves, and input validation - **Vercel deployment ready** with zero-config deployment support ## Prerequisites - Node.js 18+ - npm ## Installation ```bash npm install -g pokemon-vgc-calc-mcp ``` ## Development ```bash npm run build # Build TypeScript npm run test # Run test calculation ``` ### MCP Client Configuration Configure your MCP client (Claude Desktop, Cursor, etc.): **Using remote npm package:** ```json { "mcpServers": { "pokemon-calc": { "command": "npx", "args": ["pokemon-vgc-calc-mcp"], "env": {} } } } ``` **Local development:** Clone repo locally, build the project and then configure MCP client: ``` $ git clone git@github.com:jpbullalayao/pokemon-vgc-calc-mcp.git $ npm install $ npm run build ``` ```json { "mcpServers": { "pokemon-calc": { "command": "node", "args": ["path/to/pokemon-vgc-calc-mcp/dist/index.js"], "env": {} } } } ``` ### Tools Available The server exposes one primary tool: `calculateDamage` #### Tool: calculateDamage Calculates battle damage between an attacking and defending Pokémon. **Input Parameters:** - `attacker`: Pokémon object with species, level, stats, ability, item, etc. - `defender`: Pokémon object with species, level, stats, ability, item, etc. - `move`: Move object with name and optional critical hit flag - `field`: Field conditions including weather, terrain, and side effects **Output:** - `description`: Human-readable calculation result - `damage`: [min, max] damage range - `koChance`: Knock-out probability description - `fullResult`: Complete result object from smogon/calc ### Example Usage When called by an MCP client, the tool accepts parameters like: ```json { "attacker": { "species": "Pikachu", "level": 50, "ability": "Static", "item": "Light Ball", "nature": "Timid", "evs": { "spa": 252, "spe": 252, "hp": 4 } }, "defender": { "species": "Charizard", "level": 50, "ability": "Blaze" }, "move": { "name": "Thunderbolt" }, "field": { "gameType": "Singles" } } ``` **Output:** ``` **252 SpA Light Ball Pikachu Thunderbolt vs. 0 HP / 0 SpD Charizard: 198-234 (107 - 126.4%) -- guaranteed OHKO** Damage: 198-234 KO Chance: guaranteed OHKO ``` ## Testing ### Local MCP Server Testing You can test the local MCP server using the MCP Inspector: ```bash npm run build npx @modelcontextprotocol/inspector node path/to/pokemon-vgc-calc-mcp/dist/index.js ``` #### Test Input Example Use the following input to test the `calculateDamage` tool: ```json { "attacker": { "species": "Chien-Pao", "nature": "Jolly", "evs": { "atk": 252, "spe": 252, "hp": 4 }, "level": 50 }, "defender": { "species": "Flutter Mane", "nature": "Modest", "evs": { "hp": 164, "def": 100 }, "level": 50 }, "move": { "name": "Icicle Crash" }, "field": {} } ``` #### Expected Output ``` **252 Atk Sword of Ruin Chien-Pao Icicle Crash vs. 164 HP / 100 Def Flutter Mane: 126-148 (83.4 - 98%) -- guaranteed 2HKO** Damage: 126-148 KO Chance: guaranteed 2HKO ``` ## Project Structure ``` src/ ├── index.ts # Main MCP server implementation ├── calculator.ts # Damage calculation wrapper └── types.ts # TypeScript type definitions ``` ## Author's Note Interested in the progress of this project? Feel free to follow the repo for live updates! If you need to get a hold of me regarding this project, feel free to either: - email me at professor.ragna@gmail.com - tweet me [@professorragna](https://twitter.com/professorragna) If you're interested in helping to fund this project, you can support me [here](https://www.buymeacoffee.com/professorragna). Any and all support is greatly appreciated! ## License MIT