mcp-tenant-lib 0.3.4 → 0.3.6

package/dist/channel-tools.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { tenants, getOrCreateTenant, isValidChannelName } from './tenant.js';
 import { findChannelMatches } from './channel-search.js';
+import { buildDescribePayload } from './manifest-tools.js';
 /**
  * Registers `join_channel` and `list_channels` on an MCP server built via
  * buildMcpServer. Shared across every mcp-tenant-lib consumer (mcp-form,
@@ -18,7 +19,8 @@ export function registerChannelTools(mcp, tenant, port, setChannel, initialSchem
         '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 }) => {
+        'to resume, or redefine/refresh it). Names are URL-safe slugs: letters, digits, underscore, hyphen only. ' +
+        'To only inspect a channel\'s tools without retargeting this session onto it, use describe_channel instead.', { 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.` }],
@@ -32,11 +34,11 @@ 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. 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 () => {
+        'sessions land on before calling join_channel). Use this to discover an existing named channel, e.g. when ' +
+        'a human refers to "the pets form" without giving the exact channel 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. To see the ' +
+        'actual tools on one, call describe_channel rather than joining just to look.', {}, async () => {
         const channels = [...tenants.entries()].map(([channel, t]) => ({
             channel,
             connections: [...t.connections.values()].map((c) => ({
@@ -58,4 +60,22 @@ export function registerChannelTools(mcp, tenant, port, setChannel, initialSchem
         const matches = findChannelMatches(query, [...tenants.keys()]);
         return { content: [{ type: 'text', text: JSON.stringify(matches, null, 2) }] };
     });
+    mcp.tool('describe_channel', 'Returns the tool manifest for a named channel — same payload as describe_tools, but for ANY channel, ' +
+        'not just the one this session is currently on. Use this to go straight from a channel name (e.g. from ' +
+        'list_channels or channel_find) to what tools it has, without join_channel first retargeting this ' +
+        'session\'s own state onto it. Read-only: does not join, create, or affect this session\'s current ' +
+        'channel. Errors if the channel does not exist yet — check list_channels/channel_find first. If a tool ' +
+        'listed here fails to invoke with "No such tool available" (typically right after the MCP server ' +
+        'process was restarted), your MCP client\'s own connection is stale, not this manifest — tell the user ' +
+        'to reconnect the MCP client (e.g. /mcp in Claude Code) rather than retrying the call.', { channel: z.string().describe('Exact channel name, e.g. from list_channels or channel_find.') }, async ({ channel }) => {
+        const t = tenants.get(channel);
+        if (!t) {
+            return {
+                content: [{ type: 'text', text: `Error: no channel named "${channel}" — use list_channels or channel_find to find the right name.` }],
+                isError: true,
+            };
+        }
+        const payload = buildDescribePayload(t);
+        return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+    });
 }

package/dist/manifest-tools.d.ts

@@ -4,6 +4,33 @@ export interface ManifestToolRegistry {
     handles: Map<string, RegisteredTool>;
     sync(): void;
 }
+/**
+ * Same shape describe_tools returns for the caller's own current channel,
+ * built from any Tenant — shared with describe_channel (channel-tools.ts)
+ * so a channel's manifest can be inspected by name without join_channel
+ * retargeting the session onto it first.
+ */
+export declare function buildDescribePayload<TSchema, TValues>(t: Tenant<TSchema, TValues>): {
+    summary: string | null;
+    tools: {
+        name: string;
+        description: string;
+    }[];
+    connections?: undefined;
+} | {
+    connections: {
+        id: string;
+        label: string | null;
+        toolPrefix: string | undefined;
+        summary: string | null;
+        tools: {
+            name: string;
+            description: string;
+        }[];
+    }[];
+    summary?: undefined;
+    tools?: undefined;
+};
 /**
  * Registers one MCP tool per entry in tenant().toolManifest, dispatching
  * calls to the page via tenant().call(target, args). Also always registers

package/dist/manifest-tools.js

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+class UnsupportedParamTypeError extends Error {
+}
 function paramSpecToZod(spec) {
     let schema;
     switch (spec.type) {
@@ -11,7 +13,7 @@ function paramSpecToZod(spec) {
         case 'boolean':
             schema = z.boolean();
             break;
-        default: throw new Error(`unsupported param type "${spec.type}" (supported: string, number, boolean)`);
+        default: throw new UnsupportedParamTypeError(`unsupported param type "${spec.type}" (supported: string, number, boolean)`);
     }
     if (spec.description)
         schema = schema.describe(spec.description);
@@ -24,6 +26,34 @@ function manifestEntryToZodShape(entry) {
     }
     return shape;
 }
+/**
+ * Same shape describe_tools returns for the caller's own current channel,
+ * built from any Tenant — shared with describe_channel (channel-tools.ts)
+ * so a channel's manifest can be inspected by name without join_channel
+ * retargeting the session onto it first.
+ */
+export function buildDescribePayload(t) {
+    const conns = [...t.connections.values()];
+    if (conns.length <= 1) {
+        return {
+            summary: t.toolManifestSummary ?? null,
+            tools: t.toolManifest.map((e) => ({ name: e.name, description: e.description })),
+        };
+    }
+    const slugFor = computeSlugs(conns);
+    return {
+        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,
+            })),
+        })),
+    };
+}
 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 ' +
@@ -43,7 +73,10 @@ const DESCRIBE_TOOLS_DESCRIPTION = 'Returns manifest-level context for the tools
     '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.';
+    'and join_channel to it before assuming nothing is connected. If a tool listed here instead fails to ' +
+    'invoke with "No such tool available" (typically right after the MCP server process was restarted), ' +
+    'your MCP client\'s own connection is stale, not this manifest — tell the user to reconnect the MCP ' +
+    'client (e.g. /mcp in Claude Code) rather than retrying the call.';
 /**
  * Derives a stable, unique tool-name prefix per connection: sanitized from
  * `label` (falling back to "tab" when absent or empty after sanitizing),
@@ -91,28 +124,7 @@ 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,
-                    })),
-                })),
-            };
+            const payload = buildDescribePayload(tenant());
             return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
         });
         handles.set(DESCRIBE_TOOLS_NAME, handle);
@@ -177,7 +189,22 @@ export function createManifestToolRegistry(mcp, tenant) {
         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) => {
+            let inputSchema;
+            try {
+                inputSchema = manifestEntryToZodShape(entry);
+            }
+            catch (err) {
+                // A single page-authored tool with a malformed param spec (bad/missing
+                // `type`) must not take down sync() for every other tool on the
+                // channel, nor crash whatever triggered this sync (e.g. join_channel
+                // migrating the registry) — skip just this one entry.
+                if (err instanceof UnsupportedParamTypeError) {
+                    console.error(`[mcp-tenant-lib] skipping tool "${registeredName}": ${err.message}`);
+                    continue;
+                }
+                throw err;
+            }
+            const handle = mcp.registerTool(registeredName, { description: entry.description, inputSchema }, async (args) => {
                 try {
                     const result = await tenant().call(connectionId, entry.name, args);
                     return { content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }] };

package/dist/tenant.d.ts

@@ -56,6 +56,16 @@ export declare class Tenant<TSchema, TValues> {
      * list_fields read should be able to see that they're done.
      */
     submitted: boolean;
+    /**
+     * Timestamp of the most recent real edit to `store` (a field value
+     * changing) or a successfully-applied `restoreState` (see below) —
+     * distinct from `lastActivityAt`, which also counts reads/pings and
+     * drives idle-sweep instead. Used solely to arbitrate `resync` messages
+     * (ws.ts) when more than one browser tab reconnects to the same
+     * recreated tenant: whichever tab's last edit is newer wins, rather than
+     * whichever tab's resync happens to reach the server first.
+     */
+    lastStateChangeAt: number;
     wsClients: Set<WebSocket>;
     connections: Map<string, TenantConnection>;
     lastActivityAt: number;
@@ -139,6 +149,27 @@ export declare class Tenant<TSchema, TValues> {
     rejectCall(id: string, error: string): void;
     touch(): void;
     applyState(schema: TSchema, values: TValues): void;
+    /**
+     * Restores schema/values/submitted from a browser page's own live state
+     * after this tenant was recreated empty (see the `recreated` init flag in
+     * ws.ts) — unlike applyState (used by define_form to redefine a form),
+     * this preserves `submitted` as reported by the page rather than always
+     * resetting it, since a resync is recovering prior state, not starting a
+     * new round.
+     *
+     * `changedAt` is the pushing page's own last-local-edit timestamp
+     * (Date.now() when the user or agent last changed a field in that tab —
+     * see mcp-form's client). When two tabs both reconnect to the same
+     * recreated tenant, each pushes its own resync independently; without
+     * this guard, whichever happens to reach the server first would win,
+     * which has nothing to do with which tab actually has the fresher data.
+     * Comparing against `lastStateChangeAt` (bumped by every real edit,
+     * including a previously-applied resync) means an older resync arriving
+     * after a newer one — or after the tenant was already touched some other
+     * way, e.g. an agent's set_field — is ignored rather than clobbering it.
+     * Returns whether the resync was applied.
+     */
+    restoreState(schema: TSchema, values: TValues, submitted: boolean, changedAt: number): boolean;
     broadcastReinit(): void;
     broadcastUpdate(field: string, value: unknown): void;
     dispose(): void;

package/dist/tenant.js

@@ -59,6 +59,16 @@ export class Tenant {
      * list_fields read should be able to see that they're done.
      */
     submitted = false;
+    /**
+     * Timestamp of the most recent real edit to `store` (a field value
+     * changing) or a successfully-applied `restoreState` (see below) —
+     * distinct from `lastActivityAt`, which also counts reads/pings and
+     * drives idle-sweep instead. Used solely to arbitrate `resync` messages
+     * (ws.ts) when more than one browser tab reconnects to the same
+     * recreated tenant: whichever tab's last edit is newer wins, rather than
+     * whichever tab's resync happens to reach the server first.
+     */
+    lastStateChangeAt = 0;
     wsClients;
     connections = new Map();
     #legacyManifest;
@@ -102,7 +112,7 @@ export class Tenant {
     constructor(id, initialSchema, initialValues) {
         this.id = id;
         this.schema = initialSchema;
-        this.store = new Store(initialValues);
+        this.store = new Store(initialValues); // placeholder; #attachStore below wires the real onChange listener
         this.submitBus = new EventEmitter();
         this.submitBus.setMaxListeners(0);
         this.submitBus.on('newListener', (event) => {
@@ -117,7 +127,7 @@ export class Tenant {
         });
         this.wsClients = new Set();
         this.lastActivityAt = Date.now();
-        this.store.onChange((field, value) => this.broadcastUpdate(field, value));
+        this.#attachStore(this.store);
     }
     /**
      * Legacy/no-WS path: registers a manifest with no real connection behind
@@ -292,14 +302,51 @@ export class Tenant {
     touch() {
         this.lastActivityAt = Date.now();
     }
+    #attachStore(store) {
+        this.store = store;
+        this.store.onChange((field, value) => {
+            this.lastStateChangeAt = Date.now();
+            this.broadcastUpdate(field, value);
+        });
+    }
     applyState(schema, values) {
         this.store.dispose();
         this.schema = schema;
-        this.store = new Store(values);
+        this.#attachStore(new Store(values));
         this.submitted = false;
-        this.store.onChange((field, value) => this.broadcastUpdate(field, value));
         this.broadcastReinit();
     }
+    /**
+     * Restores schema/values/submitted from a browser page's own live state
+     * after this tenant was recreated empty (see the `recreated` init flag in
+     * ws.ts) — unlike applyState (used by define_form to redefine a form),
+     * this preserves `submitted` as reported by the page rather than always
+     * resetting it, since a resync is recovering prior state, not starting a
+     * new round.
+     *
+     * `changedAt` is the pushing page's own last-local-edit timestamp
+     * (Date.now() when the user or agent last changed a field in that tab —
+     * see mcp-form's client). When two tabs both reconnect to the same
+     * recreated tenant, each pushes its own resync independently; without
+     * this guard, whichever happens to reach the server first would win,
+     * which has nothing to do with which tab actually has the fresher data.
+     * Comparing against `lastStateChangeAt` (bumped by every real edit,
+     * including a previously-applied resync) means an older resync arriving
+     * after a newer one — or after the tenant was already touched some other
+     * way, e.g. an agent's set_field — is ignored rather than clobbering it.
+     * Returns whether the resync was applied.
+     */
+    restoreState(schema, values, submitted, changedAt) {
+        if (changedAt < this.lastStateChangeAt)
+            return false;
+        this.store.dispose();
+        this.schema = schema;
+        this.#attachStore(new Store(values));
+        this.submitted = submitted;
+        this.lastStateChangeAt = changedAt;
+        this.broadcastReinit();
+        return true;
+    }
     broadcastReinit() {
         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) {

package/dist/types.d.ts

@@ -4,7 +4,14 @@ export interface SubmitPayload {
     [field: string]: unknown;
 }
 export type ServerMessage<TSchema = unknown, TValues = unknown> = {
-    type: 'init' | 'reinit';
+    type: 'init';
+    schema: TSchema;
+    state: TValues;
+    waiting: boolean;
+    submitted: boolean;
+    recreated: boolean;
+} | {
+    type: 'reinit';
     schema: TSchema;
     state: TValues;
     waiting: boolean;
@@ -25,6 +32,31 @@ export interface SetMessage {
     field: string;
     value: unknown;
 }
+/**
+ * Sent by a page that reconnects to a tenant the server reports as
+ * `recreated` (see the `init` message) — i.e. the in-memory tenant was
+ * lost, most commonly an MCP server restart, while this page's own JS
+ * runtime (and therefore its last-known schema/values) survived because
+ * the tab itself never reloaded. Lets the still-live browser page push its
+ * state back up as the source of truth instead of accepting the server's
+ * freshly-recreated default state. The server applies it via the same
+ * path as define_form (Tenant.applyState) and rebroadcasts `reinit` to any
+ * other connected tabs.
+ */
+export interface ResyncMessage<TSchema = unknown, TValues = unknown> {
+    type: 'resync';
+    schema: TSchema;
+    values: TValues;
+    submitted: boolean;
+    /**
+     * The pushing page's own last-local-edit timestamp (Date.now()) — lets
+     * the server arbitrate when two tabs both resync the same recreated
+     * tenant, favoring whichever has the more recently edited data rather
+     * than whichever resync message happens to arrive first. See
+     * Tenant.restoreState in mcp-tenant-lib for the comparison.
+     */
+    changedAt: number;
+}
 export interface SubmitMessage {
     type: 'submit';
 }
@@ -93,4 +125,4 @@ export interface RenameConnectionMessage {
     type: 'rename_connection';
     appLabel: string;
 }
-export type ClientMessage = SetMessage | SubmitMessage | InterruptMessage | RegisterToolsMessage | CallResultMessage | RenameConnectionMessage;
+export type ClientMessage = SetMessage | SubmitMessage | InterruptMessage | RegisterToolsMessage | CallResultMessage | RenameConnectionMessage | ResyncMessage;

package/dist/ws.js

@@ -60,7 +60,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(), waiting: t.waiting, submitted: t.submitted }));
+        ws.send(JSON.stringify({ type: 'init', schema: t.schema, state: t.store.snapshot(), waiting: t.waiting, submitted: t.submitted, recreated }));
         ws.on('message', (raw) => {
             t.touch();
             let msg;
@@ -92,6 +92,12 @@ export function attachWebSocketServer(httpServer, port, initialSchema, initialVa
                 else
                     t.resolveCall(msg.id, msg.result);
             }
+            if (msg.type === 'resync') {
+                const applied = t.restoreState(msg.schema, msg.values, msg.submitted, msg.changedAt);
+                console.error(applied
+                    ? `[ws] resync from connection=${connectionId}: restoring tenant "${tenantId}" state pushed back by the browser`
+                    : `[ws] resync from connection=${connectionId}: ignored — tenant "${tenantId}" already has state at least as recent`);
+            }
         });
         ws.on('close', (code, reason) => {
             console.error(`[ws] connection closed: tenant=${tenantId} connection=${connectionId} code=${code} reason=${reason.toString() || '(none)'}`);

package/package.json

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