# Pokemon MCP Project 🎮

A Model Context Protocol (MCP) server that provides Pokemon data and battle simulation capabilities to AI assistants like Claude Desktop.

## Features ✨

- **Pokemon Data Resource**: Access comprehensive Pokemon information including stats, types, abilities, and moves
- **Battle Simulation Tool**: Simulate battles between any two Pokemon with type effectiveness and status effects
- **Type Effectiveness System**: Accurate damage calculations based on Pokemon type matchups
- **Status Effects**: Burn, Poison, and Paralysis effects implemented
- **Data Caching**: Efficient caching system to minimize API calls

## Project Structure 📁

```
Poke-MCP/
├── src/
│   ├── server.py            # Main MCP server with the tool and the resource
│   ├── pokemon_types.py     # Data classes for Pokemon, Moves, etc.
│   ├── datastore.py         # Pokemon data fetching and caching
│   ├── battle.py            # Battle simulation logic
│   ├── mechanics.py         # Battle mechanics (damage, STAB, etc.)
│   ├── type_chart.py        # Type effectiveness chart
│   └── utils.py             # Utility functions and logging
├── data/                    # Cache storage (created automatically)
├── .venv/                   # Virtual environment
├── pyproject.toml           # Project configuration and dependencies
└── README.md                # This file
```

## Prerequisites 📋

- Python 3.10 or higher
- pip (Python package manager)
- Internet connection (for fetching Pokemon data from PokeAPI)

## Installation 🚀

### Step 1: Clone/Download the Project
```bash
# If you have the zip file, extract it first
# Then navigate to the project directory
cd Poke-MCP
```

### Step 2: Create Virtual Environment (Recommended)
```bash
# Windows
python -m venv .venv
.venv\Scripts\activate

# Mac/Linux
python -m venv .venv
source .venv/bin/activate
```

### Step 3: Install Dependencies
```bash
# Using pyproject.toml (recommended)
pip install -e .

# Or using pip directly
pip install mcp[cli]>=1.2.0 httpx>=0.26.0
```

## Running the Server 🎯

### Basic Server Start
```bash
# Make sure virtual environment is activated
python -m src.server
```

**Note**: The server will run silently (no output) when working correctly. This is intentional - it's waiting for MCP client connections via STDIO.

### Verify Server is Running
- The terminal will appear to "hang" - this means it's working!
- Press `Ctrl+C` to stop the server
- Check that `data/` and `src/__pycache__/` folders are created

## Using with Claude Desktop 🤖

### Step 1: Locate Claude Desktop Config
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`

### Step 2: Add Server Configuration
Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pokemon": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "C:/full/path/to/your/Poke-MCP"
    }
  }
}

--------------
If the above didn't work use the following:
--------------
{
  "mcpServers": {
    "pokemon": {
      "command": "cmd",
      "args": ["/c", "cd /d C:/full/path/to/your/Poke-MCP && .venv\\Scripts\\python.exe -m src.server"]
    }
  }
}
```

**Important**: Replace `C:/full/path/to/your/Poke-MCP` with your actual project path including the Poke-MCP in the end of the path!

### Step 3: Restart Claude Desktop
If Claude Desktop is already running close it and reopen it to load the new configuration.

### Step 4: Activate Tools and Include Resources if not
Usually if Claude Desktop detectes the server it activates the tools automatically, but the resources need to be included in the chat messages (new chat -> press the + button -> click on Add from pokemon -> click on pokemon_list) and then it will be added to this only specific message.

### Step 5: Test in Claude
Ask Claude:
- "Can you list available Pokemon?"
- "Show me details about Pikachu"
- "Simulate a battle between Charizard and Blastoise"

## Available MCP Resources 📚

### List Pokemon
- **Parameters**: No parameters needed. Also either way Claude Desktop dosen't accept parameters in the resources.
- **Returns**: List of 20 Pokemons with mostly all of the information of each one of them! 

## Available MCP Tools 🛠️

### Battle Simulation
- **Parameters**:
  - `pokemonA_name`: Name or ID of first Pokemon
  - `pokemonB_name`: Name or ID of second Pokemon
  - `pokemonA_level`: Level of first Pokemon (1-100, default: 50)
  - `pokemonB_level`: Level of second Pokemon (1-100, default: 50)
  - `pokemonA_moves`: Optional list of moves for first Pokemon
  - `pokemonB_moves`: Optional list of moves for second Pokemon
  - `seed`: Optional seed for reproducible battles
  - `max_turns`: Maximum battle turns (default: 200)
- **Returns**: JSON string  with these fields:

    winner — the winning Pokémon’s name (or a draw indicator)

    turns — how many turns the battle took

    log — an ordered list of turn-by-turn messages

    summary — a short human-readable wrap-up



## Troubleshooting 🔧

### Server appears to hang with no output
**This is normal!** The server runs silently when using STDIO transport. It's waiting for client connections.

### ImportError: No module named 'mcp'
Install dependencies:
```bash
pip install mcp[cli]>=1.2.0
```

### Port already in use (when using inspector)
```bash
# Find and kill the process
netstat -ano | findstr :6277
taskkill /PID [PID_NUMBER] /F
```

### KeyboardInterrupt traceback when stopping server
This is normal! It's Python's way of confirming the server stopped when you pressed Ctrl+C.

## Implementation Details 🔍

### Battle Mechanics
- **Damage Formula**: Uses simplified version of the official Pokemon damage formula.
- **Type Effectiveness**: Fire > Grass, Water > Fire, etc.
- **STAB Bonus**: 1.5x damage for moves matching Pokemon type.
- **Critical Hits**: 6.25% chance for 1.5x damage.
- **Speed**: Determines turn order. 
- **Status Effects**:
  - Burn: 1/16 HP loss per turn, halves physical damage
  - Poison: 1/8 HP loss per turn
  - Paralysis: 25% speed reduction, 25% chance to skip turn

### Data Source
- Pokemon data fetched from [PokeAPI](https://pokeapi.co/)
- Cached locally in `data/cache.json` to reduce API calls

## Project Requirements Met ✅

- ✅ MCP server implementation using FastMCP
- ✅ Pokemon data resource with comprehensive information
- ✅ Battle simulation tool with game mechanics
- ✅ Type effectiveness calculations
- ✅ Status effects (Burn, Poison, Paralysis)
- ✅ Turn order based on Speed stats
- ✅ Detailed battle logs
- ✅ Evolution information
- ✅ Move and ability data



-----

If you encounter any issues:
- Check the Troubleshooting section above
- Ensure all dependencies are installed
- Verify Python version is 3.10+
- Check that the virtual environment is activated

---

Thank you.