recipal-mcp-unofficial

Сервер MCP для API этикеток питания ReciPal. Он позволяет ИИ-ассистенту напрямую читать и редактировать ваши рецепты, ингредиенты и подрецепты — включая массовые операции, которые в веб-интерфейсе заняли бы часы.

Неофициальный. Не связан с ReciPal, не одобрен и не поддерживается ReciPal. Создан пользователями продукта на основе его публичного API.

Временный проект — этот репозиторий будет заархивирован. ReciPal создаёт официальный MCP сервер. Когда их версия выйдет, этот будет обновлён, чтобы указывать на неё, а затем заархивирован в режиме только для чтения. Не стройте на нём ничего важного. См. SUNSET.md.

Вам нужна активная платная подписка ReciPal. Доступ к API — платная функция; ключ находится в настройках вашего аккаунта в разделе API access. Без него этот сервер не сможет ничего сделать.

Для чего это нужно

Веб-интерфейс ReciPal хорош для редактирования одного рецепта. Но он мучителен, когда нужно сделать одно и то же с сорока рецептами — исправить размер порции во всём каталоге, переименовать ингредиенты, пришедшие с суффиксами (copy), или создать семейство вариантов продукта, отличающихся одним ингредиентом. Этот сервер открывает API, чтобы ассистент мог выполнять такую работу в цикле, сначала запустив пробный прогон.

Инструмент, который оправдывает своё существование, — bulk_clone_and_swap: возьмите один полностью настроенный рецепт как шаблон, клонируйте его N раз и замените один ингредиент в каждом клоне. Настройки этикетки, теги и размеры порций переносятся, поэтому клоны получаются согласованными.

Related MCP server: cookwith-mcp

Область применения и распространение

Область применения намеренно узкая, и такой она останется:

• Исходный код, который вы клонируете и собираете. Нет готового плагина в один клик, нет пакета npx и нет публикации в каком-либо каталоге MCP или маркетплейсе. Это обязательство перед ReciPal, а не упущение или пункт в списке задач.

• Не публикуется в npm. Файл package.json намеренно помечен как private.

• Назван recipal-mcp-unofficial по просьбе ReciPal, чтобы его нельзя было спутать с их официальным сервером.

Пул-реквесты, которые добавляют упакованное распространение, публикацию в маркетплейсах или более удобный путь установки для пользователей, будут отклонены. См. CONTRIBUTING.md о том, что приветствуется.

Установка

Требуется Node.js 18 или новее.

git clone https://github.com/BlackBlack/recipal-mcp-unofficial.git
cd recipal-mcp-unofficial
npm install
npm run build

Затем зарегистрируйте его в вашем MCP-клиенте. Для Claude Code:

claude mcp add --transport stdio recipal-mcp-unofficial \
  --env RECIPAL_API_KEY=your_key_here \
  -- node /absolute/path/to/recipal-mcp-unofficial/build/index.js

Для Claude Desktop добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "recipal-mcp-unofficial": {
      "command": "node",
      "args": ["/absolute/path/to/recipal-mcp-unofficial/build/index.js"],
      "env": { "RECIPAL_API_KEY": "your_key_here" }
    }
  }
}

Перезапустите клиент и попросите его показать список ваших рецептов. Вы должны увидеть 19 доступных инструментов. Полное руководство — в docs/SETUP.md.

⚠️ Прочтите это, прежде чем подключать его к каталогу, который вам важен

Защитные механизмы confirm: true и dry_run предоставляются моделью, а не вами. Они не позволяют расплывчато сформулированному запросу причинить вред. Но они не остановят решительного или запутавшегося агента — ассистент, решивший удалить рецепт, передаст confirm: true в том же вызове. В ReciPal нет отмены действий.

Поэтому по-настоящему разрушительные инструменты по умолчанию отключены. Их включение — осознанное действие человека, запускающего сервер, а не то, что может сделать диалог:

Всё остальное — все операции чтения и обычные инструменты создания/обновления — работает из коробки. Массовые инструменты всегда доступны, но по умолчанию используют dry_run: true и отказываются выполняться, если вызывающий код не передаст одновременно dry_run: false и confirm: true.

Рекомендуемая практика в любом случае: сначала работайте с одноразовым рецептом. Некоторые эндпоинты ведут себя иначе, чем описано в документации (см. «Известные ограничения»).

Конфигурация

См. .env.example.

Инструменты

Всего 22 инструмента, 19 доступны по умолчанию. Сгенерированная документация со всеми параметрами: docs/TOOLS.md.

† отключено по умолчанию.

Инструменты записи принимают открытый объект fields вместо фиксированного списка параметров. Опубликованная документация ReciPal обрывается до полного списка атрибутов рецепта, поэтому жёстко задавать имена полей означало бы гадать; вместо этого fields передаётся напрямую, в стиле Rails, в форме form-encoded (recipe[name]=...). Незадокументированные атрибуты работают без изменения кода. Установите as_json: true, если эндпоинт предпочитает JSON.

Прежде чем писать рецепт, прочитайте настоящий. get_recipe на существующем рецепте показывает точные имена атрибутов, которые использует ваш аккаунт.

Известные ограничения

Они реальны, проверены на живом API, и о них стоит знать, прежде чем строить что-то на этой основе:

• create_recipe_shortcut не работает. Он возвращает HTTP 422 для любого испробованного формата массива ингредиентов. Документация ReciPal обрывается до списка параметров, поэтому правильная структура неизвестна. Используйте create_recipe + create_recipe_ingredient или scale_recipe для клонирования настроенного шаблона. Инструмент оставлен на месте, чтобы структуру можно было выяснить, — если вы её разгадаете, пожалуйста, откройте PR.

• PUT /recipe_ingredients/{id} молча игнорирует ingredient_id. Он возвращает HTTP 200, а исходный ингредиент остаётся прикреплённым. Замена одного ингредиента на другой должна выполняться как удаление с последующим созданием — именно это bulk_clone_and_swap и делает внутри.

• ReciPal почти каждый ответ оборачивает дважды — {recipe: {recipe_ingredients: [{recipe_ingredient: {…}}]}}. Чтение полей из внешней обёртки даёт undefined без ошибки. Если вы расширяете этот сервер, используйте существующие помощники unwrap() / extractRecords().

• Имена параметров для scale_recipe и create_subrecipe не опубликованы. Они работают через сквозную передачу fields, но сначала запустите каждый по одному разу на одноразовом рецепте и прочитайте ответ, прежде чем выполнять цикл.

• В документации /recipes/{id}/scale указан как PUT; на самом деле работает POST. Не «исправляйте» это без тестирования.

• Нет помощника для пагинации. list_recipes ограничивает 100 записей на страницу; перебирайте страницы самостоятельно.

Лимиты запросов

ReciPal указывает примерно 175 000 запросов в неделю, 1 000 в минуту (сверх этого — HTTP 429) и максимум 5 одновременных рендеров этикеток. Этот сервер уважает 429, используя Retry-After и экспоненциальную задержку, предупреждает в stderr, когда осталось меньше 100 запросов, и выполняет каждый массовый цикл строго последовательно с настраиваемой задержкой. Не распараллеливайте рендеры этикеток.

Разработка

npm run typecheck   # tsc --noEmit
npm run build       # -> build/index.js
npm test            # offline smoke tests, no API key or network needed
npm run gen:docs    # regenerate docs/TOOLS.md from the running server
npm run verify      # all of the above

docs/TOOLS.md генерируется путём запуска собранного сервера и запроса у него его собственного списка инструментов, поэтому документация не может разойтись с кодом. CI падает, если она устарела. Если вы добавляете или изменяете инструмент, выполните npm run build && npm run gen:docs и закоммитьте результат.

Вклад приветствуется в рамках указанной выше области — начните с CONTRIBUTING.md, затем docs/TESTING.md о том, как проверять изменения на живом аккаунте, и docs/DESIGN.md о том, как части сочетаются друг с другом.

Лицензия

Apache-2.0.

«ReciPal» — товарный знак его владельца и используется здесь только для описания того, с чем общается это программное обеспечение.