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

参数类型支持

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

• string：字符串类型（默认）。
• number：数字类型（浮点数）。
• integer：整数类型。
• boolean：布尔类型（true/false）。
• array：数组类型，使用 items 字段定义数组元素的模式。
• object：对象类型，使用 properties 字段定义对象属性的模式。

请求参数传递方式

这里支持四种传递方式，它们是互斥的，根据实际 API 需求选择一种即可：

1. argsToFormBody：参数以 application/x-www-form-urlencoded 格式编码在请求体中，并自动添加相应的 Content-Type 头。

   requestTemplate:
     argsToFormBody: true
   

2. argsToUrlParam：参数作为查询参数添加到 URL 中。

   requestTemplate:
     argsToUrlParam: true
   

3. argsToJsonBody：参数直接作为 JSON 对象发送到请求体中，并自动添加 Content-Type: application/json; charset=utf-8 头。

   requestTemplate:
     argsToJsonBody: true
   

4. body：手动构建请求体，最灵活的方式。

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

模板语法

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

• 请求模板：
  • 访问配置值：{{.config.字段名}}
  • 访问工具参数：{{.args.参数名}}
• 响应模板：
  • 使用 GJSON 路径语法访问 JSON 响应字段。
  • 使用模板函数（如 add、upper、lower 等）。
  • 使用控制结构（如 if、range 等）。
• GJSON 路径语法示例：
  • 点表示法：address.city
  • 数组索引：users.0.name
  • 数组迭代：users.#.name
  • 数组过滤：users.#(age>=30)#.name
  • 修饰符：users.@reverse.#.name
  • 多路径：{name:users.0.name,count:users.#}
  • 转义字符：path.with\.dot

配置示例

使用内置 MCP Server 示例：配置 quark-search

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

基础配置示例：转换高德地图 API

下面是一个将高德地图地理编码 API 转换为 MCP 工具的完整 YAML 配置。注意 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

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