poe2-build-mcp: Instructions file for Claude Code

CLAUDE.md — engineering conventions for poe2-build-mcp

This file is the working agreement for anyone (human or AI) building on this repo. For what we're building and why, read PLAN.md. This file is how we build it.

What this project is (one paragraph)

An .mcpb-installable MCP server that gives an LLM a queryable Path of Exile 2 corpus (bundled SQLite, knowledge layer) plus a Path-of-Building–faithful calculation engine (headless LuaJIT subprocess, compute layer). It answers build questions, imports a user's PoB build, and helps create/tweak builds against natural-language goals — with every number computed by PoB, never invented.

Non-negotiable invariants

These are the rules that keep the project trustworthy. Don't violate them without changing this file first.

1. The engine is the source of truth for numbers. Never hand-compute, approximate, or hard-code PoE2 damage/defense math in server code, and never let an answer state a number the engine didn't produce. If PoB can't model something, surface that via validate_build — do not fake a value.
2. The server is a substrate, not a build AI. Expose composable primitives (query, mutate, compute, validate, price). Creative synthesis is the LLM's job. Resist adding "smart" heuristics to the server that belong in the model's reasoning.
3. Knowledge is offline-first and deterministic. The corpus is a bundled, read-only SQLite file. The only network calls at runtime are the live-ops tools (get_prices, get_meta_builds, check_data_version, update_corpus, and lookup_mechanic). lookup_mechanic is a deliberate, narrow exception: a single user-triggered, read-only wiki lookup for the long tail not in the corpus. It returns a targeted slice (not a dump), degrades to "unavailable", and never alters the corpus — it is not bundled redistribution and not scraping (see #4). The deterministic corpus remains the default; live lookup is the fallback when the corpus lacks a topic.
4. Scraping happens only at build time, never at runtime. poe2db/RePoE/wiki ingestion lives in pipeline/ and runs in CI. The runtime never scrapes (bulk-fetches to store); it downloads vetted artifacts. The single on-demand lookup_mechanic read (#3) is not scraping: it fetches one page for immediate display and stores nothing.
5. Generated builds are always verified before being presented. The norm is create → validate → cost → present. A build that fails validate_build is flagged, not recommended.
6. No in-game interaction, ever. No overlay, automation, memory reading, or live-screen parsing. It's out of scope and against GGG's ToS. Reject features that head this way.
7. PoB is pinned and bumped deliberately. The PoB-PoE2 submodule is pinned to a release tag. Updating it is a conscious change gated by the golden-build tests (§ Testing).