@chrischall/mcp-utils 2.0.0 → 2.2.0

package/README.md

@@ -32,7 +32,7 @@ import light:
 
 | Import | Contents |
 | --- | --- |
-| `@chrischall/mcp-utils` | core barrel: `server` + `response` + `errors` + `config` + `fs` + `http` + `cancel` + `concurrency` + `dates` + `zod` + `auth` + `scrape` |
+| `@chrischall/mcp-utils` | core barrel: `server` + `response` + `errors` + `config` + `fs` + `http` + `cancel` + `caller` + `concurrency` + `dates` + `zod` + `auth` + `scrape` |
 | `@chrischall/mcp-utils/session` | session registry, session store, state persistence, token manager, cookie-session manager |
 | `@chrischall/mcp-utils/fetchproxy` | fetchproxy transport adapter, bot-wall / retry / concurrency helpers |
 | `@chrischall/mcp-utils/healthcheck` | credential-style healthcheck factory (no fetchproxy peer needed) |
@@ -40,6 +40,12 @@ import light:
 | `@chrischall/mcp-utils/scrape` | convenience alias for the zero-dep `scrape` module (also in the core barrel) |
 | `@chrischall/mcp-utils/test` | in-memory test harness for tool registration |
 
+See **[`docs/CLIENT-BEHAVIOUR.md`](docs/CLIENT-BEHAVIOUR.md)** for what MCP
+clients measurably support and *honour* — including why an unannotated tool
+publishes as destructive, why `structuredContent` is dead weight on
+claude.ai, and the three silent SDK gotchas around cancellation and
+progress.
+
 ```ts
 import { createMcpServer, textResult, requireEnvVar } from '@chrischall/mcp-utils';
 import { createSessionRegistry } from '@chrischall/mcp-utils/session';
@@ -457,6 +463,72 @@ half-committed write simply does not ask. Outside a tool call — a unit test,
 a CLI — `currentCallSignal()` is `undefined`, which every consumer must read
 as "no cancellation".
 
+#### Progress
+
+The same store carries the caller's progress token, so a long tool can say
+how far along it is:
+
+```ts
+import { callerWantsProgress, reportProgress } from '@chrischall/mcp-utils';
+
+for (const [i, page] of pages.entries()) {
+  await reportProgress(i + 1, pages.length, `page ${i + 1}`);
+  // …
+}
+```
+
+MEASURED support, which is why it is here: claude.ai sends
+`_meta.progressToken` on its `tools/call` requests (mcp-host usage rows,
+2026-09-20), so progress a hosted MCP reports genuinely arrives. A caller
+that did not ask has no token and `reportProgress` is a no-op —
+`callerWantsProgress()` is there for skipping work nobody will see.
+
+Three things about the SDK make this worth a helper rather than three lines
+at each call site, because **none of them throws** and all three look
+identical to working code from the server's side:
+
+- `notify` takes a notification OBJECT, not `(method, params)`. Handed a
+  string it spreads it character by character and puts
+  `{"0":"n","1":"o",…}` on the wire, which the peer rejects as
+  `Unknown message type`.
+- The caller's token lives at `_meta`, not `meta`. Read the wrong one and
+  the notification goes out well-formed but tokenless, and the client
+  discards it as *"progress notification for an unknown token"*.
+- Sending progress when the caller asked for none produces exactly that
+  error at the client, so the no-op matters.
+
+### `caller` — what the CALLER can do, made readable
+
+A confirmation-guarded tool returns `input_required`, and the SDK refuses to
+deliver one to a client that declared no `elicitation` — a protocol `-32021`
+raised **after** the handler returned, so the handler cannot catch it and the
+caller sees only an opaque failure. Measured on the mcp-host fleet
+2026-09-20: claude.ai declares `{"extensions": {…}}` and no `elicitation`, so
+`gog_gmail_forward` answered four attempts in a row in under 110 ms, having
+never run.
+
+`callerAcceptsFormElicitation(ctx)` answers before the handler returns, so
+`requireConfirmation` can refuse with a sentence instead of a prompt
+nothing will deliver.
+
+```ts
+import { callerAcceptsFormElicitation, callerCapabilities } from '@chrischall/mcp-utils';
+
+if (callerAcceptsFormElicitation(ctx) === false) { /* say so; do not prompt */ }
+```
+
+Two sources, because the answer lives in two places: a 2026-07-28 request
+carries the caller's own declaration in its `_meta` envelope — and a relay
+forwards the *real* caller's per request, so the envelope **wins** over
+anything connection-scoped — while a 2025 connection declared its
+capabilities once at `initialize`, where only the low-level `Server` kept
+them. `surfaceToolHints` reads that second source and stores it ambiently.
+
+**Absence is never a verdict.** With neither source available the helpers
+answer `undefined`, never `false`; reading "cannot tell" as "cannot" would
+refuse every caller this cannot see, including handlers registered outside
+`surfaceToolHints`.
+
 ### `concurrency` — bounded async map & single-flight
 
 `mapWithConcurrency`, `singleFlight`, `memoizeAsync` — zero-dependency async

package/dist/caller/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * What the CALLER can do, made readable from inside a tool handler.
+ *
+ * ## The gap this closes
+ *
+ * A confirmation-guarded tool returns `input_required`, and the SDK refuses
+ * to send it to a client that did not declare `elicitation` — a protocol
+ * error (`-32021`) raised AFTER the handler returned, so the handler cannot
+ * catch it and the caller is told nothing useful. Measured on the mcp-host
+ * fleet 2026-09-20: claude.ai declares `{"extensions": {…}}` and no
+ * `elicitation`, so `gog_gmail_forward` answered four attempts in a row with
+ * an opaque "Error occurred during tool execution" in 69–107 ms, having never
+ * run. The only way out is for the handler to know BEFORE it returns.
+ *
+ * ## Where the answer lives, and why it takes two sources
+ *
+ * On protocol revision 2026-07-28 each request carries its own `_meta`
+ * envelope, so the caller's capabilities are on `ctx.mcpReq.envelope` — and
+ * that is the era the mcp-host relay uses, forwarding the real caller's
+ * declaration rather than the connection's. On a 2025-era connection there is
+ * no envelope: the capabilities were declared once at `initialize` and only
+ * the underlying {@link Server} holds them. `surfaceToolHints` is the one
+ * wrapper every tool already passes through AND the one place with a
+ * reference to that server, so it reads the second source and stores it here.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * It answers `undefined` — never "no" — when neither source is available.
+ * A missing answer is not a negative one, and treating it as one would refuse
+ * every caller this cannot see, which includes any handler registered outside
+ * `surfaceToolHints`. Absence is never a verdict.
+ */
+/** The capability map a client declares, as far as this module cares about it. */
+export interface CallerCapabilities {
+    readonly elicitation?: Record<string, unknown>;
+    readonly [key: string]: unknown;
+}
+/**
+ * Run `fn` with `capabilities` as the ambient caller declaration for its whole
+ * async extent. Called by `surfaceToolHints` once per tool call.
+ *
+ * A caller whose capabilities could not be resolved runs `fn` unwrapped rather
+ * than storing `undefined`: an empty store and no store are the same answer to
+ * {@link currentCallerCapabilities}.
+ */
+export declare function withCallerCapabilities<T>(capabilities: CallerCapabilities | undefined, fn: () => T): T;
+/** The ambient caller capabilities, or `undefined` outside a wrapped tool call. */
+export declare function currentCallerCapabilities(): CallerCapabilities | undefined;
+/**
+ * The caller's declared capabilities for THIS call: the request's own envelope
+ * when the era carries one, else whatever `surfaceToolHints` stored.
+ *
+ * The envelope wins because it is per request. On the 2026-07-28 era a relay
+ * forwards the real caller's declaration with every call, so two callers on
+ * one connection can differ — and the ambient value, resolved once from the
+ * connection, would answer about the wrong one.
+ */
+export declare function callerCapabilities(ctx: unknown): CallerCapabilities | undefined;
+/**
+ * Whether this caller can be shown a FORM elicitation — the shape every
+ * {@link requireConfirmation} prompt uses.
+ *
+ * `undefined` means "cannot tell", which callers must not read as `false`.
+ *
+ * Mirrors the SDK's own gate, verified against `@modelcontextprotocol/server`
+ * 2.0.0 by driving all four shapes through a real client: `elicitation` absent
+ * refuses; `{url: {}}` refuses (a URL elicitation cannot carry a schema);
+ * `{form: {}}` passes; and `{}` — modes not enumerated — PASSES, because a
+ * client that named no mode is not a client that excluded this one.
+ */
+export declare function callerAcceptsFormElicitation(ctx: unknown): boolean | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/caller/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/caller/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,kFAAkF;AAClF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/C,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAID;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,YAAY,EAAE,kBAAkB,GAAG,SAAS,EAC5C,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAEH;AAED,mFAAmF;AACnF,wBAAgB,yBAAyB,IAAI,kBAAkB,GAAG,SAAS,CAE1E;AAYD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,GAAG,SAAS,CAO/E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAO9E"}

package/dist/caller/index.js

@@ -0,0 +1,65 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+/**
+ * Run `fn` with `capabilities` as the ambient caller declaration for its whole
+ * async extent. Called by `surfaceToolHints` once per tool call.
+ *
+ * A caller whose capabilities could not be resolved runs `fn` unwrapped rather
+ * than storing `undefined`: an empty store and no store are the same answer to
+ * {@link currentCallerCapabilities}.
+ */
+export function withCallerCapabilities(capabilities, fn) {
+    return capabilities ? storage.run(capabilities, fn) : fn();
+}
+/** The ambient caller capabilities, or `undefined` outside a wrapped tool call. */
+export function currentCallerCapabilities() {
+    return storage.getStore();
+}
+/** The envelope key the 2026-07-28 revision carries a caller's capabilities under. */
+const ENVELOPE_CAPABILITIES_KEY = 'io.modelcontextprotocol/clientCapabilities';
+/** The elicitation modes the spec defines; anything else is not a mode. */
+const ELICITATION_MODES = ['form', 'url'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The caller's declared capabilities for THIS call: the request's own envelope
+ * when the era carries one, else whatever `surfaceToolHints` stored.
+ *
+ * The envelope wins because it is per request. On the 2026-07-28 era a relay
+ * forwards the real caller's declaration with every call, so two callers on
+ * one connection can differ — and the ambient value, resolved once from the
+ * connection, would answer about the wrong one.
+ */
+export function callerCapabilities(ctx) {
+    const envelope = isRecord(ctx) && isRecord(ctx.mcpReq) ? ctx.mcpReq.envelope : undefined;
+    if (isRecord(envelope)) {
+        const declared = envelope[ENVELOPE_CAPABILITIES_KEY];
+        if (isRecord(declared))
+            return declared;
+    }
+    return currentCallerCapabilities();
+}
+/**
+ * Whether this caller can be shown a FORM elicitation — the shape every
+ * {@link requireConfirmation} prompt uses.
+ *
+ * `undefined` means "cannot tell", which callers must not read as `false`.
+ *
+ * Mirrors the SDK's own gate, verified against `@modelcontextprotocol/server`
+ * 2.0.0 by driving all four shapes through a real client: `elicitation` absent
+ * refuses; `{url: {}}` refuses (a URL elicitation cannot carry a schema);
+ * `{form: {}}` passes; and `{}` — modes not enumerated — PASSES, because a
+ * client that named no mode is not a client that excluded this one.
+ */
+export function callerAcceptsFormElicitation(ctx) {
+    const capabilities = callerCapabilities(ctx);
+    if (!capabilities)
+        return undefined;
+    const elicitation = capabilities.elicitation;
+    if (!isRecord(elicitation))
+        return false;
+    const namedModes = ELICITATION_MODES.filter((mode) => mode in elicitation);
+    return namedModes.length === 0 || namedModes.includes('form');
+}
+//# sourceMappingURL=index.js.map

package/dist/caller/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/caller/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAyCrD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAsB,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,YAA4C,EAC5C,EAAW;IAEX,OAAO,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AAC7D,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,yBAAyB;IACvC,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAED,sFAAsF;AACtF,MAAM,yBAAyB,GAAG,4CAA4C,CAAC;AAE/E,2EAA2E;AAC3E,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,KAAK,CAAU,CAAC;AAEnD,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IACzF,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,QAAQ,CAAC,yBAAyB,CAAC,CAAC;QACrD,IAAI,QAAQ,CAAC,QAAQ,CAAC;YAAE,OAAO,QAAQ,CAAC;IAC1C,CAAC;IACD,OAAO,yBAAyB,EAAE,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,4BAA4B,CAAC,GAAY;IACvD,MAAM,YAAY,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAC7C,IAAI,CAAC,YAAY;QAAE,OAAO,SAAS,CAAC;IACpC,MAAM,WAAW,GAAG,YAAY,CAAC,WAAW,CAAC;IAC7C,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;QAAE,OAAO,KAAK,CAAC;IACzC,MAAM,UAAU,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,WAAW,CAAC,CAAC;IAC3E,OAAO,UAAU,CAAC,MAAM,KAAK,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAChE,CAAC"}

package/dist/cancel/index.d.ts

@@ -7,7 +7,7 @@
  * {@link currentCallSignal}, and not entering the context at all is cheaper
  * and easier to reason about.
  */
-export declare function withCallSignal<T>(signal: AbortSignal | undefined, fn: () => T): T;
+export declare function withCallSignal<T>(signal: AbortSignal | undefined, fn: () => T, request?: ProgressCapableRequest): T;
 /**
  * The cancellation for the tool call currently running, or `undefined`
  * outside one.
@@ -60,5 +60,49 @@ export declare function killOnCancel(child: Killable, signal?: NodeJS.Signals):
  * seen is the error that propagates.
  */
 export declare function throwIfCancelled(): void;
+/** The part of the SDK's request context progress needs. */
+interface ProgressCapableRequest {
+    _meta?: {
+        progressToken?: string | number;
+    };
+    notify(notification: {
+        method: string;
+        params: Record<string, unknown>;
+    }): Promise<void> | void;
+}
+/**
+ * Tell the caller how far along a long tool call is.
+ *
+ * MEASURED SUPPORT, which is why this exists at all: on the mcp-host fleet
+ * claude.ai sends `_meta.progressToken` on its `tools/call` requests
+ * (recorded as `meta.progressToken` on the usage row, 2026-09-20), so
+ * progress a hosted MCP reports genuinely reaches it. Without a token
+ * nothing can be delivered and this is a no-op — which is the ordinary case
+ * for a client that did not ask.
+ *
+ * THREE THINGS ARE EASY TO GET WRONG HERE, and all three were, against
+ * `@modelcontextprotocol/server` 2.0.0, before this was written:
+ *
+ *  1. `notify` takes a NOTIFICATION OBJECT, not `(method, params)`. Passed a
+ *     string it spreads it character by character and puts
+ *     `{"0":"n","1":"o",…}` on the wire — a frame the peer answers with
+ *     `Unknown message type`. It does not throw, so the mistake is invisible
+ *     from the server.
+ *  2. The caller's token is at `_meta`, NOT `meta`. Reading `meta` yields
+ *     `undefined`, and the notification then goes out WITHOUT a
+ *     `progressToken` — well-formed, accepted, and dropped by the client
+ *     with "progress notification for an unknown token", because the client
+ *     routes on that field alone.
+ *  3. Neither mistake throws. A tool reporting progress into the void looks
+ *     exactly like one reporting progress correctly, from the server's side.
+ *
+ * AMBIENT, like the cancellation above and for the same reason: the token
+ * belongs to the request, `surfaceToolHints` already has it, and threading a
+ * reporter through several hundred tools is how most of them end up without
+ * one.
+ */
+export declare function reportProgress(progress: number, total?: number, message?: string): Promise<void>;
+/** Whether this caller asked for progress — for skipping work nobody will see. */
+export declare function callerWantsProgress(): boolean;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/cancel/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cancel/index.ts"],"names":[],"mappings":"AAmDA;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEjF;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,WAAW,GAAG,SAAS,CAE3D;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAK7F;AAED,8DAA8D;AAC9D,UAAU,QAAQ;IAChB,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,GAAE,MAAM,CAAC,OAAmB,GAAG,MAAM,IAAI,CAc5F;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cancel/index.ts"],"names":[],"mappings":"AAqDA;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,EAAE,EAAE,MAAM,CAAC,EACX,OAAO,CAAC,EAAE,sBAAsB,GAC/B,CAAC,CAEH;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,WAAW,GAAG,SAAS,CAE3D;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAK7F;AAED,8DAA8D;AAC9D,UAAU,QAAQ;IAChB,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,GAAE,MAAM,CAAC,OAAmB,GAAG,MAAM,IAAI,CAc5F;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC;AAED,4DAA4D;AAC5D,UAAU,sBAAsB;IAC9B,KAAK,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC5C,MAAM,CAAC,YAAY,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACjG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAetG;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C"}

package/dist/cancel/index.js

@@ -9,8 +9,8 @@ const storage = new AsyncLocalStorage();
  * {@link currentCallSignal}, and not entering the context at all is cheaper
  * and easier to reason about.
  */
-export function withCallSignal(signal, fn) {
-    return signal ? storage.run({ signal }, fn) : fn();
+export function withCallSignal(signal, fn, request) {
+    return signal ? storage.run({ signal, ...(request ? { request } : {}) }, fn) : fn();
 }
 /**
  * The cancellation for the tool call currently running, or `undefined`
@@ -88,4 +88,56 @@ export function throwIfCancelled() {
     if (signal?.aborted)
         throw signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason));
 }
+/**
+ * Tell the caller how far along a long tool call is.
+ *
+ * MEASURED SUPPORT, which is why this exists at all: on the mcp-host fleet
+ * claude.ai sends `_meta.progressToken` on its `tools/call` requests
+ * (recorded as `meta.progressToken` on the usage row, 2026-09-20), so
+ * progress a hosted MCP reports genuinely reaches it. Without a token
+ * nothing can be delivered and this is a no-op — which is the ordinary case
+ * for a client that did not ask.
+ *
+ * THREE THINGS ARE EASY TO GET WRONG HERE, and all three were, against
+ * `@modelcontextprotocol/server` 2.0.0, before this was written:
+ *
+ *  1. `notify` takes a NOTIFICATION OBJECT, not `(method, params)`. Passed a
+ *     string it spreads it character by character and puts
+ *     `{"0":"n","1":"o",…}` on the wire — a frame the peer answers with
+ *     `Unknown message type`. It does not throw, so the mistake is invisible
+ *     from the server.
+ *  2. The caller's token is at `_meta`, NOT `meta`. Reading `meta` yields
+ *     `undefined`, and the notification then goes out WITHOUT a
+ *     `progressToken` — well-formed, accepted, and dropped by the client
+ *     with "progress notification for an unknown token", because the client
+ *     routes on that field alone.
+ *  3. Neither mistake throws. A tool reporting progress into the void looks
+ *     exactly like one reporting progress correctly, from the server's side.
+ *
+ * AMBIENT, like the cancellation above and for the same reason: the token
+ * belongs to the request, `surfaceToolHints` already has it, and threading a
+ * reporter through several hundred tools is how most of them end up without
+ * one.
+ */
+export async function reportProgress(progress, total, message) {
+    const req = storage.getStore()?.request;
+    const token = req?._meta?.progressToken;
+    // No token means the caller did not ask for progress, which is the
+    // ordinary case and not a failure.
+    if (req === undefined || token === undefined)
+        return;
+    await req.notify({
+        method: 'notifications/progress',
+        params: {
+            progressToken: token,
+            progress,
+            ...(total === undefined ? {} : { total }),
+            ...(message === undefined ? {} : { message }),
+        },
+    });
+}
+/** Whether this caller asked for progress — for skipping work nobody will see. */
+export function callerWantsProgress() {
+    return storage.getStore()?.request?._meta?.progressToken !== undefined;
+}
 //# sourceMappingURL=index.js.map

package/dist/cancel/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cancel/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAiDrD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAe,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAI,MAA+B,EAAE,EAAW;IAC5E,OAAO,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AACrD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,OAAO,CAAC,QAAQ,EAAE,EAAE,MAAM,CAAC;AACpC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAA4B;IAClE,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;IACpC,IAAI,CAAC,OAAO;QAAE,OAAO,GAAG,CAAC;IACzB,IAAI,CAAC,GAAG;QAAE,OAAO,OAAO,CAAC;IACzB,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;AACzC,CAAC;AAOD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAe,EAAE,MAAM,GAAmB,SAAS;IAC9E,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;IACpC,IAAI,CAAC,OAAO;QAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAC9B,wEAAwE;IACxE,uDAAuD;IACvD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnB,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACrB,CAAC,CAAC;IACF,OAAO,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3D,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;IACnC,IAAI,MAAM,EAAE,OAAO;QAAE,MAAM,MAAM,CAAC,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;AAC/G,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cancel/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAmDrD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAe,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAC5B,MAA+B,EAC/B,EAAW,EACX,OAAgC;IAEhC,OAAO,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AACtF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,OAAO,CAAC,QAAQ,EAAE,EAAE,MAAM,CAAC;AACpC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAA4B;IAClE,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;IACpC,IAAI,CAAC,OAAO;QAAE,OAAO,GAAG,CAAC;IACzB,IAAI,CAAC,GAAG;QAAE,OAAO,OAAO,CAAC;IACzB,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;AACzC,CAAC;AAOD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAe,EAAE,MAAM,GAAmB,SAAS;IAC9E,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;IACpC,IAAI,CAAC,OAAO;QAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAC9B,wEAAwE;IACxE,uDAAuD;IACvD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnB,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACrB,CAAC,CAAC;IACF,OAAO,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3D,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;IACnC,IAAI,MAAM,EAAE,OAAO;QAAE,MAAM,MAAM,CAAC,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;AAC/G,CAAC;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,QAAgB,EAAE,KAAc,EAAE,OAAgB;IACrF,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,EAAE,EAAE,OAAO,CAAC;IACxC,MAAM,KAAK,GAAG,GAAG,EAAE,KAAK,EAAE,aAAa,CAAC;IACxC,mEAAmE;IACnE,mCAAmC;IACnC,IAAI,GAAG,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO;IACrD,MAAM,GAAG,CAAC,MAAM,CAAC;QACf,MAAM,EAAE,wBAAwB;QAChC,MAAM,EAAE;YACN,aAAa,EAAE,KAAK;YACpB,QAAQ;YACR,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;YACzC,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;SAC9C;KACF,CAAC,CAAC;AACL,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,mBAAmB;IACjC,OAAO,OAAO,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,KAAK,SAAS,CAAC;AACzE,CAAC"}

package/dist/index.d.ts

@@ -14,6 +14,7 @@
  *   - `@chrischall/mcp-utils/test`        in-memory test harness
  */
 export * from './cancel/index.js';
+export * from './caller/index.js';
 export * from './server/index.js';
 export * from './response/index.js';
 export * from './errors/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -14,6 +14,7 @@
  *   - `@chrischall/mcp-utils/test`        in-memory test harness
  */
 export * from './cancel/index.js';
+export * from './caller/index.js';
 export * from './server/index.js';
 export * from './response/index.js';
 export * from './errors/index.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC"}

package/dist/server/confirmation.d.ts

@@ -11,6 +11,14 @@ export interface RequireConfirmationOptions {
     requestKey?: string;
     /** Label shown beside the required confirmation checkbox. */
     confirmationLabel?: string;
+    /**
+     * One sentence appended when the caller cannot be shown a prompt at all,
+     * naming what to do instead (typically the tool that stages the same action
+     * without dispatching it). Omitted, the refusal still explains itself — this
+     * only adds the way forward, which the caller of this helper knows and this
+     * helper does not.
+     */
+    unsupportedNote?: string;
 }
 /**
  * Require an explicit, checked form elicitation before a mutating tool proceeds.

package/dist/server/confirmation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"confirmation.d.ts","sourceRoot":"","sources":["../../src/server/confirmation.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AAOtC,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,0BAA0B,GAClC,mBAAmB,GAAG,cAAc,GAAG,SAAS,CAuClD"}
+{"version":3,"file":"confirmation.d.ts","sourceRoot":"","sources":["../../src/server/confirmation.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AAUtC,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,0BAA0B,GAClC,mBAAmB,GAAG,cAAc,GAAG,SAAS,CA0DlD"}

package/dist/server/confirmation.js

@@ -1,8 +1,11 @@
 import { acceptedContent, inputRequired, inputResponse, } from '@modelcontextprotocol/server';
 import { z } from 'zod';
+import { callerAcceptsFormElicitation } from '../caller/index.js';
 import { textResult } from '../response/index.js';
 const DEFAULT_REQUEST_KEY = 'confirmation';
 const DEFAULT_CONFIRMATION_LABEL = 'Confirm this action should proceed.';
+const UNSUPPORTED_NOTE = 'Nothing was done because this client cannot show a confirmation prompt '
+    + '(it declares no MCP elicitation capability), and this action is never taken without one';
 /**
  * Require an explicit, checked form elicitation before a mutating tool proceeds.
  *
@@ -23,6 +26,25 @@ export function requireConfirmation(ctx, options) {
     const response = inputResponse(ctx.mcpReq.inputResponses, requestKey);
     const accepted = acceptedContent(ctx.mcpReq.inputResponses, requestKey, confirmationSchema);
     if (response.kind === 'missing') {
+        // A CALLER THAT CANNOT BE ASKED IS TOLD SO, rather than being handed a
+        // prompt the SDK will refuse to deliver. That refusal is a protocol error
+        // (-32021) raised after this function has returned, so it cannot be caught
+        // here and the caller sees only an opaque failure: measured on the mcp-host
+        // fleet, claude.ai — which declares no `elicitation` — got four of those in
+        // a row from `gog_gmail_forward`, each in under 110 ms, having never run.
+        //
+        // `false` only, never a missing answer: see `callerAcceptsFormElicitation`.
+        if (callerAcceptsFormElicitation(ctx) === false) {
+            return textResult({
+                confirmed: false,
+                dispatched: false,
+                action: options.action,
+                reason: 'confirmation-unsupported',
+                note: options.unsupportedNote
+                    ? `${UNSUPPORTED_NOTE}. ${options.unsupportedNote}`
+                    : `${UNSUPPORTED_NOTE}.`,
+            });
+        }
         const preview = {
             action: options.action,
             ...(options.details === undefined ? {} : { details: options.details }),

package/dist/server/confirmation.js.map

@@ -1 +1 @@
-{"version":3,"file":"confirmation.js","sourceRoot":"","sources":["../../src/server/confirmation.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,aAAa,EACb,aAAa,GAId,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,MAAM,mBAAmB,GAAG,cAAc,CAAC;AAC3C,MAAM,0BAA0B,GAAG,qCAAqC,CAAC;AAgBzE;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAAkB,EAClB,OAAmC;IAEnC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;IAC7D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;QAClC,SAAS,EAAE,CAAC;aACT,OAAO,EAAE;aACT,QAAQ,CAAC,OAAO,CAAC,iBAAiB,IAAI,0BAA0B,CAAC;KACrE,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAG,eAAe,CAC9B,GAAG,CAAC,MAAM,CAAC,cAAc,EACzB,UAAU,EACV,kBAAkB,CACnB,CAAC;IAEF,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG;YACd,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;SACvE,CAAC;QACF,OAAO,aAAa,CAAC;YACnB,aAAa,EAAE;gBACb,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC;oBACjC,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,KAAK,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;oBAClE,eAAe,EAAE,kBAAkB;iBACpC,CAAC;aACH;SACF,CAAC,CAAC;IACL,CAAC;IAED,IAAI,QAAQ,CAAC,IAAI,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,IAAI,QAAQ,EAAE,SAAS,KAAK,IAAI,EAAE,CAAC;QAC/F,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,UAAU,CAAC;QAChB,SAAS,EAAE,KAAK;QAChB,SAAS,EAAE,IAAI;QACf,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,IAAI,EAAE,0FAA0F;KACjG,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"confirmation.js","sourceRoot":"","sources":["../../src/server/confirmation.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,aAAa,EACb,aAAa,GAId,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,MAAM,mBAAmB,GAAG,cAAc,CAAC;AAC3C,MAAM,0BAA0B,GAAG,qCAAqC,CAAC;AACzE,MAAM,gBAAgB,GAAG,yEAAyE;MAC9F,yFAAyF,CAAC;AAwB9F;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAAkB,EAClB,OAAmC;IAEnC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;IAC7D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;QAClC,SAAS,EAAE,CAAC;aACT,OAAO,EAAE;aACT,QAAQ,CAAC,OAAO,CAAC,iBAAiB,IAAI,0BAA0B,CAAC;KACrE,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAG,eAAe,CAC9B,GAAG,CAAC,MAAM,CAAC,cAAc,EACzB,UAAU,EACV,kBAAkB,CACnB,CAAC;IAEF,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAChC,uEAAuE;QACvE,0EAA0E;QAC1E,2EAA2E;QAC3E,4EAA4E;QAC5E,4EAA4E;QAC5E,0EAA0E;QAC1E,EAAE;QACF,4EAA4E;QAC5E,IAAI,4BAA4B,CAAC,GAAG,CAAC,KAAK,KAAK,EAAE,CAAC;YAChD,OAAO,UAAU,CAAC;gBAChB,SAAS,EAAE,KAAK;gBAChB,UAAU,EAAE,KAAK;gBACjB,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,MAAM,EAAE,0BAA0B;gBAClC,IAAI,EAAE,OAAO,CAAC,eAAe;oBAC3B,CAAC,CAAC,GAAG,gBAAgB,KAAK,OAAO,CAAC,eAAe,EAAE;oBACnD,CAAC,CAAC,GAAG,gBAAgB,GAAG;aAC3B,CAAC,CAAC;QACL,CAAC;QACD,MAAM,OAAO,GAAG;YACd,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;SACvE,CAAC;QACF,OAAO,aAAa,CAAC;YACnB,aAAa,EAAE;gBACb,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC;oBACjC,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,KAAK,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;oBAClE,eAAe,EAAE,kBAAkB;iBACpC,CAAC;aACH;SACF,CAAC,CAAC;IACL,CAAC;IAED,IAAI,QAAQ,CAAC,IAAI,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,IAAI,QAAQ,EAAE,SAAS,KAAK,IAAI,EAAE,CAAC;QAC/F,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,UAAU,CAAC;QAChB,SAAS,EAAE,KAAK;QAChB,SAAS,EAAE,IAAI;QACf,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,IAAI,EAAE,0FAA0F;KACjG,CAAC,CAAC;AACL,CAAC"}

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAE,SAAS,EAA+B,MAAM,8BAA8B,CAAC;AACtF,OAAO,KAAK,EAAE,SAAS,EAAkB,MAAM,8BAA8B,CAAC;AAI9E,cAAc,mBAAmB,CAAC;AAGlC;;;GAGG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAE5E;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,CAAC,KAAK,GAAG,OAAO,IAAI,CAC3C,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,KAAK,KACR,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB,mBAGnC,CAAC;AAEH,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,CAAC;AAEhD,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB,CAAC,KAAK,GAAG,OAAO;IACrD,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;IAC9B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,mGAAmG;IACnG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAwCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAoCxD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CAAC,KAAK,GAAG,OAAO,EACnD,IAAI,EAAE,sBAAsB,CAAC,KAAK,CAAC,GAClC,OAAO,CAAC,SAAS,CAAC,CAsBpB;AAED,wDAAwD;AACxD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,gDAAgD;AAChD,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,EACjB,IAAI,GAAE,uBAA4B,GACjC,IAAI,CAyBN;AAED,oFAAoF;AACpF,MAAM,WAAW,aAAa,CAAC,KAAK,GAAG,OAAO,CAAE,SAAQ,sBAAsB,CAAC,KAAK,CAAC;IACnF;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,uBAAuB,CAAC;IAC7C;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC5B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,MAAM,CAAC,KAAK,GAAG,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,KAAK,CAAC,GAAG,iBAAiB,CAoCrF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAE,SAAS,EAA+B,MAAM,8BAA8B,CAAC;AACtF,OAAO,KAAK,EAAE,SAAS,EAAkB,MAAM,8BAA8B,CAAC;AAI9E,cAAc,mBAAmB,CAAC;AAKlC;;;GAGG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAE5E;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,CAAC,KAAK,GAAG,OAAO,IAAI,CAC3C,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,KAAK,KACR,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB,mBAGnC,CAAC;AAEH,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,CAAC;AAEhD,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB,CAAC,KAAK,GAAG,OAAO;IACrD,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;IAC9B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,mGAAmG;IACnG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AA6FD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAgDxD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CAAC,KAAK,GAAG,OAAO,EACnD,IAAI,EAAE,sBAAsB,CAAC,KAAK,CAAC,GAClC,OAAO,CAAC,SAAS,CAAC,CAsBpB;AAED,wDAAwD;AACxD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,gDAAgD;AAChD,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,EACjB,IAAI,GAAE,uBAA4B,GACjC,IAAI,CAyBN;AAED,oFAAoF;AACpF,MAAM,WAAW,aAAa,CAAC,KAAK,GAAG,OAAO,CAAE,SAAQ,sBAAsB,CAAC,KAAK,CAAC;IACnF;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,uBAAuB,CAAC;IAC7C;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC5B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,MAAM,CAAC,KAAK,GAAG,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,KAAK,CAAC,GAAG,iBAAiB,CAoCrF"}

package/dist/server/index.js

@@ -39,6 +39,7 @@ import { McpToolError, redactSecrets } from '../errors/index.js';
 import { errorResult } from '../response/index.js';
 export * from './confirmation.js';
 import { withCallSignal } from '../cancel/index.js';
+import { withCallerCapabilities } from '../caller/index.js';
 /** Protocol revisions supported by servers and the shared test harness. */
 export const SERVER_PROTOCOL_VERSIONS = Object.freeze([
     '2026-07-28',
@@ -58,6 +59,29 @@ function hintResultOrRethrow(err) {
     }
     throw err;
 }
+/**
+ * The SDK request for the call in flight, or `undefined` when it cannot
+ * deliver a notification.
+ *
+ * Shares the shape rules described on {@link callSignalFrom} below — the
+ * context is the LAST argument, and what matters hangs off `mcpReq` rather
+ * than off the context. The extra check here is `notify`: `reportProgress`
+ * must never have to guess whether the request can carry a notification, so
+ * a request without it is treated as absent.
+ */
+function mcpRequestFrom(args) {
+    const ctx = args.at(-1);
+    if (typeof ctx !== 'object' || ctx === null)
+        return undefined;
+    const req = ctx.mcpReq;
+    if (typeof req !== 'object' || req === null)
+        return undefined;
+    // Only a request that can actually deliver one, so `reportProgress` never
+    // has to guess: the SDK's own shape, checked the same way the signal is.
+    return typeof req.notify === 'function'
+        ? req
+        : undefined;
+}
 /**
  * The caller's `AbortSignal`, dug out of whatever the SDK passed.
  *
@@ -82,6 +106,39 @@ function callSignalFrom(args) {
     const signal = req.signal;
     return signal instanceof AbortSignal ? signal : undefined;
 }
+/**
+ * The capabilities the client declared at `initialize`, read off the low-level
+ * `Server` the {@link McpServer} wraps.
+ *
+ * This is the 2025-ERA source, and that is the whole reason the wrapper
+ * resolves it: a 2026-07-28 request carries the caller's declaration in its
+ * own per-request envelope, which {@link callerCapabilities} reads and
+ * prefers, but a 2025 connection declared them once at handshake and only the
+ * server kept them.
+ *
+ * Checked at every step rather than asserted, for the reason the two above
+ * are: this runs on the tool path for every call, and `getClientCapabilities`
+ * is a deprecated accessor on a type this package does not own — it is absent
+ * from `McpServer` itself, which is how a first attempt read `undefined`
+ * forever without anything failing.
+ */
+function declaredCapabilitiesFrom(server) {
+    const inner = server.server;
+    if (typeof inner !== 'object' || inner === null)
+        return undefined;
+    const read = inner.getClientCapabilities;
+    if (typeof read !== 'function')
+        return undefined;
+    try {
+        const declared = read.call(inner);
+        return typeof declared === 'object' && declared !== null
+            ? declared
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Wrap `server.registerTool` so every tool handler surfaces its error `hint`.
  *
@@ -120,7 +177,15 @@ export function surfaceToolHints(server) {
     // Here because this is the one wrapper every tool already passes
     // through: threading the signal by hand would mean editing several
     // hundred handlers and missing exactly the ones nobody edits.
-    withCallSignal(callSignalFrom(args), () => {
+    withCallSignal(callSignalFrom(args), () => 
+    // WHAT THE CALLER CAN DO, made ambient for the same reason and in
+    // the same place (`caller/index.ts`). Only the 2025-era half needs
+    // the wrapper — a 2026-07-28 request answers for itself off its own
+    // envelope — but a guarded tool that cannot tell whether the caller
+    // can be shown a prompt returns one the SDK then refuses to deliver,
+    // and that refusal reaches the caller as an unexplained protocol
+    // error it had no chance to catch.
+    withCallerCapabilities(declaredCapabilitiesFrom(server), () => {
         let result;
         try {
             result = cb(...args);
@@ -129,7 +194,7 @@ export function surfaceToolHints(server) {
             return hintResultOrRethrow(err);
         }
         return result instanceof Promise ? result.catch(hintResultOrRethrow) : result;
-    }));
+    }), mcpRequestFrom(args)));
 }
 /**
  * Build an {@link McpServer}, print the optional stderr banner, and apply every

package/dist/server/index.js.map

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

package/dist/zod/index.d.ts

@@ -129,6 +129,25 @@ export interface ToolAnnotationsInput {
     readOnly?: boolean;
     /** Repeated identical calls have the same effect. Emitted ONLY when set. */
     idempotent?: boolean;
+    /**
+     * Tool performs DESTRUCTIVE updates — it removes or overwrites something
+     * that cannot be put back, or its effect reaches a third party. Emitted
+     * ONLY when set.
+     *
+     * **Omitting this is not neutral.** `destructiveHint` defaults to TRUE in
+     * the MCP spec whenever `readOnlyHint` is false, so every `readOnly: false`
+     * tool that says nothing here is published as destructive. Measured
+     * 2026-09-21 across the fleet: 1,181 tools, of which 500 read as
+     * destructive and SIX as additive — because this option did not exist and
+     * the honest answer was literally inexpressible. A client that must raise
+     * the same alarm for "add a grocery item" as for "delete the frame" has
+     * been told nothing.
+     *
+     * The line the fleet draws is RECOVERABILITY, not "only appends": pass
+     * `false` for an edit the owner can undo, and `true` for a delete, a send,
+     * or anything another person sees. See `docs/CLIENT-BEHAVIOUR.md`.
+     */
+    destructive?: boolean;
     /**
      * Tool reaches an open/unbounded external world (the live web/API) rather
      * than a closed local computation. Emitted ONLY when set.
@@ -143,7 +162,9 @@ export interface ToolAnnotationsInput {
  * injecting hints a tool didn't declare.
  *
  * @example toolAnnotations({ title: 'Search properties' })  // { title, readOnlyHint: true }
- * @example toolAnnotations({ readOnly: false })             // { readOnlyHint: false }
+ * @example toolAnnotations({ readOnly: false })             // { readOnlyHint: false } — DESTRUCTIVE by spec default
+ * @example toolAnnotations({ readOnly: false, destructive: false })
+ *   // { readOnlyHint: false, destructiveHint: false } — a recoverable edit
  * @example toolAnnotations({ title: 'Search', idempotent: true, openWorld: true })
  *   // { title, readOnlyHint: true, idempotentHint: true, openWorldHint: true }
  */

package/dist/zod/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/zod/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,2CAA2C;AAC3C,eAAO,MAAM,WAAW,aAA8B,CAAC;AAEvD,uCAAuC;AACvC,eAAO,MAAM,SAAS,aAAiC,CAAC;AAExD,uEAAuE;AACvE,eAAO,MAAM,cAAc,aAAoB,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,OAAO,cAAe,CAAC;AAEpC;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,aAEqD,CAAC;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,aAG0D,CAAC;AAEvF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,aAOzB,CAAC;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,YAAY,4BAKtB,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,aAAa,6BAGuD,CAAC;AAMlF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;aAC3B,MAAM;aACN,KAAK;CAOG,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,UAAU;aACrB,QAAQ;aACR,SAAS;CAOD,CAAC;AAEX;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIlE;AAMD,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,oBAAyB,GAAG,eAAe,CAOhF;AAMD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAOpE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAuBlF;AAED,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/zod/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,2CAA2C;AAC3C,eAAO,MAAM,WAAW,aAA8B,CAAC;AAEvD,uCAAuC;AACvC,eAAO,MAAM,SAAS,aAAiC,CAAC;AAExD,uEAAuE;AACvE,eAAO,MAAM,cAAc,aAAoB,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,OAAO,cAAe,CAAC;AAEpC;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,aAEqD,CAAC;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,aAG0D,CAAC;AAEvF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,aAOzB,CAAC;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,YAAY,4BAKtB,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,aAAa,6BAGuD,CAAC;AAMlF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;aAC3B,MAAM;aACN,KAAK;CAOG,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,UAAU;aACrB,QAAQ;aACR,SAAS;CAOD,CAAC;AAEX;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIlE;AAMD,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,oBAAyB,GAAG,eAAe,CAQhF;AAMD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAOpE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAuBlF;AAED,cAAc,oBAAoB,CAAC"}

package/dist/zod/index.js

@@ -160,7 +160,9 @@ export function calculateOffset(page, size) {
  * injecting hints a tool didn't declare.
  *
  * @example toolAnnotations({ title: 'Search properties' })  // { title, readOnlyHint: true }
- * @example toolAnnotations({ readOnly: false })             // { readOnlyHint: false }
+ * @example toolAnnotations({ readOnly: false })             // { readOnlyHint: false } — DESTRUCTIVE by spec default
+ * @example toolAnnotations({ readOnly: false, destructive: false })
+ *   // { readOnlyHint: false, destructiveHint: false } — a recoverable edit
  * @example toolAnnotations({ title: 'Search', idempotent: true, openWorld: true })
  *   // { title, readOnlyHint: true, idempotentHint: true, openWorldHint: true }
  */
@@ -169,6 +171,7 @@ export function toolAnnotations(opts = {}) {
         ...(opts.title !== undefined ? { title: opts.title } : {}),
         readOnlyHint: opts.readOnly ?? true,
         ...(opts.idempotent !== undefined ? { idempotentHint: opts.idempotent } : {}),
+        ...(opts.destructive !== undefined ? { destructiveHint: opts.destructive } : {}),
         ...(opts.openWorld !== undefined ? { openWorldHint: opts.openWorld } : {}),
     };
 }

package/dist/zod/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/mcp-utils",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Shared scaffolding for the chrischall MCP fleet — server bootstrap, tool-result formatting, helpful errors, hardened env/config, a bearer API-client kit, zod atoms, session registries, a fetchproxy transport adapter, auth resolver skeletons, an in-memory test harness, and opt-in HTML helpers. The generic MCP glue hoisted out of ~19 sibling servers.",
   "type": "module",
   "license": "MIT",