# Pokémon Battle Simulation – MCP Server

Minimal MCP server exposing:
- Pokémon data from PokeAPI
- A simple battle simulator (type effectiveness, status effects, logs)

This document explains install, run, Claude Desktop setup, and how to test.

## MCP architecture (overview)

```mermaid
flowchart LR
  subgraph Client[Claude Desktop]
    UI[User prompt]
    MCPClient[MCP client]
  end

  subgraph Server[MCP Pokémon Server]
    Tools[Tools]
    Resources[Resources]
    Engine[BattleEngine]
    API[PokeAPI Client]
  end

  subgraph PokeAPI[PokeAPI]
    DS[(Types\nMoves\nPokémon)]
  end

  UI --> MCPClient
  MCPClient <--> |stdio JSON-RPC| Server
  Server --> Resources
  Server --> Tools
  Tools --> Engine
  Engine --> API
  Resources --> API
  API --> |HTTPS| DS
```

## Prerequisites
- Node.js 18+ on Windows (recommended via nvm-windows or nodejs.org installer)
- Internet access (for PokeAPI and first-time dependency install)
- Claude Desktop installed

## Project structure
```
mcp-pokemon/
├── src/
│   ├── server/            # MCP server (registers resources + tools)
│   ├── data_layer/        # PokeAPI client + caching
│   ├── battle/            # battle engine
│   └── schemas/           # TypeScript interfaces
├── scripts/
│   └── ingest_pokeapi.ts  # optional: pre-fetch data to local JSON
├── data/                  # generated by ingestion (optional)
├── dist/                  # compiled JS
├── package.json
└── tsconfig.json
```

## 1) Install
```bash
npm install
```

## 2) Build
```bash
npm run build
```
This compiles TypeScript to `dist/`.

## 3) Run the server (pick one)
- Development (tsx + TypeScript):
```bash
npm run dev
```
- Production (compiled JS):
```bash
node dist/server/index.js
```
Expected output: `Pokémon MCP Server running on stdio`.

## 4) Configure Claude Desktop (Windows)
Edit the file:
```
C:\Users\<YourUser>\AppData\Roaming\Claude\claude_desktop_config.json
```
Add this entry (adjust paths if needed):
```json
{
  "mcpServers": {
    "pokemon": {
      "command": "node",
      "args": ["C:\\Users\\Sujal\\mcp-pokemon\\dist\\server\\index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```
Notes:
- Dev alternative: `"command": "npx", "args": ["tsx", "src/server/index.ts"]`.
- Restart Claude Desktop after editing the config.

## 5) Optional: Pre-fetch data
Downloads type effectiveness, popular moves, and Gen‑1 Pokémon to `data/`.
```bash
npm run ingest
```

## 6) Use from Claude
Example prompts:
- List the available MCP tools
- Get detailed information about Pikachu
- Search for Pokémon with “char” in the name
- Tell me about the move “thunderbolt”
- Simulate a battle between Charizard and Blastoise at level 50

Tools:
- `get_pokemon(identifier: string)`
- `search_pokemon(query: string)`
- `get_move(moveName: string)`
- `simulate_battle(pokemon1: string, pokemon2: string, level1?: number, level2?: number)`

Resource:
- `pokemon://data` – metadata and usage help for the Pokémon data resource

## Troubleshooting
- If Claude shows “Server disconnected”, open logs: “Open Logs Folder” → `mcp-server-pokemon.log`.
- Ensure the config path points to the absolute `dist/server/index.js`.
- Rebuild after edits: `npm run build`.
- Manual test: `node dist/server/index.js` (expect stdio banner, no errors).

## Uninstall / clean
```bash
# remove build output
rd /s /q dist

# remove downloaded data (if created by ingest)
rd /s /q data
```

## License
MIT