MCP Server 插件配置

server:
  name: my-api-server
  securitySchemes:
  - id: MyBasicAuth
    type: http
    scheme: basic
    defaultCredential: "admin:secretpassword" # 默认的用户名和密码
  - id: MyBearerToken
    type: http
    scheme: bearer
    defaultCredential: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." # 默认的Bearer Token
  - id: MyApiKeyInHeader
    type: apiKey
    in: header
    name: X-Custom-API-Key # API Key 在名为 X-Custom-API-Key 的 Header 中
    defaultCredential: "abcdef123456" # 默认的 API Key
  - id: MyApiKeyInQuery
    type: apiKey
    in: query
    name: "api_token" # API Key 在名为 api_token 的查询参数中
    defaultCredential: "uvwxyz789012"

tools:
- name: get-user-details
  # ... 其他工具配置 ...
  requestTemplate:
    url: "https://api.example.com/users/{{.args.userId}}"
    method: GET
    security:
      id: MyBearerToken # 使用上面定义的 MyBearerToken 方案
      # credential: "override_token_for_this_tool" # 可选：为此工具覆盖默认Token
# ...
- name: update-inventory
  # ... 其他工具配置 ...
  requestTemplate:
    url: "https://api.example.com/inventory/{{.args.itemId}}"
    method: POST
    security:
      id: MyApiKeyInHeader # 使用 MyApiKeyInHeader 方案
      # 此工具将使用 MyApiKeyInHeader 中定义的 defaultCredential

server:
  name: product-api-server
  securitySchemes:
  - id: ClientSideBearer # 客户端使用Bearer Token
    type: http
    scheme: bearer
  - id: BackendApiKey    # 后端API使用X-API-Key
    type: apiKey
    in: header
    name: X-API-Key
    # defaultCredential: "optional_default_backend_key"

tools:
- name: get-product-securely
  description: "获取产品信息（安全透传）"
  security: # 客户端 -> MCP Server 认证配置
    id: ClientSideBearer # MCP Server期望客户端使用此方案，并会尝试提取此类型的凭证
    passthrough: true   # 启用透传
  args:
  - name: product_id
    description: "产品ID"
    type: string
    required: true
  requestTemplate:
    security: # MCP Server -> 后端 REST API 认证配置
      id: BackendApiKey # 后端API需要此方案。透传的凭证将按此方案应用。
    url: "https://api.example.com/products/{{.args.product_id}}"
    method: GET

args:
- name: query
  description: "搜索关键词"
  type: string
  required: true
- name: limit
  description: "返回结果数量"
  type: integer
  default: 10
- name: filters
  description: "过滤条件"
  type: object
  properties:
    category:
      type: string
      enum: ["food", "hotel", "attraction"]
    price:
      type: integer
      minimum: 0
- name: coordinates
  description: "坐标点列表"
  type: array
  items:
    type: object
    properties:
      lat:
        type: number
      lng:
        type: number

args:
- name: petId
  description: "宠物ID"
  type: string
  required: true
  position: path
- name: token
  description: "认证令牌"
  type: string
  required: true
  position: header
- name: sessionId
  description: "会话ID"
  type: string
  position: cookie
- name: limit
  description: "返回结果数量"
  type: integer
  default: 10
  position: query
- name: tags
  description: "标签列表"
  type: array
  position: body

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

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

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
    headers:
    - key: x-api-key
      value: "{{.config.apiKey}}"
  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 }}

server:
  name: weather-api-server
  config:
    apiKey: your-weather-api-key
tools:
- name: get-weather
  description: "获取指定城市的天气预报信息"
  args:
  - name: city
    description: "城市名称"
    type: string
    required: true
  - name: days
    description: "天数(1-7)"
    type: integer
    required: false
    default: 3
  - name: include_hourly
    description: "是否包含每小时预报"
    type: boolean
    default: true
  requestTemplate:
    url: "https://api.weatherapi.com/v1/forecast.json"
    method: GET
    argsToUrlParam: true
    headers:
    - key: x-api-key
      value: "{{.config.apiKey}}"
  responseTemplate:
    body: |
      # {{.location.name}}, {{.location.country}} 天气预报

      **当前温度**: {{.current.temp_c}}°C
      **体感温度**: {{.current.feelslike_c}}°C
      **天气状况**: {{.current.condition.text}}
      **湿度**: {{.current.humidity}}%
      **风速**: {{.current.wind_kph}} km/h

      ## 未来预报
      {{range $index, $day := .forecast.forecastday}}
      ### {{$day.date}} ({{dateFormat "Monday" $day.date_epoch | title}})

      {{if gt $day.day.maxtemp_c 30}}**高温预警!**{{end}}
      {{if lt $day.day.mintemp_c 0}}**低温预警!**{{end}}

      - **最高温度**: {{$day.day.maxtemp_c}}°C
      - **最低温度**: {{$day.day.mintemp_c}}°C
      - **降水概率**: {{$day.day.daily_chance_of_rain}}%
      - **天气状况**: {{$day.day.condition.text}}

      #### 分时预报
      {{range $hour := slice $day.hour 6 24 3}}
      - **{{dateFormat "15:04" $hour.time_epoch}}**: {{$hour.temp_c}}°C, {{$hour.condition.text}}
      {{end}}
      {{end}}

server:
  name: product-api-server
  config:
    apiKey: your-api-key-here
tools:
- name: get-product
  description: "获取产品详细信息"
  args:
  - name: product_id
    description: "产品ID"
    type: string
    required: true
  requestTemplate:
    url: "https://api.example.com/products/{{.args.product_id}}"
    method: GET
    headers:
    - key: Authorization
      value: "Bearer {{.config.apiKey}}"
  responseTemplate:
    prependBody: |
      # 产品信息

      以下是产品的详细信息，以JSON格式返回。字段说明：

      - **id**: 产品唯一标识符
      - **name**: 产品名称
      - **description**: 产品描述
      - **price**: 产品价格（美元）
      - **category**: 产品类别
      - **inventory**: 库存信息
        - **quantity**: 当前库存数量
        - **warehouse**: 仓库位置
      - **ratings**: 用户评分列表
        - **score**: 评分（1-5）
        - **comment**: 评论内容

      原始JSON响应：

    appendBody: |

      您可以使用这些信息来了解产品的详细信息、价格、库存状态和用户评价。

请帮我创建一个 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的描述"
    type: string  # 可选类型: string, number, integer, boolean, array, object
    required: true
    position: path  # 可选位置: query, path, header, cookie, body
  - name: arg2
    description: "参数2的描述"
    type: integer
    required: false
    default: 10
    position: query
  - name: arg3
    description: "参数3的描述"
    type: array
    items:
      type: string
    position: body
  - name: arg4
    description: "参数4的描述"
    type: object
    properties:
      subfield1:
        type: string
      subfield2:
        type: number
    # 未指定position，将根据argsToJsonBody/argsToUrlParam/argsToFormBody处理
  requestTemplate:
    url: "https://api.example.com/endpoint"
    method: POST
    # 以下四个选项互斥，只能选择其中一种
    argsToUrlParam: true  # 将参数添加到URL查询参数
    # 或者
    # argsToJsonBody: true  # 将参数作为JSON对象发送到请求体
    # 或者
    # argsToFormBody: true  # 将参数以表单编码发送到请求体
    # 或者
    # body: |  # 手动构建请求体
    #   {
    #     "param1": "{{.args.arg1}}",
    #     "param2": {{.args.arg2}},
    #     "complex": {{toJson .args.arg4}}
    #   }
    headers:
    - key: x-api-key
      value: "{{.config.apiKey}}"
  responseTemplate:
    # 以下三个选项互斥，只能选择其中一种
    body: |
      # 结果
      {{- range $index, $item := .items }}
      ## 项目 {{add $index 1}}
      - **名称**: {{ $item.name }}
      - **值**: {{ $item.value }}
      {{- end }}
    # 或者
    # prependBody: |
    #   # API响应说明
    #
    #   以下是原始JSON响应，字段含义如下：
    #   - field1: 字段1的含义
    #   - field2: 字段2的含义
    #
    # appendBody: |
    #
    #   您可以使用这些数据来...

请根据以上信息生成一个完整的配置，包括：
1. 具有描述性名称和适当的服务器配置
2. 定义所有必要的参数，并提供清晰的描述和适当的类型、必填/默认值
3. 选择合适的参数传递方式（argsToUrlParam、argsToJsonBody、argsToFormBody 或自定义 body）
4. 创建将 API 响应转换为适合 AI 消费的可读格式的 responseTemplate