Higress MCP Server 实战oil-price-query 今日油价查询服务的 REST-to-MCP 配置全解【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress本文以 Higress 仓库中 oil-price-query MCP Server 文档 为主体完整讲解该服务如何将阿里云云市场的今日油价 API 转换为 AI 可调用的 MCP 工具包括工具的用途与参数、HTTP 请求/响应结构、mcp-server.yaml 的逐字段配置以及 rest_server.go 中 REST-to-MCP 模板引擎的底层实现。读完本文你可以掌握 Higress 零代码把 REST API 变成 MCP 工具 的完整方法并能照此模式接入任意云市场 API。一、服务定位oil-price-query 是什么oil-price-query是 Higress 提供的 MCP Server 配置之一主要负责处理中国各地油价相关的查询请求它通过阿里云云市场 API 获取最新的油价数据并以结构化方式返回给调用者。该服务特别适用于需要实时监控或分析不同地区燃油价格变化趋势的应用场景例如汽车加油应用、物流成本估算系统等见 README.md 与 README_ZH.md。它的特点是纯配置实现整个目录下没有任何 Go 源码只有四样东西——文件作用README.md / README_ZH.md功能与工具说明文档mcp-server.yamlREST-to-MCP 插件配置核心api.json上游 API 的 OpenAPI 3.0.1 描述文件这正是 Higress 内置REST-to-MCP能力的典型用法不写一行代码仅靠 YAML 配置就能把任意 REST API 转换为 MCP 工具机制说明见 MCP Server 实现指南。二、前置准备云市场 API 的订阅与 AppCode 获取根据 README_ZH.md 中的云市场 API MCP 服务章节接入流程为订阅 API进入阿里云 API 市场中该油价 API 的详情页API 编号cmapi00062739先使用免费试用订阅该 API获取 AppCode前往云市场用户控制台使用阿里云账号登录后查看已订阅 API 服务的 AppCode并将其配置到 Higress MCP Server 的配置中。对同一账号订阅的所有云市场 API 服务AppCode 是同一个只需使用这一个 AppCode 即可访问所有已订阅的 API 服务关注额度云市场用户控制台会实时展示已订阅的预付费 API 服务的可用额度免费试用额度用完后需重新订阅。API 认证方式采用云市场统一的APPCODE头认证并且每次请求需要携带一个随机X-Ca-NonceUUID作为防重放标识——这一点在所有云市场系 MCP Server 中一致仓库中 mcp-scripts/yunmarket-tmpl.yaml 给出了通用模板server: config: appCode: tools: requestTemplate: headers: - key: Authorization value: APPCODE {{.config.appCode}} - key: X-Ca-Nonce value: {{uuidv4}}三、工具详解today-oil-price今日油价3.1 功能与使用场景用途查询指定省份当前日期下的各类汽油及柴油价格使用场景个人用户想了解所在区域或其他关心地区的最新油价企业做成本控制和预算规划时参考最新燃料费用标准参数说明prov需要查询的省份名称如北京、广西。该参数必须放在URL 查询字符串中传递在 mcp-server.yaml 中对应position: query。3.2 请求示例原文档给出的上游 API 请求形态如下替换为你的 AppCode 后即为真实请求GET https://smjryjcx.market.alicloudapi.com/oil/price?prov北京 Authorization: APPCODE your_app_code_here X-Ca-Nonce: random_uuid_value其中两个占位符的处理要求很关键your_app_code_here替换为从阿里云云市场获得的有效 AppCoderandom_uuid_value每次请求都要生成一个新的随机 UUID作为X-Ca-Nonce头的值。在 REST-to-MCP 配置中这一每次请求自动刷新的语义由{{uuidv4}}模板函数承担见下文配置。api.json 中对该接口的 OpenAPI 描述与之一致路径为GET /oil/price查询参数prov省份如北京、广西Base URL 为https://smjryjcx.market.alicloudapi.com接口版本 1.0.0。3.3 响应结构API 返回 JSON完整结构如下与文档及 api.json 的 schema 一致字段类型说明codeinteger状态码successboolean是否成功msgstring响应消息成功时为成功dataobject数据对象data.list[]array油价列表data.list[].ctstring更新时间如2022-10-21 09:00:00.238data.list[].provstring省份data.list[].p0string0号柴油价格如7.85data.list[].p89string89号汽油价格如7.56data.list[].p90string90号汽油价格data.list[].p92string92号汽油价格如8.16data.list[].p93string93号汽油价格data.list[].p95string95号汽油价格如8.68data.list[].p97string97号汽油价格data.list[].p98string98号汽油价格如9.50data.orderNostring订单号如yb7pxbiup6nkg1iw2zdata.ret_codeinteger返回状态码0 表示成功其他表示失败注意两点细节各油品价格字段中某些地区可能无对应油品如 93 号已退市此时对应字段可能为空字符串判断业务成败应以data.ret_code 0为准而非仅看 HTTP 状态码。四、核心配置逐行解读mcp-server.yaml完整配置见 mcp-server.yaml其请求/响应模板部分为server: name: oil-price-query config: appCode: # 部署时填入云市场 AppCode tools: - name: today-oil-price description: 今日油价 args: - name: prov description: 省份如北京广西 type: string position: query # 拼入 URL 查询字符串 requestTemplate: url: https://smjryjcx.market.alicloudapi.com/oil/price method: GET headers: - key: Authorization value: APPCODE {{.config.appCode}} # 从 server.config 取 AppCode - key: X-Ca-Nonce value: {{uuidv4}} # 每次请求自动生成新 UUID responseTemplate: prependBody: | # API Response Information ... ## Response Structure ...各字段的中英文说明... ## Original Response各部分职责server.nameMCP Server 标识。按 MCP 实现指南 的说明该名称用于识别请求应路由到哪个 MCP Server在 All-in-One 插件中尤其重要多个 MCP Server 共享一个插件实例靠name区分server.config.appCode全局配置项供模板通过.config.appCode引用。这里留空部署时替换为真实 AppCode——这也是把密钥与工具定义解耦的做法tools[].args声明工具入参。prov的position: query决定了它会被拼到请求 URL 的查询字符串上与文档此参数必须在 URL 查询字符串中指定的要求对应requestTemplate定义如何构造对上游 API 的 HTTP 请求。{{.config.appCode}}是 GJSON Template 的配置引用语法{{uuidv4}}是模板函数保证每个请求的X-Ca-Nonce唯一满足上游的防重放校验responseTemplate.prependBody在原始 JSON 响应之前拼上一段 Markdown 文本内容包含响应结构字段逐一说明 原始响应两部分。这是为 LLM 优化的关键设计把 schema 说明注入结果帮助模型正确理解p92、p0这类简写字段如 0 号柴油的语义。五、源码纵深REST-to-MCP 在 rest_server.go 中如何实现上述配置由 Higress WASM Go SDK 的 REST-to-MCP 引擎解释执行实现位于 plugins/wasm-go/pkg/mcp/server/rest_server.go。从源码可以确认几个关键行为模板字段定义RestToolResponseTemplate结构体中声明了PrependBodyText to insert before the response body即插入响应体之前的文本以及Body、AppendBody等字段rest_server.go 第 76~79 行附近互斥校验在工具配置校验逻辑中若设置了responseTemplate.body则PrependBody与AppendBody不允许同时使用否则返回错误PrependBody and AppendBody cannot be used when Body is specifiedrest_server.go 第 207~210 行。oil-price-query 恰好采用了prependBody而未设置body因此原始 JSON 会原样保留在结果中拼接逻辑执行阶段当配置了PrependBody或AppendBody时最终返回给 AI 的内容为PrependBody 原始响应 AppendBody的直接拼接rest_server.go 第 912~913 行。也就是说 LLM 收到的是一段 Markdown 说明 完整原始 JSON模型既知道字段含义又保有全量数据模板引擎能力REST-to-MCP 使用 GJSON TemplateGo 模板语法 GJSON 路径语法内置全部 Sprig 函数70 个其中就包含本文用到的uuidv4UUID 生成函数完整的模板语法说明见 MCP Server 实现指南的 REST-to-MCP 章节。六、部署与调用方式该 MCP Server 属于 Higress 的 REST-to-MCP 配置型服务无需单独编译 WASM 插件对比需要 Go 代码实现的 amap-tools 等 MCP Server接入步骤为将 mcp-server.yaml 作为 MCP Server 插件如 All-in-One MCP 插件的配置下发到 Higress并把server.config.appCode填为你在云市场获取的 AppCodeMCP Client如 MCP Inspector、IDE 内置 MCP 客户端或支持 MCP 的 Agent连接 Higress 网关暴露的 MCP 端点后可通过tools/list看到名为today-oil-price的工具及其入参 schemaprovstring以自然语言发起查一下北京的今日油价这类请求网关会将模型生成的{prov: 北京}参数渲染为对上游 API 的 GET 请求并把字段说明 原始 JSON的结果返回给模型。适用前提与限制需要留意需要 Higress 版本支持 MCP Server 插件机制2.1.0 及以上见 MCP Server 实现指南 的版本说明上游 API 依赖阿里云云市场账号的有效 AppCode 与剩余调用额度额度用尽时需要重新订阅否则请求会失败prov在 OpenAPI 描述中并非强制必填required: false但实际查询特定省份时仍应显式传入。七、小结oil-price-query 是 Higress REST-to-MCP 能力的最佳最小示例一个 mcp-server.yaml 就完成了从云市场 REST API 到 MCP 工具的全部转换——requestTemplate解决认证头与防重放 UUIDresponseTemplate.prependBody解决 LLM 对简写字段的理解问题rest_server.go 中的模板引擎则在每次调用时自动完成渲染与拼接。掌握这套模式后替换 URL、参数与字段说明即可将仓库 mcp-servers 目录下天气、汇率、物流、天气等数十个云市场 API 以同样方式接入你的 AI 应用。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
