工具接入

1.1 插件与工具

平台的能力接入使用两层模型：

关系：一个插件包含一个或多个工具。插件负责连接层（URL、认证、协议），工具负责能力层（参数、返回值、调用逻辑）。

插件 Plugin（天气服务）
├── 工具 Tool（查询实时天气）
├── 工具 Tool（查询 7 天预报）
└── 工具 Tool（查询空气质量）

1.2 编码规则

1.3 生命周期

插件遵循「草稿 → 已发布」的生命周期：

草稿(DRAFT) ──────发布─────▶ 已发布(PUBLISHED)

• 草稿（DRAFT）：可自由编辑、调试。

• 已发布（PUBLISHED）：已发布插件会进入锁定状态，暂不可修改，避免影响线上Skill

工具遵循「草稿 → 调试通过 → 已发布」的生命周期：

草稿(DRAFT) ──────调试通过(DEBUGGING_PASSED)── 发布───▶ 已发布(PUBLISHED)
   ▲                         │            											
   │                         │            											
   └─────── 更新 ◀────────────┘

• 草稿（DRAFT）：可自由编辑、调试。

• 调试通过（DEBUGGING_PASSED）：工具调试通过一次状态自动更新；可自由编辑、调试。

• 已发布（PUBLISHED）：已发布工具会进入锁定状态，暂不可修改，避免影响线上Skill

• 工具状态跟随插件状态联动，发布后同样锁定。

• SKILL发布上线时，其引用的所有工具都必须处于已发布。

2.1 能力边界速查

4.1 创建 OpenAPI 插件

新建插件时需要填写以下字段：

4.2 认证方式（AuthInfo）

认证配置作用于插件级别，插件下所有工具共享。

4.3 插件级公共参数与密钥参数

OpenAPI 插件支持两类插件级配置，均在插件的 config.openApi 下：

公共参数 publicParameters：所有工具共享的参数（如 appKey、时间戳、签名），会自动应用到该插件下每个工具的请求。

{
  "config": {
    "openApi": {
      "publicParameters": [
        { "name": "app_key", "type": "string", "position": "query", "from": "constant", "defaultValue": "your-app-key" },
        { "name": "timestamp", "type": "string", "position": "query", "from": "gop_shortcut", "gopShortcut": "timestamp" },
        { "name": "nonce", "type": "string", "position": "query", "from": "gop_shortcut", "gopShortcut": "random_string32" }
      ]
    }
  }
}

密钥参数 configParameters：仅参与签名计算、不会随请求发出的常量（如 appSecret）。以键值对形式配置，会以 config 入口传入 Groovy 脚本。

{
  "config": {
    "openApi": {
      "configParameters": { "app_secret": "your-app-secret" }
    }
  }
}

4.4 添加工具（基础信息）

在插件下添加具体接口，核心字段：

说明：stream（SSE 流式输出）字段暂不对外开放，OpenAPI 工具当前不支持流式响应。

4.5 配置请求参数（ToolParameter）

请求参数是 OpenAPI 工具的核心。每个参数由「类型 + 位置 + 来源」三要素定义。

这个参数值需要签名或复杂派生计算吗？
  → 是：选择「脚本生成」
  → 否：
    与用户/设备身份相关吗？（用户ID、设备UUID、经纬度）
      → 是：选择「系统上下文」
    是时间戳 / 随机串等动态量吗？
      → 是：选择「内置语法糖」
    是固定常量、不随请求变化吗？
      → 是：选择「常量」
    需要由大模型从用户输入中提取吗？
      → 是：选择「模型抽取」

{
  "requestParameters": [
    { "name": "city", "type": "string", "position": "query", "from": "model", "required": true, "description": "城市名称，如北京、上海" },
    { "name": "units", "type": "string", "position": "query", "from": "constant", "defaultValue": "metric" },
    { "name": "device_id", "type": "string", "position": "header", "from": "context", "contextField": "uuid" }
  ]
}

{
  "name": "filters",
  "type": "object",
  "position": "body",
  "subParameters": [
    { "name": "tags", "type": "array", "subParameters": [ { "name": "item", "type": "string", "from": "model", "description": "标签" } ] },
    { "name": "limit", "type": "number", "from": "constant", "defaultValue": "10" }
  ]
}

4.6 配置响应参数（ResponseParameter）

响应参数用于描述接口返回结构，帮助模型理解与使用返回值。结构为树形，支持嵌套：

{
  "responseParameter": {
    "name": "result",
    "type": "object",
    "subParameters": [
      { "name": "temperature", "type": "number", "description": "当前温度（摄氏度）" },
      { "name": "weather", "type": "string", "description": "天气状况" }
    ]
  }
}

4.7 使用 Groovy 脚本处理签名

当参数值需要签名或复杂计算时，选择「脚本生成」来源。脚本运行在受限的沙箱环境中，并强制编译检查。

脚本编写规则：

脚本可用入参（arguments: Map<String, Object>）：

├── "path"   → Map | null   URL 路径参数
├── "query"  → Map | null   URL 查询参数
├── "header" → Map | null   HTTP 请求头
├── "body"   → Map | null   请求体
└── "config" → Map | null   密钥参数（configParameters）

脚本采用两阶段执行：先解析所有非 script 参数，再把结果作为上下文传入脚本，因此脚本可读取其它已解析参数的值。

脚本骨架示例：

package com.alibaba.aicloud.mcp.service.mcp.caller.openapi

import java.util.*
import java.nio.charset.StandardCharsets
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec

public class SignCalculator_K7mN2p implements GroovyParserService {
    @Override
    public Object parse(Map<String, Object> arguments) {
        Map<String, Object> query = (Map<String, Object>) arguments.get("query")
        Map<String, Object> config = (Map<String, Object>) arguments.get("config")
        String appSecret = (String) config.get("app_secret")

        TreeMap<String, Object> sorted = new TreeMap<>(query)
        StringBuilder sb = new StringBuilder()
        for (Map.Entry<String, Object> e : sorted.entrySet()) {
            if (sb.length() > 0) sb.append("&")
            sb.append(e.getKey()).append("=").append(String.valueOf(e.getValue()))
        }

        Mac mac = Mac.getInstance("HmacSHA1")
        mac.init(new SecretKeySpec(appSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA1"))
        byte[] bytes = mac.doFinal(sb.toString().getBytes(StandardCharsets.UTF_8))
        StringBuilder hex = new StringBuilder()
        for (byte b : bytes) { hex.append(String.format("%02x", b & 0xff)) }
        return hex.toString()
    }
}

5.1 注册 MCP 插件

自定义授权限制：MCP 的「自定义授权」认证参数位置仅支持「查询参数」或「请求头」，不支持「路径参数」。

5.2 传输协议 transport

5.3 创建与刷新工具

1. 创建 MCP 插件时填写 baseUrl、传输协议、endpoint 与认证方式。

2. 保存时平台会自动连接 MCP Server 并调用 tools/list，自动注册为本地工具（连接失败会报错，也可能由于授权方式填错导致连接成功但工具清单为空）。

3. 后续若 MCP Server 的工具有变更，可在列表页点击「刷新工具」重新拉取。

5.4 工具调用与参数特点

• 参数全部在 arguments 中传递（遵循 MCP 协议），无需也不支持手工配置位置，可手动配置参数来源。

• 参数的描述全部来自 MCP Server，无需也不支持在平台上修改；

• 认证方式继承自插件配置。

• 工具调用链路：

大模型 → MCP 调用请求 → 平台 MCP 网关 → 远端 MCP Server → 返回结果

5.5 MCP JSON导入格式

MCP 服务支持通过 JSON 配置进行导入，配置的顶层字段为 mcpServers，其中每个键代表一个 MCP 服务的名称，值为该服务的具体配置。根据鉴权方式和导入数量的不同，配置格式略有差异，下面分别说明。

1. 无鉴权的单MCP导入：

{
  "mcpServers": {
    "mcp-http-example": {
      "type": "streamableHttp",
      "description": "插件描述",
      "url": "https://api.example.com/mcp"
    }
  }
}

2. Bearer鉴权的单MCP导入：适用于使用标准 Bearer Token 鉴权的 MCP 服务，通过 headers 字段配置 Authorization。其中 ${Token} 需更换为真正的Token。

{
  "mcpServers": {
    "mcp-http-example": {
      "type": "streamableHttp",
      "description": "插件描述",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${Token}"
      }
    }
  }
}

3. 自定义鉴权的单MCP导入：当服务使用自定义鉴权方式时，支持在 query（URL 查询参数）或 headers（请求头）中放置自定义字段。以下示例通过 query 传递 apiKey：

{
  "mcpServers": {
    "mcp-http-example": {
      "type": "streamableHttp",
      "description": "插件描述",
      "url": "https://api.example.com/mcp",
      "query": {
        "apiKey": "${API_KEY}"
      }
    }
  }
}

3. 多MCP导入：mcpServers 内可包含多个 MCP 服务的配置，一次性完成批量导入。每个服务的键名需保持唯一。

{
  "mcpServers": {
    "mcp-http-example1": {
      "type": "streamableHttp",
      "description": "插件描述",
      "url": "https://api.example.com/mcp1"
    },
    "mcp-http-example2": {
      "type": "streamableHttp",
      "description": "插件描述",
      "url": "https://api.example.com/mcp2"
    },
    "mcp-http-example3": {
      "type": "streamableHttp",
      "description": "插件描述",
      "url": "https://api.example.com/mcp3"
    }
  }
}

6.1 支持的平台

6.2 创建 Agent 插件

6.3 入参 / 出参约定（固定）

Agent 类型工具不支持自定义入参，工具入参固定为单个 query 字段：

{
  "type": "object",
  "required": ["query"],
  "properties": {
    "query": { "type": "string", "description": "用户 query，需要传递给 agent。" }
  }
}

出参固定为 {$: string} 格式。即大模型只需传递 query，平台自动路由到对应智能体并返回结果。

6.4 调用与流式响应

Agent 工具支持流式响应，通过 MCP 进度通知逐步返回结果：

用户输入 → 大模型提取 query → MCP 调用 → 平台路由
                                        ├→ DashScope（百炼）
                                        └→ Coze（扣子）
                                             ↓
                                   流式 SSE 返回 → 逐 chunk 推送

7.1 插件级

7.2 OpenAPI 工具级

7.3 通用规则

• 已发布的插件 / 工具不可修改，需删除后重建。

• 脚本在沙箱环境执行，强制编译检查，禁用危险方法。

• 调用超时统一 3000ms（工具级可覆盖插件级）。