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

参数定义细节

每个参数 (args) 包含以下关键属性：

• name: 参数名称。
• description: 参数描述。
• type: 类型（string, number, integer, boolean, array, object）。默认为 string。
• required: 是否必需。默认为 false。
• default: 默认值。
• enum: 允许的值列表。
• items / properties: 用于定义 array 或 object 类型的子结构。

请求参数传递方式

支持四种互斥的传递方式，根据目标 API 的要求选择：

1. argsToFormBody：参数以 application/x-www-form-urlencoded 格式编码，自动设置 Content-Type。

   requestTemplate:
     argsToFormBody: true
   

2. argsToUrlParam：参数作为查询参数追加到 URL 中。

   requestTemplate:
     argsToUrlParam: true
   

3. argsToJsonBody：参数直接作为 JSON 对象发送到请求体，自动设置 Content-Type: application/json; charset=utf-8。

   requestTemplate:
     argsToJsonBody: true
   

4. body：手动构建请求体，灵活性最高。

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

模板语法

配置中使用 GJSON Template 语法，结合了 Go 模板和 GJSON 路径语法，非常强大。

• 访问配置值：{{.config.字段名}}
• 访问工具参数：{{.args.参数名}}
• 响应处理：使用 GJSON 路径访问 JSON 字段，配合模板函数（如 add, upper）和控制结构（if, range）。

GJSON 路径示例：

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

配置实战

场景一：使用内置 MCP Server

如果直接使用 Higress 内置的服务（如搜索），配置非常简单：

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

场景二：转换高德地图 API

这是一个典型的 REST-to-MCP 案例，将地理编码服务暴露给 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 可用的工具，显著提升开发效率。