# Pokédex MCP Server
A Model Context Protocol (MCP) server that provides comprehensive Pokémon data access through the PokeAPI. This server enables AI agents to fetch detailed Pokémon information, type effectiveness charts, encounter locations, and search capabilities.
## Features
- **Detailed Pokémon Information**: Get comprehensive data including stats, abilities, types, sprites, and artwork
- **Type Effectiveness**: Complete damage relationship charts for all Pokémon types
- **Encounter Locations**: Wild encounter data with locations, levels, and capture methods
- **Search Functionality**: Find Pokémon by partial name matching
- **REST API Client**: Full TypeScript client for PokeAPI v2 with type safety
- **Zod Validation**: Runtime schema validation for all tool inputs
- **Clean Architecture**: Modular design with separated concerns
## Architecture
The server is built with a clean, modular architecture:
```
src/
├── index.ts # MCP server entry point and transport setup
├── tools.ts # MCP tool definitions and registration
├── client.ts # PokeAPI REST client with TypeScript types
├── formatters.ts # Response formatting utilities
└── fetcher.ts # GraphQL client (legacy, replaced by REST client)
```
### Core Components
- **MCP Server**: Uses `@modelcontextprotocol/sdk` for protocol compliance
- **REST API Client**: Comprehensive PokeAPI v2 client with full TypeScript support
- **Zod Validation**: Runtime type checking and schema validation
- **Response Formatters**: Centralized formatting for consistent output
## Available Tools
### `fetch_pokemon`
Fetch detailed information about a Pokémon by name or ID.
**Parameters:**
- `name` (string): The name or ID of the Pokémon
**Example Response:**
```
**pikachu** (ID: 25)
Height: 4 decimetres (0.4m)
Weight: 60 hectograms (6.0kg)
Base Experience: 112
Order: 35
**Types:** electric
**Abilities:** static, lightning-rod (hidden)
**Base Stats:** hp: 35, attack: 55, defense: 40, special-attack: 50, special-defense: 50, speed: 90
**Sprites:**
- Default: https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/25.png
- Shiny: https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/shiny/25.png
- Artwork: https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/other/official-artwork/25.png
```
### `get_type_effectiveness`
Get type effectiveness information including strengths, weaknesses, and resistances.
**Parameters:**
- `name` (string): The name or ID of the type
**Example Response:**
```
**FIRE Type Effectiveness**
**Strong Against (2x damage to):** grass, ice, bug, steel
**Weak Against (0.5x damage to):** fire, water, rock, dragon
**No Effect Against (0x damage to):** None
**Resistant To (0.5x damage from):** fire, grass, ice, bug, steel, fairy
**Vulnerable To (2x damage from):** water, ground, rock
**Pokémon with this type:** charmander, charmeleon, charizard, vulpix, ninetales, growlithe and 58 more...
```
### `get_pokemon_encounters`
Get location encounter information for a Pokémon.
**Parameters:**
- `name` (string): The name or ID of the Pokémon
**Example Response:**
```
**pikachu Encounter Locations:**
**viridian forest:**
red: walk (Lv.3-5, 5% chance)
blue: walk (Lv.3-5, 5% chance)
yellow: walk (Lv.4-6, 100% chance)
**power plant:**
red: walk (Lv.20-24, 25% chance)
blue: walk (Lv.20-24, 25% chance)
```
### `search_pokemon`
Search for Pokémon by partial name match.
**Parameters:**
- `query` (string): Partial name to search for
**Example Response:**
```
**Search results for "char":**
1. charmander (ID: 4)
2. charmeleon (ID: 5)
3. charizard (ID: 6)
*Use fetch_pokemon with any of these names to get detailed information.*
```
## Installation
### Prerequisites
- Node.js 18+
- pnpm (recommended) or npm
### Setup
1. **Clone and install dependencies:**
```bash
git clone <repository>
cd pokedex
pnpm install
```
2. **Build the project:**
```bash
pnpm build
```
3. **Run the server:**
```bash
node dist/index.js
```
## Development
### Project Structure
```
pokedex/
├── src/
│ ├── index.ts # Server entry point
│ ├── tools.ts # MCP tool definitions
│ ├── client.ts # PokeAPI REST client
│ ├── formatters.ts # Response formatting
│ └── fetcher.ts # GraphQL client (legacy)
├── dist/ # Compiled JavaScript
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── CLAUDE.md # Development guidelines
└── README.md # This file
```
### Available Scripts
```bash
# Build TypeScript to JavaScript
pnpm build
# Run tests
pnpm test
# Build and run server
pnpm build && node dist/index.js
```
### Development Guidelines
- **ES Modules**: Project uses `"type": "module"` for modern JavaScript
- **TypeScript**: Strict mode enabled with ES2022 target
- **Code Style**: Formatted with consistent patterns
- **Validation**: All inputs validated with Zod schemas
- **Error Handling**: Comprehensive error catching and user-friendly messages
## MCP Integration
### Claude Desktop Integration
Add to your Claude Desktop MCP configuration:
```json
{
"mcpServers": {
"pokedex": {
"command": "node",
"args": ["/path/to/pokedex/dist/index.js"],
"env": {}
}
}
}
```
### Other MCP Clients
The server implements the standard MCP protocol and works with any compliant client:
- **Transport**: stdio (standard input/output)
- **Protocol Version**: 2025-06-18
- **Capabilities**: tools (with listChanged support)
## API Coverage
This server provides access to major PokeAPI v2 endpoints:
- **Pokémon Data**: `/pokemon/{id or name}` - Complete Pokémon information
- **Type Information**: `/type/{id or name}` - Type effectiveness and relationships
- **Encounter Data**: `/pokemon/{id}/encounters` - Wild encounter locations
- **Search**: `/pokemon` list endpoint for name-based searching
## Dependencies
### Runtime Dependencies
- **@modelcontextprotocol/sdk**: MCP protocol implementation
- **zod**: Runtime type validation and schema definition
### Development Dependencies
- **typescript**: TypeScript compiler and language support
- **@types/node**: Node.js type definitions
## Contributing
1. Follow existing code patterns and architecture
2. Maintain TypeScript strict mode compliance
3. Add appropriate error handling for new features
4. Update formatters for consistent response formatting
5. Test with MCP clients before submitting changes
## API References
- **PokeAPI**: https://pokeapi.co/docs/v2
- **MCP Protocol**: https://modelcontextprotocol.io
- **MCP TypeScript SDK**: https://github.com/modelcontextprotocol/typescript-sdk
## License
This project provides educational access to Pokémon data through the public PokeAPI service. All Pokémon data is owned by The Pokémon Company.
