Pokémon MCP Server

Pokémon MCP Server — Data Resource + Battle Simulation Tool

Overview

This project implements an MCP (Model Context Protocol) server that provides AI models with access to two key capabilities:

1- Pokémon Data Resource – a resource that exposes comprehensive Pokémon data from the public PokéAPI ( https://pokeapi.co/ ).

2- Battle Simulation Tool – a tool that simulates battles between any two Pokémon, including type effectiveness, stats-based damage, turn order, and basic status effects.

This server acts as a bridge between AI and the Pokémon world, enabling LLMs to both retrieve knowledge and interactively simulate battles.

Part 1: Pokémon Data Resource

Implementation

• Connects to the public PokéAPI ( https://pokeapi.co/ )
• Exposes comprehensive Pokémon information including:
• Base stats: HP, Attack, Defense, Special Attack, Special Defense, Speed
• Types (e.g., Fire, Water, Grass)
• Abilities
• Available moves and their effects (power, accuracy, type, effect text)
• Evolution information

MCP Resource

• Resource: pokemon://{name}
• Returns JSON including stats, types, abilities, moves (with effects), and evolution chain.
• Implements MCP resource design patterns to make this data accessible to LLMs.

Deliverables

• Code for the MCP server with the Pokémon data resource.
• Documentation (this README) describing how the resource exposes data.
• Example queries (examples/llm_examples.md).

Part 2: Battle Simulation Tool

Implementation

• Tool: simulate_battle(pokemon_a, pokemon_b, max_turns=100, seed=None)
• Simulates a battle between any two Pokémon using:
• Type effectiveness calculations (e.g., Water > Fire)
• Damage calculations based on stats and move power
• Turn order based on Speed stat

Status effects:

• Paralysis – chance to skip a turn
• Burn – recurring HP loss
• Poison – recurring HP loss
• Detailed battle logs showing each turn’s actions and outcomes
• Winner determination (first Pokémon to faint, or higher HP after max turns)

MCP Tool

• Exposed via MCP as a callable tool: simulate_battle
• Returns JSON object, e.g.:

Deliverables

• Code for the battle simulation tool following MCP tool specification
• Example usage in examples/llm_examples.md

Project Packaging

The submission includes a ZIP file containing:

• All code (pkmon_core/server.py, pkmon_core/battle.py)
• Supporting files (requirements.txt, README.md, examples/)
• A test script (test_part1.py)
• Clear instructions for setup and usage

Installation & Setup

Requirements

• Python 3.10+
• Virtual environment recommended

Setup

Running & Testing

Run the MCP Server

Note: The server runs in stdio mode and will appear idle, waiting for an MCP client. Stop with Ctrl+C.

Quick Python Tests

Expected output:

• JSON data for Pikachu (types, stats, moves, evolution chain)
• Battle log with turn-by-turn actions and a winner (e.g., Blastoise)

Examples for LLM Usage

See examples/llm_examples.md for prompt examples, such as:

• Summarizing a Pokémon’s stats, moves, and evolution
• Simulating a battle and explaining why the winner won

See examples/llm_examples.md for prompt examples.

Notes

• Simplified mechanics: ignores PP, items, weather, etc.
• Focused on clarity and educational battle simulation
• Easily extensible to add more mechanics