name: mcd-party-officer agent_created: true description: 麦当劳门店派对/包场/拼团的选址、成团调度与筹备助手。当用户想办生日派对、亲子派对、主题派对、品鉴会、读书会、麦麦体验营，或说「麦当劳派对」「派对拼团」「包场」「生日会怎么办」「哪家店能办派对」「还差几个人成团」「包场还是拼团划算」「帮我写拼团招募文案」「做一张派对邀请函」「孩子派对吃什么不超标」时使用。基于麦当劳官方 MCP（mcp.mcd.cn）的 party 系列工具：扫描全城场次、估算成团概率、对比包场与拼团成本、按官方营销活动日历挑最佳日期、审查儿童餐营养、生成招募卡与邀请函。

派对拼团官（McDonald's Party Officer）

麦当劳门店派对在 MCP 里是一条完整但几乎无人使用的业务线：城市 → 门店 → 可约日期 → 场次（含成团人数与余位）→ 下单，五个工具环环相扣。

本 Skill 不是"帮你订个派对"，而是一整套派对决策系统。官方规则写着两条关键约束：

• 拼团若未在截止前凑够人数会自动取消并退款
• 需提前 3 天预订

于是就产生了四个真实问题，也正是本 Skill 的四大能力：

再加上三个能直接拿去用的产出物：拼团招募卡（发群）、派对邀请函（可分享 HTML）、筹备时间线（T-7→T 待办 + 预订截止倒计时）。

When to use

• 选址与成团：「想给孩子办麦当劳生日会」「附近哪家店能办派对」「还差几个人成团」
• 决策：「包场还是拼团」「多少钱」「有没有余位」「最近哪天有活动」
• 健康：「开心乐园餐这套搭配适合小孩吗」「怎么换更健康」
• 传播：「帮我写个拼团招募文案」「做张派对邀请函发群里」
• 其它派对型商品：主题派对、麦麦体验营、品鉴会、读书会、积分兑换活动

八大能力总览

派对业务关键规则（来自官方商品说明，务必向用户复述）

价格、人数门槛、适用人群因商品而异，一律以 mall-product-detail 返回的 note 与 skuList[].price 为准。

执行流程

第 0 步：确定派对商品（spuId）

mall-points-products({"catRuleIds": "1>6>20"})   # 生日类派对
mall-points-products({"catRuleIds": "1>6>21"})   # 主题类派对
mall-points-products({"catRuleIds": "1>6>22"})   # 麦麦体验营
mall-points-products({"catRuleIds": "1>6>25"})   # 品鉴会
mall-points-products({"catRuleIds": "1>6>34"})   # 读书会
mall-points-products({"catRuleIds": "1>6>40"})   # 积分兑换活动

拿到 spuId 后，用 mall-product-detail({"spuId": ...}) 读取 skuList[].skuId（下单必需）与 note。

第 1–4 步：扫描场次（核心）

query-party-city({"spuId": 1779})                       → 城市列表（code / 经纬度）
query-party-store({"code": "330100",                    → 可承办门店（含 distance / 营业状态）
                   "spuId": 1779,
                   "latitude": ..., "longitude": ...})
query-party-store-date({"spuId": 1779,                  → 可预约日期
                        "storeCode": "3330206"})
query-party-store-session({"spuId": 1779,               → 场次（时间/成团人数/价格/余位）
                           "storeCode": "3330206",
                           "dateStr": "2026-10-14"})

第 5 步：成团调度排序

对每个候选场次打分（scripts/party_officer.py::score），五维：成团可行性（硬约束）、余位紧张度、时段匹配、价格、距离。 输出三个视图：推荐 Top N、最易成团、余位告急。

第 6 步：下单（必须二次确认）

party-order-create({"partyType": 1,        # 1=包场，2=拼团
                    "spuId": 1779, "skuId": 2027,
                    "storeCode": "3330206", "code": "330100",
                    "dateStr": "2026-10-14",
                    "id": 36825489,        # 场次 id
                    "leftNum": 12, "count": 6})

未经用户明确确认，禁止调用下单类工具。

创意增强模块（差异化所在）

以下模块全部为纯算法 + 官方数据，不依赖模型猜测，结果可复现、可解释。

① 成团概率雷达 formation_radar(date, sess, headcount)

输出 prob(5~95%) / level / gap(还差几人) / reasons(逐条依据) / pitch(可直接发群的拉人话术)。

评分依据（透明可查）：是否达成团线（基础 68，每差 1 人 −11）／余位是否够用（+8 / +2 / −22）／筹备窗口（3–7 天 +10，≤2 天 −16）／周末 +7 ／晚市 +4。

② 包场 vs 拼团 compare_modes(sess, headcount)

给出两种模式的总价、确定性、推荐结论。要点：包场按 max(人数, 起订数) 计费换取"确定举办"；拼团按实际人数计费但承担未成团退款风险。同价时优先包场。

③ 派对黄历 party_almanac(cli, dates, sessions_by_date, headcount)

把 campaign-calendar（markdown 文本，需 raw_text=True 解析）的官方活动日与场次余位结合，逐日评分： 有官方活动 +18 ／周末 +12 ／余位充足 +10 ／满足提前 3 天 +8 ／不满足 −30。 输出 宜 / 可 / 忌 与"当月有活动的日期"清单。

④ 儿童营养安心指数 kids_nutrition_audit(cli, combo)

数据源 list-nutrition-foods（158 个餐品的表格文本，藏在 JSON 的 data 字段里，需二次解析）。 对一份餐单算合计热量/脂肪/钠/碳水，按超出参考上限的比例扣分，给 A/B/C 评级，并自动给出替换建议（如「中薯条→小薯条 = 钠 −45mg、热量 −79kcal」）。

参考区间为儿童单餐：热量 400–700 kcal、钠 ≤800 mg、脂肪 ≤26 g。这是本模块唯一的硬编码标准，需向用户说明是参考值而非官方结论。

⑤ 筹备时间线 party_timeline(date)

输出 T-7 → T 日待办与预订截止倒计时（截止日 = 活动日 − 3 天），并在 ≤3 天时给出强提醒。

⑥ 招募卡 / 邀请函

• render_recruit_card(...) → 带余位进度条的群消息文本
• render_invite_html(...) → 麦当劳红黄配色的单文件邀请函（浅色、可直接分享）

⑦ 四宫格比选 scout_grid(ranked)

一屏给出：最优综合 / 最省人均 / 最近门店 / 空位最多。

输出规范

给用户的最终答复建议为四段：

1. 商品与规则：派对名称、人均价、成团区间、提前预订天数、适用人群
2. 推荐场次表：门店 | 日期 | 时段 | 人均 | 余位 | 成团概率 | 推荐理由
3. 决策建议：包场还是拼团 + 最佳日期 + 筹备截止提醒
4. 可复制产出：招募卡文本（或邀请函文件路径）+ 是否代下单的确认问句

金额一律显示为「元」（接口单位为分，需 /100）。

代码入口

export MCD_MCP_TOKEN=<your_token>          # https://open.mcd.cn/mcp 免费领取
python scripts/demo.py                       # 基础演示（成团调度）
python scripts/demo_plus.py                  # 创意增强演示（八大能力全量）

from scripts.party_officer import plan
from scripts.party_plus import formation_radar, compare_modes, party_almanac, \
     kids_nutrition_audit, party_timeline, render_recruit_card, render_invite_html, scout_grid

res = plan("杭州市", 1779, headcount=6, budget=60, prefer_time="dinner")
top = res["best"][0]
radar = formation_radar(top["date"], top["sess"], 6)     # 成团概率
modes = compare_modes(top["sess"], 6)                    # 包场 vs 拼团
audit = kids_nutrition_audit(cli, ["吉士汉堡包", "中薯条", "可乐中杯"])  # 营养

• scripts/mcd_client.py —— MCP 通用客户端（35 工具，仅标准库）
• scripts/party_officer.py —— 扫描 + 五维成团调度评分
• scripts/party_plus.py —— 七个创意增强模块
• references/party_flow.md —— 链路详解与字段字典
• references/tools.md —— 全量工具速查

边界与注意事项

• 只读优先：除 party-order-create 外全部为只读调用，可放心批量扫描。
• 两种响应格式：多数工具返回 JSON（用 extract_json 解析）；campaign-calendar 与 list-nutrition-foods 返回文本/表格，需 raw_text=True 或取 data 字段后二次解析。
• 团餐接口不稳：query-meals / query-promotions 依赖门店营业状态，非营业时段会返回「门店可能已关闭或不在营业时间」，不要作为核心链路依赖。
• 城市匹配：query-party-city 返回全国城市，按名称宽松匹配（"杭州" 可命中 "杭州市"）。
• 门店筛选：只保留 businessStatus == 1 且 onlineBusinessStatus == true 的门店。
• 限流：单 Token 600 请求/分钟；扫描请求数 = 门店数 × 日期数，建议 max_stores ≤ 8、max_dates ≤ 3。
• Token 安全：只从环境变量读取，不要写入代码或提交到仓库。

🍟 派对拼团官 · McParty Officer

麦当劳门店派对最怕的不是贵，是凑不齐人。 一句话问出去，回来一张「这场到底办得成吗」的确定性答案。

官方规则写明：拼团未在截止前凑够人数会自动取消并退款。 本项目把派对从「怎么策划」推进到「到底办不办得成」：算成团概率、比包场与拼团、挑最值的日子、一键生成招募卡把人群拉满，并给出预订截止倒计时。

别人帮你策划一场派对；我们帮你把人凑齐、把场锁定、把日子挑对、把人喊来。

上图为 2026-10-09 用真实 Token 跑通的原始输出，未做美化、未替换数据。

🎬 先看效果：在线演示（免安装、免 Token）

🍟 打开在线演示页 —— 浏览器直接点： 切换人数（4 / 6 / 9 人），看成团概率雷达、包场 vs 拼团对比、招募卡与邀请函的完整输出。 页面为 2026-10-09 真实 Token 跑通的快照（由本仓库 scripts/party_plus.py 真实函数计算固化），不是实时查询，已明确标注。

🚀 三步开吃

第 1 步 · 把这段话整段发给 WorkBuddy（不用碰命令行）

帮我安装这个技能：https://github.com/yzg1226/mcd-party-officer
把仓库内容放到用户级技能目录 ~/.workbuddy/skills/mcd-party-officer/
（SKILL.md 与 scripts/ 需同级保留），确认 SKILL.md 存在，装完提醒我重开一轮会话

熟手可用命令行（效果一样，重复执行即更新）：

git clone https://github.com/yzg1226/mcd-party-officer.git ~/.workbuddy/skills/mcd-party-officer

卸载：rm -rf ~/.workbuddy/skills/mcd-party-officer

第 2 步 · 对它说一句话

「帮我给 6 岁的女儿办一场麦当劳生日会，杭州，6 个人，晚上办」

它会自己确认城市、扫场次、算成团概率，最后把决策摆在你面前。

第 3 步 · 贴一次 Token，以后一直免配置

第一次使用时按提示到 https://open.mcd.cn/mcp 登录 → 控制台 → 激活 → 复制 Token，粘进对话即可。 Token 只写进你本机的环境变量或 WorkBuddy 配置，不进仓库、不进日志、不在回复里回显。

⚠️ Token 等同账号凭证：只贴在自己的对话里，不要发群聊、朋友圈或 GitHub。

📖 目录

30 秒看懂：它和别的派对 Skill 差在哪

派对赛道已有两类做法，都很不错，但都停在下单之前：

差异不在功能多少，而在是否回答了那个真正会导致派对泡汤的问题：

「未成团自动退款」这条规则，只有先发现它，才会意识到真问题是凑人而不是策划——这就是本项目的立足点。

两个能直接发出去的产出物

工具产出数字容易，产出能传播的内容难。派对是麦当劳场景里唯一自带"发出去"动作的品类：

邀请函为单文件 HTML，麦当劳红黄配色，可直接分享；上图为真实渲染结果。 招募卡为纯文本，复制即可粘贴到任意群聊。

一、痛点：派对最容易死在"凑不齐人"

麦当劳门店派对的官方规则里有两条硬约束，它们决定了这个场景真正的难点：

于是用户在真实场景里会连续撞上四个问题：

1. 哪家店、哪天、哪一场，我最可能凑满人？ —— 余位和成团区间全在门店端，没法自助比价
2. 包场还是拼团？ —— 两种模式价格与风险不同，没人会算
3. 未来哪天办最值？ —— 官方营销活动日历是公开的，但没人拿它做决策
4. 怎么快速把人凑齐？ —— 发群、催人、统计，全靠人肉

二、本项目解决什么

四个决策

三个产出物

一个扫描视图

五维成团调度评分：成团可行性（硬约束）→ 余位紧张度 → 时段匹配 → 价格 → 距离，输出三个视图：推荐 Top N / 最易成团 / 余位告急，以及一屏四宫格（最优综合 / 最省人均 / 最近门店 / 空位最多）。

三、快速开始

1. 获取 MCP Token

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

每个 Token 每分钟最多 600 次请求，Token 请勿写入代码或提交到仓库。

2. 配置 MCP（可选）

若在支持 MCP 的客户端里使用，参考 mcp-config.example.json（脱敏示例，仅含环境变量占位符）。

3. 运行

export MCD_MCP_TOKEN=<你的 MCP Token>      # Windows: set MCD_MCP_TOKEN=...

python scripts/demo.py          # 基础演示：成团调度扫描
python scripts/demo_plus.py     # 完整演示：八大能力全量

零第三方依赖，仅使用 Python 标准库（3.7+）。

四、使用示例

对话式（在 WorkBuddy / Claude Code 等客户端中）

用户：帮我给 6 岁的女儿办一场麦当劳生日会，杭州，6 个人，预算每人 60，想晚上办

派对拼团官：
【商品与规则】麦当劳奇妙生日派对 · 人均 ¥50 · 5~12 人成团 · 需提前 3 天预订 · 面向 4-12 岁
【推荐场次】
门店                  日期          时段    人均   余位   成团概率   理由
杭州大厦501城市广场    2026-10-14   18:30   ¥50    12     90%       已达 5 人成团线 / 晚市热度高 / 筹备期 5 天
...
【决策建议】推荐包场（与拼团同价，但 100% 确定举办）；最佳日期 10-14（当天有官方活动）
【提醒】预订截止 10-11，仅剩 2 天
【可复制产出】<拼团招募卡文本>

代码式

from scripts.party_officer import plan
from scripts.party_plus import formation_radar, compare_modes, kids_nutrition_audit

res   = plan("杭州市", 1779, headcount=6, budget=60, prefer_time="dinner")
top   = res["best"][0]
radar = formation_radar(top["date"], top["sess"], 6)     # 成团概率 90%
modes = compare_modes(top["sess"], 6)                    # 包场 vs 拼团
audit = kids_nutrition_audit(cli, ["吉士汉堡包", "中薯条", "可乐中杯"])

真实运行输出（2026-10-09 实测）

① 成团概率雷达
场次：杭州大厦501城市广场餐厅 2026-10-14 18:30
成团概率：90%（高，可放心订）｜ 还差 0 人 ｜ 距活动 5 天

② 包场 vs 拼团
包场 6 人 ¥300  100%（确定举办）
拼团 6 人 ¥300  取决于成团（未成团自动退款）
结论：推荐【包场】

④ 儿童营养安心指数
吉士汉堡包 + 中薯条 + 可乐中杯 = 730 kcal / 脂肪 24g / 钠 838mg
安心指数：79 分 → B（尚可，建议微调）
  把「中薯条」换成「小薯条」→ 钠 -45mg、热量 -79kcal

五、能力清单

算法细节与阈值见 references/creative_modules.md。

六、目录结构

mcd-party-officer/
├── SKILL.md                          # 技能主文件（Agent 运行时加载）
├── README.md                         # 本文件
├── CONTEST_DECLARATION.md            # 参赛声明（官方原文，未改动）
├── MCP_INTEGRATION.md                # MCP 接入说明
├── mcp-config.example.json           # 脱敏配置示例
├── workbuddy.md                      # WorkBuddy 开发对话上下文
├── docs/                             # README 预览图
├── examples/sample_invite.html       # 邀请函产物示例
├── scripts/
│   ├── mcd_client.py                 # MCP 通用客户端（仅标准库）
│   ├── party_officer.py              # 扫描 + 五维成团调度评分
│   ├── party_plus.py                 # 七个创意增强模块
│   ├── demo.py                       # 基础演示
│   └── demo_plus.py                  # 完整演示
└── references/
    ├── party_flow.md                 # 业务链路与字段字典
    ├── tools.md                      # 全量工具速查 + 响应格式陷阱
    └── creative_modules.md           # 创意模块算法说明

七、目标用户

• 有孩子的家庭：想办生日会，但不清楚哪家店能办、哪场最容易凑满人
• 公司行政 / 团建组织者：需要在小预算下组织团体派对
• 朋友聚会组局人：需要快速招募、统计人数、把场锁定
• 门店端运营：可用于观察余位分布与成团难度

八、隐私与安全

• Token 只从环境变量读取，不写入代码、不提交仓库（mcp-config.example.json 仅含占位符）
• 全流程只读优先：除下单接口 party-order-create 外均为只读调用；下单必须经用户二次确认
• 不在日志或输出中展示任何个人凭证信息
• 项目输出仅供参考，不构成医疗、营养或其他专业建议；餐品信息、价格与供应状态以麦当劳官方渠道实时结果为准

九、参赛信息

• 参赛活动：麦当劳程序员创意开发大赛（1024 程序员节）
• 开发工具：腾讯 WorkBuddy
• 参赛声明：CONTEST_DECLARATION.md
• 本项目为参赛作品，由参赛者独立开发，非麦当劳官方产品

参赛材料对照

© 2026 · 本项目为麦当劳程序员创意开发大赛参赛作品