js-bridge-mcp 0.1.9 → 0.2.0

package/README.md

@@ -71,6 +71,127 @@ repeated `get_embed_snippet` calls within the same session return the same
 tenant id — the page stays connected to whichever session generated the
 snippet it's using.
 
+## Auto-connect on page load (no DevTools paste)
+
+The manual paste above is the right default for a one-off static page, but a
+real app with its own build (Vite/webpack/etc) that wants to stay connected
+across every reload doesn't need a human to paste anything, ever. Instead of
+a session-minted tenant UUID, the app connects itself on boot using a fixed,
+human-readable **channel** name — `js-bridge-mcp`'s channel support
+(`mcp-tenant-lib` 0.3.3+) treats a channel name as the same string-keyed
+tenant id `main.js` already accepts via its `tenant` query param, so any MCP
+client can attach to the exact same live connection later via
+`join_channel("<channel-name>")`, with zero interaction on the page side.
+
+There's also a packaged skill for this exact recipe:
+`.agents/skills/js-bridge-mcp-auto-connect-button/SKILL.md` — load it before
+implementing so you don't reinvent the wiring below from scratch.
+
+**Requires `window.__mcpTools` to already be defined by the page** (see
+above) — this only handles the *connection*, not the tool contract.
+
+The connect lifecycle itself (probe, connect, rename, leave-old-channel-on-
+switch) is shared infrastructure, served by this package the same way
+`tool-bus.js` is: `src/client/connect.js`, importable by URL at
+`<server>/connect.js`, exporting one factory:
+
+```js
+import { createMcpConnect } from 'http://localhost:8766/connect.js';
+
+const connect = createMcpConnect({ appName: 'myapp' }); // localStorage key + default channel + tool-name label
+connect.init();                                          // connects on page load
+connect.handleConnectClick();                             // wire to a toolbar button
+connect.onConnectionStateChange((state, channel, appLabel) => { /* render a status indicator */ });
+connect.getConnectionState();                              // { state, channel, appLabel } - synchronous
+```
+
+`createMcpConnect` also accepts `defaultChannel` (defaults to `appName`) and
+`beforeConnect` (an optional async hook run once, before the first
+`main.js` import — for a host page that layers extra tool providers onto
+`window.__mcpTools` first, e.g. via `tool-bus.js`; see bulletino-1's
+`mcp-connect.mjs` for a worked example).
+
+If the host page's bundler doesn't support top-level await at its configured
+build target (common with Vite's default target), `connect.js` still has to
+be reached via a dynamic `import()` rather than a static one — wrap it in a
+small synchronous stub that starts `'disconnected'` and swaps in the real
+instance once the import resolves, so a UI component that reads
+`getConnectionState()` synchronously at its own module-eval time still
+works. See htmlpaint.com's or mindfoo's `mcp-connect.js`/`.ts` for the
+pattern (native ESM pages with no bundler, like bulletino-1's
+`mcp-connect.mjs`, can just top-level-`await` it directly).
+
+### Channel:app-name — joining a shared channel
+
+The prompt `handleConnectClick()` shows (and the one in this recipe's own
+UI wiring below) accepts either a bare channel name (`"bug123"`) or
+`"channel:app-name"` (`"bug123:htmlpaint"`) — the part after the colon sets
+`window.__mcpAppName` explicitly, independent of the channel itself. This is
+how several different apps deliberately join the **same** channel (like
+inviting several people into one Slack channel) while each keeps its own
+readable tool-name prefix instead of colliding on the channel name as its
+label: type `bug123:htmlpaint` in one tab and `bug123:bulletino` in another,
+and both land on tenant `bug123` with tools prefixed `htmlpaint__...` /
+`bulletino__...` — see "Multiple tabs on one tenant" below for how that
+prefixing works. Omitting `:app-name` keeps the app's own default label.
+
+### Orphaned channels get cleaned up automatically
+
+Two independent mechanisms, so switching channels (or just closing a tab)
+doesn't leave a dead tenant sitting around for the 2-hour general idle sweep
+to eventually notice:
+
+- **Explicit switch**: when `connect.js` reconnects a tab from channel A to
+  channel B (via `handleConnectClick` or a fresh `init()`), it sends a
+  `leave_channel` message on A's socket before opening the new one on B. The
+  server drops A's tenant immediately if that was its last connection — a
+  no-op if other tabs/apps are still on A.
+- **Tab closed / crashed**: the server can't distinguish a genuine tab close
+  from a brief network drop — both look like the same WebSocket `close`
+  event. So instead it tracks how long a tenant has had *zero* connections
+  and disposes it once that exceeds `TENANT_EMPTY_TIMEOUT_MS` (default
+  15s, separate from and much shorter than `TENANT_IDLE_TIMEOUT_MS`'s 2-hour
+  default) — comfortably above the client's ~2s reconnect retry, so a reload
+  or brief blip never trips it, but an actually-closed tab is gone within
+  seconds rather than hours.
+
+Add a thin connector module, e.g. `src/mcp-connect.ts`, wrapping the shared
+factory shown above:
+
+```ts
+import { createMcpConnect } from 'http://localhost:8766/connect.js';
+
+export const connect = createMcpConnect({ appName: 'myapp' });
+```
+
+(If your bundler can't top-level-`await` a dynamic import at its configured
+build target, wrap this in the synchronous-stub pattern described above
+instead of a bare re-export — see htmlpaint.com's/mindfoo's `mcp-connect`
+files for the full worked version.)
+
+Wire it into the app's entry point, **after** `window.__mcpTools` is set:
+
+```ts
+import './mcpbridge'; // sets window.__mcpTools
+import { connect } from './mcp-connect';
+
+connect.init(); // no dev-mode gate - JSBRIDGE_HOST is always localhost
+```
+
+And a status button somewhere in the toolbar, bound to
+`connect.onConnectionStateChange` and `connect.handleConnectClick`:
+
+```
+⚪ myapp        -- disconnected, click to connect
+🟡 connecting…  -- probing/importing
+🟢 myapp        -- connected on channel "myapp", click to rename (or "channel:app-name" to join a shared channel)
+```
+
+Any MCP client can now reach this page's tools without ever touching
+DevTools: `join_channel("myapp")`, then call tools by name (or their
+prefixed form if more than one connection shares the channel — see
+"Multiple tabs on one tenant" below).
+
 ## Bridge any other project's static HTML to this MCP server
 
 `js-bridge-mcp` doesn't care what the page is — `legacy-page/hello-world.html`

package/dist/client/connect.js

@@ -0,0 +1,230 @@
+// Shared connect-lifecycle module for any page auto-connecting to a locally
+// running js-bridge-mcp server via a named CHANNEL (not a session-minted
+// tenant UUID) - see packages/js-bridge-mcp/README.md's "Auto-connect on
+// page load" section for the full design rationale.
+//
+// This used to be copy-pasted per host app (mindfoo/src/mcp-connect.ts,
+// bulletino-1/mcp-connect.mjs, htmlpaint.com/src/mcp-connect.js - all three
+// nearly byte-identical). Hoisted here, alongside tool-bus.js, as another
+// hand-written vanilla ES module any host page can import by URL:
+//   <script type="module" src="http://<js-bridge-mcp host>/connect.js"></script>
+// Deliberately NOT part of main.ts's build (see vite.config.ts's
+// copy-client-extras plugin), same reasoning as tool-bus.js: this is
+// infrastructure shared across host apps/origins, not app-specific code
+// bundled with the bridge itself.
+//
+// Usage from a host app's own thin per-app module:
+//
+//   import { createMcpConnect } from 'http://localhost:8766/connect.js';
+//   export const mcpConnect = createMcpConnect({ appName: 'htmlpaint' });
+//   mcpConnect.init();
+//
+// Channel identity: js-bridge-mcp's channel support (mcp-tenant-lib 0.3.3+)
+// makes a channel name the same string-keyed tenant id main.js accepts via
+// the `tenant` query param - so a host app can connect with a fixed,
+// human-readable name with zero interaction, and any MCP client can attach
+// to the exact same live connection via join_channel("<name>").
+//
+// Channel:app-name syntax: a chosen channel may be typed as "channel:app" -
+// e.g. "bug123:htmlpaint" - to explicitly set BOTH the shared channel
+// (join_channel target) and this connection's own app label/tool-name
+// prefix in one prompt, letting several different apps deliberately join
+// the same channel (like inviting several people into one Slack channel)
+// while each still gets a distinct, readable tool prefix instead of
+// colliding on "channel" as its own label. Omitting the ":app" part keeps
+// the app's own default label.
+
+// js-bridge-mcp has no production deployment - it only ever runs locally,
+// launched via `npx` (see packages/js-bridge-mcp), so this always targets
+// localhost regardless of where the host app is served from.
+const JSBRIDGE_HOST = 'http://localhost:8766';
+
+// Must match js-bridge-mcp's own isValidChannelName (mcp-tenant-lib/src/tenant.ts)
+// exactly - channel names become the WS `?tenant=` query param, and the
+// server rejects anything outside this set with a 4404 close before a
+// Tenant is ever created.
+const VALID_CHANNEL_NAME = /^[a-zA-Z0-9_-]+$/;
+
+function sanitizeToValidChannelName(raw) {
+  return raw.replace(/[^a-zA-Z0-9_-]+/g, '-');
+}
+
+/**
+ * Splits a user-typed "channel" or "channel:app" string into its parts.
+ * A bare name (no colon) is just the channel, with no app-label override.
+ */
+function parseChannelInput(input) {
+  const idx = input.indexOf(':');
+  if (idx === -1) return { channel: input, appLabel: undefined };
+  const channel = input.slice(0, idx).trim();
+  const appLabel = input.slice(idx + 1).trim();
+  return { channel, appLabel: appLabel || undefined };
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.appName - Short app-specific identifier, e.g.
+ *   "htmlpaint", "bulletino", "mindfoo". Used as: the localStorage key
+ *   namespace, the default channel name, and (unless a "channel:app" prompt
+ *   input overrides it) the connection's window.__mcpAppName label.
+ * @param {string} [opts.defaultChannel] - Defaults to opts.appName.
+ * @param {(state: 'disconnected'|'connecting'|'connected', channel: string, appLabel: string) => void} [opts.onStateChange]
+ *   Optional convenience callback, called on every state transition - an
+ *   alternative to onConnectionStateChange() below for a caller that just
+ *   wants one function rather than subscribing.
+ * @param {() => Promise<void>|void} [opts.beforeConnect]
+ *   Optional hook run once, before the very first main.js import - for a
+ *   host page that layers extra tool providers onto window.__mcpTools ahead
+ *   of connecting (e.g. bulletino-1 loading tool-bus.js + folderfoo's
+ *   provider). Not re-run on a later channel switch/rename - main.js reads
+ *   window.__mcpTools fresh on every import, so whatever this hook set up
+ *   the first time is still in place for subsequent connects.
+ */
+export function createMcpConnect(opts) {
+  const appName = opts.appName;
+  const defaultChannel = opts.defaultChannel ?? appName;
+  const CHANNEL_STORAGE_KEY = `${appName}_mcp_channel`;
+  const APP_LABEL_STORAGE_KEY = `${appName}_mcp_app_label`;
+
+  function getStored(key, fallback) {
+    try {
+      return localStorage.getItem(key) || fallback;
+    } catch {
+      return fallback;
+    }
+  }
+
+  function setStored(key, value) {
+    try {
+      localStorage.setItem(key, value);
+    } catch {
+      // ignore - falls back to the default next load
+    }
+  }
+
+  let state = 'disconnected'; // 'disconnected' | 'connecting' | 'connected'
+  let currentChannel = getStored(CHANNEL_STORAGE_KEY, defaultChannel);
+  let currentAppLabel = getStored(APP_LABEL_STORAGE_KEY, appName);
+  // The live socket's own leave() - set each time connectToChannel opens a
+  // new one, so a later switch can tell the OLD socket to leave_channel
+  // before this module opens the new one. undefined until the first
+  // successful import() below.
+  let leaveCurrentSocket;
+  let beforeConnectRan = false;
+  const stateListeners = new Set();
+
+  function setState(next) {
+    state = next;
+    for (const cb of stateListeners) cb(state, currentChannel, currentAppLabel);
+    opts.onStateChange?.(state, currentChannel, currentAppLabel);
+  }
+
+  // Lightweight reachability probe via plain HTTP - main.js's own
+  // connectStateSocket doesn't expose connect/disconnect events to the
+  // importer, so this is the only way to know "is js-bridge-mcp up" before
+  // (and independent of) actually importing main.js.
+  async function probeJsBridgeMcp() {
+    try {
+      const res = await fetch(`${JSBRIDGE_HOST}/main.js`, { method: 'HEAD' });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  async function connectToChannel(channelName, appLabel) {
+    // Tell whichever channel we were previously on that we're leaving it
+    // BEFORE opening the new socket, so the server can drop that tenant the
+    // moment it's empty rather than only after this tab's old socket times
+    // out - see leave_channel's own doc comment in mcp-tenant-lib/types.ts.
+    // Safe to call unconditionally: a no-op if there's no prior socket, or
+    // if other connections remain on that channel.
+    leaveCurrentSocket?.();
+    leaveCurrentSocket = undefined;
+
+    setState('connecting');
+    currentChannel = channelName;
+    currentAppLabel = appLabel ?? appName;
+    window.__mcpAppName = currentAppLabel;
+    setStored(CHANNEL_STORAGE_KEY, currentChannel);
+    setStored(APP_LABEL_STORAGE_KEY, currentAppLabel);
+
+    const reachable = await probeJsBridgeMcp();
+    if (!reachable) {
+      setState('disconnected');
+      return;
+    }
+
+    if (!beforeConnectRan) {
+      beforeConnectRan = true;
+      await opts.beforeConnect?.();
+    }
+
+    // A fresh import (unique URL per channel/tenant, since main.js reads
+    // `tenant` once at module-eval time and exposes no way to retarget an
+    // existing connection) - main.js has no export, so this is fire-and-
+    // forget; connect/disconnect status past this point is inferred from
+    // the probe above plus the module having loaded without throwing.
+    try {
+      const mod = await import(
+        /* @vite-ignore */ `${JSBRIDGE_HOST}/main.js?server=${encodeURIComponent(JSBRIDGE_HOST)}&tenant=${encodeURIComponent(channelName)}&_=${Date.now()}`
+      );
+      // main.js exposes __mcpLeaveChannel (see main.ts) as a best-effort
+      // hook for exactly this - a module-scoped function, not a return
+      // value, since main.js has no exports of its own (see its own
+      // comment) and is imported purely for its side effects.
+      leaveCurrentSocket = typeof window.__mcpLeaveChannel === 'function' ? window.__mcpLeaveChannel : undefined;
+      setState('connected');
+    } catch {
+      setState('disconnected');
+    }
+  }
+
+  /**
+   * Click behavior: connect (or reconnect) if not connected; if already
+   * connected, prompt to rename - so a user with multiple tabs open can
+   * name each one on purpose instead of ending up with an unlabeled
+   * auto-suffixed channel they can't identify later. Accepts a bare channel
+   * name ("bug123") or "channel:app-name" ("bug123:htmlpaint") to join a
+   * shared channel under an explicit app label distinct from the channel
+   * name itself - lets several different apps deliberately land on the same
+   * channel (like inviting several people into one Slack channel) while
+   * keeping each one's tools under its own readable prefix.
+   */
+  async function handleConnectClick() {
+    const promptCurrent = currentAppLabel === appName ? currentChannel : `${currentChannel}:${currentAppLabel}`;
+    if (state === 'connected') {
+      let next = prompt('Name this connection (channel, or channel:app-name to share a channel):', promptCurrent);
+      if (!next || next === promptCurrent) return;
+      let parsed = parseChannelInput(next);
+      while (parsed.channel && !VALID_CHANNEL_NAME.test(parsed.channel)) {
+        next = prompt(
+          `"${parsed.channel}" isn't a valid channel name - only letters, digits, underscore, and hyphen are allowed (no spaces). Try again:`,
+          `${sanitizeToValidChannelName(parsed.channel)}${parsed.appLabel ? `:${parsed.appLabel}` : ''}`
+        );
+        if (!next) return;
+        parsed = parseChannelInput(next);
+      }
+      if (!parsed.channel) return;
+      await connectToChannel(parsed.channel, parsed.appLabel);
+      return;
+    }
+    await connectToChannel(currentChannel, currentAppLabel);
+  }
+
+  /** Connects automatically on page load - no button click required. */
+  async function init() {
+    await connectToChannel(currentChannel, currentAppLabel);
+  }
+
+  function onConnectionStateChange(cb) {
+    stateListeners.add(cb);
+    return () => stateListeners.delete(cb);
+  }
+
+  function getConnectionState() {
+    return { state, channel: currentChannel, appLabel: currentAppLabel };
+  }
+
+  return { init, handleConnectClick, onConnectionStateChange, getConnectionState };
+}

package/dist/client/main.js

@@ -1,19 +1,19 @@
 function _(e) {
-  const n = [], o = /* @__PURE__ */ new Map();
+  const t = [], o = /* @__PURE__ */ new Map();
   for (const { fn: c, ...s } of e)
-    n.push(s), o.set(s.name, c);
-  return { manifest: n, fnByName: o };
+    t.push(s), o.set(s.name, c);
+  return { manifest: t, fnByName: o };
 }
 const w = 1e4, f = 3600 * 1e3;
-function $(e, n = {}) {
+function h(e, t = {}) {
   let o, c = !1, s = 0, p;
   const m = () => {
-    const a = n.tenant ?? (location.pathname.startsWith("/t/") ? location.pathname.slice(3).split("/")[0] : ""), y = a ? `/ws?tenant=${encodeURIComponent(a)}` : "/ws", d = `${n.serverUrl ? n.serverUrl.replace(/^http/, "ws") : `${location.protocol === "https:" ? "wss:" : "ws:"}//${location.host}`}${y}`;
+    const l = t.tenant ?? (location.pathname.startsWith("/t/") ? location.pathname.slice(3).split("/")[0] : ""), y = l ? `/ws?tenant=${encodeURIComponent(l)}` : "/ws", d = `${t.serverUrl ? t.serverUrl.replace(/^http/, "ws") : `${location.protocol === "https:" ? "wss:" : "ws:"}//${location.host}`}${y}`;
     console.log(`[mcp-ws] connecting (attempt ${s + 1}): ${d}`), o = new WebSocket(d), o.onopen = () => {
       console.log(`[mcp-ws] connected${s > 0 ? ` after ${s} reconnect attempt(s)` : ""}`), s = 0, p = void 0, e.onConnect?.();
-    }, o.onclose = (r) => {
-      if (console.log(`[mcp-ws] disconnected: code=${r.code} reason=${r.reason || "(none)"} wasClean=${r.wasClean}`), e.onDisconnect?.(), !c) {
-        if (r.code === 4404) {
+    }, o.onclose = (a) => {
+      if (console.log(`[mcp-ws] disconnected: code=${a.code} reason=${a.reason || "(none)"} wasClean=${a.wasClean}`), e.onDisconnect?.(), !c) {
+        if (a.code === 4404) {
           console.log("[mcp-ws] invalid tenant id (4404) — not retrying");
           return;
         }
@@ -25,41 +25,41 @@ function $(e, n = {}) {
       }
     }, o.onerror = () => {
       console.log("[mcp-ws] socket error (see close event for details)");
-    }, o.onmessage = (r) => {
-      const t = JSON.parse(r.data);
-      t.type === "init" && e.onInit?.(t.schema, t.state), t.type === "reinit" && e.onReinit?.(t.schema, t.state), t.type === "update" && e.onUpdate?.(t.field, t.value), t.type === "call" && e.onCall?.(t.id, t.name, t.args), t.type === "identify" && (e.onIdentify ? e.onIdentify(t.label) : alert(`Identify: this is the "${t.label ?? "unlabeled"}" connection`));
+    }, o.onmessage = (a) => {
+      const n = JSON.parse(a.data);
+      n.type === "init" && e.onInit?.(n.schema, n.state), n.type === "reinit" && e.onReinit?.(n.schema, n.state), n.type === "update" && e.onUpdate?.(n.field, n.value), n.type === "call" && e.onCall?.(n.id, n.name, n.args), n.type === "identify" && (e.onIdentify ? e.onIdentify(n.label) : alert(`Identify: this is the "${n.label ?? "unlabeled"}" connection`));
     };
   };
   return m(), {
-    send(a) {
-      o?.send(JSON.stringify(a));
+    send(l) {
+      o?.send(JSON.stringify(l));
     },
     close() {
       c = !0, o?.close();
     }
   };
 }
-const h = window.__mcpTools ?? [], { manifest: b, fnByName: C } = _(h), N = window.__mcpSummary ?? void 0, v = typeof window.__mcpAppName == "string" && window.__mcpAppName;
+const $ = window.__mcpTools ?? [], { manifest: C, fnByName: b } = _($), v = window.__mcpSummary ?? void 0, N = typeof window.__mcpAppName == "string" && window.__mcpAppName;
 let i = window.__mcpAppName ?? document.title ?? void 0, g = !1;
 function S() {
-  if (g || (g = !0, v)) return i;
+  if (g || (g = !0, N)) return i;
   const e = prompt("Name this MCP connection (used to identify it to the agent):", i ?? "");
   return e && (i = e), i;
 }
-const u = new URL(import.meta.url), R = u.searchParams.get("server") ?? void 0, U = u.searchParams.get("tenant") ?? void 0, l = $(
+const u = new URL(import.meta.url), R = u.searchParams.get("server") ?? void 0, U = u.searchParams.get("tenant") ?? void 0, r = h(
   {
     onConnect() {
       const e = S();
-      console.log(`[js-bridge-mcp] connected as "${e ?? "(unlabeled)"}"`), l.send({ type: "register_tools", tools: b, summary: N, appLabel: e });
+      console.log(`[js-bridge-mcp] connected as "${e ?? "(unlabeled)"}"`), r.send({ type: "register_tools", tools: C, summary: v, appLabel: e });
     },
-    async onCall(e, n, o) {
+    async onCall(e, t, o) {
       try {
-        const c = C.get(n);
-        if (!c) throw new Error(`no page tool named "${n}" — was it in window.__mcpTools when this script loaded?`);
+        const c = b.get(t);
+        if (!c) throw new Error(`no page tool named "${t}" — was it in window.__mcpTools when this script loaded?`);
         const s = await c(o);
-        l.send({ type: "call_result", id: e, result: s });
+        r.send({ type: "call_result", id: e, result: s });
       } catch (c) {
-        l.send({ type: "call_result", id: e, error: String(c.message) });
+        r.send({ type: "call_result", id: e, error: String(c.message) });
       }
     },
     onDisconnect() {
@@ -69,6 +69,9 @@ const u = new URL(import.meta.url), R = u.searchParams.get("server") ?? void 0,
   { serverUrl: R, tenant: U }
 );
 window.__mcpRename = (e) => {
-  const n = e ?? prompt("Rename this MCP connection:", i ?? "");
-  n && (i = n, l.send({ type: "rename_connection", appLabel: n }), console.log(`[js-bridge-mcp] renamed connection to "${n}"`));
+  const t = e ?? prompt("Rename this MCP connection:", i ?? "");
+  t && (i = t, r.send({ type: "rename_connection", appLabel: t }), console.log(`[js-bridge-mcp] renamed connection to "${t}"`));
+};
+window.__mcpLeaveChannel = () => {
+  r.send({ type: "leave_channel" });
 };

package/dist/src/server.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { getOrCreateTenant as getOrCreateTenantFor, tenants, startIdleSweep, createHttpServer, attachWebSocketServer } from 'mcp-tenant-lib';
+import { execSync } from 'node:child_process';
+import { getOrCreateTenant as getOrCreateTenantFor, tenants, startIdleSweep, startEmptySweep, createHttpServer, attachWebSocketServer } from 'mcp-tenant-lib';
 import { initialHelloState } from './types.js';
 import { registerHelloTools } from './tools/register.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -10,10 +11,42 @@ const packageRoot = __dirname.endsWith(`${path.sep}dist${path.sep}src`)
     ? path.join(__dirname, '..', '..')
     : path.join(__dirname, '..');
 const PORT = process.env.PORT ? Number(process.env.PORT) : 8766;
+// A stale js-bridge-mcp instance (e.g. left running from a previous editor
+// session/reload) is the overwhelmingly common occupant of this port, and
+// leaving it running would just make this new instance fail to bind. Free
+// the port unconditionally before listening, macOS/Linux only.
+function killWhateverIsOnPort(port) {
+    let pids;
+    try {
+        pids = execSync(`lsof -ti tcp:${port}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    }
+    catch {
+        return; // lsof exits non-zero when nothing is listening on the port
+    }
+    if (!pids)
+        return;
+    for (const pid of pids.split('\n')) {
+        if (pid === String(process.pid))
+            continue;
+        try {
+            process.kill(Number(pid), 'SIGKILL');
+            console.error(`[js-bridge-mcp] killed process ${pid} that was on port ${port}`);
+        }
+        catch {
+            // already gone
+        }
+    }
+}
+killWhateverIsOnPort(PORT);
 const getOrCreateTenant = (id) => getOrCreateTenantFor(id, undefined, { ...initialHelloState });
 // The 'default' tenant backs direct access with no explicit ?tenant= param.
 getOrCreateTenant('default');
 startIdleSweep((id) => console.error(`[mcp] sweeping idle tenant: ${id}`));
+// Separate, much shorter sweep for channels with zero live connections
+// (tab closed, or the page deliberately left via leave_channel when
+// switching channels) - see startEmptySweep's own doc comment for why this
+// is a distinct mechanism from the idle sweep above.
+startEmptySweep((id) => console.error(`[mcp] sweeping empty channel: ${id}`));
 // main.js is fetched from here by absolute path (get_embed_snippet always
 // embeds "<server>/main.js", see hello-tools.ts) regardless of what's
 // mounted at "/" — the legacy page it's injected into is hosted separately
@@ -30,7 +63,17 @@ const httpServer = createHttpServer({
     initialValues: initialHelloState,
     identity: { name: 'js-bridge-mcp', version: '0.1.0' },
     registerFn: registerHelloTools,
-    extraStaticMounts: { '/main.js': CLIENT_DIR },
+    // Each of these is a fixed-URL asset other pages import cross-origin by
+    // absolute path (main.js via get_embed_snippet; tool-bus.js/connect.js
+    // per their own header comments: shared infrastructure any host app
+    // imports directly, e.g. "<server>/connect.js") - single-file mounts, not
+    // a whole-directory one, so dist/client can't accidentally serve
+    // anything else placed there later.
+    extraStaticMounts: {
+        '/main.js': CLIENT_DIR,
+        '/tool-bus.js': CLIENT_DIR,
+        '/connect.js': CLIENT_DIR,
+    },
     // js-bridge-mcp typically bridges a single browser page per server; MCP
     // clients aren't expected to pin ?tenant= themselves (some, like VS Code
     // Copilot, open a fresh MCP session with no ?tenant= on every

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-bridge-mcp",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "type": "module",
   "description": "Generic bridge: exposes MCP tools discovered from a connected page's own JSON tool manifest, dispatched over a cross-origin WebSocket. Ships a hello-world example page under legacy-page/.",
   "repository": {
@@ -29,6 +29,7 @@
     "build": "tsc -p tsconfig.build.json && vite build && vite build --config vite.dashboard.config.ts",
     "prestart:mcp": "npm run build",
     "start:mcp": "tsx src/server.ts",
+    "start": "npm run start:mcp",
     "start:static": "http-server legacy-page --cors -p 8080",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc --noEmit -p tsconfig.server.json && tsc --noEmit -p tsconfig.client.json",
@@ -36,7 +37,7 @@
     "test": "node --import tsx --test test/**/*.test.ts"
   },
   "dependencies": {
-    "mcp-tenant-lib": "^0.3.3",
+    "mcp-tenant-lib": "^0.4.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "avosignals": "^1.0.16",
     "lit": "^3.3.3",