M-CODE WRAPPED

麦当劳 MCP 工具箱：从调试接口到出报告，一条龙。

基于 麦当劳 MCP 开放能力，四个模块覆盖开发者到消费者的完整链路：

模块	一句话	入口
MCP 能力探测器	一键探测全部 35 个 tool 的真实返回，自动串联参数	scripts/explore.py
个人年度消费年报	订单、消费、积分、奖品、高频单品，一页看完	scripts/collect.py
麦当劳数据全景报告	158 个餐品营养、营销日历、抽奖池、商城、优惠券	scripts/public_data.py
抽奖 EV 精算器	蒙特卡洛模拟，算清抽奖到底值不值	scripts/lottery_ev.py

并可选粤语/方言语音播报，把报告念出来。

麦当劳 1024 程序员节创意开发大赛参赛作品 · 非麦当劳官方产品

如果你正在对接麦当劳 MCP，先看这个

官方文档不太全，实测踩了 3 个坑，都在探测器报告里：

1. 返回体不是 JSON，是 Markdown，真 JSON 藏在 ## Original Response 之后
2. list-nutrition-foods 的 data 是逗号分隔文本表格，不是 JSON
3. 无数据时返回中文文案（如 暂无可用优惠券），不是空数组

服务端实际暴露 35 个 tool（文档写的是 33 个），探测器已跑通 27 个， 7 个写操作默认不调用。不想看报告也行，直接跑：

export MCD_MCP_TOKEN=你的token
python3 scripts/explore.py     # 零第三方依赖，输出 out/mcp-explorer.md

上图由真实 MCP 数据生成。样张来自授权测试账户，接入你自己的 Token 后会替换为你的真实数据。

为什么不是"又一个点餐助手"

大赛里绝大多数作品在做同一件事：怎么更便宜地下单。这个项目换个方向—— 先帮开发者搞清楚 MCP 到底返回了什么，再把数据做成值得点星的报告。

	点餐助手	M-CODE WRAPPED
视角	省钱、下单	调试 + 数据可视化 + 决策
是否需要消费记录	需要	公共全景不需要，个人年报需要
产物	一个订单	探测报告 + 年报 + 全景 + 精算
对开发者友好度	一般	探测器专门解决这个痛点

模块一：MCP 能力探测器

官方文档列了 tool 名字，但没说清楚实际返回什么。实测下来坑不少：

• 返回的是 Markdown 文本，真 JSON 藏在 ## Original Response 之后
• 营养数据是逗号分隔文本表格，不是 JSON
• 无数据时返回中文文案（如 暂无可用优惠券），不是空数组

探测器一键跑完所有只读工具，记录真实形态：

export MCD_MCP_TOKEN=你的token
python3 scripts/explore.py

自动串联参数：从 order-list 取 storeCode 喂给 query-meals，取 orderId 喂给 query-order， 取 spuId 喂给 mall-product-detail——需要参数的工具也能跑起来。

本次实测：35 个 tool，27 个成功调用，7 个写操作跳过，1 个缺参数。 完整报告见 out/mcp-explorer.md。

安全红线：draw-lottery、create-order、cancel-order、mall-create-order、 auto-bind-coupons、party-order-create、delivery-create-address 一律不调用， 只在报告里展示参数定义。

模块二：个人年度消费年报

export MCD_MCP_TOKEN=你的token
python3 scripts/collect.py
python3 scripts/build_report.py       # -> out/mcd-wrapped.html

包含：年度下单数、消费总额、客单价、深夜订单占比、最常去门店、连续打卡、 高频单品 Top 6、月度趋势、周几偏好、下单高峰、累计能量、可用积分、奖品数。

模块三：麦当劳数据全景报告

python3 scripts/public_data.py
python3 scripts/build_panorama.py     # -> out/panorama.html

不需要消费记录，只用公共数据：158 个餐品营养档案、热量 TOP10 / 低卡 TOP10 / 分布直方图、 当月营销日历、积分抽奖池、麦麦省可领券、积分商城商品。

模块四：抽奖 EV 精算器

python3 scripts/lottery_ev.py                    # 默认 10 连抽 × 10000 轮
python3 scripts/lottery_ev.py --draws 50 --trials 50000
python3 scripts/lottery_ev.py --base-price 45    # 调整折扣券基准价

真实奖池 + 真实单次消耗（24 积分），蒙特卡洛模拟。 券面额按奖品名智能匹配基准价（麦旋风按 ¥9、三件套按 ¥40）。

麦当劳未公布中奖概率，所有结果基于等概率假设，脚本从不调用 draw-lottery。 完整报告见 out/lottery-ev.md。

方言播报

python3 scripts/speak.py --dialect cantonese    # 粤语
python3 scripts/speak.py --dialect taiwanese    # 闽南语调
python3 scripts/speak.py --dialect mandarin     # 普通话
python3 scripts/speak.py --dry-run              # 只看播报稿

后端按 VoxCPM2 → macOS 内置中文嗓音 自动回退：

export VOXCPM_API_URL=http://127.0.0.1:7860     # 本地 VoxCPM2 Gradio 服务
export VOXCPM_REF_AUDIO=/path/to/四川话参考音频.wav
python3 scripts/speak.py --dialect voxcpm

目录结构