6.7 KiB
MCP 工具目录与按需调用
Agent 的 MCP 主路径使用 discover_mcp_tools 和 call_mcp_tool,不再把每个 MCP 工具的完整 schema 放进初始模型请求。现有 Agent / 请求级服务选择范围保持有效。
使用顺序
{"mode":"list_servers","limit":20}
从结果获取 server_id,再读取该服务的工具目录:
{"mode":"list_tools","server_id":"目录中的服务ID","limit":20}
按返回的原始名称读取完整定义:
{"mode":"describe","server_id":"目录中的服务ID","tool_name":"get_order"}
模型使用 call_mcp_tool 调用:
{"tool_ref":"describe 返回的引用","arguments":{"order_id":"123"}}
search 是限定单个服务的名称 / 描述子串匹配,可忽略大小写;不是 BM25 或跨语言语义检索。空结果时使用 list_tools 完整枚举,再精确 describe,工具可达性不依赖搜索排名。
目录、连接和权限
- 启动只读取配置中的获准服务并安装两个入口,不连接所有服务。工具描述中包含最多约 2,000 字符的服务摘要,其余服务通过分页目录读取。
- 工具元数据在每个 Agent engine 内按服务缓存;不同请求的目录不共享。目录绑定租户、调用主体及有效 OAuth 主体。
list_tools/describe/search首次访问指定服务时才连接、列工具,继续复用既有 MCPManager 连接和 OAuth 流程。- 成功目录在本次 engine 中复用;
list_tools支持refresh:true,刷新时不能带 cursor。刷新失败不回退到旧目录。 - 目标读取与调用会重新获取服务配置并检查单工具策略。服务禁用、不可访问、配置版本变化都会被处理;新加入 Agent 范围外的服务不会自动扩权。
- 列目录通过现有策略服务批量读取权限,工具数量增加不会增加数据库查询次数;精确描述与调用解析只检查目标工具。工具定义缓存不缓存权限决策,自定义旧版 gate 可继续使用逐工具检查接口。
- 运行中状态包括
not_loaded、loading、ready、needs_auth、error、disabled、unavailable。服务列表展示缓存的最近观察状态,目标访问负责重新验证。 - 当前不增加持久元数据缓存、跨请求缓存、后台自动刷新或 MCP 通知订阅。后续扩展须保留相同权限边界。
分页与定义完整性
列表默认 20 项,最大 50 项。输出预算较小时自动缩小单页,返回完整 JSON 和 next_cursor;一直跟随 cursor,直到 has_more=false。工具游标绑定查询和可见记录,权限或目录变化导致游标失效时,需从第一页重新枚举。服务列表游标绑定有序服务 ID,正常加载导致的状态变化不会使游标失效。
MCP 客户端通过现有认证 transport 读取原始 inputSchema,保留顶层组合约束、definitions 和引用路径;不经过 SDK 的固定 schema 结构转换。客户端读取全部服务端分页,并在重复游标、分页失败或取消时拒绝发布不完整目录。
服务端 URL 由租户配置,属于不可信端点:协议分页上限为 100 页、2,000 个工具,单个 inputSchema 上限 256 Ki 字节。恶意或自循环服务无法用互不重复的游标在超时前无限增长目录;超限直接报错,不发布部分目录。
工具引用由服务 ID、原始工具名及 schema 生成,不使用有损的函数名清洗结果,避免中文名称、大小写或截断造成的调用冲突。刷新后 schema 变化会使旧引用失效。新的 engine 中如引用尚未载入,需先重新发现。
describe 返回完整 schema,单条完整结果硬上限为 256 Ki 字符;超限明确报错,不返回半截 JSON。Agent 上下文预算不足时,目录结果整体替换为说明,不能把截断后的参数定义用于调用。列表摘要与精确描述有不同的预算,避免将每个工具的长说明提前加入上下文。
执行与历史
代理解析到当前目录的 MCPTool,并复用 registry 的目标参数转换、校验、输出处理和 MCPTool 的权限、审批、OAuth、SSRF 安全客户端及结果链。MCP 图片和内容项保持原有处理;代理不能转调用内置工具或代理自身。
MCP 参数使用完整 JSON Schema 校验,覆盖嵌套对象、数组、组合约束、额外属性以及本地引用。按 schema 声明选择方言,未声明时使用 2020-12;schema 编译结果按工具快照缓存。验证器不读取外部 URL 或文件,无法解析的外部引用明确报错。审批修改后的参数也会重新校验,并整体替换原参数。内置工具继续使用原有校验规则。
ToolCall.Name / Args / ID / ProviderMetadata 保留模型原始调用,用于当前轮及跨轮回放。新增 ToolCall.Target 保存实际服务、工具名和内层参数,供界面和日志展示。实时事件使用目标名称,历史恢复也读取 target;不通过改写模型调用来实现展示。
MCP schema 和外部返回值保持外部身份语义,不参与 WeKnora 知识库 ID 的改写。用户显式 @MCP 时,提示语指向目录读取,不再依赖初始请求中的原生 MCP 函数名前缀。
间接提示注入
目录先于任何工具结果到达模型,工具名、说明和 schema 都由远端服务撰写。原先由每个 MCP 工具的 [MCP Service: X (external)] 描述前缀承担的信任边界,现由 list_tools / search / describe 结果中的 notice 字段承担,声明其为数据而非指令。标记随数据走而不是放在工具定义里:历史压缩会让工具定义远离它所限定的文本。list_servers 返回的是本地配置的服务名,不带标记。定义内容按原文返回,不做删改,只声明信任级别;call_mcp_tool 的执行结果保留原有的 untrusted 前缀。标记按页而非按条,避免为每条摘要付出前缀开销。
验证
覆盖目录全量分页、精确读取、搜索漏召回后的枚举、权限及游标变化、跨身份拒绝、名称冲突、schema 变更后旧引用、刷新失败、取消和并发读取。另有注入型工具说明的信任标记,以及协议分页/工具数/schema 体积上限的测试。HTTP MCP 集成测试覆盖原始 schema 保留、服务端分页、目标参数校验/转换、审批修改及拒绝、图片结果、实际目标事件与原始调用回放。另有 1,000 个工具下的权限查询次数回归测试,以及外部 schema 资源不被读取的测试。
原生 Claude / Responses 延迟工具协议、Code Mode 和常用 MCP 工具直出不属于当前默认路径;目录与模型可见定义的接口已经分开,后续可以增加独立适配。本次不引入向量搜索或额外部署组件。