spideymooon/McOracle

解決する問題

人々は人生の質問に対する楽しく斬新な答えを求めることがよくありますが、AI チャットボットは物事をでっち上げる傾向があります。そして、食べ物の推薦を求めると、メニュー項目や価格を発明するかもしれません。McOracle は、遊び心のある部分（ランダムオラクル）と事実の部分（実際のマクドナルド中国データ）を分離することでこれを解決します。ランダムに選ばれた中国風オラクルのことわざを提供し、次に公式のマクドナルド中国 MCP（モデルコンテキストプロトコル）を使用して実際の近くの店舗、実際に販売可能なメニュー項目、検証済みの価格を照会します。製品、価格、店舗を決して捏造しません。また、明示的に確認するまで注文を拒否し、確認後も注文を作成するだけで、自動支払いは行いません。

仕組み

McOracle は「スキル」（WorkBuddy アシスタント用のパッケージ化された機能）として構成されています。フローは次のとおりです：

1. 質問する — 「今日辞めるべき？」など、何でも質問します。
2. オラクルを引く — Python スクリプト（draw-oracle.py）が secrets モジュールを使用して、ローカルライブラリ（oracle-library.json）から 104 のオリジナル中国語オラクルのことわざの 1 つを選びます。抽選は状態ファイルにロックされ、解釈、推薦、カードに同じことわざが再利用され、明示的に再抽選を要求するまで続きます。
3. 実際の推薦を得る — 希望する場合、システムはマクドナルド中国公式 MCP ツール（query-nearby-stores、query-meals、calculate-price）を呼び出して近くの店舗を見つけ、実際の価格確認済みの「今日の必注」項目を表示します。価格はセント単位で、常に検証済みとして表示されるか、確認されていない場合は「価格未検証」とマークされます。
4. 運勢カードを生成する — Python スクリプト（generate-card.py）が固定 1200×1600 の PNG をレンダリングし、ダークレッドとゴールドのタロット風テンプレートを使用します。食品画像は利用可能な場合は公式製品画像 URL から取得されます。利用できない場合は、フォールバックのコンセプトイラスト（明確にラベル付け）またはエラーコード付きの劣化カードが使用されます。成功を偽装することはありません。
5. オプションの注文 — 「注文を確認」と言った場合のみ、システムは価格を再確認し、create-order MCP ツールを呼び出し、公式支払いリンク付きの実際の注文番号を返します。注文の作成は支払いではありません。システムは自動支払いをしません。

オラクルのみが必要な場合、フローはステップ 2 で停止します。位置情報を共有したり、MCP ツールを呼び出したりすることを強制されることはありません。

対象読者

このプロジェクトは次の人向けに設計されています：

• カジュアルな質問に対する楽しく迅速な「運勢」の答えを求め、共有できる視覚的に魅力的なカードを望む人。
• 実際の商用 API（マクドナルド中国 MCP）を安全で捏造のない方法で統合するスキルを試したい WorkBuddy デスクトップアシスタントのユーザー。
• 実際の MCP 統合、安全制御、テストを備えたスキルの参照実装を必要とするマクドナルド中国開発者チャレンジに参加する開発者。

これは予測ツールではなく、専門的なアドバイスの代替でもありません。オラクルは娯楽専用です。

ハイライト

• 真のランダム性 — オラクルの抽選は Python の secrets モジュールを使用して真のランダム選択を行い、モデルの即興ではありません。
• 常に検証済みの価格 — 推奨される各項目は実際の MCP クエリから取得されます。価格を検証できない場合、カードと会話には「価格未検証」と表示され、数字を発明しません。
• 厳格な注文安全 — ユーザーが明示的に確認するまで注文は作成されず、項目、店舗、価格の変更は以前の確認を無効にします。システムは自動支払いをせず、成功を偽装しません。
• オフライン対応のビジュアル — 運勢カードは Pillow でプログラム的にレンダリングされます。画像生成 API やキーは不要です。テンプレートは失敗せず、製品画像が欠落している場合は正直に劣化します（終了コード 2、ok=false）。
• 24/24 テスト合格 — 3 つのテストスイートがオラクルのランダム性/ロック、カード生成と劣化、注文安全状態遷移（モックのみ、実際の注文なし）をカバーしています。
• 明確な制限の文書化 — 注文から支払いまでの完全なループはエンドツーエンドで検証されていません。配送とクーポンのフローは README で未検証とマークされています。