Skip to main content

MCP 管理 API

@grant CAT.agent.mcp

MCP（Model Context Protocol）管理 API 允许脚本管理 MCP 服务器连接，MCP 服务器提供的工具会自动注册到 Agent，供 AI 对话调用。

MCP 服务器​

ScriptCat 的 MCP Client 使用 Streamable HTTP 传输协议（JSON-RPC 2.0 POST），支持 MCP 协议版本 2025-03-26。

MCP 服务器可以提供三种能力：

能力说明
Tools工具函数，自动注册为 Agent 可调用的工具
Resources可读取的资源（文本/二进制）
Prompts提示词模板，支持参数化

listServers — 列出服务器​

const servers = await CAT.agent.mcp.listServers();

返回值 MCPServerConfig[]：

字段类型说明
idstring服务器 ID
namestring显示名称
urlstringHTTP 端点地址
apiKeystringAPI Key（可选）
headersRecord<string, string>自定义请求头（可选）
enabledboolean是否启用
createtimenumber创建时间戳
updatetimenumber更新时间戳

getServer — 获取服务器详情​

const server = await CAT.agent.mcp.getServer(serverId);

addServer — 添加服务器​

const server = await CAT.agent.mcp.addServer({
  name: "My MCP Server",
  url: "https://mcp.example.com/api",
  apiKey: "sk-xxx",          // 可选
  headers: {                  // 可选自定义头
    "X-Custom": "value"
  },
  enabled: true
});

updateServer — 更新服务器​

await CAT.agent.mcp.updateServer(serverId, {
  name: "新名称",
  enabled: false
});

removeServer — 删除服务器​

await CAT.agent.mcp.removeServer(serverId);

testConnection — 测试连接​

await CAT.agent.mcp.testConnection(serverId);

尝试连接服务器并交换协议版本，成功无返回，失败抛出异常。

listTools — 列出工具​

const tools = await CAT.agent.mcp.listTools(serverId);

返回服务器提供的工具列表，每个工具包含 name、description 和 inputSchema（JSON Schema 参数定义）。

启用的 MCP 服务器的工具会自动注册到 Agent，命名格式为 mcp_{serverId}_{toolName}。

listResources — 列出资源​

const resources = await CAT.agent.mcp.listResources(serverId);

返回服务器可读取的资源列表。

readResource — 读取资源​

const result = await CAT.agent.mcp.readResource(serverId, uri);

参数：

参数类型说明
serverIdstring服务器 ID
uristring资源 URI

返回资源内容。

listPrompts — 列出提示词模板​

const prompts = await CAT.agent.mcp.listPrompts(serverId);

getPrompt — 获取提示词​

const messages = await CAT.agent.mcp.getPrompt(serverId, promptName, args?);

参数：

参数类型说明
serverIdstring服务器 ID
promptNamestring提示词名称
argsRecord<string, string>提示词参数

完整示例​

// ==UserScript==
// @name        MCP 工具管理
// @match       *://*/*
// @grant       CAT.agent.mcp
// @grant       CAT.agent.conversation
// ==/UserScript==

// 添加一个 MCP 服务器
const server = await CAT.agent.mcp.addServer({
  name: "Knowledge Base",
  url: "https://my-kb.example.com/mcp",
  apiKey: "my-api-key",
  enabled: true
});

// 测试连接
try {
  await CAT.agent.mcp.testConnection(server.id);
  console.log("连接成功！");
} catch (e) {
  console.error("连接失败:", e);
}

// 查看可用工具
const tools = await CAT.agent.mcp.listTools(server.id);
console.log("可用工具:", tools.map(t => t.name));

// 在对话中使用 — MCP 工具会自动注册，AI 可以直接调用
const conv = await CAT.agent.conversation.create();
const reply = await conv.chat("请使用知识库搜索关于 ScriptCat 的信息");