Pokemon Gen3 Calculator

Una calculadora de daño y estado para Pokémon Generación 3.

Documentación

pokemon-gen3-calc-mcp

Servidor MCP (Model Context Protocol) para calcular estadísticas y daño de la tercera generación de Pokémon (Rubí, Zafiro, Esmeralda, Rojo Fuego y Verde Hoja).

Resumen

Este proyecto funciona como una herramienta externa para que los LLM realicen cálculos de Pokémon con precisión. Está implementado como un servidor MCP y puede utilizarse desde clientes MCP como Claude Desktop.

Funciones principales

Cálculo de estadísticas (calculate_status): Cálculo preciso de valores reales teniendo en cuenta valores base, valores individuales, puntos de esfuerzo y naturaleza.
Cálculo de daño (calculate_damage): Cálculo integral de daño que considera los siguientes factores:
- Compatibilidad de tipos
- Bonificación por mismo tipo (STAB)
- Efectos de habilidades (Mar Llamas, Torrente, Espesura, etc.)
- Efectos de objetos (Cinta Elegida, objetos potenciadores de tipo, etc.)
- Efectos climáticos (sol, lluvia, tormenta de arena, granizo)
- Estado del campo (Reflejo, Pantalla de Luz, Lodazal, Ducha)
- Modificadores de rango de características (-6 a +6)
- Determinación de golpe crítico
- Manejo de movimientos especiales (Meteorobola, Patada Baja, Rayo Solar, Autodestrucción/Explosión)
Cálculo exhaustivo de esfuerzo del atacante (calculate_damage_matrix_varying_attack):
- Fija el esfuerzo del defensor y calcula la matriz de daño probando todas las combinaciones de esfuerzo del atacante.
- Útil para encontrar el esfuerzo de ataque mínimo necesario para derrotar al oponente de forma segura.
Cálculo exhaustivo de esfuerzo del defensor (calculate_damage_matrix_varying_defense):
- Fija el esfuerzo del atacante y calcula la matriz de daño probando todas las combinaciones de esfuerzo del defensor.
- Útil para considerar la distribución de esfuerzo defensivo necesaria para resistir un ataque específico.

Requisitos del entorno

Node.js (se recomienda instalarlo mediante Volta)
npm

Instalación

# リポジトリのクローン
git clone https://github.com/ptrst102/pokemon-gen3-calc-mcp.git
cd pokemon-gen3-calc-mcp

# 依存関係のインストール
npm install

Uso

Integración con clientes MCP

Ejecuta la compilación para generar los archivos en el directorio dist:

npm run build

Añade lo siguiente al archivo de configuración del cliente MCP (como Claude Desktop):

{
  "mcpServers": {
    "pokemon-gen3-calc": {
      "command": "node",
      "args": ["path/to/pokemon-gen3-calc-mcp/dist/index.js"]
    }
  }
}

Manejo de movimientos especiales

Este servidor MCP admite el manejo de los siguientes movimientos especiales:

Meteorobola

El tipo y la potencia cambian según el clima.
Sol: tipo fuego, potencia 100
Lluvia: tipo agua, potencia 100
Granizo: tipo hielo, potencia 100
Tormenta de arena: tipo roca, potencia 100

Patada Baja

La potencia cambia según el peso del Pokémon rival.
Potencia de 20 a 120 según el peso.

Rayo Solar

El daño se reduce a la mitad con lluvia, tormenta de arena o granizo.

Autodestrucción/Explosión

Se calcula considerando la defensa del rival a la mitad.

Para desarrolladores

Generación de esquemas

npm run schemagen

Este proyecto utiliza un mecanismo que genera automáticamente esquemas JSON para MCP (Model Context Protocol) a partir de esquemas Zod.

Después de modificar los esquemas Zod en src/tools/*/handlers/schemas/, al ejecutar npm run schemagen se genera automáticamente src/tools/*/generated/inputSchema.ts.

Inicio del servidor de desarrollo

npm run dev

Pruebas de integración

Para verificar que el servidor de desarrollo funciona correctamente, se incluye un script de pruebas de integración:

# MCPサーバーへの実際のリクエストをテスト
npm run test:integration

Las pruebas de integración verifican lo siguiente:

La conexión al servidor
El cálculo de estadísticas mediante la herramienta calculate_status
El cálculo de daño mediante la herramienta calculate_damage
El cálculo exhaustivo de esfuerzo del atacante mediante la herramienta calculate_damage_matrix_varying_attack
El cálculo exhaustivo de esfuerzo del defensor mediante la herramienta calculate_damage_matrix_varying_defense
El manejo de errores

Entorno de desarrollo recomendado

Para el desarrollo de este proyecto se recomienda el uso de las siguientes herramientas:

GitHub CLI (gh)

Se recomienda encarecidamente instalar GitHub CLI para agilizar la integración con GitHub.

Consulta las instrucciones oficiales de instalación.

Claude Code

Se recomienda el uso de la herramienta de desarrollo asistida por IA Claude Code. Dado que este proyecto cuenta con pautas de desarrollo definidas en CLAUDE.md, el uso de Claude Code facilita la generación de código.

Comandos de desarrollo

# 型チェック
npm run typecheck

# テスト実行
npm run test                    # 全テスト実行
npm run test -- --watch         # ウォッチモードでテスト実行
npm run test -- src/tools/calculateDamage  # 特定ディレクトリのテスト
npm run test -- src/utils/adjustSpecialMoves/adjustSpecialMoves.spec.ts  # 特定ファイルのテスト

# テストカバレッジ測定
npm run test:coverage           # カバレッジ付きでテスト実行
# カバレッジレポート：
# - コンソールに概要が表示されます
# - HTMLレポートは coverage/index.html で確認できます

# リント・フォーマット
npm run lint    # チェックのみ
npm run format  # 自動修正

# 全チェック（型チェック + リント + テスト）
npm run check

# 結合テスト（MCPサーバーへの実際のリクエストをテスト）
npm run test:integration

# スキーマ生成（ZodスキーマからMCP用JSONスキーマを生成）
# src/tools/*/handlers/schemas/ 内のZodスキーマを変更した後に実行
npm run schemagen

# ビルド（dist/ディレクトリに出力）
npm run build

Estructura del proyecto

Estructura de directorios principal:

src/
├── data/          # ポケモンデータ（種族値、わざ、もちもの等）
├── tools/         # MCPツール定義とハンドラ
│   ├── calculateStatus/
│   ├── calculateDamage/
│   ├── calculateDamageMatrixVaryingAttack/
│   └── calculateDamageMatrixVaryingDefense/
├── types/         # 共通型定義
└── utils/         # 共通ユーティリティ
    ├── adjustSpecialMoves/     # 特殊な技の処理
    ├── calculateDamageCore/    # ダメージ計算コアロジック
    └── error/                  # エラーハンドリング

Stack tecnológico

TypeScript (ESNext, ESM)
Model Context Protocol SDK
Zod (validación)
Vitest (pruebas)
Biome (linter/formateador)
esbuild (compilación)

Licencia

MIT