walk-kcal

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

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

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

<details> <summary><b>English TL;DR</b> (the README below is in Chinese)</summary>

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/

</details>

---

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

<p align="center"> <img src="assets/screenshot-preview.png" width="290" alt="输出长图：地图圈层 + 门店卡片，每道菜标绿（吃得起）或标红（超了）"><br> _{一张竖屏长图：附近哪家店、哪道菜<strong>你这顿吃不吃得下</strong> —— 绿色 = 吃得起，红色 = 超了（划掉）。} </p>

---

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

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

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

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

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

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

---

这个工具能做什么

| 你说 | 它做 | |---|---| | 我现在还能吃 450 卡，附近有什么能吃的 | 算额度、列附近店、每道菜标「吃得下 / 超了」 | | 走过去 500 米能多吃多少 | 走 500 米 ≈ 多挣 28 卡，额度实时重算 | | 麦当劳和隔壁面馆哪个更合适 | 同一额度下对比热量，一眼看出差距 | | 这家店整体会不会吃超 | 按推荐菜相对额度给店铺定性 |

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

---

独特之处

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

| 别人通常做的 | 我们做的 | |---|---| | 算一下麦当劳某一款汉堡的热量 | 你楼下的任意一家店，例如麦当劳 | | 把距离当成「还有多远」 | 把距离换成「这顿能多吃多少卡」 | | 只做一个平台 | 三种形式，共用同一份内核 |

三种形式，同一份结果：

| | 形式 | 怎么用 | |---|---|---| | ① | Skill | 对 Agent 说一句「附近吃什么」 | | ② | Bot | 在聊天软件里发消息，回复带可点的按钮 | | ③ | MCP | 从任何 MCP 客户端调用，标准 JSON-RPC |

<p align="center"> <img src="assets/screenshot-three-shells.png" alt="三种接入形式：① Skill（Agent 宿主）② Bot（聊天软件）③ MCP（任何 MCP 客户端）"> </p>

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

---

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

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

| 能力 | 供什么 | 来源 | |---|---|---| | 麦当劳 | 门店 + 推荐菜 + 官方精确营养值（官方表 158 条，含蛋白/脂肪/碳水/钠/钙） | 麦当劳官方 MCP | | 高德地图 | 周边任意餐厅 + 网友推荐菜 + 真实路网步行距离 | 高德开放平台 |

麦当劳的两条通道

| 通道 | 怎么开 | 你拿到什么 | |---|---|---| | 内置快照 | 什么都不用配 | 门店 + 推荐菜 + 官方热量值（收录 demo 用到的 22 条；官方全表 158 条，2026-10-16 已用实时表逐条校准） | | 实时数据 | 配上 MCD_MCP_TOKEN（+ WALKKCAL_MCD_LIVE=1） | 门店与营养值都实时从 mcp.mcd.cn 拉 |

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

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

| 你想要的 | 怎么配 | 你会拿到 | |---|---|---| | 两个都要（默认） | 不设 | 麦当劳与周边餐厅合并成一份结果 | | 只要麦当劳 | WALKKCAL_PACKS=mcd | 只有麦当劳，全部官方精确值 | | 只要周边餐厅（即「只要地图」） | WALKKCAL_PACKS=nearby | 只有你楼下那些面馆、火锅、小吃 |

也可以接你自己的 —— 点评的企业接口、美团、或者你手上任何一份门店／菜品数据。 数据源是可插拔的：加一个文件 + 一个环境变量，主流程 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 条，已按官方实时表校准）。

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

| 数据源 | 配了你会得到 | 需要什么 | |---|---|---| | 麦当劳 | 门店与营养值走实时（而非内置快照） | MCD_MCP_TOKEN + WALKKCAL_MCD_LIVE=1 | | 地图（默认高德） | 你周边任意餐厅 + 真实步行距离 | 高德地图的 AMAP_KEY |

# 抓新点位：地址 → 坐标 → 抓数 → 出图，实测约 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 对它更有用。）

---

<div align="center">

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

</div>