Higress Tool Search MCP Server 实战基于 Milvus 的 AI 工具语义搜索服务配置与实现解析【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress本篇技术指南围绕 Higress 内置的 Tool Search MCP Server源码位于 plugins/golang-filter/mcp-server/servers/tool-search展开系统讲解如何利用 OpenAI 兼容 Embedding API Milvus 向量数据库在 Higress 网关侧为 AI Agent 提供工具语义搜索能力。读完本文你将掌握该 MCP Server 的数据库 Schema 设计、完整配置参数、Higress ConfigMap 接入方式、x_higress_tool_search工具调用约定以及从向量检索到工具元数据拼接的底层实现原理。一、服务定位与功能特性Tool Search MCP Server 是基于 Higress Golang Filter 实现的 MCP Server核心价值在于当 AI Agent 需要调用大量 MCP 工具时无法将全部工具描述塞进上下文因此需要一个“工具路由器”来根据用户意图做语义检索只把最相关的 TopK 个工具定义返回给 Agent 使用。需要特别强调的是当前实现仅支持向量语义搜索基于 Milvus 向量数据库不包含全文检索或混合搜索。其功能特性如下向量语义搜索使用 OpenAI 兼容的 Embedding API 将用户查询转换为向量并在 Milvus 中做相似度检索工具元数据支持从数据库中读取完整的工具定义JSON 格式并动态拼接工具名称全量工具列表支持获取数据库中所有可用工具可配置 Embedding 模型支持自定义模型、向量维度及 API 端点默认对接 DashScopeMilvus 集成通过标准 gRPC 接口连接 Milvus 向量数据库。从源码看该 Server 通过init()中的注册机制挂载到 Higress MCP 框架func init() { common.GlobalRegistry.RegisterServer(tool-search, ToolSearchConfig{}) }注册名tool-search即对应配置中servers[].type字段的取值见 server.go。二、数据库要求Milvus 集合 Schema本服务依赖 Milvus 向量数据库需预先创建集合Collection。参考 milvus.go 中实际查询的输出字段集合 Schema 应包含以下字段字段名类型说明idVarChar(64)文档唯一 IDcontentVarChar工具描述文本注意README 表格中的长度 64 应为笔误源码未对长度做强约束metadataJSON完整的工具定义必须包含name字段vectorFloatVector(1024)embedding 向量created_atInt64创建时间毫秒时间戳说明原文档表格中最后一行将created_at误写为重复的metadata。依据源码ListAllDocs中的outputFields : []string{id, content, metadata, created_at}可确认第 5 个字段应为created_atInt64 类型且代码在解析时以time.UnixMilli(createdAt)还原时间见 milvus.go。metadata字段是整个方案的关键它存放完整的工具定义如 name、description、inputSchema、outputSchema 等搜索结果会直接以该 JSON 作为返回给 Agent 的工具描述。若某条记录缺失 metadata代码会退化为仅用namecontent构造基础定义见 search.go。三、配置参数详解Tool Search MCP Server 的配置分三层根级配置、Vector 配置与 Embedding 配置。以下参数说明均已结合 server.go 的解析逻辑核对。3.1 根级配置参数类型必填默认值说明vectorobject是-向量数据库配置见 3.2embeddingobject是-Embedding API 配置见 3.3descriptionstring否Tool search server for semantic similarity searchMCP Server 描述信息会作为 MCP 指令instructions下发给客户端ParseConfig中若缺少vector或embedding对象会分别返回missing vector configuration/missing embedding configuration错误并导致该 Server 加载失败见 server.go。3.2 Vector 配置vector对象参数类型必填默认值说明typestring是-必须为milvus其他值报unsupported vector.type错误hoststring是-Milvus 服务地址如localhostportint是-Milvus gRPC 端口如19530databasestring否defaultMilvus 数据库名tableNamestring否apig_mcp_toolsMilvus 集合名usernamestring否-认证用户名可选passwordstring否-认证密码可选值得注意的源码细节tableName的默认值常量defaultTableName apig_mcp_tools定义在 server.go源码中VectorConfig结构体还保留了vectorWeight字段config-example.json 中示例值为0.5但当前纯向量搜索实现并未使用该字段它属于从 RAG 混合搜索迁移时遗留的字段配置时可忽略连接 Milvus 时仅当username与password同时非空才会启用认证见 milvus.go。3.3 Embedding 配置embedding对象参数类型必填默认值说明apiKeystring是-Embedding 服务的 API KeybaseURLstring否https://dashscope.aliyuncs.com/compatible-mode/v1OpenAI 兼容 API 的 Base URLmodelstring否text-embedding-v4使用的 Embedding 模型dimensionsint否1024向量维度需与 Milvus 集合中vector字段维度一致apiKey是唯一必填项缺失时报missing embedding.apiKey。三个默认值常量defaultBaseURL、defaultModel、defaultDimensions同样定义在 server.go。由于使用 OpenAI 兼容协议baseURL可替换为任意兼容服务如本地 vLLM、其他云厂商 OpenAI 兼容端点model与dimensions需与所选模型能力匹配。四、Higress 配置接入完整示例Tool Search MCP Server 作为 Higress 的一个模块通过 Higress ConfigMap 的mcpServer配置段接入。以下为完整的可运行示例apiVersion: v1 kind: ConfigMap metadata: name: higress-config namespace: higress-system data: higress: | mcpServer: enable: true sse_path_suffix: /sse redis: address: Redis IP:6379 username: password: db: 0 match_list: - path_rewrite_prefix: upstream_type: enable_path_rewrite: false match_rule_domain: * match_rule_path: /mcp-servers/tool-search match_rule_type: prefix servers: - path: /mcp-servers/tool-search name: tool-search type: tool-search config: vector: type: milvus host: localhost port: 19530 database: default tableName: apig_mcp_tools username: root password: Milvus maxTools: 1000 embedding: apiKey: your-dashscope-api-key baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1 model: text-embedding-v4 dimensions: 1024 description: Higress 工具语义搜索服务配置要点解读结合 config.go 的解析流程mcpServer.enable: true开启 MCP Server 过滤器总开关match_list将/mcp-servers/tool-search前缀的请求路由到 MCP 处理链路servers[].type必须为tool-search过滤器会通过common.GlobalRegistry.NewServerConfig(serverType)查找已注册的 Server 类型见 config.goservers[].pathMCP 消息端点路径SSE 端点会自动拼接sse_path_suffix为/mcp-servers/tool-search/sse见 config.goconfig即上文 3.1–3.3 的配置对象解析失败时该 Server 会被跳过并在日志中记录failed to parse config警告maxTools示例中保留了该字段但当前源码注释明确“移除 maxTools 的解析逻辑”实际在 server.go 中写死为常量fixedMaxTools 1000即全量工具列表最多返回 1000 条。另附独立的 JSON 配置模板 config-example.json 可供参考。五、MCP 工具接口x_higress_tool_searchTool Search MCP Server 对外提供唯一一个 MCP 工具x_higress_tool_search工具注册见 server.go用于基于语义相似度搜索最相关的工具。5.1 输入参数参数名类型必填说明querystring是查询语句用于与工具描述进行语义相似度比较topKint否指定需要选择的工具数量默认选择前 10 个工具参数校验逻辑见 tools.goquery必须为非空字符串为空直接返回query cannot be empty错误topK支持 float64/int/int64 三种类型当topK 0或topK 100时回退为默认值10。对应的 JSON Schema 中topK的约束为minimum: 1, maximum: 100见 tools.go。5.2 输出格式工具调用成功后会以 JSON 文本形式返回{ tools: [ { name: server_name___tool_name, title: Tool Title, description: Tool description, inputSchema: {...}, outputSchema: {...} } ] }其中每个 tool 元素即为 Milvus 中metadata字段存储的完整工具定义 JSON工具名称取自metadata.name若缺失则退化为仅含name与description的基础结构见 search.go。5.3 调用链路一次完整检索的调用链路为MCP 客户端调用x_higress_tool_searchHandleToolSearch解析并校验query/topK注入 30 秒超时上下文见 tools.goSearchService.SearchTools先生成查询向量再执行向量检索见 search.go结果转换为{tools: [...]}JSON 后封装为mcp.CallToolResult返回。六、搜索实现与索引配置6.1 向量检索实现搜索通过 Milvus 向量相似度实现核心调用位于MilvusVectorStoreProvider.SearchDocs见 milvus.go关键点如下索引算法使用HNSW索引算法进行向量索引默认建索引参数M8, efConstruction64README 说明搜索参数源码中使用entity.NewIndexHNSWSearchParam(16)构造搜索参数ef16相似度度量方式内积IP, Inner Product通过entity.IP指定检索字段anns_field为vector输出字段为id、content、metadataTopK 控制options.TopK直接作为 Milvus Search 的 limit 传入。6.2 Embedding 生成Embedding 客户端基于openai-gov2 SDK 实现见 embedding.go客户端创建时设置 API Key、Base URL 与30 秒请求超时请求参数携带model、input、dimensions并显式指定EncodingFormat为 float 格式响应中的[]float64会被转换为 Milvus 所需的[]float32向量。6.3 全量工具列表除语义搜索外服务还提供GetAllTools能力通过 MilvusQuery接口空过滤表达式拉取集合内全部文档并按maxTools当前写死为 1000限制返回数量输出字段为id、content、metadata、created_at见 milvus.go。七、源码结构速览与本地验证Tool Search MCP Server 源码组织清晰便于二次开发与排障文件职责server.goServer 注册、配置解析、Server/工具装配embedding.goOpenAI 兼容 Embedding 客户端milvus.goMilvus 连接、向量检索、全量查询search.go搜索编排、结果到工具定义的转换tools.goMCP 工具 handler 与 JSON Schemaconfig-example.json独立 JSON 配置模板server_test.go本地功能测试server_test.go 提供了完整的本地验证思路可通过环境变量TEST_MILVUS_HOST、TEST_MILVUS_PORT、TEST_API_KEY等覆盖默认连接参数默认localhost:19530、DashScope、apig_mcp_tools集合依次验证配置解析、GetAllTools全量拉取以及对weather data、database query、file operations、HTTP requests、library documents等典型查询的语义检索结果与耗时。这为在没有完整 Higress 环境的情况下联调 Milvus Embedding 链路提供了便捷途径。八、适用前提与注意事项能力边界当前仅支持向量语义搜索无全文检索/混合检索工具召回质量完全依赖 Milvus 中工具描述的 embedding 质量与向量维度一致性环境依赖需预先部署 MilvusgRPC 19530 端口可达并创建符合上述 Schema 的集合、写入工具数据需可访问 OpenAI 兼容 Embedding 服务默认 DashScope需有效 API Key参数一致性embedding.dimensions必须与 Milvus 集合vector字段维度默认 1024一致否则检索会失败返回上限单次搜索topK有效范围 1–100全量列表上限写死为 1000 条fixedMaxTools常量源码注释标明仅用于单测但实际NewServer装配时同样使用该值命名约定工具名取自metadata.nameREADME 输出示例中的server_name___tool_name格式体现了多 MCP Server 场景下工具名的语义化约定实际返回以metadata中的name为准。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考