TaifAlsadoon/pokemon-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.:

{
  "winner": "blastoise",
  "log": [
    "--- Turn 1 ---",
    "charizard used fire-punch → blastoise lost 14 HP!",
    "blastoise is now affected by burn!",
    ...
  ]
}

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

git clone https://github.com/TaifAlsadoon/pokemon-mcp-server.git
cd pokemon-mcp-server

python -m venv .venv
source .venv/bin/activate  

pip install -r requirements.txt

Running & Testing

Run the MCP Server

python -m pkmon_core.server

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

Quick Python Tests

python - << 'PY'
from pkmon_core.server import get_pokemon, simulate_battle

print("Resource sample (pikachu) ->")
print(get_pokemon("pikachu")[:200], "...\n")

print("Battle sample ->")
res = simulate_battle("charizard", "blastoise", seed=42, max_turns=20)
print("Winner:", res["winner"])
print("\n".join(res["log"][:10]))
PY

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 for prompt examples.

Notes

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