Oomol Connect MCP SDK

English Documentation

用于 Oomol Connect 的 MCP (Model Context Protocol) SDK，支持集成到 Cherry Studio、VSCode 等 MCP 兼容客户端。

特性

• ✅ 基于官方 @modelcontextprotocol/sdk 的完整 MCP 协议支持
• ✅ 9 个工具覆盖 Oomol Connect 所有功能
• ✅ 完整的 TypeScript 类型支持
• ✅ 文件上传支持（本地路径和 base64 编码）
• ✅ 指数退避的智能轮询策略
• ✅ 实时进度监控
• ✅ 智能版本过滤（默认只返回最新版本）
• ✅ 轻松集成 Cherry Studio、VSCode、Claude Desktop

安装

全局安装

npm install -g oomol-connect-mcp-sdk-ts

使用 npx（推荐）

npx -y oomol-connect-mcp-sdk-ts

本地开发

git clone <repository-url>
cd oomol-connect-mcp-sdk-ts
npm install
npm run build

配置

环境变量

| 变量名 | 说明 | 是否必需 | 默认值 | |--------|------|---------|--------| | OOMOL_CONNECT_BASE_URL | API 基础 URL | 是 | - | | OOMOL_CONNECT_API_TOKEN | API Token | 是 | - | | MCP_SERVER_NAME | MCP Server 名称 | 否 | "oomol-connect" | | MCP_SERVER_VERSION | MCP Server 版本 | 否 | package.json 版本 | | OOMOL_CONNECT_DEFAULT_TIMEOUT | 默认超时时间(毫秒) | 否 | 300000 (5分钟) |

配置示例

# 必需配置
export OOMOL_CONNECT_BASE_URL="http://localhost:3000/api"
export OOMOL_CONNECT_API_TOKEN="api-your-token-here"

# 可选配置
export OOMOL_CONNECT_DEFAULT_TIMEOUT="300000"

MCP 客户端集成

Cherry Studio

在 Cherry Studio 的 MCP 配置中添加：

{
  "mcpServers": {
    "oomol-connect": {
      "command": "npx",
      "args": ["-y", "oomol-connect-mcp-sdk-ts"],
      "env": {
        "OOMOL_CONNECT_BASE_URL": "http://localhost:3000/api",
        "OOMOL_CONNECT_API_TOKEN": "your-token-here"
      }
    }
  }
}

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "oomol-connect": {
      "command": "npx",
      "args": ["-y", "oomol-connect-mcp-sdk-ts"],
      "env": {
        "OOMOL_CONNECT_BASE_URL": "http://localhost:3000/api",
        "OOMOL_CONNECT_API_TOKEN": "your-token-here"
      }
    }
  }
}

VSCode

在 VSCode 设置中配置或使用 MCP 扩展。

可用工具

高层工具（推荐，用户友好）

1. list_blocks - 列出所有可用的 blocks（默认只返回最新版本，可选返回所有版本）
2. list_tasks - 列出任务历史
3. execute_task - 执行任务并等待结果（最常用）
4. execute_task_with_files - 执行任务（含文件上传）
5. list_packages - 列出已安装的包
6. install_package - 安装包并等待完成

低层工具（高级用户，精细控制）

1. create_task - 仅创建任务（异步，不等待）
2. get_task - 查询任务状态
3. stop_task - 停止运行中的任务

使用示例

列出 Blocks

{
  "tool": "list_blocks",
  "arguments": {
    "includeAllVersions": false
  }
}

返回的每个 block 自动包含 blockId（格式："package::name"）和 version 字段。

执行任务

{
  "tool": "execute_task",
  "arguments": {
    "blockId": "audio-lab::text-to-audio",
    "inputValues": {
      "text": "你好",
      "voice": "zh-CN-XiaoxiaoNeural"
    },
    "pollIntervalMs": 2000,
    "timeoutMs": 300000
  }
}

执行任务（含文件上传）

{
  "tool": "execute_task_with_files",
  "arguments": {
    "blockId": "ffmpeg::audio_video_separation",
    "inputValues": {
      "outputFormat": "mp3"
    },
    "files": [
      {
        "path": "/absolute/path/to/video.mp4"
      }
    ]
  }
}

安装包

{
  "tool": "install_package",
  "arguments": {
    "name": "package-name",
    "version": "1.0.0"
  }
}

编程式使用

import { OomolConnectMcpServer } from "oomol-connect-mcp-sdk-ts";

const server = new OomolConnectMcpServer({
  baseUrl: "http://localhost:3000/api",
  authHeader: "api-your-token-here",
  name: "my-server",
  version: "1.0.0",
});

await server.run();

开发

# 安装依赖
npm install

# 构建
npm run build

# 开发模式（监听）
npm run dev

# 本地运行
npm start

架构

本 SDK 基于：

• @modelcontextprotocol/sdk - 官方 MCP SDK
• oomol-connect-sdk - Oomol Connect API 客户端

该 SDK 为 oomol-connect-sdk 提供零业务逻辑重复的 MCP 协议封装。

许可证

MIT

贡献

欢迎贡献！请提交 issue 或 pull request。

相关项目

• oomol-connect-sdk-ts - 核心 Oomol Connect SDK
• oomol-cloud-mcp-sdk-ts - Oomol Cloud 的 MCP SDK

支持

问题和咨询：

• GitHub Issues: 创建 issue
• 文档：查看 examples 文件夹获取更多使用示例