# Weekly Meal Planner

> Turn your pantry and its expiry dates into a 7-day dinner plan and a shopping list. List what is in your fridge and cupboards (with quantities and best-before dates) and your preferences (vegetarian, vegan, pescatarian, maximum cooking time, ingredients to avoid). The planner picks one dinner per day from about 60 simple home-cooking recipes, using food that expires soonest first, and adds up a shopping list of everything still missing.

Part of usefulweb.site (https://usefulweb.site/). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://weeklymealplanner.usefulweb.site/ (interactive tool at https://weeklymealplanner.usefulweb.site/tool)
- JSON API: POST https://weeklymealplanner.usefulweb.site/api/v1/calculate with a JSON object of inputs (schema: https://weeklymealplanner.usefulweb.site/api/v1/tool)
- OpenAPI: https://weeklymealplanner.usefulweb.site/openapi.json
- MCP (Streamable HTTP): https://weeklymealplanner.usefulweb.site/mcp - tool `weekly_meal_planner`

## Inputs
- startDate (date): First day - Default: today.
- days (integer): Number of days
- servings (integer): People per meal
- diet (select): Diet
- maxMinutes (integer): Maximum cooking time
- pantry (table): Pantry and fridge - Leave the quantity empty if you are not sure (counted as enough). Best-before dates make the planner use those items first.
- exclude (list): Avoid these ingredients - One per line, e.g. mushrooms or feta. Recipes containing them are skipped.

## Method
- Recipes come from a bundled editorial dataset of about 60 simple home-cooking dinners with ingredient quantities, cooking time and diet. Quantities are scaled linearly to the number of people.
- Recipes are filtered by diet (vegan ⊂ vegetarian ⊂ pescatarian ⊂ everything), maximum cooking time and the ingredients to avoid.
- Pantry names are matched to recipe ingredients after normalising plurals and common synonyms (e.g. eggs → egg, courgette → zucchini, spaghetti → pasta). kg and l are converted to g and ml.
- Day by day, every remaining recipe gets a score: for each ingredient, the share covered by the pantry × an urgency weight (expires within 1 day: 6, 3 days: 4, 7 days: 2, later: 1, no date: 0.5) × 10, plus the share of that pantry item used up × urgency × 5, minus 3 for every ingredient that must be bought. The highest score wins (ties: dataset order); the pantry is then reduced by what the recipe uses.
- Items past their best-before date on the cooking day are not used. A recipe is repeated only when every eligible recipe has already been planned.
- The shopping list adds up all missing amounts per ingredient (pieces rounded up to whole pieces). Salt, pepper, cooking oil and water are assumed to be at home.