基于 Higress 将 REST API 转换为 MCP Server 工具

Higress 是一款云原生 API 网关，集成了流量网关、微服务网关、安全网关和 AI 网关的功能。 它基于 Istio 和 Envoy 开发，支持使用 Go/Rust/JS 等语言编写 Wasm 插件。 提供了数十个通用插件和开箱即用的控制台。 Higress AI 网关支持多种 AI 服务提供商，如 OpenAI、DeepSeek、通义千问等，并具备令牌限流、消费者鉴权、WAF 防护、语义缓存等功能。

MCP Server 插件配置

功能说明

• mcp-server 插件基于 Model Context Protocol (MCP)，专为 AI 助手设计，定义了 AI 模型与外部工具和资源交互的标准方式。
• 功能特点：
  1. 无需编写代码：将现有 REST API 转换为 AI 助手可调用的工具。
  2. 统一认证、鉴权、限流和可观测性：利用 Higress 网关提供的能力，确保安全性和性能。
  3. 快速构建和部署：通过 Higress 插件机制，快速添加新的 MCP Server。

运行属性

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

配置字段

Server 配置

字段名	数据类型	填写要求	默认值	描述
server.name	string	必填	-	MCP Server 的名称。如果是内置 MCP Server（如 quark-search），只需配置此字段；如果是 REST-to-MCP 场景，此字段可以自定义。
server.config	object	选填	{}	MCP Server 配置，如 API 密钥等。
server.allowTools	array of string	选填	-	允许调用的工具列表。如果不指定，则允许所有工具。

REST-to-MCP 工具配置

字段名	数据类型	填写要求	默认值	描述
tools	array of object	选填	[]	REST-to-MCP 工具配置列表。
tools[].name	string	必填	-	工具名称。
tools[].description	string	必填	-	工具功能描述。
tools[].args	array of object	必填	[]	工具参数定义。
tools[].args[].name	string	必填	-	参数名称。
tools[].args[].description	string	必填	-	参数描述。
tools[].args[].type	string	选填	string	参数类型（string、number、integer、boolean、array、object）。
tools[].args[].required	boolean	选填	false	参数是否必需。
tools[].args[].default	any	选填	-	参数默认值。
tools[].args[].enum	array	选填	-	参数允许的值列表。
tools[].args[].items	object	选填	-	数组项的模式（当 type 为 array 时）。
tools[].args[].properties	object	选填	-	对象属性的模式（当 type 为 object 时）。
tools[].requestTemplate	object	必填	-	HTTP 请求模板。
tools[].requestTemplate.url	string	必填	-	请求 URL 模板。
tools[].requestTemplate.method	string	必填	-	HTTP 方法（如 GET、POST 等）。
tools[].requestTemplate.headers	array of object	选填	[]	请求头模板。
tools[].requestTemplate.headers[].key	string	必填	-	请求头名称。
tools[].requestTemplate.headers[].value	string	必填	-	请求头值模板。
tools[].requestTemplate.body	string	选填	-	请求体模板（与 argsToJsonBody、argsToUrlParam、argsToFormBody 互斥）。
tools[].requestTemplate.argsToJsonBody	boolean	选填	false	参数直接作为 JSON 请求体（与 body、argsToUrlParam、argsToFormBody 互斥）。
tools[].requestTemplate.argsToUrlParam	boolean	选填	false	参数作为查询参数添加到 URL 中（与 body、argsToJsonBody、argsToFormBody 互斥）。
tools[].requestTemplate.argsToFormBody	boolean	选填	false	参数以 application/x-www-form-urlencoded 格式编码在请求体中（与 body、argsToJsonBody、argsToUrlParam 互斥）。
tools[].responseTemplate	object	必填	-	HTTP 响应转换模板。
tools[].responseTemplate.body	string	必填	-	响应体转换模板。

参数类型支持

• 支持多种参数类型，用于更精确地定义工具参数：
  • string：字符串类型（默认）。
  • number：数字类型（浮点数）。
  • integer：整数类型。
  • boolean：布尔类型（true/false）。
  • array：数组类型，使用 items 字段定义数组元素的模式。
  • object：对象类型，使用 properties 字段定义对象属性的模式。

请求参数传递方式

• 支持四种请求参数传递方式，这些选项是互斥的：

argsToFormBody：参数以 application/x-www-form-urlencoded 格式编码在请求体中，并自动添加相应的 Content-Type 头。

requestTemplate:argsToFormBody:true

argsToUrlParam：参数作为查询参数添加到 URL 中。

requestTemplate:argsToUrlParam:true

argsToJsonBody：参数直接作为 JSON 对象发送到请求体中，并自动添加 Content-Type: application/json; charset=utf-8 头。

requestTemplate:argsToJsonBody:true

body：手动构建请求体，最灵活的方式。

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

模板语法

• 使用 GJSON Template 语法，结合了 Go 模板和 GJSON 路径语法。
• 请求模板：
  • 访问配置值：{{.config.字段名}}
  • 访问工具参数：{{.args.参数名}}
• 响应模板：
  • 使用 GJSON 路径语法访问 JSON 响应字段。
  • 使用模板函数（如 add、upper、lower 等）。
  • 使用控制结构（如 if、range 等）。
• GJSON 路径语法：
  • 点表示法：address.city
  • 数组索引：users.0.name
  • 数组迭代：users.#.name
  • 数组过滤：users.#(age>=30)#.name
  • 修饰符：users.@reverse.#.name
  • 多路径：{name:users.0.name,count:users.#}
  • 转义字符：path.with\.dot

配置示例

使用内置 MCP Server 示例：配置 quark-search

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

基础配置示例：转换高德地图 API

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