recipal-mcp-unofficial

ReciPal の栄養ラベル API 用の MCP サーバーです。AI アシスタントがレシピ、原材料、サブレシピを直接読み取り・編集できるようにします。Web UI では何時間もかかる一括操作も含みます。

非公式です。 ReciPal とは提携・承認・サポート関係にありません。製品の公開 API に対してユーザーが構築したものです。

暫定プロジェクト — このリポジトリはアーカイブされます。 ReciPal は公式 MCP サーバーを開発中です。彼らのサーバーがリリースされたら、このサーバーはそれを指すように更新され、読み取り専用でアーカイブされます。これに依存するような重要なものは構築しないでください。SUNSET.md を参照してください。

有効な有料 ReciPal サブスクリプションが必要です。 API アクセスは有料機能であり、キーはアカウント設定の API access から取得します。これがないと、このサーバーは何もできません。

目的

ReciPal の Web UI は、1 つのレシピを編集するには十分です。しかし、40 個のレシピに同じ操作を行う場合（カタログ全体のサービングサイズを修正する、(copy) サフィックスが付いた原材料名を変更する、1 つの原材料だけが異なる製品バリエーション群を作成するなど）は苦痛です。このサーバーは API を公開するため、アシスタントがドライランを先に行い、ループでその作業を実行できます。

特に有用なツールは bulk_clone_and_swap です。完全に設定された 1 つのレシピをテンプレートとして、N 回クローンし、各クローンで 1 つの原材料を交換します。ラベル設定、タグ、サービングサイズは引き継がれるため、クローンは一貫性のあるものになります。

Related MCP server: cookwith-mcp

スコープと配布

意図的に狭く、今後もそのままです：

• クローンしてビルドするソース。 ワンクリックプラグインバンドル、npx パッケージ、MCP ディレクトリやマーケットプレイスへの掲載はありません。これは ReciPal への約束であり、見落としや ToDo ではありません。

• npm には公開されていません。 package.json は意図的に private とマークされています。

• ReciPal の要請により recipal-mcp-unofficial と命名されており、公式サーバーと誤認されることはありません。

パッケージ化された配布、マーケットプレイスへの提出、またはより親しみやすい消費者向けインストールパスを追加するプルリクエストは拒否されます。歓迎される内容については 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 スタイルのフォームエンコード（recipe[name]=...）で送信されます。文書化されていない属性もコード変更なしで動作します。エンドポイントが JSON を好む場合は as_json: true を設定します。

書き込む前に実際のレシピを読んでください。 既存のレシピに対する get_recipe は、アカウントが使用する正確な属性名を示します。

既知の制限

これらは実際のもので、ライブ API に対して検証済みであり、これを基に構築する前に知っておく価値があります：

• create_recipe_shortcut は動作しません。 試したすべての ingredients 配列形式で 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 は 1 ページあたり最大 100 件です。自分でページを進めてください。

レート制限

ReciPal は、おおよそ 175,000 リクエスト/週、1,000 リクエスト/分（それを超えると HTTP 429）、および最大 5 つの同時ラベルレンダリングを文書化しています。このサーバーは 429 を Retry-After と指数バックオフで尊重し、残り 100 リクエスト未満になると stderr に警告し、すべての一括ループを設定可能な遅延で厳密に順次実行します。ラベルレンダリングを並列化しないでください。

開発

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」はその所有者の商標であり、ここではこのソフトウェアが通信する対象を説明するためにのみ使用されています。