docs: add MCP external integration spec v1.0
This commit is contained in:
my_local_kimi_dev2
@@ -0,0 +1,140 @@
|
||||
# 小趣 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`。
|
||||
Reference in New Issue
Block a user