使用 Higress 网关将 REST API 转换为 MCP Server 工具

参数类型支持

为了更精确地定义工具输入，支持多种数据类型：

• string：字符串（默认）
• number / integer：数字或整数
• boolean：布尔值
• array：数组，需配合 items 定义元素模式
• object：对象，需配合 properties 定义属性模式

请求参数传递方式

配置 requestTemplate 时，有四种互斥的参数传递策略，根据后端接口需求选择：

1. 表单提交 (argsToFormBody)：自动设置 Content-Type: application/x-www-form-urlencoded。
2. URL 查询参数 (argsToUrlParam)：将参数追加到 URL 后。
3. JSON 体 (argsToJsonBody)：自动设置 Content-Type: application/json，参数作为 JSON 对象发送。
4. 手动构建 (body)：最灵活，完全控制请求体内容。

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

模板语法

配置中广泛使用了 GJSON Template 语法，结合了 Go 模板与 GJSON 路径解析能力。

• 访问配置：{{.config.字段名}}
• 访问参数：{{.args.参数名}}
• 响应处理：支持 GJSON 路径（如 users.0.name）、控制结构（if, range）及函数（add, upper 等）。

实战配置示例

1. 使用内置 MCP Server

如果使用的是平台内置服务，配置非常简洁：

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

2. 转换高德地图 API

下面是一个将高德地理编码 API 转换为 MCP 工具的完整示例。注意 YAML 的缩进层级。

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 可用的工具，无需编写额外的胶水代码，显著提升开发效率。