mcp-tenant-lib 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anatoli Radulov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# mcp-tenant-lib
+
+Generic tenant/session bookkeeping + MCP wiring, reusable across MCP servers that need to
+track multiple browser-connected clients ("tenants") over HTTP + WebSocket.
+
+## Usage
+
+```ts
+import { getOrCreateTenant, tenants, startIdleSweep, createHttpServer, attachWebSocketServer } from 'mcp-tenant-lib';
+```
+
+Browser-side helpers (types + WebSocket bridge) are available from the `client` subpath:
+
+```ts
+import type { ServerMessage, ClientMessage } from 'mcp-tenant-lib/client';
+```

package/dist/client-bridge.d.ts

@@ -0,0 +1,57 @@
+import type { ClientMessage, ToolManifestEntry, ToolParamSpec } from './types.js';
+export interface ClientAction {
+    name: string;
+    resolve: 'window' | ((args: any) => unknown | Promise<unknown>);
+}
+/**
+ * The page-authored form of a manifest entry: same shape as
+ * ToolManifestEntry (name/description/params/example) plus a real function
+ * reference. Pages build an array of these (e.g. assigned to a global like
+ * window.__mcpTools) and pass it to registerPageTools below — the function
+ * reference never goes over the wire, only the serializable fields do.
+ */
+export interface PageToolDef {
+    name: string;
+    description: string;
+    params: Record<string, ToolParamSpec>;
+    example?: Record<string, unknown>;
+    fn: (args: any) => unknown | Promise<unknown>;
+}
+/**
+ * Strips `fn` from each PageToolDef to produce the wire-safe
+ * ToolManifestEntry[] for a RegisterToolsMessage, and returns a
+ * name -> fn lookup for dispatching incoming CallMessages locally.
+ */
+export declare function splitPageTools(defs: PageToolDef[]): {
+    manifest: ToolManifestEntry[];
+    fnByName: Map<string, PageToolDef['fn']>;
+};
+export declare function createClientBridge(actions: ClientAction[]): {
+    dispatch(name: string, args: unknown): Promise<unknown>;
+};
+export interface StateSocketHandlers<TSchema, TValues> {
+    onInit?(schema: TSchema, state: TValues): void;
+    onReinit?(schema: TSchema, state: TValues): void;
+    onUpdate?(field: string, value: unknown): void;
+    onCall?(id: string, name: string, args: unknown): void;
+    onConnect?(): void;
+    onDisconnect?(): void;
+}
+export interface StateSocketOptions {
+    /**
+     * Origin of the mcp-tenant-lib instance to connect to, e.g.
+     * 'http://localhost:8766'. Omit when the page is served by the same
+     * server it's connecting to (same-origin) — defaults to location.host.
+     * Required for the cross-origin "AI-enable an existing page" pattern.
+     */
+    serverUrl?: string;
+    /**
+     * Explicit tenant id. Omit to fall back to parsing '/t/<id>' from
+     * location.pathname (same-origin pattern), else 'default'.
+     */
+    tenant?: string;
+}
+export declare function connectStateSocket<TSchema, TValues>(handlers: StateSocketHandlers<TSchema, TValues>, options?: StateSocketOptions): {
+    send(msg: ClientMessage): void;
+    close(): void;
+};

package/dist/client-bridge.js

@@ -0,0 +1,91 @@
+/**
+ * Strips `fn` from each PageToolDef to produce the wire-safe
+ * ToolManifestEntry[] for a RegisterToolsMessage, and returns a
+ * name -> fn lookup for dispatching incoming CallMessages locally.
+ */
+export function splitPageTools(defs) {
+    const manifest = [];
+    const fnByName = new Map();
+    for (const { fn, ...entry } of defs) {
+        manifest.push(entry);
+        fnByName.set(entry.name, fn);
+    }
+    return { manifest, fnByName };
+}
+export function createClientBridge(actions) {
+    const byName = new Map(actions.map((a) => [a.name, a]));
+    return {
+        async dispatch(name, args) {
+            const action = byName.get(name);
+            if (!action)
+                throw new Error(`No client action registered for "${name}"`);
+            if (action.resolve === 'window') {
+                const fn = window[name];
+                if (typeof fn !== 'function') {
+                    throw new Error(`window.${name} is not a function — expose it before dispatching`);
+                }
+                return fn(args);
+            }
+            return action.resolve(args);
+        },
+    };
+}
+export function connectStateSocket(handlers, options = {}) {
+    let ws;
+    let closedByCaller = false;
+    let reconnectAttempts = 0;
+    const connect = () => {
+        const tenantId = options.tenant ?? (location.pathname.startsWith('/t/')
+            ? location.pathname.slice('/t/'.length).split('/')[0]
+            : '');
+        const wsPath = tenantId ? `/ws?tenant=${encodeURIComponent(tenantId)}` : '/ws';
+        const wsOrigin = options.serverUrl
+            ? options.serverUrl.replace(/^http/, 'ws')
+            : `${location.protocol === 'https:' ? 'wss:' : 'ws:'}//${location.host}`;
+        const wsUrl = `${wsOrigin}${wsPath}`;
+        console.log(`[mcp-ws] connecting (attempt ${reconnectAttempts + 1}): ${wsUrl}`);
+        ws = new WebSocket(wsUrl);
+        ws.onopen = () => {
+            console.log(`[mcp-ws] connected${reconnectAttempts > 0 ? ` after ${reconnectAttempts} reconnect attempt(s)` : ''}`);
+            reconnectAttempts = 0;
+            handlers.onConnect?.();
+        };
+        ws.onclose = (event) => {
+            console.log(`[mcp-ws] disconnected: code=${event.code} reason=${event.reason || '(none)'} wasClean=${event.wasClean}`);
+            handlers.onDisconnect?.();
+            if (closedByCaller)
+                return;
+            if (event.code === 4404) {
+                console.log('[mcp-ws] tenant unknown/expired (4404) — not retrying');
+                return;
+            }
+            reconnectAttempts++;
+            console.log(`[mcp-ws] retrying in 2s (attempt ${reconnectAttempts + 1})`);
+            setTimeout(connect, 2000);
+        };
+        ws.onerror = () => {
+            console.log('[mcp-ws] socket error (see close event for details)');
+        };
+        ws.onmessage = (event) => {
+            const msg = JSON.parse(event.data);
+            if (msg.type === 'init')
+                handlers.onInit?.(msg.schema, msg.state);
+            if (msg.type === 'reinit')
+                handlers.onReinit?.(msg.schema, msg.state);
+            if (msg.type === 'update')
+                handlers.onUpdate?.(msg.field, msg.value);
+            if (msg.type === 'call')
+                handlers.onCall?.(msg.id, msg.name, msg.args);
+        };
+    };
+    connect();
+    return {
+        send(msg) {
+            ws?.send(JSON.stringify(msg));
+        },
+        close() {
+            closedByCaller = true;
+            ws?.close();
+        },
+    };
+}

package/dist/http.d.ts

@@ -0,0 +1,32 @@
+import http from 'node:http';
+import { type RegisterToolsFn, type McpServerIdentity } from './mcp.js';
+export interface CreateHttpServerOptions<TSchema, TValues> {
+    port: number;
+    staticDir: string;
+    initialSchema: TSchema;
+    initialValues: TValues;
+    identity: McpServerIdentity;
+    registerFn: RegisterToolsFn<TSchema, TValues>;
+    /**
+     * Which tenant an MCP session with no ?tenant= param on its server URL
+     * lands on:
+     *
+     * - 'per-session' (default): a fresh randomUUID() tenant per session,
+     *   same as every session getting its own isolated state — what
+     *   mcp-form relies on so concurrent agents don't share form state
+     *   (see tenant-isolation.test.ts).
+     *
+     * - 'shared': every unpinned session lands on the single 'default'
+     *   tenant (same one the WS side and both packages' boot-time
+     *   getOrCreateTenant('default') call already use for plain browser
+     *   access). Appropriate when there's exactly one browser page bridged
+     *   per server and MCP clients aren't expected to pin a tenant
+     *   explicitly — some clients (observed with VS Code Copilot) open a
+     *   brand-new MCP session on every reconnect/idle DELETE cycle with no
+     *   ?tenant=, and under 'per-session' each such reconnect mints a new,
+     *   empty tenant that orphans whatever browser tab was already bridged
+     *   to the previous one.
+     */
+    defaultTenantMode?: 'per-session' | 'shared';
+}
+export declare function createHttpServer<TSchema, TValues>({ port, staticDir, initialSchema, initialValues, identity, registerFn, defaultTenantMode }: CreateHttpServerOptions<TSchema, TValues>): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;

package/dist/http.js

@@ -0,0 +1,160 @@
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { getOrCreateTenant } from './tenant.js';
+import { buildMcpServer } from './mcp.js';
+const UPLOAD_DIR = path.join(os.tmpdir(), 'mcp-form-uploads');
+fs.mkdirSync(UPLOAD_DIR, { recursive: true });
+const mime = { '.html': 'text/html', '.js': 'text/javascript', '.json': 'application/json' };
+const sessions = new Map();
+export function createHttpServer({ port, staticDir, initialSchema, initialValues, identity, registerFn, defaultTenantMode = 'per-session' }) {
+    const getTenant = (id) => {
+        const t = getOrCreateTenant(id, initialSchema, initialValues);
+        t.touch();
+        return t;
+    };
+    const httpServer = http.createServer(async (req, res) => {
+        const url = new URL(req.url ?? '/', `http://localhost:${port}`);
+        if (url.pathname === '/mcp') {
+            res.setHeader('Access-Control-Allow-Origin', '*');
+            res.setHeader('Access-Control-Allow-Methods', 'POST, GET, DELETE, OPTIONS');
+            res.setHeader('Access-Control-Allow-Headers', 'Content-Type, mcp-session-id');
+            if (req.method === 'OPTIONS') {
+                res.writeHead(204);
+                res.end();
+                return;
+            }
+            const sessionId = req.headers['mcp-session-id'];
+            if (req.method === 'POST' && !sessionId) {
+                // An MCP client that wants a stable identity across reconnects (its
+                // own idle timeouts, extension host restarts, etc.) can always pin
+                // one explicitly by including ?tenant=<id> on its configured server
+                // URL — same convention the WS bridge already uses. Without that,
+                // which tenant the session lands on depends on defaultTenantMode
+                // (see CreateHttpServerOptions for the tradeoff).
+                //
+                // The MCP *session id* itself is always a fresh randomUUID() —
+                // sessionIdGenerator must stay unique per transport (the `sessions`
+                // map is keyed on it) so concurrent clients don't collide; only
+                // which *tenant* the session operates on varies by mode.
+                const requestedTenantId = url.searchParams.get('tenant');
+                const tenantId = requestedTenantId || (defaultTenantMode === 'shared' ? 'default' : randomUUID());
+                const transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    onsessioninitialized: (id) => {
+                        sessions.set(id, transport);
+                        getOrCreateTenant(tenantId, initialSchema, initialValues);
+                        console.error(`[mcp] session opened: ${id} (tenant=${tenantId})`);
+                    },
+                });
+                transport.onclose = () => {
+                    // The transport closing only means this particular HTTP/SSE
+                    // connection ended — it does NOT mean the tenant (and any
+                    // browser tabs bridged to it over /ws) should be torn down.
+                    // Disposing here used to force-close every connected browser
+                    // tab the instant an MCP client reconnected/recycled its
+                    // connection, even though the tenant itself was still healthy.
+                    // Tenant disposal is now solely driven by the idle sweep (see
+                    // startIdleSweep) or an explicit DELETE (below), so a tenant —
+                    // and its live browser connections — survives MCP-side session
+                    // churn as long as it keeps seeing activity from either side.
+                    if (transport.sessionId) {
+                        sessions.delete(transport.sessionId);
+                        console.error(`[mcp] session detached: ${transport.sessionId}`);
+                    }
+                };
+                const mcpInstance = buildMcpServer(identity, tenantId, getTenant, port, registerFn);
+                await mcpInstance.connect(transport);
+                await transport.handleRequest(req, res);
+                return;
+            }
+            if (sessionId && sessions.has(sessionId)) {
+                if (req.method === 'DELETE') {
+                    // Mirrors transport.onclose above: a client-initiated DELETE ends
+                    // *this* MCP session, but some clients (observed with Copilot)
+                    // send it routinely between turns / on idle, not just on final
+                    // teardown. Disposing the tenant here used to force-close every
+                    // bridged browser tab and wipe its tool manifest on every such
+                    // DELETE, which surfaced to the agent as tools vanishing
+                    // ("Tool X not found") the moment it tried to call something
+                    // right after a DELETE-triggered reconnect cycle. Tenant
+                    // disposal is left to the idle sweep (see startIdleSweep) so
+                    // browser state survives MCP-side session churn from either
+                    // close path — the DELETE still reaches the transport below so
+                    // its own session bookkeeping (and transport.onclose, which
+                    // removes it from `sessions`) runs normally.
+                    console.error(`[mcp] session closing (explicit DELETE): ${sessionId}`);
+                }
+                await sessions.get(sessionId).handleRequest(req, res);
+                return;
+            }
+            console.error(`[mcp] rejected ${req.method} for unknown session: ${sessionId ?? '(none)'}${url.searchParams.get('tenant') ? ` tenant=${url.searchParams.get('tenant')}` : ''}`);
+            res.writeHead(404);
+            res.end('Unknown session');
+            return;
+        }
+        if (url.pathname === '/upload' && req.method === 'POST') {
+            const contentType = req.headers['content-type'] ?? '';
+            const boundaryMatch = contentType.match(/boundary=(.+)$/);
+            if (!boundaryMatch) {
+                res.writeHead(400);
+                res.end('Missing boundary');
+                return;
+            }
+            const boundary = Buffer.from('--' + boundaryMatch[1]);
+            const chunks = [];
+            req.on('data', (chunk) => chunks.push(chunk));
+            req.on('end', () => {
+                const body = Buffer.concat(chunks);
+                // Find the filename from Content-Disposition header in the part
+                const headerEnd = body.indexOf('\r\n\r\n');
+                const headerSection = body.slice(0, headerEnd).toString();
+                const nameMatch = headerSection.match(/filename="([^"]+)"/);
+                const originalName = nameMatch ? nameMatch[1] : 'upload';
+                const ext = path.extname(originalName);
+                const savedName = `${randomUUID()}${ext}`;
+                const savedPath = path.join(UPLOAD_DIR, savedName);
+                // Extract file bytes: after \r\n\r\n, before the closing boundary
+                const fileStart = headerEnd + 4;
+                const closingBoundary = Buffer.from('\r\n' + boundary.toString() + '--');
+                let fileEnd = body.length;
+                for (let i = fileStart; i <= body.length - closingBoundary.length; i++) {
+                    if (body.slice(i, i + closingBoundary.length).equals(closingBoundary)) {
+                        fileEnd = i;
+                        break;
+                    }
+                }
+                fs.writeFile(savedPath, body.slice(fileStart, fileEnd), (err) => {
+                    if (err) {
+                        res.writeHead(500);
+                        res.end('Write error');
+                        return;
+                    }
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ path: savedPath, name: originalName }));
+                });
+            });
+            return;
+        }
+        let pathname = url.pathname;
+        if (pathname.startsWith('/t/')) {
+            pathname = '/';
+        }
+        let filePath = pathname === '/' ? '/index.html' : pathname;
+        filePath = path.join(staticDir, filePath);
+        fs.readFile(filePath, (err, data) => {
+            if (err) {
+                res.writeHead(404);
+                res.end('Not found');
+                return;
+            }
+            const ext = path.extname(filePath);
+            res.writeHead(200, { 'Content-Type': mime[ext] || 'application/octet-stream', 'Access-Control-Allow-Origin': '*' });
+            res.end(data);
+        });
+    });
+    return httpServer;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep } from './tenant.js';
+export { buildMcpServer, type RegisterToolsFn, type McpServerIdentity } from './mcp.js';
+export { createHttpServer, type CreateHttpServerOptions } from './http.js';
+export { attachWebSocketServer } from './ws.js';
+export { createManifestToolRegistry, type ManifestToolRegistry } from './manifest-tools.js';
+export * from './types.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep } from './tenant.js';
+export { buildMcpServer } from './mcp.js';
+export { createHttpServer } from './http.js';
+export { attachWebSocketServer } from './ws.js';
+export { createManifestToolRegistry } from './manifest-tools.js';
+export * from './types.js';

package/dist/manifest-tools.d.ts

@@ -0,0 +1,21 @@
+import type { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Tenant } from './tenant.js';
+export interface ManifestToolRegistry {
+    handles: Map<string, RegisteredTool>;
+    sync(): void;
+}
+/**
+ * Registers one MCP tool per entry in tenant().toolManifest, dispatching
+ * calls to the page via tenant().call(target, args). Also always registers
+ * a fixed `describe_tools` tool that surfaces tenant().toolManifestSummary -
+ * the page-authored manifest-level context from RegisterToolsMessage.summary
+ * - plus a compact index of current tool names/descriptions. That summary
+ * can't be baked into the McpServer's static `instructions` because the
+ * page (and its manifest/summary) only connects and registers *after* the
+ * McpServer is already constructed per session (see http.ts) - describe_tools
+ * is the one mechanism that can carry page-supplied context to the agent.
+ * Call sync() again after the manifest changes (e.g. on a fresh
+ * register_tools push) to remove stale tools and register new ones - each
+ * mutation trips the SDK's own tools/list_changed notification automatically.
+ */
+export declare function createManifestToolRegistry<TSchema, TValues>(mcp: McpServer, tenant: () => Tenant<TSchema, TValues>): ManifestToolRegistry;

package/dist/manifest-tools.js

@@ -0,0 +1,162 @@
+import { z } from 'zod';
+function paramSpecToZod(spec) {
+    let schema;
+    switch (spec.type) {
+        case 'string':
+            schema = z.string();
+            break;
+        case 'number':
+            schema = z.number();
+            break;
+        case 'boolean':
+            schema = z.boolean();
+            break;
+        default: throw new Error(`unsupported param type "${spec.type}" (supported: string, number, boolean)`);
+    }
+    if (spec.description)
+        schema = schema.describe(spec.description);
+    return spec.optional ? schema.optional() : schema;
+}
+function manifestEntryToZodShape(entry) {
+    const shape = {};
+    for (const [key, spec] of Object.entries(entry.params)) {
+        shape[key] = paramSpecToZod(spec);
+    }
+    return shape;
+}
+const DESCRIBE_TOOLS_NAME = 'describe_tools';
+const DESCRIBE_TOOLS_DESCRIPTION = 'Returns manifest-level context for the tools this connected page registered: a ' +
+    'page-authored summary (what kind of page/app this is, cross-tool sequencing rules, ' +
+    'domain concepts) plus the current list of tool names and one-line descriptions. Call ' +
+    'this once after connecting, before calling any other tool from this page, so you have ' +
+    'the shared context that individual tool descriptions don\'t repeat. When multiple ' +
+    'pages/tabs are connected to this session at once, tool names are prefixed per ' +
+    'connection (e.g. "formalin__submit_form", "htmlpaint__clear_canvas") and this tool\'s ' +
+    'response includes a `connections` array listing each connection\'s id, label, and ' +
+    'prefix — call it whenever you\'re unsure which prefix routes to which tab.';
+/**
+ * Derives a stable, unique tool-name prefix per connection: sanitized from
+ * `label` (falling back to "tab" when absent or empty after sanitizing),
+ * with a 1-based ordinal appended on collision (first connection to open
+ * keeps the bare slug; later ones sharing that slug get "2", "3", ...).
+ * Recomputed fresh on every call from `connections`' current iteration
+ * order (== connection-open order, since Map preserves insertion order and
+ * entries are only ever added/removed, never reordered) — no state to
+ * keep in sync separately.
+ */
+function computeSlugs(connections) {
+    const slugFor = new Map();
+    const countSoFar = new Map();
+    for (const conn of connections) {
+        const base = slugify(conn.label);
+        const n = (countSoFar.get(base) ?? 0) + 1;
+        countSoFar.set(base, n);
+        slugFor.set(conn.id, n === 1 ? base : `${base}${n}`);
+    }
+    return slugFor;
+}
+function slugify(label) {
+    const cleaned = (label ?? '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, 24);
+    return cleaned || 'tab';
+}
+/**
+ * Registers one MCP tool per entry in tenant().toolManifest, dispatching
+ * calls to the page via tenant().call(target, args). Also always registers
+ * a fixed `describe_tools` tool that surfaces tenant().toolManifestSummary -
+ * the page-authored manifest-level context from RegisterToolsMessage.summary
+ * - plus a compact index of current tool names/descriptions. That summary
+ * can't be baked into the McpServer's static `instructions` because the
+ * page (and its manifest/summary) only connects and registers *after* the
+ * McpServer is already constructed per session (see http.ts) - describe_tools
+ * is the one mechanism that can carry page-supplied context to the agent.
+ * Call sync() again after the manifest changes (e.g. on a fresh
+ * register_tools push) to remove stale tools and register new ones - each
+ * mutation trips the SDK's own tools/list_changed notification automatically.
+ */
+export function createManifestToolRegistry(mcp, tenant) {
+    const handles = new Map();
+    function registerDescribeTools() {
+        const handle = mcp.registerTool(DESCRIBE_TOOLS_NAME, { description: DESCRIBE_TOOLS_DESCRIPTION, inputSchema: {} }, async () => {
+            const t = tenant();
+            const conns = [...t.connections.values()];
+            if (conns.length <= 1) {
+                const payload = {
+                    summary: t.toolManifestSummary ?? null,
+                    tools: t.toolManifest.map((e) => ({ name: e.name, description: e.description })),
+                };
+                return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+            }
+            const slugFor = computeSlugs(conns);
+            const payload = {
+                connections: conns.map((c) => ({
+                    id: c.id,
+                    label: c.label ?? null,
+                    toolPrefix: slugFor.get(c.id),
+                    summary: c.summary ?? null,
+                    tools: c.manifest.map((e) => ({
+                        name: `${slugFor.get(c.id)}__${e.name}`,
+                        description: e.description,
+                    })),
+                })),
+            };
+            return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+        });
+        handles.set(DESCRIBE_TOOLS_NAME, handle);
+    }
+    function sync() {
+        const conns = [...tenant().connections.values()];
+        const multi = conns.length >= 2;
+        const slugFor = multi ? computeSlugs(conns) : undefined;
+        // registeredName -> which connection/entry it dispatches to. With a
+        // single (or no) connection, registeredName === entry.name, exactly
+        // like before multi-connection support existed.
+        const registeredNow = new Map();
+        if (multi) {
+            for (const conn of conns) {
+                for (const entry of conn.manifest) {
+                    if (entry.name === DESCRIBE_TOOLS_NAME)
+                        continue;
+                    registeredNow.set(`${slugFor.get(conn.id)}__${entry.name}`, { connectionId: conn.id, entry });
+                }
+            }
+        }
+        else {
+            const conn = conns[0];
+            for (const entry of tenant().toolManifest) {
+                if (entry.name === DESCRIBE_TOOLS_NAME)
+                    continue;
+                registeredNow.set(entry.name, { connectionId: conn?.id, entry });
+            }
+        }
+        // A page tool named "describe_tools" would collide with the fixed tool
+        // below - the fixed one always wins so agents can rely on the name.
+        const currentNames = new Set([DESCRIBE_TOOLS_NAME, ...registeredNow.keys()]);
+        for (const [name, handle] of handles) {
+            if (!currentNames.has(name)) {
+                handle.remove();
+                handles.delete(name);
+            }
+        }
+        if (!handles.has(DESCRIBE_TOOLS_NAME))
+            registerDescribeTools();
+        for (const [registeredName, { connectionId, entry }] of registeredNow) {
+            if (handles.has(registeredName))
+                continue;
+            const handle = mcp.registerTool(registeredName, { description: entry.description, inputSchema: manifestEntryToZodShape(entry) }, async (args) => {
+                try {
+                    const result = await tenant().call(connectionId, entry.name, args);
+                    return { content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }] };
+                }
+                catch (err) {
+                    return { content: [{ type: 'text', text: String(err.message) }], isError: true };
+                }
+            });
+            handles.set(registeredName, handle);
+        }
+    }
+    return { handles, sync };
+}

package/dist/mcp.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Tenant } from './tenant.js';
+export type RegisterToolsFn<TSchema = any, TValues = any> = (mcp: McpServer, tenant: () => Tenant<TSchema, TValues>, port: number) => void;
+export interface McpServerIdentity {
+    name: string;
+    version: string;
+}
+export declare function buildMcpServer<TSchema, TValues>(identity: McpServerIdentity, tenantId: string, getTenant: (id: string) => Tenant<TSchema, TValues>, port: number, registerFn: RegisterToolsFn<TSchema, TValues>): McpServer;

package/dist/mcp.js

@@ -0,0 +1,7 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export function buildMcpServer(identity, tenantId, getTenant, port, registerFn) {
+    const mcp = new McpServer(identity);
+    const tenant = () => getTenant(tenantId);
+    registerFn(mcp, tenant, port);
+    return mcp;
+}

package/dist/tenant.d.ts

@@ -0,0 +1,122 @@
+import { EventEmitter } from 'node:events';
+import type { WebSocket } from 'ws';
+import type { ToolManifestEntry } from './types.js';
+/**
+ * One WS connection's own tool manifest/summary/label, addressable
+ * independently of other connections sharing the same tenant (e.g. two
+ * browser tabs pasted the same embed snippet). See manifest-tools.ts for
+ * how multiple connections' tools get name-disambiguated.
+ */
+export interface TenantConnection {
+    id: string;
+    socket: WebSocket;
+    label?: string;
+    manifest: ToolManifestEntry[];
+    summary?: string;
+}
+export declare class Store<TValues> {
+    #private;
+    constructor(initial: TValues);
+    has(name: string): boolean;
+    get(name: string): unknown;
+    set(name: string, value: unknown): void;
+    snapshot(): TValues;
+    onChange(fn: (name: string, value: unknown) => void): () => boolean;
+    dispose(): void;
+}
+/**
+ * TSchema is set once per applyState call and is not itself reactive
+ * (e.g. field definitions/labels). TValues is the reactive value bag
+ * backing `store`, broadcast field-by-field over the WS `update` message.
+ * Consumers with no separate schema concept can pass `undefined` for TSchema.
+ */
+export declare class Tenant<TSchema, TValues> {
+    #private;
+    id: string;
+    schema: TSchema;
+    store: Store<TValues>;
+    submitBus: EventEmitter;
+    wsClients: Set<WebSocket>;
+    connections: Map<string, TenantConnection>;
+    lastActivityAt: number;
+    pendingCalls: Map<string, {
+        resolve: (v: unknown) => void;
+        reject: (e: Error) => void;
+    }>;
+    /**
+     * Back-compat view over the per-connection manifests below: single flat
+     * array/summary, meaningful for the 0-1-connection case (the overwhelming
+     * majority — a single page/tab on this tenant). With 2+ connections this
+     * flattens everything, which loses which tool belongs to which
+     * connection — multi-connection-aware code (manifest-tools.ts) reads
+     * `connections` directly instead.
+     */
+    get toolManifest(): ToolManifestEntry[];
+    get toolManifestSummary(): string | undefined;
+    constructor(id: string, initialSchema: TSchema, initialValues: TValues);
+    /**
+     * Legacy/no-WS path: registers a manifest with no real connection behind
+     * it. Used directly by tests that construct a bare Tenant, and left in
+     * place for any caller that doesn't (yet) know about individual
+     * connections. Real WS-driven registration goes through
+     * registerConnection/updateConnectionManifest instead (see ws.ts).
+     */
+    setToolManifest(manifest: ToolManifestEntry[], summary?: string): void;
+    registerConnection(id: string, socket: WebSocket): void;
+    updateConnectionManifest(id: string, manifest: ToolManifestEntry[], summary?: string, label?: string): void;
+    /**
+     * Updates only a connection's display label, leaving its manifest/summary
+     * untouched — used by RenameConnectionMessage so a page can rename itself
+     * (e.g. via __mcpRename) without resending its whole tool manifest.
+     * Re-syncs so tool-name prefixes (computeSlugs in manifest-tools.ts)
+     * reflect the new label immediately.
+     */
+    renameConnection(id: string, label: string): void;
+    removeConnection(id: string): void;
+    addManifestToolRegistry(registry: {
+        sync(): void;
+    }): void;
+    removeManifestToolRegistry(registry: {
+        sync(): void;
+    }): void;
+    syncManifestToolRegistries(): void;
+    /**
+     * `connectionId` targets the call at one specific connection's socket —
+     * this is what lets multiple tabs share a tenant without racing on each
+     * other's responses. Passing `undefined` broadcasts to every socket on
+     * the tenant, same as the old behavior; kept for the legacy/no-connections
+     * test path.
+     *
+     * A reconnecting tab always gets a brand-new `connectionId` (see ws.ts),
+     * so a call already in flight when its socket drops has no old id to
+     * reconnect to. Rather than failing it immediately (the client's own 2s
+     * reconnect loop — see client-bridge.ts — would very likely have
+     * succeeded a moment later), we give it a short grace window to see if
+     * *some* connection reappears on this tenant before giving up. This only
+     * matters for the target-one-connection path: with a single-tab tenant
+     * (the overwhelming common case) any reappearing connection is the same
+     * tab; with multiple tabs the caller only reaches this path once the
+     * specific one it wanted has already vanished, so re-targeting the sole
+     * survivor (if there's exactly one) is still the best available guess.
+     */
+    call(connectionId: string | undefined, name: string, args: unknown, timeoutMs?: number, reconnectGraceMs?: number): Promise<unknown>;
+    /**
+     * Resolves with a live connection id once `this.connections` becomes
+     * non-empty again within `graceMs`, or `undefined` on timeout. Polls
+     * instead of hooking registerConnection directly to keep this
+     * self-contained and cheap for the rare/short-lived window it's used in.
+     */
+    private waitForReconnect;
+    resolveCall(id: string, result: unknown): void;
+    rejectCall(id: string, error: string): void;
+    touch(): void;
+    applyState(schema: TSchema, values: TValues): void;
+    broadcastReinit(): void;
+    broadcastUpdate(field: string, value: unknown): void;
+    dispose(): void;
+}
+declare const tenants: Map<string, Tenant<any, any>>;
+declare function getOrCreateTenant<TSchema, TValues>(id: string, initialSchema: TSchema, initialValues: TValues): Tenant<TSchema, TValues>;
+declare function disposeTenant(id: string): void;
+declare function startIdleSweep(onSweep: (id: string) => void): NodeJS.Timeout;
+export { tenants, getOrCreateTenant, disposeTenant, startIdleSweep };

package/dist/tenant.js

@@ -0,0 +1,323 @@
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+/**
+ * How long Tenant.call waits for some connection to reappear on a tenant
+ * before giving up, when the connection it was targeting has already
+ * vanished (see Tenant.call). Set comfortably above the client's 2s
+ * reconnect retry (client-bridge.ts) so a single dropped-then-reconnected
+ * socket doesn't surface as a failed call.
+ */
+const RECONNECT_GRACE_MS = 4_000;
+export class Store {
+    #values;
+    #subscribers = new Set();
+    constructor(initial) {
+        this.#values = initial;
+    }
+    has(name) { return Object.prototype.hasOwnProperty.call(this.#values, name); }
+    get(name) { return this.#values[name]; }
+    set(name, value) {
+        this.#values[name] = value;
+        for (const fn of this.#subscribers)
+            fn(name, value);
+    }
+    snapshot() { return { ...this.#values }; }
+    onChange(fn) {
+        this.#subscribers.add(fn);
+        return () => this.#subscribers.delete(fn);
+    }
+    dispose() { this.#subscribers.clear(); }
+}
+/**
+ * TSchema is set once per applyState call and is not itself reactive
+ * (e.g. field definitions/labels). TValues is the reactive value bag
+ * backing `store`, broadcast field-by-field over the WS `update` message.
+ * Consumers with no separate schema concept can pass `undefined` for TSchema.
+ */
+export class Tenant {
+    id;
+    schema;
+    store;
+    submitBus;
+    wsClients;
+    connections = new Map();
+    #legacyManifest;
+    #legacySummary;
+    lastActivityAt;
+    pendingCalls = new Map();
+    /**
+     * One entry per MCP session currently bound to this tenant (each session
+     * builds its own McpServer + registry via registerFn — see register.ts).
+     * Under defaultTenantMode: 'shared' (http.ts), multiple concurrent MCP
+     * sessions legitimately share one tenant, so this can't be a single
+     * slot: overwriting it on each new session used to silently stop
+     * syncing every *other* session's tool list on the next WS manifest
+     * change, freezing their tools/list stale. addManifestToolRegistry /
+     * removeManifestToolRegistry (called from mcp.ts around session
+     * connect/close) keep this in sync with which sessions are live;
+     * syncManifestToolRegistries() (called wherever the single sync() call
+     * used to happen) fans out to all of them.
+     */
+    #manifestToolRegistries = new Set();
+    /**
+     * Back-compat view over the per-connection manifests below: single flat
+     * array/summary, meaningful for the 0-1-connection case (the overwhelming
+     * majority — a single page/tab on this tenant). With 2+ connections this
+     * flattens everything, which loses which tool belongs to which
+     * connection — multi-connection-aware code (manifest-tools.ts) reads
+     * `connections` directly instead.
+     */
+    get toolManifest() {
+        if (this.connections.size === 0)
+            return this.#legacyManifest ?? [];
+        if (this.connections.size === 1)
+            return [...this.connections.values()][0].manifest;
+        return [...this.connections.values()].flatMap((c) => c.manifest);
+    }
+    get toolManifestSummary() {
+        if (this.connections.size === 1)
+            return [...this.connections.values()][0].summary;
+        return this.#legacySummary;
+    }
+    constructor(id, initialSchema, initialValues) {
+        this.id = id;
+        this.schema = initialSchema;
+        this.store = new Store(initialValues);
+        this.submitBus = new EventEmitter();
+        this.submitBus.setMaxListeners(0);
+        this.wsClients = new Set();
+        this.lastActivityAt = Date.now();
+        this.store.onChange((field, value) => this.broadcastUpdate(field, value));
+    }
+    /**
+     * Legacy/no-WS path: registers a manifest with no real connection behind
+     * it. Used directly by tests that construct a bare Tenant, and left in
+     * place for any caller that doesn't (yet) know about individual
+     * connections. Real WS-driven registration goes through
+     * registerConnection/updateConnectionManifest instead (see ws.ts).
+     */
+    setToolManifest(manifest, summary) {
+        this.#legacyManifest = manifest;
+        this.#legacySummary = summary;
+        this.syncManifestToolRegistries();
+    }
+    registerConnection(id, socket) {
+        this.connections.set(id, { id, socket, manifest: [], summary: undefined, label: undefined });
+        this.wsClients.add(socket);
+    }
+    updateConnectionManifest(id, manifest, summary, label) {
+        const conn = this.connections.get(id);
+        if (!conn)
+            return; // connection closed/unknown — ignore a late message
+        conn.manifest = manifest;
+        conn.summary = summary;
+        conn.label = label;
+        this.syncManifestToolRegistries();
+    }
+    /**
+     * Updates only a connection's display label, leaving its manifest/summary
+     * untouched — used by RenameConnectionMessage so a page can rename itself
+     * (e.g. via __mcpRename) without resending its whole tool manifest.
+     * Re-syncs so tool-name prefixes (computeSlugs in manifest-tools.ts)
+     * reflect the new label immediately.
+     */
+    renameConnection(id, label) {
+        const conn = this.connections.get(id);
+        if (!conn)
+            return; // connection closed/unknown — ignore a late message
+        conn.label = label;
+        this.syncManifestToolRegistries();
+    }
+    removeConnection(id) {
+        const conn = this.connections.get(id);
+        if (conn)
+            this.wsClients.delete(conn.socket);
+        this.connections.delete(id);
+        this.syncManifestToolRegistries();
+    }
+    addManifestToolRegistry(registry) {
+        this.#manifestToolRegistries.add(registry);
+        registry.sync();
+    }
+    removeManifestToolRegistry(registry) {
+        this.#manifestToolRegistries.delete(registry);
+    }
+    syncManifestToolRegistries() {
+        for (const registry of this.#manifestToolRegistries)
+            registry.sync();
+    }
+    /**
+     * `connectionId` targets the call at one specific connection's socket —
+     * this is what lets multiple tabs share a tenant without racing on each
+     * other's responses. Passing `undefined` broadcasts to every socket on
+     * the tenant, same as the old behavior; kept for the legacy/no-connections
+     * test path.
+     *
+     * A reconnecting tab always gets a brand-new `connectionId` (see ws.ts),
+     * so a call already in flight when its socket drops has no old id to
+     * reconnect to. Rather than failing it immediately (the client's own 2s
+     * reconnect loop — see client-bridge.ts — would very likely have
+     * succeeded a moment later), we give it a short grace window to see if
+     * *some* connection reappears on this tenant before giving up. This only
+     * matters for the target-one-connection path: with a single-tab tenant
+     * (the overwhelming common case) any reappearing connection is the same
+     * tab; with multiple tabs the caller only reaches this path once the
+     * specific one it wanted has already vanished, so re-targeting the sole
+     * survivor (if there's exactly one) is still the best available guess.
+     */
+    call(connectionId, name, args, timeoutMs = 10_000, reconnectGraceMs = RECONNECT_GRACE_MS) {
+        const id = randomUUID();
+        const promise = new Promise((resolve, reject) => {
+            this.pendingCalls.set(id, { resolve, reject });
+            const timer = setTimeout(() => {
+                if (this.pendingCalls.delete(id))
+                    reject(new Error(`call to "${name}" timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            timer.unref();
+        });
+        const send = (targetConnectionId) => {
+            const payload = { type: 'call', id, name, args };
+            const raw = JSON.stringify(payload);
+            if (targetConnectionId) {
+                const conn = this.connections.get(targetConnectionId);
+                if (conn && conn.socket.readyState === conn.socket.OPEN)
+                    conn.socket.send(raw);
+            }
+            else {
+                for (const client of this.wsClients) {
+                    if (client.readyState === client.OPEN)
+                        client.send(raw);
+                }
+            }
+        };
+        if (connectionId && !this.connections.has(connectionId)) {
+            this.waitForReconnect(reconnectGraceMs).then((revivedConnectionId) => {
+                const pending = this.pendingCalls.get(id);
+                if (!pending)
+                    return; // already timed out/resolved while we waited
+                if (!revivedConnectionId) {
+                    this.pendingCalls.delete(id);
+                    pending.reject(new Error(`connection "${connectionId}" is no longer connected`));
+                    return;
+                }
+                send(revivedConnectionId);
+            });
+            return promise;
+        }
+        send(connectionId);
+        return promise;
+    }
+    /**
+     * Resolves with a live connection id once `this.connections` becomes
+     * non-empty again within `graceMs`, or `undefined` on timeout. Polls
+     * instead of hooking registerConnection directly to keep this
+     * self-contained and cheap for the rare/short-lived window it's used in.
+     */
+    waitForReconnect(graceMs) {
+        return new Promise((resolve) => {
+            const deadline = Date.now() + graceMs;
+            const poll = () => {
+                const [first] = this.connections.keys();
+                if (first) {
+                    resolve(first);
+                    return;
+                }
+                if (Date.now() >= deadline) {
+                    resolve(undefined);
+                    return;
+                }
+                setTimeout(poll, 250).unref();
+            };
+            poll();
+        });
+    }
+    resolveCall(id, result) {
+        const pending = this.pendingCalls.get(id);
+        if (!pending)
+            return;
+        this.pendingCalls.delete(id);
+        pending.resolve(result);
+    }
+    rejectCall(id, error) {
+        const pending = this.pendingCalls.get(id);
+        if (!pending)
+            return;
+        this.pendingCalls.delete(id);
+        pending.reject(new Error(error));
+    }
+    touch() {
+        this.lastActivityAt = Date.now();
+    }
+    applyState(schema, values) {
+        this.store.dispose();
+        this.schema = schema;
+        this.store = new Store(values);
+        this.store.onChange((field, value) => this.broadcastUpdate(field, value));
+        this.broadcastReinit();
+    }
+    broadcastReinit() {
+        const payload = JSON.stringify({ type: 'reinit', schema: this.schema, state: this.store.snapshot() });
+        for (const client of this.wsClients) {
+            if (client.readyState === client.OPEN)
+                client.send(payload);
+        }
+    }
+    broadcastUpdate(field, value) {
+        const payload = JSON.stringify({ type: 'update', field, value });
+        for (const client of this.wsClients) {
+            if (client.readyState === client.OPEN)
+                client.send(payload);
+        }
+    }
+    dispose() {
+        this.submitBus.emit('submit', { __interrupted: true, __disposed: true, ...this.store.snapshot() });
+        this.store.dispose();
+        this.submitBus.removeAllListeners();
+        for (const [, pending] of this.pendingCalls) {
+            pending.reject(new Error('tenant disposed'));
+        }
+        this.pendingCalls.clear();
+        for (const client of this.wsClients)
+            client.close();
+        this.wsClients.clear();
+        this.connections.clear();
+    }
+}
+const tenants = new Map();
+function getOrCreateTenant(id, initialSchema, initialValues) {
+    let tenant = tenants.get(id);
+    if (!tenant) {
+        tenant = new Tenant(id, initialSchema, initialValues);
+        tenants.set(id, tenant);
+    }
+    return tenant;
+}
+function disposeTenant(id) {
+    tenants.get(id)?.dispose();
+    tenants.delete(id);
+}
+function envMs(name, defaultMs) {
+    const raw = process.env[name];
+    if (!raw)
+        return defaultMs;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : defaultMs;
+}
+const TENANT_IDLE_TIMEOUT_MS = envMs('TENANT_IDLE_TIMEOUT_MS', 30 * 60 * 1000);
+const TENANT_SWEEP_INTERVAL_MS = envMs('TENANT_SWEEP_INTERVAL_MS', 5 * 60 * 1000);
+function startIdleSweep(onSweep) {
+    const sweepInterval = setInterval(() => {
+        const now = Date.now();
+        for (const [id, tenant] of tenants) {
+            if (id === 'default')
+                continue;
+            if (now - tenant.lastActivityAt > TENANT_IDLE_TIMEOUT_MS) {
+                onSweep(id);
+                disposeTenant(id);
+            }
+        }
+    }, TENANT_SWEEP_INTERVAL_MS);
+    sweepInterval.unref();
+    return sweepInterval;
+}
+export { tenants, getOrCreateTenant, disposeTenant, startIdleSweep };

package/dist/types.d.ts

@@ -0,0 +1,88 @@
+export interface SubmitPayload {
+    __interrupted: boolean;
+    __disposed?: boolean;
+    [field: string]: unknown;
+}
+export type ServerMessage<TSchema = unknown, TValues = unknown> = {
+    type: 'init' | 'reinit';
+    schema: TSchema;
+    state: TValues;
+} | {
+    type: 'update';
+    field: string;
+    value: unknown;
+} | CallMessage;
+export interface SetMessage {
+    type: 'set';
+    field: string;
+    value: unknown;
+}
+export interface SubmitMessage {
+    type: 'submit';
+}
+export interface InterruptMessage {
+    type: 'interrupt';
+}
+export interface ToolParamSpec {
+    type: 'string' | 'number' | 'boolean';
+    description?: string;
+    optional?: boolean;
+}
+/**
+ * The wire form of a manifest entry, as sent to the server in a
+ * RegisterToolsMessage. No function reference here — only JSON-serializable
+ * fields. The page keeps the actual function (see PageToolDef in
+ * client-bridge.ts) and dispatches on it locally when the server sends a
+ * CallMessage back by `name`.
+ */
+export interface ToolManifestEntry {
+    name: string;
+    description: string;
+    params: Record<string, ToolParamSpec>;
+    example?: Record<string, unknown>;
+}
+export interface RegisterToolsMessage {
+    type: 'register_tools';
+    tools: ToolManifestEntry[];
+    /**
+     * Optional page-authored context shared across all tools in this manifest:
+     * what kind of page/app this is, cross-tool sequencing rules ("call X
+     * before Y"), and any domain concepts an agent needs before calling
+     * individual tools blindly. Distinct from each tool's own `description` -
+     * this is manifest-level, told once, not repeated per tool. Surfaced to
+     * MCP clients via the `describe_tools` tool that createManifestToolRegistry
+     * auto-registers (see manifest-tools.ts) since it arrives after the
+     * McpServer is already constructed and can't be baked into static server
+     * `instructions`.
+     */
+    summary?: string;
+    /**
+     * Optional page-authored app identity (e.g. document.title or
+     * window.__mcpAppName). Used to disambiguate tool names and connections
+     * when a tenant has more than one live WS connection. Sanitized
+     * server-side into a slug; the raw value is only used as a display label.
+     */
+    appLabel?: string;
+}
+export interface CallMessage {
+    type: 'call';
+    id: string;
+    name: string;
+    args: unknown;
+}
+export interface CallResultMessage {
+    type: 'call_result';
+    id: string;
+    result?: unknown;
+    error?: string;
+}
+/**
+ * Renames an already-registered connection's display label (and therefore
+ * its tool-name prefix once re-slugged) without resending its whole
+ * manifest. Fire-and-forget, like RegisterToolsMessage - no ack.
+ */
+export interface RenameConnectionMessage {
+    type: 'rename_connection';
+    appLabel: string;
+}
+export type ClientMessage = SetMessage | SubmitMessage | InterruptMessage | RegisterToolsMessage | CallResultMessage | RenameConnectionMessage;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ws.d.ts

@@ -0,0 +1,3 @@
+import type { Server } from 'node:http';
+import { type WebSocket } from 'ws';
+export declare function attachWebSocketServer<TSchema, TValues>(httpServer: Server, port: number, initialSchema: TSchema, initialValues: TValues): import("ws").Server<typeof WebSocket, typeof import("http").IncomingMessage>;

package/dist/ws.js

@@ -0,0 +1,95 @@
+import { randomUUID } from 'node:crypto';
+import { WebSocketServer } from 'ws';
+import { getOrCreateTenant, tenants } from './tenant.js';
+/**
+ * Ping interval for the liveness check below. Half-open sockets (client
+ * process killed/suspended without a clean TCP close — the common case for
+ * a backgrounded browser tab or a harness that drops its child process)
+ * otherwise sit in `wsClients`/`connections` indefinitely: no 'close' event
+ * ever fires, so removeConnection() never runs and Tenant.call() keeps
+ * "succeeding" at sending into a socket that will never respond, running
+ * out the clock on its own 10s timeout instead of failing fast.
+ */
+const HEARTBEAT_INTERVAL_MS = 15_000;
+const heartbeatState = new WeakMap();
+export function attachWebSocketServer(httpServer, port, initialSchema, initialValues) {
+    const wss = new WebSocketServer({ server: httpServer, path: '/ws' });
+    const heartbeat = setInterval(() => {
+        for (const ws of wss.clients) {
+            const state = heartbeatState.get(ws);
+            if (state && !state.isAlive) {
+                console.error('[ws] heartbeat missed, terminating dead connection');
+                ws.terminate();
+                continue;
+            }
+            if (state)
+                state.isAlive = false;
+            ws.ping();
+        }
+    }, HEARTBEAT_INTERVAL_MS);
+    heartbeat.unref();
+    wss.on('close', () => clearInterval(heartbeat));
+    wss.on('connection', (ws, req) => {
+        const wsUrl = new URL(req.url ?? '/', `http://localhost:${port}`);
+        const requestedTenantId = wsUrl.searchParams.get('tenant');
+        if (requestedTenantId && !tenants.has(requestedTenantId)) {
+            // An explicit tenant was requested but no longer exists (for example
+            // because its MCP session was disposed). Reject instead of silently
+            // falling back to the shared default tenant.
+            console.error(`[ws] rejected connection: unknown/expired tenant "${requestedTenantId}"`);
+            ws.close(4404, 'Unknown or expired tenant');
+            return;
+        }
+        const tenantId = requestedTenantId || 'default';
+        const t = getOrCreateTenant(tenantId, initialSchema, initialValues);
+        const connectionId = randomUUID();
+        t.registerConnection(connectionId, ws);
+        console.error(`[ws] connection opened: tenant=${tenantId} connection=${connectionId} (${t.connections.size} connection(s) on tenant)`);
+        heartbeatState.set(ws, { isAlive: true });
+        ws.on('pong', () => {
+            const state = heartbeatState.get(ws);
+            if (state)
+                state.isAlive = true;
+        });
+        ws.send(JSON.stringify({ type: 'init', schema: t.schema, state: t.store.snapshot() }));
+        ws.on('message', (raw) => {
+            t.touch();
+            let msg;
+            try {
+                msg = JSON.parse(raw.toString());
+            }
+            catch {
+                return;
+            }
+            if (msg.type === 'set' && t.store.has(msg.field)) {
+                t.store.set(msg.field, msg.value);
+            }
+            if (msg.type === 'submit') {
+                t.submitBus.emit('submit', { __interrupted: false, ...t.store.snapshot() });
+            }
+            if (msg.type === 'interrupt') {
+                t.submitBus.emit('submit', { __interrupted: true, ...t.store.snapshot() });
+            }
+            if (msg.type === 'register_tools') {
+                t.updateConnectionManifest(connectionId, msg.tools, msg.summary, msg.appLabel);
+            }
+            if (msg.type === 'rename_connection') {
+                t.renameConnection(connectionId, msg.appLabel);
+            }
+            if (msg.type === 'call_result') {
+                if (msg.error)
+                    t.rejectCall(msg.id, msg.error);
+                else
+                    t.resolveCall(msg.id, msg.result);
+            }
+        });
+        ws.on('close', (code, reason) => {
+            console.error(`[ws] connection closed: tenant=${tenantId} connection=${connectionId} code=${code} reason=${reason.toString() || '(none)'}`);
+            t.removeConnection(connectionId);
+        });
+        ws.on('error', (err) => {
+            console.error(`[ws] connection error: tenant=${tenantId} connection=${connectionId}: ${err.message}`);
+        });
+    });
+    return wss;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "mcp-tenant-lib",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Generic tenant/session bookkeeping + MCP wiring, reusable across projects.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anatolipr/avo-mcp-tools.git",
+    "directory": "packages/mcp-tenant-lib"
+  },
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client-bridge.d.ts",
+      "default": "./dist/client-bridge.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "test": "node --import tsx --test test/**/*.test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "ws": "^8.18.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/ws": "^8.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}