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 在定位门店前会主动问一句「这单是你自己吃，还是帮几个人一起点（拼单）？」，再据此分流。多人拼单不需要用户自己想到，答一句"拼单"即可进入完整的分账流程；回答含糊时会再确认一次，不会默认按单人处理。

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 只读推送"]
    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 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 首页、公众号、门店海报，看到时往往已经结束；
• 优惠券种类多、门槛各异（满减 / 第二份半价 / 指定商品 / 限渠道），靠人脑判断哪种买法最便宜成本极高；
• 群点时刷屏报菜名记不住、满减档差几块钱没人算、配送费、打包费和优惠券没人分，收钱环节更是大型社死现场；
• 想拼单却不知道工具支持——多人点餐能力如果只能靠用户自己提起，等于不存在；本项目把它前置为点餐入口的主动提问；
• 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
├── config/
│   └── keywords.json          # 关注关键词配置（能力二读取）
├── references/
│   ├── mcd-tools.md           # 35 个 MCP 工具速查表 + 调用顺序 + 错误码
│   └── group-order.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 官方流程）

1. 打开 WorkBuddy，在左侧边栏【专家·技能·连接器】，选中【连接器】页签；

2. 点击右上角【自定义连接器】→【配置MCP】；

3. 在打开的手动配置页面中填入以下的 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} 这个写法本身。

4. 回到【自定义连接器】，将 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合作 / 品牌合作），并回显最新关键词列表。之后每天 09:00 自动查询当月活动，只推命中项；没有命中就明确说「今日无命中关键词的新活动」，不拿无关活动凑数。

你：不再关注联名了，改成关注新品

Agent：更新配置文件 → 回显最新列表。

能力三 · 最优惠点餐

你：两个人吃，到店取，怎么点最划算？我在静安寺附近（入口询问时已确认「一起吃、我自己付款」）

Agent：

1. 查附近门店 → 2. 查麦麦省可领券 + 我已有的券 + 该门店可用券 → 3. 拉菜单 →
2. 围绕券的门槛枚举 2~5 个候选组合 → 5. 逐个调 calculate-price 真算 → 6. 输出比价表：

方案	商品组合	使用券	商品金额	优惠	应付
✅ 最省	…	满 39 减 8	¥41.00	-¥8.00	¥33.00
备选	…	第二份半价	¥45.50	-¥7.25	¥38.25

1. 你说「就第一个」，才调 create-order 下单。

能力四 · 多人群点聚合

你：办公室下午茶，5 个人拼麦当劳外送到公司，帮我收单算账

（这条诉求也可以只由入口的一句「帮几个人一起点」触发——不必像这样一次性说全）

Agent：

1. 开单：确认门店 / 地址与三项分摊偏好（公共费用怎么摊？券省的归你还是平摊？接受凑单建议吗？）→ 创建订单会话；
2. 收单：你逐个转述——"张三 板烧鸡腿麦满分单人餐×1""李四跟张三一样""王五撤销"——每次变动后增量回显聚合列表与小计；多人点了同款会自动合并并问"要不要分开包装"；
3. 收完单进入算账：
   • 盘券（下单人账户）：命中你的「9.9元中杯冰美式」，原价 ¥19.00 → 券后 ¥9.90（省 ¥9.10），已用 calculate-price 实算验证；
   • 券归属：按平摊规则，账单标注「券省 ¥9.10，每人减 ¥1.82」；
   • 公共费用 ¥9.00（配送费 ¥6.00 + 打包费 ¥3.00）按消费比例分摊（尾差兜底，保证合计严格等于实付）；
   • 凑单判定：算价未返回满减档位 → 直接说明"本单无凑单空间"，不臆造门槛、不自动加购；
4. 输出账单（以下为真实实测数据，门店 storeCode 1421053）：

成员	餐品	券前小计	分摊券省	分摊公共费	应付
张三 👑	板烧鸡腿麦满分单人餐×1	¥21.90	-¥1.82	¥1.76	¥21.84
李四	芝芝火腿扒堡三件套×1	¥19.90	-¥1.82	¥1.60	¥19.68
王五	猪柳蛋麦满分×1，脆薯饼×1	¥28.00	-¥1.82	¥2.26	¥28.44
赵六	麦咖啡™冰奶铁中杯×1，香芋派×1	¥22.90	-¥1.82	¥1.85	¥22.93
钱七	麦咖啡™冰美式中杯×1	¥19.00	-¥1.82	¥1.53	¥18.71
合计		¥111.70	-¥9.10	¥9.00	¥111.60

✅ 校验：Σ每人应付 ¥111.60 = calculate-price 实付总额 ¥111.60。

1. 你确认账单后调 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

六、设计原则与安全边界

这是本项目区别于"把工具列表塞给模型"的核心：

1. 写操作必须二次确认。 create-order、auto-bind-coupons、cancel-order、draw-lottery、mall-create-order、party-order-create、delivery-create-address 等会花钱、耗积分或改变账户状态的调用，必须先向用户列清明细并获得明确同意，严禁静默执行。
2. 算价不靠心算。 一切金额以 calculate-price 的返回为准。券面文字不等于真实优惠（门槛、渠道、指定商品都会影响），必须真跑一遍。
3. 时间不靠模型记忆。 涉及日期一律调用 now-time-info。
4. 限流友好。 串行调用、复用会话内已获取的结果，不做无意义的重复查询。
5. 只做该做的事。 定时推送任务被明确限定为"只读"，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、麦乐送、麦麦省等商标归麦当劳及其关联方所有。