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

package/dist/cli.js

@@ -1,52 +1,68 @@
 #!/usr/bin/env node
 /**
- * device-mcp-server CLI — spins up a Fastify HTTP server on the chosen
- * `SandboxBackend`. Designed to run as a sibling process inside a Redroid pod /
- * edge site; the agent runtime in `@beeos-ai/device-agent` reaches it via HTTP
- * loopback on port 7900 by default.
+ * `device-mcp-server` CLI — singleton multi-device MCP server.
+ *
+ * 0.4.0 reshape:
+ *   - Switched from a per-device process model to a singleton: one
+ *     `device-mcp-server` discovers every adb device in `adb devices`
+ *     and exposes them as separate `device` ids on every tool call (just
+ *     like Mobile-Next/mobile-mcp). The `--adb-serial` flag from 0.3.x
+ *     is REMOVED — multi-device discovery is the only supported mode.
+ *   - Switched the wire from a bespoke REST envelope to the official
+ *     Model Context Protocol over `@modelcontextprotocol/sdk`.
+ *   - Two transports:
+ *       HTTP (default)  Express + Streamable HTTP at `POST /mcp`
+ *       stdio (--stdio) Single-session JSON-RPC over stdin/stdout
  *
  * Examples:
- *   device-mcp-server --backend adb --adb-serial emulator-5554
- *   device-mcp-server --backend desktop --port 7901   # smart-resolve to host OS
- *   device-mcp-server --backend macos                 # real macOS host control
- *   device-mcp-server --backend linux                 # real Linux host control
- *   device-mcp-server --backend windows               # real Windows host control
+ *   # HTTP loopback for `device-agent` siblings
+ *   device-mcp-server --backend desktop --port 7900
+ *
+ *   # IDE / Cursor stdio entry — JSON-RPC on stdin/stdout, logs on stderr
+ *   device-mcp-server --backend desktop --stdio
+ *
+ *   # Android farm — server discovers every adb device and exposes them
+ *   # as separate `device` ids. Pass `device: <serial>` per tool call.
+ *   device-mcp-server --backend adb --port 7900
  *
  * Env overrides:
  *   DEVICEAGENT_BACKEND=adb|macos|linux|windows|desktop|...
- *   ANDROID_SERIAL=<adb serial>
- *   ADB_DEFAULT_TIMEOUT_MS=10000   (per-call adb command timeout, ms)
- *   ADB_SHELL_TIMEOUT_MS=30000     (adb shell timeout, ms)
- *   ADB_SCREENSHOT_TIMEOUT_MS=15000 (adb exec-out screencap timeout, ms)
- *   ADB_INSTALL_TIMEOUT_MS=120000  (adb install timeout, ms)
- *   MAC_CLICLICK_PATH=/opt/homebrew/bin/cliclick (override autodetected path)
- *   MCP_HOST=0.0.0.0
- *   MCP_PORT=7900
+ *   ADB_DEFAULT_TIMEOUT_MS    per-call adb command timeout (ms)
+ *   ADB_SHELL_TIMEOUT_MS      adb shell timeout (ms)
+ *   ADB_SCREENSHOT_TIMEOUT_MS adb exec-out screencap timeout (ms)
+ *   ADB_INSTALL_TIMEOUT_MS    adb install timeout (ms)
+ *   MAC_CLICLICK_PATH         override autodetected cliclick path
+ *   MCP_HOST                  HTTP bind address (default 127.0.0.1)
+ *   MCP_PORT                  HTTP listen port (default 7900)
+ *   DEVICE_MCP_POLL_MS        adb-discovery poll interval (default 10000)
+ *   GUI_AGENT_SS_MAX_EDGE     screenshot resize cap (default 1280)
+ *   GUI_AGENT_SS_JPEG_QUALITY screenshot JPEG quality (default 80)
  *
  * macOS notes:
- *   - The "macos" backend (and "desktop" on a darwin host) drives the real
- *     local Mac via cliclick + osascript + screencapture. The host process
- *     MUST hold Accessibility permission (System Settings → Privacy &
- *     Security → Accessibility) for synthetic input to take effect.
- *   - cliclick is auto-detected on PATH; install via `brew install cliclick`
- *     for the smoothest pointer ergonomics. Without it the backend falls back
- *     to JXA + Quartz CGEvent (`osascript -l JavaScript`), which is also
- *     production-grade — every verb keeps working, including scroll (cliclick
- *     itself has no scroll command; scroll is always JXA-driven).
+ *   - The `macos` backend (and `desktop` on a darwin host) drives the
+ *     real local Mac via cliclick + osascript + screencapture. The host
+ *     process MUST hold Accessibility permission (System Settings →
+ *     Privacy & Security → Accessibility) for synthetic input to take
+ *     effect.
+ *   - cliclick is auto-detected on PATH; install via `brew install
+ *     cliclick` for the smoothest pointer ergonomics. Without it the
+ *     backend falls back to JXA + Quartz CGEvent.
  */
 import { parseArgs } from "node:util";
 import { DeviceError } from "@beeos-ai/device-common";
 import { createBackend, SUPPORTED_BACKENDS } from "./backends/index.js";
 import { buildApp } from "./server/app.js";
+import { runStdio } from "./server/stdio.js";
+import { BackendRegistry } from "./server/registry.js";
+import { stderrLogger } from "./util/logger.js";
 function parseCliArgs(argv) {
     const { values } = parseArgs({
         args: argv,
         options: {
             backend: { type: "string" },
-            "adb-serial": { type: "string" },
             host: { type: "string" },
             port: { type: "string" },
-            "skip-connect": { type: "boolean", default: false },
+            stdio: { type: "boolean", default: false },
             width: { type: "string" },
             height: { type: "string" },
             help: { type: "boolean", short: "h", default: false },
@@ -58,7 +74,7 @@ function parseCliArgs(argv) {
         printHelp();
         process.exit(0);
     }
-    const backendName = (values.backend ?? process.env.DEVICEAGENT_BACKEND ?? "desktop");
+    const backendName = (values.backend ?? process.env.DEVICEAGENT_BACKEND ?? "adb");
     if (!SUPPORTED_BACKENDS.includes(backendName)) {
         throw new DeviceError(`unknown backend '${backendName}'. Supported: ${SUPPORTED_BACKENDS.join(", ")}`, { subtype: "invalid_args" });
     }
@@ -70,39 +86,34 @@ function parseCliArgs(argv) {
         backend: backendName,
         host: values.host ?? process.env.MCP_HOST ?? "127.0.0.1",
         port,
-        adbSerial: values["adb-serial"] ?? process.env.ANDROID_SERIAL,
-        skipConnectValidation: !!values["skip-connect"],
+        stdio: !!values.stdio,
         width: values.width ? Number(values.width) : undefined,
         height: values.height ? Number(values.height) : undefined,
     };
 }
 function printHelp() {
-    process.stdout.write(`device-mcp-server — BeeOS in-pod device control HTTP server.
+    process.stdout.write(`device-mcp-server — singleton multi-device MCP tool server.
 
 Usage:
   device-mcp-server [options]
 
 Options:
-  --backend <name>      Canonical: adb | macos | linux | windows | desktop
-                        Aliases: android (= adb), mac (= macos), win (= windows),
-                                 desktop-{linux,macos,windows}, mock-desktop, ios
-                        Default: "desktop" — smart-resolves to macOS / Linux /
-                        Windows native control on the corresponding host.
-                        macOS native control requires Accessibility permission
-                        (System Settings → Privacy & Security → Accessibility).
-                        linux/windows stubs cover screen-capture + shell only;
-                        pointer / keyboard come in a follow-up.
-  --adb-serial <id>     ADB serial (adb backend only)
-  --host <addr>         Bind address (default: 127.0.0.1)
-  --port <n>            Listen port (default: 7900)
-  --skip-connect        Skip connect-time backend validation (tests / cold farms)
-  --width / --height    Override mock-desktop canvas size (ignored on macos)
-  -h, --help            Show this help
+  --backend <name>   Canonical: adb | macos | linux | windows | desktop
+                     Aliases: android (= adb), mac (= macos), win (= windows),
+                              desktop-{linux,macos,windows}, mock-desktop, ios
+                     Default: "adb" — the singleton multi-device path.
+  --host <addr>      HTTP bind address (default: 127.0.0.1; ignored under --stdio)
+  --port <n>         HTTP listen port (default: 7900; ignored under --stdio)
+  --stdio            Use stdio transport (single session, JSON-RPC on stdin/stdout,
+                     logs on stderr). Mutually exclusive with HTTP.
+  --width / --height Override mock-desktop canvas size (ignored on macos)
+  -h, --help         Show this help
 
 Env overrides:
-  DEVICEAGENT_BACKEND, ANDROID_SERIAL, MCP_HOST, MCP_PORT, MAC_CLICLICK_PATH,
+  DEVICEAGENT_BACKEND, MCP_HOST, MCP_PORT, MAC_CLICLICK_PATH,
   ADB_DEFAULT_TIMEOUT_MS, ADB_SHELL_TIMEOUT_MS, ADB_SCREENSHOT_TIMEOUT_MS,
-  ADB_INSTALL_TIMEOUT_MS
+  ADB_INSTALL_TIMEOUT_MS, DEVICE_MCP_POLL_MS,
+  GUI_AGENT_SS_MAX_EDGE, GUI_AGENT_SS_JPEG_QUALITY
 `);
 }
 function parsePositiveIntEnv(name) {
@@ -116,49 +127,73 @@ function parsePositiveIntEnv(name) {
 }
 async function main() {
     const cli = parseCliArgs(process.argv.slice(2));
-    const backend = createBackend(cli.backend, {
-        android: {
-            serial: cli.adbSerial,
-            skipConnectValidation: cli.skipConnectValidation,
+    // Build the static (non-adb) backend up front. The adb path is handled
+    // by the registry's discovery poll — there's no per-process adb pinning
+    // any more.
+    const isAdb = cli.backend === "adb" || cli.backend === "android";
+    const initialBackends = isAdb
+        ? []
+        : [
+            createBackend(cli.backend, {
+                desktop: { width: cli.width, height: cli.height },
+                macos: {
+                    cliclickPath: process.env.MAC_CLICLICK_PATH || undefined,
+                },
+                linux: {
+                    shellTimeoutMs: parsePositiveIntEnv("LINUX_SHELL_TIMEOUT_MS"),
+                },
+                windows: {
+                    shellTimeoutMs: parsePositiveIntEnv("WINDOWS_SHELL_TIMEOUT_MS"),
+                    powershellBin: process.env.WINDOWS_POWERSHELL_BIN || undefined,
+                },
+            }),
+        ];
+    const registry = new BackendRegistry({
+        initialBackends,
+        enableAdbDiscovery: isAdb,
+        pollIntervalMs: parsePositiveIntEnv("DEVICE_MCP_POLL_MS") ?? undefined,
+        androidDefaults: {
             defaultTimeoutMs: parsePositiveIntEnv("ADB_DEFAULT_TIMEOUT_MS"),
             shellTimeoutMs: parsePositiveIntEnv("ADB_SHELL_TIMEOUT_MS"),
             screenshotTimeoutMs: parsePositiveIntEnv("ADB_SCREENSHOT_TIMEOUT_MS"),
             installTimeoutMs: parsePositiveIntEnv("ADB_INSTALL_TIMEOUT_MS"),
         },
-        desktop: { width: cli.width, height: cli.height },
-        macos: {
-            cliclickPath: process.env.MAC_CLICLICK_PATH || undefined,
-        },
-        linux: {
-            shellTimeoutMs: parsePositiveIntEnv("LINUX_SHELL_TIMEOUT_MS"),
-        },
-        windows: {
-            shellTimeoutMs: parsePositiveIntEnv("WINDOWS_SHELL_TIMEOUT_MS"),
-            powershellBin: process.env.WINDOWS_POWERSHELL_BIN || undefined,
-        },
     });
-    if (!cli.skipConnectValidation) {
-        await backend.connect();
-    }
-    if ((cli.backend === "desktop" && process.platform === "darwin") ||
-        cli.backend === "macos" ||
-        cli.backend === "mac" ||
-        cli.backend === "desktop-macos") {
-        // eslint-disable-next-line no-console
-        console.error("[device-mcp-server] macOS backend selected — ensure the host process " +
+    await registry.start();
+    // Surface a one-shot warning for macOS Accessibility permission since
+    // that's the most common "tools silently no-op" failure mode.
+    if (!cli.stdio &&
+        ((cli.backend === "desktop" && process.platform === "darwin") ||
+            cli.backend === "macos" ||
+            cli.backend === "mac" ||
+            cli.backend === "desktop-macos")) {
+        process.stderr.write("[device-mcp-server] macOS backend selected — ensure the host process " +
             "holds Accessibility permission (System Settings → Privacy & Security " +
-            "→ Accessibility) for synthetic input to take effect.");
+            "→ Accessibility) for synthetic input to take effect.\n");
     }
-    const app = await buildApp({ backend });
-    const address = await app.listen({ host: cli.host, port: cli.port });
-    app.log.info({ backend: cli.backend, address }, `device-mcp-server listening on ${address}`);
+    if (cli.stdio) {
+        await runStdio({ registry, version: process.env.npm_package_version });
+        // runStdio resolves once stdin is wired up; the SDK transport keeps
+        // the process alive while stdin is open and exits the loop on EOF.
+        return;
+    }
+    const app = buildApp({ registry, version: process.env.npm_package_version });
+    const httpServer = app.listen(cli.port, cli.host, () => {
+        const addr = httpServer.address();
+        const display = typeof addr === "string"
+            ? addr
+            : addr
+                ? `http://${cli.host}:${addr.port}/mcp`
+                : `http://${cli.host}:${cli.port}/mcp`;
+        stderrLogger.info?.({ backend: cli.backend, address: display }, "device-mcp-server listening");
+    });
     const shutdown = async (signal) => {
-        app.log.info({ signal }, "shutting down");
+        stderrLogger.info?.({ signal }, "shutting down");
         try {
-            await app.close();
-            await backend.disconnect();
+            await new Promise((res) => httpServer.close(() => res()));
         }
         finally {
+            await registry.stop().catch(() => undefined);
             process.exit(0);
         }
     };
@@ -166,11 +201,10 @@ async function main() {
     process.on("SIGTERM", () => void shutdown("SIGTERM"));
 }
 main().catch((err) => {
-    // eslint-disable-next-line no-console
-    console.error(`[device-mcp-server] fatal: ${err?.message ?? err}`);
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[device-mcp-server] fatal: ${message}\n`);
     if (err instanceof DeviceError) {
-        // eslint-disable-next-line no-console
-        console.error(`  subtype=${err.subtype} retriable=${err.retriable}`);
+        process.stderr.write(`  subtype=${err.subtype} retriable=${err.retriable}\n`);
     }
     process.exit(1);
 });

package/dist/cli.js.map

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

package/dist/index.d.ts

@@ -1,13 +1,16 @@
 /**
- * @beeos-ai/device-mcp-server — public surface.
+ * @beeos-ai/device-mcp-server — public surface (0.4.0).
  *
  * Most callers use the CLI (`device-mcp-server`) and reach the server over
- * HTTP. The exports here are for embedders that want to host a server in
- * the same Node process (e.g. integration tests, custom orchestration).
+ * HTTP / stdio. The exports here are for embedders that want to host the
+ * server in the same Node process (e.g. integration tests, custom
+ * orchestration, IDE plugins).
  */
 export { buildApp, type BuildAppOptions } from "./server/app.js";
-export { TOOLS, getTool, listToolDescriptors, type ToolEntry, type ToolHandler, type ToolHandlerContext, } from "./server/tool-registry.js";
-export { mapActionToTool, type ActionMappingResult, type ToolCall, type UnsupportedActionResult, } from "./server/action-mapping.js";
+export { runStdio, type RunStdioOptions } from "./server/stdio.js";
+export { buildMcpServer, type BuildMcpServerOptions } from "./server/mcp-server.js";
+export { BackendRegistry, type AvailableDevice as RegistryAvailableDevice, type BackendRegistryOptions, } from "./server/registry.js";
+export { TOOL_SPECS, allToolNames, getToolSpec, registerAllTools, type ToolHandler, type ToolHandlerContext, type ToolSpec, } from "./server/tool-registry.js";
 export { AndroidAdbBackend, DesktopBackend, WindowsBackend, MacOsBackend, IosBackend, createBackend, SUPPORTED_BACKENDS, type BackendName, type SandboxBackend, type BackendFamily, type AndroidAdbBackendOptions, type DesktopBackendOptions, type CreateBackendOptions, } from "./backends/index.js";
 export { BaseSandboxBackend, type ScreenSize, type UiDumpOutput, type ExecuteCommandOutput, type ListDirectoryEntry, } from "./backends/base.js";
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.4.0";

package/dist/index.js

@@ -1,14 +1,17 @@
 /**
- * @beeos-ai/device-mcp-server — public surface.
+ * @beeos-ai/device-mcp-server — public surface (0.4.0).
  *
  * Most callers use the CLI (`device-mcp-server`) and reach the server over
- * HTTP. The exports here are for embedders that want to host a server in
- * the same Node process (e.g. integration tests, custom orchestration).
+ * HTTP / stdio. The exports here are for embedders that want to host the
+ * server in the same Node process (e.g. integration tests, custom
+ * orchestration, IDE plugins).
  */
 export { buildApp } from "./server/app.js";
-export { TOOLS, getTool, listToolDescriptors, } from "./server/tool-registry.js";
-export { mapActionToTool, } from "./server/action-mapping.js";
+export { runStdio } from "./server/stdio.js";
+export { buildMcpServer } from "./server/mcp-server.js";
+export { BackendRegistry, } from "./server/registry.js";
+export { TOOL_SPECS, allToolNames, getToolSpec, registerAllTools, } from "./server/tool-registry.js";
 export { AndroidAdbBackend, DesktopBackend, WindowsBackend, MacOsBackend, IosBackend, createBackend, SUPPORTED_BACKENDS, } from "./backends/index.js";
 export { BaseSandboxBackend, } from "./backends/base.js";
-export const VERSION = "0.2.0";
+export const VERSION = "0.4.0";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAwB,MAAM,iBAAiB,CAAC;AACjE,OAAO,EACL,KAAK,EACL,OAAO,EACP,mBAAmB,GAIpB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,eAAe,GAIhB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,YAAY,EACZ,UAAU,EACV,aAAa,EACb,kBAAkB,GAOnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,GAKnB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAwB,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAwB,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,cAAc,EAA8B,MAAM,wBAAwB,CAAC;AACpF,OAAO,EACL,eAAe,GAGhB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,UAAU,EACV,YAAY,EACZ,WAAW,EACX,gBAAgB,GAIjB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,YAAY,EACZ,UAAU,EACV,aAAa,EACb,kBAAkB,GAOnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,GAKnB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/dist/server/app.d.ts

@@ -1,23 +1,66 @@
 /**
- * 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 { type FastifyInstance } from "fastify";
-import type { SandboxBackend } from "../backends/base.js";
+import { type Express } from "express";
+import type { BackendRegistry } from "./registry.js";
+import { type Logger } from "../util/logger.js";
 export interface BuildAppOptions {
-    backend: SandboxBackend;
-    /** Override Fastify's logger. Pass `false` to silence in tests. */
-    logger?: boolean | object;
-    /** Per-request body size cap (bytes). Defaults to 16MB for file_write base64. */
+    registry: BackendRegistry;
+    /** Override the advertised server `name`. */
+    name?: string;
+    /** Override the advertised server `version`. */
+    version?: string;
+    /** Per-request body size cap (bytes). Defaults to 16MB for `file_write` base64. */
     bodyLimit?: number;
+    /** Pino-shaped logger. Defaults to a stderr-only logger so stdio mode is safe. */
+    logger?: Logger;
+    /**
+     * Bearer token required on every `POST /mcp` (`Authorization: Bearer
+     * <token>`). When undefined, falls back to `BEEOS_DEVICE_AUTH` env.
+     * Empty string explicitly disables auth (overrides env).
+     */
+    authToken?: string;
+    /**
+     * Comma-separated allow-list for the `Origin` header. When undefined,
+     * falls back to `BEEOS_DEVICE_ALLOWED_ORIGINS`. Empty string disables
+     * origin enforcement.
+     */
+    allowedOrigins?: string;
+    /**
+     * If true, requests without an `Origin` header are also rejected.
+     * Defaults to `BEEOS_DEVICE_REQUIRE_ORIGIN === "1"`.
+     */
+    requireOrigin?: boolean;
 }
-export declare function buildApp(opts: BuildAppOptions): Promise<FastifyInstance>;
+export declare function buildApp(opts: BuildAppOptions): Express;