pokemon_sv_damage_calc_mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Pokémon Scarlet/Violet (SV) damage calculation API built with FastAPI. It provides high-precision damage calculations for competitive Pokémon battling, supporting 16-stage random damage rolls, comprehensive stat calculations, type effectiveness (including Terastal mechanics), abilities, items, weather, and terrain effects.

Common Development Commands

Running the Application

# Development server with auto-reload
python src/damage_calculator_api/main.py

# Production server with uvicorn
uvicorn src.damage_calculator_api.main:app --host 0.0.0.0 --port 8000

# Install dependencies
pip install -e .
# or with Poetry (if available)
poetry install

Testing

# Run all tests
python -m pytest tests/ -v

# Run specific test file
python -m pytest tests/test_calculators/test_damage_calculator.py -v

# Run tests with detailed output
python tests/test_calculators/test_damage_calculator.py

Development Tools

# Check for linting/typing issues (if available)
python -m pytest tests/ --verbose

# Access interactive API documentation
# Start the server and visit: http://localhost:8000/docs

Architecture Overview

Core Components

FastAPI Application (src/damage_calculator_api/main.py)

• Main application entry point with CORS, exception handling, and router registration
• Lifespan management for data preloading
• Health check and documentation endpoints

Damage Calculation Engine (src/damage_calculator_api/calculators/damage_calculator.py)

• DamageCalculator: Main calculation engine integrating all mechanics
• Supports 16-stage damage rolls (85%-100% random factor)
• Comprehensive ability, item, weather, terrain, and status effect handling
• Move comparison and detailed analysis capabilities

Data Models (src/damage_calculator_api/models/pokemon_models.py)

• PokemonState: Complete Pokémon battle state (stats, abilities, conditions)
• MoveInput: Move information with modifiers
• BattleConditions: Field conditions (weather, terrain, room effects)
• DamageResult: Comprehensive calculation results with KO analysis