meal-planner-mcp: Instructions file for Claude Code

CLAUDE.md — Meal Planner guidance

Read this first. It's the contract for working in this repo with an agent: what the pieces are, how to run and test, the design decisions and why they were made, and the deliberate simplifications (each one a good place to extend).

What this is

A self-contained MCP server that plans a week of meals from a local recipe library. It optimizes for ingredient overlap (buy shared things once), reuses serving-surplus leftovers (a big-batch cook covers extra nights), and avoids recently-cooked recipes — then produces a consolidated shopping list and a Markdown plan doc.

Single-user by design. No auth, no cloud, no external API. It clones and runs with zero credentials — the bundled data/recipes.seed.json is enough to plan a week immediately.

Why this is an MCP and not just a prompt

The honest test for whether a tool earns its place: does it give the model something it can't do alone? There are four such things, and this hits all four — which is the whole justification for the project:

Need	Plain Claude	This MCP
Suggest a generic meal	✅ fine	(a tool would add nothing)
Plan around your recipe library	❌ doesn't know it	✅ grounded in local data (#3 private data)
Remember what you ate, avoid repeats	❌ no cross-session memory	✅ state.json history (#1 persistence)
Produce a plan + list that persists	❌ can't write files	✅ Markdown export (#2 side effects)
Merge/scale ingredients exactly	❌ hand-waves arithmetic	✅ deterministic aggregate (#4 exact compute)

When changing or adding a tool, ask which of the four it serves. If the answer is "none — Claude already does this well," it probably shouldn't be a tool.

Architecture: pure core + thin adapters

The logic is pure and I/O-free, so it's all unit-tested without a runtime. Two adapters (MCP server, CLI) wire the same functions to the outside world; one module (store.py) is the only thing that touches the filesystem.