使用 Higress 将 REST API 转换为 MCP Server 工具

Higress MCP Server 插件配置指南

Higress 是一款云原生 API 网关，集成了流量、微服务、安全及 AI 网关功能。基于 Istio 和 Envoy 开发，支持 Go/Rust/JS 等语言编写 Wasm 插件。其中 MCP Server 插件专为 AI 助手设计，允许我们将现有的 REST API 快速转换为 AI 模型可调用的工具。

核心功能

• 无需编码：通过配置即可将 REST API 暴露为 AI 工具。
• 统一治理：利用网关能力实现认证、鉴权、限流和可观测性。
• 快速集成：适配 OpenAI、DeepSeek、通义千问等多种 AI 服务商。

插件基础信息

• 执行阶段：默认阶段
• 优先级：30

配置结构

Server 级配置

字段名	类型	必填	描述
server.name	string	是	MCP Server 名称。内置服务（如 quark-search）只需此项；REST-to-MCP 场景可自定义。
server.config	object	否	服务器配置，例如 API 密钥。
server.allowTools	array	否	允许调用的工具列表，未指定则允许所有。

工具定义 (REST-to-MCP)

每个工具需定义名称、描述、参数及请求模板。

字段路径	类型	必填	说明
tools[].name	string	是	工具名称
tools[].description	string	是	功能描述
tools[].args	array	是	参数定义列表
tools[].requestTemplate	object	是	HTTP 请求模板
tools[].responseTemplate	object	是	响应转换模板

参数类型支持

支持多种类型以精确描述工具输入：

• string：字符串（默认）
• number：浮点数
• integer：整数
• boolean：布尔值
• array：数组，需配合 items 定义元素模式
• object：对象，需配合 properties 定义属性模式

请求参数传递方式

以下四种方式在 requestTemplate 中互斥，选择一种即可：

1. 表单提交 (argsToFormBody) 参数以 application/x-www-form-urlencoded 编码，自动添加 Content-Type。

   requestTemplate:
     argsToFormBody: true
   

2. URL 查询参数 (argsToUrlParam) 参数追加到 URL 中。

   requestTemplate:
     argsToUrlParam: true
   

3. JSON Body (argsToJsonBody) 参数作为 JSON 对象发送，自动设置 Content-Type: application/json; charset=utf-8。

   requestTemplate:
     argsToJsonBody: true
   

4. 手动构建 Body (body) 最灵活的方式，适合复杂场景。

   requestTemplate:
     body: |
       { "query": "{{.args.query}}", "filters": {{toJson .args.filters}}, "options": { "limit": {{.args.limit}} } }
   

模板语法

配置中使用 GJSON Template 语法，结合 Go 模板与 GJSON 路径。

• 访问配置：{{.config.字段名}}
• 访问参数：{{.args.参数名}}
• 响应处理：使用 GJSON 路径访问 JSON 字段，支持控制结构（if/range）及函数（add/upper/lower）。

常用 GJSON 路径示例：

• 点表示法：address.city
• 数组索引：users.0.name
• 数组过滤：users.#(age>=30)#.name

配置示例

1. 使用内置 MCP Server

server:
  name: "quark-search"
  config:
    apiKey: "xxxx"

2. 转换高德地图 API

此例展示了如何将结构化地址解析接口转换为 AI 工具。

server:
  name: rest-amap-server
  config:
    apiKey: your-api-key-here
  tools:
    - name: maps-geo
      description: "将详细的结构化地址转换为经纬度坐标。支持地标性名胜景区、建筑物名称解析为经纬度坐标"
      args:
        - name: address
          description: "待解析的结构化地址信息"
          type: string
          required: true
        - name: city
          description: "指定查询的城市"
          type: string
          required: false
        - name: output
          description: "输出格式"
          type: string
          enum:
            - json
            - xml
          default: "json"
      requestTemplate:
        url: "https://restapi.amap.com/v3/geocode/geo"
        method: GET

通过上述配置，任何 REST API 都能被快速转化为 AI Agent 可调用的数据源，无需额外开发代码。