mirror of
https://github.com/alibaba/higress.git
synced 2026-06-09 12:47:28 +08:00
support rest to mcp (#1988)
This commit is contained in:
澄潭
GitHub
@@ -175,6 +175,184 @@ func init() {
|
||||
|
||||
all-in-one 插件的配置方式与所有 MCP server 插件都是一样的，都是通过 server 配置中的 name 字段来找到对应的 MCP server。
|
||||
|
||||
## REST-to-MCP 配置
|
||||
|
||||
Higress 支持一种特殊的 REST-to-MCP 配置，允许您无需编写任何代码即可将 REST API 转换为 MCP 工具。这对于快速将现有 REST API 与 AI 助手集成非常有用。
|
||||
|
||||
### 配置格式
|
||||
|
||||
要使用 REST-to-MCP 功能，您需要在插件配置中定义您的工具：
|
||||
|
||||
```yaml
|
||||
server:
|
||||
name: rest-amap-server
|
||||
config:
|
||||
apiKey: 您的API密钥
|
||||
tools:
|
||||
- name: maps-geo
|
||||
description: "将详细的结构化地址转换为经纬度坐标。支持对地标性名胜景区、建筑物名称解析为经纬度坐标"
|
||||
args:
|
||||
- name: address
|
||||
description: "待解析的结构化地址信息"
|
||||
required: true
|
||||
- name: city
|
||||
description: "指定查询的城市"
|
||||
required: false
|
||||
requestTemplate:
|
||||
url: "https://restapi.amap.com/v3/geocode/geo?key={{.config.apiKey}}&address={{.args.address}}&city={{.args.city}}&source=ts_mcp"
|
||||
method: GET
|
||||
headers:
|
||||
- key: x-api-key
|
||||
value: "{{.config.apiKey}}"
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
responseTemplate:
|
||||
body: |
|
||||
# 地理编码信息
|
||||
{{- range $index, $geo := .Geocodes }}
|
||||
## 地点 {{add $index 1}}
|
||||
|
||||
- **国家**: {{ $geo.Country }}
|
||||
- **省份**: {{ $geo.Province }}
|
||||
- **城市**: {{ $geo.City }}
|
||||
- **城市代码**: {{ $geo.Citycode }}
|
||||
- **区/县**: {{ $geo.District }}
|
||||
- **街道**: {{ $geo.Street }}
|
||||
- **门牌号**: {{ $geo.Number }}
|
||||
- **行政编码**: {{ $geo.Adcode }}
|
||||
- **坐标**: {{ $geo.Location }}
|
||||
- **级别**: {{ $geo.Level }}
|
||||
{{- end }}
|
||||
```
|
||||
|
||||
### 模板语法
|
||||
|
||||
REST-to-MCP 功能使用 [GJSON Template](https://github.com/higress-group/gjson_template) 库进行模板渲染，该库结合了 Go 的模板语法和 GJSON 的强大路径语法：
|
||||
|
||||
- **请求模板**：用于构造 HTTP 请求 URL、头部和正文
|
||||
- 使用 `.config.fieldName` 访问配置值
|
||||
- 使用 `.args.argName` 访问工具参数
|
||||
|
||||
- **响应模板**：用于将 HTTP 响应转换为适合 AI 消费的格式
|
||||
- 使用 GJSON 路径语法访问 JSON 响应字段
|
||||
- 使用模板函数如 `add`、`upper`、`lower` 等
|
||||
- 使用控制结构如 `if`、`range` 等
|
||||
|
||||
GJSON Template 包含了所有 [Sprig](https://github.com/Masterminds/sprig) 的函数，提供了超过 70 个用于字符串操作、数学运算、日期格式化、列表处理等的模板函数。这使得 GJSON Template 在功能上等同于 Helm 的模板能力。
|
||||
|
||||
一些常用的 Sprig 函数包括：
|
||||
|
||||
- **字符串操作**：`trim`、`upper`、`lower`、`replace`、`plural`、`nospace`
|
||||
- **数学运算**：`add`、`sub`、`mul`、`div`、`max`、`min`
|
||||
- **日期格式化**：`now`、`date`、`dateInZone`、`dateModify`
|
||||
- **列表操作**：`list`、`first`、`last`、`uniq`、`sortAlpha`
|
||||
- **字典操作**：`dict`、`get`、`set`、`hasKey`、`pluck`
|
||||
- **流程控制**：`ternary`、`default`、`empty`、`coalesce`
|
||||
- **类型转换**：`toString`、`toJson`、`toPrettyJson`、`toRawJson`
|
||||
- **编码/解码**：`b64enc`、`b64dec`、`urlquery`、`urlqueryescape`
|
||||
- **UUID 生成**：`uuidv4`
|
||||
|
||||
有关所有可用函数的完整参考，请参阅 [Helm 函数文档](https://helm.sh/docs/chart_template_guide/function_list/)，因为 GJSON Template 包含了相同的函数集。
|
||||
|
||||
### GJSON 路径语法
|
||||
|
||||
GJSON Template 支持完整的 GJSON 路径语法，提供强大的 JSON 查询能力：
|
||||
|
||||
- **点表示法**：`address.city`
|
||||
- **数组索引**：`users.0.name`
|
||||
- **数组迭代**：`users.#.name`
|
||||
- **通配符**：`users.*.name`
|
||||
- **数组过滤**：`users.#(age>=30)#.name`
|
||||
- **修饰符**：`users.@reverse.#.name`
|
||||
- **多路径**：`{name:users.0.name,count:users.#}`
|
||||
- **转义字符**：`path.with\.dot`
|
||||
|
||||
对于更复杂的查询，您可以在模板中直接使用 `gjson` 函数：
|
||||
|
||||
```
|
||||
<!-- 使用 gjson 函数进行复杂查询 -->
|
||||
活跃用户: {{gjson "users.#(active==true)#.name"}}
|
||||
|
||||
<!-- 带有多个条件的数组过滤 -->
|
||||
30岁以上的活跃开发者: {{gjson "users.#(active==true && age>30)#.name"}}
|
||||
|
||||
<!-- 使用修饰符 -->
|
||||
用户名（倒序）: {{gjson "users.@reverse.#.name"}}
|
||||
|
||||
<!-- 迭代过滤结果 -->
|
||||
管理员:
|
||||
{{range $user := gjson "users.#(roles.#(==admin)>0)#"}}
|
||||
- {{$user.name}} ({{$user.age}})
|
||||
{{end}}
|
||||
```
|
||||
|
||||
有关 GJSON 路径语法的完整参考，请参阅 [GJSON 文档](https://github.com/tidwall/gjson#path-syntax)。
|
||||
|
||||
### AI 提示词生成模板
|
||||
|
||||
在与 AI 助手一起生成 REST-to-MCP 配置的模板时，您可以使用以下提示词：
|
||||
|
||||
```
|
||||
请帮我创建一个 Higress 的 REST-to-MCP 配置，将 REST API 转换为 MCP 工具。配置应遵循以下格式：
|
||||
|
||||
```yaml
|
||||
server:
|
||||
name: rest-api-server
|
||||
config:
|
||||
apiKey: 您的API密钥
|
||||
tools:
|
||||
- name: tool-name
|
||||
description: "详细描述这个工具的功能"
|
||||
args:
|
||||
- name: arg1
|
||||
description: "参数1的描述"
|
||||
required: true
|
||||
- name: arg2
|
||||
description: "参数2的描述"
|
||||
required: false
|
||||
default: "默认值"
|
||||
requestTemplate:
|
||||
url: "https://api.example.com/endpoint?key={{.config.apiKey}}¶m={{.args.arg1}}"
|
||||
method: GET
|
||||
headers:
|
||||
- key: x-api-key
|
||||
value: "{{.config.apiKey}}"
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
body: |
|
||||
{
|
||||
"param1": "{{.args.arg1}}",
|
||||
"param2": "{{.args.arg2}}"
|
||||
}
|
||||
responseTemplate:
|
||||
body: |
|
||||
# 结果
|
||||
{{- range $index, $item := .items }}
|
||||
## 项目 {{add $index 1}}
|
||||
- **名称**: {{ $item.name }}
|
||||
- **值**: {{ $item.value }}
|
||||
{{- end }}
|
||||
```
|
||||
|
||||
我想转换的 REST API 是 [在此描述您的 API，包括端点、参数和响应格式]。
|
||||
|
||||
请生成一个完整的配置，包括：
|
||||
1. 具有描述性名称和适当的服务器配置
|
||||
2. 定义所有必要的参数，并提供清晰的描述和适当的必填/默认值
|
||||
3. 创建正确格式化 API 请求的 requestTemplate，包括带有模板值的头部
|
||||
4. 创建将 API 响应转换为适合 AI 消费的可读格式的 responseTemplate
|
||||
|
||||
模板使用 GJSON Template 语法 (https://github.com/higress-group/gjson_template)，该语法结合了 Go 模板和 GJSON 路径语法进行 JSON 处理。模板引擎支持：
|
||||
|
||||
1. 基本点表示法访问字段：{{.fieldName}}
|
||||
2. 用于复杂查询的 gjson 函数：{{gjson "users.#(active==true)#.name"}}
|
||||
3. 所有 Sprig 模板函数（类似 Helm）：{{add}}、{{upper}}、{{lower}}、{{date}} 等
|
||||
4. 控制结构：{{if}}、{{range}}、{{with}} 等
|
||||
5. 变量赋值：{{$var := .value}}
|
||||
|
||||
对于复杂的 JSON 响应，请考虑使用 GJSON 强大的过滤和查询能力来提取和格式化最相关的信息。
|
||||
```
|
||||
|
||||
## 主入口点
|
||||
|
||||
main.go 文件是 MCP 服务器的入口点。它注册工具和资源：
|
||||
@@ -303,4 +481,3 @@ func TestMyToolInputSchema(t *testing.T) {
|
||||
t.Error("InputSchema 返回了空 schema")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user