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

请求参数传递策略

配置中支持四种互斥的参数传递方式，根据后端接口需求选择即可：

• 表单提交：argsToFormBody，自动添加 Content-Type: application/x-www-form-urlencoded。
• 查询参数：argsToUrlParam，将参数拼接到 URL 后面。
• JSON Body：argsToJsonBody，自动设置 application/json 头，适合大多数现代 API。
• 自定义 Body：body，最灵活的方式，手动构建请求体内容。

模板语法实战

Higress 使用 GJSON Template 语法，融合了 Go 模板与 GJSON 路径查找能力。

请求模板中：

• 访问配置值用 {{.config.字段名}}
• 访问工具参数用 {{.args.参数名}}

响应模板中：

• 利用 GJSON 路径提取 JSON 字段，如 address.city 或 users.0.name。
• 支持数组迭代 users.#.name 和过滤 users.#(age>=30)#.name。
• 可使用 if、range 等控制结构，以及 add、upper 等函数。

注意，当使用自定义 body 时，需要正确转义变量。例如：

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

这里使用了 toJson 函数来处理复杂对象，避免格式错误。

配置示例

1. 内置服务：Quark Search

如果是内置的 MCP 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
        argsToUrlParam: true
      responseTemplate:
        body: |
          {
            "lat": {{.response.results.0.location.lat}},
            "lng": {{.response.results.0.location.lng}}
          }

通过这个配置，AI Agent 就能直接调用这个工具获取地理位置信息，而无需关心底层 HTTP 协议的细节。这种配置化的方式极大地降低了集成成本，让任何 REST API 都能快速成为 AI 的能力扩展。