M餐搭子とは
M餐搭子は、マクドナルド MCP データを基盤としたスマートなセット提案 Skill です。都市、ランドマーク、予算、上限カロリー、たんぱく質目標を入力するだけで、近隣のテイクアウト可能な店舗を検索し、現在のメニューと栄養データを照合して、実行可能なセットを3種類提示します。
単品だけをおすすめするツールとは異なり、M餐搭子は各セットの価格、カロリー、たんぱく質、予算使用額、残りカロリー、推薦理由を表示します。また、MCP 呼び出しチェーンを展開して、各 Tool の状態と所要時間を確認することもできます。
このプロジェクトは 2026 マクドナルド・プログラマー創意開発コンテストに参加していますが、マクドナルド公式製品ではありません。商品提供状況、価格、キャンペーンについてはマクドナルド公式チャンネルの実際の情報を基準とし、出力は医療または栄養に関する専門的な助言を構成するものではありません。
このプロジェクトが解決する問題
注文が難しいのは、選択肢が不足しているからではなく、メニュー、栄養情報、割引、個人の目標がそれぞれ別の場所に分散しているからです。ユーザーは予算とカロリーを管理しながら、たんぱく質を増やしたい場合もあり、最後にはセットとして十分かどうかも判断しなければなりません。
M餐搭子は、ユーザーに先にその食事の条件を定義してもらい、具体的な商品を事前に決めるのではなく、実際のメニューから結果を計算します。メニュー価格、栄養データ、割引情報を1つのワークスペースに統合することで、推薦の過程を理解しやすく、検証しやすくしています。
主な機能
- 店舗のリアルタイム検索：
query-nearby-storesを使用し、都市とランドマークから近隣のテイクアウト可能な店舗を検索します。 - メニューのリアルタイム取得：
query-mealsを使用し、現在の店舗の価格、通常価格、商品画像、タグを取得します。 - 栄養マッチング：
list-nutrition-foodsを使用し、メニュー商品とカロリー、たんぱく質のデータを照合します。 - 3種類のセット結果：「バランス重視」「たんぱく質強化」「おまかせセット」をそれぞれ返し、ブラックボックスの答えを1つだけ提示することを避けます。
- 説明可能な指標：1元あたりのたんぱく質、予算使用額、残りカロリー、割引差額を表示します。
- 割引とキャンペーン：
available-couponsとcampaign-calendarを呼び出し、取得可能なクーポンと近日開催のキャンペーンをまとめて表示します。 - 呼び出しの追跡：MCP Tool の呼び出し状態と所要時間を確認できます。
- 安全なフォールバック：Token が設定されていない、または Tool が一時的に利用できない場合、明示的に表示された匿名化済みデモスナップショットを使用します。
実行前の準備
リアルタイム MCP 版では、リポジトリ内の Node サービスをローカルで実行する必要があります。開始前に、以下の環境を準備してください。
- Node.js 20 以上
- npm 10 以上
- マクドナルド MCP Token。デモデータだけを試す場合は不要です
まだインストールしたくない場合は、GitHub Pages オンラインデモにアクセスできます。このバージョンはフロントエンドのみのデモで、条件調整とセット計算を完全にサポートしていますが、リアルタイム MCP データではなく匿名化済みのメニュースナップショットを使用します。
インストールと設定
ステップ1：クローンと依存関係のインストール
ターミナルで以下のコマンドを実行します。リポジトリ URL のプレースホルダーを実際のアドレスに置き換えてください。
git clone <your-repository-url>
cd mcd-meal-mate
npm install
cp .env.example .envステップ2：環境変数の設定
プロジェクトのルートディレクトリにある .env ファイルを開き、MCP Token とサービスポートを記述します。
MCD_MCP_TOKEN=YOUR_MCD_MCP_TOKEN
PORT=8787MCD_MCP_TOKENは必須変数ではありません。設定するとリアルタイム MCP が有効になり、設定しない場合はデモデータを使用します。PORTは必須変数ではなく、デフォルト値は8787です。
MCP Token はサーバー側の環境変数にのみ設定し、フロントエンドコードに記述したり、公開リポジトリにコミットしたりしないでください。
ステップ3：開発環境の起動
npm run dev起動後、ブラウザで http://localhost:5173 にアクセスします。開発コマンドは Express API を実行し、Vite のホットリロードを有効にするため、画面とサーバー側ロジックのデバッグに適しています。
Token を設定しないデモモード
マクドナルド MCP Token がない場合は、プロダクション版をビルドして起動できます。
npm install
npm run build
npm startその後、http://localhost:8787 にアクセスします。このときページには「デモデータ」と明示され、メニュー、価格、キャンペーンには匿名化済みスナップショットが使用されます。
デモモードは、インタラクションの流れ、入力制約、3種類のセット結果を確認するのに適していますが、現在の店舗のリアルタイムな提供状況、価格、キャンペーンを示すものではありません。実際の利用時は、対象店舗から返されたデータを基準にしてください。
基本操作：3種類のセットプランを生成する
ステップ1：好みを選択
ワークスペースに入ったら、まず「バランス重視」などの好みを選択できます。好みはセットのスコアリングに反映されますが、結果は予算、カロリー、たんぱく質の目標による制約も受けます。
ステップ2：食事条件を入力
以下のサンプル条件から始めることができます。
都市：上海市
商業エリア / ランドマーク：人民広場
予算：35 元
上限カロリー：700 kcal
たんぱく質目標：35 gステップ3：計算結果を確認
サーバーは近隣の店舗を検索し、メニューと栄養データを読み込んだ後、3種類のプランを返します。
- プラン A：バランス重視。予算とカロリーの制限内で主食と軽食またはドリンクを組み合わせ、たんぱく質、1元あたりのたんぱく質、推薦理由を表示します。
- プラン B：たんぱく質強化。たんぱく質を優先して増やしながら、予算とカロリーの制限をできるだけ維持します。
- プラン C：おまかせセット。価格を抑えつつも十分な組み合わせを提供し、コストと選択効率をより重視する場面に適しています。
プランを比較するときは、総たんぱく質だけを見ないでください。1元あたりのたんぱく質、残り予算、残りカロリー、割引差額も合わせて、現在のニーズに最も合う結果を判断できます。
ステップ4：MCP 呼び出しチェーンを確認
「MCP 呼び出しチェーン」を展開すると、店舗、メニュー、栄養、割引、キャンペーンなどの Tool の状態と所要時間を確認できます。これにより、推薦がリアルタイムで返されたデータに基づくものか、Token の不足や Tool の利用不可によってデモスナップショットに切り替わったものかを判断できます。
よく使う開発コマンド
npm run dev：Express API と Vite のホットリロードを起動します。npm run build：フロントエンドをビルドし、サーバー側をコンパイルします。npm start：本番サービスを起動します。npm test：セットロジックと栄養解析のテストを実行します。npm run check：型チェック、サーバー側のコンパイルチェック、テストを順番に実行します。
栄養解析、メニューのマッピング、セットルールを変更した後は、少なくとも以下を実行することをおすすめします。
npm test
npm run checkこれにより、型エラー、コンパイル問題、セット制約や栄養解析に関するリグレッションを早期に発見できます。
Docker を使用したデプロイ
このプロジェクトは Docker ビルドに対応しています。まずイメージを作成します。
docker build -t mcd-meal-mate .次に、ホスト側の 8787 ポートをコンテナにマッピングし、環境変数から Token を渡します。
docker run --rm -p 8787:8787 \
-e MCD_MCP_TOKEN="YOUR_MCD_MCP_TOKEN" \
mcd-meal-mateコンテナの起動後は http://localhost:8787 にアクセスできます。MCD_MCP_TOKENを省略すると、アプリケーションはデモデータを使用します。
プロジェクト構成を理解する
このプロジェクトでは、React フロントエンド、Express サービス、MCP 呼び出し、栄養解析、セットプランニングをそれぞれ別のモジュールに分けています。
src/
App.tsx React ワークスペースとレスポンシブ操作
styles.css 編集部メニュー × レシートのビジュアルシステム
server/
index.ts Express API、入力検証、静的リソース
mcp.ts MCP JSON-RPC クライアント、Tool オーケストレーション、フォールバック
nutrition.ts 栄養テキスト解析、メニューマッピング、商品役割の識別
planner.ts セット制約、好みのスコアリング、3プランの選択
demo-data.ts 匿名化済みデモスナップショット
planner.test.ts 栄養とセットのテスト
shared/
types.ts フロントエンドとバックエンドの共有型server/mcp.tsは MCP JSON-RPC 通信、Tool のオーケストレーション、失敗時のフォールバックを担当します。server/nutrition.tsは栄養テキストとメニュー商品のマッピングを処理します。server/planner.tsはセット制約、好みのスコアリング、3プランの選択を実行します。フロントエンドとバックエンドで共通するデータ構造は shared/types.ts にあります。
バックエンドはネイティブの fetch を使用して、マクドナルド MCP Streamable HTTP Server と通信します。本番ビルドでは、同じ Express プロセスが API と静的ページを同時に提供し、メニューと栄養結果をメモリ内にキャッシュします。
高度な使い方と開発のヒント
まず制約条件から結果を確認する
期待したセットが得られない場合は、予算、上限カロリー、たんぱく質目標が厳しすぎないかを確認してください。セット作成ツールは複数の条件を同時に満たす必要があるため、目標同士が衝突する可能性があります。予算を適度に増やす、上限カロリーを引き上げる、またはたんぱく質目標を下げることで、実行可能な組み合わせを増やせます。
リアルタイムデータとデモスナップショットを区別する
デバッグ時は、ページに「デモデータ」と表示されているかを確認し、MCP 呼び出しチェーンも確認してください。Token がない場合、Tool が一時的に利用できない場合、またはフロントエンドのみの GitHub Pages 版を実行している場合、結果は匿名化済みスナップショットから取得される可能性があります。
サーバー側の認証情報を保護する
Token をブラウザ側に注入しないでください。このプロジェクトは Express サービスを通じて環境変数を読み込み、サーバー側から MCP を呼び出すことで、アーキテクチャ上 Token がフロントエンドに公開されるのを防いでいます。サーバーやコンテナにデプロイする際も、安全な環境変数管理方法で認証情報を注入してください。
プランニングロジックを変更したら完全なチェックを実行する
planner.ts、nutrition.ts、または共有型を変更した場合は、npm run checkを使用して型、コンパイル、テストのチェックを実行してください。プロジェクトにはセットと栄養解析のテストが用意されており、変更が既存の動作に影響していないかを確認できます。
連携資料を確認する
リポジトリの MCP_INTEGRATION.mdには、すべての Tool、呼び出しフロー、ビジネス上の価値、安全上の境界が記録されています。mcp-config.example.jsonには匿名化済みの設定例があり、workbuddy.mdには WorkBuddy 連携のコンテキストと再現可能な手順が含まれています。他の Agent や Skill と接続する際は、まずこれらのファイルを参照してください。
安全上の境界
- リポジトリには実際の Token、パスワード、アカウント認証情報を含めません。
- MCP Token はサーバー側の環境変数からのみ読み取ります。
- このプロジェクトは注文、決済、抽選、ポイント交換の Tool を呼び出しません。
- サーバー側でユーザー入力を保存せず、ユーザープロファイルも作成しません。
- 商品提供状況、価格、キャンペーンについてはマクドナルド公式チャンネルを基準とします。
- 推薦結果は医療、栄養、その他の専門的な助言を構成するものではありません。
まとめ
M餐搭子は、店舗検索、リアルタイムメニュー、栄養のマッチング、お得な情報、組み合わせのプランニングを、説明可能な一連の食事提案フローに統合します。MCP Tokenを設定すると、現在の店舗データを利用できます。Tokenがない場合でも、匿名化されたスナップショットを通じて完全なインタラクションを体験できます。
インストール完了後は、まずサンプル条件で3つのプランを検証し、続いてMCPの呼び出しチェーンでデータの取得元を確認できます。開発者は mcp.ts、nutrition.ts、planner.tsから読み始めることで、リアルタイムデータのオーケストレーション、栄養マッピング、制約計算の実装方法を理解できます。