@polypad/mcp 0.1.0 → 0.1.1

package/README.md

@@ -38,6 +38,16 @@ claude mcp add polypad -- npx -y @polypad/mcp
 
 Safari cannot connect to a local server, so use Chrome, Edge or Firefox for the Polypad tab. The claude.ai website cannot be used either: it needs a hosted server.
 
+## Several AI clients at once
+
+You can add Polypad to Claude Code and Claude Desktop (or Cursor) and use them at the same time. The first server to start owns the connection and the others share it, so every client drives the same Polypad tab and there is one pairing code. If the first one is closed, another takes over with a new code: enter it in the Connect AI dialog. Use version 0.1.1 or newer everywhere.
+
+## Troubleshooting
+
+- **"Server not running"** in the dialog: your AI client has not started the server yet. Ask it something about Polypad, and check `npx -y @polypad/mcp --help` works (Node 22 or newer).
+- **"Wrong code"**: enter the code from the latest start. It changes whenever the connection's owner restarts.
+- **"Port 41720 is already in use"** (the tools say so): a program that is not a Polypad MCP server (or an old 0.1.0 one) holds the port. Close it, or use `--port 41721` here and in the dialog's Advanced section. The server checks again every 2 seconds.
+
 ## Options
 
 ```

package/dist/index.js

@@ -9446,7 +9446,7 @@ var require_websocket = __commonJS({
     var http = __require("http");
     var net = __require("net");
     var tls = __require("tls");
-    var { randomBytes, createHash } = __require("crypto");
+    var { randomBytes: randomBytes2, createHash } = __require("crypto");
     var { Duplex, Readable } = __require("stream");
     var { URL: URL2 } = __require("url");
     var PerMessageDeflate2 = require_permessage_deflate();
@@ -9997,7 +9997,7 @@ var require_websocket = __commonJS({
         }
       }
       const defaultPort = isSecure ? 443 : 80;
-      const key = randomBytes(16).toString("base64");
+      const key = randomBytes2(16).toString("base64");
       const request = isSecure ? https.request : http.request;
       const protocolSet = /* @__PURE__ */ new Set();
       let perMessageDeflate;
@@ -32205,6 +32205,8 @@ var CLOSE_BAD_MESSAGE = 4004;
 var CLOSE_BAD_VERSION = 4005;
 var CLOSE_HELLO_TIMEOUT = 4006;
 var CLOSE_SHUTDOWN = 4007;
+var CLOSE_BAD_TOKEN = 4008;
+var BRIDGE_RETRY_MS = 2e3;
 var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 function parse3(text) {
   try {
@@ -32234,6 +32236,37 @@ function parseTabMessage(text) {
       return null;
   }
 }
+function parseClientMessage(text) {
+  const m = parse3(text);
+  if (!m) return null;
+  switch (m.type) {
+    case "relay-hello":
+      if (typeof m.token !== "string" || typeof m.v !== "number") return null;
+      return { type: "relay-hello", v: m.v, token: m.token };
+    case "relay-call":
+      if (typeof m.id !== "string" || typeof m.name !== "string") return null;
+      return { type: "relay-call", id: m.id, name: m.name, input: m.input };
+    default:
+      return parseTabMessage(text);
+  }
+}
+function parsePrimaryMessage(text) {
+  const m = parse3(text);
+  if (!m) return null;
+  switch (m.type) {
+    case "relay-welcome":
+      if (typeof m.v !== "number" || typeof m.code !== "string") return null;
+      return { type: "relay-welcome", v: m.v, code: m.code, server: typeof m.server === "string" ? m.server : void 0 };
+    case "relay-result":
+      if (typeof m.id !== "string" || !isResult(m.result)) return null;
+      return { type: "relay-result", id: m.id, result: m.result };
+    case "ping":
+    case "pong":
+      return { type: m.type };
+    default:
+      return null;
+  }
+}
 var encode3 = (message) => JSON.stringify(message);
 var PAIRING_ALPHABET = "ABCDEFGHJKMNPQRTUVWXYZ346789";
 var CODE_SHAPE = /^[A-Z0-9]{3}-?[A-Z0-9]{3}$/;
@@ -32243,6 +32276,7 @@ function normalizePairingCode(input2) {
   const code = `${flat.slice(0, 3)}-${flat.slice(3)}`;
   return CODE_SHAPE.test(code) ? code : null;
 }
+var bridgeUrl = (port = BRIDGE_DEFAULT_PORT) => `ws://127.0.0.1:${port}`;
 
 // src/cli.ts
 var USAGE = `polypad-mcp: MCP server that lets an AI assistant build in your open Polypad tab.
@@ -32259,6 +32293,10 @@ Options:
 The MCP client starts this program and talks to it over stdio. It prints a pairing code to stderr
 (new on every start). In Polypad, click Connect AI and enter the code.
 
+Several clients (Claude Code and Claude Desktop, say) can each start one: the first owns the port and
+the others share its Polypad tab and its code. Environment: POLYPAD_MCP_HOME moves the folder that
+holds .polypad/mcp-<port>.json (default: your home folder).
+
 Add it to Claude Code:  claude mcp add polypad -- npx -y @polypad/mcp
 `;
 function parseCli(argv) {
@@ -34802,7 +34840,7 @@ function commandSchemas() {
 }
 
 // src/bridge.ts
-import { randomInt, randomUUID, timingSafeEqual } from "crypto";
+import { randomBytes, randomInt, randomUUID as randomUUID2 } from "crypto";
 import { createServer } from "http";
 
 // ../../node_modules/.pnpm/ws@8.22.0/node_modules/ws/wrapper.mjs
@@ -34814,6 +34852,176 @@ var import_sender = __toESM(require_sender(), 1);
 var import_subprotocol = __toESM(require_subprotocol(), 1);
 var import_websocket = __toESM(require_websocket(), 1);
 var import_websocket_server = __toESM(require_websocket_server(), 1);
+var wrapper_default = import_websocket.default;
+
+// src/primary-file.ts
+import { timingSafeEqual } from "crypto";
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+function resolveHome(override) {
+  return override ?? (process.env.POLYPAD_MCP_HOME || homedir());
+}
+var primaryFilePath = (home, port) => join(home, ".polypad", `mcp-${port}.json`);
+function writePrimaryFile(home, port, info) {
+  const file2 = primaryFilePath(home, port);
+  mkdirSync(join(home, ".polypad"), { recursive: true, mode: 448 });
+  writeFileSync(file2, JSON.stringify(info), { mode: 384 });
+  try {
+    chmodSync(file2, 384);
+  } catch {
+  }
+}
+function readPrimaryFile(home, port) {
+  try {
+    const value = JSON.parse(readFileSync(primaryFilePath(home, port), "utf8"));
+    if (typeof value !== "object" || value === null) return null;
+    const { pid, token, code } = value;
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0 || typeof token !== "string" || token.length < 16 || typeof code !== "string") return null;
+    return { pid, token, code };
+  } catch {
+    return null;
+  }
+}
+function removePrimaryFile(home, port, token) {
+  try {
+    const current = readPrimaryFile(home, port);
+    if (current && !tokensMatch(current.token, token)) return;
+    rmSync(primaryFilePath(home, port), { force: true });
+  } catch {
+  }
+}
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error62) {
+    return error62.code === "EPERM";
+  }
+}
+function tokensMatch(a, b) {
+  const x = Buffer.from(a);
+  const y = Buffer.from(b);
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+
+// src/relay-link.ts
+import { randomUUID } from "crypto";
+var fail = (text) => ({ ok: false, text });
+var RelayLink = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  // The primary's pairing code, from relay-welcome.
+  code = "";
+  ws = null;
+  open = false;
+  pending = /* @__PURE__ */ new Map();
+  closeHandler = null;
+  get connected() {
+    return this.open;
+  }
+  // Resolves once the primary has welcomed this relay. Rejects (and leaves nothing open) for anything else.
+  connect() {
+    return new Promise((resolve, reject) => {
+      const ws = new wrapper_default(bridgeUrl(this.options.port), { maxPayload: BRIDGE_MAX_MESSAGE_BYTES, perMessageDeflate: false, handshakeTimeout: this.options.handshakeTimeoutMs ?? 3e3 });
+      this.ws = ws;
+      let settled = false;
+      const giveUp = (reason) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(helloTimer);
+        ws.terminate();
+        this.ws = null;
+        reject(new Error(reason));
+      };
+      const helloTimer = setTimeout(() => giveUp("No answer to relay-hello"), this.options.handshakeTimeoutMs ?? 3e3);
+      ws.on("error", (error62) => giveUp(error62.message));
+      ws.on("open", () => ws.send(encode3({ type: "relay-hello", v: BRIDGE_PROTOCOL_VERSION, token: this.options.token })));
+      ws.on("message", (data, isBinary) => {
+        if (isBinary) return void ws.close(1003, "Text frames only");
+        const message = parsePrimaryMessage(rawToString(data));
+        if (!message) return void (settled ? ws.close(1002, "Not a Polypad bridge message") : giveUp("Not a Polypad MCP server"));
+        switch (message.type) {
+          case "relay-welcome":
+            if (settled) return;
+            settled = true;
+            clearTimeout(helloTimer);
+            this.code = message.code;
+            this.open = true;
+            resolve();
+            return;
+          case "relay-result": {
+            const entry = this.pending.get(message.id);
+            if (!entry) return;
+            clearTimeout(entry.timer);
+            this.pending.delete(message.id);
+            entry.resolve(message.result);
+            return;
+          }
+          case "ping":
+            if (ws.readyState === ws.OPEN) ws.send(encode3({ type: "pong" }));
+            return;
+          case "pong":
+            return;
+        }
+      });
+      ws.on("close", (_code, reason) => {
+        if (!settled) return giveUp(reason.toString() || "Closed before relay-welcome");
+        const wasOpen = this.open;
+        this.open = false;
+        this.ws = null;
+        this.failAll("The Polypad MCP server that this one shares stopped before Polypad answered. The change may or may not have been applied: call get_project to check (this server reconnects by itself).");
+        if (wasOpen) this.closeHandler?.();
+      });
+    });
+  }
+  // Called once when an established link ends (the primary exited), not when close() is used.
+  onClose(handler) {
+    this.closeHandler = handler;
+  }
+  // Never rejects: every failure is an ok:false result with text for the model.
+  call(name, input2) {
+    const ws = this.ws;
+    if (!ws || !this.open) return Promise.resolve(fail("The link to the shared Polypad MCP server is down."));
+    const id = randomUUID();
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        resolve(fail(`Polypad did not answer ${name} within ${Math.round(this.options.callTimeoutMs / 1e3)} s. The change may still have been applied: call get_project to check before retrying.`));
+      }, this.options.callTimeoutMs);
+      this.pending.set(id, { resolve, timer, name });
+      try {
+        ws.send(encode3({ type: "relay-call", id, name, input: input2 }));
+      } catch (error62) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        resolve(fail(`Could not send ${name} to the shared Polypad MCP server: ${error62 instanceof Error ? error62.message : String(error62)}`));
+      }
+    });
+  }
+  close() {
+    this.closeHandler = null;
+    this.open = false;
+    this.failAll("The Polypad MCP server stopped before Polypad answered.");
+    this.ws?.terminate();
+    this.ws = null;
+  }
+  failAll(text) {
+    for (const [id, entry] of [...this.pending]) {
+      clearTimeout(entry.timer);
+      this.pending.delete(id);
+      entry.resolve(fail(text));
+    }
+  }
+};
+function rawToString(data) {
+  if (typeof data === "string") return data;
+  if (Array.isArray(data)) return Buffer.concat(data).toString("utf8");
+  if (data instanceof ArrayBuffer) return Buffer.from(data).toString("utf8");
+  return data.toString("utf8");
+}
 
 // src/bridge.ts
 function newPairingCode() {
@@ -34824,30 +35032,39 @@ function newPairingCode() {
 function normalizeOrigin(origin) {
   return origin.trim().replace(/\/+$/, "").toLowerCase();
 }
-function codesMatch(a, b) {
-  const x = Buffer.from(a);
-  const y = Buffer.from(b);
-  return x.length === y.length && timingSafeEqual(x, y);
-}
-var fail = (text) => ({ ok: false, text });
+var fail2 = (text) => ({ ok: false, text });
 var Bridge = class {
-  code;
   allowedOrigins;
   options;
+  home;
   requestedPort;
+  ownCode;
+  firstAttach = true;
+  closed = false;
+  attaching = false;
+  retryTimer = null;
   http = null;
   wss = null;
   tab = null;
   tabName;
   pending = /* @__PURE__ */ new Map();
   badCodeTimes = [];
+  badTokenTimes = [];
   pingTimer = null;
   alive = /* @__PURE__ */ new WeakSet();
+  // Primary: the secret the relays have to present, and the relays that did.
+  relayToken = null;
+  relays = /* @__PURE__ */ new Set();
+  // Relay: the link to the primary and its pairing code.
+  link = null;
+  linkCode = "";
   // Set when the socket could not be opened (port in use): every call then answers with this.
   unavailable = null;
   port = 0;
+  role = "starting";
   constructor(options = {}) {
-    this.code = options.code ?? newPairingCode();
+    this.ownCode = options.code ?? newPairingCode();
+    this.home = resolveHome(options.homeDir);
     this.requestedPort = options.port ?? BRIDGE_DEFAULT_PORT;
     this.allowedOrigins = new Set([...BRIDGE_DEFAULT_ORIGINS, ...options.origins ?? []].map(normalizeOrigin));
     this.options = {
@@ -34856,65 +35073,45 @@ var Bridge = class {
       badCodeWindowMs: options.badCodeWindowMs ?? 6e4,
       helloTimeoutMs: options.helloTimeoutMs ?? 1e4,
       pingIntervalMs: options.pingIntervalMs ?? 2e4,
+      retryMs: options.retryMs ?? BRIDGE_RETRY_MS,
       log: options.log ?? (() => {
       })
     };
   }
+  // The pairing code the user enters in the tab: this server's own as primary, the primary's as a relay.
+  get code() {
+    return this.role === "relay" ? this.linkCode : this.ownCode;
+  }
+  // A primary: whether the tab is paired. A relay: whether the link to the primary is up (the primary answers
+  // "not connected" itself when it has no tab).
   get connected() {
-    return this.tab !== null;
+    if (this.role === "relay") return this.link?.connected ?? false;
+    return this.role === "primary" && this.tab !== null;
   }
   get clientName() {
     return this.tabName;
   }
-  // Starts listening on 127.0.0.1. Rejects (for example EADDRINUSE) without leaving anything open.
-  listen() {
-    return new Promise((resolve, reject) => {
-      const http = createServer((_req, res) => {
-        res.writeHead(426, { "content-type": "text/plain" });
-        res.end("Polypad MCP bridge: WebSocket only.\n");
-      });
-      const wss = new import_websocket_server.default({
-        noServer: true,
-        maxPayload: BRIDGE_MAX_MESSAGE_BYTES,
-        perMessageDeflate: false
-      });
-      http.on("upgrade", (req, socket, head) => {
-        const origin = req.headers.origin;
-        if (typeof origin !== "string" || !this.allowedOrigins.has(normalizeOrigin(origin))) {
-          this.options.log(`Rejected a connection from origin ${typeof origin === "string" ? origin : "(none)"}. Add it with --origin if it is yours.`);
-          socket.end("HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
-          return;
-        }
-        if (wss.clients.size >= 16) {
-          socket.end("HTTP/1.1 503 Service Unavailable\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
-          return;
-        }
-        wss.handleUpgrade(req, socket, head, (ws) => this.accept(ws));
-      });
-      http.once("error", (error62) => {
-        wss.close();
-        reject(error62);
-      });
-      http.listen(this.requestedPort, "127.0.0.1", () => {
-        this.http = http;
-        this.wss = wss;
-        this.port = http.address().port;
-        http.on("error", (error62) => this.options.log(`Bridge error: ${error62.message}`));
-        this.startPings();
-        resolve(this.port);
-      });
-    });
+  // Starts serving on 127.0.0.1 as the primary, or, when the port is taken by a Polypad MCP server, relays through it.
+  // Resolves with the port. When the port holder is something else this still resolves (role "busy": the tools explain
+  // it and the server keeps trying); other errors, for example EACCES, reject.
+  async listen() {
+    await this.attach(true);
+    return this.port;
   }
   // Runs a command on the paired tab. Never rejects: every failure is an ok:false result with text for the model.
   call(name, input2) {
+    if (this.role === "relay") {
+      const link = this.link;
+      return link ? link.call(name, input2) : Promise.resolve(fail2(this.notConnectedText()));
+    }
     const tab = this.tab;
-    if (!tab) return Promise.resolve(fail(this.notConnectedText()));
-    const id = randomUUID();
+    if (!tab) return Promise.resolve(fail2(this.notConnectedText()));
+    const id = randomUUID2();
     return new Promise((resolve) => {
       const timer = setTimeout(() => {
         this.pending.delete(id);
         resolve(
-          fail(
+          fail2(
             `Polypad did not answer ${name} within ${Math.round(this.options.callTimeoutMs / 1e3)} s. The change may still have been applied: call get_project to check before retrying.`
           )
         );
@@ -34923,7 +35120,7 @@ var Bridge = class {
       try {
         tab.send(encode3({ type: "call", id, name, input: input2 }));
       } catch (error62) {
-        this.settle(id, fail(`Could not send ${name} to Polypad: ${error62 instanceof Error ? error62.message : String(error62)}`));
+        this.settle(id, fail2(`Could not send ${name} to Polypad: ${error62 instanceof Error ? error62.message : String(error62)}`));
       }
     });
   }
@@ -34933,11 +35130,18 @@ var Bridge = class {
     return `Polypad is not connected. Open Polypad in Chrome, Edge or Firefox, click Connect AI and enter code ${this.code}.${port}`;
   }
   async close() {
+    this.closed = true;
+    if (this.retryTimer) clearTimeout(this.retryTimer);
+    this.retryTimer = null;
+    this.releaseSync();
+    this.link?.close();
+    this.link = null;
     if (this.pingTimer) clearInterval(this.pingTimer);
     this.pingTimer = null;
     for (const client of this.wss?.clients ?? []) client.close(CLOSE_SHUTDOWN, "Server stopped");
     this.failPending(null, "The Polypad MCP server stopped before Polypad answered.");
     this.tab = null;
+    this.relays.clear();
     const http = this.http;
     this.http = null;
     this.wss?.close();
@@ -34949,15 +35153,147 @@ var Bridge = class {
       });
     }
   }
-  // --- internals --------------------------------------------------------------------------------------------------
+  // Deletes the file that tells other servers to relay through this one; safe to call from a process "exit" handler.
+  releaseSync() {
+    if (this.relayToken) removePrimaryFile(this.home, this.port, this.relayToken);
+    this.relayToken = null;
+  }
+  // --- roles ------------------------------------------------------------------------------------------------------
+  // Finds this server's role: primary if it can bind the port, else relay if a live Polypad MCP server holds it, else busy.
+  async attach(initial) {
+    if (this.closed || this.attaching) return;
+    this.attaching = true;
+    try {
+      try {
+        await this.bind();
+        this.becomePrimary();
+        return;
+      } catch (error62) {
+        if (error62.code !== "EADDRINUSE") {
+          if (initial) throw error62;
+          this.options.log(`Could not open the bridge: ${error62.message}`);
+          this.becomeBusy(`Polypad's local bridge could not start: ${error62.message}`);
+          return;
+        }
+      }
+      if (this.closed) return;
+      if (await this.tryRelay()) return;
+      this.becomeBusy(
+        `Polypad's local bridge could not start: port ${this.requestedPort} is already in use by a program that is not a Polypad MCP server this one can share. Tell the user: close that program, or start the Polypad server with --port <other> (and enter the same port in the Connect AI dialog). This server keeps checking and shares the connection by itself once the port is free.`
+      );
+    } finally {
+      this.attaching = false;
+    }
+  }
+  becomePrimary() {
+    this.role = "primary";
+    this.unavailable = null;
+    if (!this.firstAttach) this.ownCode = newPairingCode();
+    this.firstAttach = false;
+    this.relayToken = randomBytes(32).toString("base64url");
+    let shared = true;
+    try {
+      writePrimaryFile(this.home, this.port, { pid: process.pid, token: this.relayToken, code: this.ownCode });
+    } catch (error62) {
+      shared = false;
+      this.relayToken = null;
+      this.options.log(`Could not write the file other Polypad MCP servers use to share this one: ${error62.message}`);
+    }
+    this.options.log(`Polypad MCP server ready on ws://127.0.0.1:${this.port}${shared ? "" : " (not shareable with other MCP clients)"}`);
+    this.options.log(`Pairing code: ${this.ownCode}   (open Polypad, click Connect AI, enter this code)`);
+  }
+  async tryRelay() {
+    const info = readPrimaryFile(this.home, this.requestedPort);
+    if (!info || !pidAlive(info.pid)) return false;
+    const link = new RelayLink({ port: this.requestedPort, token: info.token, callTimeoutMs: this.options.callTimeoutMs });
+    try {
+      await link.connect();
+    } catch (error62) {
+      this.options.log(`Port ${this.requestedPort} is taken and the Polypad MCP server there did not accept this one as a relay: ${error62.message}`);
+      return false;
+    }
+    if (this.closed) {
+      link.close();
+      return true;
+    }
+    this.link = link;
+    this.linkCode = link.code;
+    this.port = this.requestedPort;
+    this.role = "relay";
+    this.firstAttach = false;
+    this.unavailable = null;
+    link.onClose(() => {
+      if (this.link !== link) return;
+      this.link = null;
+      this.role = "busy";
+      this.options.log("The Polypad MCP server this one was sharing stopped. Looking for a new one to share, or taking over.");
+      void this.attach(false).catch((error62) => this.options.log(`Bridge error: ${error62.message}`));
+    });
+    this.options.log(`Port ${this.requestedPort} is used by another Polypad MCP server (pid ${info.pid}): relaying through it, same Polypad tab and same code.`);
+    this.options.log(`Pairing code: ${this.linkCode}   (open Polypad, click Connect AI, enter this code)`);
+    return true;
+  }
+  becomeBusy(text) {
+    const first = this.role !== "busy" || this.unavailable !== text;
+    this.role = "busy";
+    this.port = this.requestedPort;
+    this.unavailable = text;
+    if (first) this.options.log(`Could not open the bridge: port ${this.requestedPort} is already in use. Trying again every ${Math.round(this.options.retryMs / 1e3)} s. Start with --port <other> to use another port.`);
+    if (this.closed) return;
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = null;
+      void this.attach(false).catch((error62) => this.options.log(`Bridge error: ${error62.message}`));
+    }, this.options.retryMs);
+    this.retryTimer.unref();
+  }
+  // --- the primary's socket server --------------------------------------------------------------------------------
+  // Starts listening on 127.0.0.1. Rejects (for example EADDRINUSE) without leaving anything open.
+  bind() {
+    return new Promise((resolve, reject) => {
+      const http = createServer((_req, res) => {
+        res.writeHead(426, { "content-type": "text/plain" });
+        res.end("Polypad MCP bridge: WebSocket only.\n");
+      });
+      const wss = new import_websocket_server.default({
+        noServer: true,
+        maxPayload: BRIDGE_MAX_MESSAGE_BYTES,
+        perMessageDeflate: false
+      });
+      http.on("upgrade", (req, socket, head) => {
+        const origin = req.headers.origin;
+        if (origin !== void 0 && (typeof origin !== "string" || !this.allowedOrigins.has(normalizeOrigin(origin)))) {
+          this.options.log(`Rejected a connection from origin ${typeof origin === "string" ? origin : "(unreadable)"}. Add it with --origin if it is yours.`);
+          socket.end("HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
+          return;
+        }
+        if (wss.clients.size >= 16) {
+          socket.end("HTTP/1.1 503 Service Unavailable\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
+          return;
+        }
+        wss.handleUpgrade(req, socket, head, (ws) => this.accept(ws, origin !== void 0));
+      });
+      http.once("error", (error62) => {
+        wss.close();
+        reject(error62);
+      });
+      http.listen(this.requestedPort, "127.0.0.1", () => {
+        this.http = http;
+        this.wss = wss;
+        this.port = http.address().port;
+        http.on("error", (error62) => this.options.log(`Bridge error: ${error62.message}`));
+        this.startPings();
+        resolve();
+      });
+    });
+  }
   send(ws, message) {
     if (ws.readyState === ws.OPEN) ws.send(encode3(message));
   }
-  accept(ws) {
+  accept(ws, hasOrigin) {
     this.alive.add(ws);
-    let paired = false;
+    let kind = "unknown";
     const helloTimer = setTimeout(() => {
-      if (!paired) ws.close(CLOSE_HELLO_TIMEOUT, "No hello received");
+      if (kind === "unknown") ws.close(CLOSE_HELLO_TIMEOUT, "No hello received");
     }, this.options.helloTimeoutMs);
     ws.on("pong", () => this.alive.add(ws));
     ws.on("error", () => {
@@ -34965,7 +35301,7 @@ var Bridge = class {
     ws.on("message", (data, isBinary) => {
       this.alive.add(ws);
       if (isBinary) return void ws.close(CLOSE_BAD_MESSAGE, "Text frames only");
-      const message = parseTabMessage(rawToString(data));
+      const message = parseClientMessage(rawToString2(data));
       if (!message) return void ws.close(CLOSE_BAD_MESSAGE, "Not a Polypad bridge message");
       switch (message.type) {
         case "ping":
@@ -34973,10 +35309,26 @@ var Bridge = class {
         case "pong":
           return;
         case "hello":
-          if (paired) return;
-          paired = this.pair(ws, message.code, message.v, message.client);
-          if (paired) clearTimeout(helloTimer);
+          if (kind !== "unknown") return;
+          if (!hasOrigin) return void ws.close(CLOSE_BAD_MESSAGE, "A Polypad tab connects from a web page (no Origin header)");
+          if (this.pair(ws, message.code, message.v, message.client)) {
+            kind = "tab";
+            clearTimeout(helloTimer);
+          }
           return;
+        case "relay-hello":
+          if (kind !== "unknown") return;
+          if (this.admitRelay(ws, message.token, message.v)) {
+            kind = "relay";
+            clearTimeout(helloTimer);
+          }
+          return;
+        case "relay-call": {
+          if (kind !== "relay") return void ws.close(CLOSE_BAD_MESSAGE, "Say relay-hello first");
+          const { id } = message;
+          void this.call(message.name, message.input).then((result) => this.send(ws, { type: "relay-result", id, result }));
+          return;
+        }
         case "result":
           if (this.tab !== ws) return void ws.close(CLOSE_BAD_MESSAGE, "Pair first");
           if (this.pending.get(message.id)?.socket === ws) this.settle(message.id, message.result);
@@ -34985,6 +35337,10 @@ var Bridge = class {
     });
     ws.on("close", () => {
       clearTimeout(helloTimer);
+      if (kind === "relay") {
+        this.relays.delete(ws);
+        this.options.log("A Polypad MCP server that shared this one has left.");
+      }
       if (this.tab === ws) {
         this.tab = null;
         this.tabName = void 0;
@@ -34993,17 +35349,21 @@ var Bridge = class {
       this.failPending(ws, "Polypad disconnected before it answered (the tab was closed, reloaded or disconnected). The change may or may not have been applied. Ask the user to reconnect with Connect AI, then call get_project.");
     });
   }
+  // Wrong attempts within the window; true when no more are tolerated.
+  tooMany(times) {
+    const now = Date.now();
+    while (times.length && now - times[0] > this.options.badCodeWindowMs) times.shift();
+    return times.length >= this.options.maxBadCodes;
+  }
   // Returns true when the tab is now the paired one; otherwise closes it with the reason.
   pair(ws, code, version2, client) {
-    const now = Date.now();
-    while (this.badCodeTimes.length && now - this.badCodeTimes[0] > this.options.badCodeWindowMs) this.badCodeTimes.shift();
-    if (this.badCodeTimes.length >= this.options.maxBadCodes) {
+    if (this.tooMany(this.badCodeTimes)) {
       ws.close(CLOSE_RATE_LIMITED, "Too many wrong codes. Wait a minute or restart the MCP server.");
       return false;
     }
     const given = normalizePairingCode(code);
-    if (!given || !codesMatch(given, this.code)) {
-      this.badCodeTimes.push(now);
+    if (!given || !tokensMatch(given, this.ownCode)) {
+      this.badCodeTimes.push(Date.now());
       this.options.log("Rejected a pairing attempt with a wrong code.");
       ws.close(CLOSE_BAD_CODE, "Wrong pairing code");
       return false;
@@ -35024,6 +35384,27 @@ var Bridge = class {
     this.options.log(`Polypad connected${client ? ` (${client})` : ""}.`);
     return true;
   }
+  // Returns true when the socket is now a relay; otherwise closes it with the reason.
+  admitRelay(ws, token, version2) {
+    if (this.tooMany(this.badTokenTimes)) {
+      ws.close(CLOSE_RATE_LIMITED, "Too many wrong tokens");
+      return false;
+    }
+    if (!this.relayToken || !tokensMatch(token, this.relayToken)) {
+      this.badTokenTimes.push(Date.now());
+      this.options.log("Rejected a relay with a wrong token.");
+      ws.close(CLOSE_BAD_TOKEN, "Wrong relay token");
+      return false;
+    }
+    if (version2 !== BRIDGE_PROTOCOL_VERSION) {
+      ws.close(CLOSE_BAD_VERSION, `Protocol version ${version2} is not supported (server speaks ${BRIDGE_PROTOCOL_VERSION})`);
+      return false;
+    }
+    this.relays.add(ws);
+    this.send(ws, { type: "relay-welcome", v: BRIDGE_PROTOCOL_VERSION, code: this.ownCode, server: "polypad-mcp" });
+    this.options.log("Another Polypad MCP server (Claude Code or Desktop, say) now shares this one.");
+    return true;
+  }
   settle(id, result) {
     const entry = this.pending.get(id);
     if (!entry) return;
@@ -35034,7 +35415,7 @@ var Bridge = class {
   // Fails the calls waiting on `socket`, or all of them when it is null.
   failPending(socket, text) {
     for (const [id, entry] of [...this.pending]) {
-      if (socket === null || entry.socket === socket) this.settle(id, fail(text));
+      if (socket === null || entry.socket === socket) this.settle(id, fail2(text));
     }
   }
   startPings() {
@@ -35057,7 +35438,7 @@ var Bridge = class {
     this.pingTimer.unref();
   }
 };
-function rawToString(data) {
+function rawToString2(data) {
   if (typeof data === "string") return data;
   if (Array.isArray(data)) return Buffer.concat(data).toString("utf8");
   if (data instanceof ArrayBuffer) return Buffer.from(data).toString("utf8");
@@ -35104,7 +35485,7 @@ function createPolypadMcp(options = {}) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.1.0" : "0.0.0-dev";
+var VERSION = true ? "0.1.1" : "0.0.0-dev";
 var err = (line2) => process.stderr.write(`${line2}
 `);
 async function main() {
@@ -35129,12 +35510,9 @@ ${USAGE}`);
   const mcp = createPolypadMcp({ port: cli.port, origins: cli.origins, version: VERSION, log: err });
   try {
     await mcp.bridge.listen();
-    err(`Polypad MCP server ready on ws://127.0.0.1:${mcp.bridge.port}`);
-    err(`Pairing code: ${mcp.bridge.code}   (open Polypad, click Connect AI, enter this code)`);
   } catch (error62) {
-    const reason = error62.code === "EADDRINUSE" ? `port ${cli.port} is already in use (another polypad-mcp running?). Start with --port <other>.` : error62.message;
-    mcp.bridge.unavailable = `Polypad's local bridge could not start: ${reason} Tell the user; Polypad cannot be reached until it runs.`;
-    err(`Could not open the bridge: ${reason}`);
+    mcp.bridge.unavailable = `Polypad's local bridge could not start: ${error62.message} Tell the user; Polypad cannot be reached until it runs.`;
+    err(`Could not open the bridge: ${error62.message}`);
   }
   const shutdown = () => {
     void mcp.close().finally(() => process.exit(0));
@@ -35143,6 +35521,7 @@ ${USAGE}`);
   process.on("SIGTERM", shutdown);
   process.stdin.on("end", shutdown);
   process.stdin.on("close", shutdown);
+  process.on("exit", () => mcp.bridge.releaseSync());
   await mcp.server.connect(new StdioServerTransport());
 }
 main().catch((error62) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polypad/mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "MCP server that lets Claude, Cursor or another AI assistant build and inspect 3D models in your open Polypad tab (polypad.ink). Runs locally, nothing is uploaded.",
   "license": "MIT",