js-bridge-mcp 0.1.0

package/README.md

@@ -0,0 +1,362 @@
+# js-bridge-mcp
+
+A generic bridge: MCP tools are discovered at runtime from a connected
+page's own JSON tool manifest, and dispatched to that page's `window.*`
+functions over a cross-origin WebSocket. This package ships a worked
+"hello world" example of `@avo-mcp-tools/mcp-tenant-lib`'s
+**Pattern B**: AI-enabling an existing static page that this stack
+doesn't own or build.
+
+Two independent servers, two independent origins:
+
+- **`js-bridge-mcp`'s own server** — MCP endpoint (`/mcp`) + WebSocket
+  bridge (`/ws`) + one static asset (`/main.js`), on port 8766.
+- **`legacy-page/hello-world.html`** — a plain HTML page with an `<h1>`
+  and a `<main>`, no build step, no dependency on this stack. Served by
+  any static file server — this example uses `http-server --cors` on
+  port 8080.
+
+The page and the MCP server never talk to each other directly. The
+*browser* bridges them: a one-line executable JS snippet (generated by the
+`get_embed_snippet` tool) connects straight to `js-bridge-mcp`'s WebSocket,
+cross-origin. The primary way to run it is pasting it directly into the
+target page's DevTools console — no editing the page's source required,
+which is the expected workflow for a developer today. It can also be
+wrapped in a `<script type="module">...</script>` tag and baked into the
+page's HTML if preferred. Once connected, the page pushes its own
+`#mcp-tools` JSON manifest over that socket, and the server registers the
+tools it describes — see `packages/mcp-tenant-lib/BRIDGING.md` for how
+to write one for a new page.
+
+## Run it
+
+```bash
+npm run build        # bundle src/client/main.ts -> dist/client/main.js
+npm run start:mcp     # MCP + WS + main.js server, port 8766
+npm run start:static  # serves legacy-page/, port 8080, in a second terminal
+```
+
+Open `http://localhost:8080/hello-world.html` — it renders as-is, not yet
+connected to anything.
+
+## Connect an agent
+
+1. Point an MCP client at `http://localhost:8766/mcp`.
+2. Call `get_embed_snippet`. It returns something like:
+   ```js
+   import("http://localhost:8766/main.js?server=http%3A%2F%2Flocalhost%3A8766&tenant=<uuid>");
+   ```
+3. Open `legacy-page/hello-world.html` in a browser, open DevTools, go to
+   the Console tab, paste that line, and press enter. (Alternatively, wrap
+   it in a `<script type="module">...</script>` tag and paste it into the
+   page's HTML before `</body>` — there's a comment marking the spot — then
+   reload.)
+4. Call `insert_title` / `insert_main` from the MCP client — the open tab
+   updates live, no page refresh needed.
+
+The tenant id embedded in the snippet is this MCP session's own tenant, so
+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.
+
+## 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`
+is just a worked example. Any static HTML page (in this repo or a totally
+unrelated project) can become a tenant of an already-running `js-bridge-mcp`
+server by adding two things to its own source, with zero build-step
+dependency on this package. This section is the complete recipe — no need to
+go spelunking in other packages' docs.
+
+### 1. Define `window.__mcpTools` in the page, before the bridge script runs
+
+A global array of tool definitions, each holding a **real function
+reference** (not a string name):
+
+```html
+<script>
+  function highlightRow({ rowId, color }) {
+    const row = document.getElementById(rowId);
+    if (!row) throw new Error(`no row with id "${rowId}"`);
+    row.style.backgroundColor = color ?? 'yellow';
+    return `highlighted ${rowId}`;
+  }
+
+  window.__mcpTools = [
+    {
+      name: 'highlight_row',
+      description: 'Highlights the table row matching the given id. Call list_rows first if you don\'t know valid ids.',
+      params: {
+        rowId: { type: 'string', description: 'The id attribute of the <tr> to highlight' },
+        color: { type: 'string', description: 'CSS color name, defaults to yellow if omitted', optional: true },
+      },
+      example: { rowId: 'row-42', color: 'yellow' },
+      fn: highlightRow,
+    },
+  ];
+</script>
+```
+
+Schema per entry:
+
+- **`name`** — snake_case, unique on the page. What the MCP-connected agent
+  sees and calls.
+- **`description`** — written for the *agent*, not a human reader: state what
+  it does, preconditions ("call X first"), and side effects. See
+  `get_embed_snippet`'s description in `src/tools/hello-tools.ts` for the bar
+  to hit.
+- **`params`** — flat object only, values are `{ type, description?, optional? }`
+  with `type` one of `"string"` / `"number"` / `"boolean"`. No nested objects
+  or arrays — the server's JSON→zod converter only supports these three
+  primitives and throws a registration error otherwise. Need structured data?
+  Encode it as a JSON string param and `JSON.parse` inside `fn`.
+- **`example`** — a realistic call, useful both as page-source documentation
+  and as something you should actually try once connected.
+- **`fn`** — called with a single args object matching `params` (never
+  positional args). Its return value, or a thrown `Error`'s message, becomes
+  the tool call's result. `fn` never leaves the browser — the bridge strips
+  it before talking to the server, which only ever sees
+  `name`/`description`/`params`/`example` and dispatches calls back by
+  `name` against its local copy of `window.__mcpTools`.
+
+Optionally also set `window.__mcpAppName` (a short string, e.g. `"formalin"`
+or `"htmlpaint"`) before the embed snippet runs. It identifies this page/app
+when the *same* `get_embed_snippet` output gets pasted into more than one
+browser tab — see "Multiple tabs on one tenant" below. Falls back to
+`document.title` if omitted, and has no effect at all with a single
+connection.
+
+If the page is an ES module build rather than plain script tags, define
+`window.__mcpTools` in whichever module already has the real functions in
+scope — same shape, still a direct function reference, no string lookup.
+
+### 2. Add the embed snippet, after `window.__mcpTools` is defined
+
+Get it by calling this server's `get_embed_snippet` MCP tool (from any MCP
+client pointed at `http://localhost:8766/mcp`); it returns one line like:
+
+```js
+import("http://localhost:8766/main.js?server=http%3A%2F%2Flocalhost%3A8766&tenant=<uuid>");
+```
+
+Two ways to run it, both fine:
+
+- **Paste into DevTools console** on the already-open target page — no
+  source edit at all. This is the default workflow when you (or the agent)
+  have the page open in a browser you control.
+- **Bake into the page's HTML**, wrapped in a module script tag, placed
+  *after* the `window.__mcpTools` block:
+  ```html
+  <script type="module">import("http://localhost:8766/main.js?server=...&tenant=...");</script>
+  ```
+
+Either way, the bridge reads `window.__mcpTools` **once**, synchronously, at
+load/(re)connect time — it does not poll. Edit the tool list, then reload the
+page (and let the bridge reconnect) before the new tools show up.
+
+### Full example: a bare page, wired up end-to-end
+
+This is `legacy-page/hello-world.html` in full — copy it as a starting point
+for any project's own static page. The only things that change per-project
+are the functions and tool definitions inside the `<script>` block; the
+embed-snippet line at the bottom is generated fresh per tenant by
+`get_embed_snippet` and pasted in (or run from DevTools instead of baked in).
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>Hello World</title>
+</head>
+<body>
+  <h1>Hello, world!</h1>
+  <main>Waiting for an agent to say something...</main>
+
+  <script>
+    function insertTitle({ title }) {
+      document.title = title;
+      document.querySelector('h1').textContent = title;
+      return `title set to "${title}"`;
+    }
+
+    function insertMain({ main }) {
+      document.querySelector('main').textContent = main;
+      return 'main content updated';
+    }
+
+    // window.__mcpTools is the contract the injected bridge script looks
+    // for: an array of { name, description, params, example, fn } — real
+    // function references, not string lookups. Must be defined before the
+    // embed snippet below runs.
+    window.__mcpTools = [
+      {
+        name: 'insert_title',
+        description: 'Sets the <h1> title shown on this page.',
+        params: { title: { type: 'string', description: 'New page title' } },
+        example: { title: 'Welcome, Ada!' },
+        fn: insertTitle,
+      },
+      {
+        name: 'insert_main',
+        description: 'Sets the <main> body content shown on this page.',
+        params: { main: { type: 'string', description: 'New body text' } },
+        example: { main: 'Here is your daily summary...' },
+        fn: insertMain,
+      },
+    ];
+  </script>
+
+  <!-- Paste the snippet from get_embed_snippet here, wrapped in a
+       <script type="module"> tag — or just run it from DevTools instead. -->
+  <script type="module">import("http://localhost:8766/main.js?server=http%3A%2F%2Flocalhost%3A8766&tenant=<uuid>");</script>
+</body>
+</html>
+```
+
+Run this repo's copy of it via `npm run start:static` (see "Run it" above),
+or drop the equivalent markup into any other project's page — nothing here
+depends on this package's build tooling.
+
+### Optional: `run_transient` for one-off computations
+
+A page can optionally define one more tool, alongside its regular fixed
+ones, that lets an agent write and immediately run a throwaway JS
+computation for the current session only — see `legacy-page/hello-world.html`
+for the full worked pilot (`runTransient` + its manifest entry). The
+motivating case: a page exposes some data (e.g. a big list of numbers,
+durations, or other values via a `get_*` tool), and the agent needs an
+aggregate over it — sum, average, max/min, a multi-step filter. Doing that
+arithmetic itself, in-context, token by token, gets unreliable as the list
+grows — it produces a plausible-looking wrong number with no error signal.
+Real JS run against the real data is deterministic.
+
+```js
+function runTransient({ code, args }) {
+  const parsedArgs = typeof args === 'string' && args ? JSON.parse(args) : undefined;
+  // eslint-disable-next-line no-new-func -- deliberate, see hello-world.html for the full rationale
+  const fn = new Function('args', 'document', 'window', code);
+  const result = fn(parsedArgs, document, window);
+  return typeof result === 'string' ? result : JSON.stringify(result);
+}
+
+window.__mcpTools.push({
+  name: 'run_transient',
+  description: '...(see hello-world.html for the bar to hit — must state clearly this is ' +
+    'for large/complex computations only, not a replacement for fixed tools, and that "code" ' +
+    'is a function BODY whose return value becomes the result)',
+  params: {
+    code: { type: 'string', description: 'JS function body; receives (args, document, window), return value becomes the result' },
+    args: { type: 'string', description: 'JSON string passed as `args`; omit if code takes no input', optional: true },
+  },
+  fn: runTransient,
+});
+```
+
+Deliberately **not** a new registered MCP tool per definition, and
+**not** persisted anywhere (not `localStorage`, not appended to
+`window.__mcpTools`) — each call compiles `code`, runs it once, and
+discards it:
+
+- The bridge reads `window.__mcpTools` once at connect and does not poll
+  (see "Common mistakes" above) — a page tool array mutated mid-session
+  wouldn't reach the *current* session's MCP client without a reconnect
+  anyway, so "register a new tool name per definition" doesn't reliably
+  work today even where the server-side sync supports it in principle.
+- Persisting agent-authored code across page loads is a materially
+  different, larger risk than running it once in the current tab: it turns
+  into arbitrary code that runs automatically on every future load with no
+  review step. Keep it session-scoped; if a computation turns out to be
+  worth reusing, promote it to a normal hand-authored, reviewed tool in the
+  page's own source instead of auto-persisting what the agent wrote.
+
+**This is still full code execution in the page's own origin** —
+`new Function` is not meaningfully safer than `eval`; session-scoping
+bounds *persistence*, not *capability*. Fine for a page with no
+auth/secrets (like the demo page here). A page carrying real session state,
+cookies, or API access should treat adding this tool as a deliberate,
+visible grant — document it clearly in `window.__mcpSummary` — not a
+default to copy onto every bridged page. The call itself (tool name, the
+`code` string, `args`, and the result) is an ordinary logged MCP
+call/result like any other tool call, so even though the code is
+agent-authored, what actually ran is auditable after the fact from the
+session transcript.
+
+### Common mistakes
+
+- Positional args instead of one args object (`fn({ rowId })`, not
+  `fn(rowId)`).
+- Defining `window.__mcpTools` *after* the embed snippet already ran.
+- Reusing a `name` across two entries in the **same page**'s own
+  `window.__mcpTools` array — this is still a real bug (last one wins).
+  Reusing a `name` across two *different* pages/tabs sharing a tenant is
+  fine now — see "Multiple tabs on one tenant" below, each gets an
+  automatic per-connection prefix.
+- Expecting a live-edited `window.__mcpTools` to take effect without a page
+  reload — it's read once per connect, not watched.
+- Pasting the embed snippet into the page **after** your MCP client already
+  connected: some clients (Claude Code included, observed against
+  `js-bridge-mcp`) fetch `tools/list` once at `initialize` and won't re-poll
+  on the server's `tools/list_changed` notification mid-session. New tools
+  may need a full MCP client restart to appear, even though the browser
+  tenant is connected and the server registered them correctly.
+- Two tabs of the *same* page connected to the same tenant get
+  ordinal-suffixed prefixes (`tab__`, `tab2__`, ...) unless
+  `window.__mcpAppName`/`document.title` differ between them — call
+  `describe_tools` to see current prefixes rather than guessing.
+
+### Multiple tabs on one tenant
+
+`get_embed_snippet` returns the same tenant id for the life of an MCP
+session, so pasting that same snippet into more than one browser tab — a
+different app in each tab, or several tabs of the same app — connects all
+of them to the same tenant. This is supported, not just an edge case to
+avoid: it's how one MCP session can drive multiple pages at once (e.g.
+"read form data from tab A, use it to drive tab B").
+
+- Each WS connection is tracked separately server-side. As soon as a
+  **second** connection registers tools, every registered MCP tool name
+  gets an automatic prefix: `${slug}__${name}` — e.g. `formalin__submit_form`,
+  `htmlpaint__clear_canvas`. With only one connection, tool names stay
+  exactly as they'd be alone (`submit_form`), no prefix.
+- The slug comes from `window.__mcpAppName` (or `document.title` if unset),
+  sanitized to `[a-z0-9_]`. Two connections that land on the same slug (same
+  app, or both unlabeled) get ordinal-suffixed: the first to connect keeps
+  the bare slug, the next becomes `slug2`, then `slug3`, etc. — so "use the
+  first htmlpaint tab" maps to the plain `htmlpaint__...` tools, and "use
+  the second" maps to `htmlpaint2__...`.
+- Calling `describe_tools` with 2+ connections returns a `connections[]`
+  array (`id`, `label`, `toolPrefix`, `summary`, `tools[]`) instead of the
+  single-connection flat shape — call it whenever you're not sure which
+  prefix routes to which tab.
+- Calls are routed to exactly one connection's socket — the other
+  tab(s) never see or respond to a call meant for a different one.
+- Closing a tab drops its connection; if that leaves exactly one connection
+  behind, that one's tools become unprefixed again on the next call.
+
+### Validation checklist before calling it done
+
+1. Call `get_embed_snippet`, run the snippet against the target page.
+2. Call `tools/list` (or just try the new tool by name) — confirm it appears.
+3. Call each new tool with its `example` args, confirm the page visibly
+   updates and the result isn't an error.
+4. Open a second tenant (call `get_embed_snippet` again from a fresh MCP
+   session) and confirm the new tools do **not** appear there — manifests
+   are per-tenant, never global.
+5. Paste the *same* `get_embed_snippet` snippet into a second browser tab
+   (same tenant, deliberately). Call `describe_tools` — confirm it lists
+   two connections with distinct labels/prefixes (`tab`/`tab2` if neither
+   page set `window.__mcpAppName`/title). Call one of the newly prefixed
+   tools (e.g. `tab__insert_title`) and confirm only that tab updates, not
+   the other. Close one tab, call `describe_tools` again, confirm it now
+   reports a single connection and that connection's tools are reachable
+   unprefixed again.
+
+For the fuller version of this recipe (including how to scaffold a brand-new
+MCP server package, "Pattern A" vs "Pattern B") see
+`packages/mcp-tenant-lib/BRIDGING.md` and `AGENTS.md`.
+
+## Why this shape
+
+See `packages/mcp-tenant-lib/AGENTS.md`, "Pattern B" section, for the
+general recipe this example follows.

package/bin/js-bridge-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/src/server.js';

package/dist/client/main.js

@@ -0,0 +1,69 @@
+function f(e) {
+  const t = [], o = /* @__PURE__ */ new Map();
+  for (const { fn: c, ...s } of e)
+    t.push(s), o.set(s.name, c);
+  return { manifest: t, fnByName: o };
+}
+function u(e, t = {}) {
+  let o, c = !1, s = 0;
+  const p = () => {
+    const i = t.tenant ?? (location.pathname.startsWith("/t/") ? location.pathname.slice(3).split("/")[0] : ""), g = i ? `/ws?tenant=${encodeURIComponent(i)}` : "/ws", m = `${t.serverUrl ? t.serverUrl.replace(/^http/, "ws") : `${location.protocol === "https:" ? "wss:" : "ws:"}//${location.host}`}${g}`;
+    console.log(`[mcp-ws] connecting (attempt ${s + 1}): ${m}`), o = new WebSocket(m), o.onopen = () => {
+      console.log(`[mcp-ws] connected${s > 0 ? ` after ${s} reconnect attempt(s)` : ""}`), s = 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) {
+          console.log("[mcp-ws] tenant unknown/expired (4404) — not retrying");
+          return;
+        }
+        s++, console.log(`[mcp-ws] retrying in 2s (attempt ${s + 1})`), setTimeout(p, 2e3);
+      }
+    }, o.onerror = () => {
+      console.log("[mcp-ws] socket error (see close event for details)");
+    }, o.onmessage = (r) => {
+      const n = JSON.parse(r.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);
+    };
+  };
+  return p(), {
+    send(i) {
+      o?.send(JSON.stringify(i));
+    },
+    close() {
+      c = !0, o?.close();
+    }
+  };
+}
+const y = window.__mcpTools ?? [], { manifest: h, fnByName: $ } = f(y), _ = window.__mcpSummary ?? void 0;
+let a = window.__mcpAppName ?? document.title ?? void 0, d = !1;
+function C() {
+  if (d) return a;
+  d = !0;
+  const e = prompt("Name this MCP connection (used to identify it to the agent):", a ?? "");
+  return e && (a = e), a;
+}
+const w = new URL(import.meta.url), b = w.searchParams.get("server") ?? void 0, S = w.searchParams.get("tenant") ?? void 0, l = u(
+  {
+    onConnect() {
+      console.log("[js-bridge-mcp] connected"), l.send({ type: "register_tools", tools: h, summary: _, appLabel: C() });
+    },
+    async onCall(e, t, o) {
+      try {
+        const c = $.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 });
+      } catch (c) {
+        l.send({ type: "call_result", id: e, error: String(c.message) });
+      }
+    },
+    onDisconnect() {
+      console.log("[js-bridge-mcp] disconnected, retrying...");
+    }
+  },
+  { serverUrl: b, tenant: S }
+);
+window.__mcpRename = (e) => {
+  const t = e ?? prompt("Rename this MCP connection:", a ?? "");
+  t && (a = t, l.send({ type: "rename_connection", appLabel: t }), console.log(`[js-bridge-mcp] renamed connection to "${t}"`));
+};

package/dist/src/server.js

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getOrCreateTenant as getOrCreateTenantFor, tenants, startIdleSweep, 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));
+// __dirname is <pkg>/src when run via tsx (dev/test) and <pkg>/dist/src once
+// built for publishing.
+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;
+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}`));
+// Only main.js is ever fetched from here — the legacy page this bundle is
+// injected into is hosted separately (see legacy-page/, run via
+// `npm run start:static`), not by this server.
+const STATIC_DIR = path.join(packageRoot, 'dist', 'client');
+const httpServer = createHttpServer({
+    port: PORT,
+    staticDir: STATIC_DIR,
+    initialSchema: undefined,
+    initialValues: initialHelloState,
+    identity: { name: 'js-bridge-mcp', version: '0.1.0' },
+    registerFn: registerHelloTools,
+    // 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
+    // reconnect/idle DELETE cycle). Sharing the one 'default' tenant keeps
+    // every such session pointed at the same already-bridged browser tab
+    // instead of each reconnect minting a new, empty tenant.
+    defaultTenantMode: 'shared',
+});
+attachWebSocketServer(httpServer, PORT, undefined, initialHelloState);
+httpServer.listen(PORT, () => {
+    console.error(`[js-bridge-mcp] MCP + bridge server listening on http://localhost:${PORT}`);
+    console.error(`[js-bridge-mcp] serve legacy-page/hello-world.html separately: npm run start:static`);
+});
+export { getOrCreateTenant, tenants, httpServer };

package/dist/src/tools/hello-tools.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+const getEmbedSnippet = {
+    name: 'get_embed_snippet',
+    description: 'Returns a single line of executable JavaScript that connects the current page to this ' +
+        'MCP session\'s tenant. Primary use: paste it directly into the browser\'s DevTools console ' +
+        '(Chrome/Firefox/etc.) on the target page and press enter — no editing the page\'s source ' +
+        'required. It can also be wrapped in a <script type="module">...</script> tag if the user ' +
+        'wants to bake it into the page\'s HTML instead (e.g. right before </body>). Either way, once ' +
+        'it runs, the page pushes its own tool manifest (window.__mcpTools, plus an optional ' +
+        'window.__mcpSummary string with shared cross-tool context — see the describe_tools tool once ' +
+        'connected) to this session\'s tenant, and the tools it declares become available to call from ' +
+        'THIS conversation. By default this server shares one tenant across every MCP session that ' +
+        'doesn\'t explicitly pin one (this keeps a single browser connection stable across an agent ' +
+        'harness\'s own session churn) — so unless the server was started with per-session tenants, ' +
+        'pages bridged from different conversations end up on the same tenant and see each other\'s ' +
+        'tools rather than staying isolated. Running the snippet immediately opens a browser prompt() ' +
+        'asking the user to name this connection (pre-filled with the page title) — warn the user ' +
+        'about this pop-up before they paste it so it isn\'t a surprise, and know that ' +
+        'dismissing/cancelling it is safe (falls back to the page title, connection proceeds either ' +
+        'way). The chosen name becomes this connection\'s tool-name prefix once a second connection ' +
+        'joins the same tenant (see describe_tools). Share the returned snippet with the user and tell ' +
+        'them to open DevTools on the target page, go to the Console tab, paste it, and press enter; do ' +
+        'not construct this URL by hand.',
+    schema: {},
+    handler: async (_args, tenant, port) => {
+        const tenantId = tenant().id;
+        const serverUrl = `http://localhost:${port}`;
+        const moduleUrl = `${serverUrl}/main.js?server=${encodeURIComponent(serverUrl)}&tenant=${tenantId}`;
+        const snippet = `import(${JSON.stringify(moduleUrl)});`;
+        return { content: [{ type: 'text', text: snippet }] };
+    },
+};
+export const helloTools = [getEmbedSnippet];

package/dist/src/tools/register.js

@@ -0,0 +1,16 @@
+import { createManifestToolRegistry } from 'mcp-tenant-lib';
+import { helloTools } from './hello-tools.js';
+export function registerHelloTools(mcp, tenant, port) {
+    for (const tool of helloTools) {
+        mcp.tool(tool.name, tool.description, tool.schema, (args) => tool.handler(args, tenant, port));
+    }
+    const registry = createManifestToolRegistry(mcp, tenant);
+    // addManifestToolRegistry syncs immediately and keeps this registry
+    // subscribed to future tenant.syncManifestToolRegistries() calls (see
+    // tenant.ts) — required under defaultTenantMode: 'shared', where
+    // multiple concurrent MCP sessions' McpServer/registry pairs can be
+    // bound to the same tenant at once and all need to stay in sync, not
+    // just whichever one connected last.
+    tenant().addManifestToolRegistry(registry);
+    mcp.server.onclose = () => tenant().removeManifestToolRegistry(registry);
+}

package/dist/src/types.js

@@ -0,0 +1,4 @@
+export const initialHelloState = {
+    title: 'Hello, world!',
+    main: 'Waiting for an agent to say something...',
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "js-bridge-mcp",
+  "version": "0.1.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": {
+    "type": "git",
+    "url": "git+https://github.com/anatolipr/avo-mcp-tools.git",
+    "directory": "packages/js-bridge-mcp"
+  },
+  "license": "MIT",
+  "bin": {
+    "js-bridge-mcp": "bin/js-bridge-mcp.js"
+  },
+  "main": "dist/src/server.js",
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "npm-run-all --parallel dev:client dev:mcp",
+    "dev:client": "vite build --watch",
+    "dev:mcp": "tsx watch src/server.ts",
+    "build": "tsc -p tsconfig.build.json && vite build",
+    "prestart:mcp": "npm run build",
+    "start:mcp": "tsx src/server.ts",
+    "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",
+    "stop": "kill -9 $(lsof -ti :${PORT:-8766}) 2>/dev/null && echo 'Server stopped' || echo 'No server running'",
+    "test": "node --import tsx --test test/**/*.test.ts"
+  },
+  "dependencies": {
+    "mcp-tenant-lib": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "ws": "^8.18.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/ws": "^8.5.0",
+    "http-server": "^14.1.1",
+    "npm-run-all": "^4.1.5",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0"
+  }
+}