mcd-budget-meal: a budget check built on McDonald's own price API

A request in one sentence becomes a priced shortlist

The idea is compact: you state a request, the tool returns official prices, and you compare a few candidate meals against the budget you named. The README frames it as the budget is yours to set, the menu is laid out, and the extra money is explained.

The worked example in the documentation is a person who wants to collect a meal now, has a budget of 30, wants one burger and one drink, and wants to pick a store first. The tool then queries the menu, the available coupons and the meal set details for that store, prices up to three candidates one by one, and shows the amount payable for the whole order, the actual items and portions, the remaining budget and the conditions attached to any discount.

In the recorded case the three official prices came back as 14.90, 22.90 and 26.90. Swapping the cola in one of the meal sets for sugar free cola and re-pricing the entire order produced 22.90, and the full run is recorded in the repository under examples.

The scope is stated just as tightly. Same store, one person, collect now, and the tool stops at the meal suggestion stage without ordering. The comparison covers only the candidates considered in that round, so it is not a guarantee of the cheapest item on the whole menu.

Three Python scripts with clearly separated jobs

The project entry points table makes the architecture unusually easy to read, because each file has one job.

quote_meals.py handles request validation, the official pricing call and the budget comparison for at most three candidates. compare_meals.py does the offline amount and preference checks, sorts the results and produces Markdown output, and it never touches the network. report_meals.py turns the valid quotes into a standalone interactive report and extracts only display fields for that purpose.

That split is the design decision worth understanding. The network call and the money arithmetic are in different scripts, so the checking logic can be exercised without a token and without a connection. The offline example is invoked like this:

python skills/mcd-budget-meal/scripts/compare_meals.py examples/demo-quotes.json

The README is explicit that the data in that example is fictional. The same separation is what allows a local report to be regenerated later from recorded quotes without re-querying, which is how the docs directory holds an example report built from a real batch run on 16 October and a token free preview of a historical pricing session.

The scripts need Python 3.10 or later and use only the standard library, so there is nothing to install before running them.

Budget checks run on integer cents, not on display prices

The README states the division of labour in one line: the AI understands the request, queries the real menu and prepares candidates, the official calculate-price tool returns the amount payable for the whole order, and the local script checks the budget, the portion counts, the exclusions, the pricing time and duplicate meals.

Working in integer cents matters more than it sounds. Floating point comparisons on currency produce rounding artefacts at exactly the boundary that matters, the one where a candidate is a few cents over the limit. The script also enforces the part of the request that is about quantities rather than money, so a request for at least two burgers is checked against the portions actually in the order rather than against the number of items listed on the menu.

When nothing fits, the rule is stated explicitly: the budget you entered is what counts, and if no candidate fits, the tool lists the closest valid option together with the amount by which it exceeds the budget. The alternative of quietly returning a cheaper-looking but smaller meal is avoided by showing the overage instead of hiding it.

Duplicate meals and the pricing timestamp are checked in the same pass, so two identical candidates or a stale quote do not slip into the comparison as if they were distinct options.

Substitutions trigger a fresh price call

The most important behavioural rule in the project is short: after a substitution the whole order is priced again, and old quotes are never adjusted by adding or subtracting menu display prices.

This is the difference between a tool that knows what something costs and a tool that knows what the current price of this exact basket is. A coupon can apply to one item and not another, a meal set can change what is included, and a price can move between the moment the menu was read and the moment the order is priced. Arithmetic on menu numbers produces a number that was never charged to anyone.

The README gives the concrete shape of the feature requests that trigger this. Asking for no cola while keeping the burger makes the tool check the exclusion, substitute, and re-price the complete order. Asking for a 25 budget with at least two burgers makes it check the actual portion count and show the overage when no in-budget option exists. Asking to compare with coupons if any are available, and to proceed without them otherwise, makes it verify the coupons available at the selected store and compare the no-coupon options when there are none.

The difference reporting is handled with the same care. Increased, decreased and unchanged items are listed with their portions, and the whole-order difference is not presented as if it were the individual price of the new item.

Interface failure stops the round instead of retrying

When the interface fails, the run stops and no further calls are made. Earlier valid results are kept, and there is no automatic retry.

That is a deliberate constraint rather than an oversight. A retry loop against a pricing service that has already returned an error tends to produce a round that looks complete while mixing results from different points in time, and a user cannot tell which prices were confirmed and which were guessed. Stopping keeps the report honest, since the documentation also states that failed candidates never get a made up price attached to them.

The same principle governs the generated report. The report produced for a round uses the budget filtering, the difference analysis and the copy function of that round's successful quotes only, and the script that builds it extracts display fields rather than the raw responses.

Quote freshness has a default window of 15 minutes, which the README attributes to the project itself as a display policy rather than to a rule from the pricing service. The dashboard marks quotes that have passed that age, and a stale quote is labelled as such instead of being presented as current.

Installing the skill and wiring your own MCP token

You need an AI client that supports remote MCP, such as WorkBuddy, Cherry Studio or Cursor, and your own McDonald's MCP token.

The token comes from the McDonald's MCP platform, where you sign in and activate it, and the client connects to https://mcp.mcd.cn using the Streamable HTTP protocol. The documentation is explicit that the token belongs only in the client's private configuration.

The repository is downloaded and unpacked, and then either the install script is run in the repository directory, or the client is asked to import the complete skills/mcd-budget-meal folder into its skills directory. Existing skills are backed up first, and the install script neither reads the token nor modifies the connector. If the client has no skill import entry point, the repository directory is opened and the AI is pointed at skills/mcd-budget-meal/SKILL.md.

Two conditional notes matter. The scripts are optional when only native MCP tools are used. And where a client hits an array validation problem during pricing, the local Python has to use the project's direct connection path instead.

The public configuration file mcp-config.example.json contains only a ${MCD_MCP_TOKEN} placeholder, while real credentials and raw responses stay in a private local directory.

What the verification actually covers

The README keeps a table of what has been checked, and it is worth reading closely before trusting a number the tool prints.

The recorded verification covers a real MCP run where the batch entry point priced three candidates and generated a report, plus a separate drink swap that was priced successfully, with the public summary redacted. The Python logic has 51 offline regression cases, including keeping valid quotes when an export fails, restoring an older comparison JSON and the original budget checks. The page logic has 14 simulated DOM scenarios covering the copy fallback, clearing old results, expired quotes and marking restored history. The install path has 14 checks in an isolated temporary configuration directory, including removing old files, keeping private records and restoring the previous version when a replacement fails.

The gaps are stated in the same section. The coupon branch has no live account case. The install acceptance work used an isolated temporary configuration directory, was not installed into a real user WorkBuddy directory, and automatic skill discovery in WorkBuddy was not verified.

The offline regression can be reproduced with these commands, where Node is only needed for the page checks and not for using the skill or running the Python scripts:

python -B -m unittest discover -s tests -v
node tests/check_report.cjs
./tests/test_install.ps1

On licensing, the original skill, scripts and examples use the MIT licence, while the repository carries a custom licence that GitHub cannot classify, and the official contest declaration is preserved as written. The project is a contest entry and not an official McDonald's product, and use of the MCP service has to follow the official service rules. The last push was on 2026-10-19 and there are no GitHub releases.

Editorial conclusion

Adopt mcd-budget-meal if you drive an AI client that speaks remote MCP, you hold your own McDonald's MCP token, and you want a meal suggestion whose price comes from the official pricing call rather than from menu screenshots. Skip it if you need coupons to be handled automatically, since the coupon branch has no recorded live account case, or if you want live stock and allergen handling, which the rules explicitly leave out. Before the first run, read skills/mcd-budget-meal/SKILL.md, run the offline regression with python -B -m unittest discover -s tests -v, and confirm the token stays in the client private config. The last push was on 2026-10-19 and the repository has no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. README
3. Sam-Hui-dot/mcd-budget-meal on GitHub