企业官网建设流程全解析

基于 Higress 的云市场 API MCP 服务实战：企业专利查询（business-patent-query）

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

Higress 作为 AI Native API Gateway，内置 REST-to-MCP 能力，可以把阿里云云市场的 REST API 零代码转换为可供 AI Agent 调用的 MCP 工具。本文以business-patent-query企业专利查询服务为完整案例，从订阅 API、获取 AppCode、理解两个核心工具的参数与响应结构，到剖析mcp-server.yaml配置模板与底层生成机制，帮助读者掌握在 Higress 上快速接入云市场 API 的完整流程。

一、背景：什么是云市场 API MCP 服务

阿里云云市场是生态伙伴的交易服务平台，其 API 服务涵盖应用开发、身份验证与金融、车辆交通与物流、企业服务、短信与运营商、AI 应用与 OCR、生活服务等多个类目。云市场 API 依托 Higress 提供 MCP 服务：只需在云市场完成订阅并获取 AppCode，通过 Higress MCP Server 进行配置，即可无缝集成云市场 API 服务。

Higress 作为基于 Envoy 的 API 网关，支持通过插件方式托管 MCP Server。MCP（Model Context Protocol）本质上是面向 AI 更友好的 API，使 AI Agent 能够更容易地调用各种工具和服务。Higress 可以统一处理工具调用的认证、鉴权、限流、观测等能力，简化 AI 应用的开发和部署（参见 MCP 服务器实现指南）。

注意：MCP Server 插件需要 Higress 2.1.0 或更高版本才能使用。

二、准备工作：订阅 API 与获取 AppCode

使用企业专利查询服务前，需要完成两步准备：

1. 订阅 API：进入 企业专利查询 API 详情页，订阅该 API，可以优先使用免费试用额度。
2. 获取 AppCode：前往云市场用户控制台，使用阿里云账号登录后查看已订阅 API 服务的 AppCode，并配置到 Higress MCP Server 的配置中。

需要特别注意的是：在阿里云市场订阅 API 服务后获得的 AppCode，对于所订阅的所有API 服务是相同的，只需使用这一个 AppCode 即可访问所有已订阅的 API 服务。云市场用户控制台会实时展示已订阅的预付费 API 服务的可用额度，如免费试用额度已用完，可以重新订阅。

三、服务功能与两大核心工具

business-patent-query服务器专注于为企业或个人用户提供专利相关信息的服务。通过此服务，用户可以搜索到特定技术领域内的所有相关专利，这有助于避免侵犯他人的知识产权，并为自身的研发活动指明方向。它包括两大核心功能：专利信息列表检索与专利详情查看（定义于 mcp-server.yaml）。

3.1 专利信息列表（business-patent-query）

• 用途：根据关键字（如公司名称、社会统一信用代码、注册号等）查找相关的专利列表。
• 应用场景：当需要对某一行业或公司的专利布局进行全面了解时使用；也可用于市场调研、竞争对手分析等领域。
• 参数说明：

该工具对应的底层 API 为GET /utn/ip/PatentPageByKey/V2，其请求模板定义如下：

requestTemplate: url: http://icpatent.market.alicloudapi.com/utn/ip/PatentPageByKey/V2 method: GET headers: - key: Authorization value: APPCODE {{.config.appCode}} - key: X-Ca-Nonce value: '{{uuidv4}}'

3.2 专利信息详情（patent-detail）

• 用途：基于已知的专利 ID，获取单个专利的具体细节信息。
• 应用场景：适用于深入研究某一项具体的专利内容，或是需要详细了解某项技术解决方案的情况。
• 参数说明：

该工具对应的底层 API 为GET /utn/ip/PatentDetail，请求模板与列表接口一致，均通过Authorization: APPCODE {{.config.appCode}}头携带认证信息。

四、部署配置：mcp-server.yaml 深度解析

企业专利查询服务的完整配置位于 mcp-server.yaml，其顶层结构如下：

server: name: business-patent-query config: appCode: "" tools: - name: business-patent-query ... - name: patent-detail ...

4.1 server 配置段

• name：MCP 服务器名称，必须与 all-in-one 插件中mcp.AddMCPServer()注册的名称一致，系统通过该字段识别由哪个 MCP Server 处理请求。
• config.appCode：云市场订阅后获取的 AppCode，通过模板变量{{.config.appCode}}注入到请求头中完成 API 认证。

4.2 请求模板（requestTemplate）

请求模板用于构造 HTTP 请求的 URL、头部和正文：

• 使用.config.fieldName访问服务器配置值，如{{.config.appCode}}；
• 使用.args.argName访问工具参数，如{{.args.keyword}}；
• 模板函数如{{uuidv4}}用于生成X-Ca-Nonce（阿里云 API 网关要求的防重放随机数）头。

4.3 响应模板（responseTemplate）

响应模板用于将 HTTP 响应转换为适合 AI 消费的格式。business-patent-query使用prependBody方式，在原始响应前拼接一段 Markdown 格式的响应结构说明，帮助 LLM 理解每个字段的含义，随后附上原始响应内容。这是云市场 MCP 模板（yunmarket-tmpl.yaml）的典型写法：先描述字段语义，再给出数据，让 AI 在解析时"看图说话"。

4.4 可选白名单：allowTools

在部署时还可以通过allowTools配置工具白名单，只有列出的工具才能被调用，起到安全管控作用：

server: name: business-patent-query config: appCode: "你的AppCode" allowTools: - business-patent-query - patent-detail

五、响应数据结构详解

5.1 专利信息列表响应

列表接口（/utn/ip/PatentPageByKey/V2）的响应包含三个顶层字段：

• data（object）：
  • data.Items（array）：专利列表，每项包含：
    • Id（integer）：专利 ID，作为详情查询的入参；
    • Title（string）：标题；
    • ApplicationNumber/ApplicationDate：申请号与申请日期；
    • PublicationNumber/PublicationDate：公开号与公开日期；
    • AssigneeStringList：申请人；
    • InventorStringList：发明人；
    • Agency：代理机构；
    • IPCList/IPCDesc：IPC 分类号与分类描述；
    • KindCodeDesc：类别代码描述（如"发明"）；
    • LegalStatusDesc：法律状态描述（如"授权"）。
  • data.Paging（object）：分页信息，含PageIndex（当前页码）、PageSize（每页显示条数）、TotalRecords（总记录数）。
• orderNo（integer）：订单号，用于跟踪请求。
• statusCode（integer）：状态码（成功为1）。
• statusMessage（string）：状态消息（如"请求成功"）。

字段的完整定义与示例值可在 api.json 的 OpenAPI 3.0.1 规范中核对，例如Id示例值为45233394、TotalRecords示例值为8842。

5.2 专利信息详情响应

详情接口（/utn/ip/PatentDetail）的响应在列表字段基础上进一步扩充：

• data.Abstract：摘要；
• data.Agent：代理人；
• data.PrimaryExaminer/data.AssiantExaminer：主审查员 / 辅助审查员；
• data.AssigneestringList：专利权人列表；
• data.Cites/data.OtherReferences：引用与其他引用；
• data.PatentImage：专利图片链接；
• data.DocumentTypes：文档类型；
• data.PatentLegalHistory（array）：法律状态变更历史，每项含LegalStatus、LegalStatusDate、Desc；
• data.LegalStatusDate：法律状态日期。

响应同样包含orderNo、statusCode、statusMessage元数据，便于跟踪请求状态和解析数据。每个工具都提供了详细的请求模板和响应模板说明，以确保开发者能够正确调用 API 并处理返回的数据。

六、底层机制：REST-to-MCP 与自动生成流程

6.1 零代码的 REST-to-MCP 能力

business-patent-query之所以只需要一份 YAML 配置而无需编写任何 Go 代码，是因为 Higress 内置了 REST-to-MCP 能力：它允许将任意 REST API 转换为 MCP 工具，该能力内置于所有 MCP Server（可基于 all-in-one 插件使用），模板渲染基于 GJSON Template 库，结合 Go 模板语法与 GJSON 路径语法（详见 MCP 服务器实现指南）。

6.2 配置文件的自动生成脚本

该服务的三个文件（api.json、mcp-server.yaml、README_ZH.md/README.md）由脚本 create_api_directories.sh 批量生成：

1. 在脚本的api_codes与server_names数组中维护了 35 个云市场 API 的映射（企业专利查询对应cmapi00049059/business-patent-query）；
2. 通过openapi-to-mcp工具将api.json（OpenAPI 3.0.1 规范）转换为mcp-server.yaml，使用yunmarket-tmpl.yaml模板；
3. 再通过yaml_to_markdown.py与translate_readme.py生成中英文 README。

因此api.json与mcp-server.yaml在参数、端点、响应结构上严格一致，是理解该服务最权威的两份证据。

6.3 构建与镜像发布

如需将该 MCP Server 打包发布，可复用 mcp-servers/Makefile 中定义的目标：

# 构建 WASM 二进制（GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared） make SERVER_NAME=business-patent-query build # 构建包含 WASM 二进制的 Docker 镜像 make SERVER_NAME=business-patent-query REGISTRY=my-registry.example.com/ build-image

镜像基于scratch构建，仅包含/plugin.wasm一个产物（见 Dockerfile）。

七、典型应用场景与注意事项

典型场景：

• 知识产权风险排查：在立项或产品发布前，用公司名或技术关键词检索专利列表，确认是否存在侵权风险；
• 竞争对手分析：输入竞对公司名称（或统一社会信用代码），拉取全量专利清单，评估其技术布局方向；
• 研发方向调研：检索特定技术领域（IPC 分类）的专利，了解已有技术方案，为研发调整提供参考；
• AI 助手集成：将两个工具暴露给 AI Agent，用户用自然语言即可完成"查某公司专利"到"看某专利详情"的完整链路。

注意事项：

• pageSize最大不超过 10 条，大批量检索需配合pageIndex分页遍历，可通过Paging.TotalRecords计算总页数；
• dtype仅支持json与xml两种格式，默认json；
• AppCode 是访问所有已订阅云市场 API 的统一凭证，注意保管，避免泄露导致额度被盗用；
• 免费试用额度用完后需重新订阅，可用额度可在云市场用户控制台实时查看；
• 部署时若使用 all-in-one 插件，多个 MCP Server 共享同一插件实例，通过server.name区分，可降低网关上部署多个插件的额外开销。

八、小结

本文以business-patent-query企业专利查询服务为实例，完整走通了"云市场订阅 API → 获取 AppCode → 编写 REST-to-MCP 配置 → 理解工具参数与响应结构"的全流程。通过 Higress 的 MCP 能力，云市场数千个 REST API 都能以同样的方式低成本接入 AI 应用，统一获得网关层面的认证、鉴权、限流与观测能力。读者可在此基础上，参考 api.json 与 mcp-server.yaml 复制出属于自己业务场景的 MCP 服务配置。

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