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

请求体构建策略

支持四种互斥的请求参数传递方式，根据实际接口需求选择：

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

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

3. JSON Body (argsToJsonBody) 参数作为 JSON 对象发送，自动添加 Content-Type: application/json。

4. 自定义 Body (body) 最灵活的方式，手动构建请求体内容。

requestTemplate:
  url: "https://restapi.amap.com/v3/geocode/geo"
  method: GET
  argsToUrlParam: 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 等函数或 if, range 控制结构。

GJSON 路径示例：

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

配置示例

1. 内置服务配置

如果是内置的 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

通过这种方式，任何 REST API 都可以被快速封装成 AI Agent 可用的工具，无需编写额外的后端代码，极大地提升了开发效率。