@polypad/mcp 0.1.0 → 0.1.2

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) {
@@ -34771,25 +34809,25 @@ var inputs = {
 };
 var descriptions = {
   new_project: "Start a new, empty Polypad project (optionally from a template), replacing the open one. All lengths in Polypad are millimetres and angles are degrees; Z is up.",
-  set_parameter: "Create or change a named parameter (a number or an expression). Any length field of any feature can use the name, so one change resizes everything bound to it. Reports features that no longer build.",
+  set_parameter: "Create or change a named parameter (a number or an expression). Any length field of any feature can use the name, so one change resizes everything bound to it. Reports features that no longer build. Set the sizes up front, then use the names in fields.",
   add_primitive: "Add a solid box, cylinder, sphere or cone as a new body. Returns the new feature's id, which is also the body id for later commands. Sizes in mm.",
   add_sketch: "Add a 2D sketch on a base plane or on a flat face and draw shapes in it (rectangle, circle, line, polyline, arc, slot, polygon). The sketch is solved and its remaining degrees of freedom reported. Use extrude or revolve to turn closed shapes into a solid.",
   extrude: "Extrude the closed shapes of a sketch into a solid: as a new body, or cut from / joined to an existing body. Returns the feature id (the new body's id when mode is new).",
-  revolve: "Revolve the closed shapes of a sketch about an axis in the sketch plane to make a solid of revolution: new body, or cut / join with an existing body.",
-  combine: "Boolean-combine bodies: union, subtract (remove the tools from the target) or intersect. The target keeps its id; the tools are consumed.",
-  hole: "Drill a screw hole (M2 to M10, with clearance, tap or heat-set insert fit and optional counterbore / countersink) into a flat face. Call list_faces first and pass the face index and its rebuildId.",
-  fillet: "Round the given edges of a body with a radius. Call list_edges first and pass the edge indices and their rebuildId.",
-  chamfer: "Bevel the given edges of a body. Call list_edges first and pass the edge indices and their rebuildId.",
-  shell: "Hollow out a body, leaving the given faces open, with walls of a given thickness. Call list_faces first and pass the face indices and their rebuildId.",
-  pattern: "Repeat a body in a row or grid, or around an axis, either fusing the copies into the body or making each copy a body of its own.",
-  mirror: "Mirror a whole body across a plane (yz, xz or xy, optionally moved along its normal), joining the copy into the body or making it a separate body.",
+  revolve: "Revolve the closed shapes of a sketch about an axis in the sketch plane to make a solid of revolution: new body, or cut / join with an existing body. Use it for round parts: draw half the outline beside the axis.",
+  combine: "Boolean-combine bodies: union, subtract (remove the tools from the target) or intersect. The target keeps its id; the tools are consumed. To hollow a body use shell, not a subtracted box; to check a collision, intersect two bodies, measure the result, then undo.",
+  hole: "Drill a screw hole (M2 to M10, with clearance, tap or heat-set insert fit and optional counterbore / countersink) into a flat face. Call list_faces first and pass the face index and its rebuildId. Use this for every screw, standoff or insert hole instead of cutting circles.",
+  fillet: "Round the given edges of a body with a radius. Call list_edges first (narrow it with its filter) and pass the edge indices and their rebuildId. If it fails, try a smaller radius or fewer edges.",
+  chamfer: "Bevel the given edges of a body. Call list_edges first (narrow it with its filter) and pass the edge indices and their rebuildId. If it fails, try a smaller distance or fewer edges.",
+  shell: "Hollow out a body, leaving the given faces open, with walls of a given thickness. Call list_faces first and pass the face indices and their rebuildId. Use this for enclosures and cups instead of subtracting a smaller box; list_faces with filter normal finds the face to open.",
+  pattern: "Repeat a body in a row or grid, or around an axis, either fusing the copies into the body or making each copy a body of its own. Model one copy (or one cutter) and pattern it instead of adding copies by hand.",
+  mirror: "Mirror a whole body across a plane (yz, xz or xy, optionally moved along its normal), joining the copy into the body or making it a separate body. Model one side of a symmetric part, then mirror it.",
   move: "Move, rotate and/or scale a whole body (translate in mm, rotate in degrees about X, Y, Z around a pivot).",
-  update_feature: "Change fields of an existing feature (for example an extrude's distance or a box's width); everything after it rebuilds. The change is refused, and the project left as it was, if the result is not a valid model.",
+  update_feature: "Change fields of an existing feature (for example an extrude's distance or a box's width); everything after it rebuilds. The change is refused, and the project left as it was, if the result is not a valid model. Prefer this over deleting and rebuilding a feature.",
   delete_feature: "Delete a feature. Refused while other features still use it; delete those first.",
   undo: "Undo the last change made to the project. Can be repeated.",
   get_project: "Describe the whole project: parameters, every feature in order (id, name, type, main values, whether it built or the error), and every body (volume, area, bounding box). Start here, and call it again after changes to check the result.",
-  list_faces: "List the faces of a body: index, flat or curved, normal, centre, area, and for flat faces the sketch frame (origin, x and y axes) with the face's bounds in it. The indices go into hole, shell and add_sketch (face). Returns a rebuildId those commands require.",
-  list_edges: "List the edges of a body: index, convex / concave / smooth, length, straight or curved, direction, midpoint, and the faces they border. The indices go into fillet and chamfer. Returns a rebuildId those commands require.",
+  list_faces: "List the faces of a body: index, flat or curved, normal, centre, area, and for flat faces the sketch frame (origin, x and y axes) with the face's bounds in it. The indices go into hole, shell and add_sketch (face). Returns a rebuildId those commands require. A body can have hundreds of faces: use the filter (normal, kind).",
+  list_edges: "List the edges of a body: index, convex / concave / smooth, length, straight or curved, direction, midpoint, and the faces they border. The indices go into fillet and chamfer. Returns a rebuildId those commands require. A body can have hundreds of edges: use the filter (face, direction, kind).",
   measure: "Measure bodies: volume (mm3), surface area (mm2), bounding box (mm) and its centre.",
   render_view: "Render the model to a PNG image from a standard view, to look at the result. Needs the Polypad browser tab."
 };
@@ -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");
@@ -35070,12 +35451,23 @@ var SERVER_INSTRUCTIONS = `Polypad is a parametric CAD editor. These tools build
 Units and axes: lengths are millimetres, angles degrees, Z is up. Any length field accepts a number or an expression over the project's parameters ("width / 2"); prefer set_parameter for sizes that belong together.
 
 Workflow:
-1. Start with get_project to see what is already there (the user may have work open). new_project replaces the open project, so use it only when asked or when the project is empty.
+1. Start with get_project to see what is already there (the user may have work open). new_project replaces the open project: if it has features, ask the user first and never call it over their work; use it freely only when the project is empty.
 2. Build with add_primitive, or add_sketch then extrude / revolve. Ids returned by a command are the feature and body ids for later calls.
 3. For hole, shell, fillet, chamfer and for sketching on a face, call list_faces or list_edges first. Pass the indices they return together with the same rebuildId. The rebuildId changes whenever the model changes, so after any change list again; a stale one is refused ("Call list_edges again").
 4. A feature that does not build stays in the project with its error: fix it with update_feature, or remove it with delete_feature or undo.
 5. Check your work: measure gives volume and bounding box, and render_view returns a PNG (iso, top, front, right) so you can look at the result. Compare the numbers with what was asked before you finish.
 
+Pick the tool by task:
+- Hollow part (enclosure, box, cup): shell the solid with the open face(s) removed (list_faces with filter normal "+z" finds the top); don't subtract a smaller box.
+- Screw holes, standoffs, inserts: hole (size, fit close/normal/loose/tap/insert, counterbore or countersink, blind depth), not cut circles.
+- Repeated parts (rows, grids, around a circle, lattices): model one body, or one cutter body, then pattern it (then combine subtract for a cutter). Symmetric parts: model one side, then mirror.
+- Round parts (knobs, turrets, finials, domes): add_sketch on XZ (sketch x = world X, sketch y = world Z), draw half the outline at x >= 0, then revolve with axis "y" (the world Z axis).
+- Sizes that belong together or may change: set_parameter first, then use the names in fields.
+- Changing or fixing a feature: update_feature (or undo the last step); don't delete and rebuild.
+- Picking edges: use the list_edges filter (face, direction, kind) and the list_faces filter (normal, kind) instead of reading every edge. For the rim of the top: list_faces normal "+z", then list_edges face <index>.
+- Fillet fails: try a smaller radius or fewer edges at once, or use chamfer.
+- Clearances and collisions: measure gives bounding boxes; combine intersect on two bodies, then measure, shows an overlap; then undo.
+
 Results: a result with isError set was refused or something in the model did not build; the text says what and how to fix it. Nothing is changed by a refused call.`;
 function toToolResult(result) {
   const content = [{ type: "text", text: result.text }];
@@ -35104,7 +35496,7 @@ function createPolypadMcp(options = {}) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.1.0" : "0.0.0-dev";
+var VERSION = true ? "0.1.2" : "0.0.0-dev";
 var err = (line2) => process.stderr.write(`${line2}
 `);
 async function main() {
@@ -35129,12 +35521,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 +35532,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.2",
   "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",