watcher-mcp 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Watcher Contributors
+
+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,140 @@
+# watcher-mcp
+
+MCP server that gives AI agents real-world perception through the [Watcher](https://github.com/AAswordman/Watcher) Android app gateway.
+
+## What it does
+
+- Discovers Watcher devices on the local network
+- Binds a device and caches connection details
+- Reads gateway capabilities and health
+- Captures live camera snapshots
+- Creates and manages monitoring/analysis tasks
+- Polls task events and commentary state
+
+## What it does not do
+
+- Desktop automation (Git, file ops, lock screen)
+- Replace the agent's own terminal or OS tools
+- Hardcode scenario-specific workflows
+
+Watcher is the agent's **eyes**, not its hands.
+
+## Install
+
+```bash
+npm install -g watcher-mcp
+```
+
+Or use without installing:
+
+```bash
+npx -y watcher-mcp
+```
+
+## Configure with Claude Code
+
+One command:
+
+```bash
+claude mcp add --transport stdio watcher -- npx -y watcher-mcp
+```
+
+Or add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "watcher": {
+      "command": "npx",
+      "args": ["-y", "watcher-mcp"]
+    }
+  }
+}
+```
+
+## Configure with Codex
+
+```bash
+codex mcp add watcher -- npx -y watcher-mcp
+```
+
+Or in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.watcher]
+command = "npx"
+args = ["-y", "watcher-mcp"]
+```
+
+## Requirements
+
+- Node.js 18+
+- Watcher app running on an Android device with gateway enabled
+- Phone and computer on the same LAN
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `watcher_discover_devices` | Find Watcher devices on LAN via mDNS + subnet scan |
+| `watcher_bind_device` | Pair with a device using its URL and API key |
+| `watcher_get_device` | Read device identity and health |
+| `watcher_get_capabilities` | Read the gateway protocol contract |
+| `watcher_capture_snapshot` | Get current camera frame as JPEG |
+| `watcher_create_task` | Create a monitor or video_analysis task |
+| `watcher_list_tasks` | List recent tasks |
+| `watcher_get_task` | Get one task with status and events |
+| `watcher_list_task_events` | Poll task events incrementally |
+| `watcher_wait_for_condition` | Block until a matching event fires |
+| `watcher_cancel_task` | Cancel a running task |
+| `watcher_get_commentary_state` | Read live commentary state |
+| `watcher_list_commentary_entries` | Read commentary entries |
+
+## Typical flow
+
+```
+1. User: "备份项目当我离开工位"
+2. Agent → watcher_bind_device (if not cached)
+3. Agent → watcher_create_task (monitor: "detect user leaving desk")
+4. Agent → watcher_wait_for_condition (eventDataContains: "ALERT")
+5. Watcher detects user left
+6. Agent → git add && git commit && git push (using its own tools)
+7. Agent → watcher_cancel_task
+```
+
+## Local state
+
+Device bindings are cached at `~/.watcher-mcp/devices.json`. This file contains your API keys — do not share it.
+
+## Development
+
+```bash
+git clone https://github.com/AAswordman/Watcher.git
+cd Watcher/mcp
+npm install
+npm run check   # syntax validation
+npm test        # integration tests (31 assertions)
+```
+
+For local development, use a direct path in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "watcher": {
+      "command": "node",
+      "args": ["./mcp/server.js"]
+    }
+  }
+}
+```
+
+## Known limitations
+
+- Enterprise networks may block phone-to-computer communication
+- mDNS discovery depends on network multicast support
+- The gateway is designed for trusted LAN use, not public internet
+
+## License
+
+MIT

package/lib/discovery.js

@@ -0,0 +1,183 @@
+import os from "node:os";
+import { Bonjour } from "bonjour-service";
+import { loadDevices } from "./state.js";
+
+const PROBE_TIMEOUT_MS = 1500;
+
+function isPrivateIpv4(address) {
+  return address.startsWith("10.") || address.startsWith("192.168.") || /^172\.(1[6-9]|2\d|3[0-1])\./.test(address);
+}
+
+function enumerateCandidateHosts() {
+  const candidates = new Set();
+  const interfaces = os.networkInterfaces();
+  for (const iface of Object.values(interfaces)) {
+    for (const entry of iface || []) {
+      if (entry.family !== "IPv4" || entry.internal || !isPrivateIpv4(entry.address)) {
+        continue;
+      }
+      const octets = entry.address.split(".");
+      const prefix = `${octets[0]}.${octets[1]}.${octets[2]}`;
+      for (let host = 1; host <= 254; host += 1) {
+        if (host === Number(octets[3])) {
+          continue;
+        }
+        candidates.add(`${prefix}.${host}`);
+      }
+    }
+  }
+  return Array.from(candidates);
+}
+
+async function probeHealth(baseUrl) {
+  try {
+    const response = await fetch(`${baseUrl}/api/health`, {
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS)
+    });
+    if (!response.ok) return null;
+    const payload = await response.json();
+    const health = payload.data ?? payload;
+    if (health.status !== "ok") return null;
+    return { baseUrl, health };
+  } catch {
+    return null;
+  }
+}
+
+async function probeIdentity(baseUrl) {
+  try {
+    const response = await fetch(`${baseUrl}/api/device/identity`, {
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS)
+    });
+    if (!response.ok) return null;
+    const payload = await response.json();
+    return payload.data ?? payload;
+  } catch {
+    return null;
+  }
+}
+
+async function probeFull(baseUrl) {
+  const health = await probeHealth(baseUrl);
+  if (!health) return null;
+  const identity = await probeIdentity(baseUrl);
+  return { baseUrl, health: health.health, identity, source: "http_probe" };
+}
+
+export async function discoverDevices({ timeoutMs = 5000, ports = [8080, 8081, 8090] } = {}) {
+  const results = [];
+  const seen = new Set();
+  const diagnostics = {
+    cachedProbe: { attempted: false, hit: false },
+    mdns: { attempted: true, servicesSeen: 0 },
+    subnetScan: { attempted: false, candidateCount: 0, scannedCount: 0 }
+  };
+
+  // Phase 0: Try cached/known devices first (instant)
+  const cached = loadDevices();
+  if (cached.length > 0) {
+    diagnostics.cachedProbe.attempted = true;
+    const cachedProbes = await Promise.all(
+      cached.map((d) => probeFull(d.baseUrl))
+    );
+    for (const result of cachedProbes) {
+      if (result) {
+        diagnostics.cachedProbe.hit = true;
+        seen.add(result.baseUrl);
+        results.push({ ...result, source: "cached" });
+      }
+    }
+    if (results.length > 0) {
+      return { devices: results, diagnostics };
+    }
+  }
+
+  // Phase 1: mDNS + subnet scan in parallel, hard timeout wins
+  const abort = new AbortController();
+  const timer = setTimeout(() => abort.abort(), timeoutMs);
+
+  const [mdnsResult, scanResult] = await Promise.all([
+    mdnsDiscover(timeoutMs, seen, diagnostics, abort.signal),
+    subnetScan(ports, seen, diagnostics, abort.signal)
+  ]);
+
+  clearTimeout(timer);
+
+  if (mdnsResult) results.push(mdnsResult);
+  if (scanResult) results.push(scanResult);
+
+  return { devices: results, diagnostics };
+}
+
+async function mdnsDiscover(timeoutMs, seen, diagnostics, abortSignal) {
+  return new Promise((resolve) => {
+    let resolved = false;
+    const bonjour = new Bonjour();
+    const browser = bonjour.find({ type: "watcher" });
+
+    const cleanup = () => {
+      browser.stop();
+      bonjour.destroy();
+    };
+
+    const done = (value) => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      cleanup();
+      resolve(value);
+    };
+
+    const timer = setTimeout(() => done(null), timeoutMs);
+    abortSignal?.addEventListener("abort", () => done(null), { once: true });
+
+    browser.on("up", async (service) => {
+      diagnostics.mdns.servicesSeen += 1;
+      const host = service.referer?.address || service.addresses?.find((a) => a.includes("."));
+      const port = service.port;
+      if (!host || !port) return;
+
+      const baseUrl = `http://${host}:${port}`;
+      if (seen.has(baseUrl)) return;
+      seen.add(baseUrl);
+
+      const result = await probeFull(baseUrl);
+      if (result) {
+        done({
+          ...result,
+          source: "mdns",
+          mdns: { name: service.name, txt: service.txt || {} }
+        });
+      }
+    });
+  });
+}
+
+async function subnetScan(ports, seen, diagnostics, abortSignal) {
+  diagnostics.subnetScan.attempted = true;
+  const candidates = [];
+  for (const host of enumerateCandidateHosts()) {
+    for (const port of ports) {
+      const baseUrl = `http://${host}:${port}`;
+      if (!seen.has(baseUrl)) {
+        seen.add(baseUrl);
+        candidates.push(baseUrl);
+      }
+    }
+  }
+  diagnostics.subnetScan.candidateCount = candidates.length;
+
+  const concurrency = 128;
+  for (let i = 0; i < candidates.length; i += concurrency) {
+    if (abortSignal?.aborted) break;
+    const batch = candidates.slice(i, i + concurrency);
+    diagnostics.subnetScan.scannedCount += batch.length;
+    const probes = await Promise.all(batch.map(probeHealth));
+    const hit = probes.find((p) => p !== null);
+    if (hit) {
+      const identity = await probeIdentity(hit.baseUrl);
+      return { baseUrl: hit.baseUrl, health: hit.health, identity, source: "subnet_scan" };
+    }
+  }
+  return null;
+}

package/lib/gateway-client.js

@@ -0,0 +1,145 @@
+function buildHeaders({ apiKey, bindingToken, accept } = {}) {
+  const headers = {};
+  if (apiKey) {
+    headers["X-API-Key"] = apiKey;
+  }
+  if (bindingToken) {
+    headers.Authorization = `Bearer ${bindingToken}`;
+  }
+  if (accept) {
+    headers.Accept = accept;
+  }
+  return headers;
+}
+
+async function parseResponse(response) {
+  const contentType = response.headers.get("content-type") || "";
+  if (contentType.includes("application/json")) {
+    const payload = await response.json();
+    return payload.data ?? payload;
+  }
+  const arrayBuffer = await response.arrayBuffer();
+  return {
+    rawBytesBase64: Buffer.from(arrayBuffer).toString("base64"),
+    mimeType: contentType || "application/octet-stream"
+  };
+}
+
+async function request(baseUrl, path, options = {}) {
+  const timeoutMs = options.timeoutMs || 10000;
+  delete options.timeoutMs;
+  const response = await fetch(`${baseUrl}${path}`, {
+    ...options,
+    signal: AbortSignal.timeout(timeoutMs)
+  });
+  const payload = await parseResponse(response);
+  if (!response.ok) {
+    const error = new Error(payload.error || `HTTP ${response.status}`);
+    error.status = response.status;
+    error.payload = payload;
+    throw error;
+  }
+  return payload;
+}
+
+function withQuery(path, query = {}) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined && value !== null && value !== "") {
+      params.set(key, String(value));
+    }
+  }
+  const qs = params.toString();
+  return qs ? `${path}?${qs}` : path;
+}
+
+export async function fetchHealth(baseUrl) {
+  return request(baseUrl, "/api/health");
+}
+
+export async function fetchIdentity(baseUrl) {
+  return request(baseUrl, "/api/device/identity");
+}
+
+export async function fetchCapabilities({ baseUrl, apiKey }) {
+  return request(baseUrl, "/api/capabilities", {
+    headers: buildHeaders({ apiKey })
+  });
+}
+
+export async function pairDevice({ baseUrl, apiKey, bridgeId, bridgeName }) {
+  return request(baseUrl, "/api/device/pair", {
+    method: "POST",
+    headers: {
+      ...buildHeaders({ apiKey }),
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ bridgeId, bridgeName })
+  });
+}
+
+export async function fetchSnapshot({ baseUrl, apiKey }) {
+  const payload = await request(baseUrl, "/api/stream/snapshot", {
+    headers: buildHeaders({ apiKey, accept: "image/jpeg" })
+  });
+  return {
+    mimeType: payload.mimeType,
+    dataUrl: `data:${payload.mimeType};base64,${payload.rawBytesBase64}`,
+    sizeBytes: Buffer.from(payload.rawBytesBase64, "base64").length
+  };
+}
+
+export async function createTask({ baseUrl, apiKey, payload }) {
+  return request(baseUrl, "/api/tasks", {
+    method: "POST",
+    headers: {
+      ...buildHeaders({ apiKey }),
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(payload)
+  });
+}
+
+export async function fetchTasks({ baseUrl, apiKey }) {
+  return request(baseUrl, "/api/tasks", {
+    headers: buildHeaders({ apiKey })
+  });
+}
+
+export async function fetchTask({ baseUrl, apiKey, taskId }) {
+  return request(baseUrl, `/api/tasks/${encodeURIComponent(taskId)}`, {
+    headers: buildHeaders({ apiKey })
+  });
+}
+
+export async function fetchTaskEvents({ baseUrl, apiKey, taskId, afterEventId, since }) {
+  return request(
+    baseUrl,
+    withQuery(`/api/tasks/${encodeURIComponent(taskId)}/events`, {
+      afterEventId,
+      since
+    }),
+    {
+      headers: buildHeaders({ apiKey })
+    }
+  );
+}
+
+export async function cancelTask({ baseUrl, apiKey, taskId }) {
+  return request(baseUrl, `/api/tasks/${encodeURIComponent(taskId)}`, {
+    method: "DELETE",
+    headers: buildHeaders({ apiKey })
+  });
+}
+
+export async function fetchCommentaryState({ baseUrl, apiKey }) {
+  return request(baseUrl, "/api/commentary/state", {
+    headers: buildHeaders({ apiKey })
+  });
+}
+
+export async function fetchCommentaryEntries({ baseUrl, apiKey, since }) {
+  return request(baseUrl, withQuery("/api/commentary/entries", { since }), {
+    headers: buildHeaders({ apiKey })
+  });
+}

package/lib/paths.js

@@ -0,0 +1,10 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const STATE_DIR = path.join(os.homedir(), ".watcher-mcp");
+export const DEVICES_FILE = path.join(STATE_DIR, "devices.json");
+
+export function ensureStateDir() {
+  fs.mkdirSync(STATE_DIR, { recursive: true });
+}

package/lib/state.js

@@ -0,0 +1,30 @@
+import fs from "node:fs";
+import {
+  ensureStateDir,
+  DEVICES_FILE
+} from "./paths.js";
+
+function readJson(filePath, fallback) {
+  ensureStateDir();
+  if (!fs.existsSync(filePath)) {
+    return fallback;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(filePath, value) {
+  ensureStateDir();
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+export function loadDevices() {
+  return readJson(DEVICES_FILE, []);
+}
+
+export function saveDevices(devices) {
+  writeJson(DEVICES_FILE, devices);
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "watcher-mcp",
+  "version": "0.3.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "MCP server that gives AI agents real-world perception through the Watcher Android app gateway",
+  "author": "Watcher Contributors",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AAswordman/Watcher.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://github.com/AAswordman/Watcher/tree/main/mcp#readme",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "watcher",
+    "ai-agent",
+    "vision",
+    "monitoring",
+    "android",
+    "gateway",
+    "iot"
+  ],
+  "bin": {
+    "watcher-mcp": "./server.js"
+  },
+  "files": [
+    "server.js",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node ./server.js",
+    "check": "node --check ./server.js && node --check ./lib/gateway-client.js && node --check ./lib/discovery.js",
+    "test": "node ./test/integration.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "bonjour-service": "^1.3.0"
+  }
+}

package/server.js

@@ -0,0 +1,521 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  fetchCapabilities,
+  fetchCommentaryEntries,
+  fetchCommentaryState,
+  fetchHealth,
+  fetchIdentity,
+  fetchTask,
+  fetchTaskEvents,
+  fetchTasks,
+  pairDevice,
+  createTask,
+  cancelTask,
+  fetchSnapshot
+} from "./lib/gateway-client.js";
+import { discoverDevices } from "./lib/discovery.js";
+import { loadDevices, saveDevices } from "./lib/state.js";
+
+const toolDefinitions = [
+  {
+    name: "watcher.discover_devices",
+    description: "Discover Watcher devices on the current LAN and return diagnostics.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        timeoutMs: { type: "integer", default: 2500 }
+      }
+    }
+  },
+  {
+    name: "watcher.bind_device",
+    description: "Bind one Watcher device using its baseUrl and API key.",
+    inputSchema: {
+      type: "object",
+      required: ["baseUrl", "apiKey"],
+      properties: {
+        baseUrl: { type: "string" },
+        apiKey: { type: "string" },
+        bridgeId: { type: "string", default: "watcher-mcp" },
+        bridgeName: { type: "string", default: "Watcher MCP" }
+      }
+    }
+  },
+  {
+    name: "watcher.get_device",
+    description: "Read one bound device's identity and health.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        deviceId: { type: "string" },
+        baseUrl: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "watcher.get_capabilities",
+    description: "Read the Watcher gateway capabilities contract.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        deviceId: { type: "string" },
+        baseUrl: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "watcher.capture_snapshot",
+    description: "Capture the current device frame as a base64 JPEG payload.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        deviceId: { type: "string" },
+        baseUrl: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "watcher.create_task",
+    description: "Create a Watcher task such as snapshot, monitor, or video_analysis.",
+    inputSchema: {
+      type: "object",
+      required: ["tool"],
+      properties: {
+        deviceId: { type: "string" },
+        baseUrl: { type: "string" },
+        tool: { type: "string" },
+        params: { type: "object", additionalProperties: true }
+      }
+    }
+  },
+  {
+    name: "watcher.list_tasks",
+    description: "List recent tasks on a Watcher device.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        deviceId: { type: "string" },
+        baseUrl: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "watcher.get_task",
+    description: "Read one task snapshot by id.",
+    inputSchema: {
+      type: "object",
+      required: ["taskId"],
+      properties: {
+        deviceId: { type: "string" },
+        baseUrl: { type: "string" },
+        taskId: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "watcher.list_task_events",
+    description: "List task events incrementally.",
+    inputSchema: {
+      type: "object",
+      required: ["taskId"],
+      properties: {
+        deviceId: { type: "string" },
+        baseUrl: { type: "string" },
+        taskId: { type: "string" },
+        afterEventId: { type: "integer" },
+        since: { type: "integer" }
+      }
+    }
+  },
+  {
+    name: "watcher.wait_for_condition",
+    description: "Poll a task until a matching event or terminal state is observed.",
+    inputSchema: {
+      type: "object",
+      required: ["taskId"],
+      properties: {
+        deviceId: { type: "string" },
+        baseUrl: { type: "string" },
+        taskId: { type: "string" },
+        eventType: { type: "string" },
+        eventDataContains: { type: "string" },
+        timeoutMs: { type: "integer", default: 120000 },
+        pollIntervalMs: { type: "integer", default: 3000 },
+        returnOnTerminal: { type: "boolean", default: true }
+      }
+    }
+  },
+  {
+    name: "watcher.cancel_task",
+    description: "Cancel a running Watcher task.",
+    inputSchema: {
+      type: "object",
+      required: ["taskId"],
+      properties: {
+        deviceId: { type: "string" },
+        baseUrl: { type: "string" },
+        taskId: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "watcher.get_commentary_state",
+    description: "Read current commentary and speech state.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        deviceId: { type: "string" },
+        baseUrl: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "watcher.list_commentary_entries",
+    description: "Read commentary entries, optionally incrementally.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        deviceId: { type: "string" },
+        baseUrl: { type: "string" },
+        since: { type: "integer" }
+      }
+    }
+  }
+];
+
+function asToolResult(payload) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2)
+      }
+    ]
+  };
+}
+
+function getStoredDevice(args = {}) {
+  const devices = loadDevices();
+  if (args.baseUrl) {
+    return devices.find((entry) => entry.baseUrl === args.baseUrl) || null;
+  }
+  if (args.deviceId) {
+    return devices.find((entry) => entry.deviceId === args.deviceId) || null;
+  }
+  return devices[devices.length - 1] || null;
+}
+
+function requireDevice(args = {}) {
+  const device = getStoredDevice(args);
+  if (!device) {
+    throw new Error("No bound Watcher device found. Run watcher.bind_device first.");
+  }
+  return device;
+}
+
+function withDevice(args = {}) {
+  const device = requireDevice(args);
+  return {
+    device,
+    baseUrl: args.baseUrl || device.baseUrl,
+    apiKey: device.apiKey
+  };
+}
+
+async function handleDiscover(args) {
+  return discoverDevices({ timeoutMs: args.timeoutMs || 2500 });
+}
+
+async function handleBind(args) {
+  const pairing = await pairDevice({
+    baseUrl: args.baseUrl,
+    apiKey: args.apiKey,
+    bridgeId: args.bridgeId || "watcher-mcp",
+    bridgeName: args.bridgeName || "Watcher MCP"
+  });
+  const [identity, health] = await Promise.all([
+    fetchIdentity(args.baseUrl),
+    fetchHealth(args.baseUrl)
+  ]);
+  const devices = loadDevices().filter((entry) => entry.deviceId !== pairing.deviceId && entry.baseUrl !== args.baseUrl);
+  devices.push({
+    bridgeId: pairing.bridgeId,
+    bridgeName: pairing.bridgeName,
+    deviceId: pairing.deviceId,
+    bindingToken: pairing.bindingToken,
+    baseUrl: args.baseUrl,
+    apiKey: args.apiKey,
+    identity,
+    health,
+    pairedAt: pairing.createdAt
+  });
+  saveDevices(devices);
+  return {
+    paired: pairing,
+    identity,
+    health,
+    storedDeviceCount: devices.length
+  };
+}
+
+async function handleGetDevice(args) {
+  const { device, baseUrl } = withDevice(args);
+  const [identity, health] = await Promise.all([
+    fetchIdentity(baseUrl),
+    fetchHealth(baseUrl)
+  ]);
+  const updatedDevices = loadDevices().map((entry) =>
+    entry.deviceId === device.deviceId ? { ...entry, identity, health, baseUrl } : entry
+  );
+  saveDevices(updatedDevices);
+  return {
+    deviceId: device.deviceId,
+    baseUrl,
+    identity,
+    health
+  };
+}
+
+async function handleCapabilities(args) {
+  const { device, baseUrl, apiKey } = withDevice(args);
+  const capabilities = await fetchCapabilities({ baseUrl, apiKey });
+  return {
+    deviceId: device.deviceId,
+    baseUrl,
+    capabilities
+  };
+}
+
+async function handleSnapshot(args) {
+  const { device, baseUrl, apiKey } = withDevice(args);
+  const snapshot = await fetchSnapshot({ baseUrl, apiKey });
+  return {
+    deviceId: device.deviceId,
+    baseUrl,
+    ...snapshot
+  };
+}
+
+async function handleCreateTask(args) {
+  const { device, baseUrl, apiKey } = withDevice(args);
+  const params = args.params && typeof args.params === "object" ? args.params : {};
+  const task = await createTask({
+    baseUrl,
+    apiKey,
+    payload: {
+      tool: args.tool,
+      ...params
+    }
+  });
+  return {
+    deviceId: device.deviceId,
+    baseUrl,
+    task
+  };
+}
+
+async function handleListTasks(args) {
+  const { device, baseUrl, apiKey } = withDevice(args);
+  const tasks = await fetchTasks({ baseUrl, apiKey });
+  return {
+    deviceId: device.deviceId,
+    baseUrl,
+    tasks
+  };
+}
+
+async function handleGetTask(args) {
+  const { device, baseUrl, apiKey } = withDevice(args);
+  const task = await fetchTask({ baseUrl, apiKey, taskId: args.taskId });
+  return {
+    deviceId: device.deviceId,
+    baseUrl,
+    task
+  };
+}
+
+async function handleListTaskEvents(args) {
+  const { device, baseUrl, apiKey } = withDevice(args);
+  const events = await fetchTaskEvents({
+    baseUrl,
+    apiKey,
+    taskId: args.taskId,
+    afterEventId: args.afterEventId,
+    since: args.since
+  });
+  return {
+    deviceId: device.deviceId,
+    baseUrl,
+    taskId: args.taskId,
+    events
+  };
+}
+
+function eventMatches(event, args) {
+  if (args.eventType && event.type !== args.eventType) {
+    return false;
+  }
+  if (args.eventDataContains) {
+    const haystack = JSON.stringify(event.data ?? event.payload ?? {});
+    if (!haystack.includes(args.eventDataContains)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+async function handleWaitForCondition(args) {
+  const { device, baseUrl, apiKey } = withDevice(args);
+  const timeoutMs = args.timeoutMs || 120000;
+  const pollIntervalMs = args.pollIntervalMs || 3000;
+  const returnOnTerminal = args.returnOnTerminal !== false;
+  const deadline = Date.now() + timeoutMs;
+  let afterEventId = 0;
+
+  while (Date.now() < deadline) {
+    const events = await fetchTaskEvents({
+      baseUrl,
+      apiKey,
+      taskId: args.taskId,
+      afterEventId
+    });
+    if (events.length > 0) {
+      afterEventId = Math.max(...events.map((entry) => entry.id || 0), afterEventId);
+      const matched = events.find((event) => eventMatches(event, args));
+      if (matched) {
+        return {
+          deviceId: device.deviceId,
+          baseUrl,
+          taskId: args.taskId,
+          matched: true,
+          reason: "event_match",
+          event: matched
+        };
+      }
+    }
+
+    const task = await fetchTask({ baseUrl, apiKey, taskId: args.taskId });
+    if (returnOnTerminal && ["Completed", "Failed", "Cancelled"].includes(task.status)) {
+      return {
+        deviceId: device.deviceId,
+        baseUrl,
+        taskId: args.taskId,
+        matched: false,
+        reason: "task_terminal",
+        task
+      };
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+  }
+
+  const finalTask = await fetchTask({ baseUrl, apiKey, taskId: args.taskId });
+  return {
+    deviceId: device.deviceId,
+    baseUrl,
+    taskId: args.taskId,
+    matched: false,
+    reason: "timeout",
+    task: finalTask
+  };
+}
+
+async function handleCancelTask(args) {
+  const { device, baseUrl, apiKey } = withDevice(args);
+  const result = await cancelTask({ baseUrl, apiKey, taskId: args.taskId });
+  return {
+    deviceId: device.deviceId,
+    baseUrl,
+    taskId: args.taskId,
+    result
+  };
+}
+
+async function handleCommentaryState(args) {
+  const { device, baseUrl, apiKey } = withDevice(args);
+  const state = await fetchCommentaryState({ baseUrl, apiKey });
+  return {
+    deviceId: device.deviceId,
+    baseUrl,
+    state
+  };
+}
+
+async function handleCommentaryEntries(args) {
+  const { device, baseUrl, apiKey } = withDevice(args);
+  const entries = await fetchCommentaryEntries({ baseUrl, apiKey, since: args.since });
+  return {
+    deviceId: device.deviceId,
+    baseUrl,
+    entries
+  };
+}
+
+const handlers = new Map([
+  ["watcher.discover_devices", handleDiscover],
+  ["watcher.bind_device", handleBind],
+  ["watcher.get_device", handleGetDevice],
+  ["watcher.get_capabilities", handleCapabilities],
+  ["watcher.capture_snapshot", handleSnapshot],
+  ["watcher.create_task", handleCreateTask],
+  ["watcher.list_tasks", handleListTasks],
+  ["watcher.get_task", handleGetTask],
+  ["watcher.list_task_events", handleListTaskEvents],
+  ["watcher.wait_for_condition", handleWaitForCondition],
+  ["watcher.cancel_task", handleCancelTask],
+  ["watcher.get_commentary_state", handleCommentaryState],
+  ["watcher.list_commentary_entries", handleCommentaryEntries]
+]);
+
+const server = new Server(
+  {
+    name: "watcher-mcp",
+    version: "0.2.0"
+  },
+  {
+    capabilities: {
+      tools: {}
+    }
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: toolDefinitions
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const name = request.params.name;
+  const args = request.params.arguments || {};
+  const handler = handlers.get(name);
+  if (!handler) {
+    return {
+      content: [{ type: "text", text: JSON.stringify({ error: `Unknown tool: ${name}` }) }],
+      isError: true
+    };
+  }
+  try {
+    return asToolResult(await handler(args));
+  } catch (err) {
+    const detail = {
+      error: err.message || String(err),
+      status: err.status || null,
+      tool: name
+    };
+    if (err.cause?.code === "UND_ERR_CONNECT_TIMEOUT" || err.name === "TimeoutError") {
+      detail.hint = "Device unreachable. Check network connectivity and that the Watcher gateway is running.";
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify(detail, null, 2) }],
+      isError: true
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);