mcp-replay-dota2: Instructions file for Claude Code

CLAUDE.md

Guidance for working on this Dota 2 MCP Server codebase.

CRITICAL: Before Pushing Code

ALWAYS run the FULL CI pipeline locally before pushing:

# 1. Lint check
uv run ruff check src/ tests/ dota_match_mcp_server.py

# 2. Type check
uv run mypy src/ dota_match_mcp_server.py --ignore-missing-imports

# 3. Tests (requires replay files in ~/dota2/replays/)
uv run pytest

ALL THREE must pass before committing. Do not push code that fails any step.

Commands

# Always use uv, never python/pip directly
uv run python script.py
uv add package-name
uv run pytest tests/

# Run specific tests
uv run pytest tests/test_combat_log_parser.py -v

# Fetch latest constants from dotaconstants
uv run python scripts/fetch_constants.py

Project Structure

dota_match_mcp_server.py   # MCP server entry point (tools + resources)
src/
  resources/               # Data providers (heroes, map, pro_scene)
  models/                  # Pydantic response models
  utils/                   # Parsers, downloaders, caches
  services/                # Services layer (NO MCP deps)
tests/
  conftest.py              # Session-scoped fixtures - reuses parsed data
data/
  constants/               # Cached dotaconstants JSON
  pro_scene/               # Player/team aliases

Key Patterns

Use python-manta Types, Not Dicts

CRITICAL: Always use python-manta Pydantic models and access attributes directly:

# GOOD - python-manta types with attribute access
from python_manta import EntitySnapshot, HeroSnapshot, CombatLogEntry

for hero_snap in snapshot.heroes:  # hero_snap is HeroSnapshot
    hero = hero_snap.hero_name     # attribute access
    cs = hero_snap.last_hits
    x, y = hero_snap.x, hero_snap.y  # position

# BAD - dict-style access (WILL FAIL)
for hero_snap in snapshot.heroes:
    hero = hero_snap.get('hero_name')  # NO! HeroSnapshot is not a dict
    hero = hero_snap['hero_name']       # NO!

Services Layer (src/services/)