Skip to main content
Glama

walk-kcal

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

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

试试看(不用装任何东西) | GitHub 源码

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 卡起步

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

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

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


Related MCP server: nutrition-mcp

这个工具能做什么

你说

它做

我现在还能吃 450 卡,附近有什么能吃的

算额度、列附近店、每道菜标「吃得下 / 超了」

走过去 500 米能多吃多少

走 500 米 ≈ 多挣 28 卡,额度实时重算

麦当劳和隔壁面馆哪个更合适

同一额度下对比热量,一眼看出差距

这家店整体会不会吃超

按推荐菜相对额度给店铺定性

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


独特之处

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

别人通常做的

我们做的

算一下麦当劳某一款汉堡的热量

你楼下的任意一家店,例如麦当劳

把距离当成「还有多远」

把距离换成「这顿能多吃多少卡」

只做一个平台

三种形式,共用同一份内核

三种形式,同一份结果:

形式

怎么用

①

Skill

对 Agent 说一句「附近吃什么」

②

Bot

在聊天软件里发消息,回复带可点的按钮

③

MCP

从任何 MCP 客户端调用,标准 JSON-RPC

麦当劳 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 对它更有用。)


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

Available Tools

4 tools
explain_conceptB

科普 NEAT / MET 的含义与依据,不消耗任何 MCP 调用。

NameRequiredDescriptionDefault
topicNo

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It does disclose one genuine behavioral trait — that it consumes no MCP calls (i.e. no cost/rate-limit concern) — which is valuable. But it says nothing about output format, permissions, or whether it is read-only, leaving a modest gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with the verb and topic stated first and the cost note second. No wasted words, though it is terse enough that it stops short of explaining the return.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 1-param, 0-required tool with no output schema, the description covers purpose and cost but omits any indication of what the explanation looks like or how detailed it is. Adequate but leaves a gap the missing output schema does not fill.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and there is one enum parameter (topic: neat|met). The description names both 'NEAT' and 'MET', implicitly mapping to the enum values, so it partially compensates. It adds no further meaning about acceptable values or defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (科普/explain) and resource (NEAT / MET 的含义与依据), so the agent knows this is an informational/reference tool rather than a computation. It is clearly distinguishable from siblings like walk_allowance and what_can_i_eat, though it never names them explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The clause '不消耗任何 MCP 调用' implies you can call this freely when you need background on NEAT/MET, which is a usable context hint. However, there is no explicit when-to-use/when-not statement and no reference to alternative tools for related questions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nearby_foodA

附近门店 + 每道菜能不能吃下。跨数据源(麦当劳 MCP + 周边本地餐厅)。当用户问"附近有什么能吃的""现在吃什么""有什么推荐的"时使用。

★ 用户若给出限定条件,填对应参数(不要自己过滤结果): · "只看快餐/附近有什么快餐/想吃西餐/来点小吃" → industry · "不想走太远/就附近/500 米内" → radius_m=500 · "还有别的吗/换一批/再看看" → page 加 1 不带任何参数调用也能返回合理结果(默认半径 1500 米、第 1 批)。 返回值里的 next 字段是建议的下一步参数,可直接采用。

NameRequiredDescriptionDefault
pageNo批次号,从 0 开始。用户说"换一批""还有别的吗"时把上次返回的 meta.page 加 1。
quotaNo本餐额度(卡);不给则按距离自动算
industryNo业态限定。用户说"只看快餐""附近有什么西餐""想吃日料"时填对应值。不填=不限。
latitudeNo用户所在纬度(GCJ-02)
radius_mNo搜索半径(米),默认 1500。用户说"别走太远""就近"时填 500。
longitudeNo用户所在经度(GCJ-02)

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does meaningful work: it discloses the cross-source nature, the defaults used when no params are supplied (1500m, batch 1), the pagination protocol via page, and the presence of a 'next' suggestion field in the response. Gaps remain: it never explains how latitude/longitude are obtained (the tool cannot locate the user without them) and says nothing about latency, rate limits, or permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose then trigger conditions, and each bullet maps a distinct user utterance to a distinct parameter, so the length is mostly earned. The '★' mapping block duplicates the per-parameter descriptions in the schema, which is mild redundancy but not padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-param, zero-annotation, no-output-schema tool, this covers defaults, pagination, and the source mix well enough to invoke correctly without authoring params. It is incomplete on two counts that matter for a location tool: how coordinates are sourced, and how to choose between this and 'what_can_i_eat'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameter-level mapping guidance in the description (industry, radius_m=500, page+1) largely restates what the schema already documents per field. It adds one non-schema rule ('fill the param instead of filtering results yourself'), but that belongs more to usage than to parameter semantics, so this sits at the baseline for fully-documented schemas.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource: it returns nearby stores plus per-dish affordability, and explicitly notes it spans two data sources (McDonald's MCP + local restaurants). That is far more specific than the name alone. However, it never distinguishes itself from the sibling 'what_can_i_eat', which by name sounds like a competing answer to the same user intent, so the agent gets no disambiguation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Strong trigger coverage: it names concrete user phrasings ('附近有什么能吃的', '现在吃什么', '有什么推荐的') and maps constrained phrasings to specific parameters, plus a 'don't pre-filter results yourself' rule and the no-argument fallback behavior. It stops short of the top mark because it never states when NOT to use it or names an alternative sibling for the overlapping case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

walk_allowanceA

卡路里额度核算。给定步行距离,算出可用的本餐额度。当用户问"走过去能吃多少""额度还剩多少"时使用。

NameRequiredDescriptionDefault
distance_mNo步行距离(米)

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing about the underlying model: it never mentions whether user weight/step length are assumed, whether the computation is side-effect-free, or what the result contains. For a calculator tool this is a meaningful gap, since the agent cannot tell what inputs the result actually depends on.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the first states the computation and its output, the second gives the invocation condition. Nothing is wasted and the purpose is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter computed tool with no output schema, the description adequately covers what it produces ('available allowance for this meal'). The remaining gap is that the derivation assumptions (calorie-per-step or user profile) are never hinted at, but the tool's surface is small enough that this is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (distance_m with '步行距离(米)'), so the schema already documents the single parameter. The description only restates 'given walking distance' without adding units, constraints, or sign/range guidance, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific transformation: given walking distance, compute the calorie allowance available for the next meal. It is clearly distinguishable from siblings like nearby_food or explain_concept, though it never explicitly contrasts itself with what_can_i_eat, which sounds closely related.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names concrete trigger phrases ('how much can I eat after walking', 'how much allowance is left'), giving the agent a usable activation condition. However, it offers no exclusions or explicit routing away from the sibling tool what_can_i_eat, so the boundary remains inferential.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

what_can_i_eatA

额度内能吃什么(跨数据源)。当用户问"我现在能点什么""有什么便宜(低卡)的"时使用。

用户给业态限定时填 industry;用户说"还有吗"时用 nearby_food 的 page 参数。

NameRequiredDescriptionDefault
quotaNo本餐额度(卡)
industryNo业态限定,同 nearby_food。不填=不限。
latitudeNo用户所在纬度,配 longitude 一起传。
radius_mNo搜索半径(米),默认 1500
longitudeNo用户所在经度。**传了才能走麦当劳实时** —— 麦当劳 MCP 只吃文字地名,需要用它把坐标翻译成 city+keyword;不传就只能用本地快照。

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does disclose the cross-datasource aggregation behavior and, indirectly, that coordinate-free calls degrade to a local snapshot — but it says nothing about return shape, ranking, staleness, or failure modes when quota is omitted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose sentence followed by two compact routing sentences; every clause maps to a decision the agent must make. No filler or restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

All five parameters are optional and there is no output schema, so return values need not be explained. However, the description never states what happens when quota is omitted or how results are ordered, which matters for a cross-source aggregation tool with zero required inputs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3, but the description adds conditional semantics the schema lacks: fill industry only when the user constrains the business type, and the pagination follow-up belongs to nearby_food, not this tool's own parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource with scope: what can be eaten within the calorie quota, aggregated across data sources. The parenthetical '(跨数据源)' distinguishes it from a single-source lookup like nearby_food, though the distinction is brief rather than fully drawn.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit trigger phrases ('我现在能点什么', '有什么便宜(低卡)的'), an explicit conditional for filling industry when the user names a business type, and an explicit routing rule to use nearby_food's page parameter on follow-up ('还有吗'). This is close to ideal when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updates
    • First observedexplain_concept
    • First observednearby_food
    • First observedwalk_allowance
    • First observedwhat_can_i_eat

TDQS

A3.7/5.0

Scored across 4 tools

Disambiguation3/5

walk_allowance and explain_concept are clearly distinct, but nearby_food and what_can_i_eat overlap significantly for general 'what can I eat' queries. Descriptions try to separate them by context (nearby vs. within allowance), but the boundary remains fuzzy and could lead to misselection.

Naming Consistency3/5

All tool names use snake_case, but the naming patterns are mixed: walk_allowance (noun phrase), nearby_food (adjective_noun), what_can_i_eat (question phrase), and explain_concept (verb_noun). This inconsistency makes the set less predictable despite being readable.

Tool Count5/5

Four tools cover the core decision support loop: calculate allowance, discover nearby food, filter by allowance, and explain concepts. Each tool earns its place with no redundancy, and the count is well-suited to the server's narrow purpose.

Completeness4/5

The surface covers the main workflow: compute allowance, find nearby options, select within allowance, and educate on concepts. Minor gaps exist, such as no tool for detailed nutrition per dish or user preference tracking, but the core decision-making loop is complete.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Related MCP Connectors

Related MCP Servers

  • -
    license
    Not graded
    quality
    Not graded
    maintenance
    A calorie tracking MCP server that processes food photos and text descriptions to automatically log nutrition data to Google Sheets. Integrates with Apple Health for fitness metrics and provides SMS interface for convenient meal logging.
    -
  • F
    license
    Not graded
    quality
    B
    maintenance
    Enables calorie and macronutrient tracking by letting users search foods, build recipes, compute macros, and log meals through an MCP server, with all nutrition calculations performed server-side.
    -
  • A
    license
    Not graded
    quality
    C
    maintenance
    Provides a local-first Chinese dietary coaching server that reviews meals, recomputes nutrition from bundled food data, and manages user profiles and meal history in a private local SQLite database.
    MIT