AI导哈

智能任务与计算机控制服务器

ByteBot MCP Server是一个生产级的模型上下文协议服务器，提供智能混合工作流编排，用于自主任务执行和桌面计算机控制。

  • by sensuslab
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 sensuslab/spark-mcp

使用说明

ByteBot MCP服务器

ByteBot的双API架构的生产级模型上下文协议（MCP）服务器，为自主任务执行和桌面计算机控制提供智能混合工作流编排。

概述

该MCP服务器将ByteBot的Agent API（任务管理）和Desktop API（计算机控制）集成到一个统一的界面中，用于Claude等人工智能助手。它能够：

  • 自主任务执行：创建和管理ByteBot独立执行的任务
  • 计算机直接控制：鼠标、键盘、屏幕截图和文件操作
  • 混合工作流：具有自动监控和干预处理功能的智能编排
  • 实时更新：可选的WebSocket支持实时任务状态通知

特性

代理API工具（任务管理）

  • bytebot_create_task -创建具有优先级的新任务
  • bytebot_list_tasks -按状态/优先级列出和筛选任务
  • bytebot_get_task -通过消息历史记录获取详细的任务信息
  • bytebot_get_in_progress_task -检查当前正在运行的任务
  • bytebot_update_task -更新任务状态或优先级
  • bytebot_delete_task -删除任务

桌面API工具（计算机控制）

鼠标操作：

  • bytebot_move_mouse -将光标移动到坐标
  • bytebot_click -单击左/右/中按钮
  • bytebot_drag -从一个位置拖动到另一个位置
  • bytebot_scroll -向任何方向滚动

键盘操作：

  • bytebot_type_text -键入文本字符串
  • bytebot_paste_text -粘贴文本（用于特殊字符）
  • bytebot_press_keys -键盘快捷键（Ctrl+C、Alt+Tab等）

屏幕操作：

  • bytebot_screenshot -以base64 PNG格式捕获屏幕
  • bytebot_cursor_position -获取当前光标位置

文件I/O：

  • bytebot_read_file -读取文件内容（base64）
  • bytebot_write_file -写入文件内容（base64）

系统：

  • bytebot_switch_application -切换到应用程序
  • bytebot_wait -等待指定的持续时间

混合编排工具（优先级1）

  • bytebot_create_and_monitor_task -创建任务并等待完成
  • bytebot_monitor_task -监控现有任务，直到终端状态
  • bytebot_intervene_in_task -当任务需要干预时提供帮助
  • bytebot_execute_workflow -具有自动错误恢复功能的多步工作流程

先决条件

  • Node.js：20.x或更高
  • ByteBot实例：在配置的端点上运行和访问
    • 代理API（默认值： http://localhost:9991)
    • 桌面API（默认值： http://localhost:9990)

安装

# Clone or download this repository
cd bytebot-mcp-server

# Install dependencies
npm install

# Build TypeScript code
npm run build

配置

1.创建环境文件

复制示例环境文件并自定义：

cp .env.example .env

2.编辑 .env 文件

# ByteBot Agent API (Task Management)
BYTEBOT_AGENT_URL=http://localhost:9991

# ByteBot Desktop API (Computer Control)
BYTEBOT_DESKTOP_URL=http://localhost:9990

# WebSocket Configuration (Optional)
BYTEBOT_WS_URL=ws://localhost:9991
ENABLE_WEBSOCKET=false

# Server Configuration
MCP_SERVER_NAME=bytebot-mcp

# Timeouts (milliseconds)
REQUEST_TIMEOUT=30000
DESKTOP_ACTION_TIMEOUT=10000

# Retry Configuration
MAX_RETRIES=3
RETRY_DELAY=1000

# Monitoring Configuration
TASK_POLL_INTERVAL=2000
TASK_MONITOR_TIMEOUT=300000

# File Configuration
MAX_FILE_SIZE=10485760

# Logging
LOG_LEVEL=info

3.远程ByteBot配置

如果ByteBot正在远程服务器上运行：

BYTEBOT_AGENT_URL=http://your-server.com:9991
BYTEBOT_DESKTOP_URL=http://your-server.com:9990
BYTEBOT_WS_URL=ws://your-server.com:9991

MCP客户端设置

克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bytebot": {
      "command": "node",
      "args": ["/absolute/path/to/bytebot-mcp-server/dist/index.js"],
      "env": {
        "BYTEBOT_AGENT_URL": "http://localhost:9991",
        "BYTEBOT_DESKTOP_URL": "http://localhost:9990"
      }
    }
  }
}

Zed编辑

添加到Zed设置中：

{
  "context_servers": {
    "bytebot": {
      "command": {
        "path": "node",
        "args": ["/absolute/path/to/bytebot-mcp-server/dist/index.js"]
      },
      "env": {
        "BYTEBOT_AGENT_URL": "http://localhost:9991",
        "BYTEBOT_DESKTOP_URL": "http://localhost:9990"
      }
    }
  }
}

Continue.dev

增添 .continue/config.json:

{
  "mcpServers": [
    {
      "name": "bytebot",
      "command": "node",
      "args": ["/absolute/path/to/bytebot-mcp-server/dist/index.js"],
      "env": {
        "BYTEBOT_AGENT_URL": "http://localhost:9991",
        "BYTEBOT_DESKTOP_URL": "http://localhost:9990"
      }
    }
  ]
}

使用示例

示例1：基本任务创建

User: Create a task for ByteBot to search Wikipedia for "quantum computing"

Claude uses: bytebot_create_task
{
  "description": "Go to wikipedia.org and search for 'quantum computing'",
  "priority": "MEDIUM"
}

Response:
{
  "id": "task-123",
  "status": "PENDING",
  "priority": "MEDIUM",
  "createdAt": "2024-01-15T10:30:00Z"
}

示例2：混合工作流（创建→ 监视器→ 完成）

User: Create a task to log into example.com and wait for it to complete

Claude uses: bytebot_create_and_monitor_task
{
  "description": "Navigate to example.com and log in with credentials from keychain",
  "timeout": 60000,
  "pollInterval": 2000
}

Response:
{
  "taskId": "task-456",
  "finalStatus": "COMPLETED",
  "completedAt": "2024-01-15T10:31:45Z",
  "messagesCount": 12,
  "task": { ... full task details ... }
}

示例3：任务需要干预

User: Create a task to fill out a complex form

Claude uses: bytebot_create_and_monitor_task
{
  "description": "Fill out the registration form at example.com/register"
}

Response (after monitoring):
{
  "taskId": "task-789",
  "finalStatus": "NEEDS_HELP",
  "task": {
    "id": "task-789",
    "status": "NEEDS_HELP",
    "messages": [
      {
        "role": "assistant",
        "content": "I need the user's phone number to complete this form"
      }
    ]
  }
}

User: My phone number is 555-1234

Claude uses: bytebot_intervene_in_task
{
  "taskId": "task-789",
  "message": "User's phone number is 555-1234",
  "action": "resume",
  "continueMonitoring": true
}

Response:
{
  "taskId": "task-789",
  "status": "COMPLETED",
  "intervention": "applied"
}

示例4：交互式桌面控件

User: Take a screenshot and click at position (500, 300)

Claude uses: bytebot_screenshot
Response: { "screenshot": "iVBORw0KG..." }

Claude uses: bytebot_click
{
  "x": 500,
  "y": 300,
  "button": "left"
}

Response: ✓ bytebot_click completed successfully

示例5：多步骤工作流

User: Execute a workflow to open Firefox, navigate to GitHub, and take a screenshot

Claude uses: bytebot_execute_workflow
{
  "steps": [
    {
      "name": "Open Firefox",
      "description": "Switch to Firefox browser application"
    },
    {
      "name": "Navigate to GitHub",
      "description": "Navigate to github.com in the browser"
    },
    {
      "name": "Take Screenshot",
      "description": "Capture a screenshot of the GitHub homepage"
    }
  ],
  "priority": "HIGH"
}

Response:
{
  "steps": [
    { "name": "Open Firefox", "taskId": "task-001", "status": "COMPLETED" },
    { "name": "Navigate to GitHub", "taskId": "task-002", "status": "COMPLETED" },
    { "name": "Take Screenshot", "taskId": "task-003", "status": "COMPLETED" }
  ],
  "overallStatus": "completed",
  "totalInterventions": 0
}

示例6：文件操作

User: Read the contents of /home/user/data.txt

Claude uses: bytebot_read_file
{
  "path": "/home/user/data.txt"
}

Response: { "content": "SGVsbG8gV29ybGQh..." } // Base64 encoded

故障排除

错误：“无法连接到ByteBot服务器”

原因：ByteBot未运行或终结点URL不正确

解决方案:

  1. 验证ByteBot是否正在运行： curl http://localhost:9991/tasks
  2. 检查 .env 文件具有正确的URL
  3. 确保没有防火墙阻止连接

错误：“请求ByteBot超时”

原因：任务花费的时间比配置的超时时间长

解决方案:

  1. 增加 REQUEST_TIMEOUT 在 .env 用于代理API调用
  2. 增加 DESKTOP_ACTION_TIMEOUT 用于桌面API调用
  3. 使用 bytebot_create_and_monitor_task 具有自定义超时：
    {
  "description": "Long running task",
  "timeout": 600000
}

错误：“找不到ID为xyz的任务”

原因：任务已删除或ID不正确

解决方案:

  1. 列出所有任务： bytebot_list_tasks
  2. 从响应中验证任务ID
  3. 检查任务是否被意外删除

警告：“屏幕截图大小为8.5MB”

原因：屏幕截图非常大（高分辨率显示）

解决方案:

  1. 这只是一个警告，截图仍然有效
  2. 如果频繁捕获屏幕截图，请考虑降低屏幕分辨率
  3. 屏幕截图>5MB将显示此警告

错误：“任务必须处于NEEDS_HELP状态”

原因：试图干预不需要帮助的任务

解决方案:

  1. 首先检查任务状态： bytebot_get_task
  2. 仅限使用 bytebot_intervene_in_task 当状态为 NEEDS_HELP
  3. 使用 bytebot_update_task 如果需要，手动更改状态

WebSocket连接失败

原因：WebSocket URL不正确或ByteBot不支持WebSocket

解决方案:

  1. 集 ENABLE_WEBSOCKET=false 在 .env 禁用WebSocket
  2. 服务器将自动回退到HTTP轮询
  3. WebSocket是可选的-所有功能都可以在没有它的情况下工作

错误：“文件大小超过了允许的最大大小”

原因：尝试上传/读取大于10MB的文件

解决方案:

  1. 增加 MAX_FILE_SIZE 在 .env （以字节为单位）
  2. 将大文件分割成更小的块
  3. 上传前压缩文件

api参考

任务优先级

  • LOW -背景任务，非紧急
  • MEDIUM -默认优先级（推荐）
  • HIGH -重要任务，很快处理
  • URGENT -关键任务，立即处理

任务生命周期状态

  1. PENDING -任务已创建，正在等待启动
  2. IN_PROGRESS -当前正在执行的任务
  3. NEEDS_HELP -任务受阻，需要干预
  4. NEEDS_REVIEW -任务已完成，但需要验证
  5. COMPLETED -任务已成功完成
  6. CANCELLED -用户已取消任务
  7. FAILED -任务失败，出现错误

鼠标按钮

  • left -主按钮（默认）
  • right -上下文菜单按钮
  • middle -滚轮点击

滚动方向

  • up -向上滚动
  • down -向下滚动
  • left -向左滚动
  • right -向右滚动

常见应用程序

  • firefox -Mozilla Firefox
  • chrome -谷歌Chrome浏览器
  • safari -Safari浏览器（macOS）
  • terminal -终端/命令提示符
  • vscode -Visual Studio代码

建筑

┌─────────────────────────────────────────────┐
│           MCP Client (Claude)               │
└─────────────────┬───────────────────────────┘
                  │ stdio transport
┌─────────────────▼───────────────────────────┐
│         ByteBot MCP Server                  │
│  ┌────────────────────────────────────────┐ │
│  │  Agent Tools  │  Desktop Tools          │ │
│  │  Hybrid Orchestrator                    │ │
│  └────────────┬──────────────┬─────────────┘ │
└───────────────┼──────────────┼───────────────┘
                │              │
     ┌──────────▼──┐    ┌──────▼──────┐
     │ Agent API   │    │ Desktop API │
     │ (port 9991) │    │ (port 9990) │
     └─────────────┘    └─────────────┘
            │                   │
     ┌──────▼───────────────────▼──────┐
     │        ByteBot Instance         │
     └─────────────────────────────────┘

发展

构建

npm run build

类型检查

npm run type-check

观看模式

npm run dev

环境变量引用

变量 默认值 描述
BYTEBOT_AGENT_URL http://localhost:9991 ByteBot代理API终结点
BYTEBOT_DESKTOP_URL http://localhost:9990 ByteBot桌面API端点
BYTEBOT_WS_URL ws://localhost:9991 用于实时更新的WebSocket端点
ENABLE_WEBSOCKET false 启用WebSocket连接
MCP_SERVER_NAME bytebot-mcp 服务器标识符
REQUEST_TIMEOUT 30000 HTTP请求超时（毫秒）
DESKTOP_ACTION_TIMEOUT 10000 桌面操作超时（ms）
MAX_RETRIES 3 失败请求的最大重试次数
RETRY_DELAY 1000 初始重试延迟（ms）
TASK_POLL_INTERVAL 2000 任务状态轮询间隔（ms）
TASK_MONITOR_TIMEOUT 300000 最大任务监视持续时间（ms）
MAX_FILE_SIZE 10485760 最大文件大小（以字节为单位）（10MB）
LOG_LEVEL info 日志记录级别（调试/信息/警告/错误）

许可证

麻省理工学院

支持

对于问题和疑问：

  • ByteBot文档：https://docs.bytebot.ai
  • MCP规范：https://modelcontextprotocol.io
  • 报告问题：在此存储库中创建问题

版本历史记录

1.0.0 (2024-01-15)

  • 初始版本
  • 代理API集成（任务管理）
  • 桌面API集成（计算机控制）
  • 混合编排工具
  • WebSocket支持实时更新
  • 全面的错误处理和重试逻辑
  • 具有严格类型的完整TypeScript实现

相关 MCP