oomol-block-mcp-sdk

Oomol Cloud Block API 的 MCP Server SDK - 将 Oomol Cloud 区块执行能力封装成符合 Model Context Protocol 的工具。

English | 简体中文

特性

• ✅ 完整 MCP 协议支持: 基于官方 @modelcontextprotocol/sdk 使用最新的 McpServer API 构建
• ✅ Stdio 传输: 兼容 Cherry Studio、VSCode、Claude Desktop 等 MCP 客户端
• ✅ 类型安全: 完整的 TypeScript 类型定义
• ✅ 零业务逻辑重复: 完全复用 oomol-cloud-block-sdk
• ✅ 简洁 API: 4 个核心工具覆盖主要使用场景

v1.0.2 新特性

• 🔄 迁移到 McpServer API: 从已弃用的 Server 类升级到新的 McpServer 高级 API
• ✨ 简化工具注册: 现在使用 registerTool() 方法,代码更清晰、更易维护
• 🚀 更好的类型安全: 新的 McpServer API 提供了改进的类型推断

安装

全局安装:

npm install -g oomol-block-mcp-sdk

或作为项目依赖:

npm install oomol-block-mcp-sdk

快速开始

1. 作为 MCP Server 运行

设置环境变量并启动服务器:

export OOMOL_API_KEY="your-api-key"
export OOMOL_PACKAGE_NAME="your-package-name"
export OOMOL_PACKAGE_VERSION="your-package-version"
oomol-block-mcp-server

2. 在 MCP 客户端中配置

Cherry Studio / Claude Desktop

在 MCP 配置文件中添加:

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

VSCode

在 VSCode MCP 设置中添加相同配置。

3. 使用工具

配置完成后,你可以在 MCP 客户端中使用以下工具:

list_blocks - 列出可用区块

获取已配置包中所有可用区块的列表(自动使用环境变量 OOMOL_PACKAGE_NAME 和 OOMOL_PACKAGE_VERSION):

{
  "name": "list_blocks",
  "arguments": {
    "lang": "zh-CN"
  }
}

注意: 你不需要传递 packageName 和 packageVersion 参数 - 它们会自动从你配置的环境变量中读取。

响应:

[
  {
    "type": "task",
    "resourceName": "processImage",
    "name": "processImage",
    "title": "图像处理",
    "description": "处理和转换图像",
    "icon": "https://example.com/icon.png",
    "inputHandles": [
      {
        "handle": "imageUrl",
        "description": "要处理的图像 URL",
        "nullable": false
      }
    ],
    "outputHandles": [
      {
        "handle": "resultUrl",
        "description": "处理后的图像 URL",
        "nullable": false
      }
    ]
  }
]

execute_block_task - 执行区块任务并等待结果

创建并执行区块任务,等待完成:

{
  "name": "execute_block_task",
  "arguments": {
    "blockName": "processImage",
    "packageName": "my-package",
    "packageVersion": "1.0.0",
    "inputValues": {
      "imageUrl": "https://example.com/input.jpg",
      "quality": 80
    },
    "intervalMs": 3000,
    "timeoutMs": 300000
  }
}

响应:

{
  "taskID": "task-abc-123",
  "status": "success",
  "resultData": {
    "resultUrl": "https://example.com/output.jpg"
  },
  "resultURL": "https://example.com/output.jpg"
}

create_block_task - 创建区块任务(异步)

创建区块任务但不等待完成(使用 webhook 接收通知):

{
  "name": "create_block_task",
  "arguments": {
    "blockName": "processImage",
    "packageName": "my-package",
    "packageVersion": "1.0.0",
    "inputValues": {
      "imageUrl": "https://example.com/input.jpg"
    },
    "webhookUrl": "https://your-webhook.com/callback",
    "metadata": {
      "userId": "user-123"
    }
  }
}

响应:

{
  "taskID": "task-abc-123",
  "message": "任务创建成功。使用 webhook 接收异步通知或轮询获取结果。"
}

upload_file - 上传文件到云端

将文件上传到 Oomol Cloud 存储:

{
  "name": "upload_file",
  "arguments": {
    "fileName": "image.png",
    "fileData": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
    "mimeType": "image/png"
  }
}

响应:

{
  "fileUrl": "https://llm.oomol.com/api/tasks/files/remote-cache/abc123.png",
  "fileName": "image.png",
  "fileSize": 1234,
  "mimeType": "image/png"
}

编程方式使用

你也可以在 TypeScript/JavaScript 项目中以编程方式使用此 SDK:

import { OomolBlockMcpServer } from "oomol-block-mcp-sdk";

// 配置通过环境变量读取:
// - OOMOL_API_KEY (必需)
// - OOMOL_PACKAGE_NAME (必需)
// - OOMOL_PACKAGE_VERSION (必需)
const server = new OomolBlockMcpServer();

await server.run();

环境变量

• OOMOL_API_KEY (必需): 你的 Oomol Cloud API 密钥
• OOMOL_PACKAGE_NAME (必需): MCP 服务器的包名称
• OOMOL_PACKAGE_VERSION (必需): MCP 服务器的包版本

错误处理

所有工具返回标准化的错误响应:

{
  "error": "错误信息",
  "details": {
    "name": "ApiError",
    "message": "详细错误信息",
    "statusCode": 400
  }
}

架构

此 SDK 采用模块化架构构建:

oomol-block-mcp-sdk-ts/
├── src/
│   ├── index.ts          # CLI 入口点和导出
│   ├── server.ts         # MCP 服务器实现
│   ├── types.ts          # TypeScript 类型定义
│   └── tools/
│       ├── index.ts              # 工具注册器
│       ├── list-blocks.ts        # 列出区块工具
│       ├── execute-block-task.ts # 执行区块任务工具
│       ├── create-block-task.ts  # 创建区块任务工具
│       └── upload-file.ts        # 上传文件工具
├── package.json
└── tsconfig.json

相关项目

• oomol-cloud-block-sdk - 底层 Block SDK
• oomol-cloud-task-sdk - Oomol Cloud 的 Task SDK
• oomol-cloud-mcp-sdk - Task API 的 MCP SDK
• @modelcontextprotocol/sdk - 官方 MCP SDK

许可证

MIT

贡献

欢迎贡献!请随时提交 Pull Request。