ReciPal MCP by usefulapi

List your recipes (products) with yield, servings, cost per batch/package and the headline per-serving nutrition (calories, fat, sodium, carbohydrate, protein). Sorted by last update by default. Set full=true for the complete object with every nutrient. Pages of up to 20; a page with fewer rows is the last. GET /recipes.

One recipe in full: yield, servings, packages, allergens, costs (ingredient + packaging/labor/overhead), ingredient list, tags, primary label path and the complete per-serving nutrition. GET /recipes/{id}.

The formula of one recipe: every recipe ingredient line with ingredient id, name, quantity, unit, waste %, total grams and the display name per label language. Use the line ids with recipal_update_recipe_ingredient. GET /recipes/{id}/recipe_ingredients.

One ingredient line of a recipe, including units_and_grams (the units you can use for it, each with its weight in grams). GET /recipes/{recipe_id}/recipe_ingredients/{id}.

List your own ingredients (custom and subrecipe ingredients) with allergens, units and headline nutrition per 100 g. Set full=true for every nutrient. Archived ones are hidden unless asked for. GET /ingredients.

One ingredient in full (yours or a public one): allergens, ingredient-list text, custom units, and every nutrient per 100 grams. GET /ingredients/{id}.

The cost history of one ingredient: effective date, quantity, unit, price and shipping per entry (the entry with the latest effective_at not in the future is the active one). GET /ingredients/{id}/ingredient_costs.

The currently active cost of every ingredient (one entry per ingredient): price, shipping, quantity and unit. GET /ingredient_costs.

One ingredient cost entry by id. GET /ingredient_costs/{id}.

A recipe's saved nutrition-facts label settings (format, which rows show, styling) plus the computed nutrition claims (e.g. Fat Free) and ingredient list per language. The token is the last part of the recipe's primary_label path (/api/v1/labels/{token}). Optionally compute claims and ingredient list for another format. GET /labels/{token}.

WRITE (render job): start rendering a recipe's nutrition label as a PDF or PNG and return the render status with a token. Always asynchronous: poll recipal_get_label_render_status with the token until status is ready, then give the user the temporary download url. Each account may run 5 renders in parallel. GET /recipes/{id}/label.pdf|label.png?async=true.

Status of a label render started with recipal_start_label_render: waiting, processing, ready or error. When ready, url is a temporary presigned download link. Poll about once a second; each poll counts toward the weekly request limit. GET /recipes/label_renders/{token}.

Raw-material (ingredient) stock rows: quantity on hand, weeks remaining, daily consumption, quantity on order, reorder risk (safe, warning, critical), reorder level and the on-hand value. Needs an inventory plan (otherwise 403 INVENTORY_PLAN_REQUIRED). By default sorted by weeks remaining, lowest first. GET /inventories.

One raw-material stock row by id (quantity, unit, weeks remaining, reorder guideline, on-hand value). Needs an inventory plan. GET /inventories/{id}.

Ingredient tags in use with the number of ingredients carrying each, most used first. Use them to filter recipal_list_inventories. Needs an inventory plan. GET /inventories/tags.

Takes no parameters.

Finished-goods stock rows: recipe, quantity on hand, unit, total packages, lot-code settings, case/pallet sizes and the on-hand value. Needs an inventory plan. GET /finished_goods.

One finished-goods stock row by id. Needs an inventory plan. GET /finished_goods/{id}.

Recipe tags in use with the number of recipes carrying each, most used first. Use them to filter recipal_list_finished_goods. Needs an inventory plan. GET /finished_goods/tags.

Takes no parameters.

WRITE: create a new, empty recipe (add ingredient lines with recipal_add_recipe_ingredient, or use recipal_create_recipe_from_ingredients to do both at once). All fields are optional. Creates a record in your ReciPal account; it counts against the plan's recipe allowance. POST /recipes.

WRITE: change fields of one recipe; fields you leave out stay unchanged. package_yield_quantity "default" sets the package weight to the total weight of the current ingredients (no moisture loss accounted for); ingredient_list "default" rebuilds the label ingredient list in descending weight order. Changes labels and costs of this recipe. Tags cannot be set here. PUT /recipes/{id}.

WRITE: create a NEW recipe as a copy of an existing one, with every ingredient quantity and the yield multiplied by scale_amount (1 = plain copy; per-serving nutrition stays the same; scaling down cannot take packages below 1). Costs and tags carry over. The original is not changed. Without a name the copy is called "<name> (copy)" or "<name> <n>x". POST /recipes/{id}/scale.

WRITE: create a new recipe and its ingredient lines in one call. ingredients lists ingredient ids with the weight of each in grams. Optional yield, servings and packaging fields as in recipal_create_recipe. Creates a record in your ReciPal account. POST /recipes/shortcut.

WRITE: turn a recipe into an ingredient (a subrecipe) with its nutrition, costing and ingredient list, so it can be used inside other recipes. Later changes to the recipe flow through to the ingredient. Fails if the recipe is empty. Returns the new ingredient. POST /recipes/{id}/create_subrecipe.

WRITE: add an ingredient line to a recipe, by unit and quantity (the unit must be one the ingredient offers, e.g. "1 cup" or "1 gram"; see units_and_grams from recipal_get_recipe_ingredient or valid_units from recipal_get_ingredient) or directly by total_grams (overrides unit and quantity). Changes the recipe's nutrition, label and cost. POST /recipes/{id}/recipe_ingredients.

WRITE: change the AMOUNT of one ingredient line in a recipe (unit, quantity, waste or total_grams; total_grams overrides unit and quantity). It cannot swap the ingredient: remove the line and add another instead. Changes the recipe's nutrition, label and cost. PUT /recipes/{recipe_id}/recipe_ingredients/{id}.

WRITE (destructive): permanently remove one ingredient line from a recipe. It cannot be undone, but the same ingredient can be added back (with recipal_add_recipe_ingredient). Changes the recipe's nutrition, label and cost. The ingredient itself is not deleted. DELETE /recipes/{recipe_id}/recipe_ingredients/{id}.

WRITE: create a custom ingredient (private to your account) with its nutrition facts. For a food ingredient give nutrition_unit and nutrition_quantity (the serving the nutrients are entered for, e.g. 1 cup; for units beyond gram/oz/lb/kg add them in measures first) and all required nutrients. food and non_food cannot be changed later. Non-food items: set food=false and non_food to labor, packaging, safety, other_hourly or other_fixed. POST /ingredients.

WRITE: change fields of one of YOUR ingredients (public ingredients cannot be edited); fields you leave out stay unchanged. If nutrition_unit, nutrition_quantity or their measure change, nutrients you do not pass are rescaled to keep the same amount per serving. measures REPLACES the whole list of custom units, so send them all. Setting archived true hides the ingredient from lists; false restores it. The change flows into every recipe using the ingredient. PUT /ingredients/{id}.

WRITE: add a price for an ingredient that becomes active on effective_at (the active cost is the one with the latest effective_at not after the date; one cost per ingredient per date). price and shipping are per quantity x unit. Changes the cost of every recipe using the ingredient from that date. Not allowed for subrecipe ingredients. POST /ingredient_costs.

WRITE: change an existing ingredient cost entry (date, unit, quantity, price, shipping); fields you leave out stay unchanged. Changes recipe costs that depend on it. Not allowed for subrecipe ingredients. PUT /ingredient_costs/{id}.