@toolgrain/mcp 0.1.1 → 0.1.3

package/dist/tools/context.d.ts

@@ -6,28 +6,46 @@ import { type ContextRegistry } from "../context/registry.js";
 import type { DeepReadonly } from "./json-value.js";
 /** What the client reported about itself; unverified, so not a basis for security decisions. */
 export interface ToolClient {
+    /** Copied, deeply frozen implementation details supplied by the client, when available. */
     readonly info?: DeepReadonly<Implementation | LegacyImplementation>;
+    /** Copied, deeply frozen capability claims supplied by the client, when available. */
     readonly capabilities?: DeepReadonly<ClientCapabilities | LegacyClientCapabilities>;
 }
+/** Copied, immutable protocol metadata for one invocation; client claims remain unverified. */
 export interface ToolRequest {
+    /** JSON-RPC request identifier; identical IDs can occur in independent contexts. */
     readonly id: RequestId;
+    /** Supported protocol revision selected for this invocation. */
     readonly protocolVersion: SupportedProtocolVersion;
     /** Absent when the era and transport carry no client information, such as legacy HTTP. */
     readonly client?: ToolClient;
     /** A deeply frozen copy of the request's `_meta`; empty when the request carried none. */
     readonly meta: Readonly<Record<string, unknown>>;
 }
+/** Per-invocation data passed to tool handlers and lazy context resolvers. */
 export interface ToolContext {
     /** Aborts when the client cancels or disconnects, or the transport or server closes. */
     readonly signal: AbortSignal;
+    /** Frozen request metadata; contains no verified authorization identity. */
     readonly request: ToolRequest;
 }
+/** Optional metadata, cancellation, and provider bindings for a direct-call context. */
 export interface ToolContextOptions {
+    /** Caller-owned cancellation signal; defaults to a fresh, non-aborted signal. */
     signal?: AbortSignal;
+    /** Request fields to override; defaults are ID `0`, the modern revision, and empty metadata. */
     request?: Partial<ToolRequest>;
+    /** Providers or overrides available through their accessors; defaults to no registrations. */
     context?: readonly RegisteredContextProvider[];
 }
-/** Build a context for calling a definition's `execute` directly, for example in tests. */
+/**
+ * Build an unauthenticated context for direct `execute()` calls, for example in tests.
+ * Request metadata is copied and deeply frozen; each call creates a fresh provider cache.
+ * Direct execution still bypasses server authorization, validation, and MCP conversion.
+ *
+ * @param options - Optional signal, request metadata, and provider registrations.
+ * @returns A context accepted by Toolgrain's provider accessors.
+ */
 export declare function toolContext(options?: ToolContextOptions): ToolContext;
 /** Each request gets its own deeply frozen copies, so handlers cannot affect one another. */
 export declare function createToolContext(signal: AbortSignal, { client, ...request }: ToolRequest, auth?: AuthIdentity, providers?: ContextRegistry): ToolContext;

package/dist/tools/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/tools/context.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EAEnB,KAAK,SAAS,EACd,KAAK,wBAAwB,EAC9B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EACV,kBAAkB,IAAI,wBAAwB,EAC9C,cAAc,IAAI,oBAAoB,EACvC,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EACL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,gGAAgG;AAChG,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,cAAc,GAAG,oBAAoB,CAAC,CAAC;IACpE,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAClC,kBAAkB,GAAG,wBAAwB,CAC9C,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,eAAe,EAAE,wBAAwB,CAAC;IACnD,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,WAAW;IAC1B,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAC;CAChD;AAED,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAmBzE;AAED,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,WAAW,EACnB,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,EAAE,WAAW,EACnC,IAAI,CAAC,EAAE,YAAY,EACnB,SAAS,GAAE,eAAyC,GACnD,WAAW,CAiBb;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CACxB,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,EACxB,YAAY,EAAE,UAAU,CAAC,cAAc,CAAC,GACvC,UAAU,CAKZ"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/tools/context.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EAEnB,KAAK,SAAS,EACd,KAAK,wBAAwB,EAC9B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EACV,kBAAkB,IAAI,wBAAwB,EAC9C,cAAc,IAAI,oBAAoB,EACvC,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EACL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,gGAAgG;AAChG,MAAM,WAAW,UAAU;IACzB,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,cAAc,GAAG,oBAAoB,CAAC,CAAC;IACpE,sFAAsF;IACtF,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAClC,kBAAkB,GAAG,wBAAwB,CAC9C,CAAC;CACH;AAED,+FAA+F;AAC/F,MAAM,WAAW,WAAW;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,eAAe,EAAE,wBAAwB,CAAC;IACnD,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAClD;AAED,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gGAAgG;IAChG,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/B,8FAA8F;IAC9F,OAAO,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAC;CAChD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAmBzE;AAED,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,WAAW,EACnB,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,EAAE,WAAW,EACnC,IAAI,CAAC,EAAE,YAAY,EACnB,SAAS,GAAE,eAAyC,GACnD,WAAW,CAiBb;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CACxB,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,EACxB,YAAY,EAAE,UAAU,CAAC,cAAc,CAAC,GACvC,UAAU,CAKZ"}

package/dist/tools/context.js

@@ -2,7 +2,14 @@ import { PROTOCOL_VERSION, } from "@toolgrain/protocol";
 import { attachAuth } from "../auth/context.js";
 import { createContextRegistry, } from "../context/registry.js";
 import { createContextScope } from "../context/scope.js";
-/** Build a context for calling a definition's `execute` directly, for example in tests. */
+/**
+ * Build an unauthenticated context for direct `execute()` calls, for example in tests.
+ * Request metadata is copied and deeply frozen; each call creates a fresh provider cache.
+ * Direct execution still bypasses server authorization, validation, and MCP conversion.
+ *
+ * @param options - Optional signal, request metadata, and provider registrations.
+ * @returns A context accepted by Toolgrain's provider accessors.
+ */
 export function toolContext(options = {}) {
     // Default each field separately so an explicit undefined cannot replace a default.
     const { id = 0, protocolVersion = PROTOCOL_VERSION, client, meta = {}, } = options.request ?? {};

package/dist/tools/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/tools/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,gBAAgB,GAGjB,MAAM,qBAAqB,CAAC;AAK7B,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGhD,OAAO,EAEL,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAgCzD,2FAA2F;AAC3F,MAAM,UAAU,WAAW,CAAC,OAAO,GAAuB,EAAE;IAC1D,mFAAmF;IACnF,MAAM,EACJ,EAAE,GAAG,CAAC,EACN,eAAe,GAAG,gBAAgB,EAClC,MAAM,EACN,IAAI,GAAG,EAAE,GACV,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IAC1B,OAAO,iBAAiB,CACtB,OAAO,CAAC,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC,MAAM,EAC9C;QACE,EAAE;QACF,eAAe;QACf,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;QAC3C,IAAI;KACL,EACD,SAAS,EACT,qBAAqB,CAAC,OAAO,CAAC,OAAO,CAAC,CACvC,CAAC;AACJ,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,iBAAiB,CAC/B,MAAmB,EACnB,EAAE,MAAM,EAAE,GAAG,OAAO,EAAe,EACnC,IAAmB,EACnB,SAAS,GAAoB,qBAAqB,EAAE;IAEpD,MAAM,GAAG,GAAG,UAAU,CACpB;QACE,MAAM;QACN,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC;YACrB,GAAG,OAAO;YACV,GAAG,CAAC,MAAM,KAAK,SAAS;gBACtB,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC;oBACE,MAAM,EAAE,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;iBACjE,CAAC;YACN,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC;SAC/B,CAAC;KACH,EACD,IAAI,CACL,CAAC;IACF,OAAO,kBAAkB,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;AAC5C,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,UAAU,CACxB,IAAwB,EACxB,YAAwC;IAExC,OAAO;QACL,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QACvC,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC;KACxD,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAI,KAAQ;IAC7B,OAAO,UAAU,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,UAAU,CAAI,KAAQ;IAC7B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;YAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/tools/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,gBAAgB,GAGjB,MAAM,qBAAqB,CAAC;AAK7B,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGhD,OAAO,EAEL,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AA2CzD;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,OAAO,GAAuB,EAAE;IAC1D,mFAAmF;IACnF,MAAM,EACJ,EAAE,GAAG,CAAC,EACN,eAAe,GAAG,gBAAgB,EAClC,MAAM,EACN,IAAI,GAAG,EAAE,GACV,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IAC1B,OAAO,iBAAiB,CACtB,OAAO,CAAC,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC,MAAM,EAC9C;QACE,EAAE;QACF,eAAe;QACf,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;QAC3C,IAAI;KACL,EACD,SAAS,EACT,qBAAqB,CAAC,OAAO,CAAC,OAAO,CAAC,CACvC,CAAC;AACJ,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,iBAAiB,CAC/B,MAAmB,EACnB,EAAE,MAAM,EAAE,GAAG,OAAO,EAAe,EACnC,IAAmB,EACnB,SAAS,GAAoB,qBAAqB,EAAE;IAEpD,MAAM,GAAG,GAAG,UAAU,CACpB;QACE,MAAM;QACN,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC;YACrB,GAAG,OAAO;YACV,GAAG,CAAC,MAAM,KAAK,SAAS;gBACtB,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC;oBACE,MAAM,EAAE,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;iBACjE,CAAC;YACN,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC;SAC/B,CAAC;KACH,EACD,IAAI,CACL,CAAC;IACF,OAAO,kBAAkB,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;AAC5C,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,UAAU,CACxB,IAAwB,EACxB,YAAwC;IAExC,OAAO;QACL,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QACvC,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC;KACxD,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAI,KAAQ;IAC7B,OAAO,UAAU,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,UAAU,CAAI,KAAQ;IAC7B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;YAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/tools/definition.d.ts

@@ -4,9 +4,23 @@ import type { ToolContext } from "./context.js";
 import type { DeepReadonly, IsJsonCompatible, JsonCompatible } from "./json-value.js";
 import type { McpErrorResult, McpResult, McpStructuredResult } from "./rich-result.js";
 export declare const TOOL_METADATA_KEYS: readonly ["title", "description", "annotations", "icons", "_meta"];
+/**
+ * Optional client-facing tool title, description, behavior hints, icons, and `_meta`.
+ * Accepts readonly authoring data; registration checks JSON compatibility and copies
+ * metadata for wire descriptions. Hints describe behavior rather than enforce policy.
+ */
 export type ToolMetadata = DeepReadonly<Pick<ProtocolTool, (typeof TOOL_METADATA_KEYS)[number]>>;
+/**
+ * Authoring contract for `tool()`; handler input uses the parsed Zod output type.
+ *
+ * @typeParam Schema - Zod 4 Classic or Mini input schema with an exposable object root.
+ * @typeParam Result - Raw handler return value, including a promise-like value.
+ * @typeParam Output - Optional Zod output schema; the handler returns its input type.
+ */
 export interface ToolDefinition<Schema extends core.$ZodType, Result, Output extends core.$ZodType = never> extends ToolMetadata {
+    /** Input schema, parsed asynchronously by the server before the handler runs. */
     readonly input: Schema;
+    /** Optional output schema, parsed asynchronously before successful result conversion. */
     readonly output?: Output;
     /** Raw handler; server invocation performs validation and result conversion. */
     readonly execute: (input: core.output<Schema>, ctx: ToolContext) => Result;
@@ -29,27 +43,62 @@ export declare abstract class RegisteredTool {
 }
 /** Recognize definitions created by any compatible copy of this package. */
 export declare function isRegisteredTool(value: unknown): value is RegisteredTool;
+/**
+ * Frozen, reusable tool definition returned by `tool()`. Register the same definition
+ * under different keys or create typed variants by passing a spread through `tool()` again.
+ * Direct `execute()` calls remain raw application calls.
+ *
+ * @typeParam Schema - Input schema whose parsed output is passed to the handler.
+ * @typeParam Result - Raw handler return type, before server output parsing and conversion.
+ * @typeParam Output - Output schema when declared by the definition.
+ */
 export declare class Tool<Schema extends core.$ZodType, Result, Output extends core.$ZodType = core.$ZodType> extends RegisteredTool {
+    /** Zod input schema used by server validation; defaults and transforms run asynchronously. */
     readonly input: Schema;
+    /** Optional Zod output schema used by server result validation. */
     readonly output?: Output;
+    /** Raw handler; direct calls bypass authorization, input/output parsing, and MCP conversion. */
     readonly execute: (input: core.output<Schema>, ctx: ToolContext) => Result;
+    /** Optional human-readable title advertised to clients. */
     readonly title?: string;
+    /** Optional description explaining the tool's purpose and behavior to clients. */
     readonly description?: string;
+    /** Client-facing behavior hints; Toolgrain does not enforce their assertions. */
     readonly annotations?: NonNullable<ToolMetadata["annotations"]>;
+    /** Optional client-facing icon descriptors, with readonly authoring inputs. */
     readonly icons?: NonNullable<ToolMetadata["icons"]>;
+    /** Optional JSON-compatible protocol metadata advertised with the tool. */
     readonly _meta?: NonNullable<ToolMetadata["_meta"]>;
     constructor(definition: ToolDefinition<Schema, Result, core.$ZodType>);
 }
 type OutputResult<Output extends core.$ZodType> = core.input<Output> | McpStructuredResult<core.input<Output>> | McpErrorResult<core.input<Output>>;
 type JsonSafeOutput<Result> = Result extends PromiseLike<infer Resolved> ? PromiseLike<JsonSafeOutput<Resolved>> : Result extends McpResult<infer Structured> ? IsJsonCompatible<Structured> extends true ? Result : never : JsonCompatible<Result>;
 type ToolDefinitionWithoutOutput<Schema extends core.$ZodType, Result> = Omit<ToolDefinition<Schema, Result>, "execute"> & {
+    /** Raw handler accepting parsed input; server invocation validates its JSON-compatible result. */
     readonly execute: (input: core.output<Schema>, ctx: ToolContext) => Result & JsonSafeOutput<Result>;
 };
+/**
+ * Define a frozen tool with asynchronously validated input and declared output.
+ * Successful rich results must include `structuredContent`; explicit text-only errors may omit it.
+ *
+ * @param definition - Zod schemas, a handler returning the output schema's input type, and metadata.
+ * @returns A reusable tool retaining input, output, and handler inference.
+ * Its `execute` property stays raw; server invocation performs validation and conversion.
+ */
 export declare function tool<Schema extends core.$ZodType, Output extends core.$ZodType, Result extends OutputResult<NoInfer<Output>> | PromiseLike<OutputResult<NoInfer<Output>>>>(definition: ToolDefinition<Schema, Result, Output> & {
+    /** Required output schema for this overload; parses handler data before MCP conversion. */
     readonly output: Output;
 }): Tool<Schema, Result, Output> & {
+    /** Declared output schema, retained as required on the inferred tool type. */
     readonly output: Output;
 };
+/**
+ * Define a frozen tool without an output schema, preserving the handler's inferred return type.
+ * Ordinary strings and JSON values become MCP results; use `mcpResult()` for rich content.
+ *
+ * @param definition - Zod input schema, a JSON-compatible or explicit-result handler, and metadata.
+ * @returns A reusable tool whose direct `execute()` calls bypass server validation and conversion.
+ */
 export declare function tool<Schema extends core.$ZodType, Result>(definition: ToolDefinitionWithoutOutput<Schema, Result>): Tool<Schema, Result, never>;
 export {};
 //# sourceMappingURL=definition.d.ts.map

package/dist/tools/definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/tools/definition.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/tools/definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,KAAK,IAAI,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EACT,mBAAmB,EACpB,MAAM,kBAAkB,CAAC;AAE1B,eAAO,MAAM,kBAAkB,YAC7B,OAAO,EACP,aAAa,EACb,aAAa,EACb,OAAO,EACP,OAAO,CACC,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,YAAY,CACrC,IAAI,CAAC,YAAY,EAAE,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC,CACxD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,cAAc,CAC7B,MAAM,SAAS,IAAI,CAAC,QAAQ,EAC5B,MAAM,EACN,MAAM,SAAS,IAAI,CAAC,QAAQ,GAAG,KAAK,CACpC,SAAQ,YAAY;IACpB,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,WAAW,KAAK,MAAM,CAAC;CAC5E;AAKD,4EAA4E;AAC5E,8BAAsB,cAAc;IAClC,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC;IACvE,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC,CAAC;IACzE,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAE7D;;;OAGG;IACH,YAAY,IAAI,QAAQ,CAEvB;CACF;AAGD,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAMxE;AAED;;;;;;;;GAQG;AACH,qBAAa,IAAI,CACf,MAAM,SAAS,IAAI,CAAC,QAAQ,EAC5B,MAAM,EACN,MAAM,SAAS,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAC5C,SAAQ,cAAc;IACtB,8FAA8F;IAC9F,SAAiB,KAAK,EAAE,MAAM,CAAC;IAC/B,mEAAmE;IACnE,SAAiB,MAAM,CAAC,EAAE,MAAM,CAAC;IACjC,gGAAgG;IAChG,SAAiB,OAAO,EAAE,CACxB,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAC1B,GAAG,EAAE,WAAW,KACb,MAAM,CAAC;IACZ,2DAA2D;IAC3D,SAAiB,KAAK,CAAC,EAAE,MAAM,CAAC;IAChC,kFAAkF;IAClF,SAAiB,WAAW,CAAC,EAAE,MAAM,CAAC;IACtC,iFAAiF;IACjF,SAAiB,WAAW,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC,CAAC;IACxE,+EAA+E;IAC/E,SAAiB,KAAK,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5D,2EAA2E;IAC3E,SAAiB,KAAK,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAE5D,YAAY,UAAU,EAAE,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,EAUpE;CACF;AAED,KAAK,YAAY,CAAC,MAAM,SAAS,IAAI,CAAC,QAAQ,IAC1C,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAClB,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GACvC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;AAEvC,KAAK,cAAc,CAAC,MAAM,IACxB,MAAM,SAAS,WAAW,CAAC,MAAM,QAAQ,CAAC,GACtC,WAAW,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,GACrC,MAAM,SAAS,SAAS,CAAC,MAAM,UAAU,CAAC,GACxC,gBAAgB,CAAC,UAAU,CAAC,SAAS,IAAI,GACvC,MAAM,GACN,KAAK,GACP,cAAc,CAAC,MAAM,CAAC,CAAC;AAE/B,KAAK,2BAA2B,CAAC,MAAM,SAAS,IAAI,CAAC,QAAQ,EAAE,MAAM,IAAI,IAAI,CAC3E,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,SAAS,CACV,GAAG;IACF,kGAAkG;IAClG,QAAQ,CAAC,OAAO,EAAE,CAChB,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAC1B,GAAG,EAAE,WAAW,KACb,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;CACtC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAClB,MAAM,SAAS,IAAI,CAAC,QAAQ,EAC5B,MAAM,SAAS,IAAI,CAAC,QAAQ,EAC5B,MAAM,SACF,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAC7B,WAAW,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAE9C,UAAU,EAAE,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG;IACnD,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GACA,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AACF;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,MAAM,SAAS,IAAI,CAAC,QAAQ,EAAE,MAAM,EACvD,UAAU,EAAE,2BAA2B,CAAC,MAAM,EAAE,MAAM,CAAC,GACtD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC"}

package/dist/tools/definition.js

@@ -24,6 +24,15 @@ export function isRegisteredTool(value) {
         value !== null &&
         value[TOOL_BRAND] === true);
 }
+/**
+ * Frozen, reusable tool definition returned by `tool()`. Register the same definition
+ * under different keys or create typed variants by passing a spread through `tool()` again.
+ * Direct `execute()` calls remain raw application calls.
+ *
+ * @typeParam Schema - Input schema whose parsed output is passed to the handler.
+ * @typeParam Result - Raw handler return type, before server output parsing and conversion.
+ * @typeParam Output - Output schema when declared by the definition.
+ */
 export class Tool extends RegisteredTool {
     constructor(definition) {
         super();

package/dist/tools/definition.js.map

@@ -1 +1 @@
-{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../src/tools/definition.ts"],"names":[],"mappings":"AAcA,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,OAAO;IACP,aAAa;IACb,aAAa;IACb,OAAO;IACP,OAAO;CACC,CAAC;AAiBX,gFAAgF;AAChF,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAEvD,4EAA4E;AAC5E,MAAM,OAAgB,cAAc;IAUlC;;;OAGG;IACH,YAAY;QACV,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF;AACD,MAAM,CAAC,cAAc,CAAC,cAAc,CAAC,SAAS,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAE7E,4EAA4E;AAC5E,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAoC,CAAC,UAAU,CAAC,KAAK,IAAI,CAC3D,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,IAIX,SAAQ,cAAc;IAatB,YAAY,UAAyD;QACnE,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC;QAC9B,IAAI,CAAC,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC;QAClC,KAAK,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,kBAAkB,CAAU,EAAE,CAAC;YAC7D,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;YAC9B,IAAI,KAAK,KAAK,SAAS;gBACrB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;CACF;AAwCD,gFAAgF;AAChF,MAAM,UAAU,IAAI,CAClB,UAAyD;IAEzD,OAAO,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../src/tools/definition.ts"],"names":[],"mappings":"AAcA,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,OAAO;IACP,aAAa;IACb,aAAa;IACb,OAAO;IACP,OAAO;CACC,CAAC;AA+BX,gFAAgF;AAChF,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAEvD,4EAA4E;AAC5E,MAAM,OAAgB,cAAc;IAUlC;;;OAGG;IACH,YAAY;QACV,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF;AACD,MAAM,CAAC,cAAc,CAAC,cAAc,CAAC,SAAS,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAE7E,4EAA4E;AAC5E,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAoC,CAAC,UAAU,CAAC,KAAK,IAAI,CAC3D,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,IAIX,SAAQ,cAAc;IAqBtB,YAAY,UAAyD;QACnE,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC;QAC9B,IAAI,CAAC,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC;QAClC,KAAK,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,kBAAkB,CAAU,EAAE,CAAC;YAC7D,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;YAC9B,IAAI,KAAK,KAAK,SAAS;gBACrB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;CACF;AA4DD,gFAAgF;AAChF,MAAM,UAAU,IAAI,CAClB,UAAyD;IAEzD,OAAO,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC;AAC9B,CAAC"}

package/dist/tools/name.d.ts

@@ -1,6 +1,11 @@
+/** Registration error for a name outside 1–128 ASCII letters, digits, underscores, hyphens, or dots. */
 export declare class ToolNameError extends Error {
+    /** Invalid exposed registration name. */
     readonly toolName: string;
-    constructor(toolName: string);
+    /** @param toolName - Invalid registration key that could not be exposed as an MCP tool name. */
+    constructor(
+    /** Invalid exposed registration name. */
+    toolName: string);
 }
 export declare function validateToolName(name: string): void;
 //# sourceMappingURL=name.d.ts.map

package/dist/tools/name.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"name.d.ts","sourceRoot":"","sources":["../../src/tools/name.ts"],"names":[],"mappings":"AAAA,qBAAa,aAAc,SAAQ,KAAK;aACV,QAAQ,EAAE,MAAM;IAA5C,YAA4B,QAAQ,EAAE,MAAM,EAK3C;CACF;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAGnD"}
+{"version":3,"file":"name.d.ts","sourceRoot":"","sources":["../../src/tools/name.ts"],"names":[],"mappings":"AAAA,wGAAwG;AACxG,qBAAa,aAAc,SAAQ,KAAK;IAGpC,yCAAyC;aACzB,QAAQ,EAAE,MAAM;IAHlC,gGAAgG;IAChG;IACE,yCAAyC;IACzB,QAAQ,EAAE,MAAM,EAMjC;CACF;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAGnD"}

package/dist/tools/name.js

@@ -1,6 +1,10 @@
+/** Registration error for a name outside 1–128 ASCII letters, digits, underscores, hyphens, or dots. */
 export class ToolNameError extends Error {
     toolName;
-    constructor(toolName) {
+    /** @param toolName - Invalid registration key that could not be exposed as an MCP tool name. */
+    constructor(
+    /** Invalid exposed registration name. */
+    toolName) {
         super(`Invalid MCP tool name: ${JSON.stringify(toolName)}. Use 1–128 ASCII letters, digits, underscores, hyphens, or dots.`);
         this.toolName = toolName;
         this.name = "ToolNameError";

package/dist/tools/name.js.map

@@ -1 +1 @@
-{"version":3,"file":"name.js","sourceRoot":"","sources":["../../src/tools/name.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,aAAc,SAAQ,KAAK;IACV,QAAQ;IAApC,YAA4B,QAAgB;QAC1C,KAAK,CACH,0BAA0B,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,mEAAmE,CACtH,CAAC;wBAHwB,QAAQ;QAIlC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,IAAI,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC;QACtE,MAAM,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC"}
+{"version":3,"file":"name.js","sourceRoot":"","sources":["../../src/tools/name.ts"],"names":[],"mappings":"AAAA,wGAAwG;AACxG,MAAM,OAAO,aAAc,SAAQ,KAAK;IAIpB,QAAQ;IAH1B,gGAAgG;IAChG;IACE,yCAAyC;IACzB,QAAgB;QAEhC,KAAK,CACH,0BAA0B,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,mEAAmE,CACtH,CAAC;wBAJc,QAAQ;QAKxB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,IAAI,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC;QACtE,MAAM,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC"}

package/dist/tools/registry.d.ts

@@ -1,5 +1,9 @@
 import type { ToolContext } from "./context.js";
 import { type RegisteredTool, type ToolMetadata } from "./definition.js";
+/**
+ * Tools indexed by exposed MCP names. Values must be frozen definitions made with `tool()`;
+ * names come from these keys, not from a definition's variable name or title.
+ */
 export type ToolMap = Record<string, RegisteredTool>;
 export interface ToolEntry extends ToolMetadata {
     name: string;

package/dist/tools/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC;AAGzB,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAErD,MAAM,WAAW,SAAU,SAAQ,YAAY;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,IAAI,SAAS,EAAE,CAAC;IACpB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3E;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CA6BvD"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC;AAGzB;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAErD,MAAM,WAAW,SAAU,SAAQ,YAAY;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,IAAI,SAAS,EAAE,CAAC;IACpB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3E;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CA6BvD"}

package/dist/tools/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AAEpC,OAAO,EACL,gBAAgB,GAGjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAe/D,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,MAAM,OAAO,GAAG,IAAI,GAAG,CACrB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,EAAE;QAC/C,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC;YAC/B,MAAM,IAAI,SAAS,CACjB,QAAQ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,8BAA8B,CAC3D,CAAC;QACJ,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,UAAU,EAAE,CAAC,CAAU,CAAC;IAC3D,CAAC,CAAC,CACH,CAAC;IAEF,OAAO;QACL,IAAI;YACF,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,EAAE;gBAChD,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,GAAG,UAAU,CAAC;gBACtD,OAAO,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAC;YAC/B,CAAC,CAAC,CAAC;QACL,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG;YAC5B,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,CAAC,UAAU;gBAAE,MAAM,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC;YAClD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAClE,IAAI,CAAC,MAAM,CAAC,OAAO;gBAAE,MAAM,IAAI,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;YAClE,kEAAkE;YAClE,GAAG,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;YAC5B,4EAA4E;YAC5E,OAAO,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,IAAa,EAAE,GAAG,CAAC,CAAC;QACvD,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AAEpC,OAAO,EACL,gBAAgB,GAGjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAmB/D,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,MAAM,OAAO,GAAG,IAAI,GAAG,CACrB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,EAAE;QAC/C,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC;YAC/B,MAAM,IAAI,SAAS,CACjB,QAAQ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,8BAA8B,CAC3D,CAAC;QACJ,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,UAAU,EAAE,CAAC,CAAU,CAAC;IAC3D,CAAC,CAAC,CACH,CAAC;IAEF,OAAO;QACL,IAAI;YACF,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,EAAE;gBAChD,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,GAAG,UAAU,CAAC;gBACtD,OAAO,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAC;YAC/B,CAAC,CAAC,CAAC;QACL,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG;YAC5B,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,CAAC,UAAU;gBAAE,MAAM,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC;YAClD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAClE,IAAI,CAAC,MAAM,CAAC,OAAO;gBAAE,MAAM,IAAI,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;YAClE,kEAAkE;YAClE,GAAG,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;YAC5B,4EAA4E;YAC5E,OAAO,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,IAAa,EAAE,GAAG,CAAC,CAAC;QACvD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/rich-result.d.ts

@@ -1,44 +1,98 @@
 import type { ContentBlock, MetaObject } from "@toolgrain/protocol";
 import type { DeepReadonly, JsonCompatible } from "./json-value.js";
+/** Explicit MCP content and optional structured data, wrapped with `mcpResult()`. */
 export interface McpResultOptions<Structured = unknown> {
+    /** Content blocks for the client; readonly authoring arrays are accepted. */
     content: readonly DeepReadonly<ContentBlock>[];
+    /** JSON-compatible data; required for successful rich results with a declared output schema. */
     structuredContent?: Structured & JsonCompatible<NoInfer<Structured>>;
+    /** Marks an expected, client-visible tool failure; omitted or false indicates success. */
     isError?: boolean;
+    /** Optional protocol result metadata, distinct from application structured data. */
     _meta?: MetaObject;
 }
+/**
+ * Branded rich-result wrapper recognized by compatible Toolgrain package copies.
+ * Use `mcpResult()` to construct one; a plain object with the same fields remains application data.
+ */
 export declare class McpResult<Structured> {
+    /** Explicit MCP result envelope, before server validation and revision-specific conversion. */
     readonly value: McpResultOptions<Structured>;
-    constructor(value: McpResultOptions<Structured>);
+    constructor(
+    /** Explicit MCP result envelope, before server validation and revision-specific conversion. */
+    value: McpResultOptions<Structured>);
     /** Structural brand shared by package copies; object spreads do not keep it. */
     "~toolgrain"(): "result@1";
 }
 /** Recognize results created by any compatible copy of this package. */
 export declare function isMcpResult(value: unknown): value is McpResult<unknown>;
+/** Explicit, client-visible tool error; structured data may be omitted for text-only errors. */
 export type McpErrorResult<Structured = never> = McpResult<Structured> & {
+    /** Envelope statically marked as an error. */
     readonly value: McpResultOptions<Structured> & {
+        /** Explicit expected-failure marker, preserved in the MCP result. */
         isError: true;
     };
 };
 /** A result whose structured data is present, as required by an output schema. */
 export type McpStructuredResult<Structured> = McpResult<Structured> & {
+    /** Envelope with required application structured data. */
     readonly value: McpResultOptions<Structured> & {
+        /** Structured value validated against the tool's output schema when one is declared. */
         structuredContent: Structured;
     };
 };
-/** Explicitly return MCP content. Ordinary objects always remain application data. */
+/**
+ * Explicitly return rich MCP content; ordinary result-shaped objects remain application data.
+ * This overload wraps a public tool error that also supplies structured data.
+ * @param value - Error content and JSON-compatible data, parsed by any declared output schema.
+ * @returns A branded result typed as both an error and a structured result.
+ */
 export declare function mcpResult<Structured = never>(value: McpResultOptions<Structured> & {
+    /** Mark this result as an expected, client-visible tool failure. */
     isError: true;
+    /** Structured error data, subject to output-schema validation when declared. */
     structuredContent: Structured;
 }): McpErrorResult<Structured> & McpStructuredResult<Structured>;
+/**
+ * Wrap a text/content-only public tool error, allowed even when the tool declares output.
+ * @param value - Explicit error content without structured application data.
+ * @returns A branded error result whose `isError` flag is statically true.
+ */
 export declare function mcpResult(value: McpResultOptions<never> & {
+    /** Mark this result as an expected, client-visible tool failure. */
     isError: true;
 }): McpErrorResult<never>;
+/**
+ * Wrap a public tool error with an optional structured-data contract.
+ * @param value - Error content and any JSON-compatible structured data.
+ * @returns A branded error result; provided structured data still undergoes output validation.
+ */
 export declare function mcpResult<Structured>(value: McpResultOptions<Structured> & {
+    /** Mark this result as an expected, client-visible tool failure. */
     isError: true;
 }): McpErrorResult<Structured>;
+/**
+ * Wrap rich content with required structured application data.
+ * @param value - Client content and JSON-compatible data; a successful output-schema result needs both.
+ * @returns A branded structured result; the server validates and converts it for the selected revision.
+ */
 export declare function mcpResult<Structured>(value: McpResultOptions<Structured> & {
+    /** Required application data, parsed by the declared output schema when present. */
     structuredContent: Structured;
 }): McpStructuredResult<Structured>;
+/**
+ * Wrap explicit client content without structured application data.
+ * @param value - Rich content; successful results of this form require a tool without an output schema.
+ * @returns A branded MCP result. Ordinary result-shaped objects are not treated as rich results.
+ */
 export declare function mcpResult(value: McpResultOptions<never>): McpResult<never>;
+/**
+ * Explicitly return MCP content instead of ordinary application JSON.
+ * The server validates the envelope, parses supplied output data, and converts it for the protocol revision.
+ *
+ * @param value - Content blocks, optional structured data, an error marker, and protocol metadata.
+ * @returns A frozen result wrapper; content is checked during server invocation.
+ */
 export declare function mcpResult<Structured = never>(value: McpResultOptions<Structured>): McpResult<Structured>;
 //# sourceMappingURL=rich-result.d.ts.map

package/dist/tools/rich-result.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rich-result.d.ts","sourceRoot":"","sources":["../../src/tools/rich-result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEpE,MAAM,WAAW,gBAAgB,CAAC,UAAU,GAAG,OAAO;IACpD,OAAO,EAAE,SAAS,YAAY,CAAC,YAAY,CAAC,EAAE,CAAC;IAC/C,iBAAiB,CAAC,EAAE,UAAU,GAAG,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;IACrE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAKD,qBAAa,SAAS,CAAC,UAAU;IACnB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC;IAAxD,YAAqB,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC,EAEvD;IAED,gFAAgF;IAChF,YAAY,IAAI,UAAU,CAEzB;CACF;AAGD,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAAC,OAAO,CAAC,CAMvE;AAED,MAAM,MAAM,cAAc,CAAC,UAAU,GAAG,KAAK,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG;IACvE,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAAG;QAAE,OAAO,EAAE,IAAI,CAAA;KAAE,CAAC;CAClE,CAAC;AAEF,kFAAkF;AAClF,MAAM,MAAM,mBAAmB,CAAC,UAAU,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG;IACpE,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAAG;QAC7C,iBAAiB,EAAE,UAAU,CAAC;KAC/B,CAAC;CACH,CAAC;AAEF,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,UAAU,GAAG,KAAK,EAC1C,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAAG;IACpC,OAAO,EAAE,IAAI,CAAC;IACd,iBAAiB,EAAE,UAAU,CAAC;CAC/B,GACA,cAAc,CAAC,UAAU,CAAC,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;AAChE,wBAAgB,SAAS,CACvB,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GACjD,cAAc,CAAC,KAAK,CAAC,CAAC;AACzB,wBAAgB,SAAS,CAAC,UAAU,EAClC,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GACtD,cAAc,CAAC,UAAU,CAAC,CAAC;AAC9B,wBAAgB,SAAS,CAAC,UAAU,EAClC,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAAG;IAAE,iBAAiB,EAAE,UAAU,CAAA;CAAE,GACtE,mBAAmB,CAAC,UAAU,CAAC,CAAC;AACnC,wBAAgB,SAAS,CAAC,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;AAC5E,wBAAgB,SAAS,CAAC,UAAU,GAAG,KAAK,EAC1C,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAClC,SAAS,CAAC,UAAU,CAAC,CAAC"}
+{"version":3,"file":"rich-result.d.ts","sourceRoot":"","sources":["../../src/tools/rich-result.ts"],"names":[],"mappings":"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"}

package/dist/tools/rich-result.js

@@ -1,8 +1,14 @@
 // Registered symbols let duplicate package copies recognize each other's results.
 const RESULT_BRAND = Symbol.for("@toolgrain/mcp/result@1");
+/**
+ * Branded rich-result wrapper recognized by compatible Toolgrain package copies.
+ * Use `mcpResult()` to construct one; a plain object with the same fields remains application data.
+ */
 export class McpResult {
     value;
-    constructor(value) {
+    constructor(
+    /** Explicit MCP result envelope, before server validation and revision-specific conversion. */
+    value) {
         this.value = value;
         Object.freeze(this);
     }

package/dist/tools/rich-result.js.map

@@ -1 +1 @@
-{"version":3,"file":"rich-result.js","sourceRoot":"","sources":["../../src/tools/rich-result.ts"],"names":[],"mappings":"AAUA,kFAAkF;AAClF,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAE3D,MAAM,OAAO,SAAS;IACC,KAAK;IAA1B,YAAqB,KAAmC;qBAAnC,KAAK;QACxB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAED,gFAAgF;IAChF,YAAY;QACV,OAAO,UAAU,CAAC;IACpB,CAAC;CACF;AACD,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAE1E,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAsC,CAAC,YAAY,CAAC,KAAK,IAAI,CAC/D,CAAC;AACJ,CAAC;AAiCD,MAAM,UAAU,SAAS,CACvB,KAAmC;IAEnC,OAAO,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"rich-result.js","sourceRoot":"","sources":["../../src/tools/rich-result.ts"],"names":[],"mappings":"AAeA,kFAAkF;AAClF,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAE3D;;;GAGG;AACH,MAAM,OAAO,SAAS;IAGT,KAAK;IAFhB;IACE,+FAA+F;IACtF,KAAmC;qBAAnC,KAAK;QAEd,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAED,gFAAgF;IAChF,YAAY;QACV,OAAO,UAAU,CAAC;IACpB,CAAC;CACF;AACD,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAE1E,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAsC,CAAC,YAAY,CAAC,KAAK,IAAI,CAC/D,CAAC;AACJ,CAAC;AAmFD,MAAM,UAAU,SAAS,CACvB,KAAmC;IAEnC,OAAO,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC"}

package/dist/tools/schema.d.ts

@@ -9,10 +9,22 @@ export declare const toolAnnotations: z.ZodObject<{
     idempotentHint: z.ZodOptional<z.ZodBoolean>;
     openWorldHint: z.ZodOptional<z.ZodBoolean>;
 }, core.$loose>;
+/** Registration error wrapping a schema-conversion or metadata-validation failure. */
 export declare class ToolSchemaError extends Error {
+    /** Exposed registration name whose schema or metadata failed. */
     readonly toolName: string;
+    /** Whether input conversion, output conversion, or metadata validation failed. */
     readonly schemaKind: "input" | "output" | "metadata";
-    constructor(toolName: string, cause: unknown, schemaKind?: "input" | "output" | "metadata");
+    /**
+     * @param toolName - Exposed registration name whose description could not be built.
+     * @param cause - Original schema or metadata failure, retained as the error's cause.
+     * @param schemaKind - Failing part of the description; defaults to `input`.
+     */
+    constructor(
+    /** Exposed registration name whose schema or metadata failed. */
+    toolName: string, cause: unknown, 
+    /** Whether input conversion, output conversion, or metadata validation failed. */
+    schemaKind?: "input" | "output" | "metadata");
 }
 export declare function describeTool(name: string, definition: Pick<ToolMap[string], "input" | "output" | "title" | "description" | "icons" | "annotations" | "_meta">): ProtocolTool;
 //# sourceMappingURL=schema.d.ts.map

package/dist/tools/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/tools/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AAMpC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,eAAO,MAAM,eAAe;;;;;;eAM1B,CAAC;AAUH,qBAAa,eAAgB,SAAQ,KAAK;aAEtB,QAAQ,EAAE,MAAM;aAEhB,UAAU,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU;IAH7D,YACkB,QAAQ,EAAE,MAAM,EAChC,KAAK,EAAE,OAAO,EACE,UAAU,GAAE,OAAO,GAAG,QAAQ,GAAG,UAAoB,EAMtE;CACF;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,IAAI,CACd,OAAO,CAAC,MAAM,CAAC,EACb,OAAO,GACP,QAAQ,GACR,OAAO,GACP,aAAa,GACb,OAAO,GACP,aAAa,GACb,OAAO,CACV,GACA,YAAY,CAkCd"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/tools/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AAMpC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,eAAO,MAAM,eAAe;;;;;;eAM1B,CAAC;AAUH,sFAAsF;AACtF,qBAAa,eAAgB,SAAQ,KAAK;IAOtC,iEAAiE;aACjD,QAAQ,EAAE,MAAM;IAEhC,kFAAkF;aAClE,UAAU,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU;IAV7D;;;;OAIG;IACH;IACE,iEAAiE;IACjD,QAAQ,EAAE,MAAM,EAChC,KAAK,EAAE,OAAO;IACd,kFAAkF;IAClE,UAAU,GAAE,OAAO,GAAG,QAAQ,GAAG,UAAoB,EAMtE;CACF;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,IAAI,CACd,OAAO,CAAC,MAAM,CAAC,EACb,OAAO,GACP,QAAQ,GACR,OAAO,GACP,aAAa,GACb,OAAO,GACP,aAAa,GACb,OAAO,CACV,GACA,YAAY,CAkCd"}

package/dist/tools/schema.js

@@ -19,10 +19,20 @@ const metadata = z.strictObject({
     annotations: toolAnnotations.optional(),
     _meta: object.optional(),
 });
+/** Registration error wrapping a schema-conversion or metadata-validation failure. */
 export class ToolSchemaError extends Error {
     toolName;
     schemaKind;
-    constructor(toolName, cause, schemaKind = "input") {
+    /**
+     * @param toolName - Exposed registration name whose description could not be built.
+     * @param cause - Original schema or metadata failure, retained as the error's cause.
+     * @param schemaKind - Failing part of the description; defaults to `input`.
+     */
+    constructor(
+    /** Exposed registration name whose schema or metadata failed. */
+    toolName, cause, 
+    /** Whether input conversion, output conversion, or metadata validation failed. */
+    schemaKind = "input") {
         super(`Cannot expose ${schemaKind} schema for tool: ${toolName}`, {
             cause,
         });

package/dist/tools/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/tools/schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/tools/schema.ts"],"names":[],"mappings":"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"}

package/dist/transport.d.ts

@@ -2,22 +2,43 @@ import type { ProtocolResponse } from "@toolgrain/protocol";
 import type { Server } from "./server.js";
 /** Callbacks are synchronous; message processing runs independently. */
 export interface TransportCallbacks {
+    /** Deliver one JSON-decoded message without waiting for asynchronous protocol processing. */
     onMessage(message: unknown): void;
+    /** Report invalid JSON or framing so the server can send a protocol parse error. */
     onParseError(error: unknown): void;
+    /** Report a fatal transport failure; the server records it and closes the connection. */
     onError(error: unknown): void;
+    /** Notify the server of end-of-input or transport closure so active work can be aborted. */
     onClose(): void;
 }
 /** Single-use adapters own UTF-8 framing, JSON decoding, and stream cleanup. */
 export interface Transport {
+    /** Message-transport discriminator; may be omitted for custom message adapters. */
     readonly mode?: "message";
+    /**
+     * Start delivery once and resolve when ready. Call `Server.listen()` to establish ownership.
+     * @param callbacks - Synchronous message and lifecycle notifications supplied by the server.
+     */
     start(callbacks: TransportCallbacks): Promise<void>;
+    /**
+     * Send one protocol response, resolving after the adapter's write/backpressure handling.
+     * @param message - Response envelope already converted for the client's protocol revision.
+     */
     send(message: ProtocolResponse): Promise<void>;
+    /** Release adapter-owned resources; closing is terminal and must tolerate repeated calls. */
     close(): Promise<void>;
 }
 /** Single-use request transports own listeners and use per-request authorization. */
 export interface RequestTransport {
+    /** Identifies an independent-request transport, required by auth-configured servers. */
     readonly mode: "request";
+    /**
+     * Start the owned listener once and resolve when ready; invoked through `Server.listen()`.
+     * @param server - Server used for per-request authorization and protocol dispatch.
+     * @param callbacks - Fatal-error and closure notifications supplied by the server.
+     */
     start(server: Server, callbacks: Pick<TransportCallbacks, "onError" | "onClose">): Promise<void>;
+    /** Stop the owned listener and active connections; closing is terminal and idempotent. */
     close(): Promise<void>;
 }
 export declare function isRequestTransport(transport: Transport | RequestTransport): transport is RequestTransport;

package/dist/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,wEAAwE;AACxE,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,KAAK,CAAC,SAAS,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,KAAK,CACH,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,SAAS,CAAC,GACzD,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,GAAG,gBAAgB,GACtC,SAAS,IAAI,gBAAgB,CAE/B"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,wEAAwE;AACxE,MAAM,WAAW,kBAAkB;IACjC,6FAA6F;IAC7F,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,oFAAoF;IACpF,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,yFAAyF;IACzF,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,4FAA4F;IAC5F,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACxB,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,SAAS,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,6FAA6F;IAC7F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB;;;;OAIG;IACH,KAAK,CACH,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,SAAS,CAAC,GACzD,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,0FAA0F;IAC1F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,GAAG,gBAAgB,GACtC,SAAS,IAAI,gBAAgB,CAE/B"}

package/dist/transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AA6BA,MAAM,UAAU,kBAAkB,CAChC,SAAuC;IAEvC,OAAO,MAAM,IAAI,SAAS,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC;AAC7D,CAAC"}
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAkDA,MAAM,UAAU,kBAAkB,CAChC,SAAuC;IAEvC,OAAO,MAAM,IAAI,SAAS,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC;AAC7D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolgrain/mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Define reusable, typed MCP tools and servers with Zod validation.",
   "license": "MIT",
   "repository": {
@@ -8,7 +8,7 @@
     "url": "git+https://github.com/keshavkatwe/toolgrain.git",
     "directory": "packages/mcp"
   },
-  "homepage": "https://github.com/keshavkatwe/toolgrain/tree/main/packages/mcp#readme",
+  "homepage": "https://toolgrain.mintlify.site/reference/mcp",
   "bugs": {
     "url": "https://github.com/keshavkatwe/toolgrain/issues"
   },
@@ -59,7 +59,7 @@
     "@toolgrain/repo-tools": "0.0.0"
   },
   "dependencies": {
-    "@toolgrain/protocol": "0.1.1"
+    "@toolgrain/protocol": "0.1.3"
   },
   "engines": {
     "node": "^24.20.0",

package/src/auth/audience.ts

@@ -1,6 +1,14 @@
 import { AuthError } from "./errors.js";
 
-/** Validate the audience of an already verified token without disclosing its claims. */
+/**
+ * Require an already verified token's audience to contain the exact MCP resource URL.
+ * This checks only audience membership, not signatures, issuers, expiry, or revocation.
+ *
+ * @param audience - Verified `aud` claim: a string or array of strings.
+ * @param resource - Expected resource URL to match exactly.
+ * @throws `AuthError` with `invalid_token` for missing, malformed, or mismatched audiences.
+ * Missing and mismatched claims include public guidance without disclosing received claims.
+ */
 export function validateTokenAudience(
   audience: unknown,
   resource: string,