# 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