内容
# Food Core MCP
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 资源：
```text
cyberboss-food://tools/index
```
该资源会列出工具说明和输入结构。
## 环境要求
- Node.js 18 或更高版本
- 支持本地 stdio MCP 服务的客户端
项目只使用 Node.js 内置模块，因此不需要安装第三方 npm 依赖。
## 安装方法
```bash
git clone https://github.com/caroliny1031/food-core.git
cd food-core
npm test
```
## 环境变量
可选环境变量：
```text
CYBERBOSS_FOOD_STORE_FILE
```
它用于指定私有库存 JSON 文件的位置。未设置时，默认路径为：
```text
./data/food-inventory.json
```
第一次保存库存时，程序会自动创建数据目录和文件。库存可能包含食品名称、日期、备注和工作周期信息，请不要把真实库存文件提交到公开仓库。
仓库中的 `.env.example` 只是填写示例。Food Core 不会自动读取 `.env` 文件，需要通过系统环境变量或 MCP 客户端配置传入。
## 启动命令
```bash
npm start
```
等价命令：
```bash
node mcp-server.js
```
## MCP 客户端配置
以下示例中的路径必须替换成你电脑上的绝对路径。建议将真实库存文件放在仓库目录之外。
### Claude Desktop
将以下内容加入 Claude Desktop 的 MCP 配置：
```json
{
"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` 中添加：
```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`
## 使用示例
### 添加四瓶同批次牛奶
```json
{
"tool": "cyberboss_food_add",
"arguments": {
"name": "牛奶",
"quantity": "4瓶",
"storage": "fridge",
"bestBeforeDate": "2026-08-10"
}
}
```
Food Core 会创建四条独立记录。因为同组共有四瓶，所以从到期前 `4 + 3 = 7` 个自然日开始提醒。
喝掉一瓶后删除其中一条记录，剩余三瓶继续作为同组商品管理。
### 添加按重量记录的肉类
```json
{
"tool": "cyberboss_food_add",
"arguments": {
"name": "牛肉",
"quantity": "500g",
"storage": "freezer",
"bestBeforeDate": "2026-09-01"
}
}
```
`500g` 会保留为一条记录。如果只使用一部分，可以通过更新工具修改剩余重量。
### 检查到期状态
```json
{
"tool": "cyberboss_food_check_expiry",
"arguments": {
"now": "2026-08-04T09:00:00+08:00"
}
}
```
在支持自然语言的 MCP 客户端里，也可以直接说：
- “帮我记四瓶牛奶，放在冷藏，8 月 10 日到期。”
- “我喝掉了一瓶牛奶。”
- “现在有哪些食品快过期了？”
## 提醒规则
同组商品的正常提醒提前量为：
```text
提前天数 = 当前同组商品数量 + 3
```
提醒期从计算所得自然日的零点开始。例如一瓶牛奶 6 月 5 日到期，会从 6 月 1 日开始进入提醒期，并在 6 月 1、2、3、4 日的每日检查中持续返回。
如果到期后食品仍然存在，检查结果会继续把它列为已过期；只有在食品被吃掉、喝掉、用完或扔掉并从库存删除后，提醒才会停止。
Food Core 本身不会主动发送消息。要实现每天一次通知，需要由 MCP 客户端、智能体或定时任务每天调用一次 `cyberboss_food_check_expiry`。
## 测试
```bash
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](LICENSE)。
