Food Core

Food Core 是一个独立运行的 Model Context Protocol（MCP）服务，用于记录食品库存、估算建议食用日期、管理食品消耗状态，并向 MCP 客户端返回到期提醒。

项目使用本地 JSON 文件保存库存，不依赖 Cyberboss 主项目，也没有第三方运行时依赖。

[!IMPORTANT] Food Core 提供的是库存与提醒功能，不是食品安全鉴定工具。对于未包装食品，系统给出的日期只是偏保守的建议；实际食用前仍应参考包装说明、储存条件和当地食品安全建议。

主要功能

• 添加、查询、修改和删除食品库存。
• 将 4 bottles、4瓶 等离散数量保存为四条独立记录。
• 将 500g 等按重量记录的食品保留为一条可调整记录。
• 根据食品种类和储存方式估算建议食用日期。
• 储存条件不明确时主动要求补充信息，不盲目猜测。
• 按“食品名称 + 储存位置 + 到期日”识别同组商品。
• 同组有 n 件商品时，从到期前 n + 3 个自然日开始提醒。
• 进入提醒期后，每次每日检查都会继续返回该食品，直到食品被删除。
• 食品已经过期但现实中仍然存在时，继续保留并提醒处理。
• 吃掉、喝掉、用完或扔掉整份食品后，直接从库存删除。
• 支持重复的离家/在家工作周期，必要时在离家前提前提醒。

MCP 工具

为了兼容已有部署，公开版本继续使用 cyberboss_food_* 工具名称：

工具	用途
cyberboss_food_add	添加一件或多件食品
cyberboss_food_list	查询库存
cyberboss_food_update	修改数量、位置、日期、备注等信息
cyberboss_food_mark	标记食品状态；现实中已经消失的食品会被删除
cyberboss_food_remove	根据 ID 永久删除一条记录
cyberboss_food_check_expiry	查询已过期、需要提醒和暂未到提醒期的食品
cyberboss_food_set_work_cycle	保存重复的离家/在家周期
cyberboss_food_set_reminder_policy	保存自定义提醒时间规则

服务还提供只读 MCP 资源：

cyberboss-food://tools/index

该资源会列出工具说明和输入结构。

环境要求

• Node.js 18 或更高版本
• 支持本地 stdio MCP 服务的客户端

项目只使用 Node.js 内置模块，因此不需要安装第三方 npm 依赖。

安装方法

git clone https://github.com/caroliny1031/food-core.git
cd food-core
npm test

环境变量

可选环境变量：

CYBERBOSS_FOOD_STORE_FILE

它用于指定私有库存 JSON 文件的位置。未设置时，默认路径为：

./data/food-inventory.json

第一次保存库存时，程序会自动创建数据目录和文件。库存可能包含食品名称、日期、备注和工作周期信息，请不要把真实库存文件提交到公开仓库。

仓库中的 .env.example 只是填写示例。Food Core 不会自动读取 .env 文件，需要通过系统环境变量或 MCP 客户端配置传入。

启动命令

npm start

等价命令：

node mcp-server.js

MCP 客户端配置

以下示例中的路径必须替换成你电脑上的绝对路径。建议将真实库存文件放在仓库目录之外。

Claude Desktop

将以下内容加入 Claude Desktop 的 MCP 配置：

{
  "mcpServers": {
    "food-core": {
      "command": "node",
      "args": ["/absolute/path/to/food-core/mcp-server.js"],
      "env": {
        "CYBERBOSS_FOOD_STORE_FILE": "/absolute/path/to/private-data/food-inventory.json"
      }
    }
  }
}

Windows 用户可以在 JSON 中使用正斜杠，或者将反斜杠写成双反斜杠。

Codex

在 Codex 的 config.toml 中添加：

[mcp_servers.food-core]
command = "node"
args = ["/absolute/path/to/food-core/mcp-server.js"]

[mcp_servers.food-core.env]
CYBERBOSS_FOOD_STORE_FILE = "/absolute/path/to/private-data/food-inventory.json"

其他 MCP 客户端

使用本地 stdio 服务配置：

• 启动命令：node
• 参数：/absolute/path/to/food-core/mcp-server.js
• 可选环境变量：CYBERBOSS_FOOD_STORE_FILE

使用示例

添加四瓶同批次牛奶

{
  "tool": "cyberboss_food_add",
  "arguments": {
    "name": "牛奶",
    "quantity": "4瓶",
    "storage": "fridge",
    "bestBeforeDate": "2026-08-10"
  }
}

Food Core 会创建四条独立记录。因为同组共有四瓶，所以从到期前 4 + 3 = 7 个自然日开始提醒。

喝掉一瓶后删除其中一条记录，剩余三瓶继续作为同组商品管理。

添加按重量记录的肉类

{
  "tool": "cyberboss_food_add",
  "arguments": {
    "name": "牛肉",
    "quantity": "500g",
    "storage": "freezer",
    "bestBeforeDate": "2026-09-01"
  }
}

500g 会保留为一条记录。如果只使用一部分，可以通过更新工具修改剩余重量。

检查到期状态

{
  "tool": "cyberboss_food_check_expiry",
  "arguments": {
    "now": "2026-08-04T09:00:00+08:00"
  }
}

在支持自然语言的 MCP 客户端里，也可以直接说：

• “帮我记四瓶牛奶，放在冷藏，8 月 10 日到期。”
• “我喝掉了一瓶牛奶。”
• “现在有哪些食品快过期了？”

提醒规则

同组商品的正常提醒提前量为：

提前天数 = 当前同组商品数量 + 3

提醒期从计算所得自然日的零点开始。例如一瓶牛奶 6 月 5 日到期，会从 6 月 1 日开始进入提醒期，并在 6 月 1、2、3、4 日的每日检查中持续返回。

如果到期后食品仍然存在，检查结果会继续把它列为已过期；只有在食品被吃掉、喝掉、用完或扔掉并从库存删除后，提醒才会停止。

Food Core 本身不会主动发送消息。要实现每天一次通知，需要由 MCP 客户端、智能体或定时任务每天调用一次 cyberboss_food_check_expiry。

测试

npm test

测试使用内存库存，不需要真实 JSON 文件，也不会修改你的实际库存。

常见问题

Food Core 会自己发通知吗？

不会。它负责计算并返回提醒状态，具体通知由调用它的 MCP 客户端、智能体或定时任务负责发送。

食品过期后会自动删除吗？

不会。只要食品现实中还存在，就继续保留。确认已经吃掉、喝掉、用完或扔掉后才删除。

库存保存在哪里？

优先使用 CYBERBOSS_FOOD_STORE_FILE 指定的路径；没有设置时使用 ./data/food-inventory.json。

可以把库存 JSON 提交到 GitHub 吗？

不建议。库存可能包含个人饮食、时间、备注和工作周期信息。默认 .gitignore 已排除整个 data/ 目录。

为什么工具名仍然带有 cyberboss_food_？

这是为了兼容已经部署的客户端。Food Core 本身是独立项目，不会导入或修改 Cyberboss 主项目源码。

可以自定义更早的提醒时间吗？

可以。使用 cyberboss_food_set_reminder_policy 或在检查时传入策略覆盖值。系统会采用适用规则中更早的提醒时间。

可以记录常温食品吗？

可以。可以使用 pantry 或 room temperature 等储存位置。预制菜应根据包装要求选择冷藏、冷冻或常温。

隐私建议

• 不要提交真实 food-inventory.json。
• 不要把密码、Token 或 Cookie 写进备注。
• 将库存文件保存在仓库之外，或至少确保 data/ 始终被忽略。
• 公开前使用 git ls-files 再检查一次实际提交文件。

许可证

本项目使用 MIT License，详见 LICENSE。