agentfootprint/dist/esm/mcp/sdkLoadFailure.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * sdkLoadFailure — say WHY the MCP SDK did not load, because there are two
 * reasons and only one of them is "install it".
 *
 * ── The lie this exists to stop ──────────────────────────────────────────────
 * Every SDK load in this module used to sit behind a BARE `catch`, and a bare
 * catch cannot tell the two apart:
 *
 *   1. the package really is absent — `Cannot find module …`; and
 *   2. the LOADER is absent — `lazyRequire` reaches for `createRequire`, which
 *      exists in Node and does not exist in a browser bundle, where a bundler
 *      has externalized `node:module` to a stub.
 *
 * Case 2 raises `TypeError: nodeModule.createRequire is not a function`, and a
 * bare catch reported it as "install @modelcontextprotocol/sdk" — to a browser
 * that had the SDK installed all along. The reader then installs a package they
 * already have, watches nothing change, and concludes MCP does not work here.
 *
 * ── The contract ─────────────────────────────────────────────────────────────
 * The absent-package message is passed IN and returned VERBATIM: each load
 * site owns its own wording (install the package, or — in a bundled app — pass
 * the module as `sdk`). The second arm names the underlying failure and the
 * seam that gets past it.
 *
 * Pattern: pure classifier. No I/O, no throwing, no vendor names beyond the
 * package it reports on. Role: Layer-3 tool transport, shared by `mcpClient`
 * and `mcpServe` so the two cannot drift into telling different stories.
 */
/**
 * Everything a load site knows about its own failure. Split out so the same
 * classifier serves seven call sites that each name a different specifier and
 * offer a different way past it.
 */
export interface SdkLoadFailureNotes {
    /**
     * The site's own absent-package message, returned unchanged — the
     * classifier never rewrites it.
     */
    readonly notInstalled: string;
    /** The function the consumer called, e.g. `'mcpClient'`. */
    readonly caller: string;
    /** The module specifier that failed to load. */
    readonly specifier: string;
    /**
     * One sentence naming what to pass instead when the LOADER, not the package,
     * is what is missing. Written per site because the answer differs: the http
     * path has `sdk` / `connection`, stdio has neither and never will.
     */
    readonly instead: string;
}
/**
 * Which of the two failures happened, as a message.
 *
 * @param err whatever the `catch` bound — an `Error`, or anything else a
 *   loader can throw.
 * @returns the absent-package message verbatim when the specifier could not be
 *   RESOLVED; otherwise a message naming the real failure and the way past it.
 */
export declare function sdkLoadFailure(err: unknown, notes: SdkLoadFailureNotes): string;