# ZIPFORCE Hub MCP 接入指南（SaaS 数据 MCP 化 · 2026-09-24 上线）

把 SaaS 的运营数据（订单/财务/广告/库存/Listing 健康）以 **MCP 工具集**暴露给 Claude——
在 Claude Code / Claude Desktop 里直接问"最近 30 天净利多少""哪些 SKU 断货了"。

## 快速接入

### ① 生成接入密钥（管理员）

```bash
# 用租户管理员会话生成（明文仅返回一次，立即保存）
curl -X POST "https://<你的租户域>/api/mcp/keys?label=claude" \
  -H "Cookie: <登录 cookie>" 
# → {"key": "mk_....", ...}
```

密钥只存 sha256，明文丢失只能撤销重建：`DELETE /api/mcp/keys/<id>`、列表 `GET /api/mcp/keys`。

### ② Claude Code 接入（一行）

```bash
claude mcp add --transport http zipforce "https://<租户域>/mcp" \
  --header "Authorization: Bearer mk_你的密钥"
```

### ③ Claude Desktop / 其他 MCP 客户端（streamable HTTP）

- URL: `https://<租户域>/mcp`
- Header: `Authorization: Bearer mk_...`
- 协议: streamable HTTP（JSON-RPC，protocolVersion 2024-11-05）

## 工具集（7 个，全部只读）

| 工具 | 作用 | 参数 |
|---|---|---|
| `brands` | 本租户可见品牌清单 | — |
| `sales_summary` | 订单数/营收/净利/客单价 | days=30, brand? |
| `orders_recent` | 近期订单明细 | days=7, brand?, limit=20 |
| `ads_performance` | 广告花费/ACOS/TACOS | days=30, brand? |
| `inventory_risk` | 断货与低库存清单 | brand? |
| `listing_health` | 低评分/断货 SKU 注意力清单 | brand? |
| `finance_monthly` | 月度营收/净利/佣金/FBA | months=3, brand? |

返回 JSON 均带口径注释（如净利结算滞后约 2 周、ACOS/TACOS 定义）。

## 安全边界（与平台铁律一致）

- **只读**：无写入工具、**无裸 SQL**（防提示注入拖库）
- **四维隔离不下放**：密钥→租户→RLS，跨租户/跨品牌查询天然为空（已实测 onno 密钥查
  zipforce 品牌 0 行）；员工品牌授权范围同样生效
- **密钥可撤销**：泄露即 `DELETE /api/mcp/keys/<id>`，立即失效
- **审计留痕**：key 生成/撤销进 audit_log，每次调用更新 last_used_at
- MCP 是**人工侧分析入口**（与 AI 助手同域），不在采集/计算/写入链路中——LLM 不进工作流铁律不变

## 实现位置

`api/routers/mcp.py`（手写最小 streamable HTTP，零新依赖）· `pg-init/56-mcp-keys.sql` ·
网关 `/mcp` 路由（主站 + 租户子域均已放行）
