Servidor MCP de Pokémon

Un servidor de Model Context Protocol (MCP) que proporciona datos de Pokémon a través de herramientas estandarizadas. Este monorepo contiene tanto el servidor MCP como el servicio de ingesta de datos para obtener información de Pokémon desde PokeAPI.

Arquitectura

Este es un monorepo de PNPM con dos paquetes principales:

• pokemon-mcp-server: Servidor MCP que expone datos de Pokémon a través de herramientas estandarizadas

• pokemon-mcp-ingestion: Servicio de ingesta de datos que obtiene información de PokeAPI y la almacena en SQLite

El sistema utiliza una base de datos SQLite compartida (data/pokemon.sqlite) para el almacenamiento de datos de Pokémon.

Related MCP server: PokeMCP

Características

Herramientas MCP disponibles

• get_pokemon - Obtener información detallada sobre un Pokémon específico

• search_pokemon - Buscar Pokémon por nombre, tipo u otros criterios

• get_strongest_pokemon - Encontrar los Pokémon más fuertes según varias estadísticas

• get_pokemon_stats - Obtener estadísticas detalladas de un Pokémon

• compare_pokemon - Comparar estadísticas entre dos Pokémon

• get_type_effectiveness - Obtener información sobre la efectividad de tipos

Cobertura de datos

• Datos completos de Pokémon desde PokeAPI

• Estadísticas, tipos, habilidades y más

• Relaciones de efectividad de tipos

• Buscable por múltiples criterios

Inicio rápido

Requisitos previos

• Node.js 18+

• PNPM

• Git

Instalación

1. Clona el repositorio:

git clone https://github.com/grovesjosephn/pokemcp.git
cd pokemcp

2. Instala las dependencias:

bun install

3. Configura la base de datos:

./scripts/setup.sh

4. Compila todos los paquetes:

bun run build

Uso

Ejecución del servidor MCP

# Development mode (with hot reload)
bun run dev

# Production mode
cd packages/pokemon-mcp-server
bun run start

Pruebas con el inspector MCP

# Visual GUI testing
cd packages/pokemon-mcp-server
bun run inspect

# CLI testing
bun run inspect:cli

Ingesta de datos

# Run data ingestion
cd packages/pokemon-mcp-ingestion
bun run start

Integración con Claude Desktop

Opción 1: Paquete NPM (Recomendado)

Instala el servidor globalmente:

cd packages/pokemon-mcp-server
bun run build
npm link

Configura Claude Desktop:

{
  "mcpServers": {
    "pokemon": {
      "command": "pokemon-mcp-server",
      "env": {
        "POKEMON_DATA_DIR": "/path/to/pokemcp/data"
      }
    }
  }
}

Opción 2: Ejecución directa de Node

{
  "mcpServers": {
    "pokemon": {
      "command": "node",
      "args": ["/path/to/pokemcp/packages/pokemon-mcp-server/dist/server.js"],
      "env": {
        "POKEMON_DATA_DIR": "/path/to/pokemcp/data"
      }
    }
  }
}

Opción 3: Modo de desarrollo

{
  "mcpServers": {
    "pokemon": {
      "command": "bun",
      "args": ["/path/to/pokemcp/packages/pokemon-mcp-server/server.ts"],
      "env": {
        "POKEMON_DATA_DIR": "/path/to/pokemcp/data"
      }
    }
  }
}

Desarrollo

Comandos del espacio de trabajo

bun run build         # Build all packages
bun run dev           # Run all packages in development mode
bun run test          # Run tests for all packages
bun run format        # Format all files
bun run format:check  # Check formatting

Comandos del paquete del servidor

cd packages/pokemon-mcp-server

bun run build         # Compile TypeScript
bun run dev           # Watch mode
bun run start         # Run server
bun run inspect       # Run MCP Inspector GUI
bun run inspect:cli   # Run MCP Inspector CLI
bun test              # Run tests

Comandos del paquete de ingesta

cd packages/pokemon-mcp-ingestion

bun run build         # Compile TypeScript
bun run dev           # Watch mode
bun run start         # Run ingestion
bun test              # Run tests

Pruebas

El proyecto utiliza el ejecutor de pruebas integrado de bun:

# Run all tests
bun run test

# Run specific package tests
cd packages/pokemon-mcp-server && bun test
cd packages/pokemon-mcp-ingestion && bun test

Esquema de la base de datos

La base de datos SQLite incluye tablas para:

• pokemon - Información básica de Pokémon

• stats - Estadísticas de Pokémon (PS, Ataque, Defensa, etc.)

• types - Tipos de Pokémon y relaciones

• abilities - Habilidades de Pokémon

Contribución

1. Haz un fork del repositorio

2. Crea una rama de funcionalidad

3. Realiza tus cambios

4. Añade pruebas

5. Ejecuta bun run format

6. Envía una solicitud de extracción (pull request)

Directrices de confirmación (commit)

Utiliza el formato de confirmación convencional:

<type>[optional scope]: <description>

Examples:
- feat(server): add Pokemon evolution chain tool
- fix(ingestion): handle missing species URL gracefully
- docs: update integration guide

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles

Enlaces

• Model Context Protocol

• PokeAPI

• Claude Desktop