服务注册与分布式协调 / 系统课时
按目录搜索并选择服务
按目录搜索并选择服务
这一节把 Router 的服务发现过程变成可解释的选择链:先用任务描述和关键词查询候选,再比较名称与描述,最后通过初始化结果确认目标服务当前可用,而不是让 Agent 只凭模糊相似度直接调用。
学习目标
- 使用
search_mcp_server查询与任务匹配的 MCP Server 候选 - 根据名称、描述和可连接性建立稳定的筛选顺序
- 用
add_mcp_server验证最终候选并取得可调用工具列表
把搜索条件写成任务语义
search_mcp_server 接收 task_description 与 key_words。前者应描述“要完成什么”,后者提供少量稳定能力词,而不是把整段用户输入重复两遍。Router 返回候选服务及完成任务所需的使用信息;候选名称和描述来自目录元数据,因此注册时写得越准确,运行时越容易选对。([GitHub][2])
下面先搜索“内部文档检索”能力,再把最终选中的服务名交给 add_mcp_server。<SERVER_NAME> 必须替换为第一次请求实际返回的候选名称。
export ROUTER_URL='http://127.0.0.1:8000/mcp'
export SERVER_NAME='<SERVER_NAME>'
curl -sS "$ROUTER_URL" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_mcp_server","arguments":{"task_description":"检索公司内部产品文档并返回相关段落","key_words":"文档,检索,知识库"}}}'
curl -sS "$ROUTER_URL" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"add_mcp_server\",\"arguments\":{\"mcp_server_name\":\"${SERVER_NAME}\"}}}"预期结果
第一个请求返回与“文档、检索、知识库”相关的 MCP Server 候选。
第二个请求在目标 Server 可初始化时返回该 Server 的工具列表和使用说明。
具体服务名、候选数量、排序及工具名由当前 Registry 内容决定。读取候选元数据
不要把“排在第一位”直接等价为“应该调用”。先把候选拆成三个判断层次:
| 信号 | 用途 | 判断方式 |
|---|---|---|
| 名称 | 确认服务身份与业务归属 | 排除明显属于其他系统或环境的同名近似项 |
| 描述 | 判断能力是否覆盖任务 | 优先选择明确写出目标动作、对象和边界的服务 |
| 可用性 | 判断当前能否真正建立调用链 | 对最终候选执行 add_mcp_server,确认能取得工具列表 |
如果返回结果还包含 provider、相关度或其他元数据,可以用于排序,但它们只能说明“更像目标”,不能替代连接验证。尤其在目录内容频繁变化时,旧描述、错误配置或暂时不可达的实例都可能让“搜索命中”与“实际可调用”产生差异。
建立可解释的选择顺序
选择过程建议保持固定次序:先做硬过滤,再做语义比较,最后验证连接。这样 Agent 的决策可以复盘,也能避免每次因候选排序轻微变化而选择不同服务。
- 用名称或业务域排除明显不相关的候选。
- 比较描述,确认服务声明的能力与当前任务一致。
- 若仍有多个候选,优先保留边界更明确、元数据更完整的服务。
- 对最终候选调用
add_mcp_server;只有成功取得工具列表,才把它视为当前可用。 - 后续真正执行任务时,再使用 Router 的
use_tool调用该 Server 的具体工具。

处理搜索命中但不可用
如果 search_mcp_server 能找到目标,而 add_mcp_server 失败,不要立刻修改关键词。搜索成功只证明目录里存在匹配元数据;初始化失败通常应转向检查该 MCP Server 的连接配置、协议、凭据和实际运行状态,以及 Router 到目标服务的网络可达性。
反过来,如果 add_mcp_server 对某个候选一直稳定成功,但搜索经常找不到它,应优先修正文档目录中的名称与描述,让元数据真实表达服务能力。这样后续自动工具发现依赖的是可维护的目录语义,而不是 Agent 对某个固定服务名的偶然记忆。