# 司芳糯米顾客服务 MCP

面向顾客的只读 MCP 服务，帮助完成“发现商品 → 选择口味 → 确认库存与食品信息 → 打开官方购买入口”。

本仓库只包含顾客可见能力，不包含内部订单、营业报表、毛利成本、会员资料、POS 凭据或真实经营数据。

## 能力

| MCP 工具 | 用途 |
| --- | --- |
| `get_store_info` | 查询门店地址、营业时间、状态和购买渠道 |
| `get_product_catalog` | 查询商品、价格、规格和门店可售状态 |
| `get_product_detail` | 查询原料、过敏原、保存方式和最佳食用时间 |
| `get_recommended_products` | 按口味、场景、人数、预算和库存推荐 |
| `get_store_inventory` | 查询门店商品库存状态 |
| `get_order_link` | 获取到店自取、美团或饿了么官方入口 |
| `get_latest_campaigns` | 查询当前活动、节令限定与上新 |

## 安全设计

- 所有工具只读，不代替顾客提交订单或支付。
- 正式数据和自动化测试夹具分离。
- 默认数据文件标记为 `template`，不会冒充真实经营数据。
- 库存只返回“可售、少量、售罄、不供应、未知”，不伪造精确数量。
- 价格、过敏原、保质期和活动有效期缺失时不推测。

## 运行

要求 Node.js 20 或更高版本。

```bash
npm install
npm run build
npm start
```

默认读取：

```text
deploy/customer-data.json
```

也可以通过环境变量指定由后台或同步任务生成的数据文件：

```bash
SZEFONG_CUSTOMER_DATA_PATH=/absolute/path/customer-data.json npm start
```

## 测试

```bash
npm test
```

测试覆盖 7 个业务工具，以及 MCP `tools/list`、`tools/call` 协议调用。

`test-fixtures/customer-data.json` 仅用于自动化测试，其中所有门店、商品、价格和链接均为虚构测试数据，禁止对客使用。

## 正式数据启用

正式上线前必须：

1. 录入经过负责人确认的门店、商品、价格、库存、活动和购买链接。
2. 由研发或食品安全负责人确认原料、过敏原、保存方式和最佳食用时间。
3. 将 `metadata.data_status` 从 `template` 改为 `verified`。
4. 填写 `metadata.updated_at` 和 `metadata.source`。

字段规范与 Agent 使用规则位于：

- `skill/szefong-customer-service/SKILL.md`
- `skill/szefong-customer-service/references/data-contract.md`

## MCP 配置示例

```json
{
  "mcpServers": {
    "szefong-customer": {
      "command": "node",
      "args": ["/absolute/path/szefong-customer-mcp/dist/customer/server.js"],
      "env": {
        "SZEFONG_CUSTOMER_DATA_PATH": "/absolute/path/szefong-customer-mcp/deploy/customer-data.json"
      }
    }
  }
}
```

## 许可

本仓库目前未附开源许可证。公开可见不等于允许复制、修改或商用；如需开放协作，请由仓库所有者另行选择许可证。