wangheng/xiaoqu_mcp_service

Fork 0

Files

T

xqzp2026 dc2367e1cf docs(mcp): align operations web integration design

2026-09-07 19:16:58 +09:30

6.7 KiB

Raw Blame History

xiaoqu 多产品 Agent 统一接入 xiaoqu-mcp 总体设计

1. 设计结论

xiaoqu-ai 与 xiaoqu-operations-ai 共用 xiaoqu-mcp 的服务能力、Token 原语、工具协议、权限模型和审计规则，但保留各自的 Agent Runtime：

xiaoqu-ai iOS / Android / Web
        │ 产品登录 Token
        ▼
xiaoqu-ai Gateway / Agent Runtime ───┐
                                     │ 用户 MCP Token（仅服务端持有）
xiaoqu-operations-ai iOS / Android / Web
        │ 产品登录 Token             │
        ▼                            │
ops-assistant-service ───────────────┤
                                     ▼
                         xiaoqu-agent-service /mcp
                         Token + Scope + Tool
                         行级权限 + Audit

共同的是后端协议，不是 Swift、Kotlin 或 Web UI 代码。任何客户端都不实现本次 xiaoqu-mcp Client，不保存用户 MCP Token，也不接触 X-Open-Key。

2. 范围与文档分工

层级	项目	项目目录	文档
总体	xiaoqu-mcp	当前仓库 `xiaoqu-agent-service`	本文
详细设计	xiaoqu-ai iOS、Android、Web、服务端 Agent	`/Users/tonylai/xiaoquai/xiaoqu-ai`、`/Users/tonylai/jiaxk/xiaoqu-ai-android`	`xiaoqu-ai-mcp-integration-design.md`
详细设计	xiaoqu-operations-ai iOS、Android、Web、服务端 Agent	`/Users/tonylai/wangheng/xiaoqu-operations-ai`	`xiaoqu-operations-ai-mcp-integration-design.md`

本文只定义两个产品必须共同遵守的架构和安全契约。项目代码落点、配置、Capability 映射和项目级验收只写在对应详细设计中。

3. 统一职责

层	职责
iOS / Android / Web	登录、会话 UI、流式展示和确认交互；只携带产品登录凭证
产品 Gateway	验证登录态，建立可信用户、租户和数据范围上下文
产品 Agent Runtime	编排 Agent，维护本地 Capability allowlist，获取用户 MCP Token 并调用 MCP
xiaoqu-agent-service	校验 MCP Token，按 scope 过滤工具，执行用户/租户/行级权限并记录审计

两个产品可以暴露不同的 Capability 集合，但都必须通过同一套 MCP 鉴权和工具契约执行。运营项目不得直接调用 xiaoqu-ai Agent，也不得复制或直连 xiaoqu-mcp 数据库。

4. 认证与 Token 契约

4.1 三类凭证

凭证	使用链路	用途
产品登录 Token	客户端 → 产品 Gateway	证明当前产品用户身份
`X-Open-Key`	产品 Agent Runtime → `/api/open/token/ensure`	服务间获取指定用户的 MCP Token
用户 MCP Token `xqak_*`	产品 Agent Runtime → `/mcp`	绑定 MCP 用户、scope、权限和审计

X-Open-Key 和用户 MCP Token 只能存在于受信任服务端，不得进入客户端、prompt、模型输出、工具参数、普通日志或 Git。

4.2 用户映射

Gateway 验证产品登录 Token。
Agent Runtime 从可信上下文取得产品用户、租户和数据范围。
Agent Runtime 从受信任用户资料源取得手机号或邮箱。
Agent Runtime 使用服务端固定的 scopeCode 调用 POST /api/open/token/ensure。
xiaoqu-agent-service 返回该 MCP 用户对应的 Token。
Agent Runtime 使用该 Token 调用 /mcp。

客户端、Planner 和模型不得提供或覆盖 user_id、手机号、邮箱、租户、数据范围或 scopeCode。每个产品启用前必须核对管理后台中的真实 scope 和工具绑定。

4.3 `POST /api/open/token/ensure`

认证：X-Open-Key: <server-only-key>。

{
  "mobile": "<trusted-user-mobile>",
  "email": "<trusted-user-email>",
  "scopeCode": "<server-configured-scope>"
}

mobile、email 至少一个，手机号优先。
已有有效 Token：解密 key_cipher 并返回同一明文。
历史无密文 Token：禁用旧 Token 并自动签发新 Token。
不存在有效 Token：创建长期 Token；回收通过禁用实现。
密文解密失败必须报错，不得回退哈希值或公共 Token。

错误语义：400 参数或 scope 错误，401 Open Key 无效，403 Open API 未启用，404 用户不存在或不属于允许的企业账号。

5. MCP 协议与权限

调用入口：POST /mcp。

Authorization: Bearer <user-mcp-token>
Content-Type: application/json
Accept: application/json, text/event-stream

调用顺序：initialize → notifications/initialized → tools/list → tools/call。初始化响应包含 Session ID 时，后续请求携带 Mcp-Session-Id。

最终可执行能力为：

产品 Agent capability allowlist
  ∩ MCP Token scope
  ∩ 当前用户权限
  ∩ 当前租户/数据范围

tools/list 必须按 Token scope 过滤，tools/call 必须再次强制校验。不得仅依赖提示词、本地隐藏菜单或 Planner 输出做授权。

6. 生命周期与错误处理

缓存键至少包含产品、租户、产品用户 ID 和 scope。
登录用户变化或退出登录时，旧用户的 Token 缓存和 MCP Session 必须失效。
MCP 返回 401 时，只清理当前用户缓存并重新 ensure 一次。
只读调用可在重新连接后重试一次；有副作用调用不得自动重放。
MCP 不可用时返回稳定的工具不可用错误，不得回退公共 Token 或数据库直连。
日志只记录用户 ID、scope、工具名、状态和耗时，不记录凭证明文或手机号/邮箱明文。

7. 联调顺序

#	工作	完成标准
1	确认两个产品的用户映射与实际 scope	scope 已存在并绑定所需工具，不依赖客户端身份字段
2	完成 xiaoqu-ai 服务端接入	iOS、Android、Web 经同一服务端适配器调用
3	完成 xiaoqu-operations-ai 服务端接入	运营 iOS、Android、Web 经 ops-assistant-service 调用
4	跨用户、跨租户和跨产品回归	无 Token 泄露、串号、越权或副作用自动重放

8. 总体验收与回退

所有客户端请求只出现产品登录 Token，不出现用户 MCP Token 或 X-Open-Key。
用户 A/B、不同租户、不同 scope 的 Token 缓存和 MCP Session 完全隔离。
绕过 tools/list 直接调用 tools/call 仍会被服务端拒绝并审计。
两个产品的本地 allowlist 可以不同，但同名 MCP 工具的请求和响应契约一致。
任一产品回退时，只关闭该 Agent Runtime 的 MCP Capability 开关；客户端继续使用原有 Agent 功能。
禁止回退为客户端共享固定 Token、公共服务端 Token 或数据库直连。

6.7 KiB Raw Blame History Unescape Escape