# 小趣 MCP 外部接入规范

> 版本：v1.0（2026-09-15）
> 适用对象：CRM 等外部系统的后端集成方
> 状态：当前生效。认证换发流程（第 3 节）为小趣自定义扩展，后续可能升级为 OAuth 2.1 / MCP 标准授权，届时本规范会发新版并保留兼容期。

## 1. 服务边界

小趣 MCP 只做三件事：**供数据、供身份、守权限**。

- 供数据：查询工具（QUERY）+ 增量同步工具（SYNC），保证准确、一致、可恢复
- 供身份：Token 签发 / 吊销 / 自检
- 守权限：服务 Token 按授权 scope 白名单限工具，个人 Token 实时 ACL 行过滤

到期规则计算、AI 决策、消息推送、经营事项流转**不属于** MCP 职责，由接入方或小趣 AI 系统自行实现，MCP 不提供也不预留相关字段。

## 2. 接入端点与协议

| 项 | 值 |
|---|---|
| MCP 端点（生产） | `https://agent.ququclean.com/mcp` |
| 传输协议 | MCP Streamable HTTP（JSON-RPC 2.0） |
| 协议版本头 | `MCP-Protocol-Version: 2025-06-18` |
| 响应格式 | SSE（`text/event-stream`），取 `data:` 行解析为 JSON-RPC 消息 |
| 会话 | `initialize` 响应头返回 `Mcp-Session-Id`，后续请求必须携带 |

### 2.1 标准握手序列

```text
POST /mcp  initialize（JSON-RPC，带 id）
  ← 响应头取 Mcp-Session-Id，data: 行为 initialize 结果
POST /mcp  notifications/initialized（无 id，带 Mcp-Session-Id）
  ← 202，无响应体
POST /mcp  tools/list        # 自动发现工具及输入 JSON Schema
POST /mcp  tools/call        # 按 Schema 调用具体工具
```

请求统一头：

```http
Authorization: Bearer <xqak-...>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-06-18
Mcp-Session-Id: <initialize 返回的会话 ID>
X-Mcp-Schema-Version: 2
```

注意：`notifications/initialized` 生效后再发 `tools/list`，否则偶发空响应，重试即可。

## 3. 认证与凭证管理（自定义扩展）

### 3.1 两类凭证

| 凭证 | 形态 | 用途 | 获取方式 |
|---|---|---|---|
| 服务密钥 `X-Open-Key` | `xqok-...` | 换取访问 Token，**不是** MCP Token | 管理员在管理后台「服务密钥」页创建，明文只展示一次 |
| 访问 Token | `xqak-...` | 放进 `Authorization: Bearer` 调 `/mcp` | 用服务密钥调 ensure 接口换取，长期有效 |

### 3.2 换取 Token

```http
POST https://agent.ququclean.com/api/open/token/ensure
X-Open-Key: <服务密钥>
Content-Type: application/json

{"scopeCode":"sync","principalType":"service","serviceName":"<你的系统名>"}
```

响应 `token` 字段即访问 Token。该接口幂等：同一 subject 重复调用返回同一 Token。

个人 Token（前台点查场景）：同接口传 `{"mobile": "<人员手机号>"}`，幂等返回该人员的个人 Token（`user_delegated`），人员停用后 60 秒内自动失效。

### 3.3 凭证安全要求

- 服务密钥与 Token 只允许存接入方后端的密钥管理设施或环境变量，**禁止**下发浏览器/App、禁止写入日志、禁止提交代码库
- 密钥泄露：通知小趣管理员在管理后台执行「轮换」（旧密钥立即失效）或「吊销」
- 数据库只存密钥哈希，创建/轮换弹窗关闭后明文不可找回

## 4. 工具分类与调用约定

### 4.1 工具发现

`tools/list` 返回当前 Token 可见的全部工具及入参 JSON Schema。**可见性由 Token 绑定的 scope 白名单决定**——未授权的工具不出现在列表中，接入方应按 `tools/list` 结果动态适配，不要硬编码工具清单。

### 4.2 统一输出信封

所有工具返回 `structuredContent`，`X-Mcp-Schema-Version: 2` 时为新信封：

```json
{ "schema_version": 2, "request_id": "...", "data": { ... } }
```

- 不带该请求头返回 v1 老结构（兼容期内有效）
- `request_id` 必须记入接入方日志，双向排查用；Token 与手机号明文不落日志

### 4.3 通用入参约束

- 所有工具**禁止传 `tenant_id` / `scope`**，租户从 Token 推导，传了返回 `PERMISSION_DENIED`
- 分页类工具 `limit` 上限 200，超出截断并在响应带 notice

## 5. 错误码与重试规则

| 错误码 | 含义 | 接入方动作 |
|---|---|---|
| `UNAUTHENTICATED` | Token 吊销 / 人员停用 | 重新 ensure 取 Token；仍失败则告警人工介入 |
| `PERMISSION_DENIED` | 工具不在 Token scope 白名单，或传了 tenant_id | 检查绑定与入参，**不要**重试 |
| `RATE_LIMITED` | 触发限流 | 指数退避重试（1s/2s/4s…上限 60s） |
| `SYNC_CURSOR_EXPIRED` | 同步快照/游标过期或被篡改 | 清空本地镜像，`syncToken=null` 全量重建 |
| `INVALID_ARGUMENT` | 入参不符合 Schema | 修正后重发，不要原样重试 |

限流分档：SYNC 工具独立配额档，与 QUERY 互不占配额。

## 6. 增量同步协议（SYNC 工具）

工具：`users.changes.list` / `properties.changes.list` / `contracts.changes.list`。

入参仅三个：`syncToken`、`cursor`、`limit`。

协议语义：

- **快照**：每轮同步签发 `snapshot_id` + `data_cutoff_at`，同一快照内翻页结果稳定
- **游标**：页内 `(modify_time, id)` 复合游标；`has_more=true` 时带 `next_cursor` 翻页
- **续传**：仅末页（`has_more=false`）签发 `next_sync_token`；中断后从本地保存的 `sync_token + cursor` 继续，不重不漏
- **tombstone**：`deleted_at` 非空为删除标记，本地镜像应标记删除
- **版本字段**：`version` 由 `modify_time` 派生，仅用于调试核对，禁止用作并发控制

接入方必须持久化每页的 `sync_token + cursor`（断点恢复），实现 `SYNC_CURSOR_EXPIRED` 全量重建分支，并在扫描启动前用 `integration.context.get` 校验 `principal_type=tenant_service` 且 capability 含 SYNC，拿错个人 Token 时拒绝执行扫描。

## 7. 交付物与责任划分

| 小趣侧交付 | 接入方自负责 |
|---|---|
| 本规范（契约定义） | MCP 客户端实现（可用任意标准 MCP Client SDK） |
| 管理后台服务密钥创建/轮换/吊销 | 密钥与 Token 的安全存储 |
| 工具清单及入参 Schema（`tools/list` 自动发现） | 本地镜像 upsert / 逻辑删除 |
| 错误码语义与限流档位 | 定时任务调度、游标持久化、重试退避 |
| `request_id` 双侧排查支持 | 业务规则、AI 决策、推送 |

详细逐步接入示例（含报文样例与伪代码）见《CRM 接入手册》`doc/crm-integration-guide.md`。