@codedroid/mcp 0.0.0-stage → 0.1.0

package/src/host.js

@@ -0,0 +1,110 @@
+/**
+ * This computer's pairing with a phone, kept in ~/.codedroid/host.json (dir 0700, file 0600):
+ * {server, host_id, token, device: {id, model}}.
+ *
+ * The phone shows a one-time code (Settings > Computers > Pair a computer); `pair` redeems it at
+ * the CodeDroid server for a host token. The token is the key to the relay: anyone holding it
+ * reaches the phone (still behind its Allow sheet), so the file is the user's alone.
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+export const DEFAULT_SERVER = "https://orchestrator.codedroid.com";
+
+export const PAIRING_STEPS =
+  "On the phone, open CodeDroid > Settings > Computers > Pair a computer, then run the command it shows " +
+  "on this computer (npx -y @codedroid/mcp pair XXXX-XXXX).";
+
+export function hostFilePath(home = os.homedir()) {
+  return path.join(home, ".codedroid", "host.json");
+}
+
+/** The saved pairing, or null when this computer is not paired. */
+export function readHost({ home = os.homedir() } = {}) {
+  try {
+    const host = JSON.parse(fs.readFileSync(hostFilePath(home), "utf8"));
+    return host?.token && host.server ? { ...host, server: normalizeServer(host.server) } : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+export function saveHost(host, { home = os.homedir() } = {}) {
+  const file = hostFilePath(home);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  // A new file, renamed over the old: 0600 from its first byte, and never half-written.
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(host, null, 2) + "\n", { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+/** The phone a pairing points at, as status and /health show it. */
+export function pairedDevice(host) {
+  return host ? { id: host.device?.id ?? null, model: host.device?.model ?? null, server: host.server } : null;
+}
+
+/** [server] without a trailing slash, or an error saying what is wrong with it. */
+export function normalizeServer(server) {
+  let url;
+  try {
+    url = new URL(server);
+  } catch (e) {
+    throw new Error(`Not a server URL: ${server}`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") throw new Error(`Not an http(s) server URL: ${server}`);
+  url.search = "";
+  url.hash = "";
+  return url.href.replace(/\/+$/, "");
+}
+
+const NEW_CODE = "On the phone, open CodeDroid > Settings > Computers > Pair a computer for a new one.";
+
+/**
+ * Redeems [code] at [server] and saves the pairing, replacing any earlier one; resolves what was
+ * saved. Throws a message for the user, and leaves the earlier pairing as it was, on any failure.
+ */
+export async function pair(
+  code,
+  { server = DEFAULT_SERVER, fetch = globalThis.fetch, home = os.homedir(), hostname = os.hostname(), platform = os.platform() } = {},
+) {
+  // The server reads the code the forgiving way (any case, with or without the dash); this only
+  // catches what cannot be one before a round-trip.
+  const typed = String(code).replace(/\s+/g, "");
+  if (!/^[0-9a-z]{8}$/i.test(typed.replace(/-/g, ""))) {
+    throw new Error(`${code} is not a pairing code: it is 8 letters and digits, like ABCD-EFGH. ${NEW_CODE}`);
+  }
+  const base = normalizeServer(server);
+  let res;
+  try {
+    res = await fetch(`${base}/v1/mcp/pairings/redeem`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        code: typed,
+        name: hostname.replace(/\.local$/, "").slice(0, 64) || "computer",
+        platform: platform.slice(0, 32),
+      }),
+      signal: AbortSignal.timeout(30_000),
+    });
+  } catch (e) {
+    throw new Error(`Could not reach the CodeDroid server at ${base}: ${e.cause?.message ?? e.message}`);
+  }
+  const body = await res.json().catch(() => null);
+  if (res.status === 404) throw new Error(`The code ${code} is not valid: codes work once, for 10 minutes. ${NEW_CODE}`);
+  if (!res.ok) {
+    const detail = typeof body?.detail === "string" ? `: ${body.detail}` : "";
+    throw new Error(`The CodeDroid server at ${base} refused the pairing (HTTP ${res.status}${detail}).`);
+  }
+  if (typeof body?.token !== "string" || !body.host_id) {
+    throw new Error(`The CodeDroid server at ${base} answered the pairing without a host token; update codedroid-mcp.`);
+  }
+  const host = {
+    server: base,
+    host_id: body.host_id,
+    token: body.token,
+    device: { id: body.device?.id ?? null, model: body.device?.model ?? null },
+  };
+  saveHost(host, { home });
+  return host;
+}

package/src/index.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * codedroid-mcp — connect any MCP client (Claude Code, Codex, Cursor, ...) to CodeDroid on an
+ * Android phone paired with this computer.
+ *
+ * ONE daemon per computer owns the connection to the phone (through the CodeDroid server's relay)
+ * and serves MCP over Streamable HTTP on localhost; clients either point at its URL or launch this
+ * stdio shim, which auto-starts it.
+ *
+ * Modes:
+ *   codedroid-mcp                  stdio shim → daemon (auto-starts it)  [default]
+ *   codedroid-mcp daemon           run the daemon in the foreground
+ *   codedroid-mcp pair <code>      pair with the phone showing <code>, then connect
+ *   codedroid-mcp connect          connect to the phone now (and get it allowed there), then exit
+ *   codedroid-mcp status           what the running daemon sees
+ *   codedroid-mcp stop             stop the running daemon
+ *   codedroid-mcp call <tool> [json]  call one tool and print the result (scripts, CI)
+ *   codedroid-mcp skill install|path  the agent skills, for clients without the plugin
+ *
+ * Options: --port=<n> (or CODEDROID_MCP_PORT), default 4826. --server=<url> for pair. CODEDROID_MCP_ADB=0
+ * leaves out the adb tool. CODEDROID_SERIAL picks the adb tool's device when several are attached.
+ *
+ * All log output goes to stderr — stdout is reserved for MCP JSON-RPC frames.
+ *
+ * Forked from aura-mcp-connect (MIT, Copyright (c) 2026 Dinesh Kumar C; see LICENSE.aura-mcp-connect).
+ */
+import { VERSION } from "./version.js";
+
+function log(...parts) {
+  process.stderr.write(`[codedroid-mcp] ${parts.join(" ")}\n`);
+}
+
+function fatal(message, code = 1) {
+  process.stderr.write(`[codedroid-mcp] ${message}\n`);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (const raw of argv) {
+    if (!raw.startsWith("--")) {
+      out._.push(raw);
+      continue;
+    }
+    const eq = raw.indexOf("=");
+    if (eq === -1) out[raw.slice(2)] = "true";
+    else out[raw.slice(2, eq)] = raw.slice(eq + 1);
+  }
+  return out;
+}
+
+function resolvePort(args) {
+  const raw = args.port ?? process.env.CODEDROID_MCP_PORT;
+  if (raw === undefined) return undefined;
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) fatal(`Invalid port: ${raw}`);
+  return port;
+}
+
+/** The adb tool is on unless CODEDROID_MCP_ADB=0 (or --no-adb). The env var reaches a daemon the shim starts. */
+function resolveEnableAdb(args) {
+  if (args["no-adb"]) return false;
+  const raw = process.env.CODEDROID_MCP_ADB;
+  return raw === undefined || (raw !== "0" && raw.toLowerCase() !== "false");
+}
+
+const HELP = `codedroid-mcp ${VERSION}
+
+Gives an MCP client (Claude Code, Codex, Cursor...) your Android phone through CodeDroid: see the
+screen, tap and type, hand CodeDroid a task, and run adb.
+
+Usage:
+  codedroid-mcp                     MCP stdio server (auto-starts the shared daemon)
+  codedroid-mcp pair <code>         Pair with the phone showing <code>, then connect
+                                    (--server=<url> when the phone's command has it)
+  codedroid-mcp connect             Connect to the phone now; the first time, tap Allow on it
+  codedroid-mcp status              What the running daemon sees
+  codedroid-mcp stop                Stop the running daemon
+  codedroid-mcp call <tool> [json]  Call one tool and print the result
+  codedroid-mcp daemon              Run the shared daemon in the foreground
+  codedroid-mcp skill install       Install the agent skills for Claude Code
+                                    (--codex for Codex, --dir=<path> anywhere else)
+  codedroid-mcp skill path          Print where the skill files are
+
+Pair first: on the phone, open CodeDroid > Settings > Computers > Pair a computer, and run the
+command it shows here. The phone needs CodeDroid signed in, online, with its accessibility
+service on. The adb tool, alone, needs the phone on this computer's adb.
+
+Options:
+  --port=<n>   Daemon port (default 4826; env CODEDROID_MCP_PORT)
+  --no-adb     Leave out the adb tool (env CODEDROID_MCP_ADB=0)
+  --version    Print version
+  --help       This text
+
+Env: CODEDROID_SERIAL picks the adb tool's device when several are attached; ADB is the adb binary.
+
+Clients:
+  claude mcp add codedroid -- npx -y @codedroid/mcp
+  codex mcp add codedroid -- npx -y @codedroid/mcp
+  { "mcpServers": { "codedroid": { "command": "npx", "args": ["-y", "@codedroid/mcp"] } } }
+  or by URL, with the daemon running: http://127.0.0.1:4826/mcp (streamable HTTP)
+`;
+
+/** Logger for daemon mode: stderr + ~/.codedroid/daemon.log (it is usually spawned with stdio ignored). */
+async function makeDaemonLogger() {
+  const { default: fs } = await import("fs");
+  const { default: path } = await import("path");
+  const { default: os } = await import("os");
+  const logFile = path.join(os.homedir(), ".codedroid", "daemon.log");
+  try {
+    fs.mkdirSync(path.dirname(logFile), { recursive: true, mode: 0o700 });
+  } catch (e) {
+    /* stderr still works */
+  }
+  return (...parts) => {
+    const line = `${new Date().toISOString()} ${parts.join(" ")}`;
+    process.stderr.write(`[codedroid-mcp] ${line}\n`);
+    try {
+      fs.appendFileSync(logFile, line + "\n");
+    } catch (e) {
+      /* best-effort */
+    }
+  };
+}
+
+/** A client of the daemon, starting it if needed: for pair, connect, status and call. */
+async function daemonClient(port, enableAdbTool) {
+  const { ensureDaemonRunning } = await import("./stdio-shim.js");
+  const { DEFAULT_PORT } = await import("./daemon.js");
+  const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
+  const { daemonTransport } = await import("./daemon-transport.js");
+  const effective = port ?? DEFAULT_PORT;
+  await ensureDaemonRunning(effective, log, { enableAdbTool });
+  const client = new Client({ name: "codedroid-mcp-cli", version: VERSION });
+  await client.connect(daemonTransport(effective), { timeout: 150_000 });
+  return client;
+}
+
+/** The running daemon's /health, or null when there is none. */
+async function daemonHealth(port) {
+  const { DEFAULT_PORT } = await import("./daemon.js");
+  const { fetchHealth } = await import("./stdio-shim.js");
+  return fetchHealth(port ?? DEFAULT_PORT);
+}
+
+/** Stops a running daemon and waits until it is gone; false when none was running. */
+async function stopDaemon(port) {
+  const { DEFAULT_PORT } = await import("./daemon.js");
+  if (!(await daemonHealth(port))) return false;
+  await fetch(`http://127.0.0.1:${port ?? DEFAULT_PORT}/shutdown`, { method: "POST" }).catch(() => null);
+  for (let i = 0; i < 50 && (await daemonHealth(port)); i++) await new Promise((r) => setTimeout(r, 100));
+  return true;
+}
+
+function printResult(result) {
+  for (const item of result.content ?? []) {
+    if (item.type === "text") process.stdout.write(item.text + "\n");
+    else if (item.type === "image") process.stdout.write(`[image ${item.mimeType}, ${item.data.length} base64 chars]\n`);
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.version) return void process.stdout.write(`codedroid-mcp ${VERSION}\n`);
+  if (args.help || args._[0] === "help") return void process.stdout.write(HELP);
+
+  const command = args._[0];
+  const port = resolvePort(args);
+  const enableAdbTool = resolveEnableAdb(args);
+
+  if (command === "skill") {
+    const { installSkills, SKILLS_SOURCE, defaultSkillsDir } = await import("./skill.js");
+    if (args._[1] === "path") return void process.stdout.write(`${SKILLS_SOURCE}\n`);
+    if (args._[1] !== "install") fatal("Usage: codedroid-mcp skill install [--codex | --dir=<path>] | codedroid-mcp skill path");
+    const written = installSkills({ dir: args.dir ?? defaultSkillsDir({ codex: !!args.codex }) });
+    process.stdout.write(`Installed:\n${written.map((p) => `  ${p}`).join("\n")}\nNew sessions pick them up.\n`);
+    return;
+  }
+
+  if (command === "daemon") {
+    const { startDaemon, DEFAULT_PORT } = await import("./daemon.js");
+    const daemonLog = await makeDaemonLogger();
+    daemonLog(`v${VERSION} · daemon`);
+    let daemon;
+    try {
+      daemon = await startDaemon({ port, log: daemonLog, enableAdbTool });
+    } catch (e) {
+      if (e.code === "EADDRINUSE") {
+        const effectivePort = port ?? DEFAULT_PORT;
+        if (await daemonHealth(effectivePort)) {
+          daemonLog(`A CodeDroid daemon is already running on port ${effectivePort}.`);
+          process.exit(0);
+        }
+        fatal(`Port ${effectivePort} is in use by something else. Pick another: codedroid-mcp daemon --port=<n> (clients must use the same).`);
+      }
+      throw e;
+    }
+    const shutdown = async () => {
+      await daemon.close();
+      process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    return;
+  }
+
+  if (command === "stop") {
+    process.stdout.write((await stopDaemon(port)) ? "Stopped the daemon.\n" : "No daemon was running.\n");
+    return;
+  }
+
+  if (command === "pair") {
+    const code = args._.slice(1).join(" ");
+    if (!code) fatal("Usage: codedroid-mcp pair <code> [--server=<url>]. The phone shows the command: CodeDroid > Settings > Computers > Pair a computer.");
+    const { DEFAULT_SERVER, pair } = await import("./host.js");
+    const host = await pair(code, { server: args.server ?? DEFAULT_SERVER });
+    log(`Paired with ${host.device.model ?? "the phone"} through ${host.server}.`);
+    // A daemon connected, or connecting, holds the old pairing's link; a disconnected one reads the new one.
+    const phone = (await daemonHealth(port))?.phone;
+    if (phone && phone !== "disconnected" && (await stopDaemon(port))) log("Restarted the daemon for the new pairing.");
+  }
+
+  if (command === "status" || command === "connect" || command === "pair") {
+    const { PAIRING_STEPS, readHost } = await import("./host.js");
+    if (!readHost()) fatal(`This computer is not paired with a phone. ${PAIRING_STEPS}`);
+    if (command !== "status") log("Connecting to the phone. The first time, it asks whether to allow this computer: tap Allow.");
+    const client = await daemonClient(port, enableAdbTool);
+    const result = await client.callTool({ name: "codedroid_status", arguments: {} }, undefined, { timeout: 150_000 });
+    printResult(result);
+    await client.close();
+    const status = JSON.parse(result.content?.[0]?.text ?? "{}");
+    process.exit(status.connected ? 0 : 1);
+  }
+
+  if (command === "call") {
+    const name = args._[1];
+    if (!name) fatal("Usage: codedroid-mcp call <tool> ['{\"arg\": 1}']");
+    let toolArgs = {};
+    if (args._[2]) {
+      try {
+        toolArgs = JSON.parse(args._[2]);
+      } catch (e) {
+        fatal(`Arguments must be JSON: ${e.message}`);
+      }
+    }
+    const client = await daemonClient(port, enableAdbTool);
+    const result = await client.callTool({ name, arguments: toolArgs }, undefined, { timeout: 600_000 });
+    printResult(result);
+    await client.close();
+    process.exit(result.isError ? 1 : 0);
+  }
+
+  if (command) fatal(`Unknown command: ${command}. See codedroid-mcp --help.`);
+
+  const { runStdioShim } = await import("./stdio-shim.js");
+  log(`v${VERSION} · stdio → shared daemon`);
+  await runStdioShim({ port, log, enableAdbTool });
+}
+
+// Expected failures carry a message written for the user; CODEDROID_DEBUG=1 shows the stack.
+main().catch((err) => fatal(process.env.CODEDROID_DEBUG ? err?.stack || String(err) : err?.message || String(err)));

package/src/proxy-core.js

@@ -0,0 +1,294 @@
+/**
+ * proxy-core — builds an MCP Server that transparently forwards requests to a
+ * backend MCP Client (the single phone connection).
+ *
+ * Forked from aura-mcp-connect (MIT, Copyright (c) 2026 Dinesh Kumar C; see
+ * LICENSE.aura-mcp-connect). Changed: a session still opens when the phone cannot be
+ * reached, serving the local tools (adb, codedroid_status) and saying why in its
+ * instructions, and tools/list keeps trying the phone.
+ *
+ * Used twice:
+ *   - daemon: one proxy Server per HTTP client session → phone client
+ *   - stdio shim: one proxy Server on stdio → daemon client
+ *
+ * The proxy advertises exactly the backend's capabilities and instructions,
+ * so downstream agents get the same tool context at handshake as a direct
+ * connection would give them.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+  ListResourcesRequestSchema,
+  ListResourceTemplatesRequestSchema,
+  ReadResourceRequestSchema,
+  CompleteRequestSchema,
+  SetLevelRequestSchema,
+  ListToolsResultSchema,
+  CallToolResultSchema,
+  ListPromptsResultSchema,
+  GetPromptResultSchema,
+  ListResourcesResultSchema,
+  ListResourceTemplatesResultSchema,
+  ReadResourceResultSchema,
+  CompleteResultSchema,
+  EmptyResultSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+/** Device tools drive a real screen — give them a generous budget and let
+ *  progress notifications keep the clock alive. */
+const CALL_TOOL_TIMEOUT_MS = 120_000;
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * Phone tools that never touch the screen, so need not wait behind the calls that do: get_task
+ * alone can wait 55 s for a task, and holding cancel_task behind it would defeat the point.
+ */
+const UNQUEUED_TOOLS = new Set(["get_task", "cancel_task", "device_info"]);
+
+/** The request never reached the phone: the link was already down when it was sent. */
+const NEVER_SENT = /not open|not connected/i;
+/** The link dropped with the request in flight: it may or may not have run. */
+const DROPPED = /connection closed/i;
+
+/** [promise]'s value, or null if it takes longer than [ms]; its rejection still rejects. */
+function within(promise, ms) {
+  if (!Number.isFinite(ms)) return promise;
+  let timer;
+  return Promise.race([promise, new Promise((resolve) => (timer = setTimeout(() => resolve(null), ms)))]).finally(() =>
+    clearTimeout(timer),
+  );
+}
+
+function toolError(text) {
+  return { content: [{ type: "text", text }], isError: true };
+}
+
+/**
+ * @param {object} options
+ * @param {() => Promise<import("@modelcontextprotocol/sdk/client/index.js").Client>} options.getClient
+ *   Resolves the live backend client (reconnecting if needed). Called per
+ *   request so a phone reconnect is picked up transparently.
+ * @param {(fn: () => Promise<any>) => Promise<any>} [options.runExclusive]
+ *   Serializer for tool calls — there is one physical screen, so concurrent
+ *   tool calls from different sessions must queue, not interleave.
+ * @param {() => void} [options.onBackendAlive]
+ *   Called after every successful backend round-trip — lets the connection
+ *   manager treat real traffic as proof of liveness (fewer health pings).
+ * @param {string} options.name
+ * @param {string} options.version
+ * @param {Array<{definition: object, handler: (args: object) => Promise<object>, instructions?: string}>} [options.localTools]
+ *   Tools served entirely by THIS process — never forwarded to the phone.
+ *   Merged into tools/list alongside the backend's tools; tools/call for one
+ *   of these names short-circuits before touching the phone connection at
+ *   all. Used for machine-local capabilities (e.g. `adb`) that make no
+ *   sense to relay over the WebRTC link. Pass only where the tool should
+ *   actually execute (the daemon — see daemon.js); the stdio shim leaves this
+ *   empty and transparently forwards such calls through to the daemon.
+ *   An optional `instructions` string on a local tool is appended to the
+ *   backend's handshake instructions, since the backend cannot describe a tool
+ *   it never sees.
+ * @param {number} [options.connectWaitMs] how long a new session waits for the backend before
+ *   opening with the local tools alone
+ * @param {number} [options.listWaitMs] in such a session, how long tools/list waits for it
+ */
+export async function buildProxyServer({
+  getClient,
+  runExclusive = (fn) => fn(),
+  onBackendAlive = () => {},
+  name,
+  version,
+  localTools = [],
+  connectWaitMs = Infinity,
+  listWaitMs = connectWaitMs,
+}) {
+  const localToolsByName = new Map(localTools.map((t) => [t.definition.name, t]));
+  let backend = null;
+  let backendError = null;
+  try {
+    // The first connect can wait on a person tapping Allow on the phone, longer than clients
+    // wait for a server to start: past connectWaitMs the session opens without the phone, and
+    // the daemon announces its tools (tools/list_changed) once it connects.
+    backend = await within(getClient(), connectWaitMs);
+    if (!backend) throw new Error("Waiting for the phone: if it asks whether to allow this computer, tap Allow.");
+  } catch (e) {
+    // With nothing of our own to serve, a session without the phone is no session.
+    if (localToolsByName.size === 0) throw e;
+    backendError = e;
+  }
+  const backendCaps = backend?.getServerCapabilities() ?? {};
+
+  // Local tools are invisible to the phone, so the phone's instructions can't
+  // mention them. Append their own guidance after it — a tool description is
+  // only read once a model is already picking a tool, whereas instructions
+  // shape strategy before the first call. Phone text stays first and unedited:
+  // it owns the safety doctrine, and these sections defer to it.
+  const unreachable = backendError
+    ? `CodeDroid on the phone is not connected yet: ${String(backendError.message).split("\n")[0]} ` +
+      "Call codedroid_status for what to do; once it connects, its tools appear and codedroid_status " +
+      "returns the phone's own instructions: read them before driving the phone."
+    : null;
+  const instructions = [
+    backend?.getInstructions() ?? unreachable,
+    ...[...localToolsByName.values()].map((t) => t.instructions).filter(Boolean),
+  ]
+    .filter(Boolean)
+    .join("\n\n")
+    .trim() || undefined;
+
+  // Only advertise what we actually forward (and what the phone declared).
+  const capabilities = {};
+  if (backendCaps.tools || localToolsByName.size > 0) {
+    // listChanged: the phone's tools can arrive after the session opened (see connectWaitMs).
+    capabilities.tools = { ...(backendCaps.tools ?? {}), listChanged: localToolsByName.size > 0 || !!backendCaps.tools?.listChanged };
+  }
+  if (backendCaps.prompts) capabilities.prompts = backendCaps.prompts;
+  if (backendCaps.resources) capabilities.resources = backendCaps.resources;
+  if (backendCaps.logging) capabilities.logging = backendCaps.logging;
+  if (backendCaps.completions) capabilities.completions = backendCaps.completions;
+
+  const server = new Server({ name, version }, { capabilities, instructions });
+
+  const forward = (requestSchema, resultSchema, options = {}) => {
+    server.setRequestHandler(requestSchema, async (request) => {
+      const call = async () => {
+        const client = await getClient();
+        return client.request(
+          { method: request.method, params: request.params },
+          resultSchema,
+          {
+            timeout: options.timeout ?? DEFAULT_TIMEOUT_MS,
+            resetTimeoutOnProgress: true,
+          },
+        );
+      };
+      const run = () => (options.exclusive ? runExclusive(call) : call());
+      let result;
+      try {
+        result = await run();
+      } catch (e) {
+        // "Connection closed" = the request never completed against a link
+        // that is now provably dead; getClient() will reconnect. Retry once —
+        // but never for tool calls: a lost RESPONSE still moved real pixels,
+        // and replaying a tap is worse than surfacing the error.
+        const message = e?.message ?? "";
+        if (!(NEVER_SENT.test(message) || DROPPED.test(message)) || options.exclusive) throw e;
+        result = await run();
+      }
+      onBackendAlive();
+      return result;
+    });
+  };
+
+  if (backendCaps.tools || localToolsByName.size > 0) {
+    server.setRequestHandler(ListToolsRequestSchema, async (request) => {
+      const backendResult = backendCaps.tools || backendError
+        ? await (async () => {
+            // A session that opened without the phone does not wait on it here either: the
+            // phone's tools follow in a tools/list_changed once it connects.
+            const client = backendError ? await within(getClient(), listWaitMs) : await getClient();
+            if (!client) return { tools: [] };
+            const result = await client.request(
+              { method: request.method, params: request.params },
+              ListToolsResultSchema,
+              { timeout: DEFAULT_TIMEOUT_MS, resetTimeoutOnProgress: true },
+            );
+            onBackendAlive();
+            return result;
+          })().catch((e) => {
+            // Without local tools a failed list is the client's to see.
+            if (localToolsByName.size === 0) throw e;
+            return { tools: [] };
+          })
+        : { tools: [] };
+      return {
+        ...backendResult,
+        tools: [
+          ...backendResult.tools,
+          ...[...localToolsByName.values()].map((t) => t.definition),
+        ],
+      };
+    });
+
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      // Local tools never touch the phone connection — no need for the
+      // exclusive queue, which exists only to serialize against the one
+      // physical screen.
+      const local = localToolsByName.get(request.params.name);
+      if (local) return local.handler(request.params.arguments ?? {});
+
+      // A failure comes back as a tool error, not a protocol one, so the model reads why. Only a
+      // call that never left is tried again: a tap whose answer was lost still happened, and
+      // replaying it is worse than saying so.
+      const call = async () => {
+        let client;
+        try {
+          client = await getClient();
+        } catch (e) {
+          return { unreachable: e };
+        }
+        return client.request(
+          { method: request.method, params: request.params },
+          CallToolResultSchema,
+          { timeout: CALL_TOOL_TIMEOUT_MS, resetTimeoutOnProgress: true },
+        );
+      };
+      const name = request.params.name;
+      const run = UNQUEUED_TOOLS.has(name) ? call : () => runExclusive(call);
+      let result;
+      for (let attempt = 0; ; attempt++) {
+        try {
+          result = await run();
+          break;
+        } catch (e) {
+          const message = e?.message ?? String(e);
+          if (NEVER_SENT.test(message) && attempt === 0) continue;
+          if (NEVER_SENT.test(message)) return toolError(`CodeDroid on the phone is not connected: ${message} Call codedroid_status.`);
+          return toolError(
+            `The link to the phone failed during ${name} (${message}). It may or may not have happened on the ` +
+              "phone: read the screen with get_screen before trying again. If calls keep failing, call codedroid_status.",
+          );
+        }
+      }
+      if (result.unreachable) {
+        return toolError(`CodeDroid on the phone is not connected: ${result.unreachable.message}\nCall codedroid_status once it is fixed.`);
+      }
+      onBackendAlive();
+      return result;
+    });
+  }
+  if (backendCaps.prompts) {
+    forward(ListPromptsRequestSchema, ListPromptsResultSchema);
+    forward(GetPromptRequestSchema, GetPromptResultSchema);
+  }
+  if (backendCaps.resources) {
+    forward(ListResourcesRequestSchema, ListResourcesResultSchema);
+    forward(ListResourceTemplatesRequestSchema, ListResourceTemplatesResultSchema);
+    forward(ReadResourceRequestSchema, ReadResourceResultSchema);
+  }
+  if (backendCaps.completions) {
+    forward(CompleteRequestSchema, CompleteResultSchema);
+  }
+  if (backendCaps.logging) {
+    forward(SetLevelRequestSchema, EmptyResultSchema);
+  }
+
+  return server;
+}
+
+/**
+ * Forward a notification from the backend to a set of live proxy servers.
+ * Sessions that can't take it (closing, capability mismatch) are skipped —
+ * a notification must never take a session down.
+ */
+export async function broadcastNotification(servers, notification) {
+  for (const server of servers) {
+    try {
+      await server.notification(notification);
+    } catch (e) {
+      // Best-effort fan-out.
+    }
+  }
+}