mcp-tenant-lib 0.3.5 → 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/package.json

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