@jini-ai/mcp 0.4.2 → 0.4.4

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

@@ -0,0 +1,46 @@
+/**
+ * @module @jini-ai/mcp/server/tool-arguments
+ *
+ * The argument-shape half of `tools/call` dispatch, split out of `./tool-protocol.js`: copying
+ * caller arguments into a tool's canonical wrapper shape before schema validation, and turning
+ * validator errors into one field-specific recovery instruction. Pure functions, no I/O. Not
+ * re-exported by the `./index.js` barrel — {@link handleToolCall} in `./tool-protocol.js` is the
+ * only production caller.
+ * See docs/decisions/DR-005-proxy-argument-shapes.md.
+ */
+import type { OutputUnit } from '@cfworker/json-schema';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+/** Argument normalization's input contract, shared with the dispatcher without a reverse import. */
+export interface McpToolArgumentContract {
+    readonly inputSchema: Tool['inputSchema'];
+    /** Compatibility rules applied once before strict schema validation; never sent on the wire. */
+    readonly argumentNormalization?: {
+        readonly aliases?: Readonly<Record<string, string>>;
+        readonly foldIntoInput?: true;
+    };
+}
+/** True for a plain JSON object (not `null`, not an array). */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Copies caller arguments into their canonical wrapper shape before schema validation.
+ * @param requiredArgs - Tool contract and untrusted arguments; neither is mutated.
+ * @param _options - Reserved normalization options.
+ * @returns Canonical arguments; nested tool input is copied only when fields are folded.
+ * @throws Error naming an ambiguous alias, duplicate input key, or invalid wrapper field.
+ * @complexity O(k + a + i) time and space for k argument keys, a aliases, and i input keys.
+ */
+export declare function normalizeToolArguments({ tool, rawArgs }: {
+    tool: McpToolArgumentContract;
+    rawArgs: unknown;
+}, _options?: Record<string, never>): Record<string, unknown>;
+/**
+ * Formats structured validation errors as field-specific recovery instructions.
+ * @param requiredArgs - Validator errors, including JSON Pointer locations and keywords.
+ * @param _options - Reserved formatting options.
+ * @returns One actionable diagnostic; no schema-location trace.
+ * @complexity O(e + p) for e errors and p characters in the selected field path.
+ */
+export declare function argumentShapeMessage({ errors }: {
+    errors: readonly OutputUnit[];
+}, _options?: Record<string, never>): string;
+//# sourceMappingURL=tool-arguments.d.ts.map

package/dist/server/tool-arguments.js

@@ -0,0 +1,111 @@
+/** True for a plain JSON object (not `null`, not an array). */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Renames each alias present in `args` to its canonical key, in place. An alias whose canonical key
+ * already holds a different value is ambiguous and refused; an identical value collapses silently.
+ * @throws Error naming the alias to rename.
+ */
+function applyAliases({ args, aliases }) {
+    for (const [alias, canonical] of Object.entries(aliases)) {
+        if (!Object.hasOwn(args, alias))
+            continue;
+        if (Object.hasOwn(args, canonical) && args[canonical] !== args[alias]) {
+            throw new Error(`rename \`${alias}\` to \`${canonical}\` and supply only one value for \`${canonical}\``);
+        }
+        args[canonical] = args[alias];
+        delete args[alias];
+    }
+}
+/**
+ * Moves `extraKeys` from the top level of `args` into its `input` object (created when absent), in place.
+ * @throws Error when `input` is not a JSON object, or already holds one of the keys being folded.
+ */
+function foldExtraKeysIntoInput({ args, extraKeys }) {
+    const input = Object.hasOwn(args, 'input') ? args.input : {};
+    if (!isRecord(input)) {
+        throw new Error("put the tool's own arguments inside `input`; replace `input` with a JSON object");
+    }
+    if (extraKeys.some((key) => Object.hasOwn(input, key))) {
+        throw new Error("put the tool's own arguments inside `input`");
+    }
+    args.input = { ...input, ...Object.fromEntries(extraKeys.map((key) => [key, args[key]])) };
+    for (const key of extraKeys)
+        delete args[key];
+}
+/**
+ * For a strict flat schema (no additional or pattern properties, no declared `input`), refuses a
+ * nested `input` object carrying a key the schema declares at the top level, with a move instruction.
+ * Any other shape is left for schema validation to report.
+ * @throws Error naming the nested key to move.
+ */
+function assertNoMisplacedInputKey({ args, schema }) {
+    if (schema.additionalProperties !== false || schema.patternProperties)
+        return;
+    const properties = schema.properties ?? {};
+    if (!isRecord(args.input) || Object.hasOwn(properties, 'input'))
+        return;
+    const misplaced = Object.keys(args.input).find((key) => Object.hasOwn(properties, key));
+    if (misplaced !== undefined)
+        throw new Error(`move \`input.${misplaced}\` to top-level \`${misplaced}\``);
+}
+/**
+ * Copies caller arguments into their canonical wrapper shape before schema validation.
+ * @param requiredArgs - Tool contract and untrusted arguments; neither is mutated.
+ * @param _options - Reserved normalization options.
+ * @returns Canonical arguments; nested tool input is copied only when fields are folded.
+ * @throws Error naming an ambiguous alias, duplicate input key, or invalid wrapper field.
+ * @complexity O(k + a + i) time and space for k argument keys, a aliases, and i input keys.
+ */
+export function normalizeToolArguments({ tool, rawArgs }, _options = {}) {
+    if (!isRecord(rawArgs))
+        throw new Error('replace `arguments` with a JSON object');
+    const args = { ...rawArgs };
+    const properties = tool.inputSchema.properties ?? {};
+    applyAliases({ args, aliases: tool.argumentNormalization?.aliases ?? {} });
+    const extraKeys = Object.keys(args).filter((key) => !Object.hasOwn(properties, key));
+    if (tool.argumentNormalization?.foldIntoInput && extraKeys.length > 0) {
+        foldExtraKeysIntoInput({ args, extraKeys });
+    }
+    else {
+        assertNoMisplacedInputKey({ args, schema: tool.inputSchema });
+    }
+    const undefinedKey = Object.keys(args).find((key) => args[key] === undefined);
+    if (undefinedKey !== undefined)
+        throw new Error(`remove \`${undefinedKey}\` or supply a JSON value instead of undefined`);
+    return args;
+}
+/** Turns a validator JSON Pointer (`#/a/b~1c`) into a dotted field path (`a.b/c`); the root becomes `''`. */
+function pointerToFieldPath({ instanceLocation }) {
+    return instanceLocation.replace(/^#\/?/, '').split('/').map((part) => part.replace(/~1/g, '/').replace(/~0/g, '~')).join('.');
+}
+/**
+ * The supply/remove instruction for a `required` or `additionalProperties` error, whose message
+ * quotes the offending property name; `undefined` for any other error, or when no name is quoted.
+ */
+function namedFieldMessage({ error, path }) {
+    if (error.keyword !== 'required' && error.keyword !== 'additionalProperties')
+        return undefined;
+    const field = error.error.match(/"(.*)"/)?.[1];
+    if (field === undefined)
+        return undefined;
+    const key = path ? `${path}.${field}` : field;
+    return error.keyword === 'required' ? `supply required argument \`${key}\`` : `remove unknown argument \`${key}\``;
+}
+/**
+ * Formats structured validation errors as field-specific recovery instructions.
+ * @param requiredArgs - Validator errors, including JSON Pointer locations and keywords.
+ * @param _options - Reserved formatting options.
+ * @returns One actionable diagnostic; no schema-location trace.
+ * @complexity O(e + p) for e errors and p characters in the selected field path.
+ */
+export function argumentShapeMessage({ errors }, _options = {}) {
+    // Keep the additionalProperties diagnostic ahead of its generic false-schema child.
+    const error = errors.find((entry) => entry.keyword === 'required' || entry.keyword === 'additionalProperties' || entry.instanceLocation !== '#') ?? errors[0];
+    if (error === undefined)
+        return 'supply arguments matching the declared input schema';
+    const path = pointerToFieldPath({ instanceLocation: error.instanceLocation });
+    return namedFieldMessage({ error, path }) ?? `change \`${path || 'arguments'}\`: ${error.error}`;
+}
+//# sourceMappingURL=tool-arguments.js.map

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

@@ -1,6 +1,60 @@
+/**
+ * @module @jini-ai/mcp/server/tool-protocol
+ *
+ * The pure, SDK-connection-free half of the MCP tool-hosting mechanism: the
+ * `McpToolDef` contract a caller registers tools against, `tools/list`
+ * projection, and `tools/call` dispatch (look up a tool by name, run its
+ * handler, wrap the result). None of this touches `@modelcontextprotocol/sdk`'s
+ * `Server`/transport classes or the network — a tool `handler` is just
+ * `({ args, ctx }) => value | Promise<value>` that either returns a
+ * JSON-serializable payload (wrapped as a successful MCP result) or throws
+ * (wrapped as an `{isError:true}` MCP result). `./tool-server.js` is the thin
+ * layer that wires this to a real `Server` + `StdioServerTransport`.
+ *
+ * ## The one exception to "wrapped as a successful MCP result"
+ *
+ * {@link okResult} used to JSON.stringify every non-string payload unconditionally, which is exactly
+ * right for the overwhelming majority of handlers (plain JSON — an id, a list, a count) but wrong
+ * for a handler whose payload IS already a well-formed MCP content envelope (`{content: [...]}` of
+ * recognized block types). Stringifying that flattens a typed `image` block into an inert
+ * base64-in-quotes string the client can no longer render or hand to a vision model — the exact bug
+ * `execute_delegated_tool` (`../tools/delegated-tool.js`) hit: `@jini-ai/daemon`'s
+ * `delegated-tool-bridge.ts` already keeps an image block in its returned `ToolExecutionResult.output`
+ * (it is model-safe per that package's `tool-result-surfaces.ts`), but this module still turned it
+ * back into text on the way out. It is also how a **human-confirmation token reached model-visible
+ * text** in a separate, traced incident ( Decision 5): a `resource` block carrying the token
+ * fell to the same stringify path because an earlier version of this fix only recognized `text` and
+ * `image`, and `resource` was not yet in that hand-rolled allowlist.
+ *
+ * {@link okResult} now recognizes a `content` array whose every entry validates against the pinned
+ * `@modelcontextprotocol/sdk`'s own `ContentBlockSchema` — the same union the SDK itself defines
+ * `CallToolResultSchema.content` against — and passes such an envelope through verbatim instead of
+ * stringifying it. Deferring to the SDK's schema rather than re-implementing a per-type shape check
+ * here means every block type the pinned protocol version defines (`text`, `image`, `audio`,
+ * `resource`, `resource_link` as of `@modelcontextprotocol/sdk@^1.29.0`) is recognized automatically,
+ * and a future SDK upgrade that adds another block type is picked up the same way, without another
+ * hand-edit to this module. Whitelist, not blacklist: a `content` array holding even one entry that
+ * does not validate falls back to the stringify path, so a malformed block is never forwarded as if it
+ * were valid protocol output. What this does **not** guarantee: a block type the pinned SDK does not
+ * yet know about (a real future MCP protocol addition ahead of this dependency) still falls back to
+ * stringify until the SDK dependency itself is upgraded — this fix converts "remember to update this
+ * allowlist" into "remember to bump the SDK", not into an unconditional guarantee. It also does not
+ * (and cannot) judge intent: a handler that puts a secret inside an otherwise well-formed `text` block
+ * will still have it pass through as designed — withholding a value from the model is the handler's
+ * responsibility ( Decision 4), not this generic wrapper's.
+ * See docs/decisions/DR-002-protocol-resource-boundary.md.
+ */
+import { type ToolDescriptor } from '@jini-ai/core';
 import type { CallToolResult, Tool } from '@modelcontextprotocol/sdk/types.js';
+import { type McpToolArgumentContract } from './tool-arguments.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. */
+    readonly publishTool?: (required: {
+        descriptor: ToolDescriptor;
+    }, optional?: Record<string, never>) => Promise<void>;
+    /** Host registration metadata, supplied outside model-controlled arguments. */
+    readonly diagnosticToolIds?: readonly string[];
     /** The resolved daemon HTTP base URL (no trailing slash), fixed for the lifetime of one server run. */
     readonly baseUrl: string;
     /** Defaults to the global `fetch`; threaded through so a host can inject its own (e.g. for tests). */
@@ -42,6 +96,7 @@ export declare function daemonCallOptions({ ctx }: {
     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
@@ -51,10 +106,9 @@ export declare function daemonCallOptions({ ctx }: {
  * `CallToolResult` shape by {@link handleToolCall}, so individual tools never construct MCP
  * protocol objects themselves.
  */
-export interface McpToolDef<Args extends Record<string, unknown> = Record<string, unknown>> {
+export interface McpToolDef<Args extends Record<string, unknown> = Record<string, unknown>> extends McpToolArgumentContract {
     readonly name: string;
     readonly description: string;
-    readonly inputSchema: Tool['inputSchema'];
     readonly annotations?: Tool['annotations'];
     readonly handler: (requiredArgs: {
         args: Args;
@@ -62,7 +116,7 @@ export interface McpToolDef<Args extends Record<string, unknown> = Record<string
     }) => Promise<unknown> | unknown;
 }
 /**
- * Wraps a successful tool result as an MCP `CallToolResult`.
+ * Wraps a tool result as an MCP `CallToolResult`, preserving explicit errors and failed batch outcomes.
  *
  * A payload that is already a well-formed MCP content envelope (see {@link isMcpContentEnvelope}) is
  * returned with its `content` array verbatim, so a typed block inside it — `image`, `resource`, or any
@@ -72,7 +126,7 @@ export interface McpToolDef<Args extends Record<string, unknown> = Record<string
  * JSON-stringified (compact, no indentation) into one.
  *
  * @complexity O(n) in the number of content-array entries, only when `payload` already looks like an
- * envelope; O(1) otherwise.
+ * envelope or batch; O(1) otherwise.
  */
 export declare function okResult({ payload }: {
     payload: unknown;
@@ -95,7 +149,8 @@ export declare function buildToolIndex({ tools }: {
     tools: readonly McpToolDef[];
 }): Map<string, McpToolDef>;
 /**
- * `tools/call` dispatch: looks up `name` in `tools`, validates `rawArgs` against the tool's
+ * `tools/call` dispatch: looks up `name` in `tools`, normalizes aliases/wrapper input, then
+ * validates the canonical arguments against the tool's
  * declared `inputSchema`, runs its handler, and converts the outcome to a `CallToolResult` — an
  * unknown tool name, a schema violation, or a thrown error all produce an `{isError:true}` result
  * rather than rejecting, matching MCP's convention that tool failures are protocol-level results,
@@ -103,8 +158,8 @@ export declare function buildToolIndex({ tools }: {
  * 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, and it is cheaper to sanitize
- * unconditionally than to prove which call site needs it.
+ * result: either can end up echoing caller- or daemon-supplied text. 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 }: {
     name: string;

package/dist/server/tool-protocol.js

@@ -44,9 +44,11 @@
  * responsibility ( Decision 4), not this generic wrapper's.
  * See docs/decisions/DR-002-protocol-resource-boundary.md.
  */
+import { batchOutcomeFor } from '@jini-ai/core';
 import { sanitizeUntrustedText } from '@jini-ai/core/text';
-import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/cfworker';
+import { Validator } from '@cfworker/json-schema';
 import { ContentBlockSchema } from '@modelcontextprotocol/sdk/types.js';
+import { argumentShapeMessage, isRecord, normalizeToolArguments } from './tool-arguments.js';
 /**
  * Maps a tool context onto the `DaemonRequestOptions` every daemon call needs.
  *
@@ -64,13 +66,11 @@ import { ContentBlockSchema } from '@modelcontextprotocol/sdk/types.js';
 export function daemonCallOptions({ ctx }) {
     return {
         fetchImpl: ctx.fetchImpl,
+        ...(ctx.diagnosticToolIds !== undefined ? { diagnosticToolIds: ctx.diagnosticToolIds } : {}),
         ...(ctx.authHeaders !== undefined ? { headers: { ...ctx.authHeaders } } : {}),
         ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
     };
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 /**
  * True when `block` is a well-formed MCP content block this module will pass through verbatim rather
  * than JSON-stringify. Delegates to the pinned `@modelcontextprotocol/sdk`'s own `ContentBlockSchema`
@@ -101,7 +101,7 @@ function isMcpContentEnvelope(payload) {
     return Array.isArray(content) && content.every(isPassthroughContentBlock);
 }
 /**
- * Wraps a successful tool result as an MCP `CallToolResult`.
+ * Wraps a tool result as an MCP `CallToolResult`, preserving explicit errors and failed batch outcomes.
  *
  * A payload that is already a well-formed MCP content envelope (see {@link isMcpContentEnvelope}) is
  * returned with its `content` array verbatim, so a typed block inside it — `image`, `resource`, or any
@@ -111,17 +111,20 @@ function isMcpContentEnvelope(payload) {
  * JSON-stringified (compact, no indentation) into one.
  *
  * @complexity O(n) in the number of content-array entries, only when `payload` already looks like an
- * envelope; O(1) otherwise.
+ * envelope or batch; O(1) otherwise.
  */
 export function okResult({ payload }) {
+    const outcome = batchOutcomeFor({ output: payload });
+    const isError = (typeof payload === 'object' && payload !== null && 'isError' in payload && payload.isError === true)
+        || outcome === 'partial_failure' || outcome === 'error';
     if (isMcpContentEnvelope(payload)) {
-        return { content: payload.content };
+        return { content: payload.content, ...(isError ? { isError: true } : {}) };
     }
     // Compact on the wire: indentation made nested results ~2.5x larger for the model to read. A view
     // that shows a result to a person re-indents it at render time (`@jini-ai/chat`'s
     // `formatToolOutputForDisplay`).
     const text = typeof payload === 'string' ? payload : JSON.stringify(payload);
-    return { content: [{ type: 'text', text }] };
+    return { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) };
 }
 /** Wraps a tool failure as an MCP `isError` result. */
 export function errorResult({ message }) {
@@ -154,31 +157,22 @@ export function buildToolIndex({ tools }) {
     }
     return index;
 }
-/**
- * The SDK's own edge-runtime-compatible (no `eval`/codegen) JSON Schema validator — the same
- * mechanism `McpServer.registerTool()`'s high-level helper uses internally, borrowed here because
- * `createMcpToolServer` is built on the SDK's low-level `Server.setRequestHandler` instead (see
- * `tool-server.ts`'s module doc), which does not validate a tool's declared `inputSchema` against
- * arguments before its handler runs. One provider instance is reused across every tool: it holds no
- * per-schema state itself (see {@link compiledValidators} for the actual compiled-validator cache).
- */
-const schemaValidatorProvider = new CfWorkerJsonSchemaValidator();
-/**
- * Compiling a validator from a schema is real work `CfWorkerJsonSchemaValidator` does not cache
- * internally (per its own doc), so it is cached here per `McpToolDef` instance — stable for a
- * server's whole lifetime, since tool defs are created once at module load and never rebuilt.
- */
+/** Compiled schemas are reused for each stable tool definition, as in the SDK provider. */
 const compiledValidators = new WeakMap();
+/** Returns the cached validator, retaining structured field locations for recovery instructions. */
 function validatorForTool(tool) {
     const cached = compiledValidators.get(tool);
     if (cached)
         return cached;
-    const validator = schemaValidatorProvider.getValidator(tool.inputSchema);
+    // 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);
     compiledValidators.set(tool, validator);
     return validator;
 }
 /**
- * `tools/call` dispatch: looks up `name` in `tools`, validates `rawArgs` against the tool's
+ * `tools/call` dispatch: looks up `name` in `tools`, normalizes aliases/wrapper input, then
+ * validates the canonical arguments against the tool's
  * declared `inputSchema`, runs its handler, and converts the outcome to a `CallToolResult` — an
  * unknown tool name, a schema violation, or a thrown error all produce an `{isError:true}` result
  * rather than rejecting, matching MCP's convention that tool failures are protocol-level results,
@@ -186,34 +180,30 @@ function validatorForTool(tool) {
  * 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, and it is cheaper to sanitize
- * unconditionally than to prove which call site needs it.
+ * result: either can end up echoing caller- or daemon-supplied text. 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 } = {}) {
+    const diagnosticToolIds = [...tools.keys(), ...(ctx.diagnosticToolIds ?? [])];
+    ctx = { ...ctx, diagnosticToolIds };
     const tool = tools.get(name);
     if (tool === undefined) {
         return errorResult({ message: `unknown tool: ${name}` });
     }
-    const args = rawArgs ?? {};
-    // Validation gets its own error boundary, separate from the handler's below. The
-    // validator does not only return `{valid:false}` for a bad argument — `@cfworker/json-schema`
-    // *throws* for JavaScript values JSON cannot encode (an explicitly-`undefined` optional
-    // property yields `Instances of "undefined" type are not supported.`). Compiling the
-    // validator can throw too, on a malformed `inputSchema`. Either escaping would break this
-    // function's whole contract, that a schema violation is an `{isError:true}` result and never
-    // a rejection — and `handleToolCall` is exported, typed `Record<string, unknown>`, and
-    // callable directly by a host, so this is reachable and not merely theoretical.
+    // Normalization and schema validation share an error boundary; handlers run only afterward.
+    // See docs/decisions/DR-005-proxy-argument-shapes.md.
     let validatedArgs;
     try {
-        const validation = validatorForTool(tool)(args);
+        const args = normalizeToolArguments({ tool, rawArgs: rawArgs ?? {} });
+        const validation = validatorForTool(tool).validate(args);
         if (!validation.valid) {
-            return errorResult({ message: sanitizeUntrustedText({ text: `invalid arguments for ${name}: ${validation.errorMessage}` }) });
+            return errorResult({ message: `invalid arguments for ${tool.name}: ${sanitizeUntrustedText({ text: argumentShapeMessage({ errors: validation.errors }) }, { diagnosticToolIds })}` });
         }
-        validatedArgs = validation.data;
+        validatedArgs = args;
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return errorResult({ message: sanitizeUntrustedText({ text: `invalid arguments for ${name}: ${message}` }) });
+        return errorResult({ message: `invalid arguments for ${tool.name}: ${sanitizeUntrustedText({ text: message }, { diagnosticToolIds })}` });
     }
     try {
         const result = await tool.handler({ args: validatedArgs, ctx: ctx });
@@ -221,7 +211,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 }) });
+        return errorResult({ message: sanitizeUntrustedText({ text: message }, { diagnosticToolIds }) });
     }
 }
 //# sourceMappingURL=tool-protocol.js.map

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

@@ -7,6 +7,7 @@
  * with nominal private fields; default adapters translate those contracts to the real SDK.
  */
 import type { Readable, Writable } from 'node:stream';
+import { type ToolDescriptor } from '@jini-ai/core';
 import type { McpTransportLike } from './ports.js';
 export type { McpTransportLike } from './ports.js';
 import type { ServerOptions } from '@modelcontextprotocol/sdk/server/index.js';
@@ -14,6 +15,7 @@ import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSche
 import type { CallToolResult, Implementation, ListResourcesResult, ListToolsResult, ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
 import { type McpResourceDef } from './resource-protocol.js';
 import { type McpToolDef } from './tool-protocol.js';
+import { type CreateExecuteDelegatedToolToolOptions } from './tools/delegated-tool.js';
 /** Object-shaped server port. The default adapter translates it to the SDK interface. */
 export interface McpServerLike {
     setRequestHandler(args: {
@@ -52,6 +54,8 @@ export interface McpServerLike {
     connect(args: {
         transport: McpTransportLike;
     }): Promise<void>;
+    /** Optional for static embeddings; required when delegated publication is enabled. */
+    sendToolListChanged?(required: Record<string, never>, optional?: Record<string, never>): Promise<void>;
 }
 /** Required identity, tool surface, and daemon URL resolver. */
 export interface McpToolServerRequiredArgs {
@@ -64,6 +68,10 @@ export interface McpToolServerRequiredArgs {
     readonly resolveBaseUrl: () => Promise<string> | string;
 }
 export interface McpToolServerOptions {
+    /** Opt in to bounded, per-run typed publication after describe_tool. */
+    readonly delegatedTools?: McpDelegatedToolsOptions;
+    /** Trusted daemon registration IDs carried into every error sanitizer. */
+    readonly diagnosticToolIds?: readonly string[];
     /** The bounded, explicit read-only resource list this server hosts. Duplicate uris throw at construction time. Omit (or pass an empty array) for a tools-only server — `capabilities.resources` is only advertised when this is non-empty. */
     readonly resources?: readonly McpResourceDef[];
     /** Free-text guidance surfaced to the MCP client alongside the tool list. Optional — omit for a caller with nothing to add beyond each tool's own `description`. */
@@ -93,6 +101,17 @@ export interface McpToolServerOptions {
         stdout?: Writable;
     }) => McpTransportLike;
 }
+/** The admitted host descriptors supplied here must come from the existing registry/catalog.
+ * Publication never connects to a federated server or admits its upstream list changes.
+ */
+export interface McpDelegatedToolsOptions extends CreateExecuteDelegatedToolToolOptions {
+    readonly runId: string;
+    /** Resolve these through the authenticated daemon before running a client without refresh. */
+    readonly initialTools?: readonly ToolDescriptor[];
+    /** Defaults to F0's 64 tools and 256 KiB of schemas; new entries are skipped at the cap. */
+    readonly maxTools?: number;
+    readonly maxSchemaBytes?: number;
+}
 export interface McpToolServerHandle {
     /**
      * Resolves the daemon base URL, connects the MCP server to its transport, and holds the process

package/dist/server/tool-server.js

@@ -1,3 +1,4 @@
+import { createToolExposure } from '@jini-ai/core';
 import { adaptSdkTransport, resolveSdkTransport } from './sdk-transport.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -5,6 +6,7 @@ import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSche
 import { createMcpIdleExitController } from '../client/client.js';
 import { buildResourceIndex, handleResourceRead, resourcesToList } from './resource-protocol.js';
 import { buildToolIndex, handleToolCall, toolsToList } from './tool-protocol.js';
+import { createTypedDelegatedToolTool } from './tools/delegated-tool.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.
@@ -13,11 +15,84 @@ function defaultCreateServer({ info, options }) {
     return {
         setRequestHandler: (({ schema, handler }) => server.setRequestHandler(schema, (request, extra) => handler({ request }, { extra }))),
         connect: ({ transport }) => server.connect(resolveSdkTransport({ transport })),
+        sendToolListChanged: () => server.sendToolListChanged(),
     };
 }
 function defaultCreateTransport(_requiredArgs, { stdin, stdout } = {}) {
     return adaptSdkTransport({ transport: new StdioServerTransport(stdin, stdout) });
 }
+/**
+ * The tool context shared by every call in one run: the resolved daemon URL without its trailing
+ * slash (coerced to a string for JS hosts that ignore the contract), the configured or global
+ * `fetch`, and the auth headers and diagnostic IDs only when configured.
+ */
+function buildToolContext({ resolvedBaseUrl }, options) {
+    return {
+        ...(options.diagnosticToolIds !== undefined ? { diagnosticToolIds: options.diagnosticToolIds } : {}),
+        baseUrl: String(resolvedBaseUrl).replace(/\/$/, ''),
+        fetchImpl: options.fetchImpl ?? fetch,
+        ...(options.authHeaders !== undefined ? { authHeaders: options.authHeaders } : {}),
+    };
+}
+/** The stdio pair handed to `createTransport`, carrying only the streams the caller configured. */
+function stdioOptions(options) {
+    return {
+        ...(options.stdin === undefined ? {} : { stdin: options.stdin }),
+        ...(options.stdout === undefined ? {} : { stdout: options.stdout }),
+    };
+}
+/**
+ * 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.
+ * @returns An install-before-notify publisher, or undefined for a static server.
+ * @throws On malformed schemas, invalid exposure limits, or an embedding without notification support.
+ * @complexity O(n + s) per promotion for n bounded exposed tools and s schema bytes; no daemon I/O.
+ */
+function createToolPublisher({ index, server, options }) {
+    if (!options)
+        return undefined;
+    const notify = server.sendToolListChanged?.bind(server);
+    if (!notify)
+        throw new Error('delegated publication requires tools/list_changed support');
+    let descriptors = options.initialTools ?? [];
+    const exposure = createToolExposure({ registry: { list: () => descriptors } }, {
+        reservedNames: [...index.keys()],
+        ...(options.maxTools === undefined ? {} : { maxTools: options.maxTools }),
+        ...(options.maxSchemaBytes === undefined ? {} : { maxSchemaBytes: options.maxSchemaBytes }),
+    });
+    // Validate before promotion: malformed descriptors must not consume a pinned name or budget.
+    const validate = (descriptor) => createTypedDelegatedToolTool({ runId: options.runId, tool: { wireName: descriptor.id, descriptor } }, options);
+    for (const descriptor of descriptors)
+        validate(descriptor);
+    const initial = exposure.promote({ toolIds: descriptors.map(descriptor => descriptor.id) });
+    for (const tool of initial.snapshot.tools)
+        index.set(tool.wireName, createTypedDelegatedToolTool({ runId: options.runId, tool }, options));
+    descriptors = [];
+    let notificationPending = false;
+    return async ({ descriptor }, _optional = {}) => {
+        validate(descriptor);
+        descriptors = [descriptor];
+        const delta = exposure.promote({ toolIds: [descriptor.id] });
+        descriptors = [];
+        for (const tool of delta.snapshot.tools) {
+            if (!index.has(tool.wireName))
+                index.set(tool.wireName, createTypedDelegatedToolTool({ runId: options.runId, tool }, options));
+        }
+        if (delta.added.length > 0)
+            notificationPending = true;
+        if (!notificationPending)
+            return;
+        // Clear before awaiting: a concurrent promotion must retain its own unsent notification.
+        notificationPending = false;
+        try {
+            await notify({});
+        }
+        catch (error) {
+            notificationPending = true;
+            throw error;
+        }
+    };
+}
 /**
  * Builds a stdio MCP server hosting `requiredArgs.tools` (and, optionally, `options.resources`).
  * Construction is synchronous and cheap (validates tool-name uniqueness via
@@ -26,35 +101,35 @@ function defaultCreateTransport(_requiredArgs, { stdin, stdout } = {}) {
  * handle's `run()`.
  */
 export function createMcpToolServer(requiredArgs, options = {}) {
-    const toolIndex = buildToolIndex({ tools: requiredArgs.tools });
+    // Validate eagerly, but keep the mutable dispatch index inside run() so re-runs are isolated.
+    buildToolIndex({ tools: requiredArgs.tools });
     const resources = options.resources ?? [];
     const resourceIndex = buildResourceIndex({ resources });
     const createServer = options.createServer ?? defaultCreateServer;
     const createTransport = options.createTransport ?? defaultCreateTransport;
     return {
         async run(_required) {
-            const resolvedBaseUrl = await requiredArgs.resolveBaseUrl();
-            const ctx = {
-                baseUrl: String(resolvedBaseUrl).replace(/\/$/, ''),
-                fetchImpl: options.fetchImpl ?? fetch,
-                ...(options.authHeaders !== undefined ? { authHeaders: options.authHeaders } : {}),
-            };
-            let closeTransportForIdle = null;
-            const idleExit = createMcpIdleExitController({
-                idleMs: options.idleMs ?? DEFAULT_IDLE_MS,
-                onIdle: () => closeTransportForIdle?.(),
-            });
-            const withActivity = (handler) => (...args) => idleExit.trackRequest({ fn: () => handler(...args) });
+            const toolIndex = buildToolIndex({ tools: requiredArgs.tools });
+            let ctx = buildToolContext({ resolvedBaseUrl: await requiredArgs.resolveBaseUrl() }, options);
             const server = createServer({
                 info: { name: requiredArgs.name, version: requiredArgs.version },
                 options: {
-                    capabilities: { tools: {}, ...(resources.length > 0 ? { resources: {} } : {}) },
+                    capabilities: { tools: options.delegatedTools ? { listChanged: true } : {}, ...(resources.length > 0 ? { resources: {} } : {}) },
                     ...(options.instructions !== undefined ? { instructions: options.instructions } : {}),
                 },
             });
+            const publishTool = createToolPublisher({ index: toolIndex, server, options: options.delegatedTools });
+            if (publishTool)
+                ctx = { ...ctx, publishTool };
+            let closeTransportForIdle = null;
+            const idleExit = createMcpIdleExitController({
+                idleMs: options.idleMs ?? DEFAULT_IDLE_MS,
+                onIdle: () => closeTransportForIdle?.(),
+            });
+            const withActivity = (handler) => (...args) => idleExit.trackRequest({ fn: () => handler(...args) });
             server.setRequestHandler({
                 schema: ListToolsRequestSchema,
-                handler: withActivity(async () => ({ tools: toolsToList({ tools: requiredArgs.tools }) })),
+                handler: withActivity(async () => ({ tools: toolsToList({ tools: [...toolIndex.values()] }) })),
             });
             server.setRequestHandler({
                 schema: CallToolRequestSchema,
@@ -70,10 +145,7 @@ export function createMcpToolServer(requiredArgs, options = {}) {
                     handler: withActivity(async ({ request }) => handleResourceRead({ uri: request.params.uri, resources: resourceIndex, ctx })),
                 });
             }
-            const transport = createTransport({}, {
-                ...(options.stdin === undefined ? {} : { stdin: options.stdin }),
-                ...(options.stdout === undefined ? {} : { stdout: options.stdout }),
-            });
+            const transport = createTransport({}, stdioOptions(options));
             try {
                 closeTransportForIdle = () => {
                     void transport.close({}).catch(() => { });