基于 Higress 将 REST API 转换为 MCP Server 实践

其中 args 支持多种数据类型，包括 string、number、integer、boolean、array 和 object。对于数组或对象类型，需配合 items 或 properties 字段定义结构。

请求参数传递方式

配置中支持四种互斥的参数传递方式，根据实际 API 需求选择：

1. 表单提交 (argsToFormBody)：自动设置 Content-Type: application/x-www-form-urlencoded。
2. 查询参数 (argsToUrlParam)：将参数追加到 URL 后。
3. JSON Body (argsToJsonBody)：自动设置 application/json，参数直接作为 JSON 对象发送。
4. 手动构建 (body)：灵活性最高，适合复杂场景。

# 示例：手动构建请求体
requestTemplate:
  body: |
    {
      "query": "{{.args.query}}",
      "filters": {{toJson .args.filters}},
      "options": { "limit": {{.args.limit}} }
    }

模板语法说明

Higress 使用 GJSON Template 语法，结合了 Go 模板与 GJSON 路径解析能力。

• 请求模板：可通过 {{.config.xxx}} 访问配置值，{{.args.xxx}} 访问工具参数。
• 响应模板：支持 GJSON 路径访问 JSON 字段，以及 add、upper 等函数和控制结构（if、range）。

常见 GJSON 路径用法：

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

配置实战示例

1. 内置 Server 配置

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

2. 高德地图 API 转换示例

将高德地理编码接口转换为 MCP 工具，支持地址转经纬度。

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 可用的数据源，无需编写额外的业务代码，显著提升了集成效率。