@graphorin/mcp 0.5.0

package/dist/client/transport-factory.js

@@ -0,0 +1,86 @@
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+//#region src/client/transport-factory.ts
+/**
+* Factory that materialises a `@modelcontextprotocol/sdk` `Transport`
+* instance from a {@link MCPTransportConfig}.
+*
+* The factory is small on purpose: every MCP-spec evolution (new
+* transport, transport-specific option, transport-level header
+* convention) lands here so the higher-level {@link createMCPClient}
+* stays untouched.
+*
+* @packageDocumentation
+*/
+/**
+* Wrap a `fetch` implementation so the live `Authorization` header is
+* re-resolved and injected on **every** outgoing request. The wrapper
+* always overwrites a caller-supplied `Authorization` header so the
+* provider stays the single source of truth (refresh-ahead from
+* {@link createOAuthAuthorizationProvider} fires per request).
+*/
+function authWrappedFetch(baseFetch, auth) {
+	return (async (input, init) => {
+		const header = await auth.resolveHeader();
+		const headers = new Headers(init?.headers);
+		headers.set("Authorization", header);
+		return baseFetch(input, {
+			...init,
+			headers
+		});
+	});
+}
+/**
+* Build a SDK `Transport` from a {@link MCPTransportConfig}.
+*
+* When an `auth` source is supplied (HTTP transports only) the factory
+* installs a per-request fetch-wrapper that re-resolves the
+* `Authorization` header on every outgoing call — this is the seam that
+* makes a long-lived agent session survive OAuth token expiry without
+* re-creating the client.
+*
+* @stable
+*/
+function buildTransport(config, options) {
+	switch (config.kind) {
+		case "stdio": {
+			const stdio = new StdioClientTransport({
+				command: config.command,
+				...config.args === void 0 ? {} : { args: [...config.args] },
+				...config.env === void 0 ? {} : { env: { ...config.env } },
+				...config.cwd === void 0 ? {} : { cwd: config.cwd },
+				...config.stderr === void 0 ? {} : { stderr: config.stderr }
+			});
+			return Object.freeze({ transport: stdio });
+		}
+		case "streamable-http": {
+			const url = typeof config.url === "string" ? new URL(config.url) : config.url;
+			const headers = { ...config.headers ?? {} };
+			const baseFetch = config.fetch ?? fetch;
+			const fetchImpl = options?.auth === void 0 ? config.fetch : authWrappedFetch(baseFetch, options.auth);
+			const transport = new StreamableHTTPClientTransport(url, {
+				...fetchImpl === void 0 ? {} : { fetch: fetchImpl },
+				requestInit: { headers },
+				...config.sessionId === void 0 ? {} : { sessionId: config.sessionId }
+			});
+			return Object.freeze({ transport });
+		}
+		case "sse": {
+			const url = typeof config.url === "string" ? new URL(config.url) : config.url;
+			const headers = { ...config.headers ?? {} };
+			const baseFetch = config.fetch ?? fetch;
+			const fetchImpl = options?.auth === void 0 ? config.fetch : authWrappedFetch(baseFetch, options.auth);
+			const transport = new SSEClientTransport(url, {
+				...fetchImpl === void 0 ? {} : { fetch: fetchImpl },
+				requestInit: { headers }
+			});
+			return Object.freeze({ transport });
+		}
+	}
+}
+
+//#endregion
+export { buildTransport };
+//# sourceMappingURL=transport-factory.js.map

package/dist/client/transport-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-factory.js","names":["stdio: Transport","transport: Transport"],"sources":["../../src/client/transport-factory.ts"],"sourcesContent":["/**\n * Factory that materialises a `@modelcontextprotocol/sdk` `Transport`\n * instance from a {@link MCPTransportConfig}.\n *\n * The factory is small on purpose: every MCP-spec evolution (new\n * transport, transport-specific option, transport-level header\n * convention) lands here so the higher-level {@link createMCPClient}\n * stays untouched.\n *\n * @packageDocumentation\n */\n\nimport { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';\nimport { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';\nimport type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';\n\nimport type { MCPTransportConfig } from '../transport/types.js';\n\n/**\n * Outcome of the transport build, including the SDK transport\n * instance and the helper hooks the client needs to forward to the\n * SDK.\n */\nexport interface BuiltTransport {\n  readonly transport: Transport;\n  readonly disposeBeforeStart?: () => Promise<void>;\n}\n\n/**\n * Live source of the outbound `Authorization` header for the HTTP\n * transports. The bridge's `OAuthAuthorizationProvider` satisfies this\n * structurally (its `resolveHeader()` already returns the full\n * `Bearer <token>` value); a static `bearerToken` is wrapped into a\n * constant resolver by {@link createMCPClient}.\n *\n * @internal\n */\nexport interface TransportAuthSource {\n  /** Resolve the full `Authorization` header value (e.g. `Bearer abc`). */\n  resolveHeader(): Promise<string> | string;\n}\n\n/**\n * Wrap a `fetch` implementation so the live `Authorization` header is\n * re-resolved and injected on **every** outgoing request. The wrapper\n * always overwrites a caller-supplied `Authorization` header so the\n * provider stays the single source of truth (refresh-ahead from\n * {@link createOAuthAuthorizationProvider} fires per request).\n */\nfunction authWrappedFetch(baseFetch: typeof fetch, auth: TransportAuthSource): typeof fetch {\n  return (async (input: Parameters<typeof fetch>[0], init?: RequestInit): Promise<Response> => {\n    const header = await auth.resolveHeader();\n    const headers = new Headers(init?.headers);\n    headers.set('Authorization', header);\n    return baseFetch(input, { ...init, headers });\n  }) as typeof fetch;\n}\n\n/**\n * Build a SDK `Transport` from a {@link MCPTransportConfig}.\n *\n * When an `auth` source is supplied (HTTP transports only) the factory\n * installs a per-request fetch-wrapper that re-resolves the\n * `Authorization` header on every outgoing call — this is the seam that\n * makes a long-lived agent session survive OAuth token expiry without\n * re-creating the client.\n *\n * @stable\n */\nexport function buildTransport(\n  config: MCPTransportConfig,\n  options?: { readonly auth?: TransportAuthSource },\n): BuiltTransport {\n  switch (config.kind) {\n    case 'stdio': {\n      const stdio: Transport = new StdioClientTransport({\n        command: config.command,\n        ...(config.args === undefined ? {} : { args: [...config.args] }),\n        ...(config.env === undefined ? {} : { env: { ...config.env } }),\n        ...(config.cwd === undefined ? {} : { cwd: config.cwd }),\n        ...(config.stderr === undefined ? {} : { stderr: config.stderr }),\n      });\n      return Object.freeze({ transport: stdio });\n    }\n    case 'streamable-http': {\n      const url = typeof config.url === 'string' ? new URL(config.url) : config.url;\n      const headers = { ...(config.headers ?? {}) };\n      const baseFetch = config.fetch ?? fetch;\n      const fetchImpl =\n        options?.auth === undefined ? config.fetch : authWrappedFetch(baseFetch, options.auth);\n      // The SDK class's `sessionId: string | undefined` getter is\n      // structurally narrower than `Transport.sessionId?: string` in\n      // strict mode; route through `unknown` to keep the public\n      // surface clean.\n      const sdkTransport = new StreamableHTTPClientTransport(url, {\n        ...(fetchImpl === undefined ? {} : { fetch: fetchImpl }),\n        requestInit: { headers },\n        ...(config.sessionId === undefined ? {} : { sessionId: config.sessionId }),\n      });\n      const transport = sdkTransport as unknown as Transport;\n      return Object.freeze({ transport });\n    }\n    case 'sse': {\n      const url = typeof config.url === 'string' ? new URL(config.url) : config.url;\n      const headers = { ...(config.headers ?? {}) };\n      const baseFetch = config.fetch ?? fetch;\n      const fetchImpl =\n        options?.auth === undefined ? config.fetch : authWrappedFetch(baseFetch, options.auth);\n      const transport: Transport = new SSEClientTransport(url, {\n        ...(fetchImpl === undefined ? {} : { fetch: fetchImpl }),\n        requestInit: { headers },\n      });\n      return Object.freeze({ transport });\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAkDA,SAAS,iBAAiB,WAAyB,MAAyC;AAC1F,SAAQ,OAAO,OAAoC,SAA0C;EAC3F,MAAM,SAAS,MAAM,KAAK,eAAe;EACzC,MAAM,UAAU,IAAI,QAAQ,MAAM,QAAQ;AAC1C,UAAQ,IAAI,iBAAiB,OAAO;AACpC,SAAO,UAAU,OAAO;GAAE,GAAG;GAAM;GAAS,CAAC;;;;;;;;;;;;;;AAejD,SAAgB,eACd,QACA,SACgB;AAChB,SAAQ,OAAO,MAAf;EACE,KAAK,SAAS;GACZ,MAAMA,QAAmB,IAAI,qBAAqB;IAChD,SAAS,OAAO;IAChB,GAAI,OAAO,SAAS,SAAY,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,OAAO,KAAK,EAAE;IAC/D,GAAI,OAAO,QAAQ,SAAY,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,OAAO,KAAK,EAAE;IAC9D,GAAI,OAAO,QAAQ,SAAY,EAAE,GAAG,EAAE,KAAK,OAAO,KAAK;IACvD,GAAI,OAAO,WAAW,SAAY,EAAE,GAAG,EAAE,QAAQ,OAAO,QAAQ;IACjE,CAAC;AACF,UAAO,OAAO,OAAO,EAAE,WAAW,OAAO,CAAC;;EAE5C,KAAK,mBAAmB;GACtB,MAAM,MAAM,OAAO,OAAO,QAAQ,WAAW,IAAI,IAAI,OAAO,IAAI,GAAG,OAAO;GAC1E,MAAM,UAAU,EAAE,GAAI,OAAO,WAAW,EAAE,EAAG;GAC7C,MAAM,YAAY,OAAO,SAAS;GAClC,MAAM,YACJ,SAAS,SAAS,SAAY,OAAO,QAAQ,iBAAiB,WAAW,QAAQ,KAAK;GAUxF,MAAM,YALe,IAAI,8BAA8B,KAAK;IAC1D,GAAI,cAAc,SAAY,EAAE,GAAG,EAAE,OAAO,WAAW;IACvD,aAAa,EAAE,SAAS;IACxB,GAAI,OAAO,cAAc,SAAY,EAAE,GAAG,EAAE,WAAW,OAAO,WAAW;IAC1E,CAAC;AAEF,UAAO,OAAO,OAAO,EAAE,WAAW,CAAC;;EAErC,KAAK,OAAO;GACV,MAAM,MAAM,OAAO,OAAO,QAAQ,WAAW,IAAI,IAAI,OAAO,IAAI,GAAG,OAAO;GAC1E,MAAM,UAAU,EAAE,GAAI,OAAO,WAAW,EAAE,EAAG;GAC7C,MAAM,YAAY,OAAO,SAAS;GAClC,MAAM,YACJ,SAAS,SAAS,SAAY,OAAO,QAAQ,iBAAiB,WAAW,QAAQ,KAAK;GACxF,MAAMC,YAAuB,IAAI,mBAAmB,KAAK;IACvD,GAAI,cAAc,SAAY,EAAE,GAAG,EAAE,OAAO,WAAW;IACvD,aAAa,EAAE,SAAS;IACzB,CAAC;AACF,UAAO,OAAO,OAAO,EAAE,WAAW,CAAC"}

package/dist/client/types.d.ts

@@ -0,0 +1,353 @@
+import { MCPTransportConfig, ServerIdentity } from "../transport/types.js";
+import { OAuthAuthorizationProvider } from "../oauth/bridge.js";
+import { CollisionStrategy } from "@graphorin/tools/registry";
+import { InboundSanitizationPolicy, ModelHint, ModelSpec, SideEffectClass, Tool, TruncationStrategy } from "@graphorin/core";
+
+//#region src/client/types.d.ts
+
+/**
+ * Options accepted by {@link createMCPClient}.
+ *
+ * @stable
+ */
+interface CreateMCPClientOptions {
+  readonly transport: MCPTransportConfig;
+  /**
+   * Pre-built OAuth provider that resolves the bearer header on every
+   * request. Mutually exclusive with {@link bearerToken}.
+   */
+  readonly authProvider?: OAuthAuthorizationProvider;
+  /** Pre-shared bearer token (rare; prefer {@link authProvider}). */
+  readonly bearerToken?: string;
+  /**
+   * Per-client default for the strategy-aware tool registry. Falls
+   * through to the per-call value on {@link MCPClient.toTools}.
+   *
+   * @default `'auto-prefix'`
+   */
+  readonly collisionStrategy?: CollisionStrategy;
+  /** Per-client priority value used by the `'priority'` strategy. */
+  readonly priority?: number;
+  /** Operator-supplied server identity overrides. */
+  readonly serverInfoName?: string;
+  /** Operator-supplied logger. */
+  readonly logger?: (level: 'debug' | 'info' | 'warn' | 'error', message: string, fields?: Record<string, unknown>) => void;
+  /** Operator-supplied client name advertised to the server on `initialize`. */
+  readonly clientName?: string;
+  /** Operator-supplied client version advertised to the server on `initialize`. */
+  readonly clientVersion?: string;
+  /**
+   * Skip the deprecated-transport WARN log. Useful for tests + the
+   * standalone server's startup banner.
+   *
+   * @default `false`
+   */
+  readonly suppressDeprecatedTransportWarning?: boolean;
+  /**
+   * Handler for server-initiated **elicitation** (`elicitation/create`)
+   * requests — the server asks the human for structured input mid-call
+   * (WI-13 / P2-2). When provided, the client advertises the
+   * `elicitation` capability and routes requests here; back it with a
+   * HITL surface (e.g. a CLI prompt or the agent's approval channel).
+   * When omitted, the capability is **not** advertised and a conforming
+   * server will not elicit (gated; no implicit prompting).
+   *
+   * Note: an elicitation arrives while a `callTool(...)` JSON-RPC request
+   * is in flight, so the handler resolves in-process — it does not
+   * durably suspend a Graphorin run. Durable-suspend elicitation across
+   * the request lifetime is a follow-up.
+   */
+  readonly elicitation?: MCPElicitationHandler;
+  /**
+   * Handler for server-initiated **sampling** (`sampling/createMessage`)
+   * requests — the server asks the client's model to generate a
+   * completion (WI-13 / P2-2). When provided, the client advertises the
+   * `sampling` capability and routes requests here; back it with a
+   * `Provider`. The request messages are **MCP-derived (untrusted)**, so
+   * the backing provider should apply the usual sensitivity/redaction
+   * middleware. When omitted, the capability is **not** advertised
+   * (gated).
+   */
+  readonly sampling?: MCPSamplingHandler;
+}
+/**
+ * Server-initiated elicitation request surfaced to the operator's HITL
+ * handler.
+ *
+ * @stable
+ */
+interface MCPElicitationRequest {
+  /** Human-readable prompt the server wants answered. */
+  readonly message: string;
+  /** JSON-Schema-like shape (`{ type: 'object', properties, required? }`) for the requested input. */
+  readonly requestedSchema: Readonly<Record<string, unknown>>;
+}
+/**
+ * Operator response to an {@link MCPElicitationRequest}. `accept` returns
+ * the collected flat values; `decline`/`cancel` carry no content.
+ *
+ * @stable
+ */
+type MCPElicitationResult = {
+  readonly action: 'accept';
+  readonly content?: Readonly<Record<string, string | number | boolean | ReadonlyArray<string>>>;
+} | {
+  readonly action: 'decline';
+} | {
+  readonly action: 'cancel';
+};
+/** Handler for server-initiated elicitation requests. */
+type MCPElicitationHandler = (request: MCPElicitationRequest, opts: {
+  readonly signal?: AbortSignal;
+}) => MCPElicitationResult | Promise<MCPElicitationResult>;
+/** A single content block carried by a sampling message or result. */
+type MCPSamplingContent = {
+  readonly type: 'text';
+  readonly text: string;
+} | {
+  readonly type: 'image';
+  readonly data: string;
+  readonly mimeType: string;
+} | {
+  readonly type: 'audio';
+  readonly data: string;
+  readonly mimeType: string;
+};
+/** A message in a sampling conversation. */
+interface MCPSamplingMessage {
+  readonly role: 'user' | 'assistant';
+  /**
+   * Every content block of the SDK message (MC-13) — previously only
+   * the FIRST block survived, silently dropping e.g. the image in a
+   * text+image message before it reached the operator's handler.
+   */
+  readonly content: ReadonlyArray<MCPSamplingContent>;
+}
+/**
+ * Server-initiated sampling request surfaced to the operator's handler
+ * (typically backed by a `Provider`).
+ *
+ * @stable
+ */
+interface MCPSamplingRequest {
+  readonly messages: ReadonlyArray<MCPSamplingMessage>;
+  readonly systemPrompt?: string;
+  readonly maxTokens: number;
+  readonly temperature?: number;
+  readonly stopSequences?: ReadonlyArray<string>;
+  readonly modelPreferences?: {
+    readonly hints?: ReadonlyArray<{
+      readonly name?: string;
+    }>;
+    readonly costPriority?: number;
+    readonly speedPriority?: number;
+    readonly intelligencePriority?: number;
+  };
+  readonly includeContext?: 'none' | 'thisServer' | 'allServers';
+}
+/**
+ * Operator response to an {@link MCPSamplingRequest}.
+ *
+ * @stable
+ */
+interface MCPSamplingResult {
+  readonly role: 'assistant';
+  readonly content: MCPSamplingContent;
+  readonly model: string;
+  readonly stopReason?: string;
+}
+/** Handler for server-initiated sampling requests. */
+type MCPSamplingHandler = (request: MCPSamplingRequest, opts: {
+  readonly signal?: AbortSignal;
+}) => MCPSamplingResult | Promise<MCPSamplingResult>;
+/**
+ * Per-MCP-server `toTools()` options.
+ *
+ * @stable
+ */
+interface MCPToToolsOptions {
+  /** Filter the produced tools. */
+  readonly filter?: (tool: MCPToolDefinition) => boolean;
+  /** Tool-name namespace prepended to every produced tool. */
+  readonly namespace?: string;
+  /**
+   * Per-server inbound prompt-injection sanitization policy override.
+   * Defaults to `'detect-and-strip-and-wrap'` for MCP-derived tools.
+   */
+  readonly inboundSanitization?: InboundSanitizationPolicy;
+  /**
+   * Per-call timeout (ms) applied to every adapted tool's
+   * `client.callTool` invocation (MC-3/MC-5). Default: the SDK default.
+   */
+  readonly callTimeoutMs?: number;
+  /**
+   * Operator-pinned definition fingerprints by MCP tool name (MC-6) —
+   * the `__definitionHash` stamped on a previously approved snapshot.
+   * A mismatch means the server changed the definition behind the name.
+   */
+  readonly pinnedFingerprints?: Readonly<Record<string, string>>;
+  /**
+   * What to do on a pinned-fingerprint mismatch (MC-6). `'warn'`
+   * (default) audits `mcp.tools.pin-mismatch.total` and continues;
+   * `'reject'` throws `MCPToolPinningError`.
+   */
+  readonly onPinMismatch?: 'warn' | 'reject';
+  /**
+   * Per-server `defer_loading` override. When unset and
+   * `listTools()` returns more than `deferLoadingThreshold` entries
+   * the auto-default flips deferral on for every tool from this
+   * server.
+   */
+  readonly defer_loading?: boolean;
+  /** Auto-default trigger threshold. Defaults to `10`. */
+  readonly deferLoadingThreshold?: number;
+  /** Per-server token cap override applied at registration. */
+  readonly maxResultTokens?: number;
+  /** Per-server truncation strategy override applied at registration. */
+  readonly truncationStrategy?: TruncationStrategy;
+  /** Tool-name -> per-tool side-effect class override map. */
+  readonly sideEffectClassByTool?: Readonly<Record<string, SideEffectClass>>;
+  /** Tool-name -> per-tool preferred-model override map. */
+  readonly preferredModelByTool?: Readonly<Record<string, ModelHint | ModelSpec>>;
+}
+/**
+ * Single MCP tool descriptor returned by `listTools()`. Mirrors the
+ * MCP spec subset we consume.
+ *
+ * @stable
+ */
+interface MCPToolDefinition {
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: Readonly<Record<string, unknown>>;
+  readonly outputSchema?: Readonly<Record<string, unknown>>;
+  readonly title?: string;
+}
+/** Resource descriptor returned by `listResources()`. */
+interface MCPResourceDefinition {
+  readonly uri: string;
+  readonly name?: string;
+  readonly description?: string;
+  readonly mimeType?: string;
+}
+/** Prompt descriptor returned by `listPrompts()`. */
+interface MCPPromptDefinition {
+  readonly name: string;
+  readonly description?: string;
+  readonly arguments?: ReadonlyArray<{
+    readonly name: string;
+    readonly description?: string;
+    readonly required?: boolean;
+  }>;
+}
+/** Resource content returned by `readResource(...)`. */
+interface MCPResourceContent {
+  readonly uri: string;
+  readonly mimeType?: string;
+  readonly text?: string;
+  readonly blob?: string;
+}
+/** Tool result envelope returned by `callTool(...)`. */
+interface MCPCallToolResult {
+  readonly content: ReadonlyArray<MCPContentPart>;
+  readonly structuredContent?: Readonly<Record<string, unknown>>;
+  readonly isError?: boolean;
+}
+/** Discriminated union over MCP content parts. */
+type MCPContentPart = {
+  readonly type: 'text';
+  readonly text: string;
+} | {
+  readonly type: 'image';
+  readonly data: string;
+  readonly mimeType: string;
+} | {
+  readonly type: 'audio';
+  readonly data: string;
+  readonly mimeType: string;
+} | {
+  readonly type: 'resource';
+  readonly resource: {
+    readonly uri: string;
+    readonly text?: string;
+    readonly blob?: string;
+    readonly mimeType?: string;
+  };
+} | {
+  /**
+   * A link to a resource the server can serve on demand (MCP
+   * `resource_link`). Unlike an embedded `resource`, the body is
+   * **not** inlined: the adapter surfaces a preview + the `uri` as a
+   * result handle so the model fetches it via `read_result` only
+   * when needed (WI-13 / P2-2, ties to WI-10 result handles).
+   */
+  readonly type: 'resource_link';
+  readonly uri: string;
+  readonly name: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly mimeType?: string;
+  readonly size?: number;
+};
+/**
+ * Public surface of an active MCP client.
+ *
+ * @stable
+ */
+interface MCPClient {
+  /** Stable identifier — derived from the transport. */
+  readonly id: string;
+  /** Server-advertised information from the `initialize` handshake. */
+  readonly serverInfo: {
+    readonly name: string;
+    readonly version: string;
+  };
+  /** Server identity descriptor consumed by the tool-registry resolver. */
+  readonly serverIdentity: ServerIdentity;
+  /** Per-client default collision strategy. */
+  readonly collisionStrategy: CollisionStrategy;
+  /** Per-client priority value used by the `'priority'` strategy. */
+  readonly priority?: number;
+  /**
+   * Whether the Streamable HTTP server assigned an `Mcp-Session-Id`
+   * at `initialize` time (MC-9). A session id means stateful routing —
+   * it is NOT a replay guarantee: per the Streamable HTTP spec,
+   * event replay is the SERVER's responsibility, and the SDK
+   * transport already auto-reconnects with `Last-Event-ID` when the
+   * server supports it.
+   */
+  readonly sessionIdPresent: boolean;
+  /** @deprecated Alias of {@link sessionIdPresent} — same value, misleading name. */
+  readonly resumable: boolean;
+  listTools(opts?: {
+    signal?: AbortSignal;
+  }): Promise<ReadonlyArray<MCPToolDefinition>>;
+  listResources(opts?: {
+    signal?: AbortSignal;
+  }): Promise<ReadonlyArray<MCPResourceDefinition>>;
+  listPrompts(opts?: {
+    signal?: AbortSignal;
+  }): Promise<ReadonlyArray<MCPPromptDefinition>>;
+  callTool(name: string, args: unknown, opts?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+  }): Promise<MCPCallToolResult>;
+  readResource(uri: string, opts?: {
+    signal?: AbortSignal;
+  }): Promise<MCPResourceContent>;
+  getPrompt(name: string, args?: unknown, opts?: {
+    signal?: AbortSignal;
+  }): Promise<{
+    readonly messages: ReadonlyArray<MCPPromptMessage>;
+  }>;
+  toTools(opts?: MCPToToolsOptions): Promise<ReadonlyArray<Tool>>;
+  close(): Promise<void>;
+}
+/** Single prompt message returned by `getPrompt(...)`. */
+interface MCPPromptMessage {
+  readonly role: 'user' | 'assistant';
+  readonly content: MCPContentPart;
+}
+//#endregion
+export { CreateMCPClientOptions, MCPCallToolResult, MCPClient, MCPContentPart, MCPElicitationHandler, MCPElicitationRequest, MCPElicitationResult, MCPPromptDefinition, MCPPromptMessage, MCPResourceContent, MCPResourceDefinition, MCPSamplingContent, MCPSamplingHandler, MCPSamplingMessage, MCPSamplingRequest, MCPSamplingResult, MCPToToolsOptions, MCPToolDefinition };
+//# sourceMappingURL=types.d.ts.map

package/dist/client/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/client/types.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AAgGA;AAaY,UApFK,sBAAA,CAoFe;EAImB,SAAA,SAAA,EAvF7B,kBAuF6B;EAA3C;;;AAOR;EACW,SAAA,YAAA,CAAA,EA1Fe,0BA0Ff;EACiB;EACvB,SAAA,WAAA,CAAA,EAAA,MAAA;EAA+B;;;AAGpC;AAMA;AAgBA;EACmC,SAAA,iBAAA,CAAA,EA7GJ,iBA6GI;EAAd;EAIM,SAAA,QAAA,CAAA,EAAA,MAAA;EAEN;EAAa,SAAA,cAAA,CAAA,EAAA,MAAA;EAajB;EAQL,SAAA,MAAA,CAAA,EAAA,CAAA,KAAkB,EAAA,OAAA,GAAA,MAAA,GAAA,MAAA,GAAA,OAAA,EAAA,OAAA,EAAA,MAAA,EAAA,MAAA,CAAA,EA/HjB,MA+HiB,CAAA,MAAA,EAAA,OAAA,CAAA,EAAA,GAAA,IAAA;EACnB;EACiB,SAAA,UAAA,CAAA,EAAA,MAAA;EACvB;EAA4B,SAAA,aAAA,CAAA,EAAA,MAAA;EAAR;;AAOzB;;;;EAoBgC,SAAA,kCAAA,CAAA,EAAA,OAAA;EAmBA;;;;;;;;;AAahC;;;;;EAIkC,SAAA,WAAA,CAAA,EAtKT,qBAsKS;EAKjB;AAQjB;AAWA;AAQA;;;;;;AAOA;EAmCiB,SAAA,QAAS,CAAA,EArOJ,kBAqOI;;;;;;;;AAwB8C,UApPvD,qBAAA,CAoPuD;EAAd;EAAR,SAAA,OAAA,EAAA,MAAA;EAClB;EAAsC,SAAA,eAAA,EAjP1C,QAiP0C,CAjPjC,MAiPiC,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA;;;;;;;;AAMR,KA9OlD,oBAAA,GA8OkD;EAIxC,SAAA,MAAA,EAAA,QAAA;EAC0B,SAAA,OAAA,CAAA,EAhPvB,QAgPuB,CA/OxC,MA+OwC,CAAA,MAAA,EAAA,MAAA,GAAA,MAAA,GAAA,OAAA,GA/OG,aA+OH,CAAA,MAAA,CAAA,CAAA,CAAA;CAAd,GAAA;EAA7B,SAAA,MAAA,EAAA,SAAA;CACY,GAAA;EAA0C,SAAA,MAAA,EAAA,QAAA;CAAd;;AAClC,KA1OC,qBAAA,GA0OD,CAAA,OAAA,EAzOA,qBAyOA,EAAA,IAAA,EAAA;EAAO,SAAA,MAAA,CAAA,EAxOU,WAwOV;AAIlB,CAAA,EAAA,GA3OK,oBA2O4B,GA3OL,OA6OR,CA7OgB,oBA6OF,CAAA;;KA1OtB,kBAAA;;;;;;;;;;;;;UAMK,kBAAA;;;;;;;oBAOG,cAAc;;;;;;;;UASjB,kBAAA;qBACI,cAAc;;;;2BAIR;;qBAEN;;;;;;;;;;;;;;UAaJ,iBAAA;;oBAEG;;;;;KAMR,kBAAA,aACD;oBACiB;MACvB,oBAAoB,QAAQ;;;;;;UAOhB,iBAAA;;2BAEU;;;;;;;iCAOM;;;;;;;;;;;gCAWD,SAAS;;;;;;;;;;;;;;;;;;;gCAmBT;;mCAEG,SAAS,eAAe;;kCAEzB,SAAS,eAAe,YAAY;;;;;;;;UASrD,iBAAA;;;wBAGO,SAAS;0BACP,SAAS;;;;UAKlB,qBAAA;;;;;;;UAQA,mBAAA;;;uBAGM;;;;;;;UAQN,kBAAA;;;;;;;UAQA,iBAAA;oBACG,cAAc;+BACH,SAAS;;;;KAK5B,cAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAmCK,SAAA;;;;;;;;;2BAMU;;8BAEG;;;;;;;;;;;;;;;aAeA;MAAgB,QAAQ,cAAc;;aAClC;MAAgB,QAAQ,cAAc;;aACxC;MAAgB,QAAQ,cAAc;;aAIhD;;MACjB,QAAQ;;aACiC;MAAgB,QAAQ;;aAIhD;MACjB;uBAA6B,cAAc;;iBAC/B,oBAAoB,QAAQ,cAAc;WAChD;;;UAIM,gBAAA;;oBAEG"}

package/dist/errors/index.d.ts

@@ -0,0 +1,120 @@
+//#region src/errors/index.d.ts
+/**
+ * Typed error union for the `@graphorin/mcp` package.
+ *
+ * Every error carries a stable lowercase {@link MCPErrorKind}
+ * discriminator, an actionable {@link MCPError.hint} field where
+ * applicable, and an optional structured `metadata` bag the audit
+ * emitter persists alongside the standard `runId` / `sessionId`
+ * context.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Discriminator union for every error class produced by
+ * `@graphorin/mcp`. New kinds extend this union; never throw plain
+ * `Error` from framework code.
+ *
+ * @stable
+ */
+type MCPErrorKind = 'connection-failed' | 'protocol-error' | 'auth-error' | 'tool-not-found' | 'tool-execution' | 'pin-mismatch' | 'call-timeout' | 'cancelled' | 'invalid-config' | 'session-lost' | 'transport-not-supported' | 'transport-resumable-not-supported';
+/** Common metadata bag attached to every {@link MCPError}. */
+interface MCPErrorMetadata {
+  readonly server?: string;
+  readonly tool?: string;
+  readonly transport?: 'stdio' | 'streamable-http' | 'sse';
+  readonly cause?: unknown;
+  readonly httpStatus?: number;
+  readonly sessionId?: string;
+  readonly lastEventId?: string;
+}
+/**
+ * Base class for every typed error produced by `@graphorin/mcp`.
+ *
+ * @stable
+ */
+declare abstract class GraphorinMCPError extends Error {
+  /** Lowercase discriminator. */
+  abstract readonly kind: MCPErrorKind;
+  /** Optional remediation hint surfaced in CLI output. */
+  readonly hint?: string;
+  /** Sanitized metadata; never carries secret material. */
+  readonly metadata: Readonly<MCPErrorMetadata>;
+  /** Underlying cause (chained errors). */
+  readonly cause?: unknown;
+  constructor(message: string, opts?: {
+    readonly hint?: string;
+    readonly metadata?: MCPErrorMetadata;
+    readonly cause?: unknown;
+  });
+}
+/** Raised when a transport fails to connect or is dropped unexpectedly. */
+declare class MCPConnectionError extends GraphorinMCPError {
+  readonly kind: "connection-failed";
+}
+/** Raised on JSON-RPC / MCP protocol-level errors. */
+declare class MCPProtocolError extends GraphorinMCPError {
+  readonly kind: "protocol-error";
+}
+/** Raised when an authentication / authorization step fails. */
+declare class MCPAuthError extends GraphorinMCPError {
+  readonly kind: "auth-error";
+}
+/** Raised when {@link MCPClient.callTool} is invoked for an unknown tool. */
+declare class MCPToolNotFoundError extends GraphorinMCPError {
+  readonly kind: "tool-not-found";
+}
+/**
+ * Raised when a pinned tool-definition fingerprint does not match the
+ * server's current definition and `onPinMismatch: 'reject'` is set
+ * (MC-6) — the approve-then-swap rug-pull posture.
+ */
+declare class MCPToolPinningError extends GraphorinMCPError {
+  readonly kind: "pin-mismatch";
+}
+/**
+ * Raised when the MCP server reports a tool-level failure
+ * (`CallToolResult.isError === true`, MC-4). The server's content text
+ * rides in the message so the model keeps its self-correction signal —
+ * while the executor records a real tool FAILURE (audit, retry and
+ * error policies all engage) instead of a fake success.
+ */
+declare class MCPToolExecutionError extends GraphorinMCPError {
+  readonly kind: "tool-execution";
+}
+/** Raised when a tool call exceeds its configured timeout / aborts. */
+declare class MCPCallTimeoutError extends GraphorinMCPError {
+  readonly kind: 'call-timeout' | 'session-lost';
+  constructor(message: string, opts: {
+    readonly hint?: string;
+    readonly metadata?: MCPErrorMetadata;
+    readonly cause?: unknown;
+    readonly variant?: 'call-timeout' | 'session-lost';
+  });
+}
+/** Raised when an in-flight call is cancelled by an `AbortSignal`. */
+declare class MCPCancelledError extends GraphorinMCPError {
+  readonly kind: "cancelled";
+}
+/** Raised on invalid `createMCPClient(...)` configuration. */
+declare class MCPInvalidConfigError extends GraphorinMCPError {
+  readonly kind: "invalid-config";
+}
+/**
+ * Raised when an operator requests a transport / capability that the
+ * runtime does not support (e.g. `resumable: true` on `stdio`).
+ *
+ * @stable
+ */
+declare class MCPTransportNotSupportedError extends GraphorinMCPError {
+  readonly kind: 'transport-not-supported' | 'transport-resumable-not-supported';
+  constructor(message: string, opts: {
+    readonly hint?: string;
+    readonly metadata?: MCPErrorMetadata;
+    readonly cause?: unknown;
+    readonly variant?: 'transport-not-supported' | 'transport-resumable-not-supported';
+  });
+}
+//#endregion
+export { GraphorinMCPError, MCPAuthError, MCPCallTimeoutError, MCPCancelledError, MCPConnectionError, MCPErrorKind, MCPErrorMetadata, MCPInvalidConfigError, MCPProtocolError, MCPToolExecutionError, MCPToolNotFoundError, MCPToolPinningError, MCPTransportNotSupportedError };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/errors/index.ts"],"sourcesContent":[],"mappings":";;AAmBA;AAeA;AAeA;;;;;;;AA2BA;AAKA;AAKA;AAKA;AASA;AAWA;AAKA;AAoBA;AAKa,KA1HD,YAAA,GA0HC,mBAA8B,GAAA,gBAAiB,GAAA,YAAA,GAAA,gBAAA,GAAA,gBAAA,GAAA,cAAA,GAAA,cAAA,GAAA,WAAA,GAAA,gBAAA,GAAA,cAAA,GAAA,yBAAA,GAAA,mCAAA;AAU5D;UArHiB,gBAAA;;;;;;;;;;;;;;uBAeK,iBAAA,SAA0B,KAAA;;0BAEf;;;;qBAIL,SAAS;;;;;wBAQX;;;;;cAab,kBAAA,SAA2B,iBAAA;;;;cAK3B,gBAAA,SAAyB,iBAAA;;;;cAKzB,YAAA,SAAqB,iBAAA;;;;cAKrB,oBAAA,SAA6B,iBAAA;;;;;;;;cAS7B,mBAAA,SAA4B,iBAAA;;;;;;;;;;cAW5B,qBAAA,SAA8B,iBAAA;;;;cAK9B,mBAAA,SAA4B,iBAAA;;;;wBAOf;;;;;;cAab,iBAAA,SAA0B,iBAAA;;;;cAK1B,qBAAA,SAA8B,iBAAA;;;;;;;;;cAU9B,6BAAA,SAAsC,iBAAA;;;;wBAQzB"}

package/dist/errors/index.js

@@ -0,0 +1,88 @@
+//#region src/errors/index.ts
+/**
+* Base class for every typed error produced by `@graphorin/mcp`.
+*
+* @stable
+*/
+var GraphorinMCPError = class extends Error {
+	/** Optional remediation hint surfaced in CLI output. */
+	hint;
+	/** Sanitized metadata; never carries secret material. */
+	metadata;
+	/** Underlying cause (chained errors). */
+	cause;
+	constructor(message, opts = {}) {
+		super(message);
+		this.name = new.target.name;
+		if (opts.hint !== void 0) this.hint = opts.hint;
+		this.metadata = Object.freeze({ ...opts.metadata ?? {} });
+		if (opts.cause !== void 0) this.cause = opts.cause;
+	}
+};
+/** Raised when a transport fails to connect or is dropped unexpectedly. */
+var MCPConnectionError = class extends GraphorinMCPError {
+	kind = "connection-failed";
+};
+/** Raised on JSON-RPC / MCP protocol-level errors. */
+var MCPProtocolError = class extends GraphorinMCPError {
+	kind = "protocol-error";
+};
+/** Raised when an authentication / authorization step fails. */
+var MCPAuthError = class extends GraphorinMCPError {
+	kind = "auth-error";
+};
+/** Raised when {@link MCPClient.callTool} is invoked for an unknown tool. */
+var MCPToolNotFoundError = class extends GraphorinMCPError {
+	kind = "tool-not-found";
+};
+/**
+* Raised when a pinned tool-definition fingerprint does not match the
+* server's current definition and `onPinMismatch: 'reject'` is set
+* (MC-6) — the approve-then-swap rug-pull posture.
+*/
+var MCPToolPinningError = class extends GraphorinMCPError {
+	kind = "pin-mismatch";
+};
+/**
+* Raised when the MCP server reports a tool-level failure
+* (`CallToolResult.isError === true`, MC-4). The server's content text
+* rides in the message so the model keeps its self-correction signal —
+* while the executor records a real tool FAILURE (audit, retry and
+* error policies all engage) instead of a fake success.
+*/
+var MCPToolExecutionError = class extends GraphorinMCPError {
+	kind = "tool-execution";
+};
+/** Raised when a tool call exceeds its configured timeout / aborts. */
+var MCPCallTimeoutError = class extends GraphorinMCPError {
+	kind = "call-timeout";
+	constructor(message, opts) {
+		super(message, opts);
+		if (opts.variant !== void 0) this.kind = opts.variant;
+	}
+};
+/** Raised when an in-flight call is cancelled by an `AbortSignal`. */
+var MCPCancelledError = class extends GraphorinMCPError {
+	kind = "cancelled";
+};
+/** Raised on invalid `createMCPClient(...)` configuration. */
+var MCPInvalidConfigError = class extends GraphorinMCPError {
+	kind = "invalid-config";
+};
+/**
+* Raised when an operator requests a transport / capability that the
+* runtime does not support (e.g. `resumable: true` on `stdio`).
+*
+* @stable
+*/
+var MCPTransportNotSupportedError = class extends GraphorinMCPError {
+	kind = "transport-not-supported";
+	constructor(message, opts) {
+		super(message, opts);
+		if (opts.variant !== void 0) this.kind = opts.variant;
+	}
+};
+
+//#endregion
+export { GraphorinMCPError, MCPAuthError, MCPCallTimeoutError, MCPCancelledError, MCPConnectionError, MCPInvalidConfigError, MCPProtocolError, MCPToolExecutionError, MCPToolNotFoundError, MCPToolPinningError, MCPTransportNotSupportedError };
+//# sourceMappingURL=index.js.map