chore: import upstream snapshot with attribution

2026-07-13 13:03:19 +08:00
commit 91e75e620b
3227 changed files with 1307078 additions and 0 deletions
@@ -0,0 +1,127 @@
+# Cua Computer Server
+
+Server component for the Computer-Use Interface (CUI) framework providing low-level computer control primitives.
+
+**[Documentation](https://cua.ai/docs/cua/guide/advanced/local-computer-server)** - Installation, guides, and configuration.
+
+## Interfaces
+
+The Computer Server exposes multiple interfaces simultaneously:
+
+- **HTTP/WebSocket** - REST API and WebSocket for programmatic access
+- **MCP via HTTP** - Model Context Protocol over streamable HTTP at `/mcp` endpoint
+
+> **Android emulators** also expose the emulator's built-in **EmulatorController gRPC service** on port 8554 (via `-grpc 8554` launch flag). Local Android sandboxes (`AndroidEmulatorRuntime`) use `GRPCEmulatorTransport` to call `getScreenshot()` directly on this service, bypassing the computer-server HTTP layer entirely. Benchmark: p50 ~20ms, ~49 RPS vs ADB-backed HTTP p50 ~519ms, ~1.8 RPS.
+
+## Installation
+
+```bash
+# Basic installation (HTTP/WebSocket only)
+pip install cua-computer-server
+
+# With MCP support
+pip install cua-computer-server[mcp]
+```
+
+## Usage
+
+```bash
+# Start the server on default port 8000
+python -m computer_server
+
+# Or with custom port
+python -m computer_server --port 8080
+
+# Allow external access explicitly
+python -m computer_server --host 0.0.0.0
+
+# With resolution scaling (useful for Retina displays or VMs)
+python -m computer_server --width 1512 --height 982
+```
+
+By default the server binds to `127.0.0.1`. Deployments that need access from
+other hosts should pass `--host 0.0.0.0` or another explicit interface.
+
+This provides:
+
+- HTTP API at `/ws`, `/cmd`, `/status` endpoints
+- MCP server at `/mcp` endpoint (requires `fastmcp` package)
+
+MCP clients can connect via streamable HTTP at `http://localhost:8000/mcp`.
+
+#### Resolution Scaling
+
+When running on Retina displays or in VMs where the coordinate system may differ, use the `--width` and `--height` flags to specify the target resolution:
+
+- Screenshots will be resized to the target resolution
+- Click coordinates received will be scaled from target to actual screen coordinates
+- Cursor position will be reported in target coordinates
+
+This ensures the AI model sees consistent coordinates between screenshots and mouse actions.
+
+#### Claude Code Integration
+
+1. Start the server (or run as a service/LaunchAgent):
+
+```bash
+python -m computer_server --port 8000
+```
+
+2. Add the MCP server URL to Claude Code:
+
+```bash
+claude mcp add cua-computer-server --transport http http://localhost:8000/mcp
+```
+
+## Available MCP Tools
+
+The MCP interface exposes 40+ tools for computer control:
+
+### Screen & Mouse
+
+- `computer_screenshot` - Capture current screen
+- `computer_click` - Click at coordinates
+- `computer_double_click` - Double-click
+- `computer_move` - Move cursor
+- `computer_drag` - Drag from start to end coordinates
+- `computer_scroll` - Scroll at position
+- `computer_get_screen_size` - Get screen dimensions
+- `computer_get_cursor_position` - Get cursor position
+
+### Keyboard
+
+- `computer_type` - Type text
+- `computer_press_key` - Press a single key
+- `computer_hotkey` - Press key combination (e.g., Ctrl+C)
+- `computer_key_down` / `computer_key_up` - Hold/release keys
+
+### Clipboard
+
+- `computer_clipboard_get` - Get clipboard content
+- `computer_clipboard_set` - Set clipboard content
+
+### Shell
+
+- `computer_run_command` - Execute shell command
+
+### File System
+
+- `computer_file_read` / `computer_file_write` - Read/write files
+- `computer_file_exists` / `computer_directory_exists` - Check existence
+- `computer_list_directory` - List directory contents
+- `computer_create_directory` - Create directory
+- `computer_delete_file` / `computer_delete_directory` - Delete files/directories
+
+### Window Management
+
+- `computer_open` - Open file or URL
+- `computer_launch_app` - Launch application
+- `computer_get_active_window` - Get active window
+- `computer_activate_window` - Focus a window
+- `computer_minimize_window` / `computer_maximize_window` - Window state
+- `computer_close_window` - Close window
+
+### Accessibility
+
+- `computer_get_accessibility_tree` - Get UI element tree
+- `computer_find_element` - Find UI element by role/title