MCP Server 插件配置

x-envoy-allow-mcp-tools: tool1,tool2,tool3

// 正确的方式：使用 ReplaceHttpRequestHeader
// 这会覆盖用户可能传入的任何值，确保安全性
proxywasm.ReplaceHttpRequestHeader("x-envoy-allow-mcp-tools", "tool1,tool2,tool3")

// ❌ 错误的方式：使用 AddHttpRequestHeader
// 这可能导致用户传入的值被保留，造成安全隐患
proxywasm.AddHttpRequestHeader("x-envoy-allow-mcp-tools", "tool1,tool2,tool3")

server:
  name: my-mcp-proxy
  type: mcp-proxy
  transport: http
  mcpServerURL: "http://backend-mcp.example.com/mcp"

server:
  name: my-sse-proxy
  type: mcp-proxy
  transport: sse
  mcpServerURL: "http://backend-mcp.example.com"
  timeout: 10000  # SSE 可能需要更长的超时时间

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: my-mcpserver-proxy
  type: mcp-proxy
  transport: http  # 使用 StreamableHTTP 协议
  mcpServerURL: "http://backend-mcp.example.com/mcp"
  timeout: 5000
  defaultDownstreamSecurity: # 客户端到网关的默认认证
    id: ClientApiKey
  defaultUpstreamSecurity: # 网关到后端的默认认证
    id: BackendApiKey
  securitySchemes:
  - id: ClientApiKey
    type: apiKey
    in: header
    name: X-Client-API-Key
  - id: BackendApiKey
    type: apiKey
    in: header
    name: X-Backend-API-Key
    defaultCredential: "backend-secret-key"

tools:
- name: get-secure-product
  description: "获取安全产品信息"
  args:
  - name: product_id
    description: "产品ID"
    type: string
    required: true
  requestTemplate:
    security: # 工具级别的网关到后端认证，覆盖默认配置
      id: BackendApiKey
      credential: "special-key-for-this-tool"

server:
  name: my-sse-mcpserver-proxy
  type: mcp-proxy
  transport: sse  # 使用 SSE 协议
  mcpServerURL: "http://backend-mcp.example.com"
  timeout: 10000  # SSE 连接可能需要更长的超时时间
  defaultDownstreamSecurity:
    id: ClientBearer
  defaultUpstreamSecurity:
    id: BackendBearer
  securitySchemes:
  - id: ClientBearer
    type: http
    scheme: bearer
  - id: BackendBearer
    type: http
    scheme: bearer

allowTools:
- weather-tool
- news-tool

server:
  name: my-secure-proxy
  type: mcp-proxy
  mcpServerURL: "https://api.backend-mcp.com/v1/mcp"
  timeout: 10000
  defaultDownstreamSecurity: # 默认要求客户端提供 Bearer Token
    id: ClientBearer
    passthrough: true # 启用透明认证
  defaultUpstreamSecurity: # 默认使用透传的凭证调用后端
    id: BackendBearer
  securitySchemes:
  - id: ClientBearer # 客户端使用 Bearer Token
    type: http
    scheme: bearer
  - id: BackendBearer # 后端也使用 Bearer Token
    type: http
    scheme: bearer
  - id: AdminApiKey # 管理员工具使用特殊 API Key
    type: apiKey
    in: header
    name: X-Admin-Key
    defaultCredential: "admin-secret-key"

tools:
- name: get-user-data
  description: "获取用户数据（使用透传认证）"
  args:
  - name: user_id
    description: "用户ID"
    type: string
    required: true
  # 此工具使用默认的透传认证，客户端的 Bearer Token 会传递给后端

- name: admin-operation
  description: "执行管理员操作（使用特殊认证）"
  security: # 工具级别客户端认证：仍要求客户端提供 Bearer Token
    id: ClientBearer
    passthrough: false # 不透传客户端凭证
  args:
  - name: operation
    description: "操作类型"
    type: string
    required: true
  requestTemplate:
    security: # 工具级别后端认证：使用管理员 API Key
      id: AdminApiKey

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: |

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

server:
  config:
    appCode: ""
  name: "银行卡二三四要素"
tools:
- args:
  - description: "银行卡号"
    name: "cardno"
    position: "query"
    required: true
    type: "string"
  - description: "姓名（注意UrlEncode编码）"
    name: "name"
    position: "query"
    required: false
    type: "string"
  - description: "预留手机号"
    name: "mobile"
    position: "query"
    required: false
    type: "string"
  - description: "身份证号码"
    name: "idcard"
    position: "query"
    required: false
    type: "string"
  description: "验证卡号、姓名、手机号、证件号是否一致"
  errorResponseTemplate: |-
    statusCode: {{gjson "_headers.\\:status"}}
    errorCode: {{gjson "_headers.x-ca-error-code"}}
    data: {{.data.value}}
  name: "银行卡二三四要素验证"
  requestTemplate:
    argsToFormBody: false
    argsToJsonBody: false
    argsToUrlParam: true
    method: "GET"
    url: "https://ckid.market.alicloudapi.com/lundear/verifyBank"
  responseTemplate:
    appendBody: |2-
        - 以下是返回参数说明
        - 参数名称: code, 参数类型: integer, 参数描述: 响应状态码
        - 参数名称: desc, 参数类型: string, 参数描述: 描述信息
        - 参数名称: data, 参数类型: object, 参数描述: 无描述
        - 参数名称: data.bankId, 参数类型: string, 参数描述: 银行编码
        - 参数名称: data.bankName, 参数类型: string, 参数描述: 银行名称
        - 参数名称: data.abbr, 参数类型: string, 参数描述: 银行英文缩写
        - 参数名称: data.cardName, 参数类型: string, 参数描述: 卡名称
        - 参数名称: data.cardType, 参数类型: string, 参数描述: 卡类型
        - 参数名称: data.cardBin, 参数类型: string, 参数描述: 卡bin
        - 参数名称: data.binLen, 参数类型: integer, 参数描述: 卡bin长度
        - 参数名称: data.area, 参数类型: string, 参数描述: 卡所在地区
        - 参数名称: data.bankPhone, 参数类型: string, 参数描述: 银行电话
        - 参数名称: data.bankUrl, 参数类型: string, 参数描述: 银行网址
        - 参数名称: data.bankLogo, 参数类型: string, 参数描述: 银行logo

请帮我创建一个 Higress 的 MCP 服务器配置。支持两种类型：
1. **REST-to-MCP 服务器**：将 REST API 转换为 MCP 工具
2. **MCP 代理服务器**：代理到后端 MCP 服务器

## 配置格式

### REST-to-MCP 服务器配置

```yaml
server:
  name: rest-api-server
  type: rest  # 可选，默认为 rest
  config:
    apiKey: 您的API密钥
  # 服务器级别默认认证（可选）
  defaultDownstreamSecurity:
    id: ClientAuth
  defaultUpstreamSecurity:
    id: BackendAuth
  securitySchemes:
  - id: ClientAuth
    type: http
    scheme: bearer
  - id: BackendAuth
    type: apiKey
    in: header
    name: X-API-Key
    defaultCredential: 您的后端API密钥
tools:
- name: tool-name
  description: "详细描述这个工具的功能"
  security: # 工具级别客户端认证（可选，覆盖服务器默认）
    id: ClientAuth
    passthrough: true  # 启用透明认证
  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
  requestTemplate:
    url: "https://api.example.com/endpoint"
    method: POST
    security: # 工具级别后端认证（可选，覆盖服务器默认）
      id: BackendAuth
      credential: "特定工具的凭证"  # 可选，覆盖默认凭证
    # 以下四个选项互斥，只能选择其中一种
    argsToUrlParam: true  # 将参数添加到URL查询参数
    # 或者其他选项...
    headers:
    - key: x-api-key
      value: "{{.config.apiKey}}"
  responseTemplate:
    body: |
      # 结果
      {{- range $index, $item := .items }}
      ## 项目 {{add $index 1}}
      - **名称**: {{ $item.name }}
      - **值**: {{ $item.value }}
      {{- end }}

server:
  name: mcp-proxy-server
  type: mcp-proxy
  transport: http  # StreamableHTTP 协议
  mcpServerURL: "http://backend-mcp.example.com/mcp"  # 后端 MCP 服务器 URL
  timeout: 5000  # 超时时间（毫秒）
  # 服务器级别默认认证（推荐配置）
  defaultDownstreamSecurity:  # 客户端到网关认证
    id: ClientAuth
    passthrough: true  # 启用透明认证
  defaultUpstreamSecurity:   # 网关到后端认证
    id: BackendAuth
  securitySchemes:
  - id: ClientAuth
    type: http
    scheme: bearer
  - id: BackendAuth
    type: apiKey
    in: header
    name: X-Backend-Key
    defaultCredential: "后端服务密钥"

# 对于 MCP 代理，tools 配置是可选的
# 如果配置了 tools，则只有列出的工具可用
# 如果不配置 tools，则代理所有后端 MCP 服务器的工具
tools:
- name: specific-tool
  description: "特定工具的配置（可选）"
  security: # 覆盖默认的客户端认证
    id: ClientAuth
    passthrough: false  # 不透传
  args:
  - name: param1
    description: "参数描述"
    type: string
    required: true
  requestTemplate:
    security: # 覆盖默认的后端认证
      id: BackendAuth
      credential: "特定工具的后端凭证"

server:
  name: mcp-sse-proxy-server
  type: mcp-proxy
  transport: sse  # SSE 协议
  mcpServerURL: "http://backend-mcp.example.com"  # 后端 MCP 服务器基础 URL
  timeout: 10000  # SSE 通常需要更长的超时时间
  # 服务器级别默认认证
  defaultDownstreamSecurity:
    id: ClientBearer
  defaultUpstreamSecurity:
    id: BackendBearer
  securitySchemes:
  - id: ClientBearer
    type: http
    scheme: bearer
  - id: BackendBearer
    type: http
    scheme: bearer
    defaultCredential: "后端Bearer Token"

# 可选：限制允许的工具
allowTools:
- tool1
- tool2

## 生成要求

请根据以上信息生成一个完整的配置，包括：

### 对于 REST-to-MCP 服务器：
1. 具有描述性名称和适当的服务器配置
2. 定义所有必要的参数，并提供清晰的描述和适当的类型、必填/默认值
3. 选择合适的参数传递方式（argsToUrlParam、argsToJsonBody、argsToFormBody 或自定义 body）
4. 创建将 API 响应转换为适合 AI 消费的可读格式的 responseTemplate
5. 配置适当的认证方案和安全配置

### 对于 MCP 代理服务器：
1. 选择合适的传输协议（`http` 用于 StreamableHTTP，`sse` 用于 SSE）
2. 配置后端 MCP 服务器 URL 和超时时间（SSE 建议使用更长的超时时间）
3. 设置服务器级别的默认认证配置
4. 根据需要配置透明认证
5. 配置 `allowTools` 以限制可用工具（可选）
6. 如有特殊需求，配置特定工具的认证覆盖
7. 确保客户端到网关和网关到后端的认证链路完整