# 工作区MCP工具导入合同

## 选择工具

候选由当前工作区已发布且启用的API服务、请求附加描述符和产品API描述符合并，按此顺序保留同名的第一项。已发布服务要求ready、dynamic_service、启用、名称无歧义且有已发布版本标识。目录不等于当前工具实例列表。

tool_names省略、null或[]选择所有候选；有非空数组时按去空白后的名称精确选择，重复候选去重，未知名称被忽略。仅含空白名称的非空数组可选中零项。先预演，再明确选择api_service等可导入项；product_api正式导入会在创建前拒绝整份选择。

## 附加描述符

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `tools[].name` | string | 候选名称；常规任务使用服务端预演名称。 |
| `tools[].description` | string | 可选说明。 |
| `tools[].inputSchema` | object | JSON Schema，键名为camelCase；不要在默认值中放凭据。 |
| `tools[]._meta` | object | 可选描述信息；客户端传入的ui块被移除。 |
| `tools[]._meta.origin` | string | 来源标识；不能靠手填来源绕过实际执行权限。 |

node_id、version和workflow_id是内部描述符字段，当前不从JSON请求体解码。客户端自带ui无法指定页面；有效页面URI来自服务端发布服务。未提供tools时仍可使用服务端发现。该入口不是任意外部MCP URL的探测或批量创建接口。

## 预演、复用与恢复

dry_run=true不创建工具、不刷新已有页面元数据，也不更新智能体绑定；它仍执行发现、已有工具读取和相应授权。预演可包含已有工具ID，新候选可没有tool_id。默认dry_run=false，空body或null不是预演承诺；未知body键也不是严格拒绝合同。

正式导入按候选逐项创建或复用同名工具。同名不证明schema、来源或状态完全相同。匹配已导入API服务身份时，重导入可刷新或移除发布者管理的mcp_app描述，保留用户其他设置；无关同名工具不会仅因重导入被覆盖。

API服务工具按服务名指向调用时当前发布的服务，不固定节点ID或版本。工具级入口不绑定智能体；智能体级入口在导入后追加非空tool_id的绑定。响应不是绑定详情，绑定失败也没有统一的saved_tool_ids回执。保留预演选择，在失败或超时后回读当前工具和目标绑定，核对实际写入后再决定重试。

Product API拒绝发生在逐项写入前，但不能推广为所有失败都整体回滚。多个工具逐项写入和后续绑定没有统一外层事务；后项失败、并发重名和绑定失败均需回查。
