基于 Higress 将 REST API 转换为 MCP Server 实战指南

参数类型支持

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

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

请求参数传递策略

这四种方式是互斥的，根据后端接口需求选择最合适的一种：

1. argsToFormBody：参数以 application/x-www-form-urlencoded 编码，自动设置 Content-Type。
2. argsToUrlParam：参数作为查询参数追加到 URL 中，适合 GET 请求。
3. argsToJsonBody：参数直接转为 JSON 对象放入请求体，自动设置 Content-Type: application/json。
4. body：手动构建请求体，灵活性最高。可使用模板语法动态填充内容。

示例（手动构建 Body）：

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

响应转换模板

HTTP 响应需要经过转换才能被 AI 理解。使用 GJSON 路径语法访问返回的 JSON 字段，结合 Go 模板函数进行加工。

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

实战案例

1. 使用内置 MCP Server

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

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

2. 转换高德地图 API

下面是一个完整的配置示例，展示了如何定义参数、设置请求模板以及处理响应。注意 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

通过这种方式，任何 REST API 都可以通过简单的配置转换为 MCP Server，无需编写额外的代码逻辑。这不仅提高了开发效率，也让 AI Agent 能够灵活地调用各种数据源。