Higress 商品条码查询 MCP Server：product-barcode-query 的 REST-to-MCP 配置与实现原理
【免费下载链接】higress🤖 AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress
本文基于 Higress 仓库中product-barcode-queryMCP Server 的官方文档，完整讲解如何通过 REST-to-MCP 方式将一个"商品条码查询"REST API 零代码地转换为 AI 可调用的 MCP 工具：包括 AppCode 获取流程、mcp-server.yaml配置逐项解析、请求模板渲染机制、响应字段结构，以及该配置在 Higress MCP 插件源码（rest_server.go）中的对应实现。读完本文，你可以直接复制配置到 Higress 中使用，并理解每个配置项背后的模板渲染原理。
一、服务功能概述
product-barcode-query是 Higress 内置的一个商品条码查询 MCP Server（服务名定义在 mcp-server.yaml 的server.name字段），专门用于查询国内商品条形码信息。它通过 API 调用获取与指定条形码相关的商品详情，包括但不限于商品名称、品牌、价格等关键信息。
该服务特别适合需要快速、准确访问大量商品数据的应用场景，例如：
- 电商平台：用户扫描商品条形码后，立即展示相关商品详情；
- 库存管理系统：零售商通过条码快速检索商品资料，提升效率与准确性；
- 消费者权益保护平台：基于条码追溯商品来源。
从 api.json 的接口描述还可以确认其能力边界：支持查询商品条形码与药品条形码，根据条码返回名称、价格、厂家等信息，实现"来源可查、去向可追"。注意：条码查询目前只支持 69 开头的 13 位或 069 开头的 14 位国内商品，进口和国外商品暂不支持查询。
云市场 API MCP 服务背景
该工具并非 Higress 自研的数据服务，而是依托阿里云云市场（API 市场）提供的第三方 API，再由 Higress 以 MCP 协议托管暴露给 AI 应用。云市场的 API 服务涵盖应用开发、身份验证与金融、车辆交通与物流、企业服务、短信与运营商、AI 应用与 OCR、生活服务等多个类目；云市场 API 依托 Higress 提供 MCP 服务，只需在云市场完成订阅并获取 AppCode，通过 Higress MCP Server 配置即可无缝集成（详见 README_ZH.md 中的说明）。
二、前置条件：获取 AppCode
API 认证需要的 AppCode 需要在阿里云 API 市场申请（对应 API 市场产品编号 cmapi011032，请进入该 API 详情页完成订阅）。使用流程为：
- 进入 API 详情页订阅该 API，可优先使用免费试用；
- 前往云市场用户控制台，使用阿里云账号登录后查看已订阅 API 服务的 AppCode，并将其配置到 Higress MCP Server 的配置中；
- 控制台会实时展示已订阅的预付费 API 服务的可用额度，免费试用额度用完后可以重新订阅。
一个关键细节：在阿里云市场订阅 API 服务后，您将获得一个 AppCode；对于您订阅的所有 API 服务，此 AppCode 是相同的，即只需使用这一个 AppCode 即可访问所有已订阅的 API 服务。这也是mcp-server.yaml中只需在server.config配置一处appCode的原因。
三、MCP Server 配置全解析
该 MCP Server 的全部定义位于 mcp-server.yaml，采用 Higress 内置的 REST-to-MCP 配置格式，无需编写任何代码：
server: name: product-barcode-query config: appCode: "" tools: - name: barcode-query description: 国内商品条码查询 args: - name: code description: 国内商品条形码（69开头） type: string required: true position: query requestTemplate: url: https://barcode14.market.alicloudapi.com/barcode method: GET headers: - key: Authorization value: APPCODE {{.config.appCode}} - key: X-Ca-Nonce value: '{{uuidv4}}' responseTemplate: prependBody: |+ # API Response Information Below is the response from an API call. To help you understand the data, I've provided: 1. A detailed description of all fields in the response structure 2. The complete API response ## Response Structure > Content-Type: application/json - **showapi_res_body**: (Type: object) - **showapi_res_body.code**: 条形码 (Type: string) - **showapi_res_body.engName**: 英文名称 (Type: string) - **showapi_res_body.flag**: 查询结果标志 (Type: string) - **showapi_res_body.goodsName**: 商品名称 (Type: string) - **showapi_res_body.goodsType**: 商品分类 (Type: string) - **showapi_res_body.img**: 图片地址 (Type: string) - **showapi_res_body.manuName**: 厂商 (Type: string) - **showapi_res_body.note**: 备注信息 (Type: string) - **showapi_res_body.price**: 参考价格(单位:元) (Type: string) - **showapi_res_body.remark**: 查询结果备注 (Type: string) - **showapi_res_body.ret_code**: 返回代码 (Type: string) - **showapi_res_body.spec**: 规格 (Type: string) - **showapi_res_body.sptmImg**: 条码图片 (Type: string) - **showapi_res_body.trademark**: 商标/品牌名称 (Type: string) - **showapi_res_body.ycg**: 原产地 (Type: string) - **showapi_res_code**: 响应代码 (Type: integer) - **showapi_res_error**: 错误信息 (Type: string) ## Original Response各配置项含义如下：
| 配置项 | 取值/说明 |
|---|---|
server.name | MCP Server 名称product-barcode-query，插件通过该名称匹配对应 Server 的配置（参见 MCP 服务器实现指南 中 all-in-one 插件的说明） |
server.config.appCode | 云市场 AppCode，默认留空，部署时填入；请求模板中通过{{.config.appCode}}引用 |
tools[].name | MCP 工具名barcode-query，即 AI 侧tools/call时使用的工具标识 |
tools[].args | 工具入参定义：code（字符串、必填、置于 query 字符串） |
requestTemplate | 如何构造对上游 API 的 HTTP 请求（URL、Method、Headers） |
responseTemplate.prependBody | 在原始 API 响应之前拼接的 Markdown 说明文本，帮助 LLM 理解返回数据 |
工具与参数说明
barcode-query工具只有一个入参：
code：国内商品条形码（必须以 69 开头）。这是发起请求时必需提供的参数。- 类型：字符串（String）
- 必填：是
- 位置：查询字符串（Query string）
在 OpenAPI 定义 api.json 中给出了示例值6938166920785，与"69 开头的 13 位国内商品条码"的约束一致。
请求模板详解
请求模板定义了 MCP 工具调用被转换成上游 HTTP 请求的方式：
- URL：
https://barcode14.market.alicloudapi.com/barcode（与api.json中servers[0].url加paths./barcode一致） - Method：GET
- Headers：
Authorization:APPCODE {{.config.appCode}}—— 使用云市场 APPCODE 鉴权方式，值为服务器配置中注入的 AppCode；X-Ca-Nonce:{{uuidv4}}—— 阿里云 API 网关要求的请求级唯一 nonce，每次调用自动生成一个 UUID。
从源码结构看，这两个模板占位符的行为在 rest_server.go 中实现：RestToolRequestTemplate结构定义了url、method、headers等字段，parseTemplates会将 URL 与 Headers 中的模板字符串解析为 Go template。REST-to-MCP 功能使用 GJSON Template 库做模板渲染，该库包含全部 Sprig 函数（共 70 余个），因此：
{{.config.appCode}}：通过.config.fieldName路径访问server.config中的配置值；{{uuidv4}}：即 Sprig 提供的 UUID 生成函数（见 MCP 服务器实现指南 对模板语法的说明），保证每个请求的X-Ca-Nonce互不相同，避免被上游判定为重放。
此外，工具参数通过.args.argName路径引用，code参数由于声明了position: query，会被自动拼接到 URL 查询字符串中，最终上游请求形如：
GET /barcode?code=6938166920785 Authorization: APPCODE <你的AppCode> X-Ca-Nonce: <随机UUID> Host: barcode14.market.alicloudapi.com四、响应结构与 responseTemplate 机制
API 响应以 JSON 格式返回，包含以下主要字段：
showapi_res_body：包含实际的商品信息showapi_res_body.code：条形码showapi_res_body.engName：英文名称showapi_res_body.flag：查询结果标志showapi_res_body.goodsName：商品名称showapi_res_body.goodsType：商品分类showapi_res_body.img：图片地址showapi_res_body.manuName：厂商showapi_res_body.note：备注信息showapi_res_body.price：参考价格（单位：元）showapi_res_body.remark：查询结果备注showapi_res_body.ret_code：返回代码showapi_res_body.spec：规格showapi_res_body.sptmImg：条码图片showapi_res_body.trademark：商标/品牌名称showapi_res_body.ycg：原产地
showapi_res_code：响应状态码showapi_res_error：错误信息（如果存在的话）
在 api.json 中，这些字段以 OpenAPI 3.0.1 的 schema 形式完整声明（showapi_res_code为 integer，showapi_res_body内各字段均为 string），可被openapi-to-mcp等工具直接消费。
prependBody：把"字段字典"喂给 LLM
responseTemplate.prependBody的设计动机很实际：上游返回的 JSON 对 LLM 而言是"裸数据"，字段含义（如ycg是原产地、sptmImg是条码图片）并不自明。Higress 的做法是在返回给 AI 的最终文本前，拼接一段 Markdown 格式的字段结构说明，形成"# API Response Information → 字段描述 → ## Original Response → 原始 JSON"的结构化提示。
其执行逻辑在 rest_server.go 中可以确认：当配置了ResponseTemplate.PrependBody或AppendBody时，最终结果直接拼接为PrependBody + rawResponse + AppendBody（见RestToolResponseTemplate结构定义中的注释 "Text to insert before the response body"，rest_server.go）。同时源码还约束了互斥规则：若指定了完整的Body响应模板，则不允许同时使用PrependBody/AppendBody（解析阶段会直接报错）。本配置选择了更轻量的prependBody方案，保留原始响应原文，只在前面补充解释性文字，兼顾了信息完整性与 LLM 可读性。
五、配置与 OpenAPI 的关系：该目录是如何生成的
该 MCP Server 目录下的三个文件存在明确的生成关系。从 create_api_directories.sh 脚本可以看到，云市场类 MCP Server 的标准生产流程是：
- 提供
api.json（OpenAPI 3.0.1 定义，声明接口路径、参数、响应 schema 与服务地址）； - 通过
openapi-to-mcp --input api.json --output mcp-server.yaml --server-name <name> --template yunmarket-tmpl.yaml生成mcp-server.yaml，其中yunmarket-tmpl.yaml模板负责注入云市场通用的APPCODE鉴权头与X-Ca-Nonce头； - 再通过
yaml_to_markdown.py将mcp-server.yaml的内容转换后追加到README_ZH.md，形成中英文 README。
这意味着如果你新增了同类云市场 API，只需按同一流程提供api.json，即可得到一致的mcp-server.yaml与文档；而mcp-product-barcode-query中的Authorization: APPCODE {{.config.appCode}}+X-Ca-Nonce: {{uuidv4}}正是云市场模板的通用签名模式。
六、部署要点与适用前提
- 版本要求：MCP 服务器插件需要 Higress 2.1.0 或更高版本（见 MCP 服务器实现指南）。
- 配置入口：将
mcp-server.yaml的内容作为 mcp-server 插件（或 all-in-one MCP 插件）的配置下发，并把config.appCode替换为控制台获取的真实 AppCode；插件通过server.name字段找到对应的 MCP server。 - 能力边界：仅支持国内商品条码（69 开头的 13 位、069 开头的 14 位），进口商品不支持；免费试用额度用尽后需重新订阅。
- 复用性：由于 REST-to-MCP 是内置能力（核心实现见 rest_server.go），此配置模式同样适用于仓库中其他云市场 MCP Server（如 mcp-agricultural-product-price-query、mcp-book-query 等，它们共用同一套
APPCODE+{{uuidv4}}请求头模式）。
小结
product-barcode-query展示了 Higress "REST-to-MCP" 的典型用法：以 mcp-server.yaml 声明工具与请求模板、以 api.json 描述上游 OpenAPI 契约、以responseTemplate.prependBody增强 LLM 对响应的理解，全程零代码即可将云市场的商品条码查询 API 转化为可供 AI Agent 直接调用的 MCP 工具。相关文档可参考 英文 README 与 中文 README。
【免费下载链接】higress🤖 AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
