Add MCP server for cross-OS control from Claude Code

Instead of a standalone agent loop, this exposes remote CUP machines as MCP
tools that Claude Code can call directly. Just add the MCP server to your
config, point it at cup_server instances on each machine, and talk naturally.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: k4cper-g

examples/cross-os/README.md

@@ -1,80 +1,123 @@
 # Cross-OS Agent Demo
 
-An AI agent that performs tasks across multiple machines running different operating systems, all using the same CUP (Computer Use Protocol) format.
+Control multiple machines running different operating systems from Claude Code (or any MCP client), all through the same CUP accessibility tree format.
 
-This demonstrates CUP's core value: **one protocol, every OS**. The agent sees identical accessibility tree formats whether a machine runs Windows, macOS, or Linux — no platform-specific code needed.
+This demonstrates CUP's core value: **one protocol, every OS**. Claude sees identical UI trees whether a machine runs Windows, macOS, or Linux — no platform-specific prompting needed.
 
 ## Architecture
 
 ```
 ┌──────────────────────────────────────────────┐
-│              Agent (agent.py)                 │
-│  Claude interprets CUP trees from all        │
-│  machines and coordinates actions across them │
-└──────┬──────────────┬──────────────┬─────────┘
-       │              │              │
-   WebSocket      WebSocket      WebSocket
-       │              │              │
-┌──────▼──────┐ ┌─────▼───────┐ ┌───▼─────────┐
-│ Windows PC  │ │ Linux Box   │ │ Mac         │
-│ cup_server  │ │ cup_server  │ │ cup_server  │
-│ (UIA)       │ │ (AT-SPI2)   │ │ (AXUIElement│
-└─────────────┘ └─────────────┘ └─────────────┘
+│           Claude Code / MCP Client           │
+│  "Open Notepad on windows, type hello,       │
+│   then open Notes on mac and paste it"       │
+└──────────────────┬───────────────────────────┘
+                   │ MCP (stdio)
+┌──────────────────▼───────────────────────────┐
+│          mcp_server.py (MCP bridge)          │
+│  Exposes snapshot, action, find tools        │
+│  for each connected machine                  │
+└──────┬──────────────────────────┬────────────┘
+       │ WebSocket                │ WebSocket
+┌──────▼──────┐            ┌─────▼────────────┐
+│ Windows PC  │            │ Mac              │
+│ cup_server  │            │ cup_server       │
+│ (UIA)       │            │ (AXUIElement)    │
+└─────────────┘            └──────────────────┘
 ```
 
 ## Files
 
 | File | Purpose |
 |------|---------|
-| `cup_server.py` | WebSocket server that wraps `cup.Session()` — run on each machine |
-| `cup_remote.py` | Client library: `RemoteSession` (single machine) and `MultiSession` (multi-machine) |
-| `agent.py` | The orchestrator: connects to all machines, uses Claude to perform cross-OS tasks |
+| `cup_server.py` | WebSocket server wrapping `cup.Session()` — run on each machine |
+| `mcp_server.py` | MCP bridge — connects to remote cup_servers, exposes tools to Claude Code |
+| `cup_remote.py` | Client library: `RemoteSession` and `MultiSession` |
+| `agent.py` | Standalone agent (alternative to MCP — runs its own Claude loop) |
 
-## Setup
+## Quick Start (MCP + Claude Code)
 
 ### 1. Install dependencies on every machine
 
 ```bash
 pip install computeruseprotocol websockets
 ```
 
-### 2. Start the server on each machine
+### 2. Start cup_server on each machine
 
+**On your Windows PC:**
 ```bash
-# On your Windows PC (e.g., 192.168.1.10)
-python cup_server.py --port 9800
+python cup_server.py --host 0.0.0.0 --port 9800
+```
+
+**On your Mac:**
+```bash
+python cup_server.py --host 0.0.0.0 --port 9800
+```
+
+### 3. Add the MCP server to Claude Code
+
+Install the MCP server dependencies (on the machine running Claude Code):
+```bash
+pip install mcp websocket-client
+```
 
-# On your Linux box (e.g., 192.168.1.20)
-python cup_server.py --port 9800
+Add to your Claude Code MCP config:
 
-# On your Mac (e.g., 192.168.1.30)
-python cup_server.py --port 9800
+```json
+{
+  "mcpServers": {
+    "cup-cross-os": {
+      "command": "python",
+      "args": [
+        "C:/path/to/examples/cross-os/mcp_server.py",
+        "windows=ws://localhost:9800",
+        "mac=ws://192.168.1.30:9800"
+      ]
+    }
+  }
+}
 ```
 
-### 3. Run the agent from any machine
+Replace the paths and IPs for your setup. If you're running Claude Code on your Windows machine, `windows` can point to `localhost`.
+
+### 4. Talk to Claude
+
+Now just ask Claude Code naturally:
+
+```
+"What apps are open on both machines?"
+
+"Open Notepad on windows and type 'Hello from Mac', then open TextEdit on mac and type 'Hello from Windows'"
+
+"Take a snapshot of the foreground window on mac"
+
+"Click the Submit button on windows"
+```
+
+Claude sees the CUP tools (`snapshot_machine`, `act_on_machine`, etc.) and uses them to interact with both machines.
+
+## Standalone Agent (alternative)
+
+If you prefer a self-contained script instead of MCP:
 
 ```bash
-# Install agent dependencies
 pip install anthropic websocket-client
 
-# Set your API key
-export ANTHROPIC_API_KEY=sk-ant-...
-
-# Run with a task
 python agent.py \
-    windows=ws://192.168.1.10:9800 \
-    linux=ws://192.168.1.20:9800 \
-    --task "Open Notepad on Windows and type 'Hello from Linux', then open gedit on Linux and type 'Hello from Windows'"
+    windows=ws://localhost:9800 \
+    mac=ws://192.168.1.30:9800 \
+    --task "Open a text editor on both machines and type today's date"
 
 # Or interactive mode
-python agent.py windows=ws://192.168.1.10:9800 linux=ws://192.168.1.20:9800
+python agent.py windows=ws://localhost:9800 mac=ws://192.168.1.30:9800
 ```
 
 ## Example tasks
 
 ```
 # Cross-OS text relay
-"Copy the title of the focused window on Windows and type it into the terminal on Linux"
+"Copy the title of the focused window on Windows and type it into the terminal on Mac"
 
 # Parallel app launch
 "Open a text editor on both machines and type today's date in each"
@@ -83,13 +126,11 @@ python agent.py windows=ws://192.168.1.10:9800 linux=ws://192.168.1.20:9800
 "Take a snapshot of both machines and tell me what apps are running on each"
 
 # Multi-step workflow
-"On Windows, open Chrome and navigate to example.com. On Linux, open Firefox and navigate to the same URL."
+"On Windows, open Chrome and navigate to example.com. On Mac, open Safari and navigate to the same URL."
 ```
 
 ## Using the client library directly
 
-You don't need the agent to use cross-OS CUP. The client library works standalone:
-
 ```python
 from cup_remote import RemoteSession, MultiSession
 
@@ -98,33 +139,27 @@ with RemoteSession("ws://192.168.1.10:9800") as win:
     print(win.snapshot(scope="overview"))
     win.open_app("notepad")
     tree = win.snapshot(scope="foreground")
-    # find the text area, type into it, etc.
 
-# Multiple machines
+# Multiple machines in parallel
 with MultiSession({
     "win": "ws://192.168.1.10:9800",
-    "linux": "ws://192.168.1.20:9800",
+    "mac": "ws://192.168.1.30:9800",
 }) as multi:
-    # Snapshot all machines in parallel
     trees = multi.snapshot_all(scope="foreground")
     for name, tree in trees.items():
         print(f"--- {name} ---")
-        print(tree[:200])  # first 200 chars
+        print(tree[:200])
 
-    # Act on specific machines
     multi["win"].action("e5", "click")
-    multi["linux"].action("e12", "type", value="hello")
+    multi["mac"].action("e12", "type", value="hello")
 ```
 
 ## Protocol
 
-The server uses a simple JSON-RPC protocol over WebSocket:
+The cup_server uses a simple JSON-RPC protocol over WebSocket:
 
 ```json
-// Request
 {"id": 1, "method": "snapshot", "params": {"scope": "foreground"}}
-
-// Response
 {"id": 1, "result": "# CUP 0.1.0 | windows | 1920x1080\n..."}
 ```