メインコンテンツへ移動
AIチュートリアル

マックカードコレクター入門：WorkBuddyでマクドナルドのカードを引き、栄養情報を確認して安全に注文する

このチュートリアルでは、マックカードコレクターをインストールして使用する方法を紹介します。マクドナルド中国のMCPからリアルタイムのメニュー、価格、栄養情報を取得し、メニューをSSR、UR、Rカードに変換します。コレクションブック、ポイント、複数回抽選、オフラインのコマンドラインテスト、二段階確認による注文フローも体験できます。

約19分で読了
マックカードコレクター入門：WorkBuddyでカードを引き、栄養情報を確認して安全に注文する

プロジェクト概要

マックカードコレクター（mcd-gacha-collector）は、マクドナルド中国 MCP を基盤に開発された WorkBuddy Skill です。マクドナルドの商品を抽選・収集できるカードに変換し、カード上に価格、カロリー、タンパク質、ナトリウム含有量、健康度を表示します。

プロジェクトは MCP からリアルタイムのメニュー、栄養データ、店舗、価格を取得し、ローカルの Python エンジンで健康度の評価、レアリティ分類、予算フィルタリング、重み付き抽選を行います。購入可能な商品を引いた場合は、価格確認と再確認を経て、実際の注文を作成することもできます。

リポジトリの栄養データは約 160 品目をカバーしており、現在のウェブ版カードプールには実際のメニュー情報から生成された 53 枚のカードが含まれています。本プロジェクトはコンテスト出品作品であり、マクドナルドの公式製品ではありません。

マックカードコレクターのデスクトップ初期画面

主な機能

  • 予算抽選：「50 元以内で 1 枚引く」などの自然言語による要求に対応し、先に価格で絞り込んでから重み付き抽選を行います。
  • 栄養と健康度：MCP が返すデータに基づいて 0 から 100 の健康度を計算し、カロリー、タンパク質、脂質、ナトリウムなどを表示します。
  • SSR、UR、R のランク：レアリティは健康度の分布によって決まり、手動で指定されていません。相対的なランク付けにより、店舗ごとに異なるメニュー構成へ対応できます。
  • ローカルコレクション：抽選記録は ledger.json に保存され、重複カードの獲得回数を累計できます。平均カロリーと平均健康度の集計も可能です。
  • ポイントシステム：Skill では 4 時間ごとに抽選 1 回分が自動回復します。ウェブ版では 60 秒のクールダウン付き手動更新を採用しています。
  • 実際の注文：まず MCP で価格を確認し、ユーザーに明確な確認を求めた後、最後に create-order を呼び出します。
  • オフライン体験：リポジトリにはサンプルデータが付属しており、MCP Token を設定しなくても抽選、コレクション、HTML カード表示をテストできます。
  • サードパーティ依存なし：コアスクリプトは Python 標準ライブラリを使用し、Python 3.8 以上が必要です。

抽選の評価と注文の仕組み

動作フロー

プロジェクトは「データ取得は MCP、計算はコード、表現は Agent」という設計思想に従っています。WorkBuddy Agent がユーザーの意図を理解し、マクドナルド MCP が実際の業務データを提供し、gacha.py が決定的な計算を実行します。

ユーザーが抽選、栄養情報の確認、注文を依頼
→ WorkBuddy Agent がマクドナルド MCP を呼び出す
→ 時刻、店舗、メニュー、価格、栄養データを取得
→ gacha.py が健康度とレアリティを計算し、抽選を実行
→ render.py がカードまたはコレクションページを生成
→ ユーザーが購入を選択
→ calculate-price で価格を確認
→ ユーザーが再確認
→ create-order で注文を作成

金額、健康度、レアリティを大規模言語モデルに暗算させることはありません。価格は MCP が返し、評価と抽選は Python コードが実行するため、計算のぶれやエラーのリスクを低減できます。

開始前の準備

  • Python 3.8 以上をインストールします。
  • WorkBuddy をインストールし、利用できる状態にします。
  • アクセス可能なマクドナルド中国 MCP Token を用意します。オフライン例を実行するだけなら Token は不要です。
  • WorkBuddy がユーザーの Skill ディレクトリを読み取れることを確認します。

方法 1：オンラインで直接体験

インターフェースと抽選デモだけを確認したい場合は、マックカードコレクターのオンラインページを開いてください。ページは IP アドレスから都市を取得し、店舗検索機能を呼び出して近隣の店舗を選択します。住所を手入力する必要はありません。

マックカードコレクターのモバイル初期画面

デプロイ環境の制約により、公開ウェブページに個人の MCP Token を注入することはできません。オンライン版は位置情報、店舗、カードインターフェースの体験に適しています。実際の注文は、ローカルバックエンドまたはコネクターを設定した WorkBuddy Skill で行う必要があります。

方法 2：WorkBuddy にインストール

ステップ 1：リポジトリをクローン

git clone https://github.com/YOUR_GITHUB_USER/mcd-gacha-collector.git
cd mcd-gacha-collector

README のリポジトリアドレスにはプレースホルダーが使用されています。実際に操作する際は、YOUR_GITHUB_USER をリポジトリ所有者名に置き換えるか、GitHub ページに表示されるクローンアドレスを直接コピーしてください。

ステップ 2：マクドナルド MCP Token を申請

マクドナルド MCP オープンプラットフォームにアクセスし、携帯電話番号でログインします。コンソールでサービスを有効化して Token をコピーしてください。Token は機密認証情報です。公開リポジトリに書き込んだり、Git の履歴にコミットしたりしないでください。

ステップ 3：MCP コネクターを設定

  1. WorkBuddy 左側の「エキスパート・Skill・コネクター」を開きます。
  2. 「コネクター」に移動し、右上の「カスタムコネクター」を選択します。
  3. 「MCP を設定」を選択します。
  4. リポジトリにある mcp-config.example.json の内容をコピーします。
  5. その中の ${MCD_MCP_TOKEN} を実際の Token に置き換えるか、環境変数から注入します。
  6. 設定を保存し、コネクターを有効にします。

Token の管理には環境変数の使用を推奨します。どの方法を採用する場合でも、実際の認証情報を含む設定ファイルをバージョン管理システムにコミットしないでください。

ステップ 4：Skill をコピー

macOS または Linux で実行します。

cp -r skills/mcd-gacha-collector ~/.workbuddy/skills/

Windows の WorkBuddy ユーザー Skill ディレクトリは次のとおりです。

%USERPROFILE%\.workbuddy\skills\

コピー時は、SKILL.md、コアスクリプト、参考ドキュメント、リソースファイルを含む mcd-gacha-collector ディレクトリ全体を保持してください。

ステップ 5：インストールを確認

WorkBuddy のダイアログに戻り、次を入力します。

マクドナルドのカードを 1 枚引いて

Skill がメニューと栄養ツールを呼び出し、レアリティ、価格、カロリーを含むカード結果を返せば、インストールと MCP 接続は有効になっています。

基本的な使い方

予算内でカードを 1 枚引く

50 元以内で 1 枚引いて

Skill は現在の店舗で利用可能なメニューと栄養データを取得し、価格が 50 元以下の商品をフィルタリングしてから、重み付き抽選を行います。README の実測例では、UR サンシャインレモン紅茶 M サイズが選ばれ、価格は 10 元、カロリーは 117 kcal、健康度は 63.4 でした。

実際の結果は店舗のメニュー、リアルタイム価格、カードプールの構成、ランダム抽選の結果によって異なります。そのため、例にある商品や価格を固定の出力とみなさないでください。

10 回連続で引く

10 連して

ポイントが十分にある場合、Skill はカードを 10 枚連続で抽選し、より詳細な形式で結果を表示します。ポイントが不足している場合は、不足している回数と次回の回復時刻を説明します。

コレクションを確認

私のコレクションは？

コレクションデータはローカルの ledger.json によって集計されます。結果には、収集済みカード数、SSR・UR・R の枚数、重複回数、平均カロリー、平均健康度などが含まれます。

栄養情報を検索

ビッグマックのカロリーは？

Skill は list-nutrition-foods を通じて商品を検索します。README の例では、ビッグマックは 513 kcal、タンパク質 27 g、脂質 26 g、ナトリウム 961 mg、健康度 32.2 で、R ランクに分類されています。栄養情報は、その時点で MCP が返す公式データを基準にしてください。

近くの店舗を検索

近くのマクドナルドは？

システムはデフォルトでまず IP 位置情報を使用して都市を取得し、その後 query-nearby-stores を呼び出して、MCP が返す距離フィールドで並べ替えます。実測では店舗 API の緯度・経度が 0.0 になる場合があるため、プロジェクトはこれらの座標を使って独自に距離を計算しません。

残りのポイントを確認

モバイル全体画面

あと何回カードを引ける？

Skill はローカル台帳のポイントを読み取り、現在利用可能な回数と次回の自動回復時刻を返します。ここでのポイントは本プロジェクト独自のローカルなゲーム化機能であり、マクドナルド公式のポイントアカウントとは関係ありません。

安全に実際の注文を作成

好きなカードを引いた場合や直接購入を依頼した場合でも、プロジェクトはすぐに注文を作成せず、必ず再確認の手順を採用します。

  1. 店舗と購入可能な商品またはセットを選択します。
  2. calculate-price を呼び出して、リアルタイム価格と利用可能な受け取り方法を取得します。
  3. 有効期限 15 分の使い捨て quoteToken を生成します。
  4. 価格確認の結果をユーザーに表示し、明確な確認を待ちます。
  5. バックエンドで Token を検証し、検証に成功したら create-order を呼び出します。
  6. 注文番号と支払いリンクを返します。

create-order には必ず takeWayCode を含める必要があります。この値は calculate-price が返す takeWayList から取得してください。自分で推測したり省略したりすると、リクエストが 400 を返す可能性があります。

実測メニューでは単品を単独で注文できない場合があります。README に記録された 96 枚の単品カードはすべて canWithOrder が false であるため、実際に注文できる中心となるのは 18 枚のセットカードです。単品カードはコレクションと栄養情報の表示に利用できます。

Token 不要のコマンドライン体験

リポジトリには sample_data が付属しており、完全な抽選ロジックをオフラインで検証できます。スクリプトディレクトリに移動します。

cd skills/mcd-gacha-collector/scripts

カードプールの分布を確認

python gacha.py sample_data --inspect --budget 50

このコマンドは 50 元の予算条件でサンプルカードプールを確認し、抽選対象となるカードとレアリティ分布を確認するのに適しています。

単発抽選と 10 連

python gacha.py sample_data --draw 1 --budget 50 --ledger /tmp/ledger.json
python gacha.py sample_data --draw 10 --budget 50 --ledger /tmp/ledger.json

--ledger で台帳のパスを指定します。同じファイルを継続して使用すると、ポイントとコレクション記録を保持できます。

コレクション統計を確認

python gacha.py sample_data --collection --ledger /tmp/ledger.json

確率分布をシミュレーション

python gacha.py sample_data --simulate 100 --seed 42

サンプルの目標分布は SSR 5%、UR 20%、R 75% です。--seed 42 を指定するとランダム結果を再現できるため、デバッグやアルゴリズム変更前後の出力比較に適しています。

カード HTML をレンダリング

python render.py /tmp/ledger.json --out /tmp/cards.html --last-draw 1

レンダラーは台帳データを単一ファイルのHTMLとして出力し、ブラウザで最後に抽出したカードを確認できるようにします。

セルフテストの実行

python selftest.py

コアロジックには105項目のセルフテストが含まれています。スコア、ポイント、レアリティ、またはカード抽選コードを変更した後は、このコマンドを再実行してください。

ヘルス度とレアリティを理解する

商品のヘルス度は、次の3つの指標を加重して計算します。

  • たんぱく質密度：35%。
  • 低カロリー指標：40%。
  • 低ナトリウム指標：25%。

レアリティには相対的なランク付けを採用し、現在のデータ分布に基づいて分位点のしきい値を設定します。これにより、ある店舗にコーヒーなどの高スコア商品がないためにSSRがまったく存在しない、といった事態を避けられます。READMEの実測カードプールでは、分位点を適用した結果、SSR 3枚、UR 7枚、R 13枚となりました。

セットメニューには、商品の重み付けをそのまま適用しません。セットメニューは総カロリーが本来高くなるためです。プロジェクトではセットメニューに独自のアルゴリズムを採用し、たんぱく質密度40%、ナトリウム密度35%、カロリー負荷25%として、分位点のしきい値も個別に計算します。

ヘルス度とレアリティは娯楽目的の比較にのみ使用するものであり、医療、栄養、その他の専門的な助言を構成するものではありません。

高度な開発とトラブルシューティングのヒント

MCP栄養データを正しく解析する

list-nutrition-foodsが返すdataは、JSON配列ではなくCSV文字列の場合があります。プロジェクトには専用のparse_nutrition_csv解析ロジックが用意されています。クライアントを拡張する際は、常にリストであると決めつけないでください。

structuredContentの封筒を開く

MCPの業務データはstructuredContent.data内に格納されている場合があり、その値も辞書、リスト、文字列のいずれかである可能性があります。レスポンスを処理する際は、まず外側の封筒を開き、その後で実際の型に応じて解析器を振り分けてください。

フロントエンドとバックエンドのアルゴリズムを一致させる

Web版ではビルド時に計算します。tools/gen_web_data.pyでデータを生成し、web/build.pyでデータを単一ファイルのページにインライン化します。フロントエンドでスコアリングアルゴリズムを再実装しないため、両者の結果が一致しなくなる問題を減らせます。

データ生成、フィールドマッピング、またはWebページテンプレートを変更した後は、tools/parity_check.pyを実行できます。リポジトリには、HTML、JavaScript、カードプールの分布、フィールドの整合性を対象とした99項目の一致性チェックが記録されています。

バックエンドの店舗解析を検証する

バックエンドはserverディレクトリにあり、Python標準ライブラリでIP位置情報の取得、MCPクライアント、注文インターフェースを実装しています。店舗解析ロジックには別途15項目のアサーションがあります。105項目のSkillセルフテストと99項目のWeb検証を合わせると、プロジェクトには合計219項目のアサーションが記録されています。

店舗の緯度・経度に依存しない

READMEの実測結果によると、query-nearby-storesが返す緯度・経度フィールドは、すべて0.0になる場合があります。より確実な方法は、まずIPから都市を取得し、その後、都市名と場所のキーワードで検索して、インターフェースが返すdistanceで並べ替えることです。

表示用カードと注文可能なカードを区別する

メニューに表示される商品が、必ずしも単品で購入できるとは限りません。購入機能を構築する際は、MCPが返す注文可能状態を確認し、合法的なセットメニューを優先して案内してください。カードとして表示できるからといって、注文を作成できると判断してはいけません。

Tokenと注文操作を保護する

  • Tokenは環境変数から注入することを優先する。
  • 実際のTokenをmcp-config.example.jsonに書き込まない。
  • 注文前には必ず再見積もりを行う。
  • 使い捨てのquoteTokenとその有効期限を検証する。
  • ユーザーが明確に確認した後にのみcreate-orderを呼び出す。
  • テスト注文は慎重に扱い、速やかなキャンセルが必要か確認する。

どのようなユーザーに適しているか

  • マクドナルドMCPの呼び出し手順を学びたい開発者。
  • WorkBuddy Agent Skillを開発したい実践者。
  • カード収集、カード抽選、図鑑機能が好きなユーザー。
  • 軽い方法で商品のカロリーと栄養構成を比較したい会社員や学生。
  • MCPデータの解析、再見積もり、安全な注文手順を研究したいエンジニア。

まとめ

マックカードコレクターは、メニュー検索、栄養比較、カード抽選・収集、実際の注文を一連の流れにまとめています。初めて使う場合は、まずオンラインページで画面を確認し、その後サンプルデータでコマンドラインテストを実行するとよいでしょう。ロジックに問題がないことを確認したら、マクドナルドMCP Tokenを設定し、SkillをWorkBuddyにインストールします。

実際に使用する際は、データ形式の違い、店舗インターフェースの制限、セットメニューの注文可能状態、再確認の仕組みに特に注意してください。価格、提供状況、商品情報はすべて、マクドナルド公式チャネルの最新結果を基準としてください。