Walk Kcal

walk-kcal

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

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

试试看（不用装任何东西） ｜ GitHub 源码

English TL;DR (the README below is in Chinese)

Walk-Kcal turns walking distance into a meal calorie budget: 450 kcal + 4 kcal per 80 m. Walking 800 m buys you +44 kcal — about half an apple.

Given a location, it lists nearby restaurants and their recommended dishes, estimates kcal per dish in explicit layers (exact recipe → category median → store-type prior → "unknown"), and marks each dish as fits your budget or over. McDonald's nutrition comes from the official China MCP (query-nearby-stores, list-nutrition-foods); other restaurants are estimated from a Chinese recipe corpus, with the layer and error range disclosed per dish.

⚠️ Not a turnkey tool for your country. Map data and the recipe corpus are Chinese. What ports is the pipeline — plug in your own map API (Google / OSM) and nutrition source (USDA / OpenFoodFacts), and keep the abstain layer.

Demo (no install): https://adexbn.github.io/walk-kcal/

---

站在楼下纠结「现在吃什么」时，你真正想知道的是——这一顿，我吃得下吗？

一张竖屏长图：附近哪家店、哪道菜你这顿吃不吃得下 —— 绿色 = 吃得起，红色 = 超了（划掉）。

---

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

我们把麦当劳官方营养表（158 条）和 155 万条中餐菜谱摊在一起算了一遍。

• 麦香鱼 325 卡 · 麦满分 250 卡 · 迷你草莓新地 122 卡
• 而隔一条街那家面馆的红烧肉盖饭，780 卡起步

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

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

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

---

这个工具能做什么

输出一张竖屏长图，可以直接发微信、发小红书。

---

独特之处

同类赛道里，大多数项目只算了菜品的热量；提到「步行」的，几乎没几个把它接到热量上。

三种形式，同一份结果：

麦当劳 MCP 开放的，是它自己的营养表。可真实场景里，你 400 米外那家面馆多少卡？ 没有人做这件事。我们做了。

---

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

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

麦当劳的两条通道

只想看个 demo、不想去申请 Token？ 直接跑就行 —— 效果是完整的。 想要实时的门店和营养值，再去申请一个 Token 也不迟：https://open.mcd.cn/mcp（免费）。

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

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

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

---

跑起来

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

git clone https://github.com/adexbn/walk-kcal && cd walk-kcal
python walkkcal/render.py        # 出图（内置场景，1~2 秒，无网络请求）

# 打开离线可交互 demo（自包含，不发任何网络请求）
start demo\explore.html           # Windows
open demo/explore.html            # macOS
xdg-open demo/explore.html        # Linux

只需要 Python 3.8+，不用 pip install 任何东西 —— 默认输出 SVG（浏览器直接打开、放大不糊）； 想要 PNG（发微信/小红书那种）再装一个可选扩展包。

想当 MCP Server 跑（stdio 传输，4 个工具）：

python entry/mcp_server.py            # 直接跑，或者
docker build -t walk-kcal . && docker run -i --rm walk-kcal

快照里已经存好了门店、推荐菜、步行距离和热量 —— 麦当劳的官方营养值也是内嵌的 （demo 用到的 22 条，已按官方实时表校准）。

两套数据源，各配各的 —— 都不配也能跑：

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

输出格式是可选的：默认出 SVG —— 浏览器打开就能看、放大不糊，大多数场景够用； 想要 PNG（例如直接发微信、小红书），装一个很小的扩展包即可。

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

---

这两款能力是怎么接进来的

不看代码也能看懂的部分：

• 地图 / 语料 / 渠道都是可插拔的。 上层只认一套通用接口 —— 门店用经纬度， 热量用菜名，业态用归一化后的 12 个词。
• 某家的私有格式一律关在它自己的适配层里。 地图服务商的类目名怎么翻译、 某个品牌的门店接口只吃文字地标而不收经纬度 —— 这些差异都消化在各自的 provider / pack 内部，主流程一行都不用改。
• 所以换一家（百度、点评、美团…）＝ 加一个文件 + 一个环境变量。

想看它落到实处 → walkkcal/providers/（地图）· packs/（数据源）· docs/扩展开发.md

麦当劳那条链的具体调用（用了哪些 Tool、怎么和本地估算融合） → MCP_INTEGRATION.md

---

我们诚实地告诉你

额度是你自己定的预算，不是算法塞给你的建议 —— 走路只让它随距离增长。

中餐热量是估算的（平均误差 25–28%），因为菜谱里几乎没有可用的分量信息 （少数标了「2 人份」，标准却各不相同，我们没有采用），而且配料和调料的影响，有时候比主料还大。 我们花最大力气的地方不是「算得更准」，而是知道什么时候算不准，然后如实显示「算不出」—— 而不是猜一个看起来正常的数字。

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

---

免责

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

---

如果它帮到你了

如果你也常在楼下纠结「这顿吃什么」，它帮你把账算清楚了一点 —— 那点一下右上角的 ⭐ Star 就是最好的鼓励。它不会改变代码， 但会让更多同样在纠结的人看到这个工具。

（也欢迎提 Issue 说说你那个城市的菜算得准不准：哪个算错了、哪个该有却没有。 这比 Star 对它更有用。）

---

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