McOracleとは
McOracle（マック門の神託）は、Skillのみで構成されたAI神託体験です。ユーザーは任意の質問を入力でき、システムは104件のオリジナル中国語神託から、Pythonのsecretsモジュールを使って真の乱数で1件の回答を抽選します。その後、マクドナルド中国公式MCPを利用して実在する店舗、販売可能なメニュー、価格を照会し、「マック門啓示録」と運命カードを生成します。
プロジェクトの中核原則は、神託はランダムでよいが、商品と価格は必ず実在のものにすることです。神託はリポジトリ内の固定データから取得し、モデルがその場で創作することはありません。商品、店舗、価格にはMCPが返したデータだけを使用し、価格を確認できない場合は「価格未確認」と表示します。ユーザーが明確に確認する前に、システムが注文を作成することはありません。また、注文の作成は支払いの成功を意味しません。
完全なワークフロー
McOracleの標準的な流れは、次の5段階で構成されます。
- ユーザーが質問を入力するか、マック門の神託を直接リクエストします。
scripts/draw-oracle.pyがreferences/oracle-library.jsonから神託を真の乱数で抽選し、今回の結果をロックします。- ユーザーが商品推薦を希望する場合、SkillがMCPを通じて近隣店舗、販売可能なメニュー、商品の詳細を照会します。
calculate-priceで価格を確認し、その後scripts/generate-card.pyで1200×1600 PNGの運命カードを生成します。- ユーザーが「注文を確定」と明確に返信した場合に限り、システムが注文情報を再確認して
create-orderを呼び出します。その後も、ユーザー自身が公式入口から支払う必要があります。
ユーザーが神託の抽選だけを希望する場合、処理は第1段階で終了します。位置情報を強制的に求めることも、MCPを呼び出すこともありません。
主要モジュールとプロジェクト構成
プロジェクトは主に次のモジュールで構成されています。
- Oracle Engine：
draw-oracle.pyと神託ライブラリが、ランダム抽選、結果のロック、再抽選の制御を担当します。 - Recommendation Engine：
recommendation-rules.mdが神託のタグを商品カテゴリーに対応付け、実際のメニューと予算を組み合わせて推薦します。 - MCP Adapter：
SKILL.mdとMCP_INTEGRATION.mdが、ツール呼び出しの順序、パラメータ規則、例外処理を説明します。 - Card Generator：
generate-card.pyがPillowを使ってワインレッドとゴールドのテンプレートをプログラムで描画し、公式商品画像を合成します。 - Order Safety Controller：
validate-order.pyがステートマシンで確認フローを制御し、未確認のまま注文されることを防ぎます。 - Skill Orchestrator：
SKILL.mdが起動条件、実行フロー、出力形式、安全要件を定義します。
神託ライブラリには104件のオリジナルコンテンツが含まれ、肯定型、否定型、待機型、行動型、逆転型、幸運型、ユーモア型、マック門専用型の8カテゴリーをカバーしています。各神託には、番号、本文、カテゴリー、タグ、解釈、行動ヒント、推薦タグ、ビジュアルテーマが含まれます。
Python依存関係のインストール
プロジェクトにはPython 3.9以降が必要です。開発環境ではPython 3.13を使用しています。正式な運命カードはPillowでレイアウトするため、Pillowをインストールする必要があります。神託の抽選と注文安全スクリプト自体は、画像生成APIに依存しません。
git clone <your-repo-url> McOracle
cd McOracle
pip install PillowmacOSまたはLinuxで実行する場合は、中国語を表示できるフォントがシステムに存在することを確認してください。スクリプトは候補リストから利用可能なフォントを選択します。正式なカード生成に画像生成API Keyの設定は必要ありません。
WorkBuddy Skillとしてインストール
- プロジェクトを取得して依存関係をインストールします。
McOracle/ディレクトリ全体を、ユーザー用Skillディレクトリ~/.workbuddy/skills/McOracle/、または現在のワークスペースの{workspace}/.workbuddy/skills/McOracle/にコピーします。- WorkBuddyのコネクターでマクドナルド中国MCPを有効にします。
- 会話を開き、「マック門の神託」「おみくじを引いて」「今日の神託」などの表現でSkillを起動します。
「退職すべき？」のように、普通の質問を直接入力することもできます。完全なフローを実行したい場合は、「今日のマック門運命を完全版で」と伝えてください。WorkBuddyのバージョンによってSkill登録メタデータの要件が異なる場合があるため、使用中のバージョンに応じて必要な設定を追加してください。
マクドナルド中国公式MCPの設定
実在する店舗、メニュー、価格を使った推薦の前に、公式MCP利用ガイドでTokenの申請方法を確認し、WorkBuddyの「コネクター」→「カスタムコネクター」→「MCPを設定」で設定を入力してください。
{
"mcpServers": {
"mcd-mcp": {
"type": "streamablehttp",
"url": "https://mcp.mcd.cn",
"headers": {
"Authorization": "Bearer YOUR_MCP_TOKEN"
}
}
}
}YOUR_MCP_TOKENを自分のTokenに置き換え、Tokenをリポジトリにコミットしないでください。プロジェクトで使用する主なツールには、now-time-info、query-nearby-stores、query-meals、query-meal-detail、calculate-priceがあります。注文関連のcreate-orderは、ユーザーが明確に確認した後にのみ呼び出せます。
初回利用：神託を抽選する
プロジェクトのルートディレクトリで次のコマンドを実行すると、具体的な質問に対する神託を1件抽選できます。
python scripts/draw-oracle.py --question '今日は何を食べる？'抽選結果はscripts/_oracle_state.jsonに書き込まれ、今回のセッションでロックされます。これにより、その後の解釈、推薦、運命カードはすべて同じ神託を参照し、複数回読み込んだことで意図せず変わることがありません。
現在ロックされている結果を確認する、または再抽選を要求するには、次のコマンドを使用します。
python scripts/draw-oracle.py --peek
python scripts/draw-oracle.py --redraw--redrawは、ユーザーが明確に再抽選を求めた場合にのみ使用してください。解釈や運命カードの生成時に、システムが自動的に神託を変更することはありません。
運命カードの生成
運命カードは固定のワインレッドとゴールドのビジュアルテンプレートを使用し、画像生成サービスには依存しません。背景には深いワインレッドのグラデーション、金色の二重枠、中央の発光する円環、星の装飾を配置します。文字はPillowでプログラム的にレイアウトし、中国語、番号、価格の文字化けやはみ出しを防ぎます。
MCPが公式商品画像を返し、価格がcalculate-priceで確認済みの場合は、次のように正式なカードを生成できます。
python scripts/generate-card.py \
--oracle-id 'NO.021' \
--answer '深夜に決断してはいけない。' \
--interpretation '午前1時のあなたと午前10時のあなたは、同じ人ではない。' \
--item-name 'グリルチキンバーガー3点セット' \
--item-price 34.5 \
--price-verified \
--item-image-url 'https://menu-img.mcd.cn/.../MS_9900005462_320.png' \
--out examples/oracle-card-NO021-official.png正式な出力サイズは1200×1600 PNGです。--price-verifiedは、価格が実際にMCPで確認済みの場合にのみ使用できます。例示価格をリアルタイム価格として扱うことはできません。
画像素材のフォールバック戦略
商品のメインビジュアルは、次の優先順位で処理します。
- まず
query-mealsまたはquery-meal-detailが返す公式商品画像を使用します。 - 公式画像がない場合は、
--item-imageで独立したコンセプトイラストを指定できます。その場合はコンセプトイラストであることを明記します。 - 外部素材が利用できない場合、スクリプトは内蔵のハンバーガー、フライドポテト、コーラのプログラムイラストを使用します。
- すべての素材が利用できない場合は、「商品ビジュアル素材なし」のフォールバックカードを出力し、終了コード2とJSONの
ok=falseで失敗を報告します。
プロジェクトは空の円環を商品に見せかけることも、コンセプトイラストを公式実写画像として表示することもありません。
会話で完全な体験を行う
典型的な会話は次のようになります。
あなた：マック門の神託、今日は退職に向いていますか？
McOracle：神託を抽選し、本文、解釈、行動ヒント、重要事項の注意を返します。今日のおすすめ商品も提示できます。
あなた：注文の準備をして
McOracle：店舗、受け取り方法、商品、価格で構成された注文概要を表示します。確認してください。
あなた：注文を確定
McOracle：価格を再確認してからcreate-orderを呼び出し、実際の注文番号と公式決済入口を返します。「見てみる」「おすすめして」「注文の準備をして」は最終確認には該当しません。ユーザーが「注文を確定」と明確に返信した後にのみ、注文フローを続行できます。
注文の安全機構
注文安全コントローラーは、注文の状態と重要なパラメータを確認します。店舗、商品、数量、価格、受け取り方法のいずれかが変更された場合、以前の確認は無効になります。システムは概要を再表示し、確認を求めなければなりません。
プロジェクトが自動的に支払うことはなく、注文番号や注文成功メッセージを偽造することもありません。注文作成後も公式決済フロー外の支払い待ち状態であり、ユーザーは公式ページから自分で支払いを完了する必要があります。店舗受け取りとドライブスルーにはorderType=1を使用し、デリバリーにはorderType=2と配送先住所が必要です。2種類のパラメータを混用することはできません。
注文安全デモを単独で実行
注文スクリプトには純粋なロジックによるMockデモが用意されており、実際の注文は作成しません。
python scripts/validate-order.py demoこのデモは、実際のMCPに接続する前に確認ルールをチェックするのに適しています。未確認では注文できないこと、曖昧な表現は確認とみなされないこと、注文パラメータの変更で確認が無効になること、注文作成は支払い成功を意味しないことを確認できます。
テストの実行
プロジェクトには3つのテストセットがあり、神託ロジック、運命カード生成、注文安全ステートマシンをそれぞれカバーしています。
python tests/test-oracle.py
python tests/test-card.py
python tests/test-order-safety.pyREADMEに記録された現在の結果は、24項目すべて合格です。神託テストでは104件のデータ、番号の一意性、8カテゴリー、ランダム性、状態ロックを検証します。運命カードテストでは、実際のPNG、サイズ、素材不足時のフォールバック、未確認価格の分岐、長文レイアウトを検証します。注文テストはMockを使って安全な状態遷移を検証し、実際のMCPを呼び出すことも、注文を作成することもありません。
高度な利用上の推奨事項
娯楽としての神託と現実の判断を区別する
神託は娯楽と気づきのためのものであり、未来の予測ではありません。また、現実の判断に取って代わるものでもありません。退職、投資、健康、法律、財務に関する問題では、客観的な条件を考慮し、専門家に相談してください。
確認済み価格と例示価格を常に区別する
MCPが返す価格の単位は「分」であり、表示前に100で割る必要があります。また、価格には有効期間があります。リアルタイムの確認が完了していない場合は「価格未確認」と表示し、カードや会話で例示価格をリアルタイム価格の代わりに表示しないでください。
認証情報とプライバシーを管理する
TokenとAPI Keyはコネクター設定または環境変数からのみ読み込み、ソースコードに記述したり、リポジトリにコミットしたりしないでください。プロジェクトはユーザーのプライバシー、Cookie、注文番号、個人の認証情報を保存すべきではありません。IssueやPull Requestを提出する際も、これらの機密情報を含めないでください。
現在の機能範囲を理解する
店舗照会、メニュー照会、商品詳細、価格計算、公式画像のダウンロード、運命カード生成には、すでに実際の検証記録があります。一方、完全な「注文・支払い・状態再照会」の一連の流れ、マックデリバリーのフロー、クーポンの取得と利用確認については、まだ完全な実地検証が済んでいない部分があります。そのため、エンドツーエンドで検証に成功済みであるかのように説明することはできません。
おわりに
McOracleは、固定された神託データ、真のランダム抽選、公式MCPのリアルタイムメニュー、プログラムによる画像レイアウトを組み合わせた、楽しいWorkBuddy Skillです。神託スクリプトだけを使うことも、MCPを設定して店舗、メニュー、価格のおすすめをさらに得ることもできます。実際に利用する際は、次の3つの原則を必ず守ってください。神託は娯楽目的で使用すること、価格は必ずリアルタイムで確認すること、ユーザーが明確に確認するまで注文を作成しないこと。
運命はランダムでも、価格は正確でなければならない。