walk-kcal

你今天还能吃多少卡，取决于你愿意走多远。

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

👉 在线体验（免安装） ｜ 想在本机跑 → 快速开始

站在楼下，饿着，纠结「现在吃什么」

打开手机，满屏都是「附近美食」。可你真正想知道的是：

这一顿，我吃得下吗？

walk-kcal 把这个纠结变成一道算术题：

你走到那家店，路上消耗的卡路里，就是你这一顿多出来的额度。
走得越远，额度越高，能吃的越多。

然后告诉你：附近哪家店、哪道菜你这顿吃不吃得下。

Related MCP server: nutrition-mcp

反常识：麦当劳居然是个低热量选项

我们把 158 条麦当劳官方营养数据、155 万条中餐菜谱摊在一起算了一遍。

• 麦香鱼 325 卡 · 麦满分 250 卡 · 迷你草莓新地 122 卡

• 而隔一条街那家面馆的红烧肉盖饭，780 卡起步

同一街区里，麦当劳的推荐菜大多落在普通人的一餐额度之内。

这不是我们编的，是算出来的。

对热量预算紧张的人来说，走进麦当劳，反而是最安全的选择。

同一份内核，三个壳

同一句「附近吃什么」，从三种地方问出来，拿到的是同一份结果 —— 算法、数据源、渲染完全共用，只有「外壳」不同。

上面那张图里的对话不是编的 —— 是实跑 data/linghelu（上海浦东凌河路） 拿到的真实回复，截图自 WorkBuddy 界面。

内置两款能力 —— 也可以接你自己的

这个 demo 自带两款数据源，开箱即用：

麦当劳有两条通道 —— 一个 Token 就能走实时

★ MCD_MCP_TOKEN 的唯一用途就是走实时 MCP。 内嵌快照只是「没配 Token 时的降级」—— 让项目能被零门槛跑起来，而不是一上来就报错。

实测对照（同一坐标 121.601780, 31.272460，通道不同，门店也完全不同）：

Token 在 https://open.mcd.cn/mcp 免费申请（登录麦当劳账号 → 激活 → 复制）。

可以按需组合 —— 一个环境变量的事：

也可以接你自己的 —— 点评的企业接口、美团、或者你手上任何一份门店／菜品数据。 数据源是可插拔的：加一个文件 + 一个环境变量，主流程 0 行改动。

麦当劳在这里是一个可信的数据源，不是一个产品的边界。

为什么是我们

我们把这个赛道的 493 个报名翻了一遍：

麦当劳 MCP 开放的，是它自己的营养表。 可真实场景里，你 400 米外那家面馆、那家潮汕火锅，多少卡？

没有人做这件事。我们做了。

我们诚实地告诉你

中餐热量是估算的，平均误差 25–28%。 麦当劳的数据是 MCP 官方精确值。

因为语料库里 0% 的菜谱标注了份量，同一道菜的量级能差 40 倍。 我们花最多力气的地方，不是「算得更准」，而是知道什么时候算不准 —— 然后老老实实显示「算不出」，而不是猜一个看起来正常的数字。

宁可少算，不可算错。　详见 → docs/数据源与误差.md

跑起来

先跑内置场景 —— 这一步一个 Key 都不需要。

git clone https://github.com/adexbn/walk-kcal && cd walk-kcal
python walkkcal/render.py     # 出图（内置场景，1~2 秒）
open demo/explore.html        # 离线可交互 demo

快照里已经存好了门店、推荐菜、步行距离和热量 —— 麦当劳那 158 条官方营养值也是内嵌的。 所以「先跑起来看看」这件事，零门槛。

Key 用在哪

麦当劳两条通道的实测对照（同一坐标，门店完全不同）见上文「内置两款能力」。

# 抓新点位：地址 → 坐标 → 抓数 → 出图，实测约 16 秒
python walkkcal/shoot.py "上海市黄浦区南京东路100号"

想换组合？

WALKKCAL_PACKS=mcd     python walkkcal/render.py   # 只看麦当劳（全部官方精确值）
WALKKCAL_PACKS=nearby  python walkkcal/render.py   # 只看周边餐厅（即「只要地图」）

跑起来会打印一行「源装配」，告诉你这次到底用了谁 —— 退化会显形，不会静默变空：

源装配：麦当劳(店✓ 菜✓ 热✓官方) ｜ 周边餐厅(店✓ 菜✓ 热✓估算)

全部命令、5 个内置实拍场景、换点位、跨城市、环境变量总表 → docs/快速开始.md

出图依赖是可选增强，不是前置条件

缺包时自动降级为「只出 SVG」，不会让你撞 ImportError。 业务内容（店名 / 菜名 / 热量 / 距离）与 PNG 完全一致，差异只在位图化。 两个包都有预编译 wheel，实测 9 秒装完，不需要本地编译工具链 —— 这是唯一的第三方依赖。

★ 真的用了麦当劳 MCP —— 而且是「MCP 调 MCP」

赛事硬性要求「须真实使用麦当劳 MCP 能力」，这条链路是实的：

graph LR
    CLI["任何 MCP 客户端"] --> SRV["entry/mcp_server.py<br/><i>本项目的 MCP 入口</i>"]
    SRV -->|"list-nutrition-foods"| MCD["麦当劳官方 MCP<br/>mcp.mcd.cn"]
    SRV --> CORE["walkkcal/ 内核<br/>周边门店 + 中餐估算"]
    CORE --> MAP["高德 / 百度<br/>门店 + 步行距离"]

本项目的 MCP 入口 entry/mcp_server.py 对外暴露 4 个工具 —— walk_allowance / nearby_food / what_can_i_eat / explain_concept； 它自己内部还会再去调麦当劳官方 MCP：packs/pack_mcd.py 用 JSON-RPC 打 https://mcp.mcd.cn 的 list-nutrition-foods，拿回 158 条官方营养值（含蛋白/脂肪/碳水/钠/钙）， 与本地中餐菜谱估算融合成一个统一结果。

最硬的一条实测证据 —— 同一个坐标，门店变了：

「永兴汇餐厅」这家本地快照里根本没有 —— 只有真调 MCP 才会冒出来。 完整证据（含 35 个工具清单、158 条营养表逐条比对、7 条错值修正）→ evidence-real.md 调用流程与 Tool 清单 → MCP_INTEGRATION.md

# 不填任何 Token 也能自测（读本地快照）
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python entry/mcp_server.py

工程能力（想动手的直接看这段）

walkkcal/ 是内核（额度算法 · 数据源 · 渲染），上面三个壳都只是它的包装。 除「出图」那两颗 wheel 外零第三方依赖 —— 抓数 / 额度 / 选店 / 热量全是标准库。

换任何一环都不用改主流程：

换语料也不会把覆盖率打回原形：查热量是分层的， L2（菜名品类）/ L3（门店类型）先验与语料源无关，永远生效。

📖 想接新数据源 → docs/扩展开发.md

文档地图

想用 · 快速开始 ｜ 交互模式 ｜ 离线 demo 想懂 · 设计取舍 ｜ 数据源与误差 ｜ 工程历程 想接 · 扩展开发 ｜ 源装配契约 ｜ 服务商边界 评委 · MCP_INTEGRATION.md ｜ evidence-real.md ｜ SKILL.md

免责

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

你今天还能吃多少卡，取决于你愿意走多远。

如果这个想法让你想多走两步 —— 给个 ⭐ 吧。