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

参数定义细节

每个工具参数都需要明确类型和行为。支持的类型包括 string、number、integer、boolean、array 和 object。对于数组或对象类型，需进一步定义 items 或 properties 模式。

请求参数传递方式

这里有四种互斥的方式，决定了参数如何进入 HTTP 请求：

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

例如，使用手动构建时，可以这样写：

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

模板语法说明

配置中大量使用了模板引擎来动态填充数据。它结合了 Go Template 和 GJSON 路径语法。

• 访问配置值：使用 {{.config.字段名}}
• 访问工具参数：使用 {{.args.参数名}}
• GJSON 路径：用于解析 JSON 响应，支持点表示法、数组索引、迭代和过滤。

例如，访问用户列表中的第一个名字：users.0.name。如果需要获取所有年龄大于 30 的用户姓名：users.#(age>=30)#.name。

配置示例

内置 Server 示例

配置一个简单的内置搜索服务：

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

REST 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 可用的工具，无需修改原有后端代码，极大提升了开发效率。