[Maselkov]

First of four PRs from the plan to make the MCP assistant smarter. Using it in claude.ai showed three mistakes, all from missing context:

1. It suggested keep-in-stock targets for plasmas and a catalyst that are probably made passively or kept up by Level Maintainers, which this server can't see.
2. It read a plan that crafted 40 FusionTech Mk-V and took the 8 in storage as "crafts it rather than pulling from your 8 in stock".
3. It asked which CPU to use, then explained AE2's pick and that CPU's busy time. CPUs don't matter to the user.

The instructions (gcm/mcp/instructions.py)

Until now, assistants got one fixed paragraph. The instructions are now built for each connection from three parts:

• instructions.md (773 words; a test caps it at 900, since it's in every conversation):
  • what the server sees and doesn't
  • automation it can't see: check crafts_last_week and item_history before suggesting a target; low-stock alerts are always safe
  • how fresh the data is
  • units and voltage tiers with their EU/t
  • how to read a plan
  • "AE2 picks the crafting CPU": never offer a choice or comment on CPU load
  • how to use the tools
  • confirm before changing anything; don't change targets someone else set
  • answer style
• A snapshot of the base when the assistant connects: who's signed in and what their role can change, the GTNH version, CPUs busy and idle, the last scan, patterns, power machines, and stock rules. A part that fails to read is left out and logged.
• House rules that admins write. They're framed as unable to widen permissions or skip confirmations; the tools check roles anyway.

server/discover is now cacheScope: private with a 5-minute TTL, because its text depends on the user.

Tools

• plan_craft:
  • The requested item comes in its own requested field ("crafts 64; the 1,715 already in storage aren't used, AE2 never takes the requested item from storage").
  • Ingredient rows are labelled as totals over the whole craft. They now include from_leftovers, which was missing before.
  • Each row has a plan sentence, such as "needs 4 in all: 2 from storage (all of it), 2 missing".
• get_item adds crafts_last_week: AE2 jobs that made the item, including Level Maintainers', since their jobs run on CPUs too. Uses the new store.crafts.item_crafts_since.
• stock_rules adds set_by for each target.
• CPU wording: request_craft, request_status and craft_stats no longer invite talk about CPUs.

AI assistant dialog (Settings, admins)

• The /mcp address with Copy.
• House rules: up to 4000 characters, with a counter. They're in the instructions of the next connection.
• The latest tool calls: who, which tool, the arguments, any error, and the time taken. Every call is logged to a new mcp_calls table, kept 30 days, and to the server log at INFO level. This is for tuning: what the model actually did, rather than screenshots.
• Routes: GET /api/admin/assistant, PUT /api/admin/assistant/rules, GET /api/admin/assistant/calls, all admin only.

Docs

• docs/using.md: "What the assistant is told", and house rules with examples.
• docs/server.md: the dialog.
• docs/CONTEXT.md: the design, and assistant behaviour checks, ten scenarios to re-run after changing the prompt. The first three are the mistakes above.

Testing

• New tests/test_mcp_instructions.py (15 tests): the core text's length and contents; the snapshot before anything reports and with the fake game reporting; a failing part left out; house rules (appended, capped, admin-only routes, reaching initialize and discover); plan rows, including the requested item with stock, batch leftovers, and partly-stocked and missing ingredients; crafts_last_week; set_by; the call log (logged, admin only, cut, pruned).
• New e2e step: open the dialog, see the address and a logged call, type rules, check the counter, save, close with Escape, reopen, and check initialize ends with the rules. I checked screenshots in dark at desktop width and light at phone width.
• By hand on dev.py: the snapshot matched the fake game (10 CPUs, 8 busy; 51 item types; 14 patterns; 3 power machines; 3 targets, 1 failing). The plan sentences read as above.
• The full checklist passes: pytest (1027), node --test, e2e (56), node --check, Lua (on 5.4), ruff, luacheck and shellcheck.
• Not tested: whether claude.ai behaves better with the new instructions. That's the checklist in CONTEXT.md, best run on the gtnh.network instance after deploying.

🤖 Generated with Claude Code