当前位置：首页 > news >正文

将现有 REST API 转换为 MCP Server工具 -higress

news 2025/7/6 3:09:12

Higress 是一款云原生 API 网关，集成了流量网关、微服务网关、安全网关和 AI 网关的功能。
它基于 Istio 和 Envoy 开发，支持使用 Go/Rust/JS 等语言编写 Wasm 插件。
提供了数十个通用插件和开箱即用的控制台。
Higress AI 网关支持多种 AI 服务提供商，如 OpenAI、DeepSeek、通义千问等，并具备令牌限流、消费者鉴权、WAF 防护、语义缓存等功能。

MCP Server 插件配置

higress

功能说明

mcp-server 插件基于 Model Context Protocol (MCP)，专为 AI 助手设计，定义了 AI 模型与外部工具和资源交互的标准方式。
功能特点：
1. 无需编写代码：将现有 REST API 转换为 AI 助手可调用的工具。
2. 统一认证、鉴权、限流和可观测性：利用 Higress 网关提供的能力，确保安全性和性能。
3. 快速构建和部署：通过 Higress 插件机制，快速添加新的 MCP Server。

运行属性

插件执行阶段：默认阶段
插件执行优先级：30

配置字段

Server 配置

字段名	数据类型	填写要求	默认值	描述
`server.name`	string	必填	-	MCP Server 的名称。如果是内置 MCP Server（如 quark-search），只需配置此字段；如果是 REST-to-MCP 场景，此字段可以自定义。
`server.config`	object	选填	`{}`	MCP Server 配置，如 API 密钥等。
`server.allowTools`	array of string	选填	-	允许调用的工具列表。如果不指定，则允许所有工具。

REST-to-MCP 工具配置

字段名	数据类型	填写要求	默认值	描述
`tools`	array of object	选填	`[]`	REST-to-MCP 工具配置列表。
`tools[].name`	string	必填	-	工具名称。
`tools[].description`	string	必填	-	工具功能描述。
`tools[].args`	array of object	必填	`[]`	工具参数定义。
`tools[].args[].name`	string	必填	-	参数名称。
`tools[].args[].description`	string	必填	-	参数描述。
`tools[].args[].type`	string	选填	`string`	参数类型（`string`、`number`、`integer`、`boolean`、`array`、`object`）。
`tools[].args[].required`	boolean	选填	`false`	参数是否必需。
`tools[].args[].default`	any	选填	-	参数默认值。
`tools[].args[].enum`	array	选填	-	参数允许的值列表。
`tools[].args[].items`	object	选填	-	数组项的模式（当 `type` 为 `array` 时）。
`tools[].args[].properties`	object	选填	-	对象属性的模式（当 `type` 为 `object` 时）。
`tools[].requestTemplate`	object	必填	-	HTTP 请求模板。
`tools[].requestTemplate.url`	string	必填	-	请求 URL 模板。
`tools[].requestTemplate.method`	string	必填	-	HTTP 方法（如 `GET`、`POST` 等）。
`tools[].requestTemplate.headers`	array of object	选填	`[]`	请求头模板。
`tools[].requestTemplate.headers[].key`	string	必填	-	请求头名称。
`tools[].requestTemplate.headers[].value`	string	必填	-	请求头值模板。
`tools[].requestTemplate.body`	string	选填	-	请求体模板（与 `argsToJsonBody`、`argsToUrlParam`、`argsToFormBody` 互斥）。
`tools[].requestTemplate.argsToJsonBody`	boolean	选填	`false`	参数直接作为 JSON 请求体（与 `body`、`argsToUrlParam`、`argsToFormBody` 互斥）。
`tools[].requestTemplate.argsToUrlParam`	boolean	选填	`false`	参数作为查询参数添加到 URL 中（与 `body`、`argsToJsonBody`、`argsToFormBody` 互斥）。
`tools[].requestTemplate.argsToFormBody`	boolean	选填	`false`	参数以 `application/x-www-form-urlencoded` 格式编码在请求体中（与 `body`、`argsToJsonBody`、`argsToUrlParam` 互斥）。
`tools[].responseTemplate`	object	必填	-	HTTP 响应转换模板。
`tools[].responseTemplate.body`	string	必填	-	响应体转换模板。

参数类型支持

支持多种参数类型，用于更精确地定义工具参数：
- string：字符串类型（默认）。
- number：数字类型（浮点数）。
- integer：整数类型。
- boolean：布尔类型（true/false）。
- array：数组类型，使用 items 字段定义数组元素的模式。
- object：对象类型，使用 properties 字段定义对象属性的模式。

请求参数传递方式

支持四种请求参数传递方式，这些选项是互斥的：
1. body：手动构建请求体，最灵活的方式。
```
requestTemplate:
  body: |
    {
      "query": "{{.args.query}}",
      "filters": {{toJson .args.filters}},
      "options": {
        "limit": {{.args.limit}}
      }
    }
```
2. argsToJsonBody：参数直接作为 JSON 对象发送到请求体中，并自动添加 Content-Type: application/json; charset=utf-8 头。
```
requestTemplate:
  argsToJsonBody: true
```
3. argsToUrlParam：参数作为查询参数添加到 URL 中。
```
requestTemplate:
  argsToUrlParam: true
```
4. argsToFormBody：参数以 application/x-www-form-urlencoded 格式编码在请求体中，并自动添加相应的 Content-Type 头。
```
requestTemplate:
  argsToFormBody: true
```

模板语法

使用 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

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