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

参数类型支持

为了更精确地定义工具参数，支持以下类型：

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

请求参数传递方式

支持四种互斥的传递方式，决定了参数如何拼接到 HTTP 请求中：

1. JSON Body (argsToJsonBody: true)：参数直接作为 JSON 对象发送到请求体，自动设置 Content-Type: application/json。
2. URL Params (argsToUrlParam: true)：参数作为查询参数添加到 URL 中。
3. Form Body (argsToFormBody: true)：参数以 application/x-www-form-urlencoded 格式编码，自动设置对应 Header。
4. Custom Body (body)：手动构建请求体，灵活性最高，适合复杂场景。

模板语法

配置中使用 GJSON Template 语法，结合了 Go 模板和 GJSON 路径语法。

• 访问配置：{{.config.字段名}}
• 访问参数：{{.args.参数名}}
• 响应处理：使用 GJSON 路径访问 JSON 字段，支持控制结构（if, range）和函数（add, upper 等）。

常用 GJSON 路径示例：

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

配置示例

1. 使用内置 MCP Server

如果直接使用 Higress 内置的服务（如搜索），配置非常简单：

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

2. 转换高德地图 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
        argsToUrlParam: true

通过 MCP Server，你可以快速为 AI Agent 添加各种数据源支持。任何 REST API 都可以通过简单的配置转换为 MCP Server，无需编写额外的代码，显著提升开发效率。