McOracle McDonald’s Oracle Tutorial: From Random Oracles to Real Menu Recommendations and Safe Ordering

What Is McOracle

McOracle (McDonald's Oracle) is an AI oracle experience delivered entirely as a Skill. Users can ask any question, and the system uses Python's secrets module to draw one answer at random from 104 original Chinese oracles. It then combines this with real store, available menu, and pricing data queried through McDonald's China official MCP to generate a "McDonald's Revelation" and a destiny card.

The project's core principle is: the oracle may be random, but products and prices must be real. Oracles come from fixed data in the repository and are not improvised by the model; meals, stores, and prices use only data returned by MCP; when a price has not been verified, the system displays "Price not verified." Before the user explicitly confirms, the system will not create an order, and creating an order does not mean payment has succeeded.

Complete Workflow

McOracle's standard flow has five stages:

1. The user asks a question or directly requests a McDonald's oracle.
2. scripts/draw-oracle.py randomly draws an oracle from references/oracle-library.json and locks the result for the current session.
3. If the user wants a meal recommendation, the Skill queries nearby stores, available menus, and meal details through MCP.
4. The system verifies the price with calculate-price, then uses scripts/generate-card.py to generate a 1200×1600 PNG destiny card.
5. Only after the user explicitly replies "Confirm order" does the system recheck the order details and call create-order. The user must still complete payment independently through the official entry point.

If the user only wants to draw an oracle, the flow ends at the first stage. The system will not request location information or call MCP.

Core Modules and Project Structure

The project mainly consists of the following modules:

• Oracle Engine: draw-oracle.py and the oracle library handle random drawing, result locking, and redraw control.
• Recommendation Engine: recommendation-rules.md maps oracle tags to meal directions and provides recommendations based on the real menu and budget.
• MCP Adapter: SKILL.md and MCP_INTEGRATION.md describe the tool call order, parameter rules, and exception handling.
• Card Generator: generate-card.py uses Pillow to programmatically render a burgundy-and-gold template and composite official product images.
• Order Safety Controller: validate-order.py uses a state machine to control the confirmation flow and prevent unconfirmed orders.
• Skill Orchestrator: SKILL.md defines trigger conditions, execution flow, output format, and safety requirements.

The oracle library contains 104 original entries across eight categories: affirmative, negative, wait-and-see, action-oriented, reversal, good-luck, humorous, and McDonald's-exclusive. Each oracle includes an ID, text, category, tags, interpretation, action prompt, recommendation tags, and a visual theme.

Install Python Dependencies

The project requires Python 3.9 or later. The development environment uses Python 3.13. Official destiny cards are laid out programmatically with Pillow, so Pillow must be installed; the oracle drawing and order safety scripts do not depend on an image generation API.

git clone <your-repo-url> McOracle
cd McOracle
pip install Pillow

On macOS or Linux, make sure the system has a font that can display Chinese characters. The script selects an available font from its candidate list. Generating official cards does not require an image-generation API key.

Install as a WorkBuddy Skill

1. Get the project and install its dependencies.
2. Copy the entire McOracle/ directory to the user-level Skill directory ~/.workbuddy/skills/McOracle/, or to {workspace}/.workbuddy/skills/McOracle/ in the current workspace.
3. Enable the McDonald's China MCP in WorkBuddy's connectors.
4. Open a conversation and use phrases such as "McDonald's oracle," "Draw an oracle," or "Today's oracle" to trigger the Skill.

You can also ask an ordinary question, such as "Should I quit my job?" To run the complete flow, say "I want today's complete McDonald's destiny." Different WorkBuddy versions may have different requirements for Skill registration metadata; add the corresponding configuration for your local version.

Configure the McDonald's China Official MCP

Before using real stores, menus, and prices for recommendations, read the official MCP usage guide to learn how to apply for a token, then enter the configuration in WorkBuddy under "Connectors" → "Custom Connectors" → "Configure MCP."

{
  "mcpServers": {
    "mcd-mcp": {
      "type": "streamablehttp",
      "url": "https://mcp.mcd.cn",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

Replace YOUR_MCP_TOKEN with your own token, and do not commit the token to the repository. The main tools involved are now-time-info, query-nearby-stores, query-meals, query-meal-detail, and calculate-price. The order-related create-order tool may be called only after the user explicitly confirms.

First Use: Draw an Oracle

Run the following command from the project root to draw an oracle for a specific question:

python scripts/draw-oracle.py --question 'What should I eat today?'

The result is written to scripts/_oracle_state.json and locked for the current session. This ensures that subsequent interpretations, recommendations, and destiny cards all reference the same oracle rather than changing accidentally after multiple reads.

View the currently locked result or request a new draw:

python scripts/draw-oracle.py --peek
python scripts/draw-oracle.py --redraw

--redraw should be used only when the user explicitly requests a redraw. The system will not replace the oracle on its own while generating an interpretation or destiny card.

Generate a Destiny Card

Destiny cards use a fixed burgundy-and-gold visual template and do not depend on an image-generation service. The background includes a deep burgundy gradient, double gold borders, a glowing central ring, and star-point decorations. Text is laid out programmatically with Pillow to prevent garbled or overflowing Chinese text, IDs, and prices.

When MCP returns an official product image and the price has been verified through calculate-price, generate an official card as follows:

python scripts/generate-card.py \
  --oracle-id 'NO.021' \
  --answer 'Do not make decisions late at night.' \
  --interpretation 'You at 1 a.m. and you at 10 a.m. are not the same person.' \
  --item-name 'Grilled Chicken Burger Combo' \
  --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

The official output size is a 1200×1600 PNG. --price-verified may be used only when the price has actually been verified through MCP. Do not treat the example price as a live price.

Fallback Strategy for Image Assets

The main meal image is handled in the following priority order:

1. Prefer official product images returned by query-meals or query-meal-detail.
2. When no official image is available, use --item-image to specify an independent concept illustration, and label it accurately as a concept illustration.
3. If external assets are unavailable, the script uses built-in programmatic illustrations of a burger, fries, and cola.
4. When all assets are unavailable, output a fallback card labeled "Meal visual asset missing" and report failure with exit code 2 and JSON ok=false.

The project will not use an empty ring to impersonate a meal or label a concept illustration as an official photograph.

Complete an Experience in Conversation

A typical conversation might look like this:

You: McDonald's oracle, is today a good day to quit my job?
McOracle: Draws an oracle and returns its text, interpretation, action prompt, and major-matter reminder, with today's must-try meal available.

You: I'm ready to order.
McOracle: Shows an order summary containing the store, pickup method, items, and prices, and asks you to confirm.

You: Confirm order.
McOracle: Rechecks the prices, calls create-order, and returns the real order number and official payment entry point.

"Show me," "Make a recommendation," and "I'm ready to order" do not constitute final confirmation. The order flow may continue only after the user explicitly replies "Confirm order."

Order Safety Mechanism

The order safety controller checks the order status and key parameters. If the store, item, quantity, price, or pickup method changes, the previous confirmation becomes invalid. The system must display the summary again and request confirmation.

The project does not pay automatically and does not fabricate order numbers or success messages. After an order is created, it remains in a pending-payment state outside the official payment flow, and the user must complete payment independently through the official page. In-store pickup and drive-thru use orderType=1; delivery uses orderType=2 and requires a delivery address. The two sets of parameters cannot be mixed.

Run the Order Safety Demo Independently

The order script provides a pure-logic Mock demo that does not create real orders:

python scripts/validate-order.py demo

This demo is suitable for checking confirmation rules before connecting to a real MCP, including that unconfirmed orders cannot be placed, ambiguous expressions do not count as confirmation, changes to order parameters invalidate confirmation, and creating an order does not mean payment has succeeded.

Run Tests

The project includes three test groups covering oracle logic, destiny card generation, and the order safety state machine:

python tests/test-oracle.py
python tests/test-card.py
python tests/test-order-safety.py

The current result recorded in the README is 24 tests passing. Oracle tests verify the 104 data entries, unique IDs, eight categories, randomness, and state locking. Destiny card tests verify valid PNG output, dimensions, missing-asset fallback, the unverified-price branch, and long-text layout. Order tests use a Mock to verify safe state transitions without calling a real MCP or creating an order.

Advanced Usage Recommendations

Distinguish Entertainment from Real-Life Decisions

Oracles are for entertainment and inspiration only. They do not predict the future and cannot replace real-world judgment. For questions involving resignation, investment, health, legal matters, or finances, consider objective conditions and consult a professional.

Always Distinguish Verified Prices from Example Prices

Prices returned by MCP are in cents and must be divided by 100 before display. Prices are also time-sensitive. Without completing a live verification, display "Price not verified" and do not use an example price as a substitute for the live price in a card or conversation.

Manage Credentials and Privacy

Tokens and API keys may be read only through connector configuration or environment variables. They should not be written into source code or committed to the repository. The project should not store user privacy data, cookies, order numbers, or personal credentials. Do not include such sensitive information when submitting an Issue or Pull Request.

Understand the Current Capability Boundaries

Store lookup, menu lookup, meal details, price calculation, official image downloads, and destiny card generation have all been practically verified. The complete "order–payment–status lookup" loop, the McDelivery flow, and coupon claiming and redemption still contain areas that have not been fully tested. Therefore, they must not be described as having been successfully verified end to end.

Conclusion

McOracle combines fixed oracle data, true random draws, the official MCP real-time menu, and programmatic image layouts into a fun WorkBuddy Skill. You can start by using only the oracle script, or configure MCP to get further recommendations for stores, menu items, and prices. In actual use, always remember three principles: the oracle is for entertainment, prices must be verified in real time, and never create an order before the user explicitly confirms.

Fate may be random, but prices must be real.