@beeos-ai/device-mcp-server 0.3.0 → 0.4.2

package/dist/server/registry.js

@@ -0,0 +1,191 @@
+/**
+ * BackendRegistry — manages multiple `SandboxBackend` instances inside a
+ * **single** device-mcp-server process.
+ *
+ * Replaces the legacy "one process per device" topology (mirrored from the
+ * `mobile-mcp` design): a single `device-mcp-server` discovers every adb device
+ * in the host's `adb devices` output and lazily wraps each one in an
+ * `AndroidAdbBackend`. Tool handlers resolve the right backend through three
+ * fallbacks (in priority order):
+ *
+ *   1. explicit `device` argument on the tool call (`device: "emulator-5554"`)
+ *   2. session-sticky default set via the `use_device` MCP tool (keyed by
+ *      `extra.sessionId`, only meaningful for stdio / single-session clients)
+ *   3. single-device shortcut: if exactly one device is connected, use it
+ *
+ * If none of the above resolves to a backend the registry throws
+ * `DeviceError("device required", subtype:"invalid_args")` so the MCP tool
+ * call returns a structured error instead of silently picking a random device.
+ *
+ * The registry also owns a periodic `adb devices` poll (default 10s) so newly
+ * plugged devices show up in `list_available_devices` without restarting the
+ * process. Connect-state validation per backend is lazy — backends are
+ * constructed with `skipConnectValidation: true` and only emit errors at
+ * tool-call time.
+ *
+ * Desktop / stub backends are registered up front (one each) and re-used
+ * across every session — the device id for a desktop backend is its
+ * `os` string (`"desktop-macos"`, `"desktop-linux"`, ...).
+ */
+import { DeviceError } from "@beeos-ai/device-common";
+import { listAdbDevices, AndroidAdbBackend } from "../backends/android-adb.js";
+export class BackendRegistry {
+    backends = new Map();
+    enableAdbDiscovery;
+    adbRunner;
+    pollIntervalMs;
+    androidDefaults;
+    pollTimer;
+    /**
+     * Per-session active-device map (only meaningful for stdio / single-session
+     * transports). For stateless HTTP `extra.sessionId` is undefined and this
+     * map is never written.
+     */
+    sessionDevice = new Map();
+    constructor(opts = {}) {
+        this.enableAdbDiscovery = opts.enableAdbDiscovery ?? true;
+        this.adbRunner = opts.adbRunner;
+        this.pollIntervalMs = opts.pollIntervalMs ?? 10_000;
+        this.androidDefaults = opts.androidDefaults;
+        for (const b of opts.initialBackends ?? []) {
+            // Static (desktop / stub) backends — id == os.
+            this.backends.set(b.os, b);
+        }
+        for (const serial of opts.initialAdbSerials ?? []) {
+            this.backends.set(serial, this.makeAdbBackend(serial));
+        }
+    }
+    /**
+     * Kick off the adb-discovery poll and run one immediate scan. Returns
+     * after the first scan completes (so callers can `await` and immediately
+     * see a populated `list()`).
+     *
+     * Idempotent — safe to call multiple times.
+     */
+    async start() {
+        if (!this.enableAdbDiscovery)
+            return;
+        await this.pollOnce().catch(() => {
+            /* swallow — next poll will surface errors as device disappearance */
+        });
+        if (this.pollTimer)
+            return;
+        this.pollTimer = setInterval(() => {
+            void this.pollOnce().catch(() => undefined);
+        }, this.pollIntervalMs);
+        // Don't keep the event loop alive for the poll alone.
+        this.pollTimer.unref?.();
+    }
+    /** Stop the discovery poll and disconnect every backend. */
+    async stop() {
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = undefined;
+        }
+        await Promise.all([...this.backends.values()].map((b) => b.disconnect().catch(() => undefined)));
+    }
+    /** Snapshot of every currently-known device. */
+    list() {
+        const ids = [...this.backends.keys()];
+        const isSingle = ids.length === 1;
+        return ids.map((id) => {
+            const b = this.backends.get(id);
+            return {
+                id,
+                os: b.os,
+                isDefault: isSingle,
+                source: b.os === "android" ? "adb" : "desktop",
+            };
+        });
+    }
+    /**
+     * Resolve a backend for a single tool call. `args.device` wins; if absent,
+     * fall back to the session-sticky `use_device` value; if also absent and
+     * exactly one backend is registered, use it. Otherwise throw with a clear
+     * "device required" error so the MCP client knows it must call
+     * `list_available_devices` / `use_device` first.
+     */
+    resolve(args, sessionId) {
+        const explicit = typeof args?.device === "string" ? args.device : undefined;
+        if (explicit) {
+            const b = this.backends.get(explicit);
+            if (!b) {
+                throw new DeviceError(`device '${explicit}' is not connected; call list_available_devices`, { subtype: "invalid_args", retriable: false });
+            }
+            return b;
+        }
+        if (sessionId) {
+            const sticky = this.sessionDevice.get(sessionId);
+            if (sticky) {
+                const b = this.backends.get(sticky);
+                if (b)
+                    return b;
+                // sticky reference is stale — drop it so the caller gets the
+                // "device required" message instead of a stale-id error.
+                this.sessionDevice.delete(sessionId);
+            }
+        }
+        if (this.backends.size === 1) {
+            return this.backends.values().next().value;
+        }
+        if (this.backends.size === 0) {
+            throw new DeviceError("no devices connected; plug in a device or call list_available_devices", { subtype: "no_device", retriable: true });
+        }
+        throw new DeviceError("multiple devices connected; pass `device: <id>` or call use_device first", { subtype: "invalid_args", retriable: false });
+    }
+    /** Set the session-sticky default device. Used by the `use_device` tool. */
+    useDevice(sessionId, deviceId) {
+        if (!this.backends.has(deviceId)) {
+            throw new DeviceError(`device '${deviceId}' is not connected; call list_available_devices`, { subtype: "invalid_args", retriable: false });
+        }
+        if (sessionId) {
+            this.sessionDevice.set(sessionId, deviceId);
+        }
+        else {
+            // No session = HTTP stateless. Treat as a no-op + structured error so
+            // clients learn the "always pass `device`" rule explicitly.
+            throw new DeviceError("use_device has no effect over stateless HTTP — pass `device` on every tool call instead", { subtype: "invalid_args", retriable: false });
+        }
+    }
+    async pollOnce() {
+        let serials = [];
+        try {
+            serials = await listAdbDevices(this.adbRunner);
+        }
+        catch {
+            // adb unavailable on this host — nothing to add. Static (desktop)
+            // backends seeded at construction time stay registered.
+            return;
+        }
+        const seen = new Set(serials);
+        for (const serial of serials) {
+            if (!this.backends.has(serial)) {
+                this.backends.set(serial, this.makeAdbBackend(serial));
+            }
+        }
+        // Prune adb backends whose devices have disappeared. Static (desktop)
+        // backends are never adb serials so they're untouched by this sweep.
+        for (const [id, backend] of this.backends.entries()) {
+            if (backend.os === "android" && !seen.has(id)) {
+                this.backends.delete(id);
+                backend.disconnect().catch(() => undefined);
+                // Drop session-sticky pointers to the removed device.
+                for (const [sid, dev] of this.sessionDevice.entries()) {
+                    if (dev === id)
+                        this.sessionDevice.delete(sid);
+                }
+            }
+        }
+    }
+    makeAdbBackend(serial) {
+        return new AndroidAdbBackend({
+            ...this.androidDefaults,
+            serial,
+            // Lazy connect — discovery already proved the device is in `adb
+            // devices`, so a per-backend `adb devices` validation is redundant
+            // and would add startup latency proportional to device count.
+            skipConnectValidation: true,
+        });
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/server/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/server/registry.ts"],"names":[],"mappings":"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"}

package/dist/server/stdio.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Stdio transport for `device-mcp-server`.
+ *
+ * Used when the server is launched as a child process by an MCP client
+ * (Cursor, Claude Desktop, custom orchestrators). Single persistent
+ * connection over stdin/stdout — `extra.sessionId` is stable for the
+ * lifetime of the process so `use_device` / `list_available_devices`
+ * give a `mobile-mcp`-style stateful UX.
+ *
+ * IMPORTANT: nothing may write to stdout in stdio mode — that channel
+ * is reserved for JSON-RPC frames. All logging goes through `stderr`
+ * via `util/logger`. The `runStdio()` function intentionally does NOT
+ * `console.log` or `process.stdout.write` anything.
+ */
+import type { BackendRegistry } from "./registry.js";
+import { type Logger } from "../util/logger.js";
+export interface RunStdioOptions {
+    registry: BackendRegistry;
+    name?: string;
+    version?: string;
+    logger?: Logger;
+}
+/**
+ * Connect a fresh `McpServer` to stdin/stdout. Resolves once the
+ * transport is wired up — the process keeps running because the SDK
+ * holds the stdin readable open. Callers should let `process.exit`
+ * happen naturally on stdin EOF.
+ */
+export declare function runStdio(opts: RunStdioOptions): Promise<void>;

package/dist/server/stdio.js

@@ -0,0 +1,35 @@
+/**
+ * Stdio transport for `device-mcp-server`.
+ *
+ * Used when the server is launched as a child process by an MCP client
+ * (Cursor, Claude Desktop, custom orchestrators). Single persistent
+ * connection over stdin/stdout — `extra.sessionId` is stable for the
+ * lifetime of the process so `use_device` / `list_available_devices`
+ * give a `mobile-mcp`-style stateful UX.
+ *
+ * IMPORTANT: nothing may write to stdout in stdio mode — that channel
+ * is reserved for JSON-RPC frames. All logging goes through `stderr`
+ * via `util/logger`. The `runStdio()` function intentionally does NOT
+ * `console.log` or `process.stdout.write` anything.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildMcpServer } from "./mcp-server.js";
+import { stderrLogger } from "../util/logger.js";
+/**
+ * Connect a fresh `McpServer` to stdin/stdout. Resolves once the
+ * transport is wired up — the process keeps running because the SDK
+ * holds the stdin readable open. Callers should let `process.exit`
+ * happen naturally on stdin EOF.
+ */
+export async function runStdio(opts) {
+    const log = opts.logger ?? stderrLogger;
+    const server = buildMcpServer({
+        registry: opts.registry,
+        name: opts.name,
+        version: opts.version,
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    log.info?.({ name: opts.name ?? "device-mcp-server", version: opts.version }, "stdio_ready");
+}
+//# sourceMappingURL=stdio.js.map

package/dist/server/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/server/stdio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,YAAY,EAAe,MAAM,mBAAmB,CAAC;AAS9D;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAqB;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,IAAI,YAAY,CAAC;IACxC,MAAM,MAAM,GAAG,cAAc,CAAC;QAC5B,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,GAAG,CAAC,IAAI,EAAE,CACR,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,mBAAmB,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EACjE,aAAa,CACd,CAAC;AACJ,CAAC"}

package/dist/server/tool-registry.d.ts

@@ -1,50 +1,75 @@
 /**
- * MCP tool registry — verbs exposed by the device sandbox.
+ * SDK-style tool catalogue for device-mcp-server.
  *
- * Each tool entry carries:
- *  - a name (the MCP tool identifier, e.g. `click`)
- *  - a JSON schema describing the expected `arguments` payload
- *  - a `handler` that maps `arguments` → `SandboxBackend` method call.
+ * Each tool is a `ToolSpec` describing:
+ *   - `name`              MCP tool identifier (`screenshot`, `tap`, ...)
+ *   - `description`       human-readable verb
+ *   - `inputShape`        zod raw shape — every shape gets an implicit
+ *                         `device?: z.string().optional()` injected by
+ *                         `registerAllTools` so multi-device callers can
+ *                         target a specific backend per call
+ *   - `annotations`       `ToolAnnotations` (read-only / destructive /
+ *                         idempotent / open-world hints)
+ *   - `requires`          MCP tool name the resolved backend must declare
+ *                         in `backend.tools`. Tools with `requires:
+ *                         "registry"` are registry-level (don't touch a
+ *                         backend) — used for `list_available_devices` /
+ *                         `use_device`.
+ *   - `handler`           async `(args, ctx) => CallToolResult`
  *
- * Filtering is driven entirely by `backend.tools` (a flat
- * `ReadonlySet<string>` declared on each backend). The registry is
- * purely a name → schema/handler lookup table; it does not encode
- * support gates of its own. `listToolDescriptorsFor(backend)` filters
- * via `backend.tools.has(name)`; `getToolFor(name, backend)` mirrors
- * the same gate so `/mcp/tools/call` returns 404 (instead of 200 +
- * runtime `unsupported`) for any tool the active backend doesn't
- * advertise.
+ * `registerAllTools(server, registry)` iterates the catalogue and calls
+ * `server.registerTool` for each entry. The handler closure captures the
+ * registry so it can resolve the per-call backend via `registry.resolve`.
  *
- * Inspired by the Python `mcp_tools/registry.py` reference; verbs are kept
- * verbatim for cross-runtime compatibility.
+ * Returning shapes:
+ *   - Every handler returns `{ content, structuredContent }`. `content`
+ *     carries the human-friendly text summary (printable in MCP clients
+ *     like Claude Desktop / Cursor); `structuredContent` carries the
+ *     typed payload that programmatic callers (`device-agent`) parse.
  */
-import type { ToolDescriptor } from "@beeos-ai/device-common";
+import { z } from "zod";
+import type { CallToolResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { SandboxBackend } from "../backends/base.js";
+import type { BackendRegistry } from "./registry.js";
+/** Backend reference passed into handlers for backend-bound tools. */
 export interface ToolHandlerContext {
     backend: SandboxBackend;
+    registry: BackendRegistry;
+    sessionId?: string;
 }
-export type ToolHandler = (args: Record<string, unknown>, ctx: ToolHandlerContext) => Promise<unknown>;
-export interface ToolEntry {
-    descriptor: ToolDescriptor;
+export type ToolHandler = (args: Record<string, unknown>, ctx: ToolHandlerContext) => Promise<CallToolResult>;
+export interface ToolSpec {
+    name: string;
+    description: string;
+    /** Zod raw shape (NO `device` — the registrar injects it automatically). */
+    inputShape: z.ZodRawShape;
+    annotations?: ToolAnnotations;
+    /**
+     * Backend tool gate. Either an MCP tool name (must appear in
+     * `backend.tools`) or `"registry"` for registry-level tools that don't
+     * need a backend at all.
+     */
+    requires: string | "registry";
     handler: ToolHandler;
 }
-export declare const TOOLS: Record<string, ToolEntry>;
+export declare const TOOL_SPECS: ToolSpec[];
 /**
- * Return ALL registered tool descriptors regardless of backend support.
- *
- * Useful for documentation / tests that want to enumerate the catalog.
- * Wire callers SHOULD use `listToolDescriptorsFor(backend)` so the list
- * only contains tools the active backend can actually execute.
+ * Look up a tool spec by name. Used by tests / introspection — production
+ * code goes through `registerAllTools(server, registry)`.
  */
-export declare function listToolDescriptors(): ToolDescriptor[];
-/** Return tool descriptors filtered by the backend's advertised tool set. */
-export declare function listToolDescriptorsFor(backend: SandboxBackend): ToolDescriptor[];
-/** Look up a tool by name, ignoring backend tool-set gates. */
-export declare function getTool(name: string): ToolEntry | undefined;
+export declare function getToolSpec(name: string): ToolSpec | undefined;
+/** Ordered list of every tool name advertised by the server. */
+export declare function allToolNames(): string[];
 /**
- * Look up a tool by name, **gated** on the backend's advertised tool
- * set. Returns `undefined` for tools the active backend cannot
- * satisfy — the `/mcp/tools/call` route uses this and returns 404,
- * mirroring the filtering applied at `/mcp/tools/list`.
+ * Register every tool spec onto the given `McpServer`. Each handler closure
+ * captures the registry so per-call backend resolution stays inside the
+ * tool layer (the SDK itself is backend-agnostic).
+ *
+ * Backend-bound tools are gated on the resolved backend's `tools` set —
+ * if the active backend doesn't advertise the tool we throw a
+ * `DeviceError("unsupported")` so the SDK returns a structured error to
+ * the client. Registry-level tools (`list_available_devices`,
+ * `use_device`) skip this gate.
  */
-export declare function getToolFor(name: string, backend: SandboxBackend): ToolEntry | undefined;
+export declare function registerAllTools(server: McpServer, registry: BackendRegistry): void;