🍟 麦麦全能助手 · McOmni

一句话，搞定吃麦全流程

领券 → 选店 → 配餐 → 比价 → 下单 → 派对预约 → 积分止损

基于麦当劳中国官方 MCP Server（mcd-mcp @ https://mcp.mcd.cn）构建的全能助手 Skill。

关于徽章：图片来自 shields.io，个别网络环境下可能加载较慢。README 的全部信息在正文中都有文字说明，徽章缺失不影响阅读。

目录

• 它解决什么问题
• 能力总览
• 快速开始
• 七大核心工作流
• 为什么它靠谱
• 项目结构
• 排障速查
• 安全与边界

🧩 它解决什么问题

麦当劳把 35 个能力开放给了 AI。但在真实账号上跑一遍就会知道：能调用 ≠ 会用。

flowchart TD
    U["👤 用户：想点个麦当劳"] --> Q{"🍽️ 怎么取餐？"}

    Q -->|"到店自取"| S1["query-nearby-stores<br/>→ storeCode"]
    Q -->|"麦乐送"| S2["delivery-query-stores<br/>→ storeCode + beCode"]
    Q -->|"得来速"| S3["query-nearby-stores<br/>→ storeCode + beCode"]

    S1 --> M["query-meals<br/>→ productCode"]
    S2 --> M
    S3 --> M
    M --> P["calculate-price<br/>→ takeWayCode"]
    P --> C["create-order<br/>→ orderId"]

    style Q fill:#FAEEDA,stroke:#854F0B,stroke-width:0.5px,color:#633806
    style P fill:#E6F1FB,stroke:#185FA5,stroke-width:0.5px,color:#042C53
    style C fill:#EAF3DE,stroke:#3B6D11,stroke-width:0.5px,color:#173404

每一环都必须来自上一环的返回值；中间任何一环猜错，订单就下不出去。

同时还要管住三件事：

McOmni 的价值不在"能调用工具"，而在知道什么时候不该调用——它把踩过的坑固化成硬约束，让 AI 在你的真实账号上安全地跑完整个流程。

🎯 能力总览

35 / 35 工具全覆盖，不只是检索类接口。

三种取餐方式全部支持：到店自取 / 麦乐送外送 / 得来速车道取餐。

🚀 快速开始

第 1 步 · 拿 Token

访问 https://open.mcd.cn/mcp，手机号登录 → 控制台 → 激活，一键复制 Token。

第 2 步 · 让助手能用上它

方式 A：作为 WorkBuddy Skill（推荐）

cp -r . ~/.workbuddy/skills/mcdonalds

然后在「连接器 → 自定义连接器」中填入配置（参考 mcp-config.example.json），把 ${MCD_MCP_TOKEN} 换成你自己的 Token。

方式 B：只用命令行通道（不需要任何 AI 客户端）

export MCD_MCP_TOKEN=<你的Token>
python scripts/mcd_cli.py list 优惠

# 找门店（searchType=2 按位置搜，city 与 keyword 必须同时传）
python scripts/mcd_cli.py call query-nearby-stores \
  '{"beType":1,"searchType":2,"city":"北京市","keyword":"鼓楼南街"}'

Token 解析顺序（任选其一即可）：

第 3 步 · 用起来

# 看有什么券，然后一键领掉
python scripts/mcd_cli.py call available-coupons
python scripts/mcd_cli.py call auto-bind-coupons

# 积分快过期了？先 dry-run 看方案，再决定花不花
python scripts/points_expiry_draw.py

🧭 七大核心工作流

⚠️ 工作流 4 需要特别说明：MCP 没有原生"玩具"接口，这是组合能力。若接口未返回玩具字段，助手会如实说明「本期接口未返回玩具信息」，不会编造款式。

🛡️ 为什么它靠谱

14 条防错铁律（节选）

完整 14 条见 SKILL.md。

三条设计原则

① 绝不臆造编码      一切 code 必须来自上游工具的返回值
② 副作用必二次确认   下单前必算价；抽奖前必展示消耗明细
③ 消耗性取舍交用户   不替用户决定花多少积分、要不要溢出

💡 积分到期止损：一个具体例子

麦当劳积分会过期。实测扣减顺序是 先扣将过期积分，不足才从其他积分扣，所以：

「是否溢出」 = 总消耗 > 「本月将过期积分」   （超出 1 分也算溢出）

python scripts/points_expiry_draw.py                          # 默认 dry-run，列出两套方案的代价
python scripts/points_expiry_draw.py --yes                    # 只花将过期积分
python scripts/points_expiry_draw.py --yes --allow-overflow   # 用户明确同意后才可溢出

flowchart LR
    A["读取将过期积分"] --> B["算可抽次数 N"]
    B --> C{"会溢出吗？"}
    C -->|"不会"| D["直接执行"]
    C -->|"会"| E["拒绝执行<br/>退出码 2"]
    E --> F["需显式加 --allow-overflow"]

    style C fill:#FAEEDA,stroke:#854F0B,stroke-width:0.5px,color:#633806
    style D fill:#EAF3DE,stroke:#3B6D11,stroke-width:0.5px,color:#173404
    style E fill:#FCEBEB,stroke:#A32D2D,stroke-width:0.5px,color:#791F1F

把决定权留给你，而不是"帮你想开一点"。

📂 项目结构

.
├── SKILL.md                     # 主文件：14 条铁律 + 7 大工作流 + 触发对照表
├── README.md
├── MCP_INTEGRATION.md           # 实际使用的 Server / Tool / 调用流程 / 业务价值
├── CONTEST_DECLARATION.md       # 参赛声明（官方原文件，未改动）
├── mcp-config.example.json      # 脱敏配置示例（仅环境变量占位符）
├── LICENSE
├── scripts/
│   ├── mcd_cli.py               # 零依赖 MCP 命令行通道（list / desc / call / raw）
│   └── points_expiry_draw.py    # 积分到期止损（dry-run / --yes / --allow-overflow）
└── references/
    ├── tools.md                 # 35 个工具完整参数手册
    └── workflows.md             # 字段级示例与 items 数组构造

🔧 排障速查

🔐 安全与边界

• Token 即身份：本项目不保存、不打印你的 Token。仓库中只保留 mcp-config.example.json 占位符示例，不包含任何真实凭证。
• 有副作用的操作需明确确认：下单、领券、抽奖、兑换均需用户确认后才执行。
• 本项目非麦当劳官方产品。餐品信息、价格与供应状态以麦当劳官方渠道的实时结果为准；项目输出仅供参考。

🏆 参与的活动

本项目为「麦当劳程序员创意开发大赛（M-CODE 1024）」参赛作品，由参赛者独立开发。

开发过程使用 腾讯 WorkBuddy，完整对话上下文见 workbuddy.md。

如果这个项目对你有帮助，欢迎点一个 Star ⭐

📄 License

MIT