企业官网建设流程全解析

Higress 车辆限行查询 MCP Server 实战：基于阿里云云市场 API 的 REST-to-MCP 零代码接入指南

【免费下载链接】higress🤖 AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress

导读

本文以 Higress 仓库中的vehicle-restriction-query（车辆限行查询）MCP Server 为核心，完整讲解如何把阿里云云市场提供的「车辆尾号限行」REST API 通过 Higress 的 REST-to-MCP 能力，零代码转换为可供 AI Agent 直接调用的 MCP 工具。读完本文，你将掌握云市场 API 的订阅与 AppCode 获取流程、mcp-server.yaml中工具定义与请求/响应模板的完整写法、限行数据响应字段的解读方法，以及该 MCP Server 在 Higress 上的部署与集成方式。

一、功能简介：vehicle-restriction-query能做什么

vehicle-restriction-query是 Higress 仓库 plugins/wasm-go/mcp-servers/mcp-vehicle-restriction-query 目录下的一个 MCP Server 示例，其数据源为阿里云云市场「极速数据」提供的车辆尾号限行 API。该服务覆盖北京、天津、杭州、成都、兰州、贵阳、南昌、长春、哈尔滨、武汉、上海、深圳等城市的车辆限行时间、区域、尾号等信息查询（见目录下 api.json 的info.description）。

它对外暴露两个工具：

对 AI Agent 而言，这类工具的价值在于：当用户询问「明天杭州限行吗」「北京今天尾号几限行」时，Agent 可以先调用get-city-list确认城市代号，再调用restriction-query获取精确的限行区域、时间段和尾号规则，从而给出可执行的出行建议。

二、架构原理：云市场 API 如何成为 MCP 工具

Higress 作为基于 Envoy 的 API 网关，支持通过插件机制托管 MCP Server。MCP（Model Context Protocol）本质上是面向 AI 更友好的 API，使 AI Agent 能够更容易地调用各种工具和服务，并由 Higress 统一处理认证、鉴权、限流、观测等能力（详见 plugins/wasm-go/mcp-servers/README_ZH.md）。

车辆限行查询服务的接入链路如下：

1. 用户在阿里云云市场订阅「车辆尾号限行」API，获得全局唯一的AppCode；
2. 开发者将 AppCode 配置到 Higress MCP Server 的server.config.appCode字段中；
3. Higress 侧通过mcp-server.yaml中的 REST-to-MCP 配置，把云市场 REST API 的每个端点声明为一个 MCP 工具；
4. AI Agent 通过 MCP 协议调用工具时，Higress 根据requestTemplate构造真实 HTTP 请求（自动携带Authorization: APPCODE {{.config.appCode}}认证头）发往云市场网关；
5. 返回的 JSON 响应经responseTemplate加工为结构化说明文本后回传给 AI。

整个过程无需编写任何 Go 代码，纯粹依靠声明式 YAML 配置完成「REST 到 MCP」的转换。REST-to-MCP 能力内置于所有 MCP Server，其底层逻辑实现在 plugins/wasm-go/pkg/mcp/server/rest_server.go 中。

三、前置准备：订阅 API 并获取 AppCode

使用该 MCP 服务前，需要完成以下三步（原文档「如何在使用云市场 API MCP 服务」章节内容）：

1. 订阅 API：进入云市场「车辆尾号限行」API 详情页，订阅该 API。首次使用可优先选择免费试用额度。
2. 获取 AppCode：前往云市场用户控制台，使用阿里云账号登录后，查看已订阅 API 服务的 AppCode，并将其配置到 Higress MCP Server 的配置中。注意：在云市场订阅 API 服务后获得的 AppCode 是全局统一的——对于你订阅的所有 API 服务，此 AppCode 相同，只需一个 AppCode 即可访问所有已订阅的 API 服务。
3. 额度管理：云市场用户控制台会实时展示已订阅预付费 API 服务的可用额度；免费试用额度用完后，可重新订阅以继续使用。

说明：原文档中提到的 API 认证所需 APP Code 申请入口位于阿里云云市场 API 市场对应商品详情页，本文不展开外部链接，具体以云市场控制台实际展示为准。

四、核心配置详解：mcp-server.yaml逐段拆解

vehicle-restriction-query的完整 MCP 配置位于 mcp-server.yaml。下面逐段拆解其结构。

4.1 服务器定义与配置

server: name: vehicle-restriction-query config: appCode: ""

• name：MCP Server 名称，用于在 Higress 插件体系中标识并路由请求；若集成到 all-in-one 插件，该字段必须与代码中mcp.AddMCPServer()使用的名称一致（详见 plugins/wasm-go/mcp-servers/README_ZH.md 中「插件配置」章节）。
• config.appCode：云市场 API 认证凭据，需替换为你在云市场控制台获取的真实 AppCode。若留空，网关侧Authorization头将无法通过云市场校验。

4.2 工具一：城市限行查询接口（restriction-query）

tools: - name: restriction-query description: 通过城市代号和日期获取城市车辆限行信息查询。 args: - name: city description: 城市代号 type: string required: true position: query - name: date description: 日期 默认为今天 格式为：2015-12-02 type: string required: true position: query

参数说明（对应原文档「城市限行查询接口」章节）：

其中position: query表示参数将作为 URL 查询参数拼接到请求中，这是 Higress REST-to-MCP 参数位置的合法取值之一（另有path、header、cookie、body，见 rest_server.go 中RestToolArg.Position的定义与注释）。

请求模板部分：

requestTemplate: url: https://jisuclwhxx.market.alicloudapi.com/vehiclelimit/query method: GET headers: - key: Authorization value: APPCODE {{.config.appCode}} - key: X-Ca-Nonce value: '{{uuidv4}}'

• url：云市场 API 网关地址与路径，与 api.json 中servers[0].url和paths./vehiclelimit/query完全对应；
• method: GET：与 OpenAPI 定义中的请求方法一致；
• Authorization: APPCODE {{.config.appCode}}：云市场网关的标准签名认证头，{{.config.appCode}}为模板变量，运行时替换为server.config中配置的 AppCode。这正是云市场 AppCode 认证机制的落地方式；
• X-Ca-Nonce: {{uuidv4}}：一次性随机数，防止请求重放，uuidv4是模板引擎内置的 UUID 生成函数。

4.3 工具二：获取城市接口（get-city-list）

- name: get-city-list description: 获取城市代号和城市名称。 args: [] requestTemplate: url: https://jisuclwhxx.market.alicloudapi.com/vehiclelimit/city method: GET headers: - key: Authorization value: APPCODE {{.config.appCode}} - key: X-Ca-Nonce value: '{{uuidv4}}'

• args: []：此接口无需额外参数输入（对应原文档「获取城市接口」章节的参数说明），直接调用即可返回全部支持城市；
• 请求地址指向 api.json 中的/vehiclelimit/city端点，认证方式与查询接口一致。

4.4 响应模板：把 JSON 转成 AI 友好文本

两个工具均配置了responseTemplate，其核心是prependBody：在返回原始 JSON 之前，预先注入一段结构化的字段说明，帮助大模型正确理解响应数据。以restriction-query为例：

responseTemplate: prependBody: |+ # API Response Information ... ## Response Structure > Content-Type: application/json - **msg**: 消息 (Type: string) - **result**: (Type: object) - **result.area**: 限行区域描述 (Type: string) - **result.city**: 城市代码 (Type: string) - **result.cityname**: 城市名称 (Type: string) - **result.date**: 日期 (Type: string) - **result.number**: 限行号码 (Type: string) - **result.numberrule**: 限行号码规则 (Type: string) - **result.summary**: 限行规则摘要 (Type: string) - **result.time**: 限行时间段 (Type: array) - **result.time[]**: Items of type string - **result.week**: 星期 (Type: string) - **status**: 状态码 (Type: string) ## Original Response

prependBody对应 rest_server.go 中RestToolResponseTemplate.PrependBody字段（另有body用于完全重写响应、appendBody用于在响应后追加文本）。由于车辆限行返回结构较规整，这里选择「字段说明 + 原始 JSON」的组合，既保留完整数据供 AI 精确解析，又避免模板改写引入信息丢失。

五、响应数据模型：限行结果字段全解读

根据 api.json 中/vehiclelimit/query的响应 Schema，一次成功的查询会返回如下结构：

{ "status": "0", "msg": "ok", "result": { "city": "hangzhou", "cityname": "杭州", "date": 1449100800000, "week": "星期四", "time": ["07:00-09:00", "16:30-18:30"], "area": "限行区域描述", "summary": "本市号牌尾号限行，外地号牌全部限行。法定上班的周六周日不限行。", "numberrule": "最后一位数字", "number": "4和6" } }

各字段含义与数据类型：

get-city-list接口则返回result为数组，每个元素包含city（城市代码）与cityname（城市名称）的映射，便于客户端将其转换为下拉菜单等展示形式。

六、模板语法与底层机制

理解mcp-server.yaml中的{{.config.appCode}}、{{uuidv4}}等写法，需要了解 REST-to-MCP 的模板引擎。Higress 使用 GJSON Template 库进行渲染，它结合了 Go 模板语法与 GJSON 的路径语法（详见 plugins/wasm-go/mcp-servers/README_ZH.md 中「模板语法」与「GJSON 路径语法」章节）：

• 请求模板（requestTemplate）用于构造 HTTP 请求的 URL、头部与正文：通过.config.fieldName访问服务器配置值，通过.args.argName访问工具参数值；
• 响应模板（responseTemplate）用于把 HTTP 响应转换为适合 AI 消费的格式：使用 GJSON 路径访问 JSON 字段，支持add、upper、lower等模板函数以及if、range等控制结构。

GJSON Template 内置了全部 Sprig 函数（70 余个），本配置中用到的uuidv4即为 UUID 生成函数，用于生成X-Ca-Nonce防重放随机数。从源码结构看，rest_server.go 中RestToolRequestTemplate（含URL、Method、Headers、Body等字段）与RestToolResponseTemplate（含Body、PrependBody、AppendBody）正是这份 YAML 配置的 Go 结构体映射，解析后的 URL/Header/Body 模板会在工具调用时被逐一渲染并执行。

七、部署与集成方式

7.1 作为独立 MCP Server 插件部署

将mcp-server.yaml中的server.config.appCode填入真实值后，即可将该配置应用到 Higress 的 MCP Server 插件。Higress 通过插件机制托管 MCP Server，可获得统一认证鉴权、精细化限流、完整审计日志与可观测性等能力（见 plugins/wasm-go/mcp-servers/README_ZH.md 背景章节）。需注意：MCP Server 插件要求 Higress 2.1.0 及以上版本。

7.2 集成到 all-in-one 插件

Higress 支持将多个 MCP Server 打包进同一个 all-in-one 插件（共享一个 WASM 二进制，每个 Server 保持独立身份与配置）。vehicle-restriction-query这类基于 REST-to-MCP 的 Server 天然兼容该模式——因为 REST-to-MCP 能力内置于所有 MCP Server。集成时只需在 all-in-one 的配置中声明对应的server.name与tools，Higress 会根据name字段路由到正确的 Server。

7.3 构建 WASM 二进制（如需自行编译）

仓库 plugins/wasm-go/mcp-servers/Makefile 提供了统一的构建入口：

make SERVER_NAME=vehicle-restriction-query build # 构建 WASM 二进制 make SERVER_NAME=vehicle-restriction-query build-image # 构建 Docker 镜像

build目标实际执行GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o main.wasm main.go，将 Go 代码编译为 WASI 平台的 WebAssembly 产物；SERVER_NAME默认值为quark-search，构建时需显式指定为本 Server 名。镜像默认推送到higress-registry.cn-hangzhou.cr.aliyuncs.com/mcp-server/仓库，可通过REGISTRY、SERVER_VERSION变量覆盖。

八、总结

vehicle-restriction-query是一个典型的「云市场 API + Higress REST-to-MCP」接入范例：它展示了如何不写一行业务代码，仅通过声明式 YAML 将阿里云云市场的车辆限行 REST API 包装为两个 AI 可调用的 MCP 工具（restriction-query、get-city-list），并通过Authorization: APPCODE请求头模板实现云市场认证、通过X-Ca-Nonce随机数防重放、通过prependBody响应模板辅助大模型理解限行数据。其配套的 api.json 提供了完整的 OpenAPI 契约，mcp-server.yaml 提供了可直接落地的完整配置，开发者可参照此范式快速将任意云市场 API 接入 Higress MCP 生态。

【免费下载链接】higress🤖 AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress