mcp-tenant-lib 0.1.1 → 0.3.3

package/dist/channel-search.d.ts

@@ -0,0 +1,17 @@
+export interface ChannelMatch {
+    name: string;
+    score: number;
+}
+/**
+ * Scores one candidate channel name against a query, case-insensitively:
+ * the best of (a) whole-string typo tolerance, (b) whole-string stem match,
+ * and (c) the best per-word score against the candidate's underscore/
+ * hyphen-split words (catches "pets" -> "pet_food_memory" via "pet", and
+ * "pests" -> "pets_discussion" via a length-gated typo match on "pets").
+ */
+export declare function scoreChannelMatch(query: string, candidate: string): number;
+/**
+ * Ranks every candidate against the query, highest score first, keeping
+ * only matches above `minScore` (default 0.5).
+ */
+export declare function findChannelMatches(query: string, candidates: string[], minScore?: number): ChannelMatch[];

package/dist/channel-search.js

@@ -0,0 +1,80 @@
+import { distance } from 'fastest-levenshtein';
+/**
+ * Splits a channel name into its underscore/hyphen-delimited words, e.g.
+ * "pet_food_memory" -> ["pet", "food", "memory"]. Used so a query like
+ * "pets" can match "pet_food_memory" via the shared word "pet" even though
+ * the two full strings have a large edit distance overall.
+ */
+function words(name) {
+    return name.split(/[_-]+/).filter(Boolean);
+}
+/**
+ * Typo-tolerance score for two strings of similar length/spelling — 1 for
+ * identical, decreasing with edit distance relative to length. This is
+ * deliberately NOT used to compare unrelated short words against each other
+ * (see stemScore) — two coincidentally-similar-length words like "pets" and
+ * "prefs" have a small edit distance purely by chance, which this alone
+ * cannot tell apart from an actual typo of the same word.
+ */
+function typoScore(a, b) {
+    const maxLen = Math.max(a.length, b.length);
+    if (maxLen === 0)
+        return 1;
+    return 1 - distance(a, b) / maxLen;
+}
+/**
+ * Stem/prefix match score: how much of the shorter string is a literal
+ * prefix of the longer one, e.g. "pet" is a full-length prefix of "pets" ->
+ * strong match. Zero if neither is a prefix of the other at all — this is
+ * an intentionally strict, high-precision signal (no edit-distance fuzz),
+ * so it doesn't fire on coincidences the way typoScore can.
+ */
+function stemScore(a, b) {
+    const [shorter, longer] = a.length <= b.length ? [a, b] : [b, a];
+    if (shorter.length < 3 || !longer.startsWith(shorter))
+        return 0;
+    return shorter.length / longer.length;
+}
+/**
+ * Per-word score: the best of a strict stem match (see stemScore) and a
+ * typo-tolerant match that only kicks in when the query and word are close
+ * enough in length that a real typo is plausible (within 2 characters) —
+ * this catches "pests" -> "pets" (one transposed letter, same length).
+ * Known limitation: two short, unrelated, similar-length words (e.g.
+ * "pets" vs "prefs") can still score moderately via this path — there's no
+ * algorithmic way to distinguish "typo of the same word" from "coincidence"
+ * at that length. In practice this only surfaces as a low-ranked also-ran
+ * behind any genuine stem match, and callers (see channel-tools.ts's
+ * channel_find description) are told to disambiguate on close scores
+ * rather than blindly trust the top result.
+ */
+function wordScore(query, word) {
+    const stem = stemScore(query, word);
+    if (Math.abs(query.length - word.length) > 2)
+        return stem;
+    return Math.max(stem, typoScore(query, word));
+}
+/**
+ * Scores one candidate channel name against a query, case-insensitively:
+ * the best of (a) whole-string typo tolerance, (b) whole-string stem match,
+ * and (c) the best per-word score against the candidate's underscore/
+ * hyphen-split words (catches "pets" -> "pet_food_memory" via "pet", and
+ * "pests" -> "pets_discussion" via a length-gated typo match on "pets").
+ */
+export function scoreChannelMatch(query, candidate) {
+    const q = query.toLowerCase();
+    const c = candidate.toLowerCase();
+    const whole = Math.max(typoScore(q, c), stemScore(q, c));
+    const perWord = words(c).map((w) => wordScore(q, w));
+    return Math.max(whole, ...perWord, 0);
+}
+/**
+ * Ranks every candidate against the query, highest score first, keeping
+ * only matches above `minScore` (default 0.5).
+ */
+export function findChannelMatches(query, candidates, minScore = 0.5) {
+    return candidates
+        .map((name) => ({ name, score: scoreChannelMatch(query, name) }))
+        .filter((m) => m.score >= minScore)
+        .sort((a, b) => b.score - a.score);
+}

package/dist/channel-tools.d.ts

@@ -0,0 +1,12 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Tenant } from './tenant.js';
+/**
+ * Registers `join_channel` and `list_channels` on an MCP server built via
+ * buildMcpServer. Shared across every mcp-tenant-lib consumer (mcp-form,
+ * js-bridge-mcp, ...) so the tool behavior/wording stays identical rather
+ * than reimplemented per package.
+ *
+ * `tenant`/`setChannel`/`port` are exactly what registerFn (see mcp.ts)
+ * receives — pass them straight through from there.
+ */
+export declare function registerChannelTools<TSchema, TValues>(mcp: McpServer, tenant: () => Tenant<TSchema, TValues>, port: number, setChannel: (id: string) => void, initialSchema: TSchema, initialValues: TValues): void;

package/dist/channel-tools.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { tenants, getOrCreateTenant, isValidChannelName } from './tenant.js';
+import { findChannelMatches } from './channel-search.js';
+/**
+ * Registers `join_channel` and `list_channels` on an MCP server built via
+ * buildMcpServer. Shared across every mcp-tenant-lib consumer (mcp-form,
+ * js-bridge-mcp, ...) so the tool behavior/wording stays identical rather
+ * than reimplemented per package.
+ *
+ * `tenant`/`setChannel`/`port` are exactly what registerFn (see mcp.ts)
+ * receives — pass them straight through from there.
+ */
+export function registerChannelTools(mcp, tenant, port, setChannel, initialSchema, initialValues) {
+    mcp.tool('join_channel', 'Names (or rejoins) a channel: a persistent, agent-chosen identity for this session\'s live state, shared ' +
+        'with any other session that joins the same name. DEFAULT TO CALLING THIS as one of your first actions, ' +
+        'with a name derived from the topic at hand (e.g. a request about "pets" → join_channel("pets")) — not ' +
+        'something reserved for when you happen to think of it. Until called, a session sits on the shared, ' +
+        'anonymous "default" channel, visible to every other unnamed session on this server — skip only when the ' +
+        'user says it\'s a one-off/throwaway, or nothing suggests a distinct topic worth naming. Reusing an ' +
+        'existing name is expected, not an error: it retargets this session onto that channel\'s live state (e.g. ' +
+        'to resume, or redefine/refresh it). Names are URL-safe slugs: letters, digits, underscore, hyphen only.', { channel: z.string().describe('Agent-chosen channel name, e.g. "pets" or "pet_questions_1_of_2". Letters/digits/underscore/hyphen only.') }, async ({ channel }) => {
+        if (!isValidChannelName(channel)) {
+            return {
+                content: [{ type: 'text', text: `Error: "${channel}" is not a valid channel name — use only letters, digits, underscore, and hyphen.` }],
+                isError: true,
+            };
+        }
+        getOrCreateTenant(channel, initialSchema, initialValues);
+        setChannel(channel);
+        return {
+            content: [{ type: 'text', text: `Joined channel "${channel}" — http://localhost:${port}/t/${channel}` }],
+        };
+    });
+    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) }] };
+    });
+    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 ' +
+        'guessing at join_channel or falling back to eyeballing the full list_channels output yourself. Matches on ' +
+        'both whole-name similarity (catches typos) and per-word similarity against underscore/hyphen-split parts ' +
+        'of each name (catches "pets" matching "pet_food_memory" via the shared word "pet"). Returns a ranked list ' +
+        'of {name, score} (score 0..1, higher is better) — empty if nothing scores above the threshold. Read-only: ' +
+        'does NOT join or create anything, even on an exact match. Given the result(s), call join_channel yourself ' +
+        'on whichever one is actually right — if there\'s one clear best match, use it directly; if several score ' +
+        'closely, ask the user to disambiguate rather than guessing.', { query: z.string().describe('Loose/partial channel name or topic to search for, e.g. "pets".') }, async ({ query }) => {
+        const matches = findChannelMatches(query, [...tenants.keys()]);
+        return { content: [{ type: 'text', text: JSON.stringify(matches, null, 2) }] };
+    });
+}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep } from './tenant.js';
+export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName } 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 { findChannelMatches, scoreChannelMatch, type ChannelMatch } from './channel-search.js';
 export * from './types.js';

package/dist/index.js

@@ -1,6 +1,8 @@
-export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep } from './tenant.js';
+export { Store, Tenant, tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName } 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 { findChannelMatches, scoreChannelMatch } from './channel-search.js';
 export * from './types.js';

package/dist/manifest-tools.js

@@ -25,7 +25,7 @@ function manifestEntryToZodShape(entry) {
     return shape;
 }
 const DESCRIBE_TOOLS_NAME = 'describe_tools';
-const DESCRIBE_TOOLS_DESCRIPTION = 'Returns manifest-level context for the tools this connected page registered: a ' +
+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 ' +
     'this once after connecting, before calling any other tool from this page, so you have ' +
@@ -33,7 +33,11 @@ const DESCRIBE_TOOLS_DESCRIPTION = 'Returns manifest-level context for the tools
     '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.';
+    'prefix — call it whenever you\'re unsure which prefix routes to which tab. ' +
+    'IMPORTANT — an empty or unexpected result here does NOT mean no page is bridged: this session may ' +
+    'simply be on the wrong channel (see join_channel). If the user expects a specific bridged app/page by ' +
+    'name (e.g. "the bulletino tab") and it\'s missing, call list_channels to check for a matching channel ' +
+    'and join_channel to it before assuming nothing is connected.';
 /**
  * Derives a stable, unique tool-name prefix per connection: sanitized from
  * `label` (falling back to "tab" when absent or empty after sanitizing),

package/dist/mcp.d.ts

@@ -1,8 +1,17 @@
 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 type RegisterToolsFn<TSchema = any, TValues = any> = (mcp: McpServer, tenant: () => Tenant<TSchema, TValues>, port: number, setChannel: (id: string) => void) => void;
 export interface McpServerIdentity {
     name: string;
     version: string;
 }
+/**
+ * `tenantId` is only the session's bootstrap identity — a private id minted
+ * before any tool call has happened, so before an agent could have chosen a
+ * channel name (see channel-tools.ts). It is NOT fixed for the session's
+ * lifetime: `setChannel` (passed into `registerFn`, typically wired to a
+ * `join_channel` tool) reassigns which tenant `tenant()` resolves to from
+ * that point on, so a session can retarget itself onto an agent-named,
+ * cross-session-shared channel after connecting.
+ */
 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

@@ -1,7 +1,18 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * `tenantId` is only the session's bootstrap identity — a private id minted
+ * before any tool call has happened, so before an agent could have chosen a
+ * channel name (see channel-tools.ts). It is NOT fixed for the session's
+ * lifetime: `setChannel` (passed into `registerFn`, typically wired to a
+ * `join_channel` tool) reassigns which tenant `tenant()` resolves to from
+ * that point on, so a session can retarget itself onto an agent-named,
+ * cross-session-shared channel after connecting.
+ */
 export function buildMcpServer(identity, tenantId, getTenant, port, registerFn) {
     const mcp = new McpServer(identity);
-    const tenant = () => getTenant(tenantId);
-    registerFn(mcp, tenant, port);
+    let currentTenantId = tenantId;
+    const tenant = () => getTenant(currentTenantId);
+    const setChannel = (id) => { currentTenantId = id; };
+    registerFn(mcp, tenant, port, setChannel);
     return mcp;
 }

package/dist/tenant.d.ts

@@ -36,6 +36,26 @@ export declare class Tenant<TSchema, TValues> {
     schema: TSchema;
     store: Store<TValues>;
     submitBus: EventEmitter;
+    /**
+     * Whether some caller currently has a `submitBus.once('submit', ...)`
+     * listener registered — i.e. wait_for_submit / define_form({wait:true})
+     * is actively blocked on this tenant right now. Tracked via submitBus's
+     * own newListener/removeListener events (see constructor) rather than a
+     * manual flag, so it can never drift from the real listener count.
+     * Broadcast to the browser as a 'waiting' WS message so the UI can show
+     * whether anyone is listening, without implying Submit is meaningless
+     * when nobody currently is (see `submitted`).
+     */
+    waiting: boolean;
+    /**
+     * Whether the user has clicked Submit at least once since the form was
+     * last (re)defined. Set unconditionally on the 'submit' WS message,
+     * independent of `waiting` — the user can fill in and submit a form
+     * with no agent currently waiting (e.g. it was defined with wait:false,
+     * or the agent's turn ended), and a later wait_for_submit call or
+     * list_fields read should be able to see that they're done.
+     */
+    submitted: boolean;
     wsClients: Set<WebSocket>;
     connections: Map<string, TenantConnection>;
     lastActivityAt: number;
@@ -115,8 +135,15 @@ export declare class Tenant<TSchema, TValues> {
     broadcastUpdate(field: string, value: unknown): void;
     dispose(): void;
 }
+/**
+ * URL-safe slug rule for agent-chosen channel names (see channel-tools.ts):
+ * letters, digits, underscore, hyphen only. Channel names become part of the
+ * form URL path (`/t/<id>`), so anything requiring percent-encoding is
+ * rejected up front rather than silently mangled.
+ */
+declare function isValidChannelName(id: string): boolean;
 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 };
+export { tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName };

package/dist/tenant.js

@@ -39,6 +39,26 @@ export class Tenant {
     schema;
     store;
     submitBus;
+    /**
+     * Whether some caller currently has a `submitBus.once('submit', ...)`
+     * listener registered — i.e. wait_for_submit / define_form({wait:true})
+     * is actively blocked on this tenant right now. Tracked via submitBus's
+     * own newListener/removeListener events (see constructor) rather than a
+     * manual flag, so it can never drift from the real listener count.
+     * Broadcast to the browser as a 'waiting' WS message so the UI can show
+     * whether anyone is listening, without implying Submit is meaningless
+     * when nobody currently is (see `submitted`).
+     */
+    waiting = false;
+    /**
+     * Whether the user has clicked Submit at least once since the form was
+     * last (re)defined. Set unconditionally on the 'submit' WS message,
+     * independent of `waiting` — the user can fill in and submit a form
+     * with no agent currently waiting (e.g. it was defined with wait:false,
+     * or the agent's turn ended), and a later wait_for_submit call or
+     * list_fields read should be able to see that they're done.
+     */
+    submitted = false;
     wsClients;
     connections = new Map();
     #legacyManifest;
@@ -85,6 +105,16 @@ export class Tenant {
         this.store = new Store(initialValues);
         this.submitBus = new EventEmitter();
         this.submitBus.setMaxListeners(0);
+        this.submitBus.on('newListener', (event) => {
+            if (event !== 'submit')
+                return;
+            queueMicrotask(() => this.#syncWaiting());
+        });
+        this.submitBus.on('removeListener', (event) => {
+            if (event !== 'submit')
+                return;
+            this.#syncWaiting();
+        });
         this.wsClients = new Set();
         this.lastActivityAt = Date.now();
         this.store.onChange((field, value) => this.broadcastUpdate(field, value));
@@ -252,11 +282,12 @@ export class Tenant {
         this.store.dispose();
         this.schema = schema;
         this.store = new Store(values);
+        this.submitted = false;
         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() });
+        const payload = JSON.stringify({ type: 'reinit', schema: this.schema, state: this.store.snapshot(), waiting: this.waiting, submitted: this.submitted });
         for (const client of this.wsClients) {
             if (client.readyState === client.OPEN)
                 client.send(payload);
@@ -269,6 +300,17 @@ export class Tenant {
                 client.send(payload);
         }
     }
+    #syncWaiting() {
+        const nowWaiting = this.submitBus.listenerCount('submit') > 0;
+        if (nowWaiting === this.waiting)
+            return;
+        this.waiting = nowWaiting;
+        const payload = JSON.stringify({ type: 'waiting', waiting: this.waiting });
+        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();
@@ -283,6 +325,15 @@ export class Tenant {
         this.connections.clear();
     }
 }
+/**
+ * URL-safe slug rule for agent-chosen channel names (see channel-tools.ts):
+ * letters, digits, underscore, hyphen only. Channel names become part of the
+ * form URL path (`/t/<id>`), so anything requiring percent-encoding is
+ * rejected up front rather than silently mangled.
+ */
+function isValidChannelName(id) {
+    return /^[a-zA-Z0-9_-]+$/.test(id);
+}
 const tenants = new Map();
 function getOrCreateTenant(id, initialSchema, initialValues) {
     let tenant = tenants.get(id);
@@ -303,7 +354,7 @@ function envMs(name, 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_IDLE_TIMEOUT_MS = envMs('TENANT_IDLE_TIMEOUT_MS', 2 * 60 * 60 * 1000);
 const TENANT_SWEEP_INTERVAL_MS = envMs('TENANT_SWEEP_INTERVAL_MS', 5 * 60 * 1000);
 function startIdleSweep(onSweep) {
     const sweepInterval = setInterval(() => {
@@ -320,4 +371,4 @@ function startIdleSweep(onSweep) {
     sweepInterval.unref();
     return sweepInterval;
 }
-export { tenants, getOrCreateTenant, disposeTenant, startIdleSweep };
+export { tenants, getOrCreateTenant, disposeTenant, startIdleSweep, isValidChannelName };

package/dist/types.d.ts

@@ -7,10 +7,15 @@ export type ServerMessage<TSchema = unknown, TValues = unknown> = {
     type: 'init' | 'reinit';
     schema: TSchema;
     state: TValues;
+    waiting: boolean;
+    submitted: boolean;
 } | {
     type: 'update';
     field: string;
     value: unknown;
+} | {
+    type: 'waiting';
+    waiting: boolean;
 } | CallMessage;
 export interface SetMessage {
     type: 'set';

package/dist/ws.js

@@ -51,7 +51,7 @@ export function attachWebSocketServer(httpServer, port, initialSchema, initialVa
             if (state)
                 state.isAlive = true;
         });
-        ws.send(JSON.stringify({ type: 'init', schema: t.schema, state: t.store.snapshot() }));
+        ws.send(JSON.stringify({ type: 'init', schema: t.schema, state: t.store.snapshot(), waiting: t.waiting, submitted: t.submitted }));
         ws.on('message', (raw) => {
             t.touch();
             let msg;
@@ -65,6 +65,7 @@ export function attachWebSocketServer(httpServer, port, initialSchema, initialVa
                 t.store.set(msg.field, msg.value);
             }
             if (msg.type === 'submit') {
+                t.submitted = true;
                 t.submitBus.emit('submit', { __interrupted: false, ...t.store.snapshot() });
             }
             if (msg.type === 'interrupt') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-tenant-lib",
-  "version": "0.1.1",
+  "version": "0.3.3",
   "type": "module",
   "description": "Generic tenant/session bookkeeping + MCP wiring, reusable across projects.",
   "repository": {
@@ -35,6 +35,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
+    "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
     "zod": "^3.23.8"
   },