mcp-tenant-lib 0.3.3 → 0.3.4

package/dist/channel-tools.js

@@ -34,9 +34,17 @@ export function registerChannelTools(mcp, tenant, port, setChannel, initialSchem
     mcp.tool('list_channels', 'Lists every channel currently live on this server, including "default" (the shared, anonymous channel ' +
         'sessions land on before calling join_channel). Use this to discover an existing named channel before ' +
         'calling join_channel on it, e.g. when a human refers to "the pets form" without giving the exact channel ' +
-        'name.', {}, async () => {
-        const ids = [...tenants.keys()];
-        return { content: [{ type: 'text', text: JSON.stringify(ids, null, 2) }] };
+        'name. Each entry includes a `connections` array — one item per live browser tab/page bridged into that ' +
+        'channel, with its display `label` and `toolCount` — so you can tell which channels actually have ' +
+        'something connected without joining each one to check.', {}, async () => {
+        const channels = [...tenants.entries()].map(([channel, t]) => ({
+            channel,
+            connections: [...t.connections.values()].map((c) => ({
+                label: c.label ?? null,
+                toolCount: c.manifest.length,
+            })),
+        }));
+        return { content: [{ type: 'text', text: JSON.stringify(channels, null, 2) }] };
     });
     mcp.tool('channel_find', 'Fuzzy-searches existing channel names for ones matching a loose query — use this when a human refers to ' +
         'a channel by topic or partial name (e.g. "the pets channel") rather than its exact name, instead of ' +

package/dist/client-bridge.d.ts

@@ -36,6 +36,8 @@ export interface StateSocketHandlers<TSchema, TValues> {
     onCall?(id: string, name: string, args: unknown): void;
     onConnect?(): void;
     onDisconnect?(): void;
+    /** Server-pushed "identify yourself" signal (see identify_connection tool). Defaults to a window.alert(). */
+    onIdentify?(label: string | undefined): void;
 }
 export interface StateSocketOptions {
     /**

package/dist/client-bridge.js

@@ -30,10 +30,22 @@ export function createClientBridge(actions) {
         },
     };
 }
+/** Steady-state delay between reconnect attempts once the connection drops. */
+const RECONNECT_INTERVAL_MS = 10_000;
+/**
+ * How long to keep retrying at RECONNECT_INTERVAL_MS before giving up
+ * entirely. A dropped connection is usually the server restarting (or a
+ * laptop sleeping) rather than something permanent, and unknown named
+ * tenants are now recreated on demand server-side (see ws.ts) rather than
+ * rejected — so it's worth retrying for a long while rather than a few
+ * seconds, without retrying literally forever if the server is gone for good.
+ */
+const RECONNECT_GIVE_UP_MS = 60 * 60 * 1000;
 export function connectStateSocket(handlers, options = {}) {
     let ws;
     let closedByCaller = false;
     let reconnectAttempts = 0;
+    let firstDisconnectAt;
     const connect = () => {
         const tenantId = options.tenant ?? (location.pathname.startsWith('/t/')
             ? location.pathname.slice('/t/'.length).split('/')[0]
@@ -48,6 +60,7 @@ export function connectStateSocket(handlers, options = {}) {
         ws.onopen = () => {
             console.log(`[mcp-ws] connected${reconnectAttempts > 0 ? ` after ${reconnectAttempts} reconnect attempt(s)` : ''}`);
             reconnectAttempts = 0;
+            firstDisconnectAt = undefined;
             handlers.onConnect?.();
         };
         ws.onclose = (event) => {
@@ -56,12 +69,17 @@ export function connectStateSocket(handlers, options = {}) {
             if (closedByCaller)
                 return;
             if (event.code === 4404) {
-                console.log('[mcp-ws] tenant unknown/expired (4404) — not retrying');
+                console.log('[mcp-ws] invalid tenant id (4404) — not retrying');
+                return;
+            }
+            firstDisconnectAt ??= Date.now();
+            if (Date.now() - firstDisconnectAt > RECONNECT_GIVE_UP_MS) {
+                console.log(`[mcp-ws] giving up after retrying for over ${RECONNECT_GIVE_UP_MS / 60_000} minutes`);
                 return;
             }
             reconnectAttempts++;
-            console.log(`[mcp-ws] retrying in 2s (attempt ${reconnectAttempts + 1})`);
-            setTimeout(connect, 2000);
+            console.log(`[mcp-ws] retrying in ${RECONNECT_INTERVAL_MS / 1000}s (attempt ${reconnectAttempts + 1})`);
+            setTimeout(connect, RECONNECT_INTERVAL_MS);
         };
         ws.onerror = () => {
             console.log('[mcp-ws] socket error (see close event for details)');
@@ -76,6 +94,12 @@ export function connectStateSocket(handlers, options = {}) {
                 handlers.onUpdate?.(msg.field, msg.value);
             if (msg.type === 'call')
                 handlers.onCall?.(msg.id, msg.name, msg.args);
+            if (msg.type === 'identify') {
+                if (handlers.onIdentify)
+                    handlers.onIdentify(msg.label);
+                else
+                    alert(`Identify: this is the "${msg.label ?? 'unlabeled'}" connection`);
+            }
         };
     };
     connect();

package/dist/manifest-tools.js

@@ -25,6 +25,12 @@ function manifestEntryToZodShape(entry) {
     return shape;
 }
 const DESCRIBE_TOOLS_NAME = 'describe_tools';
+const IDENTIFY_CONNECTION_NAME = 'identify_connection';
+const IDENTIFY_CONNECTION_DESCRIPTION = 'Pops an alert in the browser tab behind one connection, so a human looking at several open tabs/windows ' +
+    'can tell which one this session means. Use when the user has multiple tabs bridged in and asks "which one ' +
+    'is X" or you need them to look at a specific one. Pass the connection `id` from describe_tools\' ' +
+    '`connections` array (single-connection channels can omit it). Fire-and-forget: returns immediately, does ' +
+    'not confirm the human saw it.';
 const DESCRIBE_TOOLS_DESCRIPTION = 'Returns manifest-level context for the tools connected to THIS SESSION\'S CURRENT CHANNEL: 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 ' +
@@ -111,6 +117,24 @@ export function createManifestToolRegistry(mcp, tenant) {
         });
         handles.set(DESCRIBE_TOOLS_NAME, handle);
     }
+    function registerIdentifyConnection() {
+        const handle = mcp.registerTool(IDENTIFY_CONNECTION_NAME, {
+            description: IDENTIFY_CONNECTION_DESCRIPTION,
+            inputSchema: { id: z.string().optional().describe('Connection id from describe_tools\' `connections` array. Omit when only one connection is live.') },
+        }, async ({ id }) => {
+            const t = tenant();
+            const targetId = id ?? [...t.connections.keys()][0];
+            if (!targetId) {
+                return { content: [{ type: 'text', text: 'No live connection on this channel to identify.' }], isError: true };
+            }
+            const ok = t.identifyConnection(targetId);
+            return {
+                content: [{ type: 'text', text: ok ? `Identify signal sent to connection "${targetId}".` : `Connection "${targetId}" is not currently open.` }],
+                isError: !ok,
+            };
+        });
+        handles.set(IDENTIFY_CONNECTION_NAME, handle);
+    }
     function sync() {
         const conns = [...tenant().connections.values()];
         const multi = conns.length >= 2;
@@ -122,7 +146,7 @@ export function createManifestToolRegistry(mcp, tenant) {
         if (multi) {
             for (const conn of conns) {
                 for (const entry of conn.manifest) {
-                    if (entry.name === DESCRIBE_TOOLS_NAME)
+                    if (entry.name === DESCRIBE_TOOLS_NAME || entry.name === IDENTIFY_CONNECTION_NAME)
                         continue;
                     registeredNow.set(`${slugFor.get(conn.id)}__${entry.name}`, { connectionId: conn.id, entry });
                 }
@@ -131,14 +155,15 @@ export function createManifestToolRegistry(mcp, tenant) {
         else {
             const conn = conns[0];
             for (const entry of tenant().toolManifest) {
-                if (entry.name === DESCRIBE_TOOLS_NAME)
+                if (entry.name === DESCRIBE_TOOLS_NAME || entry.name === IDENTIFY_CONNECTION_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()]);
+        // Page tools named "describe_tools"/"identify_connection" would collide
+        // with the fixed tools below - the fixed ones always win so agents can
+        // rely on the name.
+        const currentNames = new Set([DESCRIBE_TOOLS_NAME, IDENTIFY_CONNECTION_NAME, ...registeredNow.keys()]);
         for (const [name, handle] of handles) {
             if (!currentNames.has(name)) {
                 handle.remove();
@@ -147,6 +172,8 @@ export function createManifestToolRegistry(mcp, tenant) {
         }
         if (!handles.has(DESCRIBE_TOOLS_NAME))
             registerDescribeTools();
+        if (!handles.has(IDENTIFY_CONNECTION_NAME))
+            registerIdentifyConnection();
         for (const [registeredName, { connectionId, entry }] of registeredNow) {
             if (handles.has(registeredName))
                 continue;

package/dist/tenant.d.ts

@@ -127,6 +127,14 @@ export declare class Tenant<TSchema, TValues> {
      * self-contained and cheap for the rare/short-lived window it's used in.
      */
     private waitForReconnect;
+    /**
+     * Pushes an 'identify' message at one connection so its page can surface
+     * something a human watching the browser will notice (alert/sound) — lets
+     * an agent say "which tab is this" when several are bridged into one
+     * channel. Fire-and-forget like rename_connection: no ack, and silently
+     * a no-op if the connection has since closed.
+     */
+    identifyConnection(connectionId: string): boolean;
     resolveCall(id: string, result: unknown): void;
     rejectCall(id: string, error: string): void;
     touch(): void;

package/dist/tenant.js

@@ -261,6 +261,20 @@ export class Tenant {
             poll();
         });
     }
+    /**
+     * Pushes an 'identify' message at one connection so its page can surface
+     * something a human watching the browser will notice (alert/sound) — lets
+     * an agent say "which tab is this" when several are bridged into one
+     * channel. Fire-and-forget like rename_connection: no ack, and silently
+     * a no-op if the connection has since closed.
+     */
+    identifyConnection(connectionId) {
+        const conn = this.connections.get(connectionId);
+        if (!conn || conn.socket.readyState !== conn.socket.OPEN)
+            return false;
+        conn.socket.send(JSON.stringify({ type: 'identify', label: conn.label }));
+        return true;
+    }
     resolveCall(id, result) {
         const pending = this.pendingCalls.get(id);
         if (!pending)

package/dist/types.d.ts

@@ -16,6 +16,9 @@ export type ServerMessage<TSchema = unknown, TValues = unknown> = {
 } | {
     type: 'waiting';
     waiting: boolean;
+} | {
+    type: 'identify';
+    label?: string;
 } | CallMessage;
 export interface SetMessage {
     type: 'set';

package/dist/ws.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { WebSocketServer } from 'ws';
-import { getOrCreateTenant, tenants } from './tenant.js';
+import { getOrCreateTenant, tenants, isValidChannelName } 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
@@ -32,16 +32,25 @@ export function attachWebSocketServer(httpServer, port, initialSchema, initialVa
     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');
+        if (requestedTenantId && !isValidChannelName(requestedTenantId)) {
+            // Never silently vivify a channel from a malformed/hostile id — same
+            // validation join_channel applies agent-side.
+            console.error(`[ws] rejected connection: invalid tenant id "${requestedTenantId}"`);
+            ws.close(4404, 'Invalid tenant id');
             return;
         }
         const tenantId = requestedTenantId || 'default';
+        const recreated = !!requestedTenantId && !tenants.has(requestedTenantId);
         const t = getOrCreateTenant(tenantId, initialSchema, initialValues);
+        if (recreated) {
+            // A page reconnecting (browser retry loop) to a named channel that no
+            // longer exists server-side — most commonly a server restart, which
+            // wipes the in-memory tenants map entirely. Recreate it on demand
+            // rather than rejecting, so the page keeps working and an agent can
+            // rejoin the same name later instead of the connection being stuck
+            // retrying forever against a channel the server will never revive.
+            console.error(`[ws] recreated previously unknown/expired tenant "${tenantId}" on reconnect`);
+        }
         const connectionId = randomUUID();
         t.registerConnection(connectionId, ws);
         console.error(`[ws] connection opened: tenant=${tenantId} connection=${connectionId} (${t.connections.size} connection(s) on tenant)`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-tenant-lib",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "type": "module",
   "description": "Generic tenant/session bookkeeping + MCP wiring, reusable across projects.",
   "repository": {