xiaoqu-ai
0d43b6af23
问题：新工具部署后必须先手工绑 scope_tool，否则调用方 PERMISSION_DENIED。 2026-10-21 新增的 hardware.statistics.query 与用纸类工具因此一直不可用。 改动： - ScopeToolSyncService：启动时按 mcp.scope-tool-bindings 幂等写入 scope_tool · 格式 sync=toolA,toolB（多条用 ; 分隔） · 只新增不删除；作用域/工具缺失记 WARN 跳过，不阻断启动 · @Order(2) 保证在工具注册（ToolSyncService）之后执行 - application-prod.yml：默认绑定 sync 作用域到 CRM 画像所需的 4 个工具 （district.paper.statistics / device_average / trace.list / hardware.statistics）， 可通过 MCP_SCOPE_TOOL_BINDINGS 覆盖 - 设计文档 doc/scope-tool-binding-sync-design.md - 单测 3 例（解析/幂等/容错） 部署后启动日志会打印 scope-tool binding 新增记录，可直接核对。
1.6 KiB
1.6 KiB
作用域-工具绑定启动同步（ScopeToolSyncService）
背景
新 MCP 工具部署后，必须绑到调用方使用的 scope_tool 记录，否则调用会返回
PERMISSION_DENIED：该 token 的作用域不包含工具 [...]。
此前这一步是管理员手工执行 SQL，问题：
- 容易遗漏（2026-10-21：新增的
hardware.statistics.query与用纸类工具部署后一直不可用）； - 无法随代码评审，变更不可追溯；
- 每个环境（test/operation/xiaoqu-ai/sync）都要重复操作。
方案
启动时读取配置 mcp.scope-tool-bindings，幂等写入 scope_tool：
mcp:
scope-tool-bindings: ${MCP_SCOPE_TOOL_BINDINGS:sync=tool.a,tool.b}
- 多条绑定用
;分隔，同一条内多个工具用,分隔 - 格式：
scopeCode=toolName1,toolName2 - 执行顺序在
ToolSyncService（工具注册）之后（@Order(2)）
安全约束
| 约束 | 说明 |
|---|---|
| 只新增，不删除 | 不触碰管理员手工配置的其他绑定 |
| 能力变更可评审 | 绑定写在 application-prod.yml / 环境变量，随代码 diff 审查 |
| 失败不阻断启动 | 作用域或工具不存在时记 WARN 并跳过 |
| 显式声明 | 默认值即"CRM 同步所需 4 个工具"，不含其他能力 |
测试
ScopeToolSyncServiceTest：
- 解析：
;分隔、空白忽略、缺=忽略 - 幂等：已存在的绑定不重复插入
- 容错：作用域不存在时跳过且不抛异常
运维
开通新工具只需改配置并重新部署；启动日志会打印
scope-tool binding 新增 scope=... tool=...，可直接核对。