README.md•4.21 kB
# 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.:
```json
{
"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
```bash
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
```bash
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
```bash
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 [`examples/llm_examples.md`](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