name: mcd-mailu description: 麦途——麦当劳消费轨迹与场景叙事。当用户问「我的麦当劳账单」「我在麦当劳花了多少钱」「我最常点什么」「看看我的麦当劳足迹」「生成我的麦途卡片」时使用。基于麦当劳官方 MCP 读取历史订单，识别每单的场景（机场 / 赶早 / 深夜 / 连点 / 新店…），把订单讲成一个由数据支撑的故事，输出一张可截图分享的轨迹卡。只读不写：绝不创建、取消或修改任何订单。核心红线：卡片上的每一句话都必须能回溯到具体订单，绝不脑补数据里不存在的内容。

麦途 · mcd-mailu

别的工具告诉你「该点什么」。麦途做的是相反的事——读懂你已经点的，把它讲成一个故事。

麦当劳订单里最被低估的字段是门店名和时间。店名里藏着「机场」「火车站」「医院」「写字楼」，时间里藏着早班机、深夜加班和周末遛娃。麦途把这些线索收集起来，识别场景，串成轨迹。

核心红线（违反即产品死亡）：卡片上的每一句话，都必须能回溯到至少一条真实订单。数据里没有的东西，一个字都不能写。

什么时候用

• 「我在麦当劳花了多少钱」「我最常点什么」
• 「生成我的麦当劳年度账单 / 足迹」
• 「看看我都在哪吃过麦当劳」

前置条件

环境变量 MCD_MCP_TOKEN（https://open.mcd.cn/mcp 手机号登录领取）。 没有 Token 时不要调用工具，引导领取，或提示 --demo 用内置样本看效果。

五步工作流

Step 1 · 拉单

• order-list：餐食订单（一次返回全量，无分页参数，重度用户可能被服务端截断，属已知风险）
• mall-order-list：商城订单（支持 lastId 翻页，按 hasNext 取完为止）
• now-time-info：当前时间，所有「近 N 个月」表述的唯一基准

判据：

• 商城订单（买卡、兑券）与餐费分开统计，不得混入消费额。
• 工具失败就明说失败，不估算、不脑补。

Step 2 · 清洗归一

四条缺一不可：

1. 状态过滤：只保留「订单已完成」，其余剔除并计数。
2. 金额口径：realTotalAmount 为字符串、单位元，直接转 float。出现整数 ≥500 的量级异常时调 money.flag_suspicious 告警，人工核对，不自动换算。
3. 去重：按 orderId 去重。
4. 时间：createTime 是下单时间，用 money.parse_time 归一。时段统计一律用下单时间。

Step 3 · 场景识别

scene_engine.py 对每单打标签，规则透明可查、可扩展：

整单模式（画像层）：

判据：

• 规则全部写在 references/scene_rules.md，开源接受社区补充。这是本项目的护城河：词典越厚，认出的故事越多。
• 每条规则命中必须记录依据（店名关键词、时间、订单号），供叙事层引用。

Step 4 · 叙事生成

narrative.py 用模板 + 数字生成文案，分两种模式：

• 轨迹模式（样本 <10 单）：不装统计。按时间顺序讲每一次，突出场景标签和连点细节。
• 画像模式（样本 ≥10 单）：统计结论，比率必须带分母。

判据：

• 每个数字必须能指回订单号集合，写入 evidence。
• 首屏结论是一句话，不是「分析报告」。范例：「11 个月里你只吃了 4 次麦当劳——4 次都在路上。」
• 禁止形容词堆砌。「温暖」「治愈」这类词一行最多一个，且必须跟在数据后面，不许凭空抒情。
• 禁止脑补品类偏好：数据里没有的餐品（如可乐），文案里不得出现。

Step 5 · 出卡片

card_render.py 生成单文件 HTML 轨迹卡。

判据：

• 首屏是一条时间轴，不是柱状图。每单一个节点，节点带场景标签。4 单好看，80 单也好看。
• 单文件、零外链、零 JS 依赖、断网可开，方便截图转发。
• 卡片里不出现完整订单号、手机号、地址；门店名保留（它是故事的一部分）。
• 页脚带免责与隐私说明。

红线

1. 不做任何写操作：create-order、cancel-order、mall-create-order、party-order-create、draw-lottery 一律不碰。
2. 订单明细不落盘，全部内存计算，输出只有聚合结果与场景标签。
3. fixtures 全部是人工构造的假数据，绝不提交真实订单导出。
4. Token 只从环境变量读，不打印、不进文件、不进日志。
5. 不编造数字、不编造概率、不编造品类偏好。

文件

SKILL.md                   本文件
scripts/mcp_client.py      MCP 客户端（仅标准库）
scripts/probe.py           字段探测器（实测校准用）
scripts/money.py           金额/时间归一化
scripts/adapters.py        MCP 返回 → OrderRecord
scripts/scene_engine.py    场景标签与模式识别（规则驱动）
scripts/narrative.py       叙事生成（每句话带 evidence）
scripts/card_render.py     HTML 轨迹卡渲染
scripts/run.py             主流程，支持 --demo
scripts/gen_fixture.py     演示数据生成器
fixtures/demo_orders.json  人工构造的脱敏样本
references/scene_rules.md  场景识别词典（开源接受补充）
docs/index.html            离线演示页

麦途 mcd-mailu

别的工具告诉你「该点什么」。麦途做的是相反的事——读懂你已经点的。

在线预览 → https://calmsprite2001.github.io/mcd-mailu/

不用装任何东西、不用申请 Token，打开就是一张由 88 单样本生成的足迹卡。

基于麦当劳官方 MCP 的消费轨迹与场景叙事 Skill。读取你的历史订单，识别出「这次在机场」「这次是赶早班」「这次在机场连点了两单」，把你的麦当劳历史讲成一个每句话都能回溯到真实订单的故事，输出一张可截图分享的轨迹卡。

麦当劳程序员创意开发大赛参赛作品。

给谁用

不适合谁：想用它点餐、领券、比价的人。麦途只读历史，不干预任何下单动作。

为什么不一样

大赛里绝大多数作品在解决「帮你点」：点餐助手、省钱助手、营养助手、派对策划。这些方向都很好，但已经挤满了。

麦途补的是另一端，也是被所有人忽略的一端：已经发生的消费里有什么。

麦当劳订单里最被低估的两个字段是门店名和下单时间：

• 店名里藏着「机场」「火车站」「写字楼」「医院」——你当时在哪
• 时间里藏着早班机、深夜加班、周末遛娃——你为什么在那

把这些线索拼起来，一笔笔冷冰冰的订单就变成了能讲的故事。这是 MCP 数据用法的另一种可能：不是查询接口，是理解生活的原料。

效果长什么样

不开 Token、不连网络，直接打开 docs/index.html 就能看到完整效果。它由 fixtures/demo_orders.json 里 88 单人工构造的样本生成。

同一套代码，两种讲述方式：

样本少时讲轨迹（真实测试账号，4 单，11 个月）：

11 个月里你吃了 4 次麦当劳——2 次都在路上。

2025-11-15 17:23，麦当劳成都天府机场GTC餐厅，¥38：板烧鸡腿堡三件套（出行慰藉、新店打卡） 2025-11-15 17:35，同一家店，¥9.5：黑金奶黄年糕风味派（出行慰藉、一单多点） 最拼的一次：2025-11-15，距上一单 12 分钟、同店，连吃两单。

样本够时讲画像（88 单）：

6 个月，88 次，你是天涯路人。

88 单，共 ¥1793.8，平均每单 ¥20.4。 26/88 单在机场或火车站——这些地方从不是你的目的地。 点得最多的三样：中薯条×31、中可乐×18、香芋派×11。

核心红线

卡片上的每一句话，都必须能回溯到至少一条真实订单。

这是产品的命根子。所以：

• 数据里没有的餐品，文案里一个字都不出现（比如知道你没点过可乐，就不会说「配一杯可乐」）
• 每个数字都带 evidence（订单号集合），校验不过就不写
• 样本不足 10 单时不装统计，改成按时间讲每一次，宁可朴素也不虚构

快速开始

方式一：不用 Token，直接看效果

git clone https://github.com/calmsprite2001/mcd-mailu.git
cd mcd-mailu
python scripts/run.py --demo
# 直接用浏览器打开 docs/index.html

零依赖，纯标准库，Python 3.10+。

方式二：用你自己的真实订单

1. 到 https://open.mcd.cn/mcp 用手机号登录，控制台激活并复制 MCP Token
2. 设环境变量：

export MCD_MCP_TOKEN=你的Token

3. 在 WorkBuddy / Cherry Studio / Cursor 中配置 MCP 连接器（配置见 mcp-config.example.json）
4. 直接跑：

python scripts/run.py

或者在 WorkBuddy 里说一句「看看我的麦当劳足迹」，Skill 会自动接管。

工作流

order-list ──┐
mall-order-list ──┼─→ 清洗归一 ─→ 场景识别 ─→ 模式识别 ─→ 叙事生成 ─→ HTML 轨迹卡
now-time-info ──┘   （状态/去重/   （每单打标签  （按到访口径）  （每句带 evidence）
                      金额/时间）   带 evidence）

关键设计：按「到访」而不是「按订单」统计。 在机场候机 12 分钟连点两单，是「1 次到访、2 个订单」，不是「去了两次机场」。不做这层合并，画像会被连点污染——这个坑是实测时发现的。

场景词典是开放的

所有识别规则都在 references/scene_rules.md，透明可查。欢迎 PR 补充新场景。

词典越厚，能认出的故事越多。这是本项目的护城河：不是模型多强，是场景库多细。

隐私

• 订单明细不落盘，全部内存计算，输出只有聚合结果与场景标签
• 卡片里不出现完整订单号、手机号、地址（门店名保留，它是故事的一部分）
• Token 只从环境变量读，不打印、不进文件、不进日志
• fixtures/ 全部是人工构造的假数据

已知限制

• order-list 没有分页参数，一次返回全量。重度用户的历史是否会被服务端截断，未能验证。
• 订单明细没有单品单价，只有订单总额，所以无法计算单品花费，只能统计出现频次。
• 城市识别未实现。跨城判断目前靠店名关键词（机场/车站）间接推断。

目录

SKILL.md                  Skill 定义与工作流判据
scripts/
  mcp_client.py           麦当劳 MCP 客户端（仅标准库）
  probe.py                字段探测器（实测校准用）
  money.py                金额/时间归一化
  adapters.py             MCP 返回 → OrderRecord
  scene_engine.py         场景标签与模式识别
  narrative.py            叙事生成（带 evidence）
  card_render.py          HTML 轨迹卡
  run.py                  主流程（支持 --demo）
  gen_fixture.py          演示数据生成器
fixtures/demo_orders.json 88 单人工构造样本
references/scene_rules.md 场景识别词典（欢迎补充）
docs/index.html           离线演示页

声明

本项目为麦当劳程序员节创意开发大赛参赛作品，由参赛者独立开发，非麦当劳官方产品。输出仅供参考，不构成消费建议；餐品信息、价格及供应状态以麦当劳官方渠道实时结果为准。

详见 CONTEST_DECLARATION.md 与 MCP_INTEGRATION.md。