mcp-tenant-lib 0.3.6 → 0.3.7

package/dist/dashboard.d.ts

@@ -0,0 +1,33 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export interface DashboardConnection {
+    id: string;
+    label: string | null;
+    toolCount: number;
+    summary: string | null;
+}
+export interface DashboardChannel {
+    channel: string;
+    lastActivityAt: number;
+    connections: DashboardConnection[];
+}
+/**
+ * Flat snapshot of every live tenant ("channel" in agent-facing language)
+ * and its connections — the same data list_channels/describe_channel expose
+ * to MCP tools, reshaped for a human-facing dashboard. Rebuilt fresh on
+ * every call rather than cached: cheap (iterates in-memory maps only), and
+ * avoids a second source of truth to keep in sync with `tenants`.
+ */
+export declare function buildDashboardSnapshot(): DashboardChannel[];
+/**
+ * Handles the three dashboard HTTP routes against a raw node http.Server,
+ * the same low-level style createHttpServer (http.ts) already uses (no
+ * Express dependency in this package). Returns true if the request was
+ * handled (caller should stop routing further), false if the path/method
+ * didn't match anything here.
+ *
+ * Mount this ahead of static file serving in the consuming package's own
+ * request handler, e.g.:
+ *
+ *   if (handleDashboardRoutes(req, res)) return;
+ */
+export declare function handleDashboardRoutes(req: IncomingMessage, res: ServerResponse, port: number): boolean;

package/dist/dashboard.js

@@ -0,0 +1,74 @@
+import { tenants, dashboardEvents } from './tenant.js';
+/**
+ * Flat snapshot of every live tenant ("channel" in agent-facing language)
+ * and its connections — the same data list_channels/describe_channel expose
+ * to MCP tools, reshaped for a human-facing dashboard. Rebuilt fresh on
+ * every call rather than cached: cheap (iterates in-memory maps only), and
+ * avoids a second source of truth to keep in sync with `tenants`.
+ */
+export function buildDashboardSnapshot() {
+    return [...tenants.entries()]
+        .map(([channel, t]) => ({
+        channel,
+        lastActivityAt: t.lastActivityAt,
+        connections: [...t.connections.values()].map((c) => ({
+            id: c.id,
+            label: c.label ?? null,
+            toolCount: c.manifest.length,
+            summary: c.summary ?? null,
+        })),
+    }))
+        .sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+}
+/**
+ * Handles the three dashboard HTTP routes against a raw node http.Server,
+ * the same low-level style createHttpServer (http.ts) already uses (no
+ * Express dependency in this package). Returns true if the request was
+ * handled (caller should stop routing further), false if the path/method
+ * didn't match anything here.
+ *
+ * Mount this ahead of static file serving in the consuming package's own
+ * request handler, e.g.:
+ *
+ *   if (handleDashboardRoutes(req, res)) return;
+ */
+export function handleDashboardRoutes(req, res, port) {
+    const url = new URL(req.url ?? '/', `http://localhost:${port}`);
+    if (url.pathname === '/api/dashboard' && req.method === 'GET') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(buildDashboardSnapshot()));
+        return true;
+    }
+    // Server-sent-events stream: pushes a fresh full snapshot immediately on
+    // connect, then again every time dashboardEvents fires (a connection
+    // opened/closed, a manifest changed, a channel was created/disposed) — see
+    // tenant.ts's notifyDashboard call sites. No diffing: the snapshot is
+    // small (one row per channel/connection) and a full replace is simpler
+    // and less bug-prone client-side than patching.
+    if (url.pathname === '/api/dashboard/stream' && req.method === 'GET') {
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+        });
+        const send = () => res.write(`data: ${JSON.stringify(buildDashboardSnapshot())}\n\n`);
+        send();
+        dashboardEvents.on('change', send);
+        req.on('close', () => dashboardEvents.off('change', send));
+        return true;
+    }
+    // Triggers identifyConnection on one connection — the dashboard's "which
+    // tab is this" button, same underlying mechanism as the identify_connection
+    // MCP tool (manifest-tools.ts), just reachable from a human clicking
+    // instead of an agent calling a tool.
+    const identifyMatch = url.pathname.match(/^\/api\/dashboard\/channels\/([^/]+)\/connections\/([^/]+)\/identify$/);
+    if (identifyMatch && req.method === 'POST') {
+        const [, channel, connectionId] = identifyMatch;
+        const t = tenants.get(decodeURIComponent(channel));
+        const ok = t?.identifyConnection(decodeURIComponent(connectionId)) ?? false;
+        res.writeHead(ok ? 200 : 404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok }));
+        return true;
+    }
+    return false;
+}

package/dist/http.d.ts

@@ -28,5 +28,20 @@ export interface CreateHttpServerOptions<TSchema, TValues> {
      *   to the previous one.
      */
     defaultTenantMode?: 'per-session' | 'shared';
+    /**
+     * Extra static asset roots served ahead of `staticDir`, keyed by URL path
+     * prefix. Two shapes:
+     *  - A directory-style prefix (e.g. `{ '/dashboard': '.../dist/dashboard' }`)
+     *    resolves requests under it relative to that directory, falling back
+     *    to `index.html` for the bare prefix or a `/`-suffixed request — same
+     *    convention as `staticDir`. Lets a consumer ship a second, independent
+     *    static app (e.g. a monitoring dashboard) without colliding with
+     *    `staticDir`'s own `index.html`.
+     *  - A single-file prefix with an extension (e.g. `{ '/main.js': '.../dist/client' }`)
+     *    serves exactly that one file (`dir/main.js`) for a request matching
+     *    the prefix exactly — for a fixed-URL asset other pages already
+     *    reference by that path regardless of what's mounted at `/`.
+     */
+    extraStaticMounts?: Record<string, string>;
 }
-export declare function createHttpServer<TSchema, TValues>({ port, staticDir, initialSchema, initialValues, identity, registerFn, defaultTenantMode }: CreateHttpServerOptions<TSchema, TValues>): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+export declare function createHttpServer<TSchema, TValues>({ port, staticDir, initialSchema, initialValues, identity, registerFn, defaultTenantMode, extraStaticMounts }: CreateHttpServerOptions<TSchema, TValues>): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;

package/dist/http.js

@@ -6,11 +6,18 @@ import { randomUUID } from 'node:crypto';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { getOrCreateTenant } from './tenant.js';
 import { buildMcpServer } from './mcp.js';
+import { handleDashboardRoutes } from './dashboard.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 mime = {
+    '.html': 'text/html',
+    '.js': 'text/javascript',
+    '.json': 'application/json',
+    '.css': 'text/css',
+    '.svg': 'image/svg+xml',
+};
 const sessions = new Map();
-export function createHttpServer({ port, staticDir, initialSchema, initialValues, identity, registerFn, defaultTenantMode = 'per-session' }) {
+export function createHttpServer({ port, staticDir, initialSchema, initialValues, identity, registerFn, defaultTenantMode = 'per-session', extraStaticMounts = {} }) {
     const getTenant = (id) => {
         const t = getOrCreateTenant(id, initialSchema, initialValues);
         t.touch();
@@ -96,6 +103,8 @@ export function createHttpServer({ port, staticDir, initialSchema, initialValues
             res.end('Unknown session');
             return;
         }
+        if (url.pathname.startsWith('/api/dashboard') && handleDashboardRoutes(req, res, port))
+            return;
         if (url.pathname === '/upload' && req.method === 'POST') {
             const contentType = req.headers['content-type'] ?? '';
             const boundaryMatch = contentType.match(/boundary=(.+)$/);
@@ -143,8 +152,27 @@ export function createHttpServer({ port, staticDir, initialSchema, initialValues
         if (pathname.startsWith('/t/')) {
             pathname = '/';
         }
-        let filePath = pathname === '/' ? '/index.html' : pathname;
-        filePath = path.join(staticDir, filePath);
+        const mountEntry = Object.entries(extraStaticMounts).find(([prefix]) => pathname === prefix || pathname.startsWith(`${prefix}/`));
+        let filePath;
+        if (mountEntry) {
+            const [prefix, dir] = mountEntry;
+            if (path.extname(prefix)) {
+                // A prefix with a file extension (e.g. "/main.js") is a single-file
+                // mount — `dir` is that file's parent directory, and any request
+                // exactly matching `prefix` resolves straight to it, no index.html
+                // fallback. Lets a consumer serve one fixed-URL asset (e.g. an
+                // embed script referenced by other pages as "<server>/main.js")
+                // from a build directory that also happens to hold other files.
+                filePath = path.join(dir, path.basename(prefix));
+            }
+            else {
+                const rest = pathname.slice(prefix.length);
+                filePath = path.join(dir, rest === '' || rest === '/' ? '/index.html' : rest);
+            }
+        }
+        else {
+            filePath = path.join(staticDir, pathname === '/' ? '/index.html' : pathname);
+        }
         fs.readFile(filePath, (err, data) => {
             if (err) {
                 res.writeHead(404);

package/dist/index.d.ts

@@ -1,8 +1,10 @@
-export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName } from './tenant.js';
+export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName, sanitizeChannelName, dashboardEvents } 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 { registerChannelTools } from './channel-tools.js';
+export { handleDashboardRoutes, buildDashboardSnapshot, type DashboardChannel, type DashboardConnection } from './dashboard.js';
 export { findChannelMatches, scoreChannelMatch, type ChannelMatch } from './channel-search.js';
+export { enablePersistence } from './persistence.js';
 export * from './types.js';

package/dist/index.js

@@ -1,8 +1,10 @@
-export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName } from './tenant.js';
+export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName, sanitizeChannelName, dashboardEvents } 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 { registerChannelTools } from './channel-tools.js';
+export { handleDashboardRoutes, buildDashboardSnapshot } from './dashboard.js';
 export { findChannelMatches, scoreChannelMatch } from './channel-search.js';
+export { enablePersistence } from './persistence.js';
 export * from './types.js';

package/dist/persistence.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Loads persisted tenant state from `filePath` (if present) and pre-seeds
+ * the shared `tenants` map with it *before* any getOrCreateTenant('default')
+ * call runs at boot — so a server restart comes back up with the last known
+ * form schema/values already in place instead of blank defaults, without
+ * requiring any browser tab to still be open to push a resync (see
+ * Tenant.restoreState in tenant.ts, which only helps if a tab survived the
+ * restart). Returns the set of tenant ids it seeded, purely for logging.
+ *
+ * Then wires a debounced save-on-change: any tenant currently in memory
+ * (present or created afterward) that mutates its store gets its next
+ * snapshot written back within WRITE_DEBOUNCE_MS. Polling `tenants`
+ * directly (rather than requiring every getOrCreateTenant call site to opt
+ * in) means callers of enablePersistence don't need to change how they
+ * create tenants elsewhere in the codebase.
+ */
+export declare function enablePersistence<TSchema, TValues>(filePath: string): {
+    seededIds: string[];
+};

package/dist/persistence.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Tenant, tenants } from './tenant.js';
+/**
+ * Debounce delay between a tenant edit and the write hitting disk. Keeps
+ * rapid-fire field edits (typing in a text input broadcasts on every
+ * keystroke) from turning into one fsync per keystroke, while staying well
+ * under any timeframe a user would notice as "my edit wasn't saved".
+ */
+const WRITE_DEBOUNCE_MS = 500;
+/**
+ * Loads persisted tenant state from `filePath` (if present) and pre-seeds
+ * the shared `tenants` map with it *before* any getOrCreateTenant('default')
+ * call runs at boot — so a server restart comes back up with the last known
+ * form schema/values already in place instead of blank defaults, without
+ * requiring any browser tab to still be open to push a resync (see
+ * Tenant.restoreState in tenant.ts, which only helps if a tab survived the
+ * restart). Returns the set of tenant ids it seeded, purely for logging.
+ *
+ * Then wires a debounced save-on-change: any tenant currently in memory
+ * (present or created afterward) that mutates its store gets its next
+ * snapshot written back within WRITE_DEBOUNCE_MS. Polling `tenants`
+ * directly (rather than requiring every getOrCreateTenant call site to opt
+ * in) means callers of enablePersistence don't need to change how they
+ * create tenants elsewhere in the codebase.
+ */
+export function enablePersistence(filePath) {
+    const seededIds = [];
+    let persisted = {};
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        persisted = JSON.parse(raw);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            console.error(`[persistence] failed to read ${filePath}: ${err.message}`);
+        }
+    }
+    for (const [id, state] of Object.entries(persisted)) {
+        if (tenants.has(id))
+            continue;
+        const tenant = new Tenant(id, state.schema, state.values);
+        tenant.submitted = state.submitted;
+        tenant.lastStateChangeAt = state.lastStateChangeAt;
+        tenant.lastActivityAt = state.lastActivityAt;
+        tenants.set(id, tenant);
+        seededIds.push(id);
+    }
+    const writeToDisk = () => {
+        const out = {};
+        for (const [id, tenant] of tenants) {
+            out[id] = {
+                schema: tenant.schema,
+                values: tenant.store.snapshot(),
+                submitted: tenant.submitted,
+                lastStateChangeAt: tenant.lastStateChangeAt,
+                lastActivityAt: tenant.lastActivityAt,
+            };
+        }
+        try {
+            fs.mkdirSync(path.dirname(filePath), { recursive: true });
+            fs.writeFileSync(filePath, JSON.stringify(out));
+        }
+        catch (err) {
+            console.error(`[persistence] failed to write ${filePath}: ${err.message}`);
+        }
+    };
+    // Polls `lastStateChangeAt` (bumped on every real store edit or applied
+    // resync — see Tenant#attachStore/restoreState) rather than subscribing
+    // to each tenant's `store.onChange`, since define_form/resync/reconnect
+    // all replace `tenant.store` with a brand-new Store (Tenant#attachStore),
+    // which would silently drop a direct subscription. Polling at the same
+    // cadence as the write debounce means a change is never more than one
+    // interval late to be noticed, and comparing against a per-tenant
+    // last-seen timestamp keeps this a no-op when nothing changed.
+    const seen = new Map();
+    for (const [id, tenant] of tenants)
+        seen.set(id, tenant.lastStateChangeAt);
+    const pollInterval = setInterval(() => {
+        let dirty = false;
+        for (const [id, tenant] of tenants) {
+            if (seen.get(id) !== tenant.lastStateChangeAt) {
+                seen.set(id, tenant.lastStateChangeAt);
+                dirty = true;
+            }
+        }
+        for (const id of seen.keys()) {
+            if (!tenants.has(id)) {
+                seen.delete(id);
+                dirty = true;
+            } // tenant disposed (idle sweep)
+        }
+        if (dirty)
+            writeToDisk();
+    }, WRITE_DEBOUNCE_MS);
+    pollInterval.unref();
+    return { seededIds };
+}

package/dist/tenant.d.ts

@@ -1,6 +1,17 @@
 import { EventEmitter } from 'node:events';
 import type { WebSocket } from 'ws';
 import type { ToolManifestEntry } from './types.js';
+/**
+ * Fires whenever the *shape* of the tenants map changes in a way a
+ * dashboard/monitoring view would care about: a tenant created/disposed, a
+ * connection opening/closing, or a connection's manifest/label changing.
+ * Deliberately does NOT fire on ordinary state (Store) changes or waiting/
+ * submitted flips — those are per-tenant form data, not "who's connected."
+ * One process-wide emitter (not per-tenant) so a single dashboard SSE
+ * stream can subscribe once for every channel rather than one listener per
+ * tenant. See dashboard.ts for the consumer.
+ */
+export declare const dashboardEvents: EventEmitter<[never]>;
 /**
  * One WS connection's own tool manifest/summary/label, addressable
  * independently of other connections sharing the same tenant (e.g. two
@@ -181,8 +192,24 @@ export declare class Tenant<TSchema, TValues> {
  * rejected up front rather than silently mangled.
  */
 declare function isValidChannelName(id: string): boolean;
+/**
+ * Best-effort fixup for a browser-supplied channel name that fails
+ * isValidChannelName — collapses any run of disallowed characters (spaces,
+ * punctuation, etc.) into a single underscore and trims leading/trailing
+ * underscores, e.g. "bulletino 222aaa" -> "bulletino_222aaa". Used only on
+ * the WS connect path (ws.ts): a human renaming a bridged tab via a plain
+ * `prompt()` has no reason to know or care about the exact slug rule, so
+ * silently coercing their input into something valid is friendlier than a
+ * hard 4404 reject with no recovery. Deliberately NOT applied to
+ * join_channel (channel-tools.ts) — that's agent-driven, the tool
+ * description already states the rule up front, and an agent silently
+ * landing on a DIFFERENT name than it asked for is more likely to cause
+ * confusion (e.g. mismatched describe_channel lookups) than a clear
+ * rejection it can self-correct from.
+ */
+declare function sanitizeChannelName(id: string): string;
 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, isValidChannelName };
+export { tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName, sanitizeChannelName };

package/dist/tenant.js

@@ -1,5 +1,20 @@
 import { EventEmitter } from 'node:events';
 import { randomUUID } from 'node:crypto';
+/**
+ * Fires whenever the *shape* of the tenants map changes in a way a
+ * dashboard/monitoring view would care about: a tenant created/disposed, a
+ * connection opening/closing, or a connection's manifest/label changing.
+ * Deliberately does NOT fire on ordinary state (Store) changes or waiting/
+ * submitted flips — those are per-tenant form data, not "who's connected."
+ * One process-wide emitter (not per-tenant) so a single dashboard SSE
+ * stream can subscribe once for every channel rather than one listener per
+ * tenant. See dashboard.ts for the consumer.
+ */
+export const dashboardEvents = new EventEmitter();
+dashboardEvents.setMaxListeners(0);
+function notifyDashboard() {
+    dashboardEvents.emit('change');
+}
 /**
  * How long Tenant.call waits for some connection to reappear on a tenant
  * before giving up, when the connection it was targeting has already
@@ -144,6 +159,7 @@ export class Tenant {
     registerConnection(id, socket) {
         this.connections.set(id, { id, socket, manifest: [], summary: undefined, label: undefined });
         this.wsClients.add(socket);
+        notifyDashboard();
     }
     updateConnectionManifest(id, manifest, summary, label) {
         const conn = this.connections.get(id);
@@ -174,6 +190,7 @@ export class Tenant {
             this.wsClients.delete(conn.socket);
         this.connections.delete(id);
         this.syncManifestToolRegistries();
+        notifyDashboard();
     }
     addManifestToolRegistry(registry) {
         this.#manifestToolRegistries.add(registry);
@@ -185,6 +202,7 @@ export class Tenant {
     syncManifestToolRegistries() {
         for (const registry of this.#manifestToolRegistries)
             registry.sync();
+        notifyDashboard();
     }
     /**
      * `connectionId` targets the call at one specific connection's socket —
@@ -395,18 +413,38 @@ export class Tenant {
 function isValidChannelName(id) {
     return /^[a-zA-Z0-9_-]+$/.test(id);
 }
+/**
+ * Best-effort fixup for a browser-supplied channel name that fails
+ * isValidChannelName — collapses any run of disallowed characters (spaces,
+ * punctuation, etc.) into a single underscore and trims leading/trailing
+ * underscores, e.g. "bulletino 222aaa" -> "bulletino_222aaa". Used only on
+ * the WS connect path (ws.ts): a human renaming a bridged tab via a plain
+ * `prompt()` has no reason to know or care about the exact slug rule, so
+ * silently coercing their input into something valid is friendlier than a
+ * hard 4404 reject with no recovery. Deliberately NOT applied to
+ * join_channel (channel-tools.ts) — that's agent-driven, the tool
+ * description already states the rule up front, and an agent silently
+ * landing on a DIFFERENT name than it asked for is more likely to cause
+ * confusion (e.g. mismatched describe_channel lookups) than a clear
+ * rejection it can self-correct from.
+ */
+function sanitizeChannelName(id) {
+    return id.replace(/[^a-zA-Z0-9_-]+/g, '_').replace(/^_+|_+$/g, '');
+}
 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);
+        notifyDashboard();
     }
     return tenant;
 }
 function disposeTenant(id) {
     tenants.get(id)?.dispose();
     tenants.delete(id);
+    notifyDashboard();
 }
 function envMs(name, defaultMs) {
     const raw = process.env[name];
@@ -432,4 +470,4 @@ function startIdleSweep(onSweep) {
     sweepInterval.unref();
     return sweepInterval;
 }
-export { tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName };
+export { tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName, sanitizeChannelName };

package/dist/ws.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { WebSocketServer } from 'ws';
-import { getOrCreateTenant, tenants, isValidChannelName } from './tenant.js';
+import { getOrCreateTenant, tenants, isValidChannelName, sanitizeChannelName } 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
@@ -31,13 +31,22 @@ export function attachWebSocketServer(httpServer, port, initialSchema, initialVa
     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');
+        let requestedTenantId = wsUrl.searchParams.get('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;
+            // A browser-supplied name (e.g. a human renaming a bridged tab via a
+            // plain prompt()) has no reason to know the slug rule — coerce it
+            // into something valid rather than rejecting outright, same as
+            // join_channel would reject a raw name but this WS path favors
+            // recovering the connection. Only a genuinely empty result (every
+            // character was disallowed) still gets rejected below.
+            const sanitized = sanitizeChannelName(requestedTenantId);
+            if (!sanitized) {
+                console.error(`[ws] rejected connection: invalid tenant id "${requestedTenantId}" (nothing left after sanitizing)`);
+                ws.close(4404, 'Invalid tenant id');
+                return;
+            }
+            console.error(`[ws] sanitized invalid tenant id "${requestedTenantId}" -> "${sanitized}"`);
+            requestedTenantId = sanitized;
         }
         const tenantId = requestedTenantId || 'default';
         const recreated = !!requestedTenantId && !tenants.has(requestedTenantId);

package/package.json

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