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=...`，可直接核对。
|