claude-kvm 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rıza Emre ARAS <r.emrearas@proton.me>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,320 @@
+# Claude KVM
+
+Claude KVM is an MCP tool that controls remote desktop environments over VNC. It consists of a thin JS proxy layer (MCP server) and a platform-native Swift VNC daemon running on your macOS system.
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph MCP["MCP Client (Claude)"]
+        AI["Claude"]
+    end
+
+    subgraph Proxy["claude-kvm · MCP Proxy (stdio)"]
+        direction TB
+        Server["MCP Server<br/><code>index.js</code>"]
+        Tools["Tool Definitions<br/><code>tools/index.js</code>"]
+        Server --> Tools
+    end
+
+    subgraph Daemon["claude-kvm-daemon · Native VNC Client (stdin/stdout)"]
+        direction TB
+        CMD["Command Handler<br/><i>PC Dispatch</i>"]
+        Scale["Display Scaling<br/><i>Scaled ↔ Native</i>"]
+
+        subgraph Screen["Screen"]
+            Capture["Frame Capture<br/><i>PNG · Crop · Diff</i>"]
+            OCR["OCR Detection<br/><i>Apple Vision</i>"]
+        end
+
+        subgraph InputGroup["Input"]
+            Mouse["Mouse<br/><i>Click · Drag · Move · Scroll</i>"]
+            KB["Keyboard<br/><i>Tap · Combo · Type · Paste</i>"]
+        end
+
+        VNC["VNC Bridge<br/><i>LibVNCClient 0.9.15</i>"]
+
+        CMD --> Scale
+        Scale --> Capture
+        Scale --> Mouse
+        Scale --> KB
+        Capture -.->|"framebuffer"| VNC
+        Mouse -->|"pointer events"| VNC
+        KB -->|"key events"| VNC
+    end
+
+    subgraph Target["Target Machine"]
+        VNC_Server["VNC Server<br/><i>:5900</i>"]
+        Desktop["Desktop Environment"]
+        VNC_Server --> Desktop
+    end
+
+    AI <-->|"stdio<br/>JSON-RPC"| Server
+    Server <-->|"stdin/stdout<br/>PC (NDJSON)"| CMD
+    VNC <-->|"RFB Protocol<br/>TCP :5900"| VNC_Server
+
+    classDef proxy fill:#1a1a2e,stroke:#16213e,color:#e5e5e5
+    classDef daemon fill:#0f3460,stroke:#533483,color:#e5e5e5
+    classDef target fill:#1a1a2e,stroke:#e94560,color:#e5e5e5
+
+    class Server,Tools proxy
+    class CMD,Scale,VNC,Capture,Mouse,KB daemon
+    class VNC_Server,Desktop target
+```
+
+### Layers
+
+| Layer          | Language                | Role                                                                 | Communication            |
+|----------------|-------------------------|----------------------------------------------------------------------|--------------------------|
+| **MCP Proxy**  | JavaScript (Node.js)    | Communicates with Claude over MCP protocol, manages daemon lifecycle | stdio JSON-RPC           |
+| **VNC Daemon** | Swift/C (Apple Silicon) | VNC connection, screen capture, mouse/keyboard input injection       | stdin/stdout PC (NDJSON) |
+
+### PC (Procedure Call) Protocol
+
+Communication between the proxy and daemon uses the PC protocol over NDJSON:
+
+```
+Request:      {"method":"<name>","params":{...},"id":<int|string>}
+Response:     {"result":{...},"id":<int|string>}
+Error:        {"error":{"code":<int>,"message":"..."},"id":<int|string>}
+Notification: {"method":"<name>","params":{...}}
+```
+
+### Coordinate Scaling
+
+The VNC server's native resolution is scaled down to fit within `--max-dimension` (default: 1280px). Claude works more consistently with scaled coordinates — the daemon handles the conversion in the background:
+
+```
+Native:  4220 x 2568  (VNC server framebuffer)
+Scaled:  1280 x 779   (what Claude sees and targets)
+
+mouse_click(640, 400) → VNC receives (2110, 1284)
+```
+
+### Screen Strategy
+
+Claude minimizes token cost with a progressive verification approach:
+
+```
+diff_check       →  changeDetected: true/false     ~5ms    (text only, no image)
+detect_elements  →  OCR text + bounding boxes      ~50ms   (text only, no image)
+cursor_crop      →  crop around cursor              ~50ms   (small image)
+screenshot       →  full screen capture             ~200ms  (full image)
+```
+
+`detect_elements` uses Apple Vision framework for on-device OCR. Returns text content with bounding box coordinates in scaled space — enables precise click targeting without consuming vision tokens.
+
+---
+
+## Installation
+
+### Requirements
+
+- macOS (Apple Silicon / aarch64)
+- Node.js (LTS)
+
+### Daemon
+
+```bash
+brew tap ARAS-Workspace/tap
+brew install claude-kvm-daemon
+```
+
+> [!NOTE]
+> `claude-kvm-daemon` is compiled and code-signed via CI (GitHub Actions). The build output is packaged in two formats: a `.tar.gz` archive for Homebrew distribution and a `.dmg` disk image for notarization. The DMG is submitted to Apple servers for notarization within the same workflow — the process can be tracked from CI logs. The notarized DMG is available as a CI Artifact; the archived `.tar.gz` is also published as a release on the repository. Homebrew installation tracks this release.
+>
+> - [Release](https://github.com/ARAS-Workspace/claude-kvm/releases/tag/daemon-v1.0.1) · [Source Code](https://github.com/ARAS-Workspace/claude-kvm/tree/daemon-tool)
+> - [LibVNC Build](https://github.com/ARAS-Workspace/claude-kvm/actions/runs/22122975416) · [LibVNC Branch](https://github.com/ARAS-Workspace/claude-kvm/tree/libvnc-build)
+> - [Homebrew Tap](https://github.com/ARAS-Workspace/homebrew-tap)
+
+### MCP Configuration
+
+Create a `.mcp.json` file in your project directory:
+
+```json
+{
+  "mcpServers": {
+    "claude-kvm": {
+      "command": "npx",
+      "args": ["-y", "github:ARAS-Workspace/claude-kvm"],
+      "env": {
+        "VNC_HOST": "192.168.1.100",
+        "VNC_PORT": "5900",
+        "VNC_USERNAME": "user",
+        "VNC_PASSWORD": "pass",
+        "CLAUDE_KVM_DAEMON_PATH": "/opt/homebrew/bin/claude-kvm-daemon",
+        "CLAUDE_KVM_DAEMON_PARAMETERS": "-v"
+      }
+    }
+  }
+}
+```
+
+### Configuration
+
+#### MCP Proxy (ENV)
+
+| Parameter                      | Default             | Description                                        |
+|--------------------------------|---------------------|----------------------------------------------------|
+| `VNC_HOST`                     | `127.0.0.1`         | VNC server address                                 |
+| `VNC_PORT`                     | `5900`              | VNC port number                                    |
+| `VNC_USERNAME`                 |                     | Username (required for ARD)                        |
+| `VNC_PASSWORD`                 |                     | Password                                           |
+| `CLAUDE_KVM_DAEMON_PATH`       | `claude-kvm-daemon` | Daemon binary path (not needed if already in PATH) |
+| `CLAUDE_KVM_DAEMON_PARAMETERS` |                     | Additional CLI arguments for the daemon            |
+
+#### Daemon Parameters (CLI)
+
+Additional arguments passed to the daemon via `CLAUDE_KVM_DAEMON_PARAMETERS`:
+
+```
+"CLAUDE_KVM_DAEMON_PARAMETERS": "--max-dimension 800 -v"
+```
+
+| Parameter           | Default | Description                            |
+|---------------------|---------|----------------------------------------|
+| `--max-dimension`   | `1280`  | Maximum display scaling dimension (px) |
+| `--connect-timeout` |         | VNC connection timeout (seconds)       |
+| `--bits-per-sample` |         | Bits per pixel sample                  |
+| `--no-reconnect`    |         | Disable automatic reconnection         |
+| `-v, --verbose`     |         | Verbose logging (stderr)               |
+
+#### Runtime Configuration (PC)
+
+All timing and display parameters are configurable at runtime via the `configure` method. Use `get_timing` to inspect current values.
+
+Set timing:
+```json
+{"method":"configure","params":{"click_hold_ms":80,"key_hold_ms":50}}
+```
+```json
+{"result":{"detail":"OK — changed: click_hold_ms, key_hold_ms"}}
+```
+
+Change display scaling:
+```json
+{"method":"configure","params":{"max_dimension":960}}
+```
+```json
+{"result":{"detail":"OK — changed: max_dimension","scaledWidth":960,"scaledHeight":584}}
+```
+
+Reset to defaults:
+```json
+{"method":"configure","params":{"reset":true}}
+```
+```json
+{"result":{"detail":"OK — reset to defaults","timing":{"click_hold_ms":50,"combo_mod_ms":10,"cursor_crop_radius":150,"double_click_gap_ms":50,"drag_min_steps":10,"drag_pixels_per_step":20,"drag_position_ms":30,"drag_press_ms":50,"drag_settle_ms":30,"drag_step_ms":5,"hover_settle_ms":400,"key_hold_ms":30,"max_dimension":1280,"paste_settle_ms":30,"scroll_press_ms":10,"scroll_tick_ms":20,"type_inter_key_ms":20,"type_key_ms":20,"type_shift_ms":10},"scaledWidth":1280,"scaledHeight":779}}
+```
+
+Get current values:
+```json
+{"method":"get_timing"}
+```
+```json
+{"result":{"timing":{"click_hold_ms":80,"combo_mod_ms":10,"cursor_crop_radius":150,"double_click_gap_ms":50,"drag_min_steps":10,"drag_pixels_per_step":20,"drag_position_ms":30,"drag_press_ms":50,"drag_settle_ms":30,"drag_step_ms":5,"hover_settle_ms":400,"key_hold_ms":50,"max_dimension":1280,"paste_settle_ms":30,"scroll_press_ms":10,"scroll_tick_ms":20,"type_inter_key_ms":20,"type_key_ms":20,"type_shift_ms":10},"scaledWidth":1280,"scaledHeight":779}}
+```
+
+| Parameter              | Default | Description                |
+|------------------------|---------|----------------------------|
+| `max_dimension`        | `1280`  | Max screenshot dimension   |
+| `cursor_crop_radius`   | `150`   | Cursor crop radius (px)    |
+| `click_hold_ms`        | `50`    | Click hold duration        |
+| `double_click_gap_ms`  | `50`    | Double-click gap delay     |
+| `hover_settle_ms`      | `400`   | Hover settle wait          |
+| `drag_position_ms`     | `30`    | Pre-drag position wait     |
+| `drag_press_ms`        | `50`    | Drag press hold threshold  |
+| `drag_step_ms`         | `5`     | Between interpolation pts  |
+| `drag_settle_ms`       | `30`    | Settle before release      |
+| `drag_pixels_per_step` | `20`    | Point density per pixel    |
+| `drag_min_steps`       | `10`    | Min interpolation steps    |
+| `scroll_press_ms`      | `10`    | Scroll press-release gap   |
+| `scroll_tick_ms`       | `20`    | Inter-tick delay           |
+| `key_hold_ms`          | `30`    | Key hold duration          |
+| `combo_mod_ms`         | `10`    | Modifier settle delay      |
+| `type_key_ms`          | `20`    | Key hold during typing     |
+| `type_inter_key_ms`    | `20`    | Inter-character delay      |
+| `type_shift_ms`        | `10`    | Shift key settle           |
+| `paste_settle_ms`      | `30`    | Post-clipboard write wait  |
+
+---
+
+## Tools
+
+All operations are performed through a single `vnc_command` tool:
+
+### Screen
+
+| Action         | Parameters | Description                                |
+|----------------|------------|--------------------------------------------|
+| `screenshot`   |            | Full screen PNG capture                    |
+| `cursor_crop`  |            | Crop around cursor with crosshair overlay  |
+| `diff_check`   |            | Detect screen changes against baseline     |
+| `set_baseline` |            | Save current screen as diff reference      |
+
+### Mouse
+
+| Action               | Parameters                 | Description                    |
+|----------------------|----------------------------|--------------------------------|
+| `mouse_click`        | `x, y, button?`            | Click (left\|right\|middle)    |
+| `mouse_double_click` | `x, y`                     | Double click                   |
+| `mouse_move`         | `x, y`                     | Move cursor                    |
+| `hover`              | `x, y`                     | Move + settle wait             |
+| `nudge`              | `dx, dy`                   | Relative cursor movement       |
+| `mouse_drag`         | `x, y, toX, toY`           | Drag from start to end         |
+| `scroll`             | `x, y, direction, amount?` | Scroll (up\|down\|left\|right) |
+
+### Keyboard
+
+| Action      | Parameters        | Description                                                  |
+|-------------|-------------------|--------------------------------------------------------------|
+| `key_tap`   | `key`             | Single key press (enter\|escape\|tab\|space\|...)            |
+| `key_combo` | `key` or `keys`   | Modifier combo ("cmd+c" or ["cmd","shift","3"])              |
+| `key_type`  | `text`            | Type text character by character                             |
+| `paste`     | `text`            | Paste text via clipboard                                     |
+
+### Detection
+
+| Action            | Parameters | Description                                           |
+|-------------------|------------|-------------------------------------------------------|
+| `detect_elements` |            | OCR text detection with bounding boxes (Apple Vision) |
+
+Returns text elements with bounding box coordinates in scaled space:
+
+```json
+{"method":"detect_elements"}
+```
+```json
+{"result":{"detail":"13 elements","elements":[{"confidence":1,"h":9,"text":"Finder","w":32,"x":37,"y":6},{"confidence":1,"h":9,"text":"File","w":15,"x":84,"y":6},{"confidence":1,"h":9,"text":"Edit","w":19,"x":112,"y":6},{"confidence":1,"h":9,"text":"View","w":22,"x":143,"y":6},{"confidence":1,"h":11,"text":"Go","w":15,"x":179,"y":6},{"confidence":1,"h":9,"text":"Window","w":35,"x":207,"y":6},{"confidence":1,"h":11,"text":"Help","w":22,"x":255,"y":6},{"confidence":1,"h":11,"text":"8•","w":26,"x":1161,"y":6},{"confidence":1,"h":9,"text":"Fri Feb 20 22:19","w":80,"x":1189,"y":6},{"confidence":1,"h":9,"text":"Assets","w":32,"x":1202,"y":97},{"confidence":1,"h":9,"text":"Passwords.kdbx","w":74,"x":1181,"y":168},{"confidence":1,"h":93,"text":"PHANTOM","w":633,"x":322,"y":477},{"confidence":1,"h":32,"text":"YOUR SERVER, YOUR NETWORK, YOUR PRIVACY","w":629,"x":325,"y":568}],"scaledHeight":717,"scaledWidth":1280}}
+```
+
+### Configuration
+
+| Action       | Parameters      | Description                          |
+|--------------|-----------------|--------------------------------------|
+| `configure`  | `{<params>}`    | Set timing/display params at runtime |
+| `configure`  | `{reset: true}` | Reset all params to defaults         |
+| `get_timing` |                 | Get current timing + display params  |
+
+### Control
+
+| Action     | Parameters | Description                       |
+|------------|------------|-----------------------------------|
+| `wait`     | `ms?`      | Wait (default 500ms)              |
+| `health`   |            | Connection status + display info  |
+| `shutdown` |            | Graceful daemon shutdown          |
+
+---
+
+## Authentication
+
+Supported VNC authentication methods:
+
+- **VNC Auth** — password-based challenge-response (DES)
+- **ARD** — Apple Remote Desktop (Diffie-Hellman + AES-128-ECB)
+
+macOS is auto-detected via the ARD auth type 30 credential request. When detected, Meta keys are remapped to Super (Command key compatibility).
+
+---
+
+Copyright (c) 2026 Riza Emre ARAS — MIT License

package/index.js

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+/**
+ *  █████╗ ██████╗  █████╗ ███████╗
+ * ██╔══██╗██╔══██╗██╔══██╗██╔════╝
+ * ███████║██████╔╝███████║███████╗
+ * ██╔══██║██╔══██╗██╔══██║╚════██║
+ * ██║  ██║██║  ██║██║  ██║███████║
+ * ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝
+ *
+ * Copyright (c) 2026 Rıza Emre ARAS <r.emrearas@proton.me>
+ *
+ * This file is part of Claude KVM.
+ * Released under the MIT License — see LICENSE for details.
+ *
+ * MCP proxy server — spawns a native VNC daemon (claude-kvm-daemon)
+ * and exposes a single vnc_command tool to Claude.
+ * Communication: PC (Procedure Call) over stdin/stdout NDJSON.
+ */
+
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { vncCommandTool, actionQueueTool, controlTools } from './tools/index.js';
+
+// ── Configuration ───────────────────────────────────────────
+
+const env = (key, fallback) => process.env[key] ?? fallback;
+
+const DAEMON_PATH = env('CLAUDE_KVM_DAEMON_PATH', 'claude-kvm-daemon');
+const DAEMON_PARAMS = env('CLAUDE_KVM_DAEMON_PARAMETERS', '');
+const VNC_HOST = env('VNC_HOST', '127.0.0.1');
+const VNC_PORT = env('VNC_PORT', '5900');
+const VNC_USERNAME = env('VNC_USERNAME', '');
+const VNC_PASSWORD = env('VNC_PASSWORD', '');
+
+// ── Logging ─────────────────────────────────────────────────
+
+function log(msg) {
+  const ts = new Date().toISOString().slice(11, 23);
+  process.stderr.write(`[MCP ${ts}] ${msg}\n`);
+}
+
+// ── Daemon Process Manager ──────────────────────────────────
+
+let daemon = null;
+let daemonReady = false;
+const display = { width: 1280, height: 800 };
+const pendingRequests = new Map();
+let lineBuffer = '';
+
+function buildDaemonArgs() {
+  const args = ['--host', VNC_HOST, '--port', VNC_PORT];
+  if (VNC_USERNAME) args.push('--username', VNC_USERNAME);
+  if (VNC_PASSWORD) args.push('--password', VNC_PASSWORD);
+
+  // Extra parameters — passed directly to daemon CLI
+  if (DAEMON_PARAMS) {
+    const extra = DAEMON_PARAMS.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) || [];
+    args.push(...extra.map((s) => s.replace(/^['"]|['"]$/g, '')));
+  }
+
+  return args;
+}
+
+function spawnDaemon() {
+  const args = buildDaemonArgs();
+  log(`Spawning daemon: ${DAEMON_PATH} ${args.join(' ')}`);
+
+  daemon = spawn(DAEMON_PATH, args, {
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  daemon.stdout.on('data', (chunk) => {
+    lineBuffer += chunk.toString();
+    let idx;
+    while ((idx = lineBuffer.indexOf('\n')) !== -1) {
+      const line = lineBuffer.slice(0, idx).trim();
+      lineBuffer = lineBuffer.slice(idx + 1);
+      if (line) handleDaemonMessage(line);
+    }
+  });
+
+  daemon.stderr.on('data', (chunk) => {
+    process.stderr.write(chunk);
+  });
+
+  daemon.on('exit', (code) => {
+    log(`Daemon exited with code ${code}`);
+    daemonReady = false;
+    daemon = null;
+    for (const [, req] of pendingRequests) {
+      clearTimeout(req.timer);
+      req.reject(new Error('Daemon exited'));
+    }
+    pendingRequests.clear();
+  });
+
+  daemon.on('error', (err) => {
+    log(`Daemon spawn error: ${err.message}`);
+  });
+}
+
+function handleDaemonMessage(line) {
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    log(`Invalid daemon JSON: ${line}`);
+    return;
+  }
+
+  // PC notification — has method, no id
+  if (msg.method) {
+    const { scaledWidth, scaledHeight, state } = msg.params || {};
+    if (msg.method === 'ready') {
+      daemonReady = true;
+      if (scaledWidth) display.width = scaledWidth;
+      if (scaledHeight) display.height = scaledHeight;
+      log(`Daemon ready — display ${display.width}×${display.height}`);
+    } else if (msg.method === 'vnc_state') {
+      log(`VNC state: ${state}`);
+    }
+    return;
+  }
+
+  // PC response — has id
+  if (msg.id !== undefined && pendingRequests.has(msg.id)) {
+    const req = pendingRequests.get(msg.id);
+    pendingRequests.delete(msg.id);
+    clearTimeout(req.timer);
+    req.resolve(msg);
+  }
+}
+
+/**
+ * Send a PC request to the daemon and wait for response.
+ * @param {string} method - PC method name
+ * @param {object} [params] - Method parameters
+ * @param {number} [timeoutMs=30000] - Timeout in milliseconds
+ * @returns {Promise<object>} - Daemon PC response
+ */
+function sendRequest(method, params, timeoutMs = 30000) {
+  return new Promise((resolve, reject) => {
+    if (!daemon || !daemonReady) {
+      reject(new Error('Daemon not ready. Check CLAUDE_KVM_DAEMON_PATH and VNC credentials.'));
+      return;
+    }
+
+    const id = randomUUID();
+
+    const timer = setTimeout(() => {
+      pendingRequests.delete(id);
+      reject(new Error(`Daemon request timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    pendingRequests.set(id, { resolve, reject, timer });
+
+    const request = { method, id };
+    if (params && Object.keys(params).length > 0) request.params = params;
+
+    daemon.stdin.write(JSON.stringify(request) + '\n');
+  });
+}
+
+// ── Wait for daemon ready ───────────────────────────────────
+
+function waitForReady(timeoutMs = 30000) {
+  return new Promise((resolve, reject) => {
+    if (daemonReady) { resolve(); return; }
+
+    const interval = setInterval(() => {
+      if (daemonReady) {
+        clearInterval(interval);
+        clearTimeout(timer);
+        resolve();
+      }
+    }, 100);
+
+    const timer = setTimeout(() => {
+      clearInterval(interval);
+      reject(new Error('Daemon did not become ready within timeout'));
+    }, timeoutMs);
+  });
+}
+
+// ── Tool Execution ──────────────────────────────────────────
+
+async function executeVncCommand(input) {
+  const { action, ...params } = input;
+
+  const response = await sendRequest(action, params);
+
+  // PC error response
+  if (response.error) {
+    return {
+      content: [{ type: 'text', text: `Error: ${response.error.message}` }],
+      isError: true,
+    };
+  }
+
+  const { detail, image, x, y, scaledWidth, scaledHeight, elements, timing } = response.result || {};
+  const content = [];
+
+  // Text detail
+  if (detail) {
+    content.push({ type: 'text', text: detail });
+  }
+
+  // Image
+  if (image) {
+    content.push({ type: 'image', data: image, mimeType: 'image/png' });
+  }
+
+  // OCR elements (detect_elements)
+  if (elements) {
+    content.push({ type: 'text', text: JSON.stringify(elements) });
+  }
+
+  // Timing map (get_timing, configure with reset)
+  if (timing) {
+    content.push({ type: 'text', text: JSON.stringify(timing) });
+  }
+
+  // Cursor position (nudge, cursor_crop)
+  if (x !== undefined && y !== undefined) {
+    content.push({ type: 'text', text: `cursor: (${x}, ${y})` });
+  }
+
+  // Display dimensions (health, detect_elements, get_timing — no image)
+  if (scaledWidth !== undefined && !image) {
+    content.push({ type: 'text', text: `display: ${scaledWidth}×${scaledHeight}` });
+  }
+
+  if (content.length === 0) {
+    content.push({ type: 'text', text: 'OK' });
+  }
+
+  return { content };
+}
+
+async function executeActionQueue(input) {
+  const results = [];
+  for (let i = 0; i < input.actions.length; i++) {
+    const { action, ...params } = input.actions[i];
+    const response = await sendRequest(action, params);
+
+    if (response.error) {
+      results.push(`[${i + 1}] ${action}: ERROR — ${response.error.message}`);
+      break;
+    }
+
+    const detail = response.result?.detail;
+    results.push(`[${i + 1}] ${action}: ${detail || 'OK'}`);
+  }
+  return { content: [{ type: 'text', text: results.join('\n') }] };
+}
+
+// ── MCP Server ──────────────────────────────────────────────
+
+async function main() {
+  log('Claude KVM v1.0.0 — Native VNC proxy');
+
+  spawnDaemon();
+
+  const mcpServer = new McpServer(
+    { name: 'claude-kvm', version: '1.0.0' },
+    { capabilities: { tools: {} } },
+  );
+
+  try {
+    await waitForReady(30000);
+  } catch (err) {
+    log(`Warning: ${err.message} — registering with default dimensions`);
+  }
+
+  // Register vnc_command tool
+  const vncTool = vncCommandTool(display.width, display.height);
+  mcpServer.tool(
+    vncTool.name,
+    vncTool.inputSchema,
+    async (input) => {
+      try {
+        return await executeVncCommand(input);
+      } catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+      }
+    },
+  );
+
+  // Register action_queue tool
+  const queueTool = actionQueueTool(display.width, display.height);
+  mcpServer.tool(
+    queueTool.name,
+    queueTool.inputSchema,
+    async (input) => {
+      try {
+        return await executeActionQueue(input);
+      } catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+      }
+    },
+  );
+
+  // Register control tools
+  for (const tool of controlTools()) {
+    mcpServer.tool(
+      tool.name,
+      tool.inputSchema,
+      async (input) => {
+        if (tool.name === 'task_complete') {
+          return { content: [{ type: 'text', text: input.summary }] };
+        }
+        if (tool.name === 'task_failed') {
+          return { content: [{ type: 'text', text: input.reason }], isError: true };
+        }
+      },
+    );
+  }
+
+  const transport = new StdioServerTransport();
+  await mcpServer.connect(transport);
+  log('MCP server connected on stdio');
+
+  process.on('SIGINT', () => {
+    log('Shutting down...');
+    if (daemon) {
+      daemon.stdin.write(JSON.stringify({ method: 'shutdown' }) + '\n');
+      setTimeout(() => { daemon?.kill(); process.exit(0); }, 500);
+    } else {
+      process.exit(0);
+    }
+  });
+}
+
+main().catch((err) => {
+  log(`Fatal: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "claude-kvm",
+  "version": "2.0.0",
+  "description": "MCP server — control remote desktops via VNC (MacOS)",
+  "license": "MIT",
+  "author": "Rıza Emre ARAS <r.emrearas@proton.me>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ARAS-Workspace/claude-kvm.git"
+  },
+  "keywords": [
+    "mcp",
+    "vnc",
+    "kvm",
+    "claude",
+    "remote-desktop",
+    "automation",
+    "apple-silicon",
+    "native"
+  ],
+  "main": "index.js",
+  "bin": {
+    "claude-kvm": "index.js"
+  },
+  "files": [
+    "index.js",
+    "tools/",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.52.0",
+    "@types/node": "^25.2.3",
+    "dotenv": "^17.3.1"
+  }
+}

package/tools/index.js

@@ -0,0 +1,171 @@
+// SPDX-License-Identifier: MIT
+/**
+ *  █████╗ ██████╗  █████╗ ███████╗
+ * ██╔══██╗██╔══██╗██╔══██╗██╔════╝
+ * ███████║██████╔╝███████║███████╗
+ * ██╔══██║██╔══██╗██╔══██║╚════██║
+ * ██║  ██║██║  ██║██║  ██║███████║
+ * ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝
+ *
+ * Copyright (c) 2026 Rıza Emre ARAS <r.emrearas@proton.me>
+ *
+ * This file is part of Claude KVM.
+ * Released under the MIT License — see LICENSE for details.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Build vnc_command tool definition with display dimensions.
+ * @param {number} width  - Scaled display width
+ * @param {number} height - Scaled display height
+ */
+export function vncCommandTool(width, height) {
+  return {
+    name: 'vnc_command',
+    description: [
+      `Control a remote desktop via VNC. Display: ${width}×${height}px.`,
+      'All coordinates are in this scaled space.',
+      '',
+      'ACTIONS:',
+      '  screenshot                              → full screen PNG',
+      '  cursor_crop                             → crop around cursor with crosshair',
+      '  diff_check                              → detect screen changes since baseline',
+      '  set_baseline                            → save current screen for diff comparison',
+      '  mouse_click    {x, y, button?}          → click (left|right|middle)',
+      '  mouse_double_click {x, y}               → double click',
+      '  mouse_move     {x, y}                   → move cursor',
+      '  hover          {x, y}                   → move cursor + settle wait',
+      '  nudge          {dx, dy}                 → relative cursor move',
+      '  mouse_drag     {x, y, toX, toY}         → drag from start to end',
+      '  scroll         {x, y, direction, amount?} → scroll (up|down|left|right)',
+      '  key_tap        {key}                    → single key press (enter|escape|tab|space|...)',
+      '  key_combo      {key} or {keys:[...]}    → modifier combo (e.g. "cmd+c" or ["cmd","shift","3"])',
+      '  key_type       {text}                   → type text character by character',
+      '  paste          {text}                   → paste text via clipboard',
+      '  detect_elements                         → OCR text detection with bounding boxes',
+      '  configure      {<params>}               → set timing/display params at runtime',
+      '  configure      {reset: true}            → reset all params to defaults',
+      '  get_timing                              → get current timing + display params',
+      '  wait           {ms?}                    → pause (default 500ms)',
+      '  health                                  → connection status + display info',
+      '  shutdown                                → graceful daemon exit',
+      '',
+      'Use screenshot → analyze → act → verify pattern.',
+    ].join('\n'),
+    inputSchema: {
+      action: z.enum([
+        'screenshot', 'cursor_crop', 'diff_check', 'set_baseline',
+        'mouse_click', 'mouse_double_click', 'mouse_move', 'hover', 'nudge',
+        'mouse_drag', 'scroll',
+        'key_tap', 'key_combo', 'key_type', 'paste',
+        'detect_elements',
+        'configure', 'get_timing',
+        'wait', 'health', 'shutdown',
+      ]).describe('The action to perform'),
+      x: z.number().int().min(0).max(width - 1).optional().describe('X coordinate'),
+      y: z.number().int().min(0).max(height - 1).optional().describe('Y coordinate'),
+      toX: z.number().int().min(0).max(width - 1).optional().describe('Drag target X'),
+      toY: z.number().int().min(0).max(height - 1).optional().describe('Drag target Y'),
+      dx: z.number().int().min(-50).max(50).optional().describe('Relative X offset (nudge)'),
+      dy: z.number().int().min(-50).max(50).optional().describe('Relative Y offset (nudge)'),
+      button: z.enum(['left', 'right', 'middle']).optional().describe('Mouse button'),
+      key: z.string().optional().describe('Key name or combo string (e.g. "cmd+c")'),
+      keys: z.array(z.string()).optional().describe('Array of key names for combo (e.g. ["cmd","shift","3"])'),
+      text: z.string().optional().describe('Text to type or paste'),
+      direction: z.enum(['up', 'down', 'left', 'right']).optional().describe('Scroll direction'),
+      amount: z.number().int().min(1).max(20).optional().describe('Scroll amount (default 3)'),
+      ms: z.number().int().min(50).max(10000).optional().describe('Wait duration in ms (default 500)'),
+      // Configure params (runtime timing/display adjustment)
+      reset: z.boolean().optional().describe('Reset all params to defaults'),
+      max_dimension: z.number().int().min(320).max(3840).optional().describe('Max screenshot dimension'),
+      cursor_crop_radius: z.number().int().min(50).max(500).optional().describe('Cursor crop radius'),
+      click_hold_ms: z.number().int().min(1).max(500).optional().describe('Click hold duration'),
+      double_click_gap_ms: z.number().int().min(1).max(500).optional().describe('Double-click gap'),
+      hover_settle_ms: z.number().int().min(1).max(2000).optional().describe('Hover settle wait'),
+      drag_position_ms: z.number().int().min(1).max(500).optional().describe('Pre-drag position wait'),
+      drag_press_ms: z.number().int().min(1).max(500).optional().describe('Drag press hold'),
+      drag_step_ms: z.number().int().min(1).max(100).optional().describe('Between interpolation pts'),
+      drag_settle_ms: z.number().int().min(1).max(500).optional().describe('Settle before release'),
+      drag_pixels_per_step: z.number().min(1).max(100).optional().describe('Point density per pixel'),
+      drag_min_steps: z.number().int().min(1).max(100).optional().describe('Min interpolation steps'),
+      scroll_press_ms: z.number().int().min(1).max(200).optional().describe('Scroll press-release gap'),
+      scroll_tick_ms: z.number().int().min(1).max(200).optional().describe('Inter-tick delay'),
+      key_hold_ms: z.number().int().min(1).max(500).optional().describe('Key hold duration'),
+      combo_mod_ms: z.number().int().min(1).max(200).optional().describe('Modifier settle delay'),
+      type_key_ms: z.number().int().min(1).max(200).optional().describe('Key hold during typing'),
+      type_inter_key_ms: z.number().int().min(1).max(200).optional().describe('Inter-character delay'),
+      type_shift_ms: z.number().int().min(1).max(200).optional().describe('Shift key settle'),
+      paste_settle_ms: z.number().int().min(1).max(500).optional().describe('Post-clipboard write wait'),
+    },
+  };
+}
+
+/**
+ * Build action_queue tool definition with display dimensions.
+ * Executes multiple VNC actions in sequence, returns text-only results.
+ * @param {number} width  - Scaled display width
+ * @param {number} height - Scaled display height
+ */
+export function actionQueueTool(width, height) {
+  const queueAction = z.object({
+    action: z.enum([
+      'mouse_click', 'mouse_double_click', 'mouse_move', 'hover', 'nudge',
+      'mouse_drag', 'scroll',
+      'key_tap', 'key_combo', 'key_type', 'paste',
+      'set_baseline', 'diff_check',
+      'wait',
+    ]).describe('The action to perform'),
+    x: z.number().int().min(0).max(width - 1).optional().describe('X coordinate'),
+    y: z.number().int().min(0).max(height - 1).optional().describe('Y coordinate'),
+    toX: z.number().int().min(0).max(width - 1).optional().describe('Drag target X'),
+    toY: z.number().int().min(0).max(height - 1).optional().describe('Drag target Y'),
+    dx: z.number().int().min(-50).max(50).optional().describe('Relative X offset (nudge)'),
+    dy: z.number().int().min(-50).max(50).optional().describe('Relative Y offset (nudge)'),
+    button: z.enum(['left', 'right', 'middle']).optional().describe('Mouse button'),
+    key: z.string().optional().describe('Key name or combo string (e.g. "ctrl+c")'),
+    keys: z.array(z.string()).optional().describe('Array of key names for combo'),
+    text: z.string().optional().describe('Text to type or paste'),
+    direction: z.enum(['up', 'down', 'left', 'right']).optional().describe('Scroll direction'),
+    amount: z.number().int().min(1).max(20).optional().describe('Scroll amount (default 3)'),
+    ms: z.number().int().min(50).max(10000).optional().describe('Wait duration in ms (default 500)'),
+  });
+
+  return {
+    name: 'action_queue',
+    description: [
+      'Execute multiple VNC actions in sequence. Returns text results only (no screenshots).',
+      'Stops on first error. Use for batching confident action sequences.',
+      '',
+      'Examples:',
+      '  Navigate: [click(640,91), ctrl+a, paste("url"), return]',
+      '  Scroll:   [click(640,400), pagedown, pagedown, pagedown]',
+      '  Type:     [click(300,200), key_type("hello"), tab, key_type("world")]',
+    ].join('\n'),
+    inputSchema: {
+      actions: z.array(queueAction).min(1).max(20).describe('Ordered actions to execute sequentially'),
+    },
+  };
+}
+
+/**
+ * Control tools (task lifecycle).
+ */
+export function controlTools() {
+  return [
+    {
+      name: 'task_complete',
+      description: 'Mark the task as successfully completed. Provide a brief summary.',
+      inputSchema: {
+        summary: z.string().describe('What was accomplished'),
+      },
+    },
+    {
+      name: 'task_failed',
+      description: 'Mark the task as failed. Explain why.',
+      inputSchema: {
+        reason: z.string().describe('Why the task could not be completed'),
+      },
+    },
+  ];
+}