@codedroid/mcp 0.0.0-stage → 0.1.1

package/src/adb-tool.js

@@ -0,0 +1,200 @@
+/**
+ * adb — a single generic MCP tool that runs an adb command against a phone
+ * attached to THIS computer (USB, or Wireless Debugging).
+ *
+ * Forked from aura-mcp-connect's `aura-adb` (MIT, Copyright (c) 2026 Dinesh Kumar C;
+ * see LICENSE.aura-mcp-connect). Changed: on by default, since the user is a developer
+ * (CODEDROID_MCP_ADB=0 turns it off); marked destructive so clients ask before running
+ * it; a per-call timeout.
+ *
+ * It never touches the connection to CodeDroid: it shells out to this machine's
+ * own `adb`, exactly like a developer typing `adb install app.apk` themselves.
+ */
+import { execFile } from "child_process";
+import { promisify } from "util";
+
+const execFileAsync = promisify(execFile);
+
+export const MAX_OUTPUT_CHARS = 20_000;
+const DEFAULT_TIMEOUT_S = 60;
+const MAX_TIMEOUT_S = 900;
+
+// adb's global options that take a value: `-s SERIAL`, `-t ID`, `-H host`, `-P port`, `-L socket`.
+const VALUE_OPTIONS = new Set(["-s", "-t", "-H", "-P", "-L"]);
+// Global options that pick the device, after which CODEDROID_SERIAL must not be added.
+const DEVICE_OPTIONS = new Set(["-s", "-t", "-d", "-e"]);
+// Subcommands whose rest is a command line for the phone's shell.
+const SHELLS = new Set(["shell", "exec-out"]);
+
+/**
+ * [command] as adb's argv. Up to the subcommand, and for host-side commands (install, push, pull),
+ * words split on whitespace and quotes group them, so a path with spaces stays one argument. After
+ * `shell` or `exec-out` (and its own -x style flags) the rest goes to the phone's shell as written,
+ * quotes, pipes and all, which is what that shell expects.
+ */
+export function adbArgv(command) {
+  const text = command.trim();
+  const argv = [];
+  let subcommand = null;
+  let i = 0;
+  while (i < text.length) {
+    while (i < text.length && /\s/.test(text[i])) i++;
+    if (i >= text.length) break;
+    if (subcommand && SHELLS.has(subcommand) && !/^-[a-zA-Z]\s/.test(text.slice(i) + " ")) {
+      argv.push(text.slice(i).trim());
+      break;
+    }
+    let word = "";
+    let quote = null;
+    for (; i < text.length; i++) {
+      const c = text[i];
+      if (quote) {
+        if (c === quote) quote = null;
+        else word += c;
+      } else if (c === '"' || c === "'") {
+        quote = c;
+      } else if (/\s/.test(c)) {
+        break;
+      } else {
+        word += c;
+      }
+    }
+    if (!subcommand && !word.startsWith("-") && !VALUE_OPTIONS.has(argv[argv.length - 1])) subcommand = word;
+    argv.push(word);
+  }
+  return argv;
+}
+
+/** Whether [argv]'s own global options, before the subcommand, already pick the device. */
+function namesDevice(argv) {
+  for (let i = 0; i < argv.length && argv[i].startsWith("-"); i++) {
+    if (DEVICE_OPTIONS.has(argv[i])) return true;
+    if (VALUE_OPTIONS.has(argv[i])) i++;
+  }
+  return false;
+}
+
+function truncate(text) {
+  if (text.length <= MAX_OUTPUT_CHARS) return text;
+  const cut = text.length - MAX_OUTPUT_CHARS;
+  return `${text.slice(0, MAX_OUTPUT_CHARS)}\n…(truncated, ${cut} more chars)`;
+}
+
+/**
+ * What the handshake says about adb, appended to the phone's instructions. At most 400 bytes:
+ * Claude Code keeps about 2 KB of a server's instructions and the phone's take up to 1,600.
+ */
+const INSTRUCTIONS =
+  "You also have `adb`: this computer's adb, for the phone when it is on USB or Wireless debugging. Use " +
+  "it to install builds, read logs (logcat -d), inspect state (dumpsys), start activities, and run " +
+  "instrumentation tests; use CodeDroid's tools to see and drive the screen. Never force-stop or " +
+  "instrument com.codedroid.app.";
+
+/** The tool's full guidance: read right before calling it. */
+const DESCRIPTION = `
+Run an adb command against the phone attached to this computer. Pass what you would type after \`adb\`, e.g. \`install -r -g app/build/outputs/apk/debug/app-debug.apk\`, \`logcat -d -t 300 *:E\`, \`shell dumpsys activity activities\`. Runs this machine's adb, so the phone must be on it (USB or Wireless debugging): CODEDROID_SERIAL or ANDROID_SERIAL, or -s in the command, picks it when several devices are; otherwise adb's own default.
+
+USEFUL:
+- Install and start: \`install -r -g <apk>\`, \`shell am start -W -n <pkg>/<activity>\`, \`shell am force-stop <pkg>\`, \`shell pm clear <pkg>\`.
+- Logs: clear with \`logcat -c\` before acting, then \`logcat -d -t 300\`; crashes only: \`logcat -d -b crash\`; one app: \`shell pidof <pkg>\` then \`logcat -d --pid=<pid>\`.
+- Tests: \`shell am instrument -w -r <test-pkg>/androidx.test.runner.AndroidJUnitRunner\` (add \`-e class <Class>\`; set timeout_s); read the INSTRUMENTATION_STATUS lines.
+- State: \`shell dumpsys window | grep mCurrentFocus\`, \`shell dumpsys package <pkg>\`, \`shell settings get global <key>\`.
+
+RULES:
+- On a phone with several users, \`settings\`, \`content\`, \`pm grant\` and \`appops\` need \`--user $(adb shell am get-current-user)\`; adb defaults to user 0.
+- Do not force-stop, clear or instrument com.codedroid.app: it switches CodeDroid's accessibility off and its tools stop working.
+- \`uiautomator dump\` and UiAutomator-based tests suspend CodeDroid's accessibility while they run; use get_screen to read the screen.
+- Never stream: \`logcat\` without \`-d\`, \`screenrecord\` without \`--time-limit\` run until timeout_s.
+- Ask the user before uninstalling, clearing data, rebooting or deleting files.
+- Quotes group words for adb itself (\`install "my app.apk"\`); everything after \`shell\` goes to the phone's shell as written, which does quote, pipe and chain.
+- Output is cut at 20,000 characters, keeping the start: filter on the phone with grep or head.
+`.trim();
+
+/**
+ * Build the tool.
+ *
+ * The `run`/`env` seams exist so tests can drive the handler without a real
+ * adb on PATH: `promisify(execFile)` is captured at module load, so an ESM
+ * test can never monkeypatch it after the fact. Mirrors the injection style
+ * of `PhoneManager({ transportFactory })` elsewhere in this package.
+ *
+ * @param {{
+ *   run?: (file: string, args: string[], opts: object) => Promise<{stdout: string, stderr: string}>,
+ *   env?: Record<string, string | undefined>,
+ * }} [deps]
+ */
+export function createAdbTool({ run = execFileAsync, env = process.env } = {}) {
+  return {
+    /** Merged into the handshake instructions by buildProxyServer. */
+    instructions: INSTRUCTIONS,
+    definition: {
+      name: "adb",
+      title: "Run adb",
+      description: DESCRIPTION,
+      inputSchema: {
+        type: "object",
+        properties: {
+          command: {
+            type: "string",
+            description: "Arguments to pass to adb, e.g. 'shell pm list packages -3'",
+          },
+          timeout_s: {
+            type: "number",
+            description: `Seconds before it is stopped (default ${DEFAULT_TIMEOUT_S}, max ${MAX_TIMEOUT_S})`,
+          },
+        },
+        required: ["command"],
+      },
+      annotations: { title: "Run adb", readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    },
+
+    /** @param {{command?: string, timeout_s?: number}} args */
+    async handler(args) {
+      const command = args?.command;
+      if (typeof command !== "string" || !command.trim()) {
+        return {
+          content: [{ type: "text", text: "adb: 'command' must be a non-empty string" }],
+          isError: true,
+        };
+      }
+
+      // execFile — NOT exec()/shell:true — so metacharacters in `command`
+      // (`;`, `&&`, backticks, `|`) reach adb as literal argv entries instead of
+      // being interpreted by a shell ON THIS MACHINE. This is a generic *adb*
+      // passthrough, deliberately not a generic host-shell passthrough.
+      //
+      // It does NOT follow that the phone sees them literally: `adb shell X; Y`
+      // hands "X; Y" to the *device's* shell, which does chain (verified on
+      // device 2026-08-06 — `shell echo hi; touch /sdcard/PWNED` created the
+      // file). That is inherent to `adb shell` and expected for a dev tool; the
+      // boundary this protects is the host, not the phone.
+      const argv = adbArgv(command);
+      const serial = namesDevice(argv) ? null : env.CODEDROID_SERIAL || env.ANDROID_SERIAL;
+      const timeoutS = Math.min(Math.max(Number(args?.timeout_s) || DEFAULT_TIMEOUT_S, 1), MAX_TIMEOUT_S);
+      const fullArgv = serial ? ["-s", serial, ...argv] : argv;
+
+      try {
+        const { stdout, stderr } = await run(env.ADB || "adb", fullArgv, {
+          timeout: timeoutS * 1000,
+          maxBuffer: 10 * 1024 * 1024,
+        });
+        const text = [stdout, stderr].filter(Boolean).join("\n").trim() || "(no output)";
+        return { content: [{ type: "text", text: truncate(text) }] };
+      } catch (e) {
+        // Never let a failed adb invocation escape past the MCP boundary — the
+        // model can act on "device unauthorized" text, but not on a dead session.
+        const text =
+          e?.code === "ENOENT"
+            ? "adb was not found on this computer. Install Android platform-tools " +
+              "(https://developer.android.com/tools/releases/platform-tools) or set ADB to its path."
+            : [e.stdout, e.stderr, e.message].filter(Boolean).join("\n").trim();
+        return {
+          content: [{ type: "text", text: truncate(text || String(e)) }],
+          isError: true,
+        };
+      }
+    },
+  };
+}
+
+export const adbTool = createAdbTool();

package/src/daemon-transport.js

@@ -0,0 +1,30 @@
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+class DaemonTransport extends StreamableHTTPClientTransport {
+  async close() {
+    // The SDK's close() only aborts HTTP streams. DELETE is what releases the daemon's
+    // session, including its proxy server, when a CLI call or stdio client is finished.
+    let timer;
+    try {
+      await Promise.race([
+        this.terminateSession(),
+        new Promise((resolve) => { timer = setTimeout(resolve, 1500); }),
+      ]);
+    } catch {
+      // The daemon may already be gone; close the local transport either way.
+    } finally {
+      clearTimeout(timer);
+      await super.close();
+    }
+  }
+}
+
+/** A request owns its localhost connection: a long get_task must not hold cancel_task or
+ * another session behind it in the HTTP connection pool (reproduced with Node 26's fetch).
+ * MCP sessions still live across requests; only the underlying TCP connection is released.
+ */
+export function daemonTransport(port) {
+  return new DaemonTransport(new URL(`http://127.0.0.1:${port}/mcp`), {
+    requestInit: { headers: { Connection: "close" } },
+  });
+}

package/src/daemon.js

@@ -0,0 +1,422 @@
+/**
+ * daemon — ONE process on this computer that owns the single link to
+ * CodeDroid on the phone (through the CodeDroid server's relay) and serves MCP over
+ * Streamable HTTP on localhost.
+ *
+ * Forked from aura-mcp-connect (MIT, Copyright (c) 2026 Dinesh Kumar C; see
+ * LICENSE.aura-mcp-connect): the link is a WebSocket relay instead of WebRTC, and the adb tool is
+ * on by default.
+ *
+ * Every MCP client (Claude Code, Claude Desktop, Cursor, VS Code windows…)
+ * connects to http://127.0.0.1:<port>/mcp and gets its own MCP session; tool
+ * calls are serialized onto the one phone connection. This replaces the old
+ * model where each client spawned its own bridge and stole the phone from the
+ * previous one ("newest wins" tug-of-war).
+ *
+ * Endpoints:
+ *   POST/GET/DELETE /mcp   Streamable HTTP MCP (per-session)
+ *   GET /health            {ok, version, phone, device, error, sessions, adbToolEnabled}
+ */
+import http from "http";
+import { randomUUID } from "crypto";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { adbTool } from "./adb-tool.js";
+import { buildProxyServer, broadcastNotification } from "./proxy-core.js";
+import { RelayPhoneTransport } from "./relay-transport.js";
+import { createStatusTool } from "./status-tool.js";
+import { VERSION } from "./version.js";
+
+export const DEFAULT_PORT = 4826;
+const MAX_BODY_BYTES = 8 * 1024 * 1024;
+
+/** How long a link stays trusted after its last proven round-trip. Past
+ *  this, getClient() pings before reuse (a phone app restart kills the link
+ *  without any close event — see 2026-07-16 stale-connection incident). */
+const LIVENESS_MAX_AGE_MS = 20_000;
+const PING_TIMEOUT_MS = 5_000;
+/**
+ * How long a new session waits for the phone before opening without it (see proxy-core). A phone
+ * that already allowed this computer connects in about a second; Codex gives a server 10 s to start.
+ */
+const CONNECT_WAIT_MS = 5_000;
+/** In a session that opened without the phone, how long tools/list waits for it: a ping's worth. */
+const LIST_WAIT_MS = 2_000;
+
+/** Owns the single connection to the phone: single-flight connect, exclusive
+ *  tool-call queue, reconnect-on-demand after a drop. */
+export class PhoneManager {
+  constructor({
+    transportFactory,
+    log = () => {},
+    livenessMaxAgeMs = LIVENESS_MAX_AGE_MS,
+    pingTimeoutMs = PING_TIMEOUT_MS,
+  } = {}) {
+    this._transportFactory =
+      transportFactory ?? (() => new RelayPhoneTransport({ log }));
+    this._log = log;
+    this._livenessMaxAgeMs = livenessMaxAgeMs;
+    this._pingTimeoutMs = pingTimeoutMs;
+    this._client = null;
+    this._connectPromise = null;
+    this._queueTail = Promise.resolve();
+    this._closed = false;
+    this._lastAliveAt = 0;
+    this.state = "disconnected";
+    /** Why the last connect failed, in words for the user; null once connected. */
+    this.lastError = null;
+    /** {id, model, server} of the phone, once connected. */
+    this.device = null;
+    /** Set by the daemon to fan phone notifications out to sessions. */
+    this.onNotification = null;
+    /** Set by the daemon: the phone (re)connected, so its tools may be new to a session. */
+    this.onConnected = null;
+  }
+
+  async getClient() {
+    if (this._closed) throw new Error("Daemon is shutting down");
+    if (this._client) {
+      // A phone app restart or network flip can kill the link without any
+      // close event — the cached client then looks healthy while every
+      // forwarded request hangs. Verify liveness with a cheap MCP ping
+      // when the link hasn't been proven alive recently.
+      if (Date.now() - this._lastAliveAt <= this._livenessMaxAgeMs) return this._client;
+      try {
+        await this._client.ping({ timeout: this._pingTimeoutMs });
+        this._lastAliveAt = Date.now();
+        return this._client;
+      } catch (e) {
+        this._log("Cached phone connection is dead (ping failed) — reconnecting");
+        const dead = this._client;
+        this._client = null;
+        this.state = "disconnected";
+        try {
+          await dead.close();
+        } catch (closeErr) {
+          /* it's already gone */
+        }
+      }
+    }
+    if (!this._connectPromise) {
+      this._connectPromise = this._connect().finally(() => {
+        this._connectPromise = null;
+      });
+    }
+    return this._connectPromise;
+  }
+
+  /** Every successful round-trip proves the link — cheaper than extra pings. */
+  markAlive() {
+    this._lastAliveAt = Date.now();
+  }
+
+  async _connect() {
+    this.state = "connecting";
+    this._log("Connecting to phone...");
+    let transport;
+    try {
+      transport = await this._transportFactory();
+    } catch (e) {
+      this.state = "disconnected";
+      this.lastError = e.message;
+      throw e;
+    }
+    const client = new Client({ name: "codedroid-mcp-daemon", version: VERSION });
+    client.fallbackNotificationHandler = async (notification) => {
+      await this.onNotification?.(notification);
+    };
+    try {
+      // Generous initialize budget: the very first connect can include a
+      // human tapping Approve on the phone.
+      await client.connect(transport, { timeout: 130_000 });
+    } catch (e) {
+      this.state = "disconnected";
+      this.lastError = e.message;
+      throw e;
+    }
+    client.onclose = () => {
+      if (this._client === client) {
+        this._client = null;
+        this.state = "disconnected";
+        this._log("Phone connection closed — will reconnect on next request");
+      }
+    };
+    this._client = client;
+    this._lastAliveAt = Date.now();
+    this.state = "connected";
+    this.lastError = null;
+    this.device = transport.device ?? null;
+    this._log("Phone connected");
+    this.onConnected?.();
+    return client;
+  }
+
+  /** Serialize work against the single physical screen. */
+  runExclusive(fn) {
+    const run = this._queueTail.then(fn, fn);
+    // Keep the chain alive whether fn resolved or rejected.
+    this._queueTail = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    return run;
+  }
+
+  async close() {
+    this._closed = true;
+    const client = this._client;
+    this._client = null;
+    this.state = "disconnected";
+    if (client) {
+      try {
+        await client.close();
+      } catch (e) {
+        /* already gone */
+      }
+    }
+  }
+}
+
+function isLoopbackHost(hostHeader) {
+  if (!hostHeader) return false;
+  // Strip port; tolerate IPv6 brackets.
+  const host = hostHeader.replace(/:\d+$/, "").replace(/^\[|\]$/g, "");
+  return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
+
+function isAllowedOrigin(origin) {
+  if (origin === undefined || origin === "null") return true; // non-browser clients
+  try {
+    const url = new URL(origin);
+    return isLoopbackHost(url.host);
+  } catch (e) {
+    return false;
+  }
+}
+
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        reject(new Error("Request body too large"));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+      } catch (e) {
+        reject(new Error("Invalid JSON body"));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+function sendJson(res, status, body) {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+
+function jsonRpcError(res, status, id, code, message) {
+  sendJson(res, status, {
+    jsonrpc: "2.0",
+    error: { code, message },
+    id: id ?? null,
+  });
+}
+
+/**
+ * Start the daemon.
+ *
+ * @param {object} [options]
+ * @param {number} [options.port]   0 = ephemeral (tests)
+ * @param {string} [options.host]
+ * @param {() => Promise<import("@modelcontextprotocol/sdk/shared/transport.js").Transport> | import("@modelcontextprotocol/sdk/shared/transport.js").Transport} [options.phoneTransportFactory]
+ * @param {(msg: string) => void} [options.log]
+ * @param {boolean} [options.enableAdbTool]  Serve the host-side `adb` tool. On by
+ *   default: the user is a developer. CODEDROID_MCP_ADB=0 turns it off (index.js).
+ * @returns {Promise<{port: number, close: () => Promise<void>, phoneManager: PhoneManager}>}
+ */
+export async function startDaemon({
+  port = DEFAULT_PORT,
+  host = "127.0.0.1",
+  phoneTransportFactory,
+  log = () => {},
+  enableAdbTool = true,
+} = {}) {
+  const phoneManager = new PhoneManager({
+    transportFactory: phoneTransportFactory,
+    log,
+  });
+  /** sessionId → { transport, server } */
+  const sessions = new Map();
+
+  phoneManager.onNotification = (notification) =>
+    broadcastNotification(
+      [...sessions.values()].map((s) => s.server),
+      notification,
+    );
+  phoneManager.onConnected = () =>
+    broadcastNotification(
+      [...sessions.values()].map((s) => s.server),
+      { method: "notifications/tools/list_changed" },
+    );
+
+  const httpServer = http.createServer(async (req, res) => {
+    try {
+      // Local-only surface: reject DNS-rebinding / cross-origin browser abuse.
+      if (!isLoopbackHost(req.headers.host) || !isAllowedOrigin(req.headers.origin)) {
+        sendJson(res, 403, { error: "Forbidden: localhost access only" });
+        return;
+      }
+
+      const url = new URL(req.url, `http://${req.headers.host}`);
+
+      if (url.pathname === "/health" && req.method === "GET") {
+        sendJson(res, 200, {
+          ok: true,
+          service: "codedroid-mcp-daemon",
+          version: VERSION,
+          phone: phoneManager.state,
+          device: phoneManager.device,
+          error: phoneManager.lastError,
+          sessions: sessions.size,
+          adbToolEnabled: enableAdbTool,
+        });
+        return;
+      }
+
+      if (url.pathname === "/shutdown" && req.method === "POST") {
+        sendJson(res, 200, { ok: true });
+        setImmediate(async () => {
+          await close();
+          process.exit(0);
+        });
+        return;
+      }
+
+      if (url.pathname !== "/mcp") {
+        sendJson(res, 404, { error: "Not found" });
+        return;
+      }
+
+      const sessionId = req.headers["mcp-session-id"];
+
+      if (req.method === "POST") {
+        let body;
+        try {
+          body = await readJsonBody(req);
+        } catch (e) {
+          jsonRpcError(res, 400, null, -32700, e.message);
+          return;
+        }
+
+        // Existing session → route to its transport.
+        if (sessionId && sessions.has(sessionId)) {
+          await sessions.get(sessionId).transport.handleRequest(req, res, body);
+          return;
+        }
+
+        // New session — must be an initialize request.
+        if (!sessionId && isInitializeRequest(body)) {
+          let server;
+          try {
+            server = await buildProxyServer({
+              getClient: () => phoneManager.getClient(),
+              runExclusive: (fn) => phoneManager.runExclusive(fn),
+              onBackendAlive: () => phoneManager.markAlive(),
+              name: "codedroid (via daemon)",
+              version: VERSION,
+              // Executes on THIS machine (wherever the daemon runs), not the
+              // phone — see adb-tool.js. The stdio shim builds its own proxy
+              // server without these, so it transparently forwards their
+              // calls to here rather than double-registering them.
+              localTools: [createStatusTool(phoneManager), ...(enableAdbTool ? [adbTool] : [])],
+              connectWaitMs: CONNECT_WAIT_MS,
+              listWaitMs: LIST_WAIT_MS,
+            });
+          } catch (e) {
+            log(`Session init failed: ${e.message}`);
+            jsonRpcError(res, 503, body.id, -32001, e.message);
+            return;
+          }
+
+          const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (id) => {
+              sessions.set(id, { transport, server });
+              log(`Session ${id.slice(0, 8)}… opened (${sessions.size} active)`);
+            },
+          });
+          transport.onclose = () => {
+            const id = transport.sessionId;
+            if (id && sessions.delete(id)) {
+              log(`Session ${id.slice(0, 8)}… closed (${sessions.size} active)`);
+            }
+          };
+
+          await server.connect(transport);
+          await transport.handleRequest(req, res, body);
+          return;
+        }
+
+        jsonRpcError(
+          res,
+          400,
+          body?.id,
+          -32000,
+          "Bad Request: unknown session (send initialize without mcp-session-id to start one)",
+        );
+        return;
+      }
+
+      if (req.method === "GET" || req.method === "DELETE") {
+        if (!sessionId || !sessions.has(sessionId)) {
+          jsonRpcError(res, 400, null, -32000, "Bad Request: no valid session");
+          return;
+        }
+        await sessions.get(sessionId).transport.handleRequest(req, res);
+        return;
+      }
+
+      sendJson(res, 405, { error: "Method not allowed" });
+    } catch (e) {
+      log(`HTTP handler error: ${e.stack || e.message}`);
+      if (!res.headersSent) {
+        jsonRpcError(res, 500, null, -32603, `Internal error: ${e.message}`);
+      } else {
+        res.end();
+      }
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    httpServer.once("error", reject);
+    httpServer.listen(port, host, resolve);
+  });
+  const boundPort = httpServer.address().port;
+  log(`CodeDroid MCP daemon listening on http://${host}:${boundPort}/mcp`);
+  if (enableAdbTool) log("The adb tool is on: connected MCP clients can run adb commands on this machine.");
+
+  const close = async () => {
+    for (const { transport } of sessions.values()) {
+      try {
+        await transport.close();
+      } catch (e) {
+        /* best-effort */
+      }
+    }
+    sessions.clear();
+    await phoneManager.close();
+    await new Promise((resolve) => httpServer.close(resolve));
+  };
+
+  return { port: boundPort, close, phoneManager };
+}