spideymooon/McOracle

What it solves

People often want a fun, novelty answer to life questions, but AI chatbots tend to make things up — and if you then ask for a food recommendation, they may invent menu items or prices. McOracle solves this by separating the playful part (a random oracle) from the factual part (real McDonald's China data). It gives you a randomly drawn Chinese-style oracle saying, then uses the official McDonald's China MCP (Model Context Protocol) to query real nearby stores, actual sellable menu items, and verified prices. It never fabricates products, prices, or stores. It also refuses to place an order until you explicitly confirm, and even then it only creates the order — it does not auto-pay.

How it works

McOracle is structured as a "Skill" (a packaged capability for the WorkBuddy assistant). The flow is:

1. Ask a question — you ask anything, like "Should I quit today?"
2. Draw an oracle — a Python script (draw-oracle.py) uses the secrets module to pick one of 104 original Chinese oracle sayings from a local library (oracle-library.json). The draw is locked to a state file so the same saying is reused for the interpretation, recommendation, and card until you explicitly ask for a redraw.
3. Get a real recommendation — if you want it, the system calls McDonald's China's official MCP tools (query-nearby-stores, query-meals, calculate-price) to find a nearby store and show a real, price-checked "Today's Must-Order" item. Prices are in cents and are always shown as verified or marked "price not verified" if not confirmed.
4. Generate a fortune card — a Python script (generate-card.py) renders a fixed 1200×1600 PNG with a dark red-and-gold tarot-like template. The food image comes from the official product image URL when available; if not, a fallback concept illustration is used (clearly labeled) or a degraded card with an error code — it never fakes a success.
5. Optional order — only after you say "confirm order" (or equivalent) does the system re-check the price, call the create-order MCP tool, and return a real order number with an official payment link. Creating an order is not payment; the system never auto-pays.

If you only want the oracle, the flow stops at step 2 — you are never forced to share location or invoke MCP tools.

Who it's for

This project is designed for:

• People who want a fun, quick "fortune" answer to casual questions, with a visually appealing card to share.
• Users of the WorkBuddy desktop assistant who want to try a skill that integrates a real-world commercial API (McDonald's China MCP) in a safe, non-fabricating way.
• Developers participating in the McDonald's China developer challenge who need a reference implementation of a Skill with real MCP integration, safety controls, and tests.

It is not a prediction tool, nor a replacement for professional advice. The oracle is for entertainment only.

Highlights

• Real randomness — the oracle draw uses Python's secrets module for true random selection, not model improvisation.
• Verified prices, always — every recommended item comes from real MCP queries; if a price can't be verified, the card and conversation show "price not verified" instead of inventing a number.
• Strict order safety — no order is created until the user explicitly confirms, and any change to item, store, or price invalidates the previous confirmation. The system never auto-pays and never fakes a success.
• Offline-capable visuals — the fortune card is rendered programmatically with Pillow; no image-generation API or key is required. The template never fails, and missing product images degrade honestly (exit code 2 with ok=false).
• 24/24 tests passing — three test suites cover oracle randomness/locking, card generation and degradation, and order-safety state transitions (mock only, no real orders).
• Clear limitations documented — the full order-to-payment loop is not end-to-end verified; delivery and coupon flows are marked as unverified in the README.