mcd-cn-assistant
把麦当劳中国官方 MCP 工具，封装成一个开箱即用的 Agent 技能：活动不错过、优惠不放过、点餐不吃亏、群点不算账。
一、项目介绍
1.1 这是什么
mcd-cn-assistant 是一个面向 AI Agent 的技能包（Skill），建立在麦当劳中国官方 MCP 服务（https://mcp.mcd.cn）之上。
麦当劳中国官方 MCP 提供了 30+ 个原子工具——查门店、查菜单、查券、领券、算价、下单、查积分、积分商城、积分抽奖、主题活动预约……但原子工具不等于能用的助手。直接用这些工具，用户需要自己记住几十个工具名、自己判断先调哪个后调哪个、自己组合券和商品算最便宜的方案，还得时刻提防 AI 擅自下单。
本项目做的事情是：把这堆原子工具编排成四条用户真正会用的业务流，并把安全边界写死。
1.2 解决什么问题
1.3 四大能力 + 社交媒体场景六项
统一入口（关键设计）：能力三与能力四共用一个点餐入口——只要是点餐请求，Agent 在定位门店前会主动问一句「这单是你自己吃，还是帮几个人一起点（拼单）？」，再据此分流。多人拼单不需要用户自己想到，答一句"拼单"即可进入完整的分账流程；回答含糊时会再确认一次，不会默认按单人处理。
社交媒体场景六项（2026-10-16 新增）
完整词典、算法与模板见
references/social-playbook.md；真实对话示例见docs/examples.md示例 13~16。
1.4 架构
flowchart TD
A["麦当劳中国 MCP 服务<br/>mcp.mcd.cn · Streamable HTTP · Bearer Token"]
A --> B1["能力一：最新活动推送"]
A --> B2["能力二：联名关注推送"]
A --> G["点餐统一入口<br/>先主动问：单人还是多人拼单？"]
G --> B3["能力三：最优惠点餐"]
G --> B4["能力四：多人群点聚合"]
B1 --> C1["now-time-info<br/>campaign-calendar<br/>available-coupons"]
B2 --> C2["config/keywords.json<br/>关键词 + 同义词扩展"]
B3 --> C3["门店 → 领券 → 菜单<br/>calculate-price 比价<br/>确认后 create-order"]
B4 --> C4["开单 → 收单聚合<br/>满减凑单 + 券归属 + 公共费用分摊<br/>每人账单 → 确认后单账户结算"]
C2 --> D["定时自动化<br/>每天 09:00 只读推送"]
A --> E1["社交媒体场景六项"]
E1 --> E2["⑤ 隐藏吃法还原：文案/截图解析<br/>→ 特调 modification + 外送 remark"]
E1 --> E3["⑥ 穷鬼套餐演算：约束拆解<br/>→ 多候选 calculate-price 实算"]
E1 --> E4["⑦ 周边雷达：逐门店扫菜单<br/>→ 麦金卡随单购优化 → 锁单"]
E1 --> E5["⑧ 营养搭配：list-nutrition-foods<br/>→ 去酱 / 换无糖 / 算价"]
E1 --> E6["⑨ 晒单卡片：本地生成 SVG<br/>⑩ 场景推送：时段 + 星期"]
style A fill:#5DCAA5,stroke:#0F6E56,color:#04342C
style G fill:#FAC775,stroke:#854F0B,color:#412402
style B1 fill:#9FE1CB,stroke:#0F6E56,color:#04342C
style B2 fill:#9FE1CB,stroke:#0F6E56,color:#04342C
style B3 fill:#9FE1CB,stroke:#0F6E56,color:#04342C
style B4 fill:#9FE1CB,stroke:#0F6E56,color:#04342C
style E1 fill:#FAC775,stroke:#854F0B,color:#412402
style E2 fill:#FFF4E0,stroke:#854F0B,color:#412402
style E3 fill:#FFF4E0,stroke:#854F0B,color:#412402
style E4 fill:#FFF4E0,stroke:#854F0B,color:#412402
style E5 fill:#FFF4E0,stroke:#854F0B,color:#412402
style E6 fill:#FFF4E0,stroke:#854F0B,color:#412402
style C1 fill:#E1F5EE,stroke:#5DCAA5,color:#085041
style C2 fill:#E1F5EE,stroke:#5DCAA5,color:#085041
style C3 fill:#E1F5EE,stroke:#5DCAA5,color:#085041
style C4 fill:#E1F5EE,stroke:#5DCAA5,color:#085041
style D fill:#FAC775,stroke:#854F0B,color:#412402
1.5 目标用户
核心用户
典型痛点
- 活动散落在 App 首页、公众号、门店海报，看到时往往已经结束；
- 优惠券种类多、门槛各异（满减 / 第二份半价 / 指定商品 / 限渠道），靠人脑判断哪种买法最便宜成本极高；
- 群点时刷屏报菜名记不住、满减档差几块钱没人算、配送费、打包费和优惠券没人分，收钱环节更是大型社死现场；
- 想拼单却不知道工具支持——多人点餐能力如果只能靠用户自己提起，等于不存在；本项目把它前置为点餐入口的主动提问；
- 刷到社媒爆款吃法，不知道哪些真能点、哪些只能跟店员说，也懒得自己拆；
- 想凑"20 块穷鬼套餐"或"450 大卡减脂餐"，人脑枚举不出最优解；
- AI 助手能查菜单，但用户不敢让它下单——怕它算错价、用错券、多花钱。
适用环境
- 任意支持 MCP 的 AI 客户端（WorkBuddy / Claude Code / Cursor / Cline / Cherry Studio / Trae / Kiro / VSCode Copilot 等）；
- 需自备一枚麦当劳中国 MCP Token；
- 仅面向中国大陆地区（麦当劳 MCP 服务不含港澳台）。
二、仓库结构
mcd-cn-assistant/
├── README.md # 项目介绍 / 安装方法 / 使用示例 / 目标用户
├── CONTEST_DECLARATION.md # 参赛声明（官方文件，内容未改动）
├── MCP_INTEGRATION.md # MCP 集成说明：Server / Tool / 调用流程 / 业务价值
├── mcp-config.example.json # 脱敏配置示例（仅环境变量占位符）
├── workbuddy.md # WorkBuddy 开发上下文（WorkBuddy 专项奖励用）
├── SKILL.md # 技能主体（Agent 运行时加载）
├── LICENSE # MIT
├── assets/
│ ├── banner.svg # 顶部横幅（自绘动画 SVG）
│ └── cta-star.svg # 结尾 Star CTA 图
├── config/
│ └── keywords.json # 联名 / 活动关注关键词配置（能力二读取）
├── references/
│ ├── mcd-tools.md # 35 个 MCP 工具速查表 + 调用顺序 + 错误码 + 2026-10-16 实测要点
│ ├── group-order.md # 能力四：订单会话结构 + 分摊算法（尾差兜底）+ 账单模板
│ └── social-playbook.md # 社交媒体场景：隐藏吃法词典 + 凑单算法 + 营养子集 + 晒单模板
└── docs/
├── mcp-setup.md # MCP 接入说明（WorkBuddy / Cursor / Cherry Studio / Trae / Claude Code …）
└── examples.md # 四大能力 + 社媒六项的真实对话示例
三、安装方法
前置条件：已取得麦当劳中国 MCP Token（在 https://open.mcd.cn/mcp 手机号登录 → 控制台 → 激活 → 复制）。
第 1 步：配置 MCP 服务（WorkBuddy 官方流程）
-
打开 WorkBuddy，在左侧边栏【专家·技能·连接器】，选中【连接器】页签；
-
点击右上角【自定义连接器】→【配置MCP】；
-
在打开的手动配置页面中填入以下的 JSON 内容：
{ "mcpServers": { "mcd-mcp": { "type": "streamablehttp", "url": "https://mcp.mcd.cn", "headers": { "Authorization": "Bearer ${MCD_MCP_TOKEN}" } } } }⚠️ 一定记得把
${MCD_MCP_TOKEN}替换为「你自己的」实际 MCP Token，点击【保存】！填入后请确认
Authorization的值已经是你的真实 Token（形如Bearer abc123...）——WorkBuddy 手动配置页填入的是字面值，不要保留${MCD_MCP_TOKEN}这个写法本身。 -
回到【自定义连接器】，将
mcd-mcp【启用】。
其他客户端（Cursor / Cherry Studio / Trae / VSCode / Claude Code）见 docs/mcp-setup.md。
📌 关于占位符：本仓库不含任何真实凭证，所有出现
${MCD_MCP_TOKEN}、<你的 MCP Token>的位置都需要你填入自己的 MCP Token。完整对照见 docs/mcp-setup.md · 占位符速查。
第 2 步：安装技能
将这段话复制给你的AI Agent（WorkBuddy、claw等）： 帮我安装mcd-cn-assistant这个skill： 1、https://github.com/junxchan54-maker/mcd-cn-assistant/ 2、以后我说麦当劳下单相关的就调用mcd-cn-assistant这个skill 3、把仓库里 skill/mcd-cn-assistant 文件夹复制到用户级技能目录
把本仓库的 SKILL.md、config/、references/ 放进你所用客户端的技能目录。推荐 clone：
git clone https://github.com/<your-name>/mcd-cn-assistant.git ~/.workbuddy/skills/mcd-cn-assistant
各客户端的技能目录：
若你的客户端不支持技能目录机制，也可直接把
SKILL.md的内容作为系统提示词或项目 Rules 粘贴进去，流程完全一致。
第 3 步：验证
对 Agent 说一句：
用 mcd-cn-assistant 查一下这个月麦当劳有什么活动
能正常返回活动列表即接入成功。若报 401，说明 Token 无效或未提供；若报 429，说明触发了 600 次/分钟的限流。
四、使用示例
入口 · 点餐前主动询问（能力三 / 四 共用）
你：帮我点个麦当劳，中午想吃点好的
Agent（澄清需求后，不会直接查门店，而是先问）： 「这单是你自己一个人吃，还是帮几个人一起点（拼单）？拼单的话我可以代录大家想吃的、帮你凑满减、把配送费和打包费算清楚，最后出一张「每人应付多少」的账单。」
- 你答「就我自己」→ 进入能力三 · 最优惠点餐；
- 你答「我们部门 5 个人一起点」→ 进入能力四 · 多人群点聚合，接着确认人数、门店/地址与分摊偏好；
- 你答「我们几个人一起吃，但我自己付」→ 走能力三按整单找最省，顺带问一句要不要分摊账单；
- 你答得含糊（如「随便点点」）→ 再确认一次，不会默认按单人处理。
能力一 · 最新活动推送
你：这个月麦当劳有什么活动？
Agent：先取当前时间 → 调用活动日历 → 输出「进行中 / 即将开始」分组清单，每条含活动名、起止时间、一句话参与方式和入口。
能力二 · 联名关注推送
你：帮我盯着联名款，有新的就告诉我
Agent：把
联名写入config/keywords.json（含同义词：联动 / 限定 / 合作款 / 联名款 / IP合作 / 品牌合作 / co-brand / 联名活动），并回显最新关键词列表。之后每天 09:00 自动查询当月活动，只推命中项；没有命中就明确说「今日无命中关键词的新活动」，不拿无关活动凑数。
为什么同义词里必须有「联动」：麦当劳对 IP 合作的官方文案常写「麦当劳联动G-DRAGON」而不是「联名」。2026-10-13 实测，缺这个词会把整条联名活动漏推——而它的联名食品在菜单里明明可以代点。
⚠️ 联名周边可以直接代买（2026-10-16 修正，推翻 10-13 的错误结论）：周边就在
query-meals菜单里（如521954联名复古棒球帽、521955联名徽章），走主链路下单即可。加购 15 天麦金卡体验卡（¥9.90）几乎总是更省——周边降 ¥5、配送费与打包费归零，实测净省 ¥1.10～¥12.10。周边随门店和渠道变化（同一时刻上海某店到店菜单没有、深圳外送菜单有），所以必须先扫再下结论。MCP 做不到的是：实时库存查询与持续补货监控（无库存接口）、积分商城换周边（该类目实测全部过期）。
你：不再关注联名了，改成关注新品
Agent：更新配置文件 → 回显最新列表。
能力三 · 最优惠点餐
你：两个人吃，到店取，怎么点最划算？我在静安寺附近（入口询问时已确认「一起吃、我自己付款」）
Agent：
- 查附近门店 → 2. 查麦麦省可领券 + 我已有的券 + 该门店可用券 → 3. 拉菜单 →
- 围绕券的门槛枚举 2~5 个候选组合 → 5. 逐个调
calculate-price真算 → 6. 输出比价表：
- 你说「就第一个」，才调
create-order下单。
能力四 · 多人群点聚合
你：办公室下午茶，5 个人拼麦当劳外送到公司，帮我收单算账
（这条诉求也可以只由入口的一句「帮几个人一起点」触发——不必像这样一次性说全）
Agent：
- 开单：确认门店 / 地址与三项分摊偏好（公共费用怎么摊？券省的归你还是平摊？接受凑单建议吗？）→ 创建订单会话；
- 收单：你逐个转述——"张三 板烧鸡腿麦满分单人餐×1""李四跟张三一样""王五撤销"——每次变动后增量回显聚合列表与小计；多人点了同款会自动合并并问"要不要分开包装"；
- 收完单进入算账：
- 盘券（下单人账户）：命中你的「9.9元中杯冰美式」，原价 ¥19.00 → 券后 ¥9.90（省 ¥9.10），已用
calculate-price实算验证；- 券归属：按平摊规则，账单标注「券省 ¥9.10，每人减 ¥1.82」；
- 公共费用 ¥9.00（配送费 ¥6.00 + 打包费 ¥3.00）按消费比例分摊（尾差兜底，保证合计严格等于实付）；
- 凑单判定：算价未返回满减档位 → 直接说明"本单无凑单空间"，不臆造门槛、不自动加购；
- 输出账单（以下为真实实测数据，门店 storeCode 1421053）：
✅ 校验：Σ每人应付 ¥111.60 =
calculate-price实付总额 ¥111.60。
- 你确认账单后调
create-order（单账户结算）；每人应付金额直接复制去微信群收款即可，账单也可导出为分享用 HTML 页。
⚠️ 能力四的两个诚实边界：MCP 是单账户鉴权，只能用下单人自己的账户结算（他人按账单转账），不会模拟登录任何人的账号；Skill 不代收款项、不生成官方收款码，收款由组织者用微信群收款或本人收款码完成。
更多示例见 docs/examples.md。
五、MCP 接入说明
麦当劳中国 MCP 是远程托管的 MCP Server，无需本地安装任何进程，只需配置接入地址与 Token。
平台接入教程（WorkBuddy / Cursor / Cherry Studio / Trae / VSCode 等）→ docs/mcp-setup.md 工具清单与调用顺序 → references/mcd-tools.md
六、设计原则与安全边界
这是本项目区别于"把工具列表塞给模型"的核心：
- 写操作必须二次确认。
create-order、auto-bind-coupons、cancel-order、draw-lottery、mall-create-order、party-order-create、delivery-create-address等会花钱、耗积分或改变账户状态的调用，必须先向用户列清明细并获得明确同意，严禁静默执行。 - 算价不靠心算。 一切金额以
calculate-price的返回为准。券面文字不等于真实优惠（门槛、渠道、指定商品都会影响），必须真跑一遍。 - 时间不靠模型记忆。 涉及日期一律调用
now-time-info。 - 限流友好。 串行调用、复用会话内已获取的结果，不做无意义的重复查询。
- 只做该做的事。 定时推送任务被明确限定为"只读"，prompt 中写死禁止任何写操作。
七、参赛信息
本项目是麦当劳程序员创意开发大赛的参赛作品。
提交文件清单（按赛事要求）
如果这个项目帮你省下了一顿饭钱，欢迎点一个 ⭐ Star 支持一下。
八、兼容性
技能本身不绑定任何特定的 Agent 框架。SKILL.md 与 references/mcd-tools.md 全程使用官方工具名（query-meals、calculate-price 等）描述流程，因此可接入任何支持 MCP 的框架：
Claude Code · Cursor · Cline · Cherry Studio · Trae · Kiro · VSCode Copilot · WorkBuddy 等。
注：
config/keywords.json的读写由 Agent 直接编辑文件完成；若你的框架无文件系统权限，可把关键词直接写在对话上下文里，技能流程同样成立。
九、免责声明
- 本项目是麦当劳程序员创意开发大赛参赛作品，由参赛者独立开发，非麦当劳官方产品；项目输出仅供参考，不构成医疗、营养或其他专业建议；餐品信息、价格及供应状态以麦当劳官方渠道的实时结果为准。
- 本项目是第三方社区作品，由个人开发者独立编写，与麦当劳中国及其关联方无隶属、代理、赞助或背书关系。
- 本项目不包含也不分发麦当劳 MCP 的任何源码、Token 或私密数据；MCP 服务的使用须遵守麦当劳中国的《使用条款》及《麦当劳 MCP 服务规则》，Token 需使用者自行申请并妥善保管。
- 本项目不构成对麦当劳及其关联方商标、标识、品牌资产的任何授权。
- 本项目仅用于个人学习与非商业用途，不得用于商业售卖、付费分发、引流变现，或任何暗示官方背书、误导公众的用途，亦不得用于违法违规或黑灰产行为。
- 本项目按"现状"提供，不构成任何形式的保证或承诺；因使用本项目产生的任何后果由使用者自行承担。
- 下单、领券、抽奖等操作会真实产生费用或消耗账户权益，请务必在确认明细后再执行。
十、License
MIT © 2026 mcd-cn-assistant contributors
麦当劳、McDonald's、麦乐送、麦麦省等商标归麦当劳及其关联方所有。
⭐ 如果这个技能有帮助，请点个 Star
点一下仓库右上角的 Star —— 每一颗星都会让更多人发现它。
- 一颗星 = 一次免费的"做得好"，也是这个项目继续迭代下去的动力；
- Star 数是本作品在麦当劳程序员创意开发大赛中的唯一排名依据，你的支持直接决定它能被多少人看到；
- 顺手 Fork 一下，或者把它分享给正在被"群点算账"折磨的同事，同样帮大忙。