xiaoqu_mcp_service/xiaoqu-agent-service/doc/xiaoqu-mcp-integration-setup.md

xiaoqu-operations-ai 接入 xiaoqu-mcp 开发设置

1. 目标

让 ops-assistant-service 作为运营项目唯一 MCP Client 调用 xiaoqu_mcp_service，同时服务运营 iOS、Android。保持现有：

Router → Planner → Executor → Answer

每次调用使用当前已验证用户对应的 MCP Token，不把 MCP Token 放进提示词、Planner 输出、工具参数或普通日志。

客户端边界：

端	调用入口	MCP Token
运营 iOS	ops-assistant-service REST/WebSocket	不下发
运营 Android	ops-assistant-service REST/WebSocket	不下发

客户端只持产品登录凭证；ops-assistant-service 从已验证身份映射用户后，服务端获取并使用 MCP Token。

2. 当前代码结论

• ops-assistant-service 是 FastAPI + Python 3.12 服务。
• 当前依赖中没有 MCP SDK，也没有 tools/list / tools/call 客户端。
• Executor 目前直接调用本地 capability：customer_issues.*、smartclean.query。
• 用户身份来自 Gateway JWT，并通过 ops_identity_mappings 解析租户、用户和 scope_tags。
• 当前最合适的接入点是 Executor 的工具适配层，不新增第二套编排器。

3. xiaoqu-mcp 服务契约

3.1 MCP 调用

• 地址：POST <XQ_MCP_URL>/mcp
• 认证：Authorization: Bearer <xqak-token>
• 初始化顺序：initialize → notifications/initialized → tools/list → tools/call
• 初始化后保存 Mcp-Session-Id。
• tools/list 已按 Token scope 过滤，tools/call 仍由服务端再次鉴权。

3.2 Token 初始化

服务间调用：POST <XQ_MCP_URL>/api/open/token/ensure

X-Open-Key: <server-only-key>
Content-Type: application/json

请求体包含 mobile 或 email，以及固定的 scopeCode（首期建议 operation）。

约束：

• X-Open-Key 只能配置在受信任后端，不能下发 App。
• 业务后端必须从已验证用户会话查询手机号/邮箱，不能信任客户端或模型传入的身份字段。
• 首次创建返回 Token 明文；xiaoqu-mcp 同时保存 SHA-256 哈希和 AES-GCM 加密密文（密钥由 app.token-cipher-key 派生）。
• 已存在 Token 解密回传明文（二次获取），重复调用幂等复用同一把 Token；历史无密文 Token 自动轮换（禁用旧把、签发新把）。
• Token 密文解密失败必须报错；不得回退到哈希值或公共 Token。

4. 推荐实现

4.1 配置

在 config.py 增加以下 OPS_ASSISTANT_ 配置：

变量	默认值	说明
XQ_MCP_ENABLED	false	是否启用 MCP capability
XQ_MCP_URL	unset	例如 http://xiaoqu-mcp:8088，只存地址，不存用户 Token
XQ_MCP_OPEN_KEY	unset	仅用于服务端 Token 初始化，使用 SecretStr
XQ_MCP_SCOPE_CODE	operation	固定作用域，禁止由 Planner 或客户端选择
XQ_MCP_TIMEOUT_SECONDS	10	MCP 请求超时

启用时必须同时提供 URL、Open Key 和 scope；生产环境禁止明文写入仓库。

4.2 新增最小模块

建议只增加两个模块：

• src/ops_assistant_service/mcp_client.py
  • 管理 HTTP 请求、JSON-RPC、Session ID、Bearer Header、超时和错误映射。
  • 进程内按 user_id 缓存 MCP Session；账号或 Token 变化时销毁。
• src/ops_assistant_service/mcp_token_provider.py
  • 接收已验证的 SharedIdentity。
  • 从受信任用户资料源取得 mobile/email。
• 调用 ensure，首次签发返回明文；后续直接复用本地持久化 token。
  • 不接受 user_id/mobile/email 作为客户端覆盖参数。

不引入通用 MCP 框架、第二个 Agent 或数据库直连；现有 httpx 已足够完成首期只读接入。

4.3 Capability 映射

在 capability_registry.py 增加固定的本地 capability，禁止把远端 tools/list 原样暴露给 Planner：

本地 capability	MCP 工具	首期权限
xiaoqu.agent_count	agent.count	read
xiaoqu.agent_list	agent.list.query	read
xiaoqu.property_list	property.list.query	read

Planner 只能选择注册表中的名称和 schema。Executor 在调用前同时检查：

应用允许 ∩ 用户 scope_tags ∩ 租户/数据范围

远端返回结果先经过字段白名单投影，再交给 Answer；Token、原始 Header 和未授权字段不得进入 trace。

4.4 Executor 接入点

在 executor.py 增加一个只读分支：

validate_tool_input
  → 校验本地 capability 和参数白名单
  → 读取 SharedIdentity / DataScope
  → 获取当前用户 MCP Token
  → MCP tools/call
  → 结果投影
  → 现有 execution_trace / Answer 链路

现有 customer_issues.* 和 smartclean.query 保持不变。MCP 不可用时返回稳定的 TOOL_UNAVAILABLE，不得回退到公共 Token 或直接访问 xiaoqu-mcp 数据库。

5. 生命周期与安全

• 登录用户变化：先关闭旧 Session，再建立新用户 Session。
• MCP 返回 401：清理当前用户 Token，最多执行一次重新获取和重连；不自动重放副作用请求。
• 退出登录：清理本地/会话 Token 缓存；如需远端立即失效，走服务端管理端吊销能力。
• 日志只记录用户 ID、工具名、scope 和错误码，不记录 Token、Authorization Header 或手机号/邮箱明文。
• tools/list 仅用于校验远端能力；真正可调用集合以本地 allowlist 为准。

6. 开发顺序

1. 先确认 xiaoqu-mcp 的 ensure 契约和 Token 密文落库；运营链路不依赖 xiaoqu-ai 业务后端门面。
2. 增加 Settings 配置和启动校验。
3. 实现 mcp_token_provider.py 和 mcp_client.py，补充 JSON-RPC/Session 单元测试。
4. 增加 3 个只读 capability，并接入 Executor。
5. 增加用户隔离、scope 拒绝、401 重连、Token 脱敏和 MCP 不可用测试。
6. 先在 development/test 环境启用，完成联调后再进入 staging。

7. 验收标准

• 用户 A 的请求始终使用 A 的 MCP Token，用户 B 不能复用。
• A 无对应 scope 时，Planner/Executor 均不能调用该 MCP 工具。
• tools/list、tools/call 使用同一用户 Session 和 Bearer Token。
• 切换用户后旧 Session 不再发出请求。
• MCP 401 只刷新当前用户，且同一请求不重复执行副作用。
• 测试、日志、trace、配置文件和 Git 历史中均无 Token 明文。

8. 当前不做

• 不把 MCP Client 放进 iOS/Android 端。
• 不把全部远程工具动态注册给 Planner。
• 不复制 xiaoqu-mcp 数据库或绕过 MCP 权限。
• 不在本次首期引入写工具；写工具需另行设计审批、幂等和补偿协议。