麦麦活动雷达

回答「附近有什么麦当劳活动」「周末能去哪个麦麦主题活动」「帮我查某城市的派对或品鉴会」等问题。数据全部来自麦当劳中国官方 MCP（mcd-mcp 连接器），并配套直连命令行作为兜底。

红线：不得用网页搜索、模型记忆、examples/sample-events.json 或任何推测数据冒充实时 MCP 结果。查不到就说查不到，并说明已查范围与缺失环节。

初次使用 · 小白三步走（未配置时必走）

第 0 步自检发现「未配置」时，按下面流程引导，全程不需要用户编辑任何 JSON：

第 1 步 · 获取 Token（约 1 分钟）

把下面这段话原样发给用户：

打开麦当劳 MCP 开放平台：https://open.mcd.cn/mcp/doc ① 点右上角【登录】，用手机号验证登录； ② 登录后「登录」按钮变成「控制台」，点它； ③ 在弹出的控制台弹窗里点【激活】按钮，申请 MCP Token； ④ 同意服务协议； ⑤ Token 出现后点【一键复制】，直接粘贴到这个对话里发给我。 ⚠️ Token 等同于账号凭证：只发在这条对话里，不要发到群聊、朋友圈或 GitHub。

第 2 步 · 自动配置（用户贴出 Token 后立即执行）

用内置一键脚本写入 WorkBuddy 私有配置（自动备份原文件、保留已有服务器、在线验证 Token）。命令（<skill目录> 指本 Skill 的 base directory）：

MCD_MCP_TOKEN='<用户贴的Token>' node "<skill目录>/scripts/setup-connector.mjs"

PowerShell 环境改用：$env:MCD_MCP_TOKEN='<Token>'; node "<skill目录>/scripts/setup-connector.mjs"; Remove-Item Env:\MCD_MCP_TOKEN

• 脚本输出含在线验证结果（服务名、工具数、核实链是否齐全）与「还差两步」提示，把结论转述给用户。
• Token 安全：只允许通过该脚本写入用户本机的 ~/.workbuddy/mcp.json；不得在回复、示例、记忆文件、日志或仓库文件中回显或保存 Token。
• 若验证提示 Token 无效（401）：请用户回平台重新申请，再跑一次脚本覆盖即可。

第 3 步 · 激活（WorkBuddy 平台要求，约 30 秒，无法跳过）

① 连接器管理页 → 自定义连接器 → 对 mcd-mcp 点「Trust」； ② 聊天窗口左下角「+」菜单 → 启用 mcd-mcp； ③ 重开一轮会话，再说「查活动」。

当前会话立即出结果的兜底：配置已写入但工具尚未加载时，可先用直连脚本查一次（同样是官方 MCP、真实数据）：

MCD_MCP_TOKEN='<Token>' node "<skill目录>/scripts/live.mjs" --city <城市> [--from YYYY-MM-DD] [--to YYYY-MM-DD] --output events.local.json

输出为归一化 JSON（含门店经纬度与地址元数据），随后按「输出样式」一节用 radar.mjs 生成 HTML 活动地图呈现，并提醒用户重启后即可纯对话查询。

第 0 步 · 连接器自检（每次查询前必做）

1. 用 ToolSearch 按工具名精确检索：campaign-calendar、mall-points-products、mall-product-detail、query-party-city、query-party-store、query-party-store-date、query-party-store-session。检索到即视为可用，直接进入查询流程。（注：日期/场次两个工具以线上实际命名为准；官方文档写作 query-partystore-date / query-partystore-session，两处都试。）
2. 检索不到 → 调用 list_installed_plugins 看是否有 mcd-mcp 及其 bound / enabled 状态。
3. 仍然没有 → 读 ~/.workbuddy/mcp.json（Windows 为 %USERPROFILE%\.workbuddy\mcp.json）看 mcpServers 下有无 mcd-mcp 条目。

检查结果	状态	处理方式
工具可检索到	可用	进入查询流程
配置里有条目，但工具检索不到	已配置未生效	请用户在连接器管理页对 mcd-mcp 点「Trust」，在聊天窗口左下角「+」菜单启用，并重开一轮会话；期间可用 live.mjs 兜底
配置里没有条目	未配置	走上方「小白三步走」

「附近」与城市识别（需用户确认）

按优先级取城市：

1. 用户本轮明确给出的城市 → 直接使用。
2. 用户问「附近 / 我周围」但没给城市 → 征得用户一句同意后，运行 node "<skill目录>/scripts/locate.mjs"（城市级 IP 定位，不收集精确坐标），把检测到的城市向用户确认一次，例如「检测到你在杭州，按杭州查？」。脚本检测到海外出口（VPN/代理）会明确提示——此时直接请用户报城市。
3. 用户长期记忆中的常驻城市 → 作为待确认的默认值提出一次。
4. 以上都没有 → 请用户提供城市。

无论如何，检测或记忆得到的城市都必须经用户确认或纠正后才用于查询；不做商圈、行政区、门店级定位，也不把检测到的位置写入记忆。

日期：用户未给日期时，默认查询未来 14 天（北京时间）并明确告知该范围；用户给了就按用户的。

查询流程

1. 提取城市、日期范围、活动类型和出行偏好。
2. 调用 campaign-calendar 获取活动线索。该工具无参数时查当前月；指定日期不在当前月时，按官方 specifiedDate 参数查目标日期附近三天，必要时分段覆盖。其结果只证明活动信息，不证明某门店有可预约名额。
3. 调用 mall-points-products，用官方类目 catRuleIds=1>6>20,1>6>21,1>6>22,1>6>25,1>6>34 查生日派对、主题派对、体验营、品鉴会、读书会等活动商品；按需调用 mall-product-detail 获取真实 spuId、skuId、活动说明和适用人数。不要从标题猜测商品编码。
4. 用 spuId 调用 query-party-city 找到用户城市的真实 code；再用 spuId + 城市 code 调 query-party-store；随后用 spuId + storeCode 调 query-party-store-date，最后用 spuId + storeCode + dateStr 调 query-party-store-session 核实场次。参数类型与字段含义以运行时 schema 为准，勿混用城市 code、门店 code 和场次 id。
5. 控制查询范围：优先覆盖用户城市、日期、活动类型和最多 5 家候选门店，需要时再扩大。某步骤未返回数据就停止该分支，不编造后续结果。
6. 对每个结果记录名称、城市、门店、日期、场次、剩余名额、预约状态、价格或费用、来源工具和查询时间。只有 query-party-store-session 明确返回 leftNum > 0 才可标为「有名额」。价格展示原始值；live.mjs 会用 mall-product-detail 同商品价格（元）交叉核实场次 price 单位（2026-10-09 实测 11/11 商品倍率恒为 ×100，即单位为分），核验一致时标注「单位分 + 约价 ¥xx」，不一致时自动回退「单位待核实」，不做无依据换算。不同工具信息矛盾时，以更具体且更新的场次结果为准并说明冲突。
7. 展示「已核实可预约场次」与「活动线索／待核实」两组，排序：明确可预约 > 日期更近 > 匹配偏好。说明推荐理由与数据获取时间。无结果时说明已查范围与缺失环节，建议调整条件。
8. 查询完成后，按「输出样式」用 radar.mjs --format html 生成卡通活动地图（含活动卡片）作为可视化交付物，聊天回复只保留简洁摘要。

预约边界

默认只查询。party-order-create 会创建订单；仅当用户明确要求预约或下单，并已看到和确认活动、城市、门店、日期、场次、人数、费用后才调用。所需 spuId、skuId、城市 code、storeCode、partyType、场次 id、起止时间、leftNum 和 count 均来自实际工具结果或用户明确提供的人数。若无法确认费用单位，不得创建订单。若工具返回仍需支付，把支付链接及金额原样告知用户，由用户自行完成支付。不得擅自调用普通点餐、领券、积分兑换或抽奖工具。

输出样式 · HTML 活动地图（默认交付物）

查询得到已核实场次后，把结果整理成自包含 HTML 卡通活动地图（门店小屋按官方经纬度投影落位、辖区区块、街道标签、活动卡片面板与日期/活动/状态筛选），并用 present_files 展示给用户：

node "<skill目录>/scripts/radar.mjs" --input <归一化JSON> --city <城市> [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--districts @辖区映射.json] --output <活动地图.html>

• 输入是 live.mjs 的归一化 JSON（含 stores 门店元数据）。radar.mjs 默认 --format html；--format md / --format json 仍可用于纯文本清单或结构化导出。
• --districts 可选：传 { "门店名": "辖区名" }（内联 JSON 或 @文件）用于地图区块标注。辖区名可依据你对门店地址/位置的了解给出，属示意标注——门店位置始终取官方经纬度，不受影响。不传时按门店聚簇自动划片并按方位命名（如「西北片区」）。
• 地图不调用任何在线地图服务：门店相对位置由官方 query-party-store 返回的经纬度线性投影，辖区、道路、公园均为卡通示意，页面已标注「卡通示意图 · 非精确地图」。不要向用户宣称区块是精确行政区划边界。
• 聊天回复仍需简洁列出查询条件、获取时间与推荐场次（区分「可预约」与「待核实」；价格展示：已核实单位为分的显示约价 ¥xx 并保留原始值，未核实的显示原始值+「单位待核实」）；地图是可视化交付物，不替代文字摘要。0 场次时地图会显示空态页，文字说明已查范围与建议。

排障速查

现象	先查什么
一个麦当劳工具都检索不到	走第 0 步；多数是未配置（走三步走）或未点「Trust」
连接器已启用但工具仍不出现	重开一轮会话；用 live.mjs 兜底查询
调用返回 HTTP 401 / 403	Token 失效或权限不足：请用户到 https://open.mcd.cn/mcp/doc 重新申请，重跑 setup-connector.mjs 覆盖；不要反复重试
调用返回 HTTP 429	触发限流（每 Token 每分钟 600 次）：暂停片刻再查，别加大并发
定位结果是海外城市	VPN/代理出口，不是真实位置；直接请用户报城市
工具名与文档不一致	以 tools/list 实际返回为准（线上日期/场次工具为 query-party-store-date / query-party-store-session）
只有活动日历、没有门店场次	正常现象，日历不等于名额；按流程走门店链，走不通就归为「待核实」
某商品在该城市查不到门店	该活动未在该城市开放，停止该分支，换下一个候选商品

内置脚本（位于本 Skill 目录 scripts/ 下）

• setup-connector.mjs：一键配置——写入 ~/.workbuddy/mcp.json（自动备份、保留其他服务器）并在线验证。Token 来源：MCD_MCP_TOKEN 环境变量 / --token 参数 / 交互式隐藏输入。全程不打印 Token。
• check-connector.mjs：连接器体检（--online 需 MCD_MCP_TOKEN，核对工具覆盖；--json 结构化输出），不打印凭证。
• locate.mjs：城市级 IP 定位（ipinfo.io 主、api.ip.sb 备），识别海外/代理出口并提示；--json 输出结构化结果。
• live.mjs：直连官方 MCP 查询主题活动场次，需 MCD_MCP_TOKEN；输出包含 query-party-store 返回的门店经纬度与地址（供地图定位）。没有连接器、或当前会话工具未加载时的兜底路径。
• radar.mjs：校验、去重、筛选并整理查询结果——默认生成自包含 HTML 卡通活动地图（门店小屋 + 辖区区块 + 活动卡片 + 筛选联动，零外部依赖、离线可打开），也可 --format md / --format json 输出清单。只处理归一化字段。字段格式见 examples/sample-events.json，该文件是虚构演示数据，绝不可作为实时查询结果。