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

参数类型支持

为了精确控制 AI 输入，支持多种参数类型：

• string：字符串（默认）。
• number / integer：数字或整数。
• boolean：布尔值。
• array / object：复杂结构，需配合 items 或 properties 定义模式。

请求参数传递方式

这四种方式互斥，决定了参数如何拼接到 HTTP 请求中：

1. 表单提交 (argsToFormBody) 自动编码为 application/x-www-form-urlencoded。

   requestTemplate:
     argsToFormBody: true
   

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

   requestTemplate:
     argsToUrlParam: true
   

3. JSON Body (argsToJsonBody) 参数作为 JSON 对象发送，自动设置 Content-Type。

   requestTemplate:
     argsToJsonBody: true
   

4. 手动构建 (body) 最灵活的方式，适合复杂场景。

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

模板语法说明

Higress 结合了 Go Template 和 GJSON 路径语法，处理请求和响应非常强大。

• 访问配置：{{.config.字段名}}
• 访问参数：{{.args.参数名}}
• GJSON 路径：支持点表示法、数组索引、过滤器等。
  • 示例：users.#(age>=30)#.name

实战示例

1. 内置服务配置

直接使用内置的搜索服务：

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，显著提升开发效率。