使用说明

项目简介

Cua Computer Server (cua-computer-server) 是 cua 项目中的服务器端组件，它基于 FastAPI 框架构建，并通过 WebSocket 提供接口。该服务器允许客户端通过 JSON-RPC 协议远程控制运行 macOS 或 Linux 虚拟机的计算机，或者直接控制本地操作系统。其核心功能是提供一套标准化的接口，使得 AI 智能体 (MCP 客户端) 能够安全、高效地与计算机操作系统进行交互，执行各种自动化任务。

主要功能点

远程控制: 通过 WebSocket 协议接收并执行来自客户端的指令，实现对虚拟或本地计算机的远程操作。
操作系统交互: 提供丰富的接口，包括鼠标操作（点击、移动、拖拽）、键盘输入、剪贴板控制、屏幕截图、窗口管理、进程控制等，使 AI 智能体能够像用户一样操作计算机。
安全隔离: 通常与 cua 的虚拟机管理工具 Lume 结合使用，允许 AI 智能体在隔离的虚拟机环境中运行，保障主系统的安全。
多种传输协议支持: 通过 WebSocket 提供服务，易于集成到各种客户端应用中。
易于扩展: 基于 FastAPI 构建，方便开发者根据需求扩展新的功能接口。

安装步骤

确保已安装 Python 3.10 或更高版本。

使用 pip 安装 cua-computer-server 库：

pip install cua-computer-server

服务器配置

MCP 客户端需要配置 MCP 服务器的启动命令 (command) 及其参数 (args) 才能与 MCP 服务器建立连接。以下是 cua-computer-server 的服务器配置信息示例 (JSON 格式)：

{
  "server name": "cua-computer-server",
  "command": "run_server.py",
  "args": [
    "--host", "0.0.0.0",
    "--port", "8000"
  ],
  "notes": "上述配置将在 0.0.0.0 地址的 8000 端口启动 cua-computer-server。您可以根据需要修改 host 和 port 参数。",
  "server_details": {
    "host": "0.0.0.0",
    "port": 8000,
    "protocol": "WebSocket",
    "endpoint": "/ws"
  },
  "transport_protocol": "WebSocket",
  "request_format": "JSON-RPC",
  "response_format": "JSON-RPC"
}

参数说明:

server name: 服务器名称，可以自定义，用于在客户端标识服务器。
command: 启动 cua-computer-server 的命令。这里使用 'run_server.py'，假设您在安装了 'cua-computer-server' 的 Python 环境中运行 MCP 客户端。如果使用虚拟环境，请确保命令在虚拟环境中执行。
args: 传递给 'run_server.py' 脚本的命令行参数。
- '--host 0.0.0.0': 指定服务器监听所有可用的网络接口。
- '--port 8000': 指定服务器监听的端口为 8000。
notes: 配置备注信息，帮助用户理解配置项的含义。
server_details: 包含服务器连接详细信息的 JSON 对象。
- '"host": "0.0.0.0"': 服务器主机地址。
- '"port": 8000': 服务器端口号。
- '"protocol": "WebSocket"': 使用的传输协议为 WebSocket。
- '"endpoint": "/ws"': WebSocket 连接的端点路径。
transport_protocol: 声明服务器使用的传输协议，这里是 "WebSocket"。
request_format: 声明客户端请求的格式，这里是 "JSON-RPC"。
response_format: 声明服务器响应的格式，这里是 "JSON-RPC"。

启动服务器:

在安装了 'cua-computer-server' 的 Python 环境中，打开终端并执行以下命令启动服务器：

run_server.py --host 0.0.0.0 --port 8000

或者，您也可以直接运行 'libs/computer-server' 目录下的 'run_server.py' 脚本。

测试连接:

可以使用 'libs/computer-server' 目录下的 'test_connection.py' 脚本测试 WebSocket 连接：

./test_connection.py --host localhost --port 8000 --keep-alive

基本使用方法

确保 MCP 客户端已配置上述服务器连接信息。
客户端通过 WebSocket 连接到 'cua-computer-server' 服务器 (例如 'ws://localhost:8000/ws')。

客户端发送 JSON-RPC 格式的请求，例如获取屏幕尺寸：

{"command": "get_screen_size", "params": {}}

服务器返回 JSON-RPC 格式的响应，例如：

{"success": true, "size": {"width": 1440, "height": 900}}

客户端可以根据 MCP 协议定义，发送各种指令来控制计算机，例如鼠标点击、键盘输入、截屏等。
详细的 API 命令和参数可以参考仓库 'libs/computer-server/computer_server/main.py' 中的 'handlers' 字典，以及 'libs/computer-server/computer_server/handlers/macos.py' 和 'libs/computer-server/computer_server/handlers/base.py' 文件。

关键词