agentfootprint 9.80.0 → 9.82.0

package/dist/esm/lib/mcp/throttleRetry.d.ts

@@ -102,9 +102,28 @@ export type RetryOnThrottle = boolean | ThrottleRetryOptions;
  * so a transport that passed no custom fetch keeps passing none and its
  * behaviour is byte-identical to before this existed.
  *
+ * ── Why this is public ───────────────────────────────────────────────────────
+ * `mcpClient({ transport })` applies it for you, ON by default. `mcpClient({
+ * connection })` cannot: the library builds no transport on that arm, so there
+ * is no `fetch` of its own to wrap — and a browser consumer, who is the main
+ * reason that arm exists, would silently lose the 429 handling Node gets for
+ * free. That asymmetry is invisible from the outside, which is why the answer
+ * is to hand over the same implementation rather than to document the gap:
+ *
+ * ```ts
+ * import { retryingFetch } from 'agentfootprint/providers';
+ * import { StreamableHTTPClientTransport }
+ *   from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+ *
+ * const transport = new StreamableHTTPClientTransport(new URL('/mcp', location.href), {
+ *   fetch: retryingFetch(undefined, { maxAttempts: 5 }),
+ * });
+ * ```
+ *
  * @param inner the fetch to wrap. `undefined` means the global `fetch`,
  *   resolved at CALL time so a later polyfill still wins.
- * @internal
+ * @param config `true` / `undefined` for the defaults, `false` to get `inner`
+ *   back unchanged, or an object to tune the ceilings.
  */
 export declare function retryingFetch(inner: ThrottleFetch | undefined, config: RetryOnThrottle | undefined): ThrottleFetch | undefined;
 /**

package/dist/esm/lib/mcp/throttleRetry.js

@@ -63,9 +63,28 @@ function resolveConfig(config) {
  * so a transport that passed no custom fetch keeps passing none and its
  * behaviour is byte-identical to before this existed.
  *
+ * ── Why this is public ───────────────────────────────────────────────────────
+ * `mcpClient({ transport })` applies it for you, ON by default. `mcpClient({
+ * connection })` cannot: the library builds no transport on that arm, so there
+ * is no `fetch` of its own to wrap — and a browser consumer, who is the main
+ * reason that arm exists, would silently lose the 429 handling Node gets for
+ * free. That asymmetry is invisible from the outside, which is why the answer
+ * is to hand over the same implementation rather than to document the gap:
+ *
+ * ```ts
+ * import { retryingFetch } from 'agentfootprint/providers';
+ * import { StreamableHTTPClientTransport }
+ *   from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+ *
+ * const transport = new StreamableHTTPClientTransport(new URL('/mcp', location.href), {
+ *   fetch: retryingFetch(undefined, { maxAttempts: 5 }),
+ * });
+ * ```
+ *
  * @param inner the fetch to wrap. `undefined` means the global `fetch`,
  *   resolved at CALL time so a later polyfill still wins.
- * @internal
+ * @param config `true` / `undefined` for the defaults, `false` to get `inner`
+ *   back unchanged, or an object to tune the ceilings.
  */
 export function retryingFetch(inner, config) {
     const resolved = resolveConfig(config);

package/dist/esm/lib/mcp/throttleRetry.js.map

@@ -1 +1 @@
-{"version":3,"file":"throttleRetry.js","sourceRoot":"","sources":["../../../../src/lib/mcp/throttleRetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAgEH,wEAAwE;AAExE,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAC/B,MAAM,mBAAmB,GAAG,MAAM,CAAC;AACnC,2DAA2D;AAC3D,MAAM,eAAe,GAAG,GAAG,CAAC;AAQ5B,+EAA+E;AAC/E,SAAS,aAAa,CAAC,MAAmC;IACxD,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IACvC,MAAM,IAAI,GAAyB,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;IACzF,OAAO;QACL,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,IAAI,oBAAoB,CAAC;QAClE,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,IAAI,mBAAmB,CAAC;QAC7D,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED,wEAAwE;AAExE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAgC,EAChC,MAAmC;IAEnC,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE5B,MAAM,IAAI,GAAkB,KAAK,IAAI,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IAEtF,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QAC3B,IAAI,WAAW,GAAG,CAAC,CAAC;QAEpB,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;YAClC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YACzC,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;gBAAE,OAAO,QAAQ,CAAC;YAC7C,IAAI,OAAO,IAAI,QAAQ,CAAC,WAAW;gBAAE,OAAO,QAAQ,CAAC;YACrD,sEAAsE;YACtE,wEAAwE;YACxE,qCAAqC;YACrC,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC;gBAAE,OAAO,QAAQ,CAAC;YAChD,IAAI,IAAI,EAAE,MAAM,EAAE,OAAO;gBAAE,OAAO,QAAQ,CAAC;YAE3C,MAAM,YAAY,GAAG,eAAe,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;YAC1E,MAAM,MAAM,GAAG,YAAY,IAAI,SAAS,CAAC,OAAO,CAAC,CAAC;YAClD,uEAAuE;YACvE,8BAA8B;YAC9B,IAAI,WAAW,GAAG,MAAM,GAAG,QAAQ,CAAC,SAAS;gBAAE,OAAO,QAAQ,CAAC;YAE/D,iEAAiE;YACjE,2DAA2D;YAC3D,WAAW,CAAC,QAAQ,CAAC,CAAC;YAEtB,QAAQ,CAAC,OAAO,EAAE,CAAC;gBACjB,OAAO,EAAE,OAAO,GAAG,CAAC;gBACpB,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,MAAM;gBACN,GAAG,CAAC,YAAY,KAAK,SAAS,IAAI,EAAE,YAAY,EAAE,CAAC;gBACnD,GAAG,EAAE,WAAW,CAAC,KAAK,CAAC;aACxB,CAAC,CAAC;YAEH,MAAM,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YAClC,WAAW,IAAI,MAAM,CAAC;QACxB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,wEAAwE;AAExE;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAgC;IAC9D,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IACzD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;AACxC,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,OAAe;IAChC,MAAM,OAAO,GAAG,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;IAC3D,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,6EAA6E;AAC7E,SAAS,YAAY,CAAC,KAAmB,EAAE,IAAkB;IAC3D,2EAA2E;IAC3E,mEAAmE;IACnE,IAAI,OAAO,OAAO,KAAK,WAAW,IAAK,KAAiB,YAAY,OAAO;QAAE,OAAO,KAAK,CAAC;IAC1F,MAAM,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC;IACxB,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACrD,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,OAAO,eAAe,KAAK,WAAW,IAAI,IAAI,YAAY,eAAe;QAAE,OAAO,IAAI,CAAC;IAC3F,IAAI,OAAO,IAAI,KAAK,WAAW,IAAI,IAAI,YAAY,IAAI;QAAE,OAAO,IAAI,CAAC;IACrE,IAAI,IAAI,YAAY,WAAW,IAAI,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACzE,OAAO,KAAK,CAAC;AACf,CAAC;AAED,oEAAoE;AACpE,SAAS,WAAW,CAAC,QAAkB;IACrC,IAAI,CAAC;QACH,KAAK,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;IACrE,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,SAAS,WAAW,CAAC,KAAmB;IACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;AAC9D,CAAC;AAED,SAAS,KAAK,CAAC,EAAU,EAAE,MAA2B;IACpD,IAAI,EAAE,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IACtC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;YAC9C,OAAO;QACT,CAAC;QACD,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE;YACzB,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC9C,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,YAAY,CAAC,EAAE,CAAC,CAAC;YACjB,MAAM,CAAC,MAAM,EAAE,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;QACjD,CAAC,CAAC;QACF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"throttleRetry.js","sourceRoot":"","sources":["../../../../src/lib/mcp/throttleRetry.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/mcp/transportUrl.d.ts

@@ -0,0 +1,30 @@
+/**
+ * transportUrl — read `transport.url` the way the runtime it is running in
+ * would read it.
+ *
+ * ── Why ──────────────────────────────────────────────────────────────────────
+ * `new URL('/py/mcp')` throws `TypeError: Invalid URL`. In Node that is the
+ * right answer: there is no document, so there is no base, and a path on its
+ * own names nothing. In a browser it is the wrong answer twice over — the page
+ * HAS a base, and `/py/mcp` is the single most ordinary way to name a sidecar
+ * behind the same origin (which is also how you avoid a CORS preflight
+ * entirely). Before this, a browser consumer's first attempt died on a
+ * `TypeError` from deep inside the transport constructor, with nothing in the
+ * message naming the URL or the fix.
+ *
+ * ── The rule ─────────────────────────────────────────────────────────────────
+ * An ABSOLUTE url takes the identical first branch it always took, so every
+ * existing caller is byte-identical. A relative one resolves against
+ * `globalThis.location.href` when there is one. With neither, the refusal says
+ * which of the two worlds it is in, because "Invalid URL" does not.
+ *
+ * Pattern: pure function. Role: Layer-3 tool transport.
+ */
+/**
+ * Resolve a transport URL, honouring a document base when the runtime has one.
+ *
+ * @param raw the `url` from an `http` or `gateway` transport descriptor
+ * @param caller the function to name in the refusal, e.g. `'mcpClient'`
+ * @throws when `raw` is neither absolute nor resolvable against a base
+ */
+export declare function transportUrl(raw: string, caller: string): URL;

package/dist/esm/lib/mcp/transportUrl.js

@@ -0,0 +1,71 @@
+/**
+ * transportUrl — read `transport.url` the way the runtime it is running in
+ * would read it.
+ *
+ * ── Why ──────────────────────────────────────────────────────────────────────
+ * `new URL('/py/mcp')` throws `TypeError: Invalid URL`. In Node that is the
+ * right answer: there is no document, so there is no base, and a path on its
+ * own names nothing. In a browser it is the wrong answer twice over — the page
+ * HAS a base, and `/py/mcp` is the single most ordinary way to name a sidecar
+ * behind the same origin (which is also how you avoid a CORS preflight
+ * entirely). Before this, a browser consumer's first attempt died on a
+ * `TypeError` from deep inside the transport constructor, with nothing in the
+ * message naming the URL or the fix.
+ *
+ * ── The rule ─────────────────────────────────────────────────────────────────
+ * An ABSOLUTE url takes the identical first branch it always took, so every
+ * existing caller is byte-identical. A relative one resolves against
+ * `globalThis.location.href` when there is one. With neither, the refusal says
+ * which of the two worlds it is in, because "Invalid URL" does not.
+ *
+ * Pattern: pure function. Role: Layer-3 tool transport.
+ */
+/**
+ * Resolve a transport URL, honouring a document base when the runtime has one.
+ *
+ * @param raw the `url` from an `http` or `gateway` transport descriptor
+ * @param caller the function to name in the refusal, e.g. `'mcpClient'`
+ * @throws when `raw` is neither absolute nor resolvable against a base
+ */
+export function transportUrl(raw, caller) {
+    try {
+        return new URL(raw);
+    }
+    catch {
+        // Not absolute. A browser can still resolve it; Node cannot.
+    }
+    const base = documentBase();
+    if (base !== undefined) {
+        try {
+            return new URL(raw, base);
+        }
+        catch {
+            // A base existed and still did not help — fall through to the refusal,
+            // which names both halves rather than blaming the url alone.
+        }
+    }
+    throw new Error(`${caller}: transport.url ${JSON.stringify(raw)} is not an absolute URL, and ` +
+        `${base === undefined
+            ? 'this runtime has no document base to resolve it against (Node, a worker, a test)'
+            : `it does not resolve against the document base ${JSON.stringify(base)}`}. ` +
+        'Pass an absolute URL (for example `http://127.0.0.1:5230/mcp`); a path like ' +
+        '`/mcp` only resolves in a browser, against the page it was loaded from.');
+}
+/**
+ * The page's own URL, when there is a page.
+ *
+ * Read through `globalThis` and guarded, because every access here is on a
+ * host object this library does not own: `location` is absent in Node, present
+ * but href-less in some worker and test doubles, and a getter that throws in a
+ * sandboxed frame.
+ */
+function documentBase() {
+    try {
+        const href = globalThis.location?.href;
+        return typeof href === 'string' && href.length > 0 ? href : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=transportUrl.js.map

package/dist/esm/lib/mcp/transportUrl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transportUrl.js","sourceRoot":"","sources":["../../../../src/lib/mcp/transportUrl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,MAAc;IACtD,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,6DAA6D;IAC/D,CAAC;IACD,MAAM,IAAI,GAAG,YAAY,EAAE,CAAC;IAC5B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,IAAI,CAAC;YACH,OAAO,IAAI,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,uEAAuE;YACvE,6DAA6D;QAC/D,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CACb,GAAG,MAAM,mBAAmB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,+BAA+B;QAC5E,GACE,IAAI,KAAK,SAAS;YAChB,CAAC,CAAC,kFAAkF;YACpF,CAAC,CAAC,iDAAiD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAC3E,IAAI;QACJ,8EAA8E;QAC9E,yEAAyE,CAC5E,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,YAAY;IACnB,IAAI,CAAC;QACH,MAAM,IAAI,GAAI,UAAgD,CAAC,QAAQ,EAAE,IAAI,CAAC;QAC9E,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/esm/lib/mcp/types.d.ts

@@ -199,6 +199,25 @@ export interface McpClientOptions {
      * Ignored for `stdio`, which has no HTTP status to read.
      */
     readonly retryOnThrottle?: RetryOnThrottle;
+    /**
+     * Pre-resolved SDK modules. Give these and the library never touches its Node
+     * `require` loader — which is the whole reason a browser bundle can now speak
+     * MCP over `http`.
+     *
+     * Everything else keeps working, because the library still builds the
+     * transport: gateway vending, `retryOnThrottle`, `headers`, your own `fetch`,
+     * `_meta` ingestion. Omit it and the loader runs exactly as it always has.
+     *
+     * Ignored for `transport: 'stdio'`, which spawns a subprocess and therefore
+     * cannot run in a browser at all — that branch keeps loading
+     * `client/stdio.js` through the Node loader, which is also what keeps the
+     * SDK's only Node-bound client module off a browser's module graph.
+     *
+     * @see McpSdk for the two static imports that produce it.
+     */
+    readonly sdk?: McpSdk;
+    /** @see McpConnectionOptions — never set on this arm. */
+    readonly connection?: undefined;
     /**
      * @internal Pre-built SDK client for tests. Skips SDK import +
      * transport construction. Same convention as `AnthropicProvider._client`.
@@ -210,6 +229,45 @@ export interface McpClientOptions {
      */
     readonly _client?: McpSdkClient;
 }
+/**
+ * The other arm of `mcpClient`: you connected the client, the library adapts it.
+ *
+ * Reach for this when the library must not construct anything at all — a
+ * browser bundle behind a strict CSP, where you need the SDK's own
+ * `jsonSchemaValidator` to keep ajv's code generation off the page; or any
+ * transport this library has never heard of.
+ *
+ * The cost is stated rather than hidden: the library builds no transport here,
+ * so every option that is consumed INSIDE a transport is refused rather than
+ * accepted and ignored. `retryOnThrottle` becomes `retryingFetch` around
+ * your own `fetch`; `clientInfo` and `headers` are yours to set when you
+ * construct the client. `signal` IS honoured — it rides the SDK's trailing
+ * request-options argument, not the transport.
+ */
+export interface McpConnectionOptions {
+    /**
+     * Logical name for observability + tool-call routing, exactly as on
+     * {@link McpClientOptions}. Defaults to `'mcp'`.
+     */
+    readonly name?: string;
+    /**
+     * A connection you already opened. The library never calls `connect()` on it;
+     * `close()` on the returned client closes it exactly once.
+     */
+    readonly connection: McpConnection;
+    /** Abort the list / call paths. Rides the SDK's request options. */
+    readonly signal?: AbortSignal;
+    /** @see McpClientOptions — never set on this arm. */
+    readonly transport?: undefined;
+    /** @see McpClientOptions — never set on this arm. */
+    readonly sdk?: undefined;
+    /** @see McpClientOptions — never set on this arm. */
+    readonly clientInfo?: undefined;
+    /** @see McpClientOptions — never set on this arm. */
+    readonly retryOnThrottle?: undefined;
+    /** @internal @see McpClientOptions — never set on this arm. */
+    readonly _client?: undefined;
+}
 /**
  * What `mcpClient(opts)` returns. Connect once; call `.tools()` to
  * snapshot the tool list, `.refresh()` to re-list after the server's
@@ -235,23 +293,30 @@ export interface McpClient {
     close(): Promise<void>;
 }
 /**
- * Minimal structural type capturing the parts of the MCP SDK client
- * we touch. Defined locally so we can:
- *   1. Inject a mock for tests (`McpClientOptions._client`)
- *   2. Avoid a hard import on `@modelcontextprotocol/sdk` (which is
- *      a lazy peer-dep)
+ * A live MCP connection you opened and connected yourself.
  *
- * The real SDK exports a richer surface; we narrow to what's needed.
+ * This is the whole contract this library needs from an MCP client: three
+ * methods over JSON-RPC. Nothing in it names a vendor, so an SDK `Client`, a
+ * hand-written fake, or a future fetch-only transport all satisfy it.
+ *
+ * Pass one as `mcpClient({ connection })` when the library must not load the
+ * SDK itself — a browser bundle, where the Node `require` loader does not
+ * exist. You own construction, so you also own the transport's `fetch`, its
+ * headers, its auth, and (SDK-specific) its `jsonSchemaValidator`, which is the
+ * one way to keep ajv's `new Function` off a page with a strict CSP.
+ *
+ * What you give up by owning it: this library builds no transport on that arm,
+ * so `retryOnThrottle` has nothing to wrap. Wrap your own fetch with
+ * `retryingFetch` and the 429 handling comes back.
  *
  * Argument POSITION matters here and is easy to get wrong: the SDK keeps
- * per-request options (`signal`, `timeout`) in a SEPARATE trailing
- * argument, never inside the JSON-RPC params. A `signal` smuggled into
- * the params object is serialized onto the wire as `{}` and silently
- * fails to cancel anything, so these signatures mirror the SDK's own
- * shape rather than a flattened convenience version of it.
+ * per-request options (`signal`, `timeout`) in a SEPARATE trailing argument,
+ * never inside the JSON-RPC params. A `signal` smuggled into the params object
+ * is serialized onto the wire as `{}` and silently fails to cancel anything, so
+ * these signatures mirror the SDK's own shape rather than a flattened
+ * convenience version of it.
  */
-export interface McpSdkClient {
-    connect(transport: unknown, options?: McpRequestOptions): Promise<void>;
+export interface McpConnection {
     listTools(params?: undefined, options?: McpRequestOptions): Promise<{
         readonly tools: ReadonlyArray<McpListedTool>;
     }>;
@@ -263,6 +328,71 @@ export interface McpSdkClient {
     resultSchema?: undefined, options?: McpRequestOptions): Promise<McpCallToolResult>;
     close(): Promise<void>;
 }
+/**
+ * Minimal structural type capturing the parts of the MCP SDK client
+ * we touch. Defined locally so we can:
+ *   1. Inject a mock for tests (`McpClientOptions._client`)
+ *   2. Avoid a hard import on `@modelcontextprotocol/sdk` (which is
+ *      a lazy peer-dep)
+ *
+ * The real SDK exports a richer surface; we narrow to what's needed.
+ *
+ * Member set unchanged since it was introduced: {@link McpConnection} plus the
+ * one method the library calls when it opens the connection ITSELF. The split
+ * is what lets a caller hand over a client that is already connected without
+ * also promising a `connect` this library must never call on it.
+ */
+export interface McpSdkClient extends McpConnection {
+    connect(transport: unknown, options?: McpRequestOptions): Promise<void>;
+}
+/**
+ * The two `@modelcontextprotocol/sdk` module exports the Streamable HTTP path
+ * needs, typed STRUCTURALLY so this declaration never references the optional
+ * peer — a consumer without the SDK installed still typechecks.
+ *
+ * Hand these to `mcpClient({ sdk })` and the library never touches its Node
+ * `require` loader, which is what lets a browser bundle speak MCP over `http`.
+ * Everything else keeps working, because the library still builds the
+ * transport: gateway vending, `retryOnThrottle`, `headers`, your own `fetch`,
+ * `_meta` ingestion.
+ *
+ * Load them yourself with two static imports. The subpaths matter: the SDK's
+ * root export `"."` does not resolve (it declares no `dist/esm/index.js`), and
+ * `client/stdio.js` is the one client module that imports `node:process` and
+ * `node:stream` — importing it is what would drag Node into a browser graph.
+ *
+ * ```ts
+ * import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+ * import { StreamableHTTPClientTransport }
+ *   from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+ *
+ * const client = await mcpClient({
+ *   name: 'sidecar',
+ *   sdk: { Client, StreamableHTTPClientTransport },
+ *   transport: { transport: 'http', url: '/py/mcp' },
+ * });
+ * ```
+ */
+export interface McpSdk {
+    readonly Client: new (info: {
+        name: string;
+        version: string;
+    }, options: {
+        capabilities: Record<string, unknown>;
+    }) => McpSdkClient;
+    readonly StreamableHTTPClientTransport: new (url: URL, options?: {
+        requestInit?: {
+            headers: Record<string, string>;
+        };
+        /**
+         * The SDK's hook for a custom fetch — how per-request vending AND
+         * caller-supplied signing both get in. Typed exactly as the SDK types it,
+         * so a function this shim accepts is a function the real transport
+         * accepts.
+         */
+        fetch?: (url: string | URL, init?: RequestInit) => Promise<Response>;
+    }) => unknown;
+}
 /**
  * One entry of a `tools/list` answer, narrowed to what this client reads.
  *

package/dist/esm/tool-providers/index.d.ts

@@ -51,7 +51,7 @@ export { staticTools } from './staticTools.js';
 export { gatedTools } from './gatedTools.js';
 export { skillScopedTools, skillScopedToolsTarget, SKILL_SCOPED_TOOLS_ID_PREFIX, } from './skillScopedTools.js';
 export type { ToolProvider, ToolDispatchContext, ToolGatePredicate } from './types.js';
-export { mcpClient, mcpServe, mockMcpClient, gatewayTransport, GatewayAuthorizationRequiredError, MCP_TOOL_EXTRAS_KEY, } from '../lib/mcp/index.js';
+export { mcpClient, mcpServe, mockMcpClient, gatewayTransport, GatewayAuthorizationRequiredError, MCP_TOOL_EXTRAS_KEY, retryingFetch, } from '../lib/mcp/index.js';
 export { agentCoreGatewayTransport, agentCoreGatewayUrl, gatewaySearchTool, hasGatewaySearch, AGENTCORE_GATEWAY_SEARCH_TOOL, AGENTCORE_POLICY_SESSION_HEADER, AGENTCORE_SIGV4_SERVICE, } from '../adapters/mcp/agentcore.js';
 export type { AgentCoreGatewayTransportOptions, AgentCoreGatewayUrlOptions, } from '../adapters/mcp/agentcore.js';
-export type { GatewayTransportOptions, McpCallToolResult, McpClient, McpClientOptions, McpSdkClient, McpTransport, McpStdioTransport, McpHttpTransport, McpGatewayTransport, MockMcpClientOptions, MockMcpTool, McpServeOptions, McpServeHandle, McpServeTransport, McpStdioServeTransport, McpHttpServeTransport, McpSdkServer, McpToolExtras, } from '../lib/mcp/index.js';
+export type { GatewayTransportOptions, McpCallToolResult, McpClient, McpClientOptions, McpConnection, McpConnectionOptions, McpSdk, McpSdkClient, ThrottleFetch, McpTransport, McpStdioTransport, McpHttpTransport, McpGatewayTransport, MockMcpClientOptions, MockMcpTool, McpServeOptions, McpServeHandle, McpServeTransport, McpStdioServeTransport, McpHttpServeTransport, McpSdkServer, McpToolExtras, } from '../lib/mcp/index.js';

package/dist/esm/tool-providers/index.js

@@ -60,7 +60,12 @@ export { mcpClient, mcpServe, mockMcpClient, gatewayTransport, GatewayAuthorizat
 // The `_meta` key agentfootprint's tool declarations travel under, in both
 // directions (9.71.0). Public so a server this library did not write can
 // speak it, and so a client can read a bag it received.
-MCP_TOOL_EXTRAS_KEY, } from '../lib/mcp/index.js';
+MCP_TOOL_EXTRAS_KEY, 
+// The 429 retry `mcpClient({ transport })` applies for you (9.81.0). Public
+// so `mcpClient({ connection })` — the arm a browser takes, where the library
+// builds no transport — can wrap its own `fetch` with the same code rather
+// than quietly doing without it.
+retryingFetch, } from '../lib/mcp/index.js';
 // Reaching an AWS Bedrock AgentCore Gateway (9.66.0). A configuration of
 // `gatewayTransport` plus the four facts that are AgentCore's alone — kept in
 // the vendor's own file so the transport above stays able to say, truthfully,

package/dist/esm/tool-providers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tool-providers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EACL,gBAAgB;AAChB,kFAAkF;AAClF,kFAAkF;AAClF,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,uBAAuB,CAAC;AAG/B,uEAAuE;AACvE,wEAAwE;AACxE,0CAA0C;AAC1C,OAAO,EACL,SAAS,EACT,QAAQ,EACR,aAAa,EACb,gBAAgB,EAChB,iCAAiC;AACjC,2EAA2E;AAC3E,yEAAyE;AACzE,wDAAwD;AACxD,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,yEAAyE;AACzE,8EAA8E;AAC9E,8EAA8E;AAC9E,yCAAyC;AACzC,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,6BAA6B,EAC7B,+BAA+B,EAC/B,uBAAuB,GACxB,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tool-providers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EACL,gBAAgB;AAChB,kFAAkF;AAClF,kFAAkF;AAClF,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,uBAAuB,CAAC;AAG/B,uEAAuE;AACvE,wEAAwE;AACxE,0CAA0C;AAC1C,OAAO,EACL,SAAS,EACT,QAAQ,EACR,aAAa,EACb,gBAAgB,EAChB,iCAAiC;AACjC,2EAA2E;AAC3E,yEAAyE;AACzE,wDAAwD;AACxD,mBAAmB;AACnB,4EAA4E;AAC5E,8EAA8E;AAC9E,2EAA2E;AAC3E,iCAAiC;AACjC,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,yEAAyE;AACzE,8EAA8E;AAC9E,8EAA8E;AAC9E,yCAAyC;AACzC,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,6BAA6B,EAC7B,+BAA+B,EAC/B,uBAAuB,GACxB,MAAM,8BAA8B,CAAC"}

package/dist/lib/mcp/connectionRefusals.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * connectionRefusals — the two arms of `mcpClient` refuse to be mixed, at
+ * CONSTRUCTION, in words that name where the behaviour went.
+ *
+ * ── Why refuse rather than ignore ────────────────────────────────────────────
+ * `mcpClient({ connection })` hands over a client somebody else built, so this
+ * library builds no transport on that arm — and every option consumed INSIDE a
+ * transport therefore has nothing to act on. `retryOnThrottle` is the sharp
+ * one: it is ON by default, it is consumed by `retryingFetch` around the
+ * transport's `fetch`, and accepting it here would leave a caller holding an
+ * option that NAMES a behaviour which no longer happens. A knob that lies about
+ * what it does is worse than one that is absent, so these throw.
+ *
+ * The type union refuses the same combinations at compile time
+ * (`McpConnectionOptions` declares each of them `?: undefined`). This is the
+ * runtime half, and it is not redundant: excess-property checking does not
+ * survive a spread, and JavaScript callers have no compiler at all.
+ *
+ * Pattern: pure guard. Role: Layer-3 tool integration.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refuseConflictingOptions = void 0;
+/** The three methods this library calls on a connection. Nothing else. */
+const CONNECTION_METHODS = ['listTools', 'callTool', 'close'];
+/**
+ * Refuse a mixed or malformed options object before anything connects.
+ *
+ * @param opts what the caller passed, before any defaulting
+ * @param name the client's logical name, so a multi-server app knows which one
+ * @throws naming the two options that cannot travel together, or the member the
+ *   connection is missing
+ */
+function refuseConflictingOptions(opts, name) {
+    const at = `mcpClient[${name}]`;
+    // Read through a permissive view on purpose. The union already narrows these
+    // combinations away at compile time, so narrowing here would leave the guard
+    // reasoning about a shape it exists precisely to disbelieve — an object built
+    // by a spread, or by JavaScript.
+    const given = opts;
+    if (given['connection'] === undefined) {
+        if (given['transport'] === undefined && given['_client'] === undefined) {
+            throw new Error(`${at}: nothing to connect to. Pass \`transport\` (the library builds the connection) ` +
+                'or `connection` (a client you connected yourself).');
+        }
+        return;
+    }
+    // From here on the caller chose the `connection` arm.
+    for (const [option, moved] of BUILT_BY_THE_TRANSPORT) {
+        if (given[option] !== undefined) {
+            throw new Error(`${at}: \`connection\` and \`${option}\` cannot travel together. ` +
+                `A connection you built yourself carries its own transport, and \`${option}\` is ` +
+                `consumed inside the transport this library did not build. ${moved}`);
+        }
+    }
+    assertConnection(given['connection'], at);
+}
+exports.refuseConflictingOptions = refuseConflictingOptions;
+/**
+ * The options that only exist because the library builds the transport, each
+ * paired with the sentence naming where that behaviour moved to. Ordered so the
+ * most surprising loss — throttle retry, which is ON by default — is named
+ * first when a caller passes several.
+ */
+const BUILT_BY_THE_TRANSPORT = [
+    [
+        'retryOnThrottle',
+        'Wrap your own `fetch` with `retryingFetch(yourFetch, options)` (exported from ' +
+            '`agentfootprint/providers`) and hand THAT to your transport — it is the same ' +
+            'implementation, applied where you build it.',
+    ],
+    [
+        'clientInfo',
+        'Pass it to the SDK `Client` constructor instead: `new Client(clientInfo, { capabilities: {} })`.',
+    ],
+    [
+        'transport',
+        'Drop one of the two: `transport` asks the library to connect, `connection` says it already is.',
+    ],
+    [
+        'sdk',
+        '`sdk` exists so the library can build the transport without its Node loader; ' +
+            'on this arm you have already built it.',
+    ],
+    [
+        '_client',
+        '`_client` is the same idea as `connection` and predates it — pass `connection` alone.',
+    ],
+];
+/**
+ * A connection is only a connection if it can be called.
+ *
+ * This catches the near-miss people actually make: handing over the TRANSPORT
+ * rather than the client. A transport has none of these three methods, and
+ * without this check it fails on the first `tools()`, one stack frame deep
+ * inside the SDK.
+ *
+ * The OTHER near-miss — a `Client` that was constructed but never `connect()`ed
+ * — cannot be caught here, because it has all three methods. It is named in the
+ * message anyway, since it produces the same "my connection does not work" and
+ * the SDK's own "Not connected" is the thing to look for.
+ */
+function assertConnection(connection, at) {
+    const members = (connection ?? {});
+    for (const method of CONNECTION_METHODS) {
+        if (typeof members[method] !== 'function') {
+            throw new Error(`${at}: \`connection\` has no \`${method}()\`. It must be an MCP client that is ` +
+                'already connected, and the likely mistake is passing the TRANSPORT instead of the ' +
+                'client. (A `new Client(...)` you never awaited `connect()` on passes this check ' +
+                'and fails later with the SDK\'s own "Not connected".)');
+        }
+    }
+}
+//# sourceMappingURL=connectionRefusals.js.map

package/dist/lib/mcp/connectionRefusals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectionRefusals.js","sourceRoot":"","sources":["../../../src/lib/mcp/connectionRefusals.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;AAIH,0EAA0E;AAC1E,MAAM,kBAAkB,GAAG,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,CAAU,CAAC;AAEvE;;;;;;;GAOG;AACH,SAAgB,wBAAwB,CACtC,IAA6C,EAC7C,IAAY;IAEZ,MAAM,EAAE,GAAG,aAAa,IAAI,GAAG,CAAC;IAChC,6EAA6E;IAC7E,6EAA6E;IAC7E,8EAA8E;IAC9E,iCAAiC;IACjC,MAAM,KAAK,GAAG,IAAoD,CAAC;IAEnE,IAAI,KAAK,CAAC,YAAY,CAAC,KAAK,SAAS,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,WAAW,CAAC,KAAK,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC,KAAK,SAAS,EAAE,CAAC;YACvE,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,kFAAkF;gBACrF,oDAAoD,CACvD,CAAC;QACJ,CAAC;QACD,OAAO;IACT,CAAC;IAED,sDAAsD;IACtD,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,sBAAsB,EAAE,CAAC;QACrD,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,0BAA0B,MAAM,6BAA6B;gBAChE,oEAAoE,MAAM,QAAQ;gBAClF,6DAA6D,KAAK,EAAE,CACvE,CAAC;QACJ,CAAC;IACH,CAAC;IACD,gBAAgB,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC;AAC5C,CAAC;AAhCD,4DAgCC;AAED;;;;;GAKG;AACH,MAAM,sBAAsB,GAExB;IACF;QACE,iBAAiB;QACjB,gFAAgF;YAC9E,+EAA+E;YAC/E,6CAA6C;KAChD;IACD;QACE,YAAY;QACZ,kGAAkG;KACnG;IACD;QACE,WAAW;QACX,gGAAgG;KACjG;IACD;QACE,KAAK;QACL,+EAA+E;YAC7E,wCAAwC;KAC3C;IACD;QACE,SAAS;QACT,uFAAuF;KACxF;CACF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,SAAS,gBAAgB,CAAC,UAAmB,EAAE,EAAU;IACvD,MAAM,OAAO,GAAG,CAAC,UAAU,IAAI,EAAE,CAAsC,CAAC;IACxE,KAAK,MAAM,MAAM,IAAI,kBAAkB,EAAE,CAAC;QACxC,IAAI,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,UAAU,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,6BAA6B,MAAM,yCAAyC;gBAC/E,oFAAoF;gBACpF,kFAAkF;gBAClF,uDAAuD,CAC1D,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/lib/mcp/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GatewayAuthorizationRequiredError = exports.gatewayTransport = exports.mockMcpClient = exports.MCP_TOOL_EXTRAS_KEY = exports.mcpServe = exports.mcpClient = void 0;
+exports.retryingFetch = exports.GatewayAuthorizationRequiredError = exports.gatewayTransport = exports.mockMcpClient = exports.MCP_TOOL_EXTRAS_KEY = exports.mcpServe = exports.mcpClient = void 0;
 /**
  * MCP — Model Context Protocol, both directions. `mcpClient` connects to
  * someone else's MCP server and registers its tools on your Agent;
@@ -20,4 +20,9 @@ Object.defineProperty(exports, "mockMcpClient", { enumerable: true, get: functio
 var gatewayTransport_js_1 = require("./gatewayTransport.js");
 Object.defineProperty(exports, "gatewayTransport", { enumerable: true, get: function () { return gatewayTransport_js_1.gatewayTransport; } });
 Object.defineProperty(exports, "GatewayAuthorizationRequiredError", { enumerable: true, get: function () { return gatewayTransport_js_1.GatewayAuthorizationRequiredError; } });
+// The 429 handling `mcpClient({ transport })` applies for you — public since
+// 9.81.0 so the `connection` arm, which builds no transport of its own, can
+// apply the SAME implementation instead of silently going without it.
+var throttleRetry_js_1 = require("./throttleRetry.js");
+Object.defineProperty(exports, "retryingFetch", { enumerable: true, get: function () { return throttleRetry_js_1.retryingFetch; } });
 //# sourceMappingURL=index.js.map

package/dist/lib/mcp/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/mcp/index.ts"],"names":[],"mappings":";;;AAAA;;;;;GAKG;AACH,+CAA2C;AAAlC,yGAAA,SAAS,OAAA;AAClB,6CAAyC;AAAhC,uGAAA,QAAQ,OAAA;AACjB,8EAA8E;AAC9E,0EAA0E;AAC1E,iDAA0E;AAAjE,oHAAA,mBAAmB,OAAA;AAC5B,uDAAgG;AAAvF,iHAAA,aAAa,OAAA;AACtB,6DAI+B;AAH7B,uHAAA,gBAAgB,OAAA;AAChB,wIAAA,iCAAiC,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/mcp/index.ts"],"names":[],"mappings":";;;AAAA;;;;;GAKG;AACH,+CAA2C;AAAlC,yGAAA,SAAS,OAAA;AAClB,6CAAyC;AAAhC,uGAAA,QAAQ,OAAA;AACjB,8EAA8E;AAC9E,0EAA0E;AAC1E,iDAA0E;AAAjE,oHAAA,mBAAmB,OAAA;AAC5B,uDAAgG;AAAvF,iHAAA,aAAa,OAAA;AACtB,6DAI+B;AAH7B,uHAAA,gBAAgB,OAAA;AAChB,wIAAA,iCAAiC,OAAA;AAGnC,6EAA6E;AAC7E,4EAA4E;AAC5E,sEAAsE;AACtE,uDAAmD;AAA1C,iHAAA,aAAa,OAAA"}