mcd-coupon-strategist prices a McDonald's order through MCP instead of guessing, then audits the coupons you are about to waste

Two questions, one MCP server, and a refusal to guess prices

Saving tools for fast food chains usually answer a single question: how do I order this basket for the least money. This project asks a second one, what value am I about to lose. The documentation frames the difference as helping the user stop losing money rather than only helping them spend less.

The implementation is built on the McDonald's China MCP service, with the endpoint shown as mcp.mcd.cn. The service exposes the tools the skill depends on: calculate-price for pricing a candidate basket, order-list for past orders, and query-my-coupons for the coupon wallet. Menu and price data for the current store come from the same service.

Two design rules follow from that. First, the model never invents an amount: every figure in the output is filled in by calculate-price, so a candidate plan is costed by the server rather than estimated in text. Second, the tool distinguishes coupons usable at the current store from coupons merely held in the wallet, which in the recorded demo are two coupons and nine coupons respectively. Computing the loss of expiring coupons against the wrong set would hide seven coupons about to expire.

The agent is packaged as a skill, with SKILL.md at the repository root and integration notes in MCP_INTEGRATION.md, which is also the declared homepage. Top-level files include a contest declaration, a workbuddy.md file and an mcp-config.example.json.

The offline demo runs the real pipeline on recorded fixtures

The fastest way to see the tool work is the 30 second demo, and it needs no token, no network and no third party dependency. The project states that only the Python standard library is used, and the badge indicates Python 3.8 or newer.

git clone https://github.com/Ayzzz123/mcd-coupon-strategist.git
cd mcd-coupon-strategist
python demo.py

demo.py reads recorded MCP responses from the fixtures/ directory and runs two chains through the same business logic used in production. The first chain prices a basket at a named store in Nanjing against a 40 yuan budget. The second chain audits the coupon wallet and the order history.

That design has a purpose beyond a friendly demo. The documentation describes it as an end to end regression test for the whole data pipeline, since the business logic is unchanged and only the transport differs. If the MCP response format changes, a recorded fixture that no longer parses will surface it before a live call does.

One honesty note about the demo output. Three coupons appear with an unknown value, and the documentation insists this is a data fact rather than a parsing failure: the recorded menu snapshot was taken at 21:59 and those items were not on the menu at that hour. The project says explicitly that no matching product name was injected into the menu to make the demo look tidier.

For live use, a token is required, and the repository ships the template:

MCD_MCP_TOKEN=your_mcd_mcp_token_here

The example lives in .env.example at the repository root, alongside mcp-config.example.json for the server configuration.

Coupon value comes from the cashier first and the menu second

The metric that makes the silent cost idea possible is the value of a single coupon, and the project takes a two route approach to it.

The preferred route is to ask the server. The coupon's own product code is passed to calculate-price together with its coupon identifier, and the discount field in the response is the exact value of that coupon while price is what you would actually pay using it. In the recorded demo this produced 14.5 yuan for a buy one get one fries coupon and 6.6 yuan for an assorted snack coupon.

The fallback route is to reconstruct the value from the menu when the coupon code cannot be used. The documentation lays out four shapes: a threshold discount such as 12 off a 50 yuan order gives 12.0 yuan directly, a buy one get one takes the menu unit price, a free item coupon takes the menu unit price because the coupon makes it free, and a fixed price coupon subtracts the fixed price from the menu original, giving 23.0 minus 9.9, or 13.1 yuan.

The argument for measuring rather than inferring is concrete. The assorted snack coupon has no number in its title and no matching product on the menu, so the fallback can only report zero for something that is really worth 6.6 yuan. Inference does not merely underestimate in this design, it can turn real value into zero.

When both routes fail, the rule is strict: take zero and label the coupon as having an unknown value. No plausible looking number is estimated.

Silent coupon cost and a scheduling model that admits waste

The second half of the tool is a cost of holding, expressed as money that expires unused. In the recorded demo the wallet holds nine coupons, of which seven expire within seven days, and the measurable ones add up to 21.1 yuan. Seven further coupons have values that cannot be derived from the menu and are excluded from that total rather than guessed.

The scheduling step is the part most likely to surprise you, because it can end in a loss. The tool works out how many orders the window allows, using the order frequency in the demo at 0.089 orders per day across a two day window, concludes that about one order will happen, and assigns the highest value coupon to it. The result is that 21.1 yuan of achievable value exists but only 14.5 yuan can be captured, leaving 6.6 yuan certain to expire unused. The tool says so rather than pretending the wallet is fully usable.

The same logic runs over the rest of the wallet. The demo reports 7 coupon records in total, 4 already claimed and 3 still claimable, and it treats unclaimed coupons as a zero cost saving opportunity because claiming is free.

Order history feeds a consumption profile. The recorded data shows 8 orders, 2 of them at zero value, a total spend of 103.5 yuan and an average order of 17.25 yuan computed over the 6 orders that actually cost money. The zero value orders still count as ordering opportunities even though they are excluded from the average, which is the distinction between spend basis and order basis that the project insists on keeping.

Points pages where the status flag is not the truth

The rewards section applies the same expiry logic to points and adds a second data quality problem. In the recorded demo the account holds 376.3 usable points, 581.3 accumulated and 188 already used, and 17 points have expired, which the tool counts as a loss that already happened.

The interesting part is the redemption catalogue. Of 24 items in the points store, 9 remain inside their redemption window and 6 of those are affordable with the current balance, while 15 have passed their redemption deadline. The document explains the trap directly: the interface status still marks those 15 items as listed, so reading the status field alone would suggest they can still be redeemed.

The tool therefore reports the deadline rather than the flag, and it pairs the two. It lists what can be redeemed now with the point cost and the remaining days, and it flags same item pairs sold at different point prices, where the same product appears to cost 200 points in one listing and 100 in another.

Applying the same rule as with coupons, unstated values are never filled in. The output distinguishes a point item that is redeemable now from one that is past its window, and says which of the two the account balance supports.

What the tool refuses to compute

A reader should know the boundaries before trusting a recommendation, and this project is unusually explicit about them.

Activity dates are listed, activity prices are not. The calendar shows that 14 days in October carry activity, with 2 already past, 1 on the current day and 11 upcoming, and the nearest entry is a collaboration dated 15 October. The tool states that having an activity is not the same as it being cheaper, and that the prices written in promotional copy cannot be verified, so the copy is never used in a calculation. Only the timeline and the title are reported, and the judgement is left to the reader.

Refunds are reported without a firm total. The order history includes 2 partially refunded orders, and the interface does not return the refund amount, so the tool cannot confirm whether the total amount field is before or after the refund. It flags that the reported spend may be slightly too high rather than picking an interpretation.

Coupon values are also bounded by time of day and by store. One breakfast coupon in the demo is valid only between 05:00 and 10:29 and only for in store pickup, and the recorded menu snapshot did not include its product at the hour the data was captured. The tool shows such coupons as unknown value instead of mapping them to a near enough product.

The net effect is that the tool will under state your savings. That is a deliberate trade, and the documentation frames it as preferable to publishing a number it cannot support.

How this differs from a single order minimiser

There are plenty of tools that answer one order question well, and this project states the difference plainly in a comparison table rather than claiming a new algorithm. A conventional approach lets the model estimate prices, which cannot produce real numbers. It recommends a bundle without saying why, so the user learns nothing. It pushes the use of coupons even when topping up the order to reach a threshold makes the total higher, which is the bait the project calls the coupon trap. And it looks only at the current basket.

This implementation prices every candidate combination through the server, states which coupon or bundle produced the saving, warns against threshold bait, and also reads order history and coupon holdings to expose the longer term structure.

There is a further difference in what counts as a resource. A coupon is treated as money with an expiry date rather than as an available discount, and points are treated the same way, with the status field explicitly distrusted. The comparison table also notes that an average order value applied without distinguishing time of day misleads every downstream coupon decision.

The cost of that richer model is more API traffic and more state. A single order question needs the menu and the coupon list for one store. The audit question needs order history, the full wallet including coupons not usable at that store, points balances and the redemption catalogue.

MIT licensed, no releases, and a live dependency on one service

The repository is not archived and the last push was on 2026-10-14. There are no GitHub releases, so there is no version history to pin against and updates arrive as commits on the main branch.

The licence is MIT, so the code can be reused and modified in a commercial or personal project with attribution and preservation of the licence notice. That covers the skill code. The data it reads is a different matter: it comes from the McDonald's China MCP service, and access depends on a token issued through that service.

The genuine coupling is to a single remote API. Menu structure, coupon records, order history, points balances and the redemption catalogue all have the shape the MCP responses have, and the fixtures in fixtures/ are recordings of those responses with their own collection notes. A change in the response schema on the service side would reach the pipeline before it reached this repository, which is precisely what the offline demo is meant to catch.

The project also carries files aimed at a competition setting, including CONTEST_DECLARATION.md and workbuddy.md, and the repository root holds src/, scripts/, docs/ and assets/ alongside the demo.

Editorial conclusion

Use mcd-coupon-strategist if you eat at McDonald's China often enough for coupons and points to accumulate, and if you are willing to give an agent read access to your order history and coupon wallet through the MCP token in .env.example. Do not expect it to plan a meal for you, and do not expect the activity calendar to tell you whether a promotion is cheap, because the project deliberately refuses to calculate from marketing copy. Before adopting it, run python demo.py with no token to confirm the recorded fixtures still exercise the pipeline, then set MCD_MCP_TOKEN and compare one live calculate-price response against the fixture values for the same store.

Frequently asked questions

Official sources

1. Ayzzz123/mcd-coupon-strategist on GitHub
2. Issues
3. License: MIT
4. Project website
5. README