# 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)。