Higress mcp-router 插件解析基于工具名命名空间的 MCP 工具调用路由实践【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higressmcp-router是 Higress 提供的一个 AI 类 Wasm 插件它面向 MCPModel Context Protocol协议中的tools/call请求根据工具名称中携带的服务器标识前缀将请求动态重路由到对应的后端 MCP 服务器。通过它你可以把多个互相独立的 MCP 服务器的工具聚合到一个统一的 MCP 端点上客户端只需向单个地址发起tools/call调用网关即可保证请求准确送达真正托管该工具的后端。读完本文你将掌握 mcp-router 的完整配置字段、内部工作原理、路由级开关用法以及它与 mcp-server 组合服务器composed server机制协同工作的底层实现细节。背景为什么要做 MCP 工具路由MCPModel Context Protocol定义了一种标准化的 JSON-RPC 通信方式让 LLM 应用可以调用外部工具。在实际落地中一个智能体往往需要同时使用多个来源的工具——例如高德地图服务、随机用户生成服务、天气查询服务等它们各自运行在不同的 MCP 服务器上、拥有不同的域名和路径。如果客户端需要分别对接每个 MCP 服务器集成成本会随服务器数量线性增长。mcp-router 的解决思路是对外暴露一个统一端点工具名称采用服务器标识 工具名的命名空间形式插件解析工具名称找到对应的服务器路由配置改写请求头与请求体后交给网关重新路由。这样一来聚合多个 MCP 服务器的能力被收敛到一个入口 一份路由表客户端无需感知后端服务器的真实位置。插件的能力定位在 plugins/release/console/mcp-router/spec.yaml 中被描述为Route namespaced MCP tool calls to their configured MCP server domain and path按工具名称中的服务器命名空间将 MCP 工具调用路由到配置的域名与路径插件类别为ai要求网关最低版本 2.1.3。配置字段详解mcp-router 的全局配置结构如下字段定义来自 main.go 中的ServerConfig与McpRouterGlobalConfig名称数据类型填写要求默认值描述servers对象数组是-每个后端 MCP 服务器的路由配置列表servers[].name字符串是-MCP 服务器的唯一标识符必须与tools/call请求工具名称中使用的前缀相匹配servers[].domain字符串否-后端 MCP 服务器的域名authority省略时保留原始请求的域名servers[].path字符串是-请求将被路由到的后端 MCP 服务器路径对照 spec.yaml 中的 OpenAPI v3 校验规则可以确认三点约束顶层servers为必填字段servers[].name与servers[].path均为必填servers[].domain为可选——这一点对应源码中Domain string \json:domain,omitempty的omitempty标记若未配置插件不会改写:authority 头请求将保留原始域名。此外mcp-router 还支持路由级rule配置其中只包含一个布尔字段名称数据类型填写要求默认值描述enable布尔值否true是否在该路由上启用 mcp-router 的路由能力该开关在 ParseOverrideConfig 中通过gjson.GetBytes(configBytes, enable).Bool()解析当enable为false时ProcessRequest 会直接返回types.ActionContinue请求按原样放行不做任何路由处理。工作原理与源码级拆解mcp-router 的注册方式与普通 Wasm 插件不同它走的是 Higress MCP 插件框架在 main.go 的init()中调用mcp.LoadMCPFilter注册过滤器名称mcp-router、全局/路由级配置解析器以及通过mcp.SetToolCallRequestFilter(ProcessRequest)挂载工具调用请求处理函数。框架定义在 pkg/mcp/filter/plugin.go当请求体是合法的 JSON-RPC 且方法为tools/call时框架会从params中取出name作为toolName、取出arguments作为toolArgs一并交给ProcessRequest处理见 plugin.go。ProcessRequest的完整执行流程如下对应 main.go工具名称解析插件拿到 JSON-RPC 请求params对象中的name参数。框架层已经完成了 JSON-RPC 的解析与tools/call方法判定插件直接面对工具名称字符串。前缀匹配与拆分插件按分隔符将工具名拆成两部分。需要特别说明的是README 中以server-name/tool-name的形式描述这一概念而从源码实现看实际使用的分隔符是___三个下划线——它来自常量 pkg/mcp/consts/vars.go 中的ToolSetNameSplitter拆分逻辑为strings.SplitN(toolName, consts.ToolSetNameSplitter, 2)。如果工具名中不包含该分隔符插件仅记录一条 Debug 日志并直接放行不执行任何路由动作。路由查找以拆分出的前半段为serverName在全局配置的servers列表中做精确匹配若找不到对应配置记录 Warn 日志并放行不改变请求。请求头修改若匹配到的domain非空通过proxywasm.ReplaceHttpRequestHeader(:authority, targetServer.Domain)改写:authority头无论 domain 是否配置都会执行proxywasm.ReplaceHttpRequestHeader(:path, targetServer.Path)改写:path头同时会写入x-envoy-internal-route: true头允许网关在本次请求处理链路内部重新执行路由选择。请求体修改使用sjson.SetBytes(rawBody, params.name, actualToolName)在 JSON 层面对请求体做定点改写把params.name更新为去掉服务器前缀后的纯工具名然后通过proxywasm.ReplaceHttpRequestBody替换整个请求体。重新路由请求头与请求体改写完成后网关的路由引擎以新的目标信息再次处理请求将其发送到正确的后端 MCP 服务器。值得强调的是___分隔符并非随意约定而是与 mcp-server 的组合服务器composed server机制配套设计的在 pkg/mcp/server/composed_server.go 中组合服务器生成的工具名格式为fmt.Sprintf(%s%s%s, originalServerName, consts.ToolSetNameSplitter, originalToolName)即服务器名___工具名。也就是说mcp-server 负责把多个原始服务器的工具以___命名空间形式暴露出来mcp-router 负责把带命名空间的tools/call请求按同一分隔符拆回并路由到真实后端两者共享同一个常量构成了聚合暴露 按名路由的完整闭环。配置示例在higress-plugins.yamlHigress 插件配置文件中配置 mcp-router 的全局路由表示例来自 README.mdservers: - name: random-user-server domain: mcp.example.com path: /mcp-servers/mcp-random-user-server - name: rest-amap-server domain: mcp.example.com path: /mcp-servers/mcp-rest-amap-server其中name必须与客户端发送的工具名称前缀严格一致含大小写path一般对应后端 MCP 服务器在该域名下的 HTTP 路径。若需要对某个具体路由域名/路径单独控制是否启用路由能力可在该路由的插件配置中增加路由级配置enable: true完整使用示例假设客户端向启用了 mcp-router 的统一端点发送如下tools/call请求来自 README.md 的使用示例原始请求{ jsonrpc: 2.0, id: 2, method: tools/call, params: { name: rest-amap-server/get-weather, arguments: { location: New York } } }插件执行的动作识别工具名称为rest-amap-server/get-weather实际实现中对应rest-amap-server___get-weather形式的命名空间提取服务器标识rest-amap-server与工具名get-weather命中路由配置domain: mcp.example.com、path: /mcp-servers/mcp-rest-amap-server修改请求头:authority→mcp.example.com:path→/mcp-servers/mcp-rest-amap-server修改请求体为{ jsonrpc: 2.0, id: 2, method: tools/call, params: { name: get-weather, arguments: { location: New York } } }请求随后被重新路由到rest-amap-server对应的后端 MCP 服务器。注意arguments等其余字段在 JSON 改写过程中被原样保留仅params.name发生变化。边界行为与注意事项从源码逻辑可以归纳出以下边界行为便于你在实际接入时预判结果无命名空间前缀工具名不含分隔符时插件直接放行请求不路由、不修改前缀未命中路由表serverName在servers列表中找不到时插件放行请求并输出 Warn 日志No routing configuration found for server未配置 domain:authority头保持原始值仅改写:path头路由级enable: false整个处理函数直接返回相当于插件在该路由上被旁路请求体改写失败若sjson.SetBytes或ReplaceHttpRequestBody失败插件记录 Error 日志并按放行处理保证异常情况下不阻断原有请求链路。整体设计遵循匹配不到就不动的保守策略路由改写失败或配置缺失时请求都会以原始形态继续流转不会因路由插件引入新的故障。相关资源如需进一步深入可在仓库中继续阅读以下文件插件完整实现plugins/wasm-go/extensions/mcp-router/main.go中文版插件文档plugins/wasm-go/extensions/mcp-router/README_ZH.md分隔符常量定义plugins/wasm-go/pkg/mcp/consts/vars.go组合服务器composed server工具命名实现plugins/wasm-go/pkg/mcp/server/composed_server.goMCP 过滤器框架tools/call请求分发逻辑plugins/wasm-go/pkg/mcp/filter/plugin.go插件市场元数据与配置校验 Schemaplugins/release/console/mcp-router/spec.yamlMCP 相关 mcp-server 插件负责工具的注册与聚合暴露plugins/wasm-go/extensions/mcp-server【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考