hamster-mcp: Instructions file for Codex

AI Agent Context

For project requirements, architecture, and conventions, see:

• Project Documentation
• Architecture
• Principles
• Data Flow
• Decisions

Development Workflow

Setup

mise install          # Installs Python 3.14, uv, pre-commit, and project tools
uv sync --extra dev   # Creates .venv, installs package + dev deps
pre-commit install    # Installs git hooks

Running checks

ruff format --check .   # Formatting
ruff check .            # Linting
mypy                    # Type checking
pytest src/             # Tests

Rules

• Always use the mise-managed environment. Run python, ruff, mypy, pytest, etc. from the mise-activated shell or via mise run. Never set PYTHONPATH manually.
• Install via uv sync, not pip install. The project uses uv.lock for deterministic dependency resolution.
• Do not modify uv.lock by hand. It is generated by uv lock and updated by uv sync.

Icon generation

Brand icons are generated from brand/source.svg:

mise run generate-icons

The source SVG should contain black stroke-based line art with uniform stroke width. The script applies amber (#c87f43) fill and halo (3x stroke width), auto-fits to the canvas, then exports PNG icons at 256x256 and 512x512.

Generated files (written to custom_components/hamster_mcp/brand/):

• icon.svg, icon.png, [email protected]

Code Conventions

• Dataclasses everywhere. All classes use @dataclass. Prefer @dataclass(frozen=True, slots=True) for immutability; use explicit frozen=False when mutation is needed. Use .create() classmethods for complex construction. See Principles for details and exception criteria.

Package Structure

• src/hamster_mcp/mcp/_core/ --- sans-IO protocol core. Must not perform I/O or hold global state. May depend on any library as long as the code itself remains pure.
• src/hamster_mcp/mcp/_io/ --- I/O adapters (async transport). Does not import homeassistant (HA-independent for testability).
• src/hamster_mcp/component/ --- HA integration. May import anything.
• custom_components/hamster_mcp/ --- HACS deployment shim. Thin re-exports from hamster_mcp.component.