@codedroid/mcp 0.0.0-stage → 0.1.0

package/src/relay-transport.js

@@ -0,0 +1,190 @@
+/**
+ * RelayPhoneTransport — an MCP SDK `Transport` to CodeDroid on the phone, through the CodeDroid
+ * server's relay.
+ *
+ *   1. Read this computer's pairing (host.js): the server, the host token, the phone.
+ *   2. Open ws(s)://<server>/v1/mcp/connect with the token, plus X-CodeDroid-Client and
+ *      X-CodeDroid-Bridge, from which the server builds the phone's hello. The phone keeps its own
+ *      socket to the server, so neither side needs the other's address.
+ *   3. The first frame is the answer: {type:"approved"} (after the user taps Allow, the first time),
+ *      {type:"denied", reason}, or, from the server, {type:"unavailable", reason}.
+ *   4. Then MCP: one JSON-RPC message per text frame, both ways.
+ *
+ * A library: failures surface through start() rejecting or onclose/onerror, never process.exit().
+ */
+import WebSocket from "ws";
+import { PAIRING_STEPS, pairedDevice, readHost } from "./host.js";
+import { VERSION } from "./version.js";
+
+export class PhoneUnavailableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PhoneUnavailableError";
+  }
+}
+
+export class PhoneDeniedError extends Error {
+  constructor(reason) {
+    super(`The phone refused this computer${reason ? `: ${reason}` : "."}`);
+    this.name = "PhoneDeniedError";
+  }
+}
+
+/** The relay's WebSocket URL for a normalized [server] (host.js): https → wss, http → ws. */
+export function connectUrl(server) {
+  const url = new URL(`${server}/v1/mcp/connect`);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return url.href;
+}
+
+/** A socket error's reason. Node leaves the message empty when every address failed (localhost: ::1 and 127.0.0.1). */
+function errorText(e) {
+  return e.message || e.errors?.map((inner) => inner.message).join("; ") || e.code || String(e);
+}
+
+export class RelayPhoneTransport {
+  /**
+   * @param {object} [options]
+   * @param {Record<string, string | undefined>} [options.env]
+   * @param {number} [options.approvalTimeoutMs] the first time, a person taps Allow on the phone
+   * @param {() => {server: string, host_id: string, token: string, device: {id: string, model: string | null}} | null} [options.host]
+   *   this computer's pairing, null when it has none
+   * @param {(msg: string) => void} [options.log]
+   */
+  constructor(options = {}) {
+    this.onmessage = undefined;
+    this.onclose = undefined;
+    this.onerror = undefined;
+    this.device = null;
+
+    this._env = options.env ?? process.env;
+    this._approvalTimeoutMs = options.approvalTimeoutMs ?? 130_000;
+    this._host = options.host ?? readHost;
+    this._log = options.log ?? (() => {});
+    this._ws = null;
+    this._open = false;
+    this._closed = false;
+  }
+
+  async start() {
+    const host = this._host();
+    if (!host) throw new PhoneUnavailableError(`This computer is not paired with a phone. ${PAIRING_STEPS}`);
+    this.device = pairedDevice(host);
+    this._log(`Phone ${host.device?.id} (${host.device?.model ?? "unknown model"}) through ${host.server}`);
+    await this._handshake(host);
+    this._log("Approved by the phone");
+  }
+
+  _handshake(host) {
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(connectUrl(host.server), {
+        headers: {
+          Authorization: `Bearer ${host.token}`,
+          // Only what the user set: one daemon serves every MCP client here, so a guess from its
+          // environment would name whichever client happened to start it.
+          "X-CodeDroid-Client": this._env.CODEDROID_MCP_CLIENT?.trim() ?? "",
+          "X-CodeDroid-Bridge": VERSION,
+        },
+      });
+      this._ws = ws;
+
+      // Settles the handshake once: resolves without an error, otherwise drops the socket.
+      let pending = true;
+      const settle = (error) => {
+        if (!pending) return;
+        pending = false;
+        clearTimeout(timer);
+        if (!error) {
+          // Before resolving: a frame right behind the answer is already the phone's.
+          this._open = true;
+          resolve();
+          return;
+        }
+        ws.terminate();
+        reject(error);
+      };
+      const timer = setTimeout(
+        () =>
+          settle(
+            new PhoneUnavailableError(
+              `The phone did not answer within ${Math.round(this._approvalTimeoutMs / 1000)} s. If it asked ` +
+                "whether to allow this computer, tap Allow, then try again.",
+            ),
+          ),
+        this._approvalTimeoutMs,
+      );
+
+      ws.on("unexpected-response", (req, res) => {
+        res.resume();
+        settle(
+          new PhoneUnavailableError(
+            res.statusCode === 401 || res.statusCode === 403
+              ? `This computer's pairing was removed or is no longer valid. Pair it again. ${PAIRING_STEPS}`
+              : `The CodeDroid server at ${host.server} refused the connection (HTTP ${res.statusCode}).`,
+          ),
+        );
+      });
+      ws.on("message", (data) => {
+        const line = data.toString("utf8");
+        if (this._open) return void this._deliver(line);
+        if (!pending) return;
+        let reply = null;
+        try {
+          reply = JSON.parse(line);
+        } catch (e) {
+          // Not a handshake answer: refused below.
+        }
+        if (reply?.type === "approved") settle(null);
+        else if (reply?.type === "denied") settle(new PhoneDeniedError(reply.reason));
+        else if (reply?.type === "unavailable") {
+          settle(new PhoneUnavailableError(reply.reason || "The phone is not connected to CodeDroid."));
+        } else {
+          settle(new PhoneUnavailableError("The phone answered something other than a handshake; update codedroid-mcp."));
+        }
+      });
+      ws.on("error", (e) => {
+        if (this._open) this.onerror?.(e);
+        else settle(new PhoneUnavailableError(`Could not reach the CodeDroid server at ${host.server}: ${errorText(e)}`));
+      });
+      ws.on("close", () => {
+        if (this._open) return void this._handleClosed();
+        settle(
+          new PhoneUnavailableError(
+            "The CodeDroid server closed the connection before the phone answered. Check that CodeDroid is open " +
+              "on the phone and online, then try again.",
+          ),
+        );
+      });
+    });
+  }
+
+  _deliver(line) {
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch (e) {
+      this.onerror?.(new Error(`Failed to parse a frame from the phone: ${e.message}`));
+      return;
+    }
+    this.onmessage?.(message);
+  }
+
+  /** @param {import("@modelcontextprotocol/sdk/types.js").JSONRPCMessage} message */
+  async send(message) {
+    const ws = this._ws;
+    if (!this._open || ws.readyState !== WebSocket.OPEN) throw new Error("Phone connection is not open");
+    await new Promise((resolve, reject) => ws.send(JSON.stringify(message), (e) => (e ? reject(e) : resolve())));
+  }
+
+  async close() {
+    this._ws?.close(1000);
+    this._handleClosed();
+  }
+
+  _handleClosed() {
+    if (this._closed) return;
+    this._closed = true;
+    this._open = false;
+    this.onclose?.();
+  }
+}

package/src/skill.js

@@ -0,0 +1,39 @@
+/**
+ * The agent skills that ship with this package: `codedroid-phone` (driving the phone through
+ * CodeDroid) and `test-on-device` (the developer loop: build, install, drive, check, report).
+ *
+ * - The Claude Code plugin (plugin/claude) carries them already; `skill install` is for using the
+ *   MCP server without the plugin: Claude Code (~/.claude/skills), Codex (--codex: ~/.codex/skills),
+ *   or any directory (--dir).
+ * - Change together: the skills name tools, so a renamed tool means editing them
+ *   (test/skill.test.mjs checks every name they use exists).
+ *
+ * Forked from aura-mcp-connect's skill.js (MIT, Copyright (c) 2026 Dinesh Kumar C; see
+ * LICENSE.aura-mcp-connect).
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+
+export const SKILLS = ["codedroid-phone", "test-on-device"];
+
+export const SKILLS_SOURCE = fileURLToPath(new URL("../skills/", import.meta.url));
+
+export function skillSource(name) {
+  return path.join(SKILLS_SOURCE, name, "SKILL.md");
+}
+
+export function defaultSkillsDir({ codex = false } = {}) {
+  return codex ? path.join(os.homedir(), ".codex", "skills") : path.join(os.homedir(), ".claude", "skills");
+}
+
+/** Copies every skill to <dir>/<name>/SKILL.md, overwriting older copies; returns the written paths. */
+export function installSkills({ dir = defaultSkillsDir() } = {}) {
+  return SKILLS.map((name) => {
+    const target = path.join(dir, name, "SKILL.md");
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(skillSource(name), target);
+    return target;
+  });
+}

package/src/status-tool.js

@@ -0,0 +1,49 @@
+/**
+ * codedroid_status — whether CodeDroid on the phone is connected, and if not, what to do about it.
+ *
+ * Served by the daemon itself, so it answers when the phone cannot: the one tool an agent can
+ * call to learn that this computer is not paired, the phone is offline, or the user has not
+ * tapped Allow yet. Calling it also tries to connect again.
+ */
+import { pairedDevice, readHost } from "./host.js";
+import { VERSION } from "./version.js";
+
+const DESCRIPTION =
+  "Whether CodeDroid on the Android phone is connected to this computer (the phone's device id and model, " +
+  "the CodeDroid server), and if not, why and how to fix it. Also retries the connection. Once connected " +
+  "it returns the phone's instructions for driving it.";
+
+/**
+ * @param {import("./daemon.js").PhoneManager} phoneManager
+ * @param {{host?: () => object | null}} [deps] this computer's pairing, for the phone it points at
+ */
+export function createStatusTool(phoneManager, { host = readHost } = {}) {
+  return {
+    definition: {
+      name: "codedroid_status",
+      title: "CodeDroid connection",
+      description: DESCRIPTION,
+      inputSchema: { type: "object", properties: {} },
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    },
+    async handler() {
+      let error = null;
+      let client = null;
+      try {
+        client = await phoneManager.getClient();
+      } catch (e) {
+        error = e.message;
+      }
+      const status = {
+        connected: !error,
+        bridge: VERSION,
+        // Not connected: the phone this computer is paired with now, which a new pairing may have changed.
+        device: client ? phoneManager.device : pairedDevice(host()),
+        ...(error ? { problem: error } : {}),
+        // A session that opened before the phone connected never got these at its handshake.
+        ...(client?.getInstructions() ? { instructions: client.getInstructions() } : {}),
+      };
+      return { content: [{ type: "text", text: JSON.stringify(status, null, 2) }], isError: false };
+    },
+  };
+}

package/src/stdio-shim.js

@@ -0,0 +1,146 @@
+/**
+ * stdio-shim — the `codedroid-mcp` stdio entry point MCP clients launch. It
+ * proxies to the shared local daemon, auto-starting it when needed, so every
+ * client on this computer shares one connection to the phone.
+ *
+ *   IDE ── stdio ── this shim ── HTTP ── daemon ── relay ── CodeDroid on the phone
+ *
+ * Forked from aura-mcp-connect (MIT, Copyright (c) 2026 Dinesh Kumar C; see
+ * LICENSE.aura-mcp-connect).
+ *
+ * Any number of shims (one per IDE/window) share the one phone connection.
+ */
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildProxyServer } from "./proxy-core.js";
+import { DEFAULT_PORT } from "./daemon.js";
+import { daemonTransport } from "./daemon-transport.js";
+import { VERSION } from "./version.js";
+
+/** The daemon's /health on [port], or null when no CodeDroid daemon answers there. */
+export async function fetchHealth(port, timeoutMs = 1500) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/health`, {
+      signal: controller.signal,
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return body?.service === "codedroid-mcp-daemon" ? body : null;
+  } catch (e) {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function ensureDaemonRunning(port, log, { enableAdbTool = true } = {}) {
+  const existing = await fetchHealth(port);
+  if (existing) {
+    // A daemon's tool set is fixed at startup, so an already-running one can't
+    // be changed by a later client. Say so, or the user has nothing to go on.
+    if (enableAdbTool !== existing.adbToolEnabled) {
+      log(
+        `A daemon is already running on port ${port} with the adb tool ` +
+          `${existing.adbToolEnabled ? "on" : "off"}; CODEDROID_MCP_ADB had no effect. ` +
+          `Stop that daemon (codedroid-mcp stop) and let this client restart it.`,
+      );
+    }
+    return;
+  }
+
+  log(`Daemon not running — starting it on port ${port}...`);
+  const indexPath = fileURLToPath(new URL("./index.js", import.meta.url));
+  // Env (and therefore CODEDROID_MCP_ADB) is inherited — deliberately not
+  // filtered here, since that inheritance is what lets a client arm the daemon
+  // it auto-starts. The argv is fixed, so a CLI flag could never reach here.
+  const child = spawn(process.execPath, [indexPath, "daemon", `--port=${port}`], {
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+  });
+  child.unref();
+
+  const deadline = Date.now() + 20_000;
+  while (Date.now() < deadline) {
+    if (await fetchHealth(port)) {
+      log("Daemon is up.");
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 300));
+  }
+  throw new Error(
+    `Could not start the CodeDroid MCP daemon on port ${port} within 20s. ` +
+      `Try running it manually to see why: codedroid-mcp daemon --port=${port}`,
+  );
+}
+
+/**
+ * Run the stdio shim until the IDE closes stdin or the daemon goes away.
+ * @param {object} [options]
+ * @param {number} [options.port]
+ * @param {(msg: string) => void} [options.log] stderr logger
+ * @param {boolean} [options.enableAdbTool] Only used to warn when an already-
+ *   running daemon can't honour the request — the shim never registers the
+ *   tool itself, it forwards through to whichever daemon owns it.
+ */
+export async function runStdioShim({
+  port = DEFAULT_PORT,
+  log = () => {},
+  enableAdbTool = true,
+} = {}) {
+  await ensureDaemonRunning(port, log, { enableAdbTool });
+
+  const client = new Client({ name: "codedroid-mcp-shim", version: VERSION });
+  const httpTransport = daemonTransport(port);
+  // Long initialize budget: the daemon may be doing the first phone connect
+  // (including the on-phone approval tap) behind this call.
+  await client.connect(httpTransport, { timeout: 150_000 });
+
+  const server = await buildProxyServer({
+    getClient: async () => client,
+    name: "codedroid",
+    version: VERSION,
+  });
+
+  // Pass phone/daemon notifications through to the IDE.
+  client.fallbackNotificationHandler = async (notification) => {
+    try {
+      await server.notification(notification);
+    } catch (e) {
+      /* session closing — drop */
+    }
+  };
+
+  client.onclose = () => {
+    log("Daemon connection closed — exiting so the IDE can reconnect.");
+    process.exit(1);
+  };
+
+  const stdioTransport = new StdioServerTransport();
+  let closing = false;
+  const shutdown = async () => {
+    if (closing) return;
+    closing = true;
+    // IDE closed our stdin — release the daemon session and leave cleanly.
+    client.onclose = undefined;
+    try {
+      await client.close();
+    } catch (e) {
+      /* already gone */
+    }
+    process.exit(0);
+  };
+  server.onclose = shutdown;
+  // The SDK's stdio transport does not close itself at EOF. Without these hooks the
+  // client eventually kills the shim and its daemon session is left behind.
+  process.stdin.once("end", shutdown);
+  process.once("SIGTERM", shutdown);
+  process.once("SIGINT", shutdown);
+
+  await server.connect(stdioTransport);
+  log(`Bridging stdio ↔ daemon on port ${port}.`);
+}

package/src/version.js

@@ -0,0 +1,2 @@
+/** The bridge's version, sent to the phone in its hello and shown by `--version`. */
+export const VERSION = "0.1.0";