AIチュートリアル

McButlerチュートリアル：マクドナルドMCPでおすすめ、栄養分析、店舗比較、団体注文を実現

本チュートリアルでは、McButlerのインストールと使い方を紹介します。6つのコマンドで、商品推薦、セットメニューの栄養分析、店舗ごとの総費用比較、複数人向けの団体注文設定、マック危険度スコアの計算、インタラクティブな寸劇の生成を行えます。

2026年10月24日約15分で読了

McButlerチュートリアル：マクドナルドMCPでおすすめ、栄養分析、店舗比較、団体注文を実現

McButlerとは

McButler（マクドナルド自動注文アシスタント）は、マクドナルド公式MCPを基盤とした注文支援プロジェクトです。単に価格だけでセットをおすすめするのではなく、予算、健康、時間、苦手な食材、個人の好みなどの条件を同時に扱うことを目指しています。

このプロジェクトはWorkBuddy Skillとして利用できるほか、ローカルCLIで内蔵のデモデータを実行することもできます。開発者はデータ解析とスコアリングのモジュールを再利用し、マクドナルドMCPが返すデータを独自のクライアントに取り込むことも可能です。

プロジェクトのリポジトリはGitHubにあり、マック劇場ではオンライン体験ページも提供しています。なお、McButlerは独立した応募作品であり、マクドナルドの公式製品ではありません。

6つの主な機能

1. 毎日のおすすめ

recommendは、節約、健康、人気の3モードに対応しています。それぞれ異なる並べ替えロジックを使っており、単に並べ替え項目を切り替えるだけではありません。

節約モード：価格の正規化値、割引率、100 kcalあたりの価格を総合し、少量の商品が総額の安さだけで上位に来るのを防ぎます。
健康モード：健康スコアとエネルギー適合度を組み合わせ、実測の栄養データがある候補を優先します。
人気モード：人気商品タグ、過去によく注文された情報、割引を総合します。

2. 健康チェック

healthはプロジェクトの技術的な中核です。栄養APIが単品データのみを提供するため、McButlerはまずセットの詳細を読み込み、セットをデフォルトの構成品に分解します。その後、各商品を栄養表と照合し、カロリー、たんぱく質、脂質、ナトリウム、カルシウムなどを集計します。

セット詳細
→ デフォルト構成を読み込む
→ 各商品の栄養データを照合
→ 栄養値を集計
→ 健康スコアと減点項目を計算

健康スコアは100点満点で、エネルギー範囲、たんぱく質、脂質のエネルギー比、ナトリウム、糖分・油分の負担、野菜・果物による加点を考慮します。詳しい計算式はリポジトリ内のreferences/model-spec.mdを参照してください。

3. 店舗の総コスト比較

storesでは、最寄り、最安、総合のいずれかの基準で店舗を選べます。総合モードは商品の価格だけでなく、往復距離、徒歩時間、待ち時間もコストに換算します。

総コスト = 商品価格
       + 距離コスト（往復 0.5 元/km）
       + 時間コスト（徒歩の往復時間 + 待ち時間）× 0.30 元/分

そのため、最寄りの店舗が必ずしも最もお得とは限りません。待ち時間は現在、MCPインターフェースが直接提供するデータではなく、ユーザーが入力するか推定する必要があります。

4. 団体注文の配分

bulkは、総務、人事、クラス、チームの注文シーンを想定しています。人数、1人あたりの予算、牛肉を食べない人、辛いものを食べない人などの条件でグループ分けして注文を組み立て、価格計算に続けて渡せるorderItemsを出力します。

結果には、グループ人数、セット数、合計金額、1人あたりの価格、節約額、1人あたりのカロリーなどが含まれます。ただし、「牛肉なし」は現在、商品名のキーワードによるフィルタリングに依存しているため、メニューに明記されていない成分を含む商品を確実に判別することはできません。

5. マックリスクスコア

creditは消費者信用のスコアカードを参考に、アカウントと個別注文について300～950点のマックリスクスコアを算出します。6つの評価項目は、支払い履行の安定性、消費リズム、予算管理、割引活用率、アカウント資産、味の多様性です。

結果には各項目のスコアとデータソースが表示され、説明できない合計点だけを出力することはありません。この機能は楽しみながら消費を分析するためのもので、実際の金融信用評価を示すものではありません。

6. マック劇場

theaterは、クーポン、マックリスクスコア、カロリーデータをもとに、5人の登場人物による注文をめぐる議論を生成し、単一ファイルのHTMLページとして出力します。生成されたページは追加の依存関係を必要とせず、ブラウザで直接開けます。

実行環境の準備

ローカルモードではPython 3.8以上だけが必要で、Python標準ライブラリのみを使用するため、サードパーティ製パッケージのインストールは不要です。オンラインMCPモードでは、利用可能なMCP Tokenが必要です。

リポジトリをクローンしてセルフテストを実行

git clone https://github.com/jouaaaaaa/mcd-self-butler.git
cd mcd-self-butler
python scripts/selftest.py

セルフテストには、健康チェック、3種類のおすすめ、アカウントと注文のマックリスクスコア、団体注文、店舗比較、テキストのみのマック劇場をカバーする9つのオフラインケースが含まれます。すべて合格すれば、ローカル環境とデモデータが正常に動作していることを確認できます。

方法1：WorkBuddyにSkillとしてインストール

リポジトリ内のSKILL.md、scripts/、references/を次のディレクトリに配置します。
```
~/.workbuddy/skills/mcd-self-butler/
```
WorkBuddyで「専門家・スキル・コネクター」に入り、「コネクター」「カスタムコネクター」「MCPを設定」の順に選択します。

マクドナルドMCPのStreamable HTTP設定を入力し、プレースホルダーを自分のTokenに置き換えます。

{
  "mcpServers": {
    "mcd-mcp": {
      "type": "streamablehttp",
      "url": "https://mcp.mcd.cn",
      "headers": {
        "Authorization": "Bearer あなたの_MCP_TOKEN"
      }
    }
  }
}

mcd-mcpコネクターを有効にし、自然言語で要望を伝えます。

次のようなリクエストから始められます。

「南京西路にいます。近くのマクドナルドでビッグマック3点セットを一番お得に買える店舗はどこですか？」
「このセットのカロリーと、より健康的な変更方法を教えてください。」
「部署30人の団体注文で、1人30元、5人は牛肉を食べません。」
「私のマックリスクスコアはいくつですか？」
「待ち時間が退屈なので、みんなに口論させてください。」

方法2：ローカルCLIを使う

ローカルCLIはリポジトリ内のデモスナップショットを使用するため、Tokenもネットワーク接続も不要です。6つの機能はすべてscripts/mcd_butler.pyから呼び出せます。

セットの栄養を確認

python scripts/mcd_butler.py health \
  --nutrition demo/nutrition.txt \
  --combo demo/combo_9900011128.json

このコマンドはセットを分解し、栄養表と照合して集計結果を生成します。出力には各構成品の栄養データ、セット合計、健康スコア、具体的な減点理由が含まれます。

健康的なおすすめを取得

python scripts/mcd_butler.py recommend \
  --menu demo/menu_1450118.json \
  --nutrition demo/nutrition.txt \
  --mode healthy \
  --meal lunch \
  --budget 45 \
  --top 5 \
  --details demo/details.json

--mode healthyは健康モード、--meal lunchは昼食シーン、--budget 45は予算を45元に制限、--top 5は上位5件の結果を返す指定です。

ほかの戦略を試す場合は、CLIが対応するモードに応じて節約または人気ロジックに変更できます。各モードは異なる価値関数を使うため、結果が大きく異なる場合があります。

マックリスクスコアを計算

python scripts/mcd_butler.py credit \
  --orders demo/orders.json \
  --account demo/account.json \
  --coupons demo/coupons.md \
  --nutrition demo/nutrition.txt

このコマンドは過去の注文、アカウント情報、クーポン、栄養データを組み合わせ、合計スコア、ランク、6項目の詳細を出力します。デモデータの例では771点で、ビッグマック級となりますが、実際のスコアは入力データによって変わります。

30人分の団体注文を設定

python scripts/mcd_butler.py bulk \
  --menu demo/menu_1450118.json \
  --nutrition demo/nutrition.txt \
  --headcount 30 \
  --budget 30 \
  --no-beef 5 \
  --no-spicy 4

ここでは30人、1人あたりの予算30元、牛肉を食べない人5人、辛いものを食べない人4人を設定しています。プログラムはグループごとにセットを選び、数量を計算できる注文項目を生成します。

店舗の総コストを比較

python scripts/mcd_butler.py stores \
  --stores demo/stores.json \
  --mode balanced

balancedモードは距離、時間、価格を総合します。自分のデータを使う場合は、待ち時間を明示的に入力または推定し、サンプル値をリアルタイムの結果として扱わないでください。

マック劇場を生成

python scripts/mcd_butler.py theater \
  --context demo/theater_context.json \
  --out theater.html

実行すると、現在のディレクトリにtheater.htmlが生成されます。ブラウザで直接開くと、登場人物の会話、逐語吹き出し、最終裁定を確認できます。

方法3：独自のMCPクライアントに接続

開発者は2種類の統合方法を利用できます。

元のレスポンスを保存：MCPクライアントで店舗、メニュー、詳細、栄養、注文、クーポンなどのツールを呼び出し、demo/のサンプルと同じ用途のファイルとして元のレスポンスを保存し、CLIに渡します。
モジュールを直接呼び出す：scripts/lib/内の関数をインポートし、MCPが返すPythonのdictを直接渡します。

データ読み込み層のmcdata.pyは、{"success": true, "data": ...}形式のMCP元レスポンスと、手動で簡略化した形式の両方を受け付けます。そのため通常は、ツールのレスポンスを手作業で整形せず、そのまま保存できます。

プロジェクトのアーキテクチャを理解する

McButlerの処理フローは、次の4層にまとめられます。

クライアント層：WorkBuddy Agentまたはその他のMCPクライアントがリクエストを送信します。
MCPサービス層：店舗、メニュー、詳細、栄養、価格計算、クーポン、ポイント、注文などのデータを取得します。
データ読み込み層：mcdata.pyが展開、正規化、名前のあいまい一致を担当します。
ビジネスモデル層：health.py、credit.py、bulk.py、recommend.py、theater.pyが、それぞれスコアリング、注文配分、おすすめ、台本生成を実行します。

mcd_butler.pyは統合CLIのエントリーポイントで、MarkdownまたはJSONを出力できます。人が確認する用途にも、後続プログラムへの接続にも適しています。

高度な利用のコツ

セットの詳細を優先して提供する

栄養インターフェースは単品データのみを提供します。セットを分析する際は、セットの詳細も同時に渡し、デフォルト構成に基づいて各商品を照合させるのがおすすめです。栄養データが1件も照合できなかった場合、プロジェクトは結果を捏造せず、健康スコアを「—」と表示します。

シーンに応じておすすめモードを選ぶ

予算が厳しい場合は節約モードを使い、100 kcalあたりの価格を確認します。
減量やトレーニングでは健康モードを使い、たんぱく質、脂質、ナトリウムの減点内訳も確認します。
人気商品と自分の過去の好みを組み合わせたい場合は人気モードを使います。

MCP 生データを保存して再現可能にする

おすすめ結果をデバッグする際は、その時点の MCP 生レスポンスを保存することをおすすめします。これにより、後からメニュー、価格、提供状況が変わっても、同じデータを使って計算過程を再現できます。

データ品質を区別する

McButler では、データを次の3段階で oznaします：

実測：セット内容を分解し、各項目を集計して得たデータ。
公式：単品の栄養成分表から直接取得したデータ。
推定：完全なデータがない場合の概算で、明示的に表示されます。

自動化された結果表示では、これらのマークを削除しないでください。データの出所と信頼度を区別するために使用されます。

業務上の境界を確認する

現在の団体注文機能は、企業向け団体注文の割引ルールを重ねて最適化する機能にはまだ対応していません。「牛肉を食べない」は主に料理名のキーワードで判定され、待ち時間も明示的に入力する必要があります。実際の注文に利用する前に、マクドナルド公式の案内で価格、提供状況、商品の成分を再度確認してください。

栄養分析は参考情報であり、医療、栄養その他の専門的な助言を構成するものではありません。疾病、妊娠中、または子どもの食事に関わる場合は、専門家に相談してください。

まとめ

McButler は、MCP の生データを説明可能な消費判断へ変換する方法を示します。セット内容の分解、栄養スコア、店舗までの総費用から、団体注文のグループ分け、ユニークなスコアリング、インタラクティブなコンテンツまで、統一された CLI または WorkBuddy Skill から利用できます。

初めて試す場合は、まず python scripts/selftest.py を実行し、その後 health、recommend、stores の順に試してください。オフライン処理を確認してから、MCP Token を設定してリアルタイムデータに接続します。