name: mcd-experience-atlas description: 麦当劳体验活动地图。当用户想查询麦当劳的生日派对、主题派对、亲子读书会、品鉴会、体验营等体验类活动「在哪些城市能办、哪家门店可以、哪天可约、几点有场次、还剩多少位、多少钱、多少人起订」时使用本技能。也可用于查询麦当劳餐品营养（160 项）与积分抽奖奖池。查询与下单均通过麦当劳官方 MCP；下单默认关闭，仅在用户精确说出「确认创建订单」并核对订单指纹后才会执行。 description_en: McDonald's China experience-activity atlas. Use when the user asks where a McDonald's birthday party, themed party, reading club, tasting event or experience camp can be booked, which stores offer it, which dates and sessions are available, how many slots remain, the price and the minimum party size. Also covers McDonald's menu nutrition (160 items) and the points-lottery prize pool. Ordering is disabled by default and only fires after the user says the exact phrase "确认创建订单" and confirms the order fingerprint. license: MIT allowed-tools:

• mcp__mcd-mcp__mall-points-products
• mcp__mcd-mcp__mall-product-detail
• mcp__mcd-mcp__query-party-city
• mcp__mcd-mcp__query-party-store
• mcp__mcd-mcp__query-party-store-date
• mcp__mcd-mcp__query-party-store-session
• mcp__mcd-mcp__list-nutrition-foods
• mcp__mcd-mcp__query-lottery-info
• mcp__mcd-mcp__campaign-calendar
• mcp__mcd-mcp__now-time-info disable: false

麦当劳体验活动地图

把麦当劳体验活动的可预约性，从「App 里逐级翻五步」变成「一次查询」。

何时使用

• 用户问「麦当劳生日派对哪里能办」「成都有没有麦当劳派对」
• 用户问「这家店这周六还有派对场次吗」「多少钱」「几个人起」
• 用户问「麦当劳品鉴会 / 读书会 / 体验营怎么参加」
• 用户问「麦当劳哪个餐品热量最高」（走 list-nutrition-foods）
• 用户问「积分抽奖有什么奖品」（走 query-lottery-info）

数据来源与链路

入口是积分商城，不是独立的派对工具：

mall-points-products                    → 取体验类 SPU（shopId=5）
  → mall-product-detail(spuId)          → skuId / partyType / 人数与年龄规则 / 提前预订天数
    → query-party-city(spuId)           → 该品类可预约城市（281 个）
      → query-party-store(code,lat,lng) → 该城市可办门店
        → query-party-store-date        → 可约日期（滚动）
          → query-party-store-session   → 场次：时段 / 人数 / 价格 / 余位
            → party-order-create        → 下单（写操作，默认关闭，见下）

下单：带确认闸，默认关闭

party-order-create 是写操作，默认不调用。仅在下列条件全部满足时才执行：

1. 用户精确说出「确认创建订单」——「试试看」「可以就下单」「如果可以就下单」 等模糊措辞一律视为未确认；
2. 用户核对过完整回显（活动 / 门店 / 日期 / 场次 / 人数 / 单价 / 预估总额）；
3. 用户提供的订单指纹与当前参数算出的一致（防止「确认的是 A、下单的是 B」）；
4. 前置校验通过：人数在 [partyMin, partyMax] 内、余位 > 0、shopId == 5、 partyType 与商品规则一致、满足提前预订天数。

执行入口是 src/book.py，两步式：

# 第一步：只读，任何时候都安全，可反复运行
python src/book.py --spu-id 8516 --city 南宁市 --store 3570247 \
    --date 2026-10-17 --session 36915550 --count 6
# → 回显全部要素 + 订单指纹，并给出第二步命令

# 第二步：写操作，真实创建订单
python src/book.py --spu-id 8516 --city 南宁市 --store 3570247 \
    --date 2026-10-17 --session 36915550 --count 6 \
    --confirm 确认创建订单 --fingerprint <第一步给出的指纹>

绝不重试 party-order-create。 若订单已创建但响应未读回，重试会产生重复订单； 遇到失败或超时，应引导用户去麦当劳 App「我的订单」人工核对，而不是自动重试。

本地快照模式

data/atlas.json 内置 2026-10-13 的全国快照（281 城 / 3665 门店 / 159 场次）， 无 Token 时直接读取该文件即可回答「哪里能办」类问题； 涉及「这周还有没有位」等实时问题时再调用 MCP。

硬约束

1. 下单默认关闭：仅满足上述「下单：带确认闸」全部条件时才调用 party-order-create； 其余写操作（create-order / cancel-order / mall-create-order / draw-lottery / auto-bind-coupons / delivery-create-address）一律禁止。
2. 金额单位是分：price 字段 13800 表示 ¥138.00，展示前必须除以 100。
3. 日期必须实时获取：涉及「今天 / 这周 / 还能约吗」时，先调 now-time-info， 不要凭模型记忆推断日期。
4. 余位可能为 0：leftNum 为 0 表示已满，不要推断为「可约」。
5. 不要编造门店：所有门店信息必须来自 MCP 返回或 data/atlas.json， 不得凭常识补充未返回的门店。
6. 人数规则来自商品详情：起订人数、单场上限、适用年龄以 mall-product-detail 返回的 partyPeople / partyAge / partyRange 与场次的 partyMin / partyMax 为准， 不要自行假设。
7. 不替用户做资金决策：只展示单价与预估总额，实际应付以服务端与麦当劳侧为准。

参考文档

• MCP_INTEGRATION.md —— 完整链路、接口特性与应对
• data/tools_reference.md —— 35 个工具的完整描述与入参 Schema
• README.md —— 项目介绍与复现方式

麦当劳体验活动地图 · mcd-experience-atlas

281 个城市 · 3664 家可办门店 · 157 个场次 · 26 款体验活动 —— 全部来自麦当劳官方 MCP 实测采集 「我在成都，能办麦当劳生日派对吗？哪家店？多少钱？这周六还有位吗？」——一次查询就有答案。 生日派对、主题派对、亲子读书会、品鉴会、体验营，在全国哪些城市、哪些门店、什么时段可以预约。

🗺️ 在线体验（无需安装，打开即用）：https://johnny37.github.io/mcd-experience-atlas/

独家发现：26 款活动里，有 2 款全国一个城市都约不到

全量采集 3664 家门店、26 款体验活动之后，有两个结论是官方 App 里查不到的：

这也是本项目存在的理由 —— 官方的 App 只能逐级点开试，而这个对比视角只有把数据全拉通才能算出来。

一键分享你城市的链接

点击地图上任意城市后，地址栏会自动带上 ?city=城市名，右上角 「复制我这城市链接」 一键复制。 发到群里，别人打开直接落到你那座城 —— 不用自己再翻地图。

https://johnny37.github.io/mcd-experience-atlas/?city=成都市
https://johnny37.github.io/mcd-experience-atlas/?city=北京市

演示动图

分享海报

想转给朋友？复制这句就行 👇 孩子生日想办麦当劳派对？全国 281 城 3664 家门店哪里能办、多少钱、这周六还有没有位，一张地图查完 → https://johnny37.github.io/mcd-experience-atlas/

顺带一提：26 款活动里有 2 款全国一个城市都约不到 → https://johnny37.github.io/mcd-experience-atlas/

想基于它做点什么？

本仓库不只是个成品网页 —— src/toon.py（通用 TOON 解析器）、src/mcp_client.py（封装了麦当劳 MCP 的 14 个接口坑）、data/ 下的开放数据集都可以直接拿走用。 具体怎么 fork、怎么改、哪些模块能复用，见 CONTRIBUTING.md。

一、项目介绍

一句话定位

「我在成都，能办麦当劳生日派对吗？哪家店？多少钱？这周六还有位吗？」——一次查询就有答案。

麦当劳的体验活动（生日派对 / 主题派对 / 品鉴会 / 亲子读书会 / 体验营）分散在 App 的深层路径里， 用户需要逐级确认「城市有没有 → 哪家门店能办 → 哪天可约 → 几点有场 → 还剩多少位」。 本项目把这条链路的数据一次拉通，做成一张可以点开的全国地图。

核心数据（2026-10-13 实测快照）

它解决什么问题

官方 App 里，上述五个问题需要逐级点开、逐个城市试才能回答，且没有任何横向对比视角。 本项目把这些数据一次拉通后，可以直接回答：

• 我所在的城市能办哪些麦当劳体验活动？
• 哪家门店能办？这周还有没有场次？多少钱？几个人起订？
• 全国范围内，哪些活动其实「一个城市都约不了」？
• 同样叫「生日派对」，不同城市能办到的款式差多少？

最后一条是本项目独有的指标——体验丰富度（按可体验 SPU 款数计）： 全国中位数 18 款，最少 8 款，最多 23 款（福州 / 龙岩 / 泉州并列第一）。

二、安装方法

环境要求

安装步骤

# 1. 获取代码
git clone https://github.com/johnny37/mcd-experience-atlas.git
cd mcd-experience-atlas

# 2. （可选）验证安装 —— 无需 Token，纯本地运行
python tests/test_toon.py               # 19 项
python tests/test_data_pack.py          # 20 项
python tests/test_booking_gates.py      # 35 项
python tests/test_contest_compliance.py # 24 项
# → 共 98 项，全部通过即说明环境就绪

# 3. 查看地图（无需 Token）
python -m http.server 8000
#    浏览器打开 http://localhost:8000/web/

在线预览（GitHub Pages）

仓库根目录的 index.html 是数据完全内联的单文件版本， 因此可以直接用 GitHub Pages 托管，访客打开链接即可看到地图，无需 clone：

Settings → Pages → Build and deployment → Source: Deploy from a branch
           → Branch: main / (root) → Save

本仓库已启用 GitHub Pages，在线地址：https://johnny37.github.io/mcd-experience-atlas/。 本仓库的 dist/index.html 与根目录 index.html 内容相同，均可单独分享。

配置 MCP Token（仅采集新数据时需要）

Token 在 https://open.mcd.cn/mcp 用手机号登录后申请。本项目按以下优先级读取，不接受也不生成任何本地凭证文件：

1. 环境变量 MCD_MCP_TOKEN；
2. WorkBuddy 的 ~/.workbuddy/mcp.json 中 mcd-mcp 连接器已配置的凭证 （在 WorkBuddy 中接入过自定义连接器时自动生效，零额外配置）。

# 方式 A：环境变量
export MCD_MCP_TOKEN="你的 Token"

# 方式 B：在 WorkBuddy 中接入连接器（推荐）
#   左侧边栏 → 连接器 → 自定义连接器 → 配置 MCP，填入：
#   { "mcpServers": { "mcd-mcp": {
#       "type": "streamablehttp",
#       "url": "https://mcp.mcd.cn",
#       "headers": { "Authorization": "Bearer YOUR_MCP_TOKEN" } } } }
#   之后直接运行采集脚本即可，无需再设置环境变量。

配置模板见 mcp-config.example.json（仅含 ${MCD_MCP_TOKEN} 占位符）。

作为 Agent Skill 安装

本仓库同时是一个可被任意 MCP 客户端加载的 Agent Skill。将仓库路径加入客户端的技能目录即可， SKILL.md 已按 WorkBuddy 标准格式声明了所需的 9 个只读工具与使用约束。

三、使用示例

示例 1：查看地图（最常用，无需 Token）

三种方式任选：

# A. 本地起服务（数据走 data/atlas.json）
python -m http.server 8000
#    打开 http://localhost:8000/web/

# B. 直接双击根目录的单文件版（数据已内联，无需服务器、无需 Token）
#    index.html

# C. 在线访问（零安装）：
#    https://johnny37.github.io/mcd-experience-atlas/

页面上可以做的事：

• 切换视图：「体验丰富度」看各城市能办多少款活动；「可办门店数」看门店密度；
• 筛选品类：下拉选择「生日类派对 / 主题类派对 / 品鉴会 / 读书会」， 地图即时高亮该品类可约的城市，不可约的缩为灰点；
• 点选城市：右侧显示该城全部可办门店、7 天可约日期与每日场次数、场次时段与余位；
• 搜索：输入「东单」可直接定位到麦当劳北京东单北大街餐厅；
• 城市深链：地址栏自动带上 ?city=城市名，也可直接访问 ...?city=成都市 打开即定位； 点右上角「复制我这城市链接」一键复制，发给别人直接落到你那座城；
• 离线分享：直接双击根目录 index.html 或 dist/index.html，数据已内联，不需要服务器。

示例 2：采集最新数据（需要 Token）

python src/collect.py                    # 全量：281 城门店 + 79 城场次抽样
python src/collect.py --deep             # 深采：每个城市首店都取日期与场次
python src/collect.py --resume           # 中断后续采，跳过已完成的城市
python src/build_atlas.py                # 打包成 web/ 使用的 data/atlas.json

实际输出：

[0/7] tools/list → 35 个工具
[1/7] mall-points-products → 50 个 SPU
[2/7] 体验品类城市覆盖 {'读书会': 281, '生日类派对': 281, '主题类派对': 279, '品鉴会': 36} → 去重后 281 城
[3/7] 门店采集完成 → 3664 家
[4/7] 场次抽样 → 79 城 / 157 个场次
[5/7] list-nutrition-foods → 160 项（TOON 已解析）
[6/7] query-lottery-info → 麦麦积分抽奖，10 项奖品，单次 24 积分
[7/7] campaign-calendar → 13 天 / 27 个事件

示例 3：作为 Agent Skill 对话使用

加载本仓库为 Skill 后，可以直接这样问：

用户：我在成都，想给孩子办个麦当劳生日派对，这周六还有位吗？多少钱？

Skill 会依次调用 mall-points-products → query-party-city → query-party-store → query-party-store-date → query-party-store-session，回答：

成都可以办 6 款生日派对（开心鸭尊享版、迪士尼疯狂动物城主题尊享版等）， 全市有 97 家门店可办，你能体验的活动共 20 款，高于全国中位数（18 款）。

以成都高新区大魔方餐厅的采样场次为例，10-14 至 10-22 连续 9 天可约， 这周六（10-17）有 2 个场次：10:30–12:00 和 14:00–15:30， 5~12 人，当前各余 12 位。注意这是「亲子读书会」品类的场次与价格（¥45.00）， 生日派对的场次时间与价格需按具体 SPU 再查一次。实际下单请在麦当劳 App 或门店完成。

Skill 内置的硬约束（见 SKILL.md）：只读，禁止调用任何写操作工具； 金额单位为分需自行换算；涉日期必须实时调用 now-time-info；不得编造未返回的门店。

示例 4：运行测试

python tests/test_toon.py
python tests/test_data_pack.py

四、地图功能

五、预约功能（带确认闸，默认关闭）

地图与查询全部只读；src/book.py 额外提供了可真实下单的能力，但默认关闭， 只在满足下列全部条件时才创建订单：

1. 用户精确说出「确认创建订单」——「试试看」「可以就下单」等模糊措辞一律视为未确认；
2. 用户核对过完整回显（活动 / 门店 / 日期 / 场次 / 人数 / 单价 / 预估总额）；
3. 用户提供的订单指纹与当前参数算出的一致（防止「确认的是 A、下单的是 B」）；
4. 前置校验通过：人数在 [partyMin, partyMax] 内、余位 > 0、shopId == 5、 partyType 与商品规则一致、满足提前预订天数。

# 第一步：只读，任何时候都安全，可反复运行
python src/book.py --spu-id 8516 --city 南宁市 --store 3570247 \
    --date 2026-10-17 --session 36915550 --count 6

# 第二步：写操作，真实创建订单
python src/book.py --spu-id 8516 --city 南宁市 --store 3570247 \
    --date 2026-10-17 --session 36915550 --count 6 \
    --confirm 确认创建订单 --fingerprint <第一步给出的指纹>

实测回显效果（南宁水晶城餐厅，生日派对）：

活动名称   ：麦当劳一起开心鸭尊享版生日派对
派对类型   ：包场          人数规则：5-12 人（年龄 4-12）
门店       ：麦当劳南宁水晶城餐厅（青秀区金湖路61号）
预约日期   ：2026-10-17    场次：12:00 – 13:30   余位 12
参与人数   ：6 人          单价 ¥138.00/位      预估总额 ¥828.00
订单指纹   ：74E14B2F22B1

三条不可妥协的安全约束：

• 绝不重试 party-order-create——若订单已创建但响应未读回，重试会产生重复订单， 这是金钱相关的不可逆操作。mcp_client.call() 对写操作工具强制 retries=0。
• 默认黑名单——mcp_client.WRITE_TOOLS 默认拦截全部 7 个写操作工具， 须显式 allow_write=True 才放行，且只有 book.py 会这么做。
• 审计留痕——每次下单尝试写入 data/booking_audit.log，便于事后核对。

这些约束由 tests/test_booking_gates.py（35 项）锁定，全部离线运行、不发真实请求。

六、地图合规说明

默认视图是纯 SVG 散点图：只绘制城市坐标点与经纬网格，不描绘任何行政边界、不加载任何在线底图瓦片， 因此不涉及领土表示，可安全托管到 GitHub Pages 等任意静态空间。

如果你需要带底图的视图，请自行接入腾讯地图 / 高德 / 百度 / 天地图这四家具备资质的服务商， 并遵守《中华人民共和国测绘法》及相关地图合规要求。请注意：

• 禁止使用 Google Maps、Apple Maps、Bing 海外版、OpenStreetMap 及 Mapbox 等未取得境内测绘资质的来源；
• 前端代码中不要硬编码任何地图 Key，应通过自己的后端代理或域名白控；
• 本项目 data/ 中的经纬度来源于麦当劳 MCP 返回值，坐标系以官方为准， 接入不同底图前请自行核对是否存在 GCJ-02 / BD-09 偏移。

七、技术要点

这个项目的技术含量不在前端，而在摸清一条没有文档的链路。

1. 链路入口是积分商城，不是「派对工具」

query-party-city 这类工具的入参 spuId 来自 mall-points-products—— 也就是说，体验活动预约的入口是积分商城选商品，而不是某个独立的派对查询工具。 官方门户文档完全没有记载 query-party-* 系列，只读门户文档的开发者不会发现这条链路。

完整链路：

mall-points-products → query-party-city → query-party-store
  → query-party-store-date → query-party-store-session
  →（party-order-create，写操作，本项目不调用）

2. 接口返回不是纯 JSON

所有 tools/call 返回的是「Markdown 说明 + 内嵌一行原始 JSON」混合体。 不能取「第一行看起来像 JSON 的内容」——说明文档里也有 JSON 示例。 本项目从 {"success" 起用 JSONDecoder.raw_decode 找边界（见 src/mcp_client.py）。

3. 营养表是自研的 TOON 格式

list-nutrition-foods 返回的不是 JSON 数组，而是：

[160]{productName,nutritionDescription,energyKj,energyKcal,protein,fat,carbohydrate,sodium,calcium}:
  猪柳麦满分,null,1288,308,16,16,24,781,213
  巨无霸,null,2145,513,27,28,44,1010,190

坑在于：在原始 HTTP 响应文