Higress REST-to-MCP 实战一份声明式 YAML 把现成 REST API 变成 3 个 MCP 工具全程零 Go 代码【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress想让大模型把你手里现成的 REST API 直接当 MCP 工具调用又不想碰一行 Go 代码在 Higress 里REST-to-MCP就是干这个的你只需要写一份 MCP Server 配置mcp-server.yaml声明好工具、参数和请求模板网关负责把工具注册成 MCP、构造 HTTP 请求、渲染响应。本文拿阿里云云市场的全国停车场数据实时查询API 当案例——整个目录里没有一行 Go 源码就靠一份 OpenAPI 规范和一份 YAML变成了 3 个可被大模型调用的工具。读完这篇你可以照同样的套路为任意 REST API 编写声明式 MCP 接入配置。一、不想写代码接 REST API 当 MCP 工具怎么办先把场景摆出来你有一个已经能跑的 REST 服务比如查停车场的接口现在想把它暴露给 AI 应用。传统做法是在 Higress 的 MCP Server 框架里写 Go 代码、编译成 WASM流程不短。但 Higress 的 MCP Server 插件其实内置了一个声明式模式REST-to-MCP。它把写一个工具这件事降级成填一张表——工具叫什么、参数放哪、请求长什么样、响应怎么包装全部用 YAML 写死REST Server 源码 里的框架代码负责剩下的事。本文的落地案例就藏在 mcp-servers 目录 下mcp-parking-lot-query 这个目录就是零代码接 REST的完整样本。二、一份 api.json 如何长出 3 个 MCP 工具先看结论这个 MCP Server 目录里只有 4 个文件没有.goapi.json——上游 API 的 OpenAPI 3.0.1 规范含字段示例值mcp-server.yaml——REST-to-MCP 声明式配置服务的核心载体README_ZH.md/README.md——从 YAML 转换/翻译出来的文档它们不是各自手写的而是一条单向流水线的产物。打开 create_api_directories.sh 就能看到这个链路openapi-to-mcp工具读取api.json套用云市场模板yunmarket-tmpl.yaml生成mcp-server.yamlyaml_to_markdown.py再把 YAML 里的工具、参数说明转成中文文档拼进README_ZH.mdtranslate_readme.py把中文版翻成README.md。换句话说规范是唯一的事实来源改了api.json重新跑一遍脚本配置和文档同步刷新。这也是你以后给自己项目做 REST API 转 MCP 时可以照抄的工程结构。三、先拿凭证AppCode 怎么来、有什么坑这个停车场 API 走的是云市场AppCode 认证——凭证本身不复杂但订阅流程里有几个点得记牢在云市场 API 详情页订阅服务优先选免费试用用阿里云账号登录云市场用户控制台查看已订阅服务的 AppCode填进 MCP Server 配置控制台会实时展示预付费服务的可用额度免费试用额度用完后可以重新订阅恢复额度。这里有个省心的约束订阅多个 API 服务拿到的是同一个 AppCode一个凭证就能访问你订阅过的全部云市场 API 服务。所以配置里只需要留一个全局占位给每个工具的请求模板引用server: name: parking-lot-query config: appCode: server.name是插件路由 MCP 请求时认的服务器身份加载配置时必须保持为parking-lot-queryappCode留空即可部署时再填真实值。四、解剖一个工具args、requestTemplate、responseTemplate 三段式3 个工具里挑最典型的经纬度查询parking-lat-lng-query完整拆开看另外两个一句话带过parking-city-query按城市名查列表必传city外加page/size分页打POST /parking/query/cityparking-detail-query只收一个参数id就是列表返回的pid打POST /parking/query/detail。经纬度查询的完整条目长这样- name: parking-lat-lng-query description: 根据经纬度查询停车场信息 args: - name: lat description: 纬度 type: string required: true position: body # lng 同为必填distance默认1000米、page默认1、size默认10为可选 requestTemplate: url: https://jumparking.market.alicloudapi.com/parking/query/nearby method: POST headers: - key: Content-Type value: application/x-www-form-urlencoded - key: Authorization value: APPCODE {{.config.appCode}} - key: X-Ca-Nonce value: {{uuidv4}} responseTemplate: prependBody: | # API Response Information ...字段结构说明末尾接 ## Original Response 原始响应三段各自管一件事args告诉 MCP 客户端这个工具收哪些参数、哪些必填。position: body表示参数不进 URL而是按 form 表单序列化进请求体——正好对上上游要求的application/x-www-form-urlencodedrequestTemplate声明式地拼出完整 HTTP 请求。urlmethod定骨架headers里塞认证和防重放头下一节细讲responseTemplate.prependBody在原始响应前面插一段字段说明书这个设计的动机第五节专门说。三个接口的基地址统一来自api.json的servers字段https://jumparking.market.alicloudapi.com。五、模板语法与 AppCode 认证这几个{{ }}是怎么被渲染的先给一句大白话YAML 里所有{{ }}都是模板占位符框架在真正发请求那一刻才把它们替换成实际值。渲染引擎是 GJSON Template 库REST Server 源码 头部 import 的github.com/higress-group/gjson_template它把 Go 模板语法和 GJSON 路径语法揉在一起还内置了 70 多个 Sprig 函数。本例实际用到三个语法点写法含义{{.config.appCode}}取server.config下的字段即你填的云市场凭证{{.args.argName}}取某个工具参数本例参数走 body 自动序列化模板里没显式引用{{uuidv4}}Sprig 的 UUID 函数每次调用生成一个随机值对应到认证细节上三个请求头各司其职Authorization: APPCODE {{.config.appCode}}——把全局凭证注入认证头完成 AppCode 认证X-Ca-Nonce: {{uuidv4}}——每次请求换一个一次性随机值做请求去重/防重放Content-Type: application/x-www-form-urlencoded——声明表单编码和position: body配套。再说序列化。args[].position的合法取值有五种query、path、header、cookie、body见 REST Server 源码 中RestToolArg.Position的注释。而参数具体怎么进请求体框架还留了argsToFormBody、argsToJsonBody、argsToUrlParam这几个开关定义在RestToolRequestTemplate结构体上上游是表单接口就选 form是 JSON 接口就选 JSON不用自己拼 body。prependBody为什么要注入字段说明书这是原文档没讲透、但值得补上的设计动机。看停车场返回的字段leftnum、canbook、bookprice、taskNo……这些命名对 LLM 来说自解释性很差靠猜很容易把剩余车位和总车位弄反。而 REST-to-MCP 场景下响应并没有强 outputSchema 约束兜底所以云市场系模板yunmarket-tmpl.yaml的做法是在原始 JSON 前面先铺一段每个字段的类型 中文语义再在## Original Response之后接原始数据。相当于把 schema 提示手写进了 prompt让大模型在没有结构约束时也能稳定解析返回值。六、响应长什么样列表、详情还有一个坐标系的坑数据形态分两种对照 api.json 的示例值一目了然列表接口周边/城市查询data.list是停车场对象数组data.total给总数详情接口data下直接就是单个停车场对象没有list包裹层。外层统一包三个字段code返回码200 表示成功、msg返回码描述、taskNo本次请求号。核心字段挑重点列一下字段类型含义示例值pidinteger停车场 ID详情查询的id就传它112namestring停车场名称交通银行大厦停车场province/city/area/addressstring省 / 市 / 区 / 详细地址浙江省 / 杭州市 / 上城区 / 庆春路175号lng/latnumber经度 / 纬度百度坐标系120.173981 / 30.263525price/priceunit/pricedescinteger / string / string价格、价格单位、收费描述10 / 元/首小时 / 首小时10元后每小时6元num/leftnuminteger总车位数 / 剩余车位数20 / 1canbook/bookpricestring是否可预订 / 预定价格2 / 空piclistarray of string停车场图片列表-⚠️ 这里有个坑lng/lat是百度坐标系api.json里字段描述写得很明确。如果你的下游业务要做导航跳转、地图标注而业务侧用的是 GCJ-02 或 WGS-84记得先做坐标转换——这是接这个数据源时的隐含约束配置里看不出来。七、上线与复制从验证到照方抓药部署三步走版本门槛MCP Server 插件要求 Higress 2.1.0 或更高版本见 MCP 服务器实现指南加载配置REST-to-MCP 是内置能力可以直接基于all-in-one插件使用——它把多个 MCP Server 打包进同一个 WASM 二进制降低网关上挂一堆插件的开销。把mcp-server.yaml的内容贴进 MCP 插件配置即可server.name保持parking-lot-queryappCode填入控制台拿到的凭证收敛暴露面不想全量开放工具时用allowTools白名单点名比如只留parking-city-query。注意它只对挂载了mcp-server插件的路由生效管不到绕过插件的其他路由。顺带区分一下两类 MCP Server 的上线方式Go 代码实现的如 amap-tools走 Makefile 里的make SERVER_NAMExxx build编译为GOOSwasip1 GOARCHwasm的 WASM还有build-image、build-push等目标而本例这种纯声明式 Server无需任何编译配置即上线。一套可复用的接入方法清单把案例抽象掉任何带 OpenAPI 规范的 REST 服务都能照下面五步接入 Higress备齐契约拿到或手写上游的 OpenAPI 规范paths、servers、参数 schema 越全越好它决定了配置和文档的自动生成质量生成或手声明用openapi-to-mcp配一套自己的模板批量产出mcp-server.yaml或者参照云市场模板手写——工具名、args的position、请求模板三要素是必须想清楚的凭证走全局配置把 AppCode、Token 之类放进server.config请求头里用{{.config.xxx}}引用敏感值不进模板正文防重放加随机头上游有 nonce 要求时{{uuidv4}}一行解决响应加说明书字段命名不直观的 API务必用responseTemplate.prependBody注入字段结构 原始响应这是 LLM 稳定解析返回值的保险上线控面all-in-one 插件加载allowTools按需收敛暴露的工具集。配置即服务、规范即文档——这就是 REST-to-MCP 声明式配置的完整闭环。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考