logo文档更新博客下载 Studio
社区登录

MCP SDK

oomol-cloud-mcp-sdk 是与 OOMOL Cloud Task TypeScript SDK 对齐的 MCP Server SDK。

它同时承担两类角色：

  • 完整 re-export oomol-cloud-task-sdk，可以直接当作 Cloud Task TypeScript SDK 使用
  • 在此基础上提供一个 MCP Server 封装，把 Cloud Task 能力暴露成 MCP tools

安装​

npm install oomol-cloud-mcp-sdk

运行要求​

  • Node.js >=18
  • 通过构造参数或环境变量提供鉴权信息
  • 可选地提供默认 package 配置，给任务类 tools 复用
备注

upload_file tool 复用了 Cloud Task SDK 的上传实现，而该实现依赖浏览器式的 File 和 XMLHttpRequest。因此在纯 Node.js 环境里，只有在运行时提供兼容全局对象或 polyfill 时才适合使用。

通过 CLI 启动 MCP Server​

export OOMOL_API_KEY="your-api-key"
oomol-mcp-server

如果希望任务类 tools 默认使用某个 package，再额外设置：

export OOMOL_PACKAGE_NAME="@oomol/your-package"
export OOMOL_PACKAGE_VERSION="1.0.0"

配置 MCP Client​

{
  "mcpServers": {
    "oomol-cloud": {
      "command": "npx",
      "args": ["-y", "oomol-cloud-mcp-sdk"],
      "env": {
        "OOMOL_API_KEY": "your-api-key-here",
        "OOMOL_PACKAGE_NAME": "@oomol/your-package",
        "OOMOL_PACKAGE_VERSION": "1.0.0"
      }
    }
  }
}

直接当作 Cloud Task SDK 使用​

import { OomolTaskClient } from "oomol-cloud-mcp-sdk";

const client = new OomolTaskClient({
  apiKey: process.env.OOMOL_API_KEY,
});

const { taskID, result } = await client.createAndWait({
  packageName: "@oomol/my-package",
  packageVersion: "1.0.0",
  blockName: "main",
  inputValues: {
    text: "hello",
  },
});

通过代码启动 Server​

import { OomolMcpServer } from "oomol-cloud-mcp-sdk";

const server = new OomolMcpServer({
  apiKey: process.env.OOMOL_API_KEY,
  packageName: process.env.OOMOL_PACKAGE_NAME,
  packageVersion: process.env.OOMOL_PACKAGE_VERSION,
  name: "my-oomol-server",
  version: "1.0.0",
});

await server.run();

server.taskClient 可以直接拿到底层的 OomolTaskClient 实例。

MCP Tools​

Tool说明
create_task创建 serverless 任务
execute_task创建任务并等待终态结果
list_tasks获取当前用户任务列表
get_latest_tasks获取一个或多个 workload 的最新任务
get_task获取任务详情
get_task_result获取任务当前结果状态
await_result轮询直到任务成功或失败
get_dashboard获取配额、队列计数和暂停状态
set_tasks_pause暂停或恢复当前用户任务队列
pause_user_queue暂停当前用户任务队列
resume_user_queue恢复当前用户任务队列
upload_file上传 base64 文件并返回 URL
create_block_taskcreate_task 的别名
execute_block_taskexecute_task 的别名

create_task​

packageName 和 packageVersion 可以来自 tool 参数，也可以来自 server 默认配置。

{
  "name": "create_task",
  "arguments": {
    "blockName": "main",
    "inputValues": {
      "text": "hello"
    }
  }
}

execute_task​

和 create_task 使用相同的任务参数，同时额外支持轮询控制参数：

{
  "name": "execute_task",
  "arguments": {
    "blockName": "main",
    "inputValues": {
      "text": "hello"
    },
    "intervalMs": 2000,
    "timeoutMs": 300000
  }
}

list_tasks​

{
  "name": "list_tasks",
  "arguments": {
    "size": 20,
    "status": "running",
    "taskType": "user"
  }
}

await_result​

{
  "name": "await_result",
  "arguments": {
    "taskID": "019234a5-b678-7def-8123-456789abcdef",
    "intervalMs": 2000,
    "timeoutMs": 300000
  }
}

set_tasks_pause​

{
  "name": "set_tasks_pause",
  "arguments": {
    "paused": true
  }
}

upload_file​

传入 base64 编码后的文件内容：

{
  "name": "upload_file",
  "arguments": {
    "fileName": "example.txt",
    "fileData": "SGVsbG8gd29ybGQ=",
    "mimeType": "text/plain",
    "retries": 3
  }
}

配置​

环境变量​

变量说明必填
OOMOL_API_KEYOOMOL Cloud API Key通常需要
OOMOL_BASE_URLTask API 基础地址否
OOMOL_PACKAGE_NAME任务类 tools 的默认 package 名称否
OOMOL_PACKAGE_VERSION任务类 tools 的默认 package 版本否
MCP_SERVER_NAMEMCP Server 名称否
MCP_SERVER_VERSIONMCP Server 版本号否

ServerOptions​

ServerOptions 继承自 Cloud Task SDK 的 ClientOptions，并新增：

interface ServerOptions extends ClientOptions {
  name?: string;
  version?: string;
  packageName?: string;
  packageVersion?: string;
  maxPollIntervalMs?: number;
}

maxPollIntervalMs 会限制 execute_task、await_result 等轮询类 tool 使用的指数退避上限。

Tool 返回结构​

每个 MCP tool 都会返回一个 ToolResponse：

interface ToolResponse {
  content: Array<{
    type: "text";
    text: string;
  }>;
  isError?: boolean;
}

成功结果会把 JSON 序列化后放进 content[0].text。

错误结果会设置 isError: true，并附带错误名、错误消息以及异常对象上的可枚举字段。

导出内容​

这个包会导出：

  • OomolMcpServer
  • ServerOptions
  • ToolResponse
  • oomol-cloud-task-sdk 的全部导出

也就是说，你可以从同一个包拿到 OomolTaskClient、Cloud Task 类型、BackoffStrategy，以及 ApiError、TaskFailedError、TimeoutError、UploadError 等错误类。

相关文档​