@jini-ai/mcp 0.6.12 → 0.6.15-rc.2

package/dist/server/stdio-hosting.d.ts

@@ -0,0 +1,51 @@
+import { Writable, type Readable } from 'node:stream';
+import type { McpTransportLike } from './ports.js';
+export interface StdioHostingOptions {
+    readonly maxFrameBytes?: number;
+    readonly serial?: boolean;
+    readonly eof?: 'close' | 'drain';
+}
+/** Validate the opt-in limit before construction performs any I/O. */
+export declare function validateFrameLimit({ maxFrameBytes }: StdioHostingOptions): void;
+/** True when any hosting guard is requested; omitted options keep the legacy lifecycle. */
+export declare function wantsStdioHosting({ maxFrameBytes, serial, eof }: StdioHostingOptions): boolean;
+/**
+ * One run's guards. Stream failures and outgoing overflow are recorded and close the transport;
+ * the host's hold-open promise rejects with the first recorded failure.
+ * @complexity O(n) per n inbound bytes; O(r) bookkeeping for r accepted requests.
+ */
+export declare function createStdioHosting({ stdin, stdout, options }: {
+    stdin: Readable;
+    stdout: Writable;
+    options: StdioHostingOptions;
+}): {
+    /** The guarded pair handed to `createTransport` in place of the configured streams. */
+    streams: {
+        stdin: Readable;
+        stdout: Writable;
+    };
+    /** Bound outgoing frames on the SDK transport this run created. Narrow fakes have no send. */
+    guardTransport({ transport }: {
+        transport: McpTransportLike;
+    }): void;
+    /** Serial mode starts each handler only after the previous one settles and its response is written. */
+    track<T>({ task, signal }: {
+        task: () => Promise<T>;
+        signal: AbortSignal | undefined;
+    }): Promise<T>;
+    /** Settles once `result` settled and its response write completed, or the run stopped; never rejects. */
+    responseWritten({ result }: {
+        result: Promise<unknown>;
+    }): Promise<void>;
+    /** Install EOF handling once connected; a failure recorded during connect closes at once. */
+    watch({ close }: {
+        close: () => void;
+    }): void;
+    /** Idempotent detach; queued handlers that have not started are skipped.
+     * @returns The first recorded failure, which the run rejects with. */
+    dispose(): Promise<{
+        error: unknown;
+    } | undefined>;
+};
+export type StdioHosting = ReturnType<typeof createStdioHosting>;
+//# sourceMappingURL=stdio-hosting.d.ts.map

package/dist/server/stdio-hosting.js

@@ -0,0 +1,216 @@
+/**
+ * Private opt-in stdio guards for `createMcpToolServer`: per-frame byte caps, FIFO request
+ * execution through response writes, and EOF draining. The SDK keeps JSON parsing, dispatch and
+ * serialization; these guards only sit between it and the host-owned streams.
+ */
+import { once } from 'node:events';
+import { Transform, Writable } from 'node:stream';
+import { setImmediate } from 'node:timers/promises';
+import { serializeMessage } from '@modelcontextprotocol/sdk/shared/stdio.js';
+import { isJSONRPCErrorResponse, isJSONRPCResultResponse } from '@modelcontextprotocol/sdk/types.js';
+import { resolveSdkTransport } from './sdk-transport.js';
+/** Validate the opt-in limit before construction performs any I/O. */
+export function validateFrameLimit({ maxFrameBytes }) {
+    if (maxFrameBytes === undefined)
+        return;
+    if (!Number.isSafeInteger(maxFrameBytes) || maxFrameBytes <= 0) {
+        throw new RangeError('maxFrameBytes must be a positive safe integer');
+    }
+}
+/** True when any hosting guard is requested; omitted options keep the legacy lifecycle. */
+export function wantsStdioHosting({ maxFrameBytes, serial, eof }) {
+    return maxFrameBytes !== undefined || serial === true || eof === 'drain';
+}
+/** Measure the SDK's actual serialization; an oversized response becomes a bounded error.
+ * @throws RangeError when a request/notification or the minimal replacement exceeds the cap.
+ */
+function boundedMessage({ message, maxFrameBytes }) {
+    if (Buffer.byteLength(serializeMessage(message)) <= maxFrameBytes)
+        return message;
+    if (!isJSONRPCResultResponse(message) && !isJSONRPCErrorResponse(message)) {
+        throw new RangeError('MCP outgoing frame exceeds maxFrameBytes');
+    }
+    const replacement = { jsonrpc: '2.0', id: message.id, error: { code: -32603, message: 'Response exceeds maxFrameBytes' } };
+    if (Buffer.byteLength(serializeMessage(replacement)) > maxFrameBytes) {
+        throw new RangeError('MCP error response exceeds maxFrameBytes');
+    }
+    return replacement;
+}
+/** Count bytes per LF-terminated frame before the SDK's unbounded read buffer sees them.
+ * Chunks pass through unchanged; the SDK still owns CRLF handling and malformed-JSON policy.
+ */
+function createFrameGuard({ maxFrameBytes }) {
+    let partial = 0;
+    const guard = new Transform({
+        transform(chunk, _encoding, callback) {
+            let start = 0;
+            for (let lf = chunk.indexOf(10); lf !== -1; lf = chunk.indexOf(10, start)) {
+                if (partial + lf + 1 - start > maxFrameBytes)
+                    break;
+                partial = 0;
+                start = lf + 1;
+            }
+            partial += chunk.length - start;
+            callback(partial > maxFrameBytes ? new RangeError('MCP incoming frame exceeds maxFrameBytes') : null, chunk);
+        },
+    });
+    return { guard, hasTail: () => partial > 0 };
+}
+/** A high-water mark of 1 makes every SDK write wait for the host stdout's real write callback. */
+function createWriteTracker({ stdout }) {
+    return new Writable({ highWaterMark: 1, write(chunk, encoding, callback) { stdout.write(chunk, encoding, callback); } });
+}
+/** Insert only the stream guards the options need; the host keeps ownership of stdin/stdout. */
+function createGuardedStreams({ stdin, stdout, options: { maxFrameBytes, serial, eof } }) {
+    const drain = eof === 'drain';
+    const input = maxFrameBytes !== undefined || drain ? createFrameGuard({ maxFrameBytes: maxFrameBytes ?? Infinity }) : undefined;
+    const output = serial === true || drain ? createWriteTracker({ stdout }) : undefined;
+    if (input)
+        stdin.pipe(input.guard);
+    return { input, output, streams: { stdin: input?.guard ?? stdin, stdout: output ?? stdout } };
+}
+/**
+ * One run's guards. Stream failures and outgoing overflow are recorded and close the transport;
+ * the host's hold-open promise rejects with the first recorded failure.
+ * @complexity O(n) per n inbound bytes; O(r) bookkeeping for r accepted requests.
+ */
+export function createStdioHosting({ stdin, stdout, options }) {
+    const { maxFrameBytes, serial = false } = options;
+    const { input, output, streams } = createGuardedStreams({ stdin, stdout, options });
+    const inFlight = new Set();
+    const removers = [];
+    let tail = Promise.resolve();
+    let failure;
+    let closeTransport;
+    let stopped = false;
+    const stop = new AbortController();
+    let disposed;
+    const listen = (emitter, event, fn) => {
+        emitter.on(event, fn);
+        removers.push(() => emitter.off(event, fn));
+    };
+    const fail = (error) => {
+        failure ??= { error };
+        closeTransport?.();
+    };
+    for (const stream of [stdin, stdout, input?.guard, output])
+        if (stream)
+            listen(stream, 'error', fail);
+    async function writesDone() {
+        while (output && output.writableLength > 0)
+            await once(output, 'drain');
+    }
+    /** Yield so SDK dispatch reaches handlers/sends, then wait until tracked writes complete. */
+    async function flushWrites() {
+        await setImmediate();
+        await writesDone();
+    }
+    async function drain() {
+        try {
+            await flushWrites();
+            while (inFlight.size > 0) {
+                await Promise.allSettled([...inFlight]);
+                await flushWrites();
+            }
+            if (input?.hasTail())
+                failure ??= { error: new Error('MCP stdin ended with an unterminated frame') };
+        }
+        catch (error) {
+            failure ??= { error };
+        }
+        closeTransport?.();
+    }
+    return {
+        /** The guarded pair handed to `createTransport` in place of the configured streams. */
+        streams,
+        /** Bound outgoing frames on the SDK transport this run created. Narrow fakes have no send. */
+        guardTransport({ transport }) {
+            const sdk = resolveSdkTransport({ transport });
+            if (maxFrameBytes === undefined || typeof sdk.send !== 'function')
+                return;
+            const send = sdk.send.bind(sdk);
+            sdk.send = (message, sendOptions) => {
+                let bounded;
+                try {
+                    bounded = boundedMessage({ message, maxFrameBytes });
+                }
+                catch (error) {
+                    fail(error);
+                    throw error;
+                }
+                return send(bounded, sendOptions);
+            };
+        },
+        /** Serial mode starts each handler only after the previous one settles and its response is written. */
+        track({ task, signal }) {
+            // Behind another request, yield first so the SDK can send that request's response.
+            const behind = inFlight.size > 0;
+            const run = async () => {
+                if (serial)
+                    await (behind ? flushWrites() : writesDone());
+                if (stopped || signal?.aborted)
+                    throw new Error('MCP request cancelled');
+                return task();
+            };
+            const result = serial ? tail.then(run) : run();
+            const settled = result.then(() => { }, () => { });
+            inFlight.add(settled);
+            void settled.then(() => inFlight.delete(settled));
+            if (serial)
+                tail = settled;
+            return result;
+        },
+        /** Settles once `result` settled and its response write completed, or the run stopped; never rejects. */
+        async responseWritten({ result }) {
+            await result.then(() => { }, () => { });
+            await setImmediate();
+            // Abortable unlike writesDone: a write still pending at dispose never drains.
+            try {
+                while (output && output.writableLength > 0)
+                    await once(output, 'drain', { signal: stop.signal });
+            }
+            catch { /* run stopped */ }
+        },
+        /** Install EOF handling once connected; a failure recorded during connect closes at once. */
+        watch({ close }) {
+            closeTransport = close;
+            if (failure)
+                return close();
+            if (options.eof !== 'drain' || !input) {
+                listen(stdin, 'end', close);
+                listen(stdin, 'close', close);
+                return;
+            }
+            // The guard ends only after the SDK consumed every buffered frame.
+            listen(input.guard, 'end', () => void drain());
+            listen(stdin, 'close', () => { if (!stdin.readableEnded)
+                close(); });
+            // Embedding transports may not consume the guarded readable; still observe its end.
+            input.guard.resume();
+            if (input.guard.readableEnded)
+                void drain();
+        },
+        /** Idempotent detach; queued handlers that have not started are skipped.
+         * @returns The first recorded failure, which the run rejects with. */
+        dispose() {
+            disposed ??= (async () => {
+                stopped = true;
+                stop.abort();
+                closeTransport = undefined;
+                if (input) {
+                    stdin.unpipe(input.guard);
+                    input.guard.destroy();
+                }
+                output?.destroy();
+                // One failed write errors this wrapper and then the borrowed stdout in later turns;
+                // keep observing until both have reported, then restore the host's own listeners.
+                await setImmediate();
+                for (const remove of removers)
+                    remove();
+                return failure;
+            })();
+            return disposed;
+        },
+    };
+}
+//# sourceMappingURL=stdio-hosting.js.map

package/dist/server/tool-arguments.d.ts

@@ -9,7 +9,7 @@
  * See docs/decisions/DR-005-proxy-argument-shapes.md.
  */
 import type { OutputUnit } from '@cfworker/json-schema';
-import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Tool } from './adapters/protocol.js';
 /** Argument normalization's input contract, shared with the dispatcher without a reverse import. */
 export interface McpToolArgumentContract {
     readonly inputSchema: Tool['inputSchema'];

package/dist/server/tool-protocol.d.ts

@@ -47,6 +47,7 @@
 import { type ToolDescriptor } from '@jini-ai/core';
 import type { CallToolResult, Tool } from '@modelcontextprotocol/sdk/types.js';
 import { type McpToolArgumentContract } from './tool-arguments.js';
+import { type DaemonRequestOptions } from './daemon-client.js';
 /** What every tool handler receives alongside its parsed arguments. */
 export interface McpToolContext {
     /** Publishes a successfully described, host-owned descriptor in this server run only. */
@@ -87,16 +88,13 @@ export interface McpToolContext {
  *
  * @param ctx - The context handed to a tool or resource handler.
  * @returns Options carrying the injected `fetch` and, when present, the auth headers.
- * @complexity O(1).
+ * @complexity O(h) to copy h configured headers; no I/O.
  * @overallScore 100/100
  */
 export declare function daemonCallOptions({ ctx }: {
     ctx: McpToolContext;
-}): {
+}, _options?: {}): DaemonRequestOptions & {
     fetchImpl: typeof fetch;
-    headers?: Record<string, string>;
-    signal?: AbortSignal;
-    diagnosticToolIds?: readonly string[];
 };
 /**
  * One MCP tool a `createMcpToolServer` caller registers. `name` must be unique within a given
@@ -157,8 +155,9 @@ export declare function buildToolIndex({ tools }: {
  * not JSON-RPC errors. Schema validation runs before every handler unconditionally: a caller (an
  * agent, not this repo's own code) supplies `rawArgs`, so a handler must never be trusted to check
  * its own declared contract on the untrusted-input path. Both a validation failure's message and a
- * thrown error's message are passed through {@link sanitizeUntrustedText} before reaching the
- * result: either can end up echoing caller- or daemon-supplied text. The validation prefix uses the
+ * thrown error's message are sanitized before reaching the result: either can end up echoing
+ * caller- or daemon-supplied text. Handler errors reuse {@link safeDiagnostic} so a second
+ * pass retains slugs/tool IDs while masking the configured auth-header credential. The validation prefix uses the
  * registered tool name outside sanitization so long gateway names are not mistaken for secrets.
  */
 export declare function handleToolCall({ name, tools, ctx }: {

package/dist/server/tool-protocol.js

@@ -49,6 +49,8 @@ import { sanitizeUntrustedText } from '@jini-ai/core/text';
 import { Validator } from '@cfworker/json-schema';
 import { ContentBlockSchema } from '@modelcontextprotocol/sdk/types.js';
 import { argumentShapeMessage, isRecord, normalizeToolArguments } from './tool-arguments.js';
+import { safeDiagnostic } from './daemon-client.js';
+import { scopeNestedSchemaRefs } from './schema-ref-scope.js';
 /**
  * Maps a tool context onto the `DaemonRequestOptions` every daemon call needs.
  *
@@ -60,10 +62,10 @@ import { argumentShapeMessage, isRecord, normalizeToolArguments } from './tool-a
  *
  * @param ctx - The context handed to a tool or resource handler.
  * @returns Options carrying the injected `fetch` and, when present, the auth headers.
- * @complexity O(1).
+ * @complexity O(h) to copy h configured headers; no I/O.
  * @overallScore 100/100
  */
-export function daemonCallOptions({ ctx }) {
+export function daemonCallOptions({ ctx }, _options = {}) {
     return {
         fetchImpl: ctx.fetchImpl,
         ...(ctx.diagnosticToolIds !== undefined ? { diagnosticToolIds: ctx.diagnosticToolIds } : {}),
@@ -137,12 +139,22 @@ export function requireString({ value, name }) {
     }
     return value;
 }
+/** Each tool's input schema as published and validated: embedded `$defs` refs scoped (see schema-ref-scope.ts). */
+const wireSchemas = new WeakMap();
+function wireInputSchema(tool) {
+    let schema = wireSchemas.get(tool);
+    if (schema === undefined) {
+        schema = scopeNestedSchemaRefs({ schema: tool.inputSchema });
+        wireSchemas.set(tool, schema);
+    }
+    return schema;
+}
 /** Projects a tool list into the `Tool[]` shape `tools/list` returns. */
 export function toolsToList({ tools }) {
     return tools.map((tool) => ({
         name: tool.name,
         description: tool.description,
-        inputSchema: tool.inputSchema,
+        inputSchema: wireInputSchema(tool),
         ...(tool.annotations !== undefined ? { annotations: tool.annotations } : {}),
     }));
 }
@@ -166,7 +178,7 @@ function validatorForTool(tool) {
         return cached;
     // The validator adds internal URI fields while compiling. F0's published schemas are frozen;
     // compile a detached copy so validation cannot mutate the immutable wire contract.
-    const validator = new Validator(structuredClone(tool.inputSchema), '2020-12', true);
+    const validator = new Validator(structuredClone(wireInputSchema(tool)), '2020-12', true);
     compiledValidators.set(tool, validator);
     return validator;
 }
@@ -179,8 +191,9 @@ function validatorForTool(tool) {
  * not JSON-RPC errors. Schema validation runs before every handler unconditionally: a caller (an
  * agent, not this repo's own code) supplies `rawArgs`, so a handler must never be trusted to check
  * its own declared contract on the untrusted-input path. Both a validation failure's message and a
- * thrown error's message are passed through {@link sanitizeUntrustedText} before reaching the
- * result: either can end up echoing caller- or daemon-supplied text. The validation prefix uses the
+ * thrown error's message are sanitized before reaching the result: either can end up echoing
+ * caller- or daemon-supplied text. Handler errors reuse {@link safeDiagnostic} so a second
+ * pass retains slugs/tool IDs while masking the configured auth-header credential. The validation prefix uses the
  * registered tool name outside sanitization so long gateway names are not mistaken for secrets.
  */
 export async function handleToolCall({ name, tools, ctx }, { rawArgs } = {}) {
@@ -211,7 +224,7 @@ export async function handleToolCall({ name, tools, ctx }, { rawArgs } = {}) {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return errorResult({ message: sanitizeUntrustedText({ text: message }, { diagnosticToolIds }) });
+        return errorResult({ message: safeDiagnostic({ text: message }, daemonCallOptions({ ctx })) });
     }
 }
 //# sourceMappingURL=tool-protocol.js.map

package/dist/server/tool-server.d.ts

@@ -17,6 +17,7 @@ import { type McpResourceDef } from './resource-protocol.js';
 import { type McpToolDef } from './tool-protocol.js';
 import { type CreateExecuteDelegatedToolToolOptions } from './tools/delegated-tool.js';
 import { type McpMessageRelay } from './message-relay.js';
+import { type StdioHostingOptions } from './stdio-hosting.js';
 /** Object-shaped server port. The default adapter translates it to the SDK interface. */
 export interface McpServerLike {
     setRequestHandler(args: {
@@ -68,7 +69,8 @@ export interface McpToolServerRequiredArgs {
     /** Resolves once when the returned handle runs. */
     readonly resolveBaseUrl: () => Promise<string> | string;
 }
-export interface McpToolServerOptions {
+/** Opt-in stdio guards; omitting all three keeps SDK limits, concurrency and immediate EOF closure. */
+export interface McpToolServerOptions extends StdioHostingOptions {
     /** Set only by relay-enabled spawns; native input engines incur no extra request or tool. */
     readonly messageRelay?: McpMessageRelay;
     /** Opt in to bounded, per-run typed publication after describe_tool. */

package/dist/server/tool-server.js

@@ -8,6 +8,7 @@ import { buildResourceIndex, handleResourceRead, resourcesToList } from './resou
 import { buildToolIndex, handleToolCall, toolsToList } from './tool-protocol.js';
 import { createTypedDelegatedToolTool } from './tools/delegated-tool.js';
 import { prependRunUserMessages } from './message-relay.js';
+import { createStdioHosting, validateFrameLimit, wantsStdioHosting } from './stdio-hosting.js';
 /** Auto-exit an idle server after this long without tool activity. */
 const DEFAULT_IDLE_MS = 30 * 60 * 1000;
 // SDK objects remain behind these adapters; hosts implement the object-shaped ports above.
@@ -42,6 +43,20 @@ function stdioOptions(options) {
         ...(options.stdout === undefined ? {} : { stdout: options.stdout }),
     };
 }
+/** Opt-in stdio guards for this run, or undefined to keep the legacy lifecycle. */
+function hostingForOptions(options) {
+    if (!wantsStdioHosting(options))
+        return undefined;
+    return createStdioHosting({ stdin: options.stdin ?? process.stdin, stdout: options.stdout ?? process.stdout, options });
+}
+/** Hosted runs hand the guarded stream pair to the unchanged transport factory. */
+function createHostedTransport({ createTransport, options, hosting }) {
+    if (!hosting)
+        return createTransport({}, stdioOptions(options));
+    const transport = createTransport({}, hosting.streams);
+    hosting.guardTransport({ transport });
+    return transport;
+}
 /**
  * Own only the MCP projection/dispatch index. F0 owns immutable exposure, and the daemon catalog
  * supplies each descriptor; the temporary source below is not another definition catalog.
@@ -102,6 +117,7 @@ function createToolPublisher({ index, server, options }) {
  * handle's `run()`.
  */
 export function createMcpToolServer(requiredArgs, options = {}) {
+    validateFrameLimit(options);
     // Validate eagerly, but keep the mutable dispatch index inside run() so re-runs are isolated.
     buildToolIndex({ tools: requiredArgs.tools });
     const resources = options.resources ?? [];
@@ -127,7 +143,16 @@ export function createMcpToolServer(requiredArgs, options = {}) {
                 idleMs: options.idleMs ?? DEFAULT_IDLE_MS,
                 onIdle: () => closeTransportForIdle?.(),
             });
-            const withActivity = (handler) => (...args) => idleExit.trackRequest({ fn: () => handler(...args) });
+            const hosting = hostingForOptions(options);
+            const withActivity = (handler) => (...args) => {
+                if (!hosting)
+                    return idleExit.trackRequest({ fn: () => handler(...args) });
+                const result = hosting.track({ task: async () => handler(...args), signal: args[1]?.extra?.signal });
+                // Active from acceptance through the response write, not just the handler: a serial
+                // request queued behind a slow write must not let idle exit close the transport.
+                void idleExit.trackRequest({ fn: () => hosting.responseWritten({ result }) });
+                return result;
+            };
             server.setRequestHandler({
                 schema: ListToolsRequestSchema,
                 handler: withActivity(async () => ({ tools: toolsToList({ tools: [...toolIndex.values()] }) })),
@@ -152,7 +177,7 @@ export function createMcpToolServer(requiredArgs, options = {}) {
                     handler: withActivity(async ({ request }) => handleResourceRead({ uri: request.params.uri, resources: resourceIndex, ctx })),
                 });
             }
-            const transport = createTransport({}, stdioOptions(options));
+            const transport = createHostedTransport({ createTransport, options, hosting });
             try {
                 closeTransportForIdle = () => {
                     void transport.close({}).catch(() => { });
@@ -167,7 +192,7 @@ export function createMcpToolServer(requiredArgs, options = {}) {
                     sdkOnMessage?.({ message });
                 };
                 const stdin = options.stdin ?? process.stdin;
-                await new Promise((resolve) => {
+                await new Promise((resolve, reject) => {
                     const sdkOnClose = transport.onclose;
                     let finished = false;
                     const done = () => {
@@ -175,7 +200,11 @@ export function createMcpToolServer(requiredArgs, options = {}) {
                             return;
                         finished = true;
                         idleExit.dispose({});
-                        resolve();
+                        if (!hosting) {
+                            resolve();
+                            return;
+                        }
+                        void hosting.dispose().then(failure => (failure ? reject(failure.error) : resolve()));
                     };
                     transport.onclose = () => {
                         sdkOnClose?.();
@@ -186,12 +215,18 @@ export function createMcpToolServer(requiredArgs, options = {}) {
                     };
                     // Hold the process open until the client disconnects (stdin EOF) — `connect()` only
                     // starts the transport, it doesn't wait for the stream to close.
+                    if (hosting) {
+                        hosting.watch({ close: closeTransportForStdin });
+                        return;
+                    }
                     stdin.once('end', closeTransportForStdin);
                     stdin.once('close', closeTransportForStdin);
                 });
             }
             finally {
                 idleExit.dispose({});
+                if (hosting)
+                    void hosting.dispose();
                 closeTransportForIdle = null;
             }
         },

package/dist/server/tools/delegated-tool.js

@@ -35,7 +35,7 @@
  */
 import { delegatedResultMarker } from '@jini-ai/protocol';
 import { batchOutcomeFor, isReadOnlyTool } from '@jini-ai/core';
-import { ToolSchema } from '@modelcontextprotocol/sdk/types.js';
+import { parseMcpToolInputSchema } from '../adapters/protocol.js';
 import { randomUUID } from 'node:crypto';
 import { postDaemonJson } from '../daemon-client.js';
 import { daemonCallOptions, requireString } from '../tool-protocol.js';
@@ -248,7 +248,7 @@ export function createExecuteReadonlyDelegatedToolTool(requiredArgs, options = {
  */
 export function createTypedDelegatedToolTool({ runId, tool }, options = {}) {
     const { descriptor, wireName } = tool;
-    const inputSchema = ToolSchema.shape.inputSchema.parse(descriptor.inputSchema);
+    const inputSchema = parseMcpToolInputSchema({ inputSchema: descriptor.inputSchema, toolId: descriptor.id });
     const readOnly = isReadOnlyTool({ descriptor });
     const gateway = readOnly
         ? createExecuteReadonlyDelegatedToolTool({ runId }, options)

package/dist/server/tools/tool-catalog-tools.js

@@ -96,7 +96,7 @@ export const searchToolsTool = {
 /** `describe_tool` -> `GET /api/tools/:id` (`packages/http/src/tool-catalog.ts`'s `toolCatalogDescribeRoute`). */
 export const describeToolTool = {
     name: 'describe_tool',
-    description: 'Get the full descriptor for one tool id found via search_tools — description, input schema, readOnly and sideEffects. When dynamic publication is enabled, this also exposes that operation as a concrete tool in tools/list; call it with its own arguments. Legacy fallback: use execute_readonly_delegated_tool only when readOnly is true. Supply id (aliases: toolId or name). Paid for only on the candidates that survive search, per the tool catalog\'s staged-discovery design.',
+    description: 'Get the full descriptor for one tool id found via search_tools — description, input schema, readOnly and sideEffects. Schema-less descriptors are information only. When dynamic publication is enabled, descriptors with an input schema also expose that operation as a concrete tool in tools/list; call it with its own arguments. Legacy fallback: use execute_readonly_delegated_tool only when readOnly is true. Supply id (aliases: toolId or name). Paid for only on the candidates that survive search, per the tool catalog\'s staged-discovery design.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -112,8 +112,12 @@ export const describeToolTool = {
     handler: async ({ args, ctx }) => {
         const id = requireString({ value: args.id, name: 'id' });
         const data = await getDaemonJson({ baseUrl: ctx.baseUrl, route: `/api/tools/${encodeURIComponent(id)}` }, daemonCallOptions({ ctx }));
-        if (ctx.publishTool)
-            await ctx.publishTool({ descriptor: describedDescriptor({ id, data }) });
+        if (ctx.publishTool) {
+            const descriptor = describedDescriptor({ id, data });
+            // A family can describe its members without owning an executable input contract.
+            if (descriptor.inputSchema != null)
+                await ctx.publishTool({ descriptor });
+        }
         return data;
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/mcp",
-  "version": "0.6.12",
+  "version": "0.6.15-rc.2",
   "description": "Model Context Protocol adapters: server config schema and IO, an MCP client, and agent-side MCP server installation.",
   "license": "Apache-2.0",
   "repository": {
@@ -83,12 +83,12 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@jini-ai/core": "^0.6.12",
-    "@jini-ai/protocol": "^0.6.12"
+    "@jini-ai/core": "^0.6.15-rc.2",
+    "@jini-ai/protocol": "^0.6.15-rc.2"
   },
   "peerDependencies": {
     "@cfworker/json-schema": "^4.1.1",
-    "@jini-ai/platform": "^0.6.10",
+    "@jini-ai/platform": "^0.6.15-rc.2",
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "peerDependenciesMeta": {
@@ -105,9 +105,9 @@
   "devDependencies": {
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@jini-ai/daemon": "^0.6.12",
-    "@jini-ai/platform": "^0.6.12",
-    "@jini-ai/core": "^0.6.12"
+    "@jini-ai/core": "^0.6.15-rc.2",
+    "@jini-ai/platform": "^0.6.15-rc.2",
+    "@jini-ai/daemon": "^0.6.15-rc.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && chmod +x dist/bin/serve.js",