Skip to content
Back to search

mcd-experience-atlas

SkillWorks with Claude CodeGitHub

麦当劳体验活动地图。当用户想查询麦当劳的生日派对、主题派对、亲子读书会、品鉴会、体验营等体验类活动「在哪些城市能办、哪家门店可以、哪天可约、几点有场次、还剩多少位、多少钱、多少人起订」时使用本技能。也可用于查询麦当劳餐品营养(160 项)与积分抽奖奖池。查询与下单均通过麦当劳官方 MCP;下单默认关闭,仅在用户精确说出「确认创建订单」并核对订单指纹后才会执行。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/johnny37--mcd-experience-atlas/badge.svg)](/listings/johnny37--mcd-experience-atlas)

HTML

<a href="/listings/johnny37--mcd-experience-atlas"><img src="/api/listings/johnny37--mcd-experience-atlas/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 100 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: mcd-experience-atlas
  3. description: 麦当劳体验活动地图。当用户想查询麦当劳的生日派对、主题派对、亲子读书会、品鉴会、体验营等体验类活动「在哪些城市能办、哪家门店可以、哪天可约、几点有场次、还剩多少位、多少钱、多少人起订」时使用本技能。也可用于查询麦当劳餐品营养(160 项)与积分抽奖奖池。查询与下单均通过麦当劳官方 MCP;下单默认关闭,仅在用户精确说出「确认创建订单」并核对订单指纹后才会执行。
  4. 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.
  5. license: MIT
  6. allowed-tools:
  7. - mcp__mcd-mcp__mall-points-products
  8. - mcp__mcd-mcp__mall-product-detail
  9. - mcp__mcd-mcp__query-party-city
  10. - mcp__mcd-mcp__query-party-store
  11. - mcp__mcd-mcp__query-party-store-date
  12. - mcp__mcd-mcp__query-party-store-session
  13. - mcp__mcd-mcp__list-nutrition-foods
  14. - mcp__mcd-mcp__query-lottery-info
  15. - mcp__mcd-mcp__campaign-calendar
  16. - mcp__mcd-mcp__now-time-info
  17. disable: false
  18. ---
  19. # 麦当劳体验活动地图
  20. 把麦当劳体验活动的可预约性,从「App 里逐级翻五步」变成「一次查询」。
  21. ## 何时使用
  22. - 用户问「麦当劳生日派对哪里能办」「成都有没有麦当劳派对」
  23. - 用户问「这家店这周六还有派对场次吗」「多少钱」「几个人起」
  24. - 用户问「麦当劳品鉴会 / 读书会 / 体验营怎么参加」
  25. - 用户问「麦当劳哪个餐品热量最高」(走 `list-nutrition-foods`)
  26. - 用户问「积分抽奖有什么奖品」(走 `query-lottery-info`)
  27. ## 数据来源与链路
  28. 入口是**积分商城**,不是独立的派对工具:
  29. ```
  30. mall-points-products → 取体验类 SPU(shopId=5)
  31. → mall-product-detail(spuId) → skuId / partyType / 人数与年龄规则 / 提前预订天数
  32. → query-party-city(spuId) → 该品类可预约城市(281 个)
  33. → query-party-store(code,lat,lng) → 该城市可办门店
  34. → query-party-store-date → 可约日期(滚动)
  35. → query-party-store-session → 场次:时段 / 人数 / 价格 / 余位
  36. → party-order-create → 下单(写操作,默认关闭,见下)
  37. ```
  38. ## 下单:带确认闸,默认关闭
  39. `party-order-create` 是写操作,**默认不调用**。仅在下列条件全部满足时才执行:
  40. 1. 用户**精确说出**「确认创建订单」——「试试看」「可以就下单」「如果可以就下单」
  41. 等模糊措辞一律视为未确认;
  42. 2. 用户核对过完整回显(活动 / 门店 / 日期 / 场次 / 人数 / 单价 / 预估总额);
  43. 3. 用户提供的**订单指纹**与当前参数算出的一致(防止「确认的是 A、下单的是 B」);
  44. 4. 前置校验通过:人数在 `[partyMin, partyMax]` 内、余位 > 0、`shopId == 5`、
  45. `partyType` 与商品规则一致、满足提前预订天数。
  46. 执行入口是 `src/book.py`,两步式:
  47. ```bash
  48. # 第一步:只读,任何时候都安全,可反复运行
  49. python src/book.py --spu-id 8516 --city 南宁市 --store 3570247 \
  50. --date 2026-10-17 --session 36915550 --count 6
  51. # → 回显全部要素 + 订单指纹,并给出第二步命令
  52. # 第二步:写操作,真实创建订单
  53. python src/book.py --spu-id 8516 --city 南宁市 --store 3570247 \
  54. --date 2026-10-17 --session 36915550 --count 6 \
  55. --confirm 确认创建订单 --fingerprint <第一步给出的指纹>
  56. ```
  57. **绝不重试 `party-order-create`。** 若订单已创建但响应未读回,重试会产生重复订单;
  58. 遇到失败或超时,应引导用户去麦当劳 App「我的订单」人工核对,而不是自动重试。
  59. ## 本地快照模式
  60. `data/atlas.json` 内置 2026-10-13 的全国快照(281 城 / 3665 门店 / 159 场次),
  61. 无 Token 时直接读取该文件即可回答「哪里能办」类问题;
  62. 涉及「这周还有没有位」等实时问题时再调用 MCP。
  63. ## 硬约束
  64. 1. **下单默认关闭**:仅满足上述「下单:带确认闸」全部条件时才调用 `party-order-create`;
  65. 其余写操作(`create-order` / `cancel-order` / `mall-create-order` / `draw-lottery` /
  66. `auto-bind-coupons` / `delivery-create-address`)一律禁止。
  67. 2. **金额单位是分**:`price` 字段 13800 表示 ¥138.00,展示前必须除以 100。
  68. 3. **日期必须实时获取**:涉及「今天 / 这周 / 还能约吗」时,先调 `now-time-info`,
  69. 不要凭模型记忆推断日期。
  70. 4. **余位可能为 0**:`leftNum` 为 0 表示已满,不要推断为「可约」。
  71. 5. **不要编造门店**:所有门店信息必须来自 MCP 返回或 `data/atlas.json`,
  72. 不得凭常识补充未返回的门店。
  73. 6. **人数规则来自商品详情**:起订人数、单场上限、适用年龄以 `mall-product-detail`
  74. 返回的 `partyPeople` / `partyAge` / `partyRange` 与场次的 `partyMin` / `partyMax` 为准,
  75. 不要自行假设。
  76. 7. **不替用户做资金决策**:只展示单价与预估总额,实际应付以服务端与麦当劳侧为准。
  77. ## 参考文档
  78. - `MCP_INTEGRATION.md` —— 完整链路、接口特性与应对
  79. - `data/tools_reference.md` —— 35 个工具的完整描述与入参 Schema
  80. - `README.md` —— 项目介绍与复现方式
README.md · README · 511 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # 麦当劳体验活动地图 · mcd-experience-atlas
  2. > **281 个城市 · 3664 家可办门店 · 157 个场次 · 26 款体验活动** —— 全部来自麦当劳官方 MCP 实测采集
  3. > 「我在成都,能办麦当劳生日派对吗?哪家店?多少钱?这周六还有位吗?」——**一次查询就有答案。**
  4. > 生日派对、主题派对、亲子读书会、品鉴会、体验营,在全国哪些城市、哪些门店、什么时段可以预约。
  5. **🗺️ 在线体验(无需安装,打开即用):<https://johnny37.github.io/mcd-experience-atlas/>**
  6. [![在线地图](https://img.shields.io/badge/在线地图-立即体验-DA291C)](https://johnny37.github.io/mcd-experience-atlas/)
  7. [![MCP](https://img.shields.io/badge/MCP-mcp.mcd.cn-FFC72C)](https://open.mcd.cn/mcp)
  8. [![tools](https://img.shields.io/badge/tools-35%20实测-FFC72C)](MCP_INTEGRATION.md)
  9. [![cities](https://img.shields.io/badge/城市-281-DA291C)](#)
  10. [![stores](https://img.shields.io/badge/可办门店-3664-FFC72C)](#)
  11. [![tests](https://img.shields.io/badge/tests-98%20passed-0F6E56)](#九测试)
  12. [![license](https://img.shields.io/badge/license-MIT-444)](LICENSE)
  13. ![麦当劳体验活动地图总览:全国 281 城可预约活动分布](docs/map-overview.png)
  14. <p align="center"><sub>全国体验活动分布总览 —— 圆点大小 = 可体验的活动款数,右侧为数据洞察(含 2 款全国零城市可约的下架活动、体验丰富度中位数 18 款等独家指标)</sub></p>
  15. ### 独家发现:26 款活动里,有 2 款全国一个城市都约不到
  16. 全量采集 3664 家门店、26 款体验活动之后,有两个结论是官方 App 里查不到的:
  17. | 发现 | 数据 | 意味着什么 |
  18. |---|---|---|
  19. | **2 款活动全国零城市可约** | 一年一度品虾会、金拱门板记尝新会 —— 覆盖城市数 **0** | 官网上还挂着,但**全国任何一家店都约不到**,纯「已下架」残留 |
  20. | **覆盖最窄的在售活动只有 2 城** | 麦咖啡™奶铁品鉴会 —— 仅福州、重庆 | 看到就心动,实则大多数城市根本办不了 |
  21. | **体验丰富度差距达 3 倍** | 中位数 18 款,最少 8 款,最多 23 款(福州/龙岩/泉州并列第一) | 「我们这能不能办生日派对」不是全国统一答案 |
  22. > 这也是本项目存在的理由 —— **官方的 App 只能逐级点开试,而这个对比视角只有把数据全拉通才能算出来。**
  23. ### 一键分享你城市的链接
  24. 点击地图上任意城市后,地址栏会自动带上 `?city=城市名`,右上角 **「复制我这城市链接」** 一键复制。
  25. 发到群里,别人打开**直接落到你那座城** —— 不用自己再翻地图。
  26. ```
  27. https://johnny37.github.io/mcd-experience-atlas/?city=成都市
  28. https://johnny37.github.io/mcd-experience-atlas/?city=北京市
  29. ```
  30. ### 演示动图
  31. ![演示动图:切换视图 → 点击城市看门店 → 搜索城市与门店](docs/demo.gif)
  32. <p align="center"><sub>10 秒走完一遍:切换「可办门店数」视图 → 点击成都看门店与可预约状态 → 搜索「北京」列出 3664 家门店中的匹配项</sub></p>
  33. ### 分享海报
  34. <p align="center">
  35. <img src="docs/poster-tall.png" width="240" alt="分享海报(竖版)"/>
  36. <img src="docs/poster-wide.png" width="520" alt="分享海报(横版)"/>
  37. </p>
  38. <p align="center"><sub>海报由 <code>src/make_posters.py</code> 从真实采集数据渲染生成,数字不写死;素材在 <a href="https://github.com/johnny37/mcd-experience-atlas/releases/tag/v1.1.0">v1.1.0 Release</a> 可直接下载</sub></p>
  39. > **想转给朋友?复制这句就行 👇**
  40. > 孩子生日想办麦当劳派对?全国 281 城 3664 家门店哪里能办、多少钱、这周六还有没有位,一张地图查完 → https://johnny37.github.io/mcd-experience-atlas/
  41. >
  42. > 顺带一提:26 款活动里有 2 款全国一个城市都约不到 → https://johnny37.github.io/mcd-experience-atlas/
  43. ### 想基于它做点什么?
  44. 本仓库不只是个成品网页 —— **`src/toon.py`(通用 TOON 解析器)、`src/mcp_client.py`(封装了麦当劳 MCP 的 14 个接口坑)、`data/` 下的开放数据集**都可以直接拿走用。
  45. 具体怎么 fork、怎么改、哪些模块能复用,见 **[CONTRIBUTING.md](CONTRIBUTING.md)**。
  46. ---
  47. ## 一、项目介绍
  48. ### 一句话定位
  49. **「我在成都,能办麦当劳生日派对吗?哪家店?多少钱?这周六还有位吗?」——一次查询就有答案。**
  50. 麦当劳的体验活动(生日派对 / 主题派对 / 品鉴会 / 亲子读书会 / 体验营)分散在 App 的深层路径里,
  51. 用户需要逐级确认「城市有没有 → 哪家门店能办 → 哪天可约 → 几点有场 → 还剩多少位」。
  52. 本项目把这条链路的数据一次拉通,做成一张可以点开的全国地图。
  53. ### 核心数据(2026-10-13 实测快照)
  54. | 指标 | 数值 |
  55. |---|---:|
  56. | 可预约城市 | **281** 个(含行政区划码 + 经纬度) |
  57. | 可办活动门店 | **3664** 家 |
  58. | 场次样本 | 157 个(覆盖 79 个城市) |
  59. | 体验品类 SPU | 26 款(商城 SPU 合计 50 款) |
  60. | MCP 工具(实测) | 35 个 |
  61. | 餐品营养表 | 160 项 |
  62. | 当月营销活动 | 13 天 / 27 个事件 |
  63. | 门店数 TOP5 城市 | 北京 365 · 上海 219 · 天津 136 · 佛山 118 · 成都 97 |
  64. ### 它解决什么问题
  65. 官方 App 里,上述五个问题需要逐级点开、逐个城市试才能回答,且**没有任何横向对比视角**。
  66. 本项目把这些数据一次拉通后,可以直接回答:
  67. - 我所在的城市能办哪些麦当劳体验活动?
  68. - 哪家门店能办?这周还有没有场次?多少钱?几个人起订?
  69. - 全国范围内,哪些活动其实「一个城市都约不了」?
  70. - 同样叫「生日派对」,不同城市能办到的款式差多少?
  71. 最后一条是本项目独有的指标——**体验丰富度**(按可体验 SPU 款数计):
  72. 全国中位数 18 款,最少 8 款,最多 23 款(福州 / 龙岩 / 泉州并列第一)。
  73. ---
  74. ## 二、安装方法
  75. ### 环境要求
  76. | 项 | 要求 |
  77. |---|---|
  78. | Python | 3.8 及以上(实测 3.13) |
  79. | 第三方依赖 | **无**。全部使用标准库实现 |
  80. | Node / 构建工具 | 不需要 |
  81. | 操作系统 | Windows / macOS / Linux 均可 |
  82. | MCP Token | **仅采集时需要**;查看地图和运行测试不需要 |
  83. ### 安装步骤
  84. ```bash
  85. # 1. 获取代码
  86. git clone https://github.com/johnny37/mcd-experience-atlas.git
  87. cd mcd-experience-atlas
  88. # 2. (可选)验证安装 —— 无需 Token,纯本地运行
  89. python tests/test_toon.py # 19 项
  90. python tests/test_data_pack.py # 20 项
  91. python tests/test_booking_gates.py # 35 项
  92. python tests/test_contest_compliance.py # 24 项
  93. # → 共 98 项,全部通过即说明环境就绪
  94. # 3. 查看地图(无需 Token)
  95. python -m http.server 8000
  96. # 浏览器打开 http://localhost:8000/web/
  97. ```
  98. ### 在线预览(GitHub Pages)
  99. 仓库根目录的 `index.html` 是数据完全内联的单文件版本,
  100. 因此可以直接用 GitHub Pages 托管,访客打开链接即可看到地图,无需 clone:
  101. ```
  102. Settings → Pages → Build and deployment → Source: Deploy from a branch
  103. → Branch: main / (root) → Save
  104. ```
  105. 本仓库已启用 GitHub Pages,在线地址:<https://johnny37.github.io/mcd-experience-atlas/>。
  106. 本仓库的 `dist/index.html` 与根目录 `index.html` 内容相同,均可单独分享。
  107. ### 配置 MCP Token(仅采集新数据时需要)
  108. Token 在 <https://open.mcd.cn/mcp> 用手机号登录后申请。本项目按以下优先级读取,**不接受也不生成任何本地凭证文件**:
  109. 1. 环境变量 `MCD_MCP_TOKEN`;
  110. 2. WorkBuddy 的 `~/.workbuddy/mcp.json` 中 `mcd-mcp` 连接器已配置的凭证
  111. (在 WorkBuddy 中接入过自定义连接器时自动生效,零额外配置)。
  112. ```bash
  113. # 方式 A:环境变量
  114. export MCD_MCP_TOKEN="你的 Token"
  115. # 方式 B:在 WorkBuddy 中接入连接器(推荐)
  116. # 左侧边栏 → 连接器 → 自定义连接器 → 配置 MCP,填入:
  117. # { "mcpServers": { "mcd-mcp": {
  118. # "type": "streamablehttp",
  119. # "url": "https://mcp.mcd.cn",
  120. # "headers": { "Authorization": "Bearer YOUR_MCP_TOKEN" } } } }
  121. # 之后直接运行采集脚本即可,无需再设置环境变量。
  122. ```
  123. 配置模板见 [`mcp-config.example.json`](mcp-config.example.json)(仅含 `${MCD_MCP_TOKEN}` 占位符)。
  124. ### 作为 Agent Skill 安装
  125. 本仓库同时是一个可被任意 MCP 客户端加载的 Agent Skill。将仓库路径加入客户端的技能目录即可,
  126. [`SKILL.md`](SKILL.md) 已按 WorkBuddy 标准格式声明了所需的 9 个只读工具与使用约束。
  127. ---
  128. ## 三、使用示例
  129. ### 示例 1:查看地图(最常用,无需 Token)
  130. 三种方式任选:
  131. ```bash
  132. # A. 本地起服务(数据走 data/atlas.json)
  133. python -m http.server 8000
  134. # 打开 http://localhost:8000/web/
  135. # B. 直接双击根目录的单文件版(数据已内联,无需服务器、无需 Token)
  136. # index.html
  137. # C. 在线访问(零安装):
  138. # https://johnny37.github.io/mcd-experience-atlas/
  139. ```
  140. 页面上可以做的事:
  141. - **切换视图**:「体验丰富度」看各城市能办多少款活动;「可办门店数」看门店密度;
  142. - **筛选品类**:下拉选择「生日类派对 / 主题类派对 / 品鉴会 / 读书会」,
  143. 地图即时高亮该品类可约的城市,不可约的缩为灰点;
  144. - **点选城市**:右侧显示该城全部可办门店、7 天可约日期与每日场次数、场次时段与余位;
  145. - **搜索**:输入「东单」可直接定位到麦当劳北京东单北大街餐厅;
  146. - **城市深链**:地址栏自动带上 `?city=城市名`,也可直接访问 `...?city=成都市` 打开即定位;
  147. 点右上角「复制我这城市链接」一键复制,发给别人直接落到你那座城;
  148. - **离线分享**:直接双击根目录 `index.html` 或 `dist/index.html`,数据已内联,不需要服务器。
  149. ### 示例 2:采集最新数据(需要 Token)
  150. ```bash
  151. python src/collect.py # 全量:281 城门店 + 79 城场次抽样
  152. python src/collect.py --deep # 深采:每个城市首店都取日期与场次
  153. python src/collect.py --resume # 中断后续采,跳过已完成的城市
  154. python src/build_atlas.py # 打包成 web/ 使用的 data/atlas.json
  155. ```
  156. 实际输出:
  157. ```
  158. [0/7] tools/list → 35 个工具
  159. [1/7] mall-points-products → 50 个 SPU
  160. [2/7] 体验品类城市覆盖 {'读书会': 281, '生日类派对': 281, '主题类派对': 279, '品鉴会': 36} → 去重后 281 城
  161. [3/7] 门店采集完成 → 3664 家
  162. [4/7] 场次抽样 → 79 城 / 157 个场次
  163. [5/7] list-nutrition-foods → 160 项(TOON 已解析)
  164. [6/7] query-lottery-info → 麦麦积分抽奖,10 项奖品,单次 24 积分
  165. [7/7] campaign-calendar → 13 天 / 27 个事件
  166. ```
  167. ### 示例 3:作为 Agent Skill 对话使用
  168. 加载本仓库为 Skill 后,可以直接这样问:
  169. > **用户**:我在成都,想给孩子办个麦当劳生日派对,这周六还有位吗?多少钱?
  170. Skill 会依次调用 `mall-points-products` → `query-party-city` → `query-party-store`
  171. → `query-party-store-date` → `query-party-store-session`,回答:
  172. > 成都可以办 6 款生日派对(开心鸭尊享版、迪士尼疯狂动物城主题尊享版等),
  173. > 全市有 97 家门店可办,你能体验的活动共 20 款,高于全国中位数(18 款)。
  174. >
  175. > 以成都高新区大魔方餐厅的采样场次为例,10-14 至 10-22 连续 9 天可约,
  176. > 这周六(10-17)有 2 个场次:10:30–12:00 和 14:00–15:30,
  177. > 5~12 人,当前各余 12 位。注意这是「亲子读书会」品类的场次与价格(¥45.00),
  178. > 生日派对的场次时间与价格需按具体 SPU 再查一次。实际下单请在麦当劳 App 或门店完成。
  179. Skill 内置的硬约束(见 `SKILL.md`):**只读**,禁止调用任何写操作工具;
  180. 金额单位为分需自行换算;涉日期必须实时调用 `now-time-info`;不得编造未返回的门店。
  181. ### 示例 4:运行测试
  182. ```bash
  183. python tests/test_toon.py
  184. python tests/test_data_pack.py
  185. ```
  186. ---
  187. ## 四、地图功能
  188. | 功能 | 说明 |
  189. |---|---|
  190. | **体验丰富度视图** | 圆点大小 = 该城市可体验的活动款数(按 SPU 计)。官方渠道没有这个指标 |
  191. | **可办门店数视图** | 圆点大小 = 该城市可办活动的门店数 |
  192. | **品类筛选** | 下拉或点击覆盖条形图切换品类,地图即时高亮;不可约城市缩为灰点 |
  193. | **7 天场次日历** | 选中城市后显示一周内每日可约场次数量,零场次的日子标灰 |
  194. | **门店搜索与筛选** | 支持按城市名或门店名全局搜索;可按「仅可预约」过滤门店 |
  195. | **数据洞察面板** | 自动算出「全国零城市可约的活动」「覆盖最窄的在售活动」「门店集中度」等结论 |
  196. ## 五、预约功能(带确认闸,默认关闭)
  197. 地图与查询全部只读;`src/book.py` 额外提供了**可真实下单**的能力,但默认关闭,
  198. 只在满足下列全部条件时才创建订单:
  199. 1. 用户**精确说出**「确认创建订单」——「试试看」「可以就下单」等模糊措辞一律视为未确认;
  200. 2. 用户核对过完整回显(活动 / 门店 / 日期 / 场次 / 人数 / 单价 / 预估总额);
  201. 3. 用户提供的**订单指纹**与当前参数算出的一致(防止「确认的是 A、下单的是 B」);
  202. 4. 前置校验通过:人数在 `[partyMin, partyMax]` 内、余位 > 0、`shopId == 5`、
  203. `partyType` 与商品规则一致、满足提前预订天数。
  204. ```bash
  205. # 第一步:只读,任何时候都安全,可反复运行
  206. python src/book.py --spu-id 8516 --city 南宁市 --store 3570247 \
  207. --date 2026-10-17 --session 36915550 --count 6
  208. # 第二步:写操作,真实创建订单
  209. python src/book.py --spu-id 8516 --city 南宁市 --store 3570247 \
  210. --date 2026-10-17 --session 36915550 --count 6 \
  211. --confirm 确认创建订单 --fingerprint <第一步给出的指纹>
  212. ```
  213. 实测回显效果(南宁水晶城餐厅,生日派对):
  214. ```
  215. 活动名称 :麦当劳一起开心鸭尊享版生日派对
  216. 派对类型 :包场 人数规则:5-12 人(年龄 4-12)
  217. 门店 :麦当劳南宁水晶城餐厅(青秀区金湖路61号)
  218. 预约日期 :2026-10-17 场次:12:00 – 13:30 余位 12
  219. 参与人数 :6 人 单价 ¥138.00/位 预估总额 ¥828.00
  220. 订单指纹 :74E14B2F22B1
  221. ```
  222. **三条不可妥协的安全约束:**
  223. - **绝不重试 `party-order-create`**——若订单已创建但响应未读回,重试会产生重复订单,
  224. 这是金钱相关的不可逆操作。`mcp_client.call()` 对写操作工具强制 `retries=0`。
  225. - **默认黑名单**——`mcp_client.WRITE_TOOLS` 默认拦截全部 7 个写操作工具,
  226. 须显式 `allow_write=True` 才放行,且只有 `book.py` 会这么做。
  227. - **审计留痕**——每次下单尝试写入 `data/booking_audit.log`,便于事后核对。
  228. 这些约束由 `tests/test_booking_gates.py`(35 项)锁定,全部离线运行、不发真实请求。
  229. ---
  230. ## 六、地图合规说明
  231. 默认视图是**纯 SVG 散点图**:只绘制城市坐标点与经纬网格,**不描绘任何行政边界、不加载任何在线底图瓦片**,
  232. 因此不涉及领土表示,可安全托管到 GitHub Pages 等任意静态空间。
  233. 如果你需要带底图的视图,请自行接入**腾讯地图 / 高德 / 百度 / 天地图**这四家具备资质的服务商,
  234. 并遵守《中华人民共和国测绘法》及相关地图合规要求。请注意:
  235. - 禁止使用 Google Maps、Apple Maps、Bing 海外版、OpenStreetMap 及 Mapbox 等未取得境内测绘资质的来源;
  236. - 前端代码中不要硬编码任何地图 Key,应通过自己的后端代理或域名白控;
  237. - 本项目 `data/` 中的经纬度来源于麦当劳 MCP 返回值,坐标系以官方为准,
  238. 接入不同底图前请自行核对是否存在 GCJ-02 / BD-09 偏移。
  239. ---
  240. ## 七、技术要点
  241. 这个项目的技术含量不在前端,而在**摸清一条没有文档的链路**。
  242. ### 1. 链路入口是积分商城,不是「派对工具」
  243. `query-party-city` 这类工具的入参 `spuId` 来自 `mall-points-products`——
  244. 也就是说,体验活动预约的入口是**积分商城选商品**,而不是某个独立的派对查询工具。
  245. 官方门户文档完全没有记载 `query-party-*` 系列,只读门户文档的开发者不会发现这条链路。
  246. 完整链路:
  247. ```
  248. mall-points-products → query-party-city → query-party-store
  249. → query-party-store-date → query-party-store-session
  250. →(party-order-create,写操作,本项目不调用)
  251. ```
  252. ### 2. 接口返回不是纯 JSON
  253. 所有 `tools/call` 返回的是「Markdown 说明 + 内嵌一行原始 JSON」混合体。
  254. 不能取「第一行看起来像 JSON 的内容」——说明文档里也有 JSON 示例。
  255. 本项目从 `{"success"` 起用 `JSONDecoder.raw_decode` 找边界(见 `src/mcp_client.py`)。
  256. ### 3. 营养表是自研的 TOON 格式
  257. `list-nutrition-foods` 返回的不是 JSON 数组,而是:
  258. ```
  259. [160]{productName,nutritionDescription,energyKj,energyKcal,protein,fat,carbohydrate,sodium,calcium}:
  260. 猪柳麦满分,null,1288,308,16,16,24,781,213
  261. 巨无霸,null,2145,513,27,28,44,1010,190
  262. ```
  263. **坑在于**:在原始 HTTP 响应文本中,行分隔符是两字符序列 `\n`(反斜杠 + n),不是真实换行,
  264. 直接 `split('\n')` 会得到 0 行。本项目 `src/toon.py` 对两种形态都做了归一化,并有回归测试锁定。
  265. ### 4. 其他实测确认的接口特性
  266. 详见 [MCP_INTEGRATION.md](MCP_INTEGRATION.md) 第 5 节的 10 条清单,包括:
  267. `query-nearby-stores` 单次只回 5 家且坐标返回 `0.0`、`available-coupons` 不返回 `couponId`、
  268. 鉴权失败返回 403 + 业务错误信封、协议仅支持 ≤2025-06-18 等。
  269. ---
  270. ## 八、目录结构
  271. ```
  272. mcd-experience-atlas/
  273. ├── README.md 项目介绍 / 安装 / 使用示例 / 目标用户
  274. ├── MCP_INTEGRATION.md 实际调用的 Server/Tool/流程/业务价值(参赛必需)
  275. ├── CONTEST_DECLARATION.md 参赛声明(官方原文,未做任何改动)
  276. ├── CONTRIBUTING.md 贡献指南:可复用模块清单 + 四个二次开发方向
  277. ├── mcp-config.example.json 脱敏配置示例,仅含 ${MCD_MCP_TOKEN} 占位符
  278. ├── workbuddy.md 使用 WorkBuddy 开发的对话上下文
  279. ├── SKILL.md Agent 技能描述(可被任意 MCP 客户端加载)
  280. ├── LICENSE MIT
  281. ├── index.html 单文件地图页(数据内联,供 GitHub Pages 根目录托管)
  282. ├── data/
  283. │ ├── atlas.json 前端使用的打包数据(build_atlas.py 生成)
  284. │ ├── cities.json 281 城 + 经纬度 + 品类覆盖矩阵
  285. │ ├── stores.json 各城市可办门店全量
  286. │ ├── sessions.json 场次抽样(79 城 / 157 场次)
  287. │ ├── experiences.json 50 个商城 SPU
  288. │ ├── nutrition.json 160 项营养表(TOON 已解析)
  289. │ ├── lottery.json 积分抽奖活动与奖池
  290. │ ├── campaign_calendar.json 当月营销活动日历
  291. │ ├── live_verification.json 通过 WorkBuddy 连接器的全链路实时验证记录
  292. │ ├── tools_snapshot.json tools/list 实测元数据
  293. │ └── tools_reference.md 35 个工具的完整描述与入参 Schema
  294. ├── src/
  295. │ ├── mcp_client.py MCP 客户端(混合响应解析、429 退避、写操作黑名单)
  296. │ ├── toon.py TOON 解析器(含字面量 \n 归一化)
  297. │ ├── collect.py 采集脚本(支持 --deep / --resume)
  298. │ ├── build_atlas.py 数据打包 + 单文件版本生成(同时输出根 index.html)
  299. │ ├── make_posters.py 分享海报渲染(数字取自 atlas.json,不写死)
  300. │ ├── make_gif.py 演示动图合成(Pillow)
  301. │ └── book.py 体验活动预约:带确认闸的下单流程(默认只读)
  302. ├── web/
  303. │ ├── index.html 图谱页面(零依赖)
  304. │ └── atlas.js 投影 + 视图切换 + 品类筛选 + 搜索交互 + 城市深链
  305. ├── dist/
  306. │ └── index.html 单文件版本(数据内联,可离线双击打开)
  307. ├── docs/
  308. │ ├── map-overview.png README 首屏截图(在线演示实拍)
  309. │ ├── map-only.png 海报用纯地图裁图
  310. │ ├── demo.gif 10 秒演示动图
  311. │ ├── poster-tall.png 分享海报(竖版 1200×1820)
  312. │ └── poster-wide.png 分享海报(横版 1200×628)
  313. ├── .github/
  314. │ └── ISSUE_TEMPLATE/
  315. │ ├── feedback.yml 功能建议 / 二次开发
  316. │ └── data-correction.yml 数据勘误
  317. └── tests/
  318. ├── test_toon.py 19 项:TOON 解析与混合响应提取
  319. ├── test_data_pack.py 20 项:数据包结构与自洽性
  320. ├── test_booking_gates.py 35 项:下单确认闸的安全属性
  321. └── test_contest_compliance.py 24 项:参赛要求逐项合规校验
  322. ```
  323. ---
  324. ## 九、测试
  325. ```bash
  326. python tests/test_toon.py # 19 项:TOON 解析与混合响应提取
  327. python tests/test_data_pack.py # 20 项:数据包结构与自洽性
  328. python tests/test_booking_gates.py # 35 项:下单确认闸的安全属性
  329. python tests/test_contest_compliance.py # 24 项:参赛要求逐项合规校验
  330. # → 共 98 项,全部通过
  331. ```
  332. 三个测试各自锁定一类风险:
  333. - `test_toon.py`——TOON 的字面量 `\n` 陷阱、混合响应中「不能误取说明文档里的 JSON 示例」;
  334. - `test_booking_gates.py`——锁住「默认只读 + 显式确认 + 写操作不重试」三条安全属性:
  335. 只读客户端必须拒绝全部 7 个写操作工具、模糊确认串不构成确认、
  336. 订单指纹随任一要素变化、越界人数与零余位被拦截。全部离线运行,不发真实请求。
  337. `test_data_pack.py`——`data/atlas.json` 的计数一致性、城市字段完整性、
  338. 覆盖矩阵的 `cityCodes` 可解析、门店索引无孤立键、场次价格单位为分;
  339. - `test_contest_compliance.py`——按官方参赛要求逐项校验:四个必需文件名未改动、
  340. README 四个必备章节齐全、`CONTEST_DECLARATION.md` 与官方原文 MD5 一致(内容未改动)、
  341. `mcp-config.example.json` 仅含环境变量占位符、仓库内无任何真实凭证。
  342. 最后一个测试存在的意义:参赛要求里有「文件名不可改动」「内容不可修改」这类硬约束,
  343. 一旦日后重构目录或误改文档,它会立即失败,避免到报名截止前才发现问题。
  344. ---
  345. ## 十、采集的健壮性
  346. 长任务中断是真实会发生的事(实测遇到过代理 502)。采集脚本为此做了三件事:
  347. 1. **增量落盘**:每 25 个城市写一次 `stores.json`,中途失败不丢已采数据;
  348. 2. **断点续采**:`--resume` 复用上次已完成的城市,不从头再来;
  349. 3. **网络错误与业务错误分离**:连接层故障(`URLError`)上抛重试,
  350. 服务端错误码(401/429)按语义处理,两者不会混为一谈。
  351. ---
  352. ## 十一、目标用户
  353. - **家长**:想给孩子办一场麦当劳生日派对,先确认自己城市有没有、哪家店、什么价位;
  354. - **行政 / HR**:筹备团建或品鉴会,需要横向对比可选门店与时段;
  355. - **亲子社群 / 本地生活内容创作者**:需要「哪里能办」的确定性答案;
  356. - **麦当劳 MCP 开发者**:需要一条完整的体验活动链路参考实现与踩坑记录。
  357. ---
  358. ## 十二、参赛文件清单
  359. 按《麦当劳程序员创意开发大赛》要求逐项对照:
  360. | # | 文件 | 官方要求 | 本项目状态 |
  361. |---|---|---|---|
  362. | 1 | `README.md` | 必须,文件名不可改动;含项目介绍、安装方法、使用示例、目标用户 | ✅ 四项分别为第一、二、三、十一节 |
  363. | 2 | `CONTEST_DECLARATION.md` | 必须,**文件名及内容均不可改动** | ✅ 官方原文件,MD5 与官方仓库一致 |
  364. | 3 | `MCP_INTEGRATION.md` | 必须,文件名不可改动;说明 MCP Server、Tool、调用流程和业务价值 | ✅ 见该文件第 1~6 节 |
  365. | 4 | 源代码 | 必须,形式不限 | ✅ `src/` 4 个 Python 模块 + `web/` 前端 + `tests/` |
  366. | 5 | `workbuddy.md` | 参加 WorkBuddy 专项奖励必须 | ✅ 开发过程、决策与安全自查 |
  367. | — | `mcp-config.example.json` | 活动规则另列,仅允许环境变量占位符 | ✅ 仅含 `${MCD_MCP_TOKEN}` |
  368. | — | 项目创建时间 | 2025-12-25 ~ 2026-10-25 | ✅ |
  369. | — | 真实使用麦当劳 MCP | 必须 | ✅ 9 个只读工具,35 个工具清单已实测 |
  370. | — | 真实使用腾讯 WorkBuddy | 拿专项奖励必须 | ✅ 通过 WorkBuddy 连接器开发与验证 |
  371. ---
  372. ## 十三、免责声明
  373. 本项目为独立参赛作品,由参赛者独立开发,**非麦当劳官方产品,也未获得麦当劳品牌背书**。
  374. 项目展示的所有数据来源于麦当劳中国 MCP 的只读接口返回,仅供参考;
  375. 活动规则、价格、余位及供应状态以麦当劳官方渠道的实时结果为准。
  376. 本项目不执行任何下单、领券、抽奖或积分消费操作。
  377. 对「麦当劳」「麦麦省」「麦乐送」等名称的使用仅限描述性指代,
  378. 不构成对麦当劳及其关联方商标的任何授权,亦不暗示官方背书。
  379. ## License
  380. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.