Higress MCP 实践基于阿里云云市场 API 构建菜谱查询 MCP Server 的完整配置与实现解析【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress本文以 Higress 内置的菜谱查询Recipe QueryMCP Server 为例讲清如何将一个需要 AppCode 认证的第三方 HTTP API 封装为标准的 MCP 工具集包括 4 个查询工具的参数定义与适用场景、mcp-server.yaml的完整配置项解析请求模板、认证头、响应增强以及 Higress MCP Server 插件在运行期如何渲染这些模板、拼接响应内容的源码级实现。读完本文你可以独立地为任意AppCode/密钥认证 JSON 响应的第三方 API 编写一份可直接部署的 MCP Server 配置。一、什么是云市场 API MCP 服务菜谱查询 MCP Server 属于 Higress 仓库中云市场 API MCP 服务这一系列之一同系列还包括天气查询、物流轨迹、汇率查询、股票助手等均位于plugins/wasm-go/mcp-servers/目录下。阿里云云市场是生态伙伴的交易服务平台其 API 服务覆盖应用开发、身份验证与金融、车辆交通与物流、企业服务、短信与运营商、AI 应用与 OCR、生活服务等多个类目。云市场 API 依托 Higress 提供 MCP 服务用户只需在云市场完成 API 订阅并获取 AppCode再通过 Higress MCP Server 进行配置即可将该 API 无缝暴露为 LLM 可调用的 MCP 工具。使用流程概述进入云市场 API 详情页订阅该 API可优先使用免费试用菜谱查询对应的正是【极速数据】菜谱大全_菜谱查询_菜谱API_菜谱数据这一商品参见 api.json 中的info段前往云市场用户控制台用阿里云账号登录后查看已订阅 API 服务的 AppCode并配置到 Higress MCP Server 配置中。注意订阅所有 API 服务获得的 AppCode 是相同的一个 AppCode 即可访问所有已订阅的 API 服务云市场控制台会实时展示已订阅预付费 API 服务的可用额度免费试用额度用完后可以重新订阅。二、四个 MCP 工具及其参数该 MCP Server 提供菜谱相关的 API 服务用户可以进行多种类型的查询按分类检索菜谱、根据 ID 获取详细信息、查看菜谱分类列表、通过关键词搜索菜谱。所有请求均需携带特定的认证信息AppCode以确保安全访问。1. 按分类检索query-byclass描述从万种菜谱中查找符合条件的结果支持按照不同的分类或关键词进行检索。每条记录包含主料、辅料和详细的制作流程。参数参数类型必填说明classidinteger是指定的分类标识符numinteger是希望返回的结果数目startinteger否结果集中的起始位置默认 0应用场景当需要快速找到某一类别的多个食谱时非常有用。2. 根据 ID 查询详情query-byid描述基于提供的菜谱 ID 获取更加详尽的信息。参数参数类型必填说明idinteger是目标菜谱的唯一标识符应用场景适用于已经知道某道菜品的确切 ID、想要了解其全部细节的情况。3. 菜谱分类recipe-class描述列出所有的菜谱类别帮助开发者理解数据结构并据此构建更丰富的应用界面。参数无应用场景对于需要展示所有可用分类或让用户选择感兴趣分类的应用来说至关重要。4. 菜谱搜索recipe-search描述使用关键词对整个数据库执行全文搜索操作。参数参数类型必填说明keywordstring是用于匹配的搜索词api.json 中给出的示例值为白菜numinteger是期望返回的搜索结果数量示例值 10startinteger否搜索结果中的开始位置默认 0应用场景适合希望通过简单关键词输入就能找到相关食谱的应用。三、mcp-server.yaml 完整配置解析上述 4 个工具的完整定义位于 mcp-server.yaml这是部署该 MCP Server 的核心配置文件。其结构分为server服务器级配置和tools工具列表两部分。3.1 服务器级配置appCodeserver: name: recipe-query config: appCode: # 在此填入云市场订阅后获得的 AppCodeserver.name决定了该 MCP Server 在 Higress 中的标识config.appCode是唯一的服务器级配置项填入订阅云市场 API 后获得的 AppCode。它会被所有工具的请求模板通过模板变量{{.config.appCode}}引用实现一处配置、全局生效避免在每个工具中重复硬编码密钥。3.2 工具级配置args 与 requestTemplate以query-byclass为例工具配置由三部分构成tools: - name: query-byclass description: 万种菜谱包含主料、辅料制作流程。可按分类、关键词检索。 args: - name: classid description: 分类ID type: integer required: true position: query - name: num description: 获取数量 type: integer required: true position: query - name: start description: 起始条数默认0 type: integer position: query requestTemplate: url: http://jsucpdq.market.alicloudapi.com/recipe/byclass method: GET headers: - key: Authorization value: APPCODE {{.config.appCode}} - key: X-Ca-Nonce value: {{uuidv4}}关键字段说明name/descriptionMCP 工具名与描述LLM 依据描述来决定何时调用该工具、如何组织入参因此描述应清晰体现能力边界args参数定义数组。type取string/integer等基础类型required标注是否必填未标注即为可选position: query表示该参数以 URL query 参数形式拼接到请求 URL 上4 个工具全部采用 GET query 传参requestTemplate.url云市场 API 的网关域名jsucpdq.market.alicloudapi.com四个工具分别对应/recipe/byclass、/recipe/detail、/recipe/class、/recipe/search四个路径requestTemplate.methodHTTP 方法本例均为GETrequestTemplate.headers认证头模板。Authorization: APPCODE {{.config.appCode}}是云市场 API 的标准 AppCode 认证方式X-Ca-Nonce: {{uuidv4}}是云市场的防重放要求由 Higress 在每次请求时动态填充一个随机 UUIDuuidv4是 Higress MCP 配置模板支持的内置模板函数。从源码结构看{{.config.appCode}}、{{uuidv4}}这类模板由 MCP Server 插件的 REST 工具执行链路负责渲染——rest_server.go 中的工具执行逻辑会先解析requestTemplate再发起对目标 URL 的调用认证头在渲染完成后随请求一起发出因此明文 AppCode 只存在于 Higress 网关的配置中不会暴露给 LLM 侧。3.3 响应模板responseTemplate 与 prependBody每个工具还定义了responseTemplate.prependBody例如query-byclass的响应增强内容节选自 mcp-server.yamlresponseTemplate: prependBody: | # API Response Information Below is the response from an API call. To help you understand the data, Ive provided: 1. A detailed description of all fields in the response structure 2. The complete API response ## Response Structure Content-Type: application/json - **msg**: 响应消息 (Type: string) - **result**: (Type: object) - **result.list**: (Type: array) - **result.list[].classid**: 分类ID (Type: string) - **result.list[].content**: 菜品描述 (Type: string) - **result.list[].cookingtime**: 烹饪时间 (Type: string) - **result.list[].id**: ID (Type: string) - **result.list[].material**: (Type: array) - **result.list[].material[].amount**: 材料用量 (Type: string) - **result.list[].material[].mname**: 材料名称 (Type: string) - **result.list[].material[].type**: 材料类型 (Type: string) - **result.list[].name**: 菜名 (Type: string) - **result.list[].peoplenum**: 适合人数 (Type: string) - **result.list[].pic**: 图片URL (Type: string) - **result.list[].preparetime**: 准备时间 (Type: string) - **result.list[].process**: (Type: array) - **result.list[].process[].pcontent**: 步骤内容 (Type: string) - **result.list[].process[].pic**: 步骤图片URL (Type: string) - **result.list[].tag**: 标签 (Type: string) - **result.num**: 结果数量 (Type: string) - **status**: 状态码 (Type: integer) ## Original ResponseprependBody的作用是在返回给 LLM 的响应正文之前插入一段结构化的字段说明字段名、类型、中文含义再接上原始 JSON 响应。这是一项典型的面向 LLM 的响应整形设计原始 API 响应中的classid、peoplenum、pcontent等字段名对 LLM 并不自明前置的结构说明能显著降低模型误读字段、编造内容的概率。四个工具响应结构的主要差异query-byclass/recipe-searchresult为对象含num结果数量与list数组每个元素是一条菜谱记录material材料数组、process步骤数组query-byidresult直接是单条菜谱详情对象字段与列表元素一致recipe-classresult是分类数组每项含classid、name、parentid及子分类list含子分类classid/name/parentidstatus为 0 表示成功。从源码实现看prependBody是 rest_server.go 中ResponseTemplate结构体的字段PrependBody string json:prependBody,omitempty // Text to insert before the response body其执行逻辑在工具响应处理阶段rest_server.go当PrependBody非空时最终结果直接按PrependBody rawResponse AppendBody拼接。配置校验层还有一条约束rest_server.goBody自定义整体响应体与PrependBody/AppendBody互斥不能同时指定。对应的测试用例TestExecuteTemplaterest_server_test.go验证了仅 PrependBody AppendBody、无 Body 时合法以及Body 与 PrependBody 同时出现时配置非法两种情形说明本例的配置方式是经过测试覆盖的合法用法。四、集成部署步骤将菜谱查询能力接入 Higress 网关的步骤如下获取 AppCode在阿里云云市场订阅菜谱查询API优先使用免费试用在云市场用户控制台获取 AppCode编写配置复制 mcp-server.yaml将server.config.appCode填入实际 AppCode。其余tools定义参数、请求模板、响应增强可直接沿用注册到 Higress将该 MCP Server 配置通过 Higress 控制台或对应的 MCP Server 管理入口下发云市场系列 MCP Server 的通用做法在 mcp-servers 总目录 中有统一说明包括 AppCode 模板与uuidv4非空头的用法验证调用通过 MCP 客户端依次调用recipe-class获取分类树确认 AppCode 有效、query-byclass按分类取 N 条、query-byid取详情、recipe-search关键词搜索如keyword白菜num10检查响应是否为字段说明 原始 JSON的预期拼接格式。需要注意的前提与限制云市场 API 为按量/预付费服务免费试用额度用尽后需在控制台重新订阅否则请求会因额度耗尽而失败配置中模板 URL 为云市场网关的 HTTP 地址实际部署时应与云市场 API 详情页给出的最新调用地址保持一致由于认证依赖 AppCode切勿将含真实 AppCode 的mcp-server.yaml提交到公开仓库仓库中该文件appCode字段留空即为此原因。五、总结菜谱查询 MCP Server 展示了 Higress 将传统 HTTP API 转化为 MCP 工具的标准范式用args声明 LLM 可见的工具入参用requestTemplate声明带模板变量的目标 URL 与认证头AppCode 认证 {{uuidv4}}防重放头用responseTemplate.prependBody为 LLM 前置注入响应结构说明。这套声明式 YAML 模板渲染 响应整形的机制由 pkg/mcp/server/rest_server.go 统一实现因此本例的配置模式可以平移到仓库内其他云市场 API如 mcp-weather-query、mcp-logistics-tracking-query 等同目录下的系列 Server让开发者能够以极低的成本构建出满足不同查询需求的垂直领域 MCP 应用。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考