wangheng/xiaoqu_mcp_service

Fork 0

Files

T

my_local_kimi_dev2 798075f47e docs: add MCP external integration spec v1.0

2026-09-16 09:55:19 +08:00

6.4 KiB

Raw Blame History

小趣 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 标准握手序列

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 调用具体工具

请求统一头：

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

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 时为新信封：

{ "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。

6.4 KiB Raw Blame History Unescape Escape