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

package/dist/server/app.js

@@ -1,157 +1,201 @@
 /**
- * Fastify factory — `buildApp({ backend })` returns a configured `FastifyInstance`
- * with all routes wired up. Decoupled from `cli.ts` so unit tests can spin up
- * an in-process server with a mock backend.
+ * Express HTTP host for `device-mcp-server`'s Streamable HTTP transport.
  *
- * Routes (mirrors the Python `mcp_tools/server.py` reference):
- *   GET  /healthz             — liveness + backend OS + tool list
- *   POST /mcp/tools/list      — MCP tool discovery
- *   POST /mcp/tools/call      — invoke a single MCP tool
- *   POST /act                 — translate `Action` → tool call
- *   GET  /screen.png          — fast-path screenshot (no JSON envelope)
- *   GET  /events              — SSE event stream (placeholder, no consumers yet)
+ * 0.4.0 reshape: the previous Fastify routes (`/healthz`, `/mcp/tools/list`,
+ * `/mcp/tools/call`, `/act`, `/screen.png`, `/events`) are GONE. The only
+ * surface this app exposes is `POST /mcp` — the Streamable HTTP endpoint
+ * defined by the official MCP wire spec, hosted by
+ * `@modelcontextprotocol/sdk`'s `StreamableHTTPServerTransport`.
+ *
+ * Stateless mode is intentional:
+ *   - `sessionIdGenerator: undefined` → no session header, no in-memory
+ *     subscriber map, every POST is fully self-contained.
+ *   - GET / DELETE on `/mcp` return 405 — those verbs only make sense in
+ *     stateful (subscribe-for-notifications) mode which we don't use.
+ *   - The transport is recreated per request so concurrent calls don't
+ *     trip over a shared `_initialized` flag (this matches the SDK
+ *     stateless example in the README).
+ *
+ * Auth (0.4.1): the loopback server still binds to `127.0.0.1` by
+ * default and is safe in that posture. When the operator exposes it on
+ * a routable interface (`--host 0.0.0.0`, container forwarding, …) two
+ * defence-in-depth gates kick in:
+ *
+ *   - `BEEOS_DEVICE_AUTH=<token>` → `Authorization: Bearer <token>` is
+ *     required on every `POST /mcp`. Constant-time compared so the
+ *     check doesn't leak length differences.
+ *   - `BEEOS_DEVICE_ALLOWED_ORIGINS=https://a,https://b` → if the
+ *     incoming request carries an `Origin` header it must match one of
+ *     the listed origins. Browser callers without an origin (curl /
+ *     server-to-server) are still allowed unless `BEEOS_DEVICE_REQUIRE_ORIGIN=1`.
+ *
+ * Both are optional — leaving them unset preserves the legacy "loopback
+ * is trusted" stance.
  */
-import Fastify from "fastify";
-import { AcpError, DeviceError, VlmError, } from "@beeos-ai/device-common";
-import { mapActionToTool } from "./action-mapping.js";
-import { getToolFor, listToolDescriptorsFor } from "./tool-registry.js";
-export async function buildApp(opts) {
-    const app = Fastify({
-        logger: opts.logger ?? true,
-        bodyLimit: opts.bodyLimit ?? 16 * 1024 * 1024,
+import express from "express";
+import { randomUUID, timingSafeEqual } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { buildMcpServer } from "./mcp-server.js";
+import { stderrLogger } from "../util/logger.js";
+export function buildApp(opts) {
+    const log = opts.logger ?? stderrLogger;
+    const app = express();
+    app.use(express.json({ limit: opts.bodyLimit ?? 16 * 1024 * 1024 }));
+    // Per-request request id for log correlation (matches Fastify's old
+    // `reqId` semantic). Falls through if upstream proxies set their own.
+    app.use((req, _res, next) => {
+        req.reqId =
+            req.headers["x-request-id"] ?? randomUUID();
+        next();
     });
-    app.setErrorHandler((err, _req, reply) => {
-        if (err instanceof DeviceError) {
-            const status = err.subtype === "unsupported" ? 501 : err.subtype === "invalid_args" ? 400 : 500;
-            reply
-                .status(status)
-                .send({ error: err.message, subtype: err.subtype, retriable: err.retriable });
-            return;
-        }
-        if (err instanceof AcpError) {
-            reply.status(400).send({ error: err.message, code: err.code });
-            return;
+    // ── Auth + CORS gate ───────────────────────────────────────────────────
+    // Resolve config from explicit opts > env. We intentionally read env
+    // here (not in module top-level) so tests can manipulate the env
+    // between buildApp() calls.
+    const expectedToken = opts.authToken ?? process.env.BEEOS_DEVICE_AUTH ?? "";
+    const allowedOriginsRaw = opts.allowedOrigins ?? process.env.BEEOS_DEVICE_ALLOWED_ORIGINS ?? "";
+    const allowedOrigins = parseOriginList(allowedOriginsRaw);
+    const requireOrigin = opts.requireOrigin ?? process.env.BEEOS_DEVICE_REQUIRE_ORIGIN === "1";
+    app.use("/mcp", (req, res, next) => {
+        const reqId = req.reqId;
+        // 1) Origin allow-list. We only enforce when the operator has set
+        //    an explicit allow-list — otherwise loopback callers without
+        //    an Origin header (Cursor, Claude Desktop) keep working.
+        if (allowedOrigins.length > 0) {
+            const origin = req.headers.origin?.trim();
+            if (!origin) {
+                if (requireOrigin) {
+                    log.warn?.({ reqId }, "device_mcp_origin_missing");
+                    return jsonRpcError(res, 403, -32001, "Origin header required");
+                }
+            }
+            else if (!allowedOrigins.includes(origin)) {
+                log.warn?.({ reqId, origin }, "device_mcp_origin_rejected");
+                return jsonRpcError(res, 403, -32001, `Origin '${origin}' is not in the allow-list`);
+            }
         }
-        if (err instanceof VlmError) {
-            reply.status(400).send({ error: err.message, retriable: err.retriable });
-            return;
+        // 2) Bearer auth. Constant-time compare so a wrong-length / wrong
+        //    bytes attempt doesn't leak information through timing.
+        if (expectedToken) {
+            const presented = parseBearer(req.headers.authorization);
+            if (!presented || !constantTimeEquals(presented, expectedToken)) {
+                log.warn?.({ reqId }, "device_mcp_auth_rejected");
+                return jsonRpcError(res, 401, -32001, "Invalid bearer token");
+            }
         }
-        reply.status(500).send({ error: err?.message ?? "internal error" });
-    });
-    /* ---------- /healthz ---------- */
-    app.get("/healthz", async () => {
-        return {
-            ok: true,
-            // Wire field name kept as `backend` even though the source is
-            // now `os` rather than `family`. Values are unchanged
-            // (`"android"` / `"desktop-macos"` / etc) — see the BackendOs
-            // taxonomy in @beeos-ai/device-common/backend.ts.
-            backend: opts.backend.os,
-            version: process.env.npm_package_version ?? "0.2.0",
-            // Tool-set-filtered list — agents that pick a tool out of this
-            // list are guaranteed it'll dispatch on the active backend.
-            tools: listToolDescriptorsFor(opts.backend).map((t) => t.name),
-        };
-    });
-    /* ---------- /mcp/tools/list ---------- */
-    const toolListHandler = async () => ({
-        tools: listToolDescriptorsFor(opts.backend),
+        next();
     });
-    app.get("/mcp/tools/list", toolListHandler);
-    app.post("/mcp/tools/list", toolListHandler);
-    /* ---------- /mcp/tools/call ---------- */
-    app.post("/mcp/tools/call", async (req, reply) => {
-        const { name, arguments: args = {} } = req.body ?? {};
-        if (!name || typeof name !== "string") {
-            reply.status(400).send({ error: "missing tool name" });
-            return;
-        }
-        const tool = getToolFor(name, opts.backend);
-        if (!tool) {
-            // Either the tool is unknown OR the backend lacks the required
-            // capability — collapse both to 404 so MCP clients reading
-            // `/mcp/tools/list` cannot bypass the filter via direct call.
-            reply.status(404).send({ error: `unknown tool '${name}'` });
-            return;
-        }
-        const startedAt = Date.now();
+    // ── POST /mcp ──────────────────────────────────────────────────────────
+    // SDK stateless mode: spin up a fresh transport per request, hand it
+    // to the McpServer, and let `transport.handleRequest` turn the Express
+    // (req, res, body) trio into JSON-RPC.
+    app.post("/mcp", async (req, res) => {
+        const reqId = req.reqId;
         try {
-            const result = await tool.handler(args, { backend: opts.backend });
-            const response = {
-                ok: true,
-                tool: name,
-                durationMs: Date.now() - startedAt,
-                result,
-            };
-            reply.send(response);
+            const server = buildMcpServer({
+                registry: opts.registry,
+                name: opts.name,
+                version: opts.version,
+            });
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined, // stateless
+                enableJsonResponse: true,
+            });
+            // Make sure the per-request server/transport are released as soon
+            // as the response closes — otherwise we leak one McpServer per
+            // call.
+            res.on("close", () => {
+                transport.close().catch(() => undefined);
+                server.close().catch(() => undefined);
+            });
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
         }
         catch (e) {
-            if (e instanceof DeviceError)
-                throw e;
-            if (e instanceof Error && e.name === "TypeError") {
-                reply.status(400).send({ error: e.message });
-                return;
+            const message = e instanceof Error ? e.message : String(e);
+            log.error?.({ err: message, reqId }, "mcp_request_failed");
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: `Internal error: ${message}` },
+                    id: null,
+                });
             }
-            throw e;
         }
     });
-    /* ---------- /act ---------- */
-    app.post("/act", async (req, reply) => {
-        const action = req.body?.action;
-        if (!action || typeof action.type !== "string") {
-            reply.status(400).send({ error: "missing or malformed action" });
-            return;
-        }
-        const startedAt = Date.now();
-        const mapped = mapActionToTool(action);
-        if ("terminal" in mapped) {
-            const response = {
-                ok: true,
-                action: mapped.type,
-                terminal: true,
-                durationMs: Date.now() - startedAt,
-            };
-            reply.send(response);
-            return;
-        }
-        const tool = getToolFor(mapped.toolName, opts.backend);
-        if (!tool) {
-            reply.status(404).send({ error: `tool '${mapped.toolName}' not registered` });
+    // GET / DELETE /mcp — explicit 405 so clients get a structured response
+    // instead of Express's default 404. The SDK's stateful flows would map
+    // these onto SSE / session teardown; stateless mode has no use for them.
+    const methodNotAllowed = (_req, res) => {
+        res.status(405).json({
+            jsonrpc: "2.0",
+            error: {
+                code: -32000,
+                message: "Method Not Allowed: device-mcp-server runs in stateless mode (POST /mcp only).",
+            },
+            id: null,
+        });
+    };
+    app.get("/mcp", methodNotAllowed);
+    app.delete("/mcp", methodNotAllowed);
+    // Final error fallback so synchronous middleware throws don't crash
+    // the process. Stays JSON-RPC-shaped for client uniformity.
+    app.use((err, _req, res, _next) => {
+        log.error?.({ err: err.message }, "express_error");
+        if (res.headersSent)
             return;
-        }
-        const result = await tool.handler(mapped.args, { backend: opts.backend });
-        const response = {
-            ok: true,
-            action: action.type,
-            tool: mapped.toolName,
-            durationMs: Date.now() - startedAt,
-            result,
-        };
-        reply.send(response);
-    });
-    /* ---------- /screen.png ---------- */
-    app.get("/screen.png", async (_req, reply) => {
-        // 0.2.3: backend reports the encoded format directly so we never
-        // need to magic-byte-sniff the buffer here.
-        const shot = await opts.backend.screenshot();
-        reply
-            .header("content-type", shot.format === "png" ? "image/png" : "image/jpeg")
-            .send(shot.data);
-    });
-    /* ---------- /events (SSE placeholder) ---------- */
-    app.get("/events", async (_req, reply) => {
-        reply.raw.writeHead(200, {
-            "Content-Type": "text/event-stream",
-            "Cache-Control": "no-cache",
-            Connection: "keep-alive",
+        res.status(500).json({
+            jsonrpc: "2.0",
+            error: { code: -32603, message: err.message },
+            id: null,
         });
-        reply.raw.write(": connected\n\n");
-        const interval = setInterval(() => {
-            reply.raw.write(`: heartbeat ${Date.now()}\n\n`);
-        }, 15_000);
-        reply.raw.on("close", () => clearInterval(interval));
-        return reply;
     });
     return app;
 }
+/* ----------------------------------------------------------------------- */
+/* Auth + CORS helpers                                                      */
+/* ----------------------------------------------------------------------- */
+/** Split a comma-separated allow-list and trim whitespace. */
+function parseOriginList(raw) {
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Parse `Authorization: Bearer <token>` (case-insensitive on the
+ * scheme) and return the token, or `undefined` if absent / malformed.
+ */
+function parseBearer(header) {
+    if (!header)
+        return undefined;
+    const m = /^bearer\s+(\S+)\s*$/i.exec(header);
+    return m ? m[1] : undefined;
+}
+/**
+ * Constant-time string comparison. Returns false fast on length
+ * mismatch (timingSafeEqual itself requires equal-length buffers, so
+ * we pad the shorter one to the longer one's length and still emit
+ * `false` afterwards).
+ */
+function constantTimeEquals(a, b) {
+    const aBuf = Buffer.from(a, "utf8");
+    const bBuf = Buffer.from(b, "utf8");
+    if (aBuf.length !== bBuf.length) {
+        // Still pay the cost of one timingSafeEqual on equal-sized garbage
+        // so timing leaks one bit at most.
+        const filler = Buffer.alloc(aBuf.length, 0);
+        timingSafeEqual(aBuf, filler);
+        return false;
+    }
+    return timingSafeEqual(aBuf, bBuf);
+}
+/** Emit a JSON-RPC-shaped error response on the auth/CORS gate. */
+function jsonRpcError(res, status, code, message) {
+    res.status(status).json({
+        jsonrpc: "2.0",
+        error: { code, message },
+        id: null,
+    });
+}
 //# sourceMappingURL=app.js.map

package/dist/server/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/server/app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,OAAiC,MAAM,SAAS,CAAC;AAExD,OAAO,EACL,QAAQ,EACR,WAAW,EAQX,QAAQ,GACT,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAUxE,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAqB;IAClD,MAAM,GAAG,GAAG,OAAO,CAAC;QAClB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI;QAC3B,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,EAAE,GAAG,IAAI,GAAG,IAAI;KAC9C,CAAC,CAAC;IAEH,GAAG,CAAC,eAAe,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACvC,IAAI,GAAG,YAAY,WAAW,EAAE,CAAC;YAC/B,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,KAAK,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,KAAK,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;YAChG,KAAK;iBACF,MAAM,CAAC,MAAM,CAAC;iBACd,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;YAChF,OAAO;QACT,CAAC;QACD,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;YAC5B,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;YAC/D,OAAO;QACT,CAAC;QACD,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;YAC5B,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;YACzE,OAAO;QACT,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAG,GAAa,EAAE,OAAO,IAAI,gBAAgB,EAAE,CAAC,CAAC;IACjF,CAAC,CAAC,CAAC;IAEH,oCAAoC;IACpC,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,IAA6B,EAAE;QACtD,OAAO;YACL,EAAE,EAAE,IAAI;YACR,8DAA8D;YAC9D,sDAAsD;YACtD,8DAA8D;YAC9D,kDAAkD;YAClD,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE;YACxB,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,OAAO;YACnD,+DAA+D;YAC/D,4DAA4D;YAC5D,KAAK,EAAE,sBAAsB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SAC/D,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,2CAA2C;IAC3C,MAAM,eAAe,GAAG,KAAK,IAA+B,EAAE,CAAC,CAAC;QAC9D,KAAK,EAAE,sBAAsB,CAAC,IAAI,CAAC,OAAO,CAAC;KAC5C,CAAC,CAAC;IACH,GAAG,CAAC,GAAG,CAAC,iBAAiB,EAAE,eAAe,CAAC,CAAC;IAC5C,GAAG,CAAC,IAAI,CAAC,iBAAiB,EAAE,eAAe,CAAC,CAAC;IAE7C,2CAA2C;IAC3C,GAAG,CAAC,IAAI,CAA4B,iBAAiB,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;QAC1E,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,GAAG,EAAE,EAAE,GAAG,GAAG,CAAC,IAAI,IAAK,EAAsB,CAAC;QAC3E,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC,CAAC;YACvD,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,+DAA+D;YAC/D,2DAA2D;YAC3D,8DAA8D;YAC9D,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,iBAAiB,IAAI,GAAG,EAAE,CAAC,CAAC;YAC5D,OAAO;QACT,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;YACnE,MAAM,QAAQ,GAAqB;gBACjC,EAAE,EAAE,IAAI;gBACR,IAAI,EAAE,IAAI;gBACV,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;gBAClC,MAAM;aACP,CAAC;YACF,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,WAAW;gBAAE,MAAM,CAAC,CAAC;YACtC,IAAI,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;gBACjD,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC7C,OAAO;YACT,CAAC;YACD,MAAM,CAAC,CAAC;QACV,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,gCAAgC;IAChC,GAAG,CAAC,IAAI,CAAuB,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;QAC1D,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,MAA4B,CAAC;QACtD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC/C,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,6BAA6B,EAAE,CAAC,CAAC;YACjE,OAAO;QACT,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QAEvC,IAAI,UAAU,IAAI,MAAM,EAAE,CAAC;YACzB,MAAM,QAAQ,GAAgB;gBAC5B,EAAE,EAAE,IAAI;gBACR,MAAM,EAAE,MAAM,CAAC,IAAI;gBACnB,QAAQ,EAAE,IAAI;gBACd,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;aACnC,CAAC;YACF,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QAED,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,MAAM,CAAC,QAAQ,kBAAkB,EAAE,CAAC,CAAC;YAC9E,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAC1E,MAAM,QAAQ,GAAgB;YAC5B,EAAE,EAAE,IAAI;YACR,MAAM,EAAE,MAAM,CAAC,IAAI;YACnB,IAAI,EAAE,MAAM,CAAC,QAAQ;YACrB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;YAClC,MAAM;SACP,CAAC;QACF,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;IAEH,uCAAuC;IACvC,GAAG,CAAC,GAAG,CAAC,aAAa,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QAC3C,iEAAiE;QACjE,4CAA4C;QAC5C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QAC7C,KAAK;aACF,MAAM,CAAC,cAAc,EAAE,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC;aAC1E,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,qDAAqD;IACrD,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACvC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE;YACvB,cAAc,EAAE,mBAAmB;YACnC,eAAe,EAAE,UAAU;YAC3B,UAAU,EAAE,YAAY;SACzB,CAAC,CAAC;QACH,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QACnC,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE;YAChC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,eAAe,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACnD,CAAC,EAAE,MAAM,CAAC,CAAC;QACX,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC;QACrD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;IAEH,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/server/app.ts"],"names":[],"mappings":"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"}

package/dist/server/mcp-server.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `buildMcpServer({ registry })` — construct a configured
+ * `@modelcontextprotocol/sdk` server with every device-mcp-server tool
+ * registered against the multi-device `BackendRegistry`.
+ *
+ * Transport-agnostic. Callers pick:
+ *   - Express + `StreamableHTTPServerTransport` (see `app.ts`) for the
+ *     HTTP loopback path used by `device-agent` siblings.
+ *   - `StdioServerTransport` (see `stdio.ts`) for the IDE / Cursor path.
+ *
+ * Both paths share the same `McpServer` instance type — sessionId
+ * semantics differ (HTTP stateless = undefined, stdio = stable for the
+ * lifetime of the connection) but the tool layer handles that uniformly
+ * via the `extra.sessionId` argument.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { BackendRegistry } from "./registry.js";
+export interface BuildMcpServerOptions {
+    registry: BackendRegistry;
+    /** Override the advertised server `name` (defaults to package name). */
+    name?: string;
+    /** Override the advertised server `version` (defaults to package version). */
+    version?: string;
+}
+export declare function buildMcpServer(opts: BuildMcpServerOptions): McpServer;

package/dist/server/mcp-server.js

@@ -0,0 +1,33 @@
+/**
+ * `buildMcpServer({ registry })` — construct a configured
+ * `@modelcontextprotocol/sdk` server with every device-mcp-server tool
+ * registered against the multi-device `BackendRegistry`.
+ *
+ * Transport-agnostic. Callers pick:
+ *   - Express + `StreamableHTTPServerTransport` (see `app.ts`) for the
+ *     HTTP loopback path used by `device-agent` siblings.
+ *   - `StdioServerTransport` (see `stdio.ts`) for the IDE / Cursor path.
+ *
+ * Both paths share the same `McpServer` instance type — sessionId
+ * semantics differ (HTTP stateless = undefined, stdio = stable for the
+ * lifetime of the connection) but the tool layer handles that uniformly
+ * via the `extra.sessionId` argument.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerAllTools } from "./tool-registry.js";
+export function buildMcpServer(opts) {
+    const server = new McpServer({
+        name: opts.name ?? "device-mcp-server",
+        version: opts.version ?? process.env.npm_package_version ?? "0.4.1",
+    }, {
+        capabilities: {
+            // Tools are the only surface device-mcp-server exposes today.
+            // Resources / prompts / logging are intentionally left off so
+            // MCP clients don't pop empty UI sections for them.
+            tools: { listChanged: true },
+        },
+    });
+    registerAllTools(server, opts.registry);
+    return server;
+}
+//# sourceMappingURL=mcp-server.js.map

package/dist/server/mcp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.js","sourceRoot":"","sources":["../../src/server/mcp-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAUtD,MAAM,UAAU,cAAc,CAAC,IAA2B;IACxD,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B;QACE,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,mBAAmB;QACtC,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,OAAO;KACpE,EACD;QACE,YAAY,EAAE;YACZ,8DAA8D;YAC9D,8DAA8D;YAC9D,oDAAoD;YACpD,KAAK,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE;SAC7B;KACF,CACF,CAAC;IAEF,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/server/registry.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 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 { type AdbRunner } from "../backends/android-adb.js";
+import type { AndroidAdbBackendOptions } from "../backends/android-adb.js";
+import type { SandboxBackend } from "../backends/base.js";
+export interface AvailableDevice {
+    /** Stable device identifier — pass to tool calls as `device: "..."`. */
+    id: string;
+    /** Backend OS family — drives capability hints in MCP clients. */
+    os: SandboxBackend["os"];
+    /** True if this is the only connected device (the single-device default). */
+    isDefault: boolean;
+    /** Human-readable hint (e.g. `"adb"` / `"desktop"`). Optional sugar. */
+    source: "adb" | "desktop";
+}
+export interface BackendRegistryOptions {
+    /**
+     * Pre-registered "static" backends (desktop / stubs / iOS). Their `os`
+     * field becomes the device id used in tool calls. Use this when the
+     * server should ALWAYS expose a non-adb backend regardless of the host's
+     * adb state (e.g. when running on a Mac dev machine with `--backend
+     * desktop`).
+     */
+    initialBackends?: SandboxBackend[];
+    /**
+     * Whether to run the adb-devices discovery poll. Set to `false` when the
+     * caller only wants the static `initialBackends` (e.g. `--backend desktop`
+     * on a host without adb installed).
+     *
+     * Default: `true`.
+     */
+    enableAdbDiscovery?: boolean;
+    /** Override the spawn-backed adb runner — tests inject spies. */
+    adbRunner?: AdbRunner;
+    /** Discovery poll interval in milliseconds. Default `10_000`. */
+    pollIntervalMs?: number;
+    /**
+     * Construction options forwarded to every newly-discovered
+     * `AndroidAdbBackend`. `serial` is overridden per device, but timeouts /
+     * runner injection / sleep helpers flow through.
+     */
+    androidDefaults?: Omit<AndroidAdbBackendOptions, "serial" | "skipConnectValidation">;
+    /** Initial seed serials — useful for tests that want a known device set without polling. */
+    initialAdbSerials?: string[];
+}
+export declare class BackendRegistry {
+    private readonly backends;
+    private readonly enableAdbDiscovery;
+    private readonly adbRunner?;
+    private readonly pollIntervalMs;
+    private readonly androidDefaults;
+    private 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.
+     */
+    private readonly sessionDevice;
+    constructor(opts?: BackendRegistryOptions);
+    /**
+     * 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.
+     */
+    start(): Promise<void>;
+    /** Stop the discovery poll and disconnect every backend. */
+    stop(): Promise<void>;
+    /** Snapshot of every currently-known device. */
+    list(): AvailableDevice[];
+    /**
+     * 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: Record<string, unknown> | undefined, sessionId?: string): SandboxBackend;
+    /** Set the session-sticky default device. Used by the `use_device` tool. */
+    useDevice(sessionId: string | undefined, deviceId: string): void;
+    private pollOnce;
+    private makeAdbBackend;
+}