Schemas / Guided cooking

Make the step readable and the machine action explicit.

Plain text guides a person. Structured annotations let Cookidoo reconstruct ingredient weighing, manual settings, and supported Thermomix modes.

Required invariant

Ingredient handling and machine actions are separate steps.

Always use two consecutive steps

First weigh or add ingredients with only INGREDIENT annotations. Then chop, mix, heat, cook, or knead with a TTS or MODE annotation.

This applies to every recipe created, translated, enhanced, or repaired by the MCP.

[
  {
    "type": "STEP",
    "text": "Добавьте 75 г сахара.",
    "annotations": [{"type": "INGREDIENT", "...": "..."}]
  },
  {
    "type": "STEP",
    "text": "Измельчите 30 сек/скорость 10.",
    "annotations": [{"type": "TTS", "...": "..."}]
  }
]

Do not combine those annotations in one step, even if the original recipe does.

Text ranges

Positions use JavaScript UTF-16 code units.

Every annotation points to a human-readable substring inside its step. Python code-point indexes differ from JavaScript when emoji or other non-BMP characters appear before that substring.

Never calculate production offsets with plain len() or .index().

Use schemas.position_for or the calculate_annotation_position MCP tool.

calculate_annotation_position(
  text="Добавьте ингредиенты. Затем 30 сек/скорость 10.",
  marker="30 сек/скорость 10",
  occurrence=1
)

Manual settings

TTS: time, temperature, and speed.

TTS is Cookidoo’s manual settings annotation—not text-to-speech.

{
  "type": "TTS",
  "data": {
    "time": 30,
    "temperature": {"value": "100", "unit": "C"},
    "speed": "4",
    "direction": "CCW"
  },
  "position": {"offset": 42, "length": 29}
}

Field	Contract
`time`	Integer seconds.
`speed`	String: `soft`, `0.5`, or `1` through `10`.
`temperature.value`	String value; unit is `C` or `F`.
`direction`	Use `CCW` for reverse. Normal clockwise is normally omitted.
`position`	UTF-16 range over the readable settings phrase.

Cookidoo constrains combinations; manual temperatures cannot normally be combined with speeds above 6.

Auto-weighing

Link the ingredient phrase and its amount.

{
  "type": "INGREDIENT",
  "data": {
    "description": {
      "text": "75 г сахара",
      "annotations": [
        {
          "type": "VOLUME",
          "data": {
            "amount": 75,
            "unit": "gram",
            "unitText": "г"
          },
          "position": {"offset": 0, "length": 4}
        }
      ]
    }
  },
  "position": {"offset": 9, "length": 11}
}

The outer range selects the ingredient phrase in the step.
The nested VOLUME range selects the amount in description.text.
Use amountMax for a range.
The verified on-device weighing path is the nested VOLUME inside the step annotation.

Smart functions

Supported modes

Mode	Data
`DOUGH`	`{"time": seconds}`, 1–1200.
`BLEND`	`{"time": seconds, "speed": "6"..."8"}`, 10–300 seconds.
`TURBO`	`{"time": 0.5\|1\|2, "pulseCount": optional}`.
`WARM_UP`	Temperature plus speed `soft`, `1`, or `2`.
`RICE_COOKER`	Empty data object.
`STEAMING`	Time, speed, direction, and supported accessory.
`BROWNING`	Time, temperature, and `Gentle` or `Intense` power.

{
  "type": "MODE",
  "name": "DOUGH",
  "data": {"time": 60},
  "position": {"offset": 12, "length": 13}
}

Recommended workflow

Translate first. Annotate second.

Copy an official recipe when full instructions are needed.
Translate and clarify ingredient and step text.
Split ingredient handling from machine operations.
Add the readable settings phrase to each machine step.
Calculate positions against the final translated text.
Validate the complete structure.
PATCH ingredients and instructions separately.
Reload the customer recipe and verify the stored result.

Raw Markdown Verified JSON example