# ZIPFORCE Hub MCP 调用文档（2026-09-29 定稿）

把 SaaS 汇聚的全部电商运营数据（订单/财务/广告/库存/Listing 健康/词汇表）以 MCP 工具集
暴露给 LLM 客户端（Claude Code / Claude Desktop / GLM agent 等）。本文是唯一调用入口文档，
取代 09-24 接入指南（`mcp-setup-2026-09-24.md`，留档）。

## 1. 端点与协议（2026-09-29 拍板：统一用主域名）

- **URL**: `https://zipforcehub.com/mcp`（主域名定案；租户子域名同路径也可用，行为完全一致）
- **传输**: Streamable HTTP——单个 `POST`，JSON-RPC 2.0，服务端**无状态**（curl 单发 `tools/call`
  即可，不必先 `initialize`；标准 MCP 客户端的 initialize 流程也支持）
- **protocolVersion**: `2024-11-05` · serverInfo: `zipforce-hub 1.0.0`
- **认证**: `Authorization: Bearer mk_...`（MCP key，见 §5）
- **限速**: MCP 60 次/分 + 全局 240 次/分（按 key 身份计）；超限 429 + `Retry-After: 60`

## 2. 协议方法

| method | 说明 |
|---|---|
| `initialize` | 握手，返回协议版本与能力 |
| `notifications/initialized` | 通知（202 响应） |
| `ping` | 探活 |
| `tools/list` | 列出 8 个工具及入参 schema |
| `tools/call` | 调用工具：`params.name` + `params.arguments` |

**响应包络**：工具数据在 `result.content[0].text`，是 JSON 字符串（MCP 客户端自动解析；curl
裸调需二次 parse）。工具内部报错时 `result.isError=true`，错误文本在同一 `text` 里。

**错误码**：HTTP 401 + `-32001` = key 无效/已吊销；`-32602` = 未知工具名；`-32601` = 未知方法。

## 3. 工具集（8 个，全部只读，无裸 SQL）

所有 `brand` 参数可选；不传 = 该 key 所属租户的**全部品牌**。所有窗口按 **UTC 自然日**
（`day > CURRENT_DATE - days` 开界；与工作台的北京锚窗口在窗缘可能差一天）。

### brands — 品牌清单
返回 `{"brands": [...]}`。先调它确认 key 的可见范围。

### sales_summary — 销量汇总 `days=30, brand?`
`{orders, revenue_usd, net_usd, aov_usd}`。排除 Canceled/Cancelled；净利依赖结算事件
（滞后约 2 周，近几日偏低属正常）。

### orders_recent — 近期订单明细 `days=7, brand?, limit=20(≤100)`
`{orders: [{date, brand, country, status, skus, revenue_usd, net_usd}]}`。

### ads_performance — 广告表现 `days=30, brand?`
`{ad_spend, ad_sales, acos_pct, tacos_pct}`。ACOS=花费/广告销售，TACOS=花费/总营收。
- onno ← `audit.cleaned_amazon_ads_daily`（Amazon 站，含 campaign 级补账行，双币双计已在清洗层去重）
- 其他品牌 ← `audit.cleaned_ads_sku_daily`
- **Noon 广告不在此工具**（Noon 花费看工作台/广告页）
- 2026-09-29 修复：此前 onno 分支列名错误导致**任何调用必报错**，已修并验证
  （onno 30 天 $1,377.43 = 双计修正 + 483 行补账）

### inventory_risk — 库存风险 `brand?`
断货/低库存清单（`days_left` 短的在前，≤50 行）：`{risk: [{brand, sku, market, qty, daily_sales, days_left, status}]}`。

### listing_health — Listing 注意力清单 `brand?`
按 sku_mapping×最新排名快照×库存交叉（检查 ≤300 个 SKU）：`{attention: [评分<4 或断货/低库存 的 ≤20 条], checked: N}`。

### finance_monthly — 月度财务 `months=3, brand?`
`{months: [{mon, revenue_usd, net_usd, commission_usd, fba_usd}]}`（近 N 个自然月，源表直读）。

### glossary — 电商词汇表 `query?`
12 域 321 词条，支持中文/英文/缩写/释义模糊匹配；query 空 = 前 60 条概览。

## 4. 数据口径与时效

- 工具**每次调用实时查库**，不是快照——新数据落进既有表后自动可见
- **全部业务数据工具统一读 mars 清洗层 `audit.cleaned_*`**（2026-09-29 定稿：MCP 映射到
  cleandata；此前 sales_summary/orders_recent/inventory_risk/listing_health 曾读 raw，
  已全部迁移）：与 Web/API 同口径同数字，双计去重/防重规则生效
- 清洗 worker 每 2 小时一轮，**新 raw 数据最长滞后约 2 小时出现在 MCP**（一致性优先于新鲜度的取舍）
- 往既有表加行 = 全自动；全新表/新指标/新工具才需要改代码（注册进 TOOLS）

## 5. MCP key 管理（明文只返回一次，库内只存 sha256）

key 所属**租户**决定数据范围（RLS 四维隔离：账号/品牌/国家/平台不下放给 LLM）：

| 建 key 的域名 | key 可见品牌 |
|---|---|
| zipforce.zipforcehub.com | zipforce + onno |
| onno.zipforcehub.com | onno + brainnews |
| fittingirls 子域名 | fittingirls |

```bash
# 创建（管理员登录态；label 走查询参数，body 里的 label 不生效）
curl -X POST "https://<租户子域名>/api/mcp/keys?label=claude-code" -H "Cookie: <登录cookie>"
# → {"key": "mk_...."}   明文只此一次

GET  /api/mcp/keys          # 列表（id/label/last_used_at/revoked）
DELETE /api/mcp/keys/<id>   # 吊销（立即失效）
```

注意：建/管 key 的 `/api/*` 必须走**租户子域名**（按域名路由租户）；`/mcp` 本身用主域名。

## 6. 客户端配置示例

**Claude Code（一行）**

```bash
claude mcp add --transport http zipforce-hub https://zipforcehub.com/mcp \
  --header "authorization: Bearer mk_你的key"
```

**Claude Desktop / 任何 Streamable HTTP 客户端**

```json
{
  "mcpServers": {
    "zipforce-hub": {
      "type": "http",
      "url": "https://zipforcehub.com/mcp",
      "headers": { "authorization": "Bearer mk_你的key" }
    }
  }
}
```

**curl 裸调（无需 initialize）**

```bash
curl -s https://zipforcehub.com/mcp \
  -H "authorization: Bearer mk_你的key" -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ads_performance","arguments":{"brand":"onno","days":30}}}'
```

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

- 只读：无写入工具、无裸 SQL（防提示注入拖库）
- 隔离不下放：key→租户→RLS，跨租户/未授权品牌查询天然 0 行（已实测）
- key 可吊销：泄露即 `DELETE /api/mcp/keys/<id>`
- 审计留痕：key 创建/吊销进 audit_log，每次调用刷新 `last_used_at`
- MCP 是人工侧分析入口，不进采集/计算/写入链路（LLM 不进工作流铁律）

实现位置：`api/routers/mcp.py`（手写最小 streamable HTTP，零新依赖）· `pg-init/56-mcp-keys.sql`
