# licha-order-mcp

李茶的茶 · 企迈点单 MCP Server。让 AI 在对话里找店、看菜单、组单算价；**开启下单能力后**还能帮顾客真实下单，付款始终在李茶小程序由顾客自己完成。

**默认安装 = 只读**：不装开关就和一期完全一样，不产生任何订单、不碰钱、不读经营数据。

## 用户怎么用

对你的 AI 说一句：

> 我要喝李茶的茶，去 GitHub 拉取一下：lichadecha/licha-order-mcp

装好后直接问「有什么奶茶」「哪家离我近」即可。目前仅支持到店（堂食/自取）。

第一次喝不知道选什么？直接问「有什么推荐」。想让 AI 帮你算哪家店近，可以再给它装一个高德地图 MCP（可选）。

## 给 AI Agent 的安装说明（用户让你拉取本仓库时照做）

1. 把下面这段合并进你的 MCP 配置（mcpServers）：

```json
"licha-order-mcp": {
  "command": "npx",
  "args": ["-y", "github:lichadecha/licha-order-mcp#v0.5.3"]
}
```

2. 把本仓库根目录的 `SKILL.md` 装进你的技能/指令目录（客户端支持 skills 时）。
3. 按你的客户端要求重启或重载 MCP。
4. 告诉用户装好了，并按 `SKILL.md` 的规则开始服务（第一句先说明：仅到店堂食/自取）。

要求 Node ≥ 18；首次运行自动构建（prepare → tsc）。npx 找不到时换 Node 安装目录下的绝对路径。

## 四个工具（默认只读形态）

| 工具 | 用途 |
| --- | --- |
| find_store | 按店名/商场/城市找门店，返回 storeId、营业状态、营业时间 |
| get_menu | 看菜单：无 keyword 返回分类，有 keyword 返回商品列表 |
| get_item_detail | 点单卡片：规格、做法（温度/糖度）、加料、是否估清 |
| preview_order | 组单算预估总价（本地累加，实际金额以门店收银台/订单为准） |

设置环境变量 `LICHA_ENABLE_ORDERING=1` 后另注册 5 个下单相关工具（bind_member / prepare_order / place_order / get_order_status / my_orders），安全约束见下方「安全边界」。

## 安装（WorkBuddy / 任意 MCP 客户端）

mcpServers 配置：

```json
{
  "mcpServers": {
    "licha-order-mcp": {
      "command": "npx",
      "args": ["-y", "github:lichadecha/licha-order-mcp#v0.5.3"]
    }
  }
}
```

安装命令固定指向版本标签（`#v0.5.3`），不追踪最新提交；升级时以新版 README 给出的标签为准。

要开下单相关的 5 个工具，在同一段配置里加 `env`（不加就是默认只读 4 工具；改装新标签时**整段一起换**，2026-09-08 曾漏掉这一行只见 4 个工具）：

```json
"licha-order-mcp": {
  "command": "npx",
  "args": ["-y", "github:lichadecha/licha-order-mcp#v0.5.3"],
  "env": { "LICHA_ENABLE_ORDERING": "1" }
}
```

要求 Node 不低于 18；首次安装会自动构建（prepare 钩子跑 tsc）。

## 凭证前置（仅授权机器）

本服务从本机读取企迈开放平台凭证，凭证不进本仓库、不进配置、不进日志：

- macOS keychain：qmai-cli 条目的 openKey（自动拆封）
- ~/.config/qmai/config.yaml：active profile 的 openId / grantCode

也可用环境变量覆盖：QMAI_OPEN_KEY / QMAI_OPEN_ID / QMAI_GRANT_CODE。
缺凭证时工具调用报「凭证不完整」，服务本身正常启动。

## 安全边界

- **身份边界：当前形态为单机单人。**MCP server 进程内只有一个会话身份，同一进程内多人共用会互相覆盖（后绑的人顶掉前一位，前一位的待确认单被作废）；远程化或开放多用户之前必须先接入传输层身份。
- 默认不注册任何写工具（`LICHA_ENABLE_ORDERING=1` 才注册），未开启时 `tools/list` 只有 4 个只读工具，写通道物理不可达。
- 开启后写白名单硬编码只有 1 条（创建订单），白名单外一律物理断路。
- 下单必经两阶段确认：AI 先把待确认单念给顾客 → 顾客确认 → 才提交；下单参数由服务端组装登记，AI 手里只有一个 5 分钟一次性令牌，改不了单的内容。
- 单笔 ≤¥100、单日每顾客 ≤5 单 / 全局 ≤10 单硬护栏；**永不代付**——付款一律由顾客在李茶小程序完成。
- 三本审计日志（读/写/访问）分离，识别值只留尾号。
- 出参只投影公开字段（店名/地址/营业状态/商品价格），不输出店长联系方式、成本等经营字段。

## v0.5.3 变更（开交易后体验补洞，24 号 A 批）

只改服务端行为与两条 SKILL 固定话术，工具入参不变；`SKILL.md` 同步升到 0.5.3。

- `get_menu` 不再返回已下架（status=20）商品；有候选时提示「列表不含当日估清状态，以 get_item_detail 为准」。
- `find_store` 营业状态与营业时间单独 10 分钟刷新，出参新增 `statusSampledAt`；取不到状态报「状态未知」而不是沿用一天前的旧值。
- 同一顾客重新组单后，前一版待确认单作废；旧 confirmToken 提交被拒并说明「已被更新的一版替代」，`prepare_order` 出参新增 `supersededPendingOrders`。
- MCP 进程启动时在 access-audit 记一条 `server_started`（版本 | pid | 写开关），宿主回收进程后可直接数日志。
- `prepare_order` 组单时查询本单可用券（5.1.7，只读），出参新增 `coupons`（可用券、预测系统默认会用的那张与券后实付）；`place_order` 读回新增 `couponApplied`，与预测比对并给出话术。查券失败不阻塞组单。

## v0.5.2 变更（安全收口门）

只改服务端行为，工具入参与话术不变；`SKILL.md` 同步升到 0.5.2。

- 结果未知的下单，只有拿到同一顾客、同一门店、时间对得上的那笔订单才解除未知，无关旧单和不完整的订单列表一律保持未知，额度不退还。
- 安全账本先落盘成功才发单：账本写不进去（盘满、被占位、行损坏）就拒绝发单，重启后每日计数、按顾客计数、未决记录和幂等键逐项恢复，不归零。
- 待确认单一律用本轮实读的最新价格与可售状态算钱，撞上单笔金额上限或商品估清/下架时直接拒签令牌，浏览缓存照旧可用。
- 必选做法（如温度）缺一项，确认门在签发令牌之前就拒绝并点名缺的那一组，不替顾客落 UI 默认值。
- 版本号单源自 `package.json`（不再有第二份硬编码），绑定会员的工具说明与「报新号即换绑、同一人再报幂等」的实际行为对齐，身份边界写进本文与 `SKILL.md`。

## 复验

```bash
npm install
npm run smoke:mcp
npm run smoke
```

smoke 系列还有 smoke:store / smoke:menu / smoke:detail / smoke:order。
冒烟走真实只读接口（基础类 0.1 元/百次，10 万次/月免费额度内，单次复验不超过 30 次调用）。

## 许可证

代码部分（src/、scripts/、test/、配置文件）采用 Apache-2.0；文字部分（SKILL.md、README 及其他文档）采用 CC BY-ND 4.0。「李茶的茶」名称与标识归品牌方所有，不在任何许可证授权范围内。详见 [LICENSE](./LICENSE)。