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 新增记录，可直接核对。
46 lines
1.6 KiB
Markdown
46 lines
1.6 KiB
Markdown
# 作用域-工具绑定启动同步（ScopeToolSyncService）
|
||
|
||
## 背景
|
||
|
||
新 MCP 工具部署后，必须绑到调用方使用的 `scope_tool` 记录，否则调用会返回
|
||
`PERMISSION_DENIED：该 token 的作用域不包含工具 [...]`。
|
||
|
||
此前这一步是**管理员手工执行 SQL**，问题：
|
||
1. 容易遗漏（2026-10-21：新增的 `hardware.statistics.query` 与用纸类工具部署后一直不可用）；
|
||
2. 无法随代码评审，变更不可追溯；
|
||
3. 每个环境（test/operation/xiaoqu-ai/sync）都要重复操作。
|
||
|
||
## 方案
|
||
|
||
启动时读取配置 `mcp.scope-tool-bindings`，幂等写入 `scope_tool`：
|
||
|
||
```yaml
|
||
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`：
|
||
1. 解析：`;` 分隔、空白忽略、缺 `=` 忽略
|
||
2. 幂等：已存在的绑定不重复插入
|
||
3. 容错：作用域不存在时跳过且不抛异常
|
||
|
||
## 运维
|
||
|
||
开通新工具只需改配置并重新部署；启动日志会打印
|
||
`scope-tool binding 新增 scope=... tool=...`，可直接核对。
|