@graphorin/mcp 0.5.0

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/errors/index.ts"],"sourcesContent":["/**\n * Typed error union for the `@graphorin/mcp` package.\n *\n * Every error carries a stable lowercase {@link MCPErrorKind}\n * discriminator, an actionable {@link MCPError.hint} field where\n * applicable, and an optional structured `metadata` bag the audit\n * emitter persists alongside the standard `runId` / `sessionId`\n * context.\n *\n * @packageDocumentation\n */\n\n/**\n * Discriminator union for every error class produced by\n * `@graphorin/mcp`. New kinds extend this union; never throw plain\n * `Error` from framework code.\n *\n * @stable\n */\nexport type MCPErrorKind =\n  | 'connection-failed'\n  | 'protocol-error'\n  | 'auth-error'\n  | 'tool-not-found'\n  | 'tool-execution'\n  | 'pin-mismatch'\n  | 'call-timeout'\n  | 'cancelled'\n  | 'invalid-config'\n  | 'session-lost'\n  | 'transport-not-supported'\n  | 'transport-resumable-not-supported';\n\n/** Common metadata bag attached to every {@link MCPError}. */\nexport interface MCPErrorMetadata {\n  readonly server?: string;\n  readonly tool?: string;\n  readonly transport?: 'stdio' | 'streamable-http' | 'sse';\n  readonly cause?: unknown;\n  readonly httpStatus?: number;\n  readonly sessionId?: string;\n  readonly lastEventId?: string;\n}\n\n/**\n * Base class for every typed error produced by `@graphorin/mcp`.\n *\n * @stable\n */\nexport abstract class GraphorinMCPError extends Error {\n  /** Lowercase discriminator. */\n  public abstract readonly kind: MCPErrorKind;\n  /** Optional remediation hint surfaced in CLI output. */\n  public readonly hint?: string;\n  /** Sanitized metadata; never carries secret material. */\n  public readonly metadata: Readonly<MCPErrorMetadata>;\n  /** Underlying cause (chained errors). */\n  public override readonly cause?: unknown;\n\n  public constructor(\n    message: string,\n    opts: {\n      readonly hint?: string;\n      readonly metadata?: MCPErrorMetadata;\n      readonly cause?: unknown;\n    } = {},\n  ) {\n    super(message);\n    this.name = new.target.name;\n    if (opts.hint !== undefined) this.hint = opts.hint;\n    this.metadata = Object.freeze({ ...(opts.metadata ?? {}) });\n    if (opts.cause !== undefined) this.cause = opts.cause;\n  }\n}\n\n/** Raised when a transport fails to connect or is dropped unexpectedly. */\nexport class MCPConnectionError extends GraphorinMCPError {\n  public readonly kind = 'connection-failed' as const;\n}\n\n/** Raised on JSON-RPC / MCP protocol-level errors. */\nexport class MCPProtocolError extends GraphorinMCPError {\n  public readonly kind = 'protocol-error' as const;\n}\n\n/** Raised when an authentication / authorization step fails. */\nexport class MCPAuthError extends GraphorinMCPError {\n  public readonly kind = 'auth-error' as const;\n}\n\n/** Raised when {@link MCPClient.callTool} is invoked for an unknown tool. */\nexport class MCPToolNotFoundError extends GraphorinMCPError {\n  public readonly kind = 'tool-not-found' as const;\n}\n\n/**\n * Raised when a pinned tool-definition fingerprint does not match the\n * server's current definition and `onPinMismatch: 'reject'` is set\n * (MC-6) — the approve-then-swap rug-pull posture.\n */\nexport class MCPToolPinningError extends GraphorinMCPError {\n  public readonly kind = 'pin-mismatch' as const;\n}\n\n/**\n * Raised when the MCP server reports a tool-level failure\n * (`CallToolResult.isError === true`, MC-4). The server's content text\n * rides in the message so the model keeps its self-correction signal —\n * while the executor records a real tool FAILURE (audit, retry and\n * error policies all engage) instead of a fake success.\n */\nexport class MCPToolExecutionError extends GraphorinMCPError {\n  public readonly kind = 'tool-execution' as const;\n}\n\n/** Raised when a tool call exceeds its configured timeout / aborts. */\nexport class MCPCallTimeoutError extends GraphorinMCPError {\n  public readonly kind: 'call-timeout' | 'session-lost' = 'call-timeout';\n\n  public constructor(\n    message: string,\n    opts: {\n      readonly hint?: string;\n      readonly metadata?: MCPErrorMetadata;\n      readonly cause?: unknown;\n      readonly variant?: 'call-timeout' | 'session-lost';\n    },\n  ) {\n    super(message, opts);\n    if (opts.variant !== undefined) {\n      this.kind = opts.variant;\n    }\n  }\n}\n\n/** Raised when an in-flight call is cancelled by an `AbortSignal`. */\nexport class MCPCancelledError extends GraphorinMCPError {\n  public readonly kind = 'cancelled' as const;\n}\n\n/** Raised on invalid `createMCPClient(...)` configuration. */\nexport class MCPInvalidConfigError extends GraphorinMCPError {\n  public readonly kind = 'invalid-config' as const;\n}\n\n/**\n * Raised when an operator requests a transport / capability that the\n * runtime does not support (e.g. `resumable: true` on `stdio`).\n *\n * @stable\n */\nexport class MCPTransportNotSupportedError extends GraphorinMCPError {\n  public readonly kind: 'transport-not-supported' | 'transport-resumable-not-supported' =\n    'transport-not-supported';\n\n  public constructor(\n    message: string,\n    opts: {\n      readonly hint?: string;\n      readonly metadata?: MCPErrorMetadata;\n      readonly cause?: unknown;\n      readonly variant?: 'transport-not-supported' | 'transport-resumable-not-supported';\n    },\n  ) {\n    super(message, opts);\n    if (opts.variant !== undefined) {\n      this.kind = opts.variant;\n    }\n  }\n}\n"],"mappings":";;;;;;AAiDA,IAAsB,oBAAtB,cAAgD,MAAM;;CAIpD,AAAgB;;CAEhB,AAAgB;;CAEhB,AAAyB;CAEzB,AAAO,YACL,SACA,OAII,EAAE,EACN;AACA,QAAM,QAAQ;AACd,OAAK,OAAO,IAAI,OAAO;AACvB,MAAI,KAAK,SAAS,OAAW,MAAK,OAAO,KAAK;AAC9C,OAAK,WAAW,OAAO,OAAO,EAAE,GAAI,KAAK,YAAY,EAAE,EAAG,CAAC;AAC3D,MAAI,KAAK,UAAU,OAAW,MAAK,QAAQ,KAAK;;;;AAKpD,IAAa,qBAAb,cAAwC,kBAAkB;CACxD,AAAgB,OAAO;;;AAIzB,IAAa,mBAAb,cAAsC,kBAAkB;CACtD,AAAgB,OAAO;;;AAIzB,IAAa,eAAb,cAAkC,kBAAkB;CAClD,AAAgB,OAAO;;;AAIzB,IAAa,uBAAb,cAA0C,kBAAkB;CAC1D,AAAgB,OAAO;;;;;;;AAQzB,IAAa,sBAAb,cAAyC,kBAAkB;CACzD,AAAgB,OAAO;;;;;;;;;AAUzB,IAAa,wBAAb,cAA2C,kBAAkB;CAC3D,AAAgB,OAAO;;;AAIzB,IAAa,sBAAb,cAAyC,kBAAkB;CACzD,AAAgB,OAAwC;CAExD,AAAO,YACL,SACA,MAMA;AACA,QAAM,SAAS,KAAK;AACpB,MAAI,KAAK,YAAY,OACnB,MAAK,OAAO,KAAK;;;;AAMvB,IAAa,oBAAb,cAAuC,kBAAkB;CACvD,AAAgB,OAAO;;;AAIzB,IAAa,wBAAb,cAA2C,kBAAkB;CAC3D,AAAgB,OAAO;;;;;;;;AASzB,IAAa,gCAAb,cAAmD,kBAAkB;CACnE,AAAgB,OACd;CAEF,AAAO,YACL,SACA,MAMA;AACA,QAAM,SAAS,KAAK;AACpB,MAAI,KAAK,YAAY,OACnB,MAAK,OAAO,KAAK"}

package/dist/helpers/identity.d.ts

@@ -0,0 +1,22 @@
+import { MCPTransportConfig, ServerIdentity } from "../transport/types.js";
+
+//#region src/helpers/identity.d.ts
+
+/**
+ * Compute the canonical {@link ServerIdentity} for the supplied
+ * transport. The id is suitable for use as a registry key and as the
+ * operator-facing label in audit rows + trace attributes.
+ *
+ * @stable
+ */
+declare function deriveServerIdentity(transport: MCPTransportConfig, serverInfoName?: string): ServerIdentity;
+/**
+ * Operator-facing single-line label for a {@link MCPTransportConfig}.
+ * Suitable for trace attributes, audit rows, and CLI output.
+ *
+ * @stable
+ */
+declare function formatMCPServerName(transport: MCPTransportConfig): string;
+//#endregion
+export { deriveServerIdentity, formatMCPServerName };
+//# sourceMappingURL=identity.d.ts.map

package/dist/helpers/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","names":[],"sources":["../../src/helpers/identity.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;iBAyBgB,oBAAA,YACH,8CAEV;;;;;;;iBA0Ea,mBAAA,YAA+B"}

package/dist/helpers/identity.js

@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+
+//#region src/helpers/identity.ts
+/**
+* Helpers for deriving stable {@link ServerIdentity} records from the
+* supplied {@link MCPTransportConfig}, plus the operator-facing
+* formatter the audit emitter and the trace span attributes use.
+*
+* @packageDocumentation
+*/
+/**
+* Compute the canonical {@link ServerIdentity} for the supplied
+* transport. The id is suitable for use as a registry key and as the
+* operator-facing label in audit rows + trace attributes.
+*
+* @stable
+*/
+function deriveServerIdentity(transport, serverInfoName) {
+	switch (transport.kind) {
+		case "stdio": return deriveStdioIdentity(transport, serverInfoName);
+		case "streamable-http": return deriveStreamableHttpIdentity(transport, serverInfoName);
+		case "sse": return deriveSseIdentity(transport, serverInfoName);
+	}
+}
+function deriveStdioIdentity(transport, serverInfoName) {
+	const argsHash = createHash("sha256").update((transport.args ?? []).join("\0")).digest("hex").slice(0, 16);
+	const command = basenameWithoutExt(transport.command);
+	const id = serverInfoName ?? `${command}-${argsHash}`;
+	return Object.freeze({
+		kind: "mcp-stdio",
+		id,
+		command,
+		argsHash,
+		...serverInfoName === void 0 ? {} : { serverInfoName }
+	});
+}
+function deriveStreamableHttpIdentity(transport, serverInfoName) {
+	const url = new URL(typeof transport.url === "string" ? transport.url : transport.url.toString());
+	const urlHostname = url.hostname;
+	const urlPath = url.pathname.length === 0 ? "/" : url.pathname;
+	const id = serverInfoName ?? `${urlHostname}${urlPath}`;
+	return Object.freeze({
+		kind: "mcp-streamable-http",
+		id,
+		urlHostname,
+		urlPath,
+		...serverInfoName === void 0 ? {} : { serverInfoName }
+	});
+}
+function deriveSseIdentity(transport, serverInfoName) {
+	const url = new URL(typeof transport.url === "string" ? transport.url : transport.url.toString());
+	const urlHostname = url.hostname;
+	const urlPath = url.pathname.length === 0 ? "/" : url.pathname;
+	const id = serverInfoName ?? `${urlHostname}${urlPath}`;
+	return Object.freeze({
+		kind: "mcp-sse",
+		id,
+		urlHostname,
+		urlPath,
+		...serverInfoName === void 0 ? {} : { serverInfoName }
+	});
+}
+function basenameWithoutExt(command) {
+	const slashIdx = Math.max(command.lastIndexOf("/"), command.lastIndexOf("\\"));
+	const base = slashIdx === -1 ? command : command.slice(slashIdx + 1);
+	const dotIdx = base.lastIndexOf(".");
+	return dotIdx <= 0 ? base : base.slice(0, dotIdx);
+}
+/**
+* Operator-facing single-line label for a {@link MCPTransportConfig}.
+* Suitable for trace attributes, audit rows, and CLI output.
+*
+* @stable
+*/
+function formatMCPServerName(transport) {
+	switch (transport.kind) {
+		case "stdio": return `stdio:${basenameWithoutExt(transport.command)}${(transport.args ?? []).length === 0 ? "" : ` ${(transport.args ?? []).join(" ")}`}`;
+		case "streamable-http": return `streamable-http:${typeof transport.url === "string" ? transport.url : transport.url.toString()}`;
+		case "sse": return `sse:${typeof transport.url === "string" ? transport.url : transport.url.toString()}`;
+	}
+}
+
+//#endregion
+export { deriveServerIdentity, formatMCPServerName };
+//# sourceMappingURL=identity.js.map

package/dist/helpers/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","names":[],"sources":["../../src/helpers/identity.ts"],"sourcesContent":["/**\n * Helpers for deriving stable {@link ServerIdentity} records from the\n * supplied {@link MCPTransportConfig}, plus the operator-facing\n * formatter the audit emitter and the trace span attributes use.\n *\n * @packageDocumentation\n */\n\nimport { createHash } from 'node:crypto';\n\nimport type {\n  MCPTransportConfig,\n  ServerIdentity,\n  SseTransportConfig,\n  StdioTransportConfig,\n  StreamableHttpTransportConfig,\n} from '../transport/types.js';\n\n/**\n * Compute the canonical {@link ServerIdentity} for the supplied\n * transport. The id is suitable for use as a registry key and as the\n * operator-facing label in audit rows + trace attributes.\n *\n * @stable\n */\nexport function deriveServerIdentity(\n  transport: MCPTransportConfig,\n  serverInfoName?: string,\n): ServerIdentity {\n  switch (transport.kind) {\n    case 'stdio':\n      return deriveStdioIdentity(transport, serverInfoName);\n    case 'streamable-http':\n      return deriveStreamableHttpIdentity(transport, serverInfoName);\n    case 'sse':\n      return deriveSseIdentity(transport, serverInfoName);\n  }\n}\n\nfunction deriveStdioIdentity(\n  transport: StdioTransportConfig,\n  serverInfoName?: string,\n): ServerIdentity {\n  const argsHash = createHash('sha256')\n    .update((transport.args ?? []).join('\\u0000'))\n    .digest('hex')\n    .slice(0, 16);\n  const command = basenameWithoutExt(transport.command);\n  const id = serverInfoName ?? `${command}-${argsHash}`;\n  return Object.freeze({\n    kind: 'mcp-stdio',\n    id,\n    command,\n    argsHash,\n    ...(serverInfoName === undefined ? {} : { serverInfoName }),\n  });\n}\n\nfunction deriveStreamableHttpIdentity(\n  transport: StreamableHttpTransportConfig,\n  serverInfoName?: string,\n): ServerIdentity {\n  const url = new URL(typeof transport.url === 'string' ? transport.url : transport.url.toString());\n  const urlHostname = url.hostname;\n  const urlPath = url.pathname.length === 0 ? '/' : url.pathname;\n  const id = serverInfoName ?? `${urlHostname}${urlPath}`;\n  return Object.freeze({\n    kind: 'mcp-streamable-http',\n    id,\n    urlHostname,\n    urlPath,\n    ...(serverInfoName === undefined ? {} : { serverInfoName }),\n  });\n}\n\nfunction deriveSseIdentity(transport: SseTransportConfig, serverInfoName?: string): ServerIdentity {\n  const url = new URL(typeof transport.url === 'string' ? transport.url : transport.url.toString());\n  const urlHostname = url.hostname;\n  const urlPath = url.pathname.length === 0 ? '/' : url.pathname;\n  const id = serverInfoName ?? `${urlHostname}${urlPath}`;\n  return Object.freeze({\n    kind: 'mcp-sse',\n    id,\n    urlHostname,\n    urlPath,\n    ...(serverInfoName === undefined ? {} : { serverInfoName }),\n  });\n}\n\nfunction basenameWithoutExt(command: string): string {\n  const slashIdx = Math.max(command.lastIndexOf('/'), command.lastIndexOf('\\\\'));\n  const base = slashIdx === -1 ? command : command.slice(slashIdx + 1);\n  const dotIdx = base.lastIndexOf('.');\n  return dotIdx <= 0 ? base : base.slice(0, dotIdx);\n}\n\n/**\n * Operator-facing single-line label for a {@link MCPTransportConfig}.\n * Suitable for trace attributes, audit rows, and CLI output.\n *\n * @stable\n */\nexport function formatMCPServerName(transport: MCPTransportConfig): string {\n  switch (transport.kind) {\n    case 'stdio':\n      return `stdio:${basenameWithoutExt(transport.command)}${\n        (transport.args ?? []).length === 0 ? '' : ` ${(transport.args ?? []).join(' ')}`\n      }`;\n    case 'streamable-http':\n      return `streamable-http:${typeof transport.url === 'string' ? transport.url : transport.url.toString()}`;\n    case 'sse':\n      return `sse:${typeof transport.url === 'string' ? transport.url : transport.url.toString()}`;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAyBA,SAAgB,qBACd,WACA,gBACgB;AAChB,SAAQ,UAAU,MAAlB;EACE,KAAK,QACH,QAAO,oBAAoB,WAAW,eAAe;EACvD,KAAK,kBACH,QAAO,6BAA6B,WAAW,eAAe;EAChE,KAAK,MACH,QAAO,kBAAkB,WAAW,eAAe;;;AAIzD,SAAS,oBACP,WACA,gBACgB;CAChB,MAAM,WAAW,WAAW,SAAS,CAClC,QAAQ,UAAU,QAAQ,EAAE,EAAE,KAAK,KAAS,CAAC,CAC7C,OAAO,MAAM,CACb,MAAM,GAAG,GAAG;CACf,MAAM,UAAU,mBAAmB,UAAU,QAAQ;CACrD,MAAM,KAAK,kBAAkB,GAAG,QAAQ,GAAG;AAC3C,QAAO,OAAO,OAAO;EACnB,MAAM;EACN;EACA;EACA;EACA,GAAI,mBAAmB,SAAY,EAAE,GAAG,EAAE,gBAAgB;EAC3D,CAAC;;AAGJ,SAAS,6BACP,WACA,gBACgB;CAChB,MAAM,MAAM,IAAI,IAAI,OAAO,UAAU,QAAQ,WAAW,UAAU,MAAM,UAAU,IAAI,UAAU,CAAC;CACjG,MAAM,cAAc,IAAI;CACxB,MAAM,UAAU,IAAI,SAAS,WAAW,IAAI,MAAM,IAAI;CACtD,MAAM,KAAK,kBAAkB,GAAG,cAAc;AAC9C,QAAO,OAAO,OAAO;EACnB,MAAM;EACN;EACA;EACA;EACA,GAAI,mBAAmB,SAAY,EAAE,GAAG,EAAE,gBAAgB;EAC3D,CAAC;;AAGJ,SAAS,kBAAkB,WAA+B,gBAAyC;CACjG,MAAM,MAAM,IAAI,IAAI,OAAO,UAAU,QAAQ,WAAW,UAAU,MAAM,UAAU,IAAI,UAAU,CAAC;CACjG,MAAM,cAAc,IAAI;CACxB,MAAM,UAAU,IAAI,SAAS,WAAW,IAAI,MAAM,IAAI;CACtD,MAAM,KAAK,kBAAkB,GAAG,cAAc;AAC9C,QAAO,OAAO,OAAO;EACnB,MAAM;EACN;EACA;EACA;EACA,GAAI,mBAAmB,SAAY,EAAE,GAAG,EAAE,gBAAgB;EAC3D,CAAC;;AAGJ,SAAS,mBAAmB,SAAyB;CACnD,MAAM,WAAW,KAAK,IAAI,QAAQ,YAAY,IAAI,EAAE,QAAQ,YAAY,KAAK,CAAC;CAC9E,MAAM,OAAO,aAAa,KAAK,UAAU,QAAQ,MAAM,WAAW,EAAE;CACpE,MAAM,SAAS,KAAK,YAAY,IAAI;AACpC,QAAO,UAAU,IAAI,OAAO,KAAK,MAAM,GAAG,OAAO;;;;;;;;AASnD,SAAgB,oBAAoB,WAAuC;AACzE,SAAQ,UAAU,MAAlB;EACE,KAAK,QACH,QAAO,SAAS,mBAAmB,UAAU,QAAQ,IAClD,UAAU,QAAQ,EAAE,EAAE,WAAW,IAAI,KAAK,KAAK,UAAU,QAAQ,EAAE,EAAE,KAAK,IAAI;EAEnF,KAAK,kBACH,QAAO,mBAAmB,OAAO,UAAU,QAAQ,WAAW,UAAU,MAAM,UAAU,IAAI,UAAU;EACxG,KAAK,MACH,QAAO,OAAO,OAAO,UAAU,QAAQ,WAAW,UAAU,MAAM,UAAU,IAAI,UAAU"}

package/dist/helpers/index.d.ts

@@ -0,0 +1,3 @@
+import { deriveServerIdentity, formatMCPServerName } from "./identity.js";
+import { validateMCPServerConfig } from "./validate-config.js";
+export { deriveServerIdentity, formatMCPServerName, validateMCPServerConfig };

package/dist/helpers/index.js

@@ -0,0 +1,4 @@
+import { deriveServerIdentity, formatMCPServerName } from "./identity.js";
+import { validateMCPServerConfig } from "./validate-config.js";
+
+export { deriveServerIdentity, formatMCPServerName, validateMCPServerConfig };

package/dist/helpers/validate-config.d.ts

@@ -0,0 +1,16 @@
+import { MCPTransportConfig } from "../transport/types.js";
+
+//#region src/helpers/validate-config.d.ts
+
+/**
+ * Throws {@link MCPInvalidConfigError} on invalid configuration.
+ *
+ * @stable
+ */
+declare function validateMCPServerConfig(opts: {
+  readonly transport: MCPTransportConfig;
+  readonly resumable?: boolean;
+}): void;
+//#endregion
+export { validateMCPServerConfig };
+//# sourceMappingURL=validate-config.d.ts.map

package/dist/helpers/validate-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-config.d.ts","names":[],"sources":["../../src/helpers/validate-config.ts"],"sourcesContent":[],"mappings":";;;;;;;;;iBAqBgB,uBAAA;sBACM"}

package/dist/helpers/validate-config.js

@@ -0,0 +1,61 @@
+import { MCPInvalidConfigError, MCPTransportNotSupportedError } from "../errors/index.js";
+
+//#region src/helpers/validate-config.ts
+/**
+* `validateMCPServerConfig(...)` — sanity-check a transport configuration
+* before {@link createMCPClient} runs the network-level handshake.
+*
+* The validator catches the most common configuration mistakes
+* (missing url for HTTP transports, empty command for stdio,
+* unsupported `resumable: true` for stdio / sse, …) and surfaces them
+* as {@link MCPInvalidConfigError} so the operator does not have to
+* read a transport-specific stack trace.
+*
+* @packageDocumentation
+*/
+/**
+* Throws {@link MCPInvalidConfigError} on invalid configuration.
+*
+* @stable
+*/
+function validateMCPServerConfig(opts) {
+	validateTransport(opts.transport);
+	if (opts.resumable === true) {
+		if (opts.transport.kind === "stdio") throw new MCPTransportNotSupportedError("Resumable streaming sessions are not supported on the stdio transport.", {
+			variant: "transport-resumable-not-supported",
+			metadata: { transport: "stdio" },
+			hint: "Use the streamable-http transport when you need Mcp-Session-Id + Last-Event-ID resume semantics."
+		});
+		if (opts.transport.kind === "sse") throw new MCPTransportNotSupportedError("Resumable streaming sessions are not supported on the deprecated sse transport.", {
+			variant: "transport-resumable-not-supported",
+			metadata: { transport: "sse" },
+			hint: "Migrate to the streamable-http transport for resumable session support."
+		});
+	}
+}
+function validateTransport(transport) {
+	switch (transport.kind) {
+		case "stdio":
+			if (typeof transport.command !== "string" || transport.command.length === 0) throw new MCPInvalidConfigError("stdio transport requires a non-empty `command`.", { metadata: { transport: "stdio" } });
+			if (transport.args !== void 0 && !Array.isArray(transport.args)) throw new MCPInvalidConfigError("stdio transport `args` must be an array of strings.", { metadata: { transport: "stdio" } });
+			return;
+		case "streamable-http":
+		case "sse":
+			if (transport.url === void 0 || transport.url === null || transport.url === "") throw new MCPInvalidConfigError(`${transport.kind} transport requires a non-empty \`url\`.`, { metadata: { transport: transport.kind } });
+			try {
+				const candidate = typeof transport.url === "string" ? new URL(transport.url) : transport.url;
+				if (candidate.protocol !== "http:" && candidate.protocol !== "https:") throw new MCPInvalidConfigError(`${transport.kind} transport \`url\` must use http: or https: (got ${candidate.protocol}).`, { metadata: { transport: transport.kind } });
+			} catch (cause) {
+				if (cause instanceof MCPInvalidConfigError) throw cause;
+				throw new MCPInvalidConfigError(`${transport.kind} transport \`url\` is not a valid URL.`, {
+					metadata: { transport: transport.kind },
+					cause
+				});
+			}
+			return;
+	}
+}
+
+//#endregion
+export { validateMCPServerConfig };
+//# sourceMappingURL=validate-config.js.map

package/dist/helpers/validate-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-config.js","names":[],"sources":["../../src/helpers/validate-config.ts"],"sourcesContent":["/**\n * `validateMCPServerConfig(...)` — sanity-check a transport configuration\n * before {@link createMCPClient} runs the network-level handshake.\n *\n * The validator catches the most common configuration mistakes\n * (missing url for HTTP transports, empty command for stdio,\n * unsupported `resumable: true` for stdio / sse, …) and surfaces them\n * as {@link MCPInvalidConfigError} so the operator does not have to\n * read a transport-specific stack trace.\n *\n * @packageDocumentation\n */\n\nimport { MCPInvalidConfigError, MCPTransportNotSupportedError } from '../errors/index.js';\nimport type { MCPTransportConfig } from '../transport/types.js';\n\n/**\n * Throws {@link MCPInvalidConfigError} on invalid configuration.\n *\n * @stable\n */\nexport function validateMCPServerConfig(opts: {\n  readonly transport: MCPTransportConfig;\n  readonly resumable?: boolean;\n}): void {\n  validateTransport(opts.transport);\n  if (opts.resumable === true) {\n    if (opts.transport.kind === 'stdio') {\n      throw new MCPTransportNotSupportedError(\n        'Resumable streaming sessions are not supported on the stdio transport.',\n        {\n          variant: 'transport-resumable-not-supported',\n          metadata: { transport: 'stdio' },\n          hint: 'Use the streamable-http transport when you need Mcp-Session-Id + Last-Event-ID resume semantics.',\n        },\n      );\n    }\n    if (opts.transport.kind === 'sse') {\n      throw new MCPTransportNotSupportedError(\n        'Resumable streaming sessions are not supported on the deprecated sse transport.',\n        {\n          variant: 'transport-resumable-not-supported',\n          metadata: { transport: 'sse' },\n          hint: 'Migrate to the streamable-http transport for resumable session support.',\n        },\n      );\n    }\n  }\n}\n\nfunction validateTransport(transport: MCPTransportConfig): void {\n  switch (transport.kind) {\n    case 'stdio': {\n      if (typeof transport.command !== 'string' || transport.command.length === 0) {\n        throw new MCPInvalidConfigError('stdio transport requires a non-empty `command`.', {\n          metadata: { transport: 'stdio' },\n        });\n      }\n      if (transport.args !== undefined && !Array.isArray(transport.args)) {\n        throw new MCPInvalidConfigError('stdio transport `args` must be an array of strings.', {\n          metadata: { transport: 'stdio' },\n        });\n      }\n      return;\n    }\n    case 'streamable-http':\n    case 'sse': {\n      if (transport.url === undefined || transport.url === null || transport.url === '') {\n        throw new MCPInvalidConfigError(\n          `${transport.kind} transport requires a non-empty \\`url\\`.`,\n          {\n            metadata: { transport: transport.kind },\n          },\n        );\n      }\n      try {\n        const candidate =\n          typeof transport.url === 'string' ? new URL(transport.url) : transport.url;\n        if (candidate.protocol !== 'http:' && candidate.protocol !== 'https:') {\n          throw new MCPInvalidConfigError(\n            `${transport.kind} transport \\`url\\` must use http: or https: (got ${candidate.protocol}).`,\n            { metadata: { transport: transport.kind } },\n          );\n        }\n      } catch (cause) {\n        if (cause instanceof MCPInvalidConfigError) throw cause;\n        throw new MCPInvalidConfigError(`${transport.kind} transport \\`url\\` is not a valid URL.`, {\n          metadata: { transport: transport.kind },\n          cause,\n        });\n      }\n      return;\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,wBAAwB,MAG/B;AACP,mBAAkB,KAAK,UAAU;AACjC,KAAI,KAAK,cAAc,MAAM;AAC3B,MAAI,KAAK,UAAU,SAAS,QAC1B,OAAM,IAAI,8BACR,0EACA;GACE,SAAS;GACT,UAAU,EAAE,WAAW,SAAS;GAChC,MAAM;GACP,CACF;AAEH,MAAI,KAAK,UAAU,SAAS,MAC1B,OAAM,IAAI,8BACR,mFACA;GACE,SAAS;GACT,UAAU,EAAE,WAAW,OAAO;GAC9B,MAAM;GACP,CACF;;;AAKP,SAAS,kBAAkB,WAAqC;AAC9D,SAAQ,UAAU,MAAlB;EACE,KAAK;AACH,OAAI,OAAO,UAAU,YAAY,YAAY,UAAU,QAAQ,WAAW,EACxE,OAAM,IAAI,sBAAsB,mDAAmD,EACjF,UAAU,EAAE,WAAW,SAAS,EACjC,CAAC;AAEJ,OAAI,UAAU,SAAS,UAAa,CAAC,MAAM,QAAQ,UAAU,KAAK,CAChE,OAAM,IAAI,sBAAsB,uDAAuD,EACrF,UAAU,EAAE,WAAW,SAAS,EACjC,CAAC;AAEJ;EAEF,KAAK;EACL,KAAK;AACH,OAAI,UAAU,QAAQ,UAAa,UAAU,QAAQ,QAAQ,UAAU,QAAQ,GAC7E,OAAM,IAAI,sBACR,GAAG,UAAU,KAAK,2CAClB,EACE,UAAU,EAAE,WAAW,UAAU,MAAM,EACxC,CACF;AAEH,OAAI;IACF,MAAM,YACJ,OAAO,UAAU,QAAQ,WAAW,IAAI,IAAI,UAAU,IAAI,GAAG,UAAU;AACzE,QAAI,UAAU,aAAa,WAAW,UAAU,aAAa,SAC3D,OAAM,IAAI,sBACR,GAAG,UAAU,KAAK,mDAAmD,UAAU,SAAS,KACxF,EAAE,UAAU,EAAE,WAAW,UAAU,MAAM,EAAE,CAC5C;YAEI,OAAO;AACd,QAAI,iBAAiB,sBAAuB,OAAM;AAClD,UAAM,IAAI,sBAAsB,GAAG,UAAU,KAAK,yCAAyC;KACzF,UAAU,EAAE,WAAW,UAAU,MAAM;KACvC;KACD,CAAC;;AAEJ"}

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+import { MCPTransportConfig, ServerIdentity, SseTransportConfig, StdioTransportConfig, StreamableHttpTransportConfig } from "./transport/types.js";
+import { OAuthAuthorizationProvider, OAuthAuthorizationProviderOptions, createOAuthAuthorizationProvider } from "./oauth/bridge.js";
+import { CreateMCPClientOptions, MCPCallToolResult, MCPClient, MCPContentPart, MCPElicitationHandler, MCPElicitationRequest, MCPElicitationResult, MCPPromptDefinition, MCPPromptMessage, MCPResourceContent, MCPResourceDefinition, MCPSamplingContent, MCPSamplingHandler, MCPSamplingMessage, MCPSamplingRequest, MCPSamplingResult, MCPToToolsOptions, MCPToolDefinition } from "./client/types.js";
+import { _resetSseWarnDedupForTesting, createMCPClient } from "./client/client.js";
+import { McpResourceReaderOptions, createMcpResourceReader } from "./client/mcp-resource-reader.js";
+import { adaptCallResult } from "./client/adapt-result.js";
+import { DEFAULT_DEFER_LOADING_THRESHOLD } from "./client/defer-loading.js";
+import { _resetMcpAdapterDedupForTesting, adaptMCPTools } from "./client/to-tools.js";
+import "./client/index.js";
+import { GraphorinMCPError, MCPAuthError, MCPCallTimeoutError, MCPCancelledError, MCPConnectionError, MCPErrorKind, MCPErrorMetadata, MCPInvalidConfigError, MCPProtocolError, MCPToolExecutionError, MCPToolNotFoundError, MCPToolPinningError, MCPTransportNotSupportedError } from "./errors/index.js";
+import { deriveServerIdentity, formatMCPServerName } from "./helpers/identity.js";
+import { validateMCPServerConfig } from "./helpers/validate-config.js";
+import { mcpAuthListSessions, mcpAuthLogin, mcpAuthRefresh, mcpAuthRevoke, mcpAuthStatus } from "./oauth/library.js";
+import "./oauth/index.js";
+
+//#region src/index.d.ts
+
+/**
+ * `@graphorin/mcp` — Model Context Protocol client for the Graphorin
+ * framework.
+ *
+ * The package owns:
+ *
+ * - The {@link createMCPClient} factory that opens a typed MCP
+ *   connection over stdio, Streamable HTTP, or the deprecated SSE
+ *   transport.
+ * - The {@link MCPClient} surface (`listTools` / `listResources` /
+ *   `listPrompts` / `callTool` / `readResource` / `getPrompt` /
+ *   `close`) plus the strategy-aware {@link MCPClient.toTools}
+ *   adapter that bridges MCP tool descriptors into Graphorin
+ *   {@link Tool} records.
+ * - The OAuth bridge that resolves bearer headers from the
+ *   {@link OAuthAuthorizationProvider} backed by
+ *   `@graphorin/security/oauth`.
+ * - Library helpers (`mcpAuthLogin`, `mcpAuthListSessions`,
+ *   `mcpAuthRefresh`, `mcpAuthRevoke`, `mcpAuthStatus`) consumed by
+ *   the upcoming `graphorin auth` CLI surface.
+ * - Typed errors ({@link MCPConnectionError},
+ *   {@link MCPProtocolError}, {@link MCPAuthError},
+ *   {@link MCPToolNotFoundError}, {@link MCPCallTimeoutError},
+ *   {@link MCPCancelledError}, {@link MCPInvalidConfigError},
+ *   {@link MCPTransportNotSupportedError}, {@link GraphorinMCPError}).
+ *
+ * Stable sub-paths:
+ *
+ * ```ts
+ * import { createMCPClient } from '@graphorin/mcp/client';
+ * import { createOAuthAuthorizationProvider } from '@graphorin/mcp/oauth';
+ * import { formatMCPServerName, validateMCPServerConfig } from '@graphorin/mcp/helpers';
+ * import { MCPConnectionError } from '@graphorin/mcp/errors';
+ * import type { MCPTransportConfig, ServerIdentity } from '@graphorin/mcp/transport';
+ * ```
+ *
+ * @packageDocumentation
+ */
+/** Canonical version constant. Mirrors the `package.json` version. */
+declare const VERSION = "0.5.0";
+//#endregion
+export { CreateMCPClientOptions, DEFAULT_DEFER_LOADING_THRESHOLD, GraphorinMCPError, MCPAuthError, MCPCallTimeoutError, MCPCallToolResult, MCPCancelledError, MCPClient, MCPConnectionError, MCPContentPart, MCPElicitationHandler, MCPElicitationRequest, MCPElicitationResult, MCPErrorKind, MCPErrorMetadata, MCPInvalidConfigError, MCPPromptDefinition, MCPPromptMessage, MCPProtocolError, MCPResourceContent, MCPResourceDefinition, MCPSamplingContent, MCPSamplingHandler, MCPSamplingMessage, MCPSamplingRequest, MCPSamplingResult, MCPToToolsOptions, MCPToolDefinition, MCPToolExecutionError, MCPToolNotFoundError, MCPToolPinningError, MCPTransportConfig, MCPTransportNotSupportedError, McpResourceReaderOptions, OAuthAuthorizationProvider, OAuthAuthorizationProviderOptions, ServerIdentity, SseTransportConfig, StdioTransportConfig, StreamableHttpTransportConfig, VERSION, _resetMcpAdapterDedupForTesting, _resetSseWarnDedupForTesting, adaptCallResult, adaptMCPTools, createMCPClient, createMcpResourceReader, createOAuthAuthorizationProvider, deriveServerIdentity, formatMCPServerName, mcpAuthListSessions, mcpAuthLogin, mcpAuthRefresh, mcpAuthRevoke, mcpAuthStatus, validateMCPServerConfig };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA;;;;;;;;;;;;;;;;;;;;;;;cAAa,OAAA"}

package/dist/index.js

@@ -0,0 +1,58 @@
+import { GraphorinMCPError, MCPAuthError, MCPCallTimeoutError, MCPCancelledError, MCPConnectionError, MCPInvalidConfigError, MCPProtocolError, MCPToolExecutionError, MCPToolNotFoundError, MCPToolPinningError, MCPTransportNotSupportedError } from "./errors/index.js";
+import { deriveServerIdentity, formatMCPServerName } from "./helpers/identity.js";
+import { validateMCPServerConfig } from "./helpers/validate-config.js";
+import { adaptCallResult } from "./client/adapt-result.js";
+import { DEFAULT_DEFER_LOADING_THRESHOLD } from "./client/defer-loading.js";
+import { _resetMcpAdapterDedupForTesting, adaptMCPTools } from "./client/to-tools.js";
+import { _resetSseWarnDedupForTesting, createMCPClient } from "./client/client.js";
+import { createMcpResourceReader } from "./client/mcp-resource-reader.js";
+import "./client/index.js";
+import { createOAuthAuthorizationProvider } from "./oauth/bridge.js";
+import { mcpAuthListSessions, mcpAuthLogin, mcpAuthRefresh, mcpAuthRevoke, mcpAuthStatus } from "./oauth/library.js";
+import "./oauth/index.js";
+
+//#region src/index.ts
+/**
+* `@graphorin/mcp` — Model Context Protocol client for the Graphorin
+* framework.
+*
+* The package owns:
+*
+* - The {@link createMCPClient} factory that opens a typed MCP
+*   connection over stdio, Streamable HTTP, or the deprecated SSE
+*   transport.
+* - The {@link MCPClient} surface (`listTools` / `listResources` /
+*   `listPrompts` / `callTool` / `readResource` / `getPrompt` /
+*   `close`) plus the strategy-aware {@link MCPClient.toTools}
+*   adapter that bridges MCP tool descriptors into Graphorin
+*   {@link Tool} records.
+* - The OAuth bridge that resolves bearer headers from the
+*   {@link OAuthAuthorizationProvider} backed by
+*   `@graphorin/security/oauth`.
+* - Library helpers (`mcpAuthLogin`, `mcpAuthListSessions`,
+*   `mcpAuthRefresh`, `mcpAuthRevoke`, `mcpAuthStatus`) consumed by
+*   the upcoming `graphorin auth` CLI surface.
+* - Typed errors ({@link MCPConnectionError},
+*   {@link MCPProtocolError}, {@link MCPAuthError},
+*   {@link MCPToolNotFoundError}, {@link MCPCallTimeoutError},
+*   {@link MCPCancelledError}, {@link MCPInvalidConfigError},
+*   {@link MCPTransportNotSupportedError}, {@link GraphorinMCPError}).
+*
+* Stable sub-paths:
+*
+* ```ts
+* import { createMCPClient } from '@graphorin/mcp/client';
+* import { createOAuthAuthorizationProvider } from '@graphorin/mcp/oauth';
+* import { formatMCPServerName, validateMCPServerConfig } from '@graphorin/mcp/helpers';
+* import { MCPConnectionError } from '@graphorin/mcp/errors';
+* import type { MCPTransportConfig, ServerIdentity } from '@graphorin/mcp/transport';
+* ```
+*
+* @packageDocumentation
+*/
+/** Canonical version constant. Mirrors the `package.json` version. */
+const VERSION = "0.5.0";
+
+//#endregion
+export { DEFAULT_DEFER_LOADING_THRESHOLD, GraphorinMCPError, MCPAuthError, MCPCallTimeoutError, MCPCancelledError, MCPConnectionError, MCPInvalidConfigError, MCPProtocolError, MCPToolExecutionError, MCPToolNotFoundError, MCPToolPinningError, MCPTransportNotSupportedError, VERSION, _resetMcpAdapterDedupForTesting, _resetSseWarnDedupForTesting, adaptCallResult, adaptMCPTools, createMCPClient, createMcpResourceReader, createOAuthAuthorizationProvider, deriveServerIdentity, formatMCPServerName, mcpAuthListSessions, mcpAuthLogin, mcpAuthRefresh, mcpAuthRevoke, mcpAuthStatus, validateMCPServerConfig };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@graphorin/mcp` — Model Context Protocol client for the Graphorin\n * framework.\n *\n * The package owns:\n *\n * - The {@link createMCPClient} factory that opens a typed MCP\n *   connection over stdio, Streamable HTTP, or the deprecated SSE\n *   transport.\n * - The {@link MCPClient} surface (`listTools` / `listResources` /\n *   `listPrompts` / `callTool` / `readResource` / `getPrompt` /\n *   `close`) plus the strategy-aware {@link MCPClient.toTools}\n *   adapter that bridges MCP tool descriptors into Graphorin\n *   {@link Tool} records.\n * - The OAuth bridge that resolves bearer headers from the\n *   {@link OAuthAuthorizationProvider} backed by\n *   `@graphorin/security/oauth`.\n * - Library helpers (`mcpAuthLogin`, `mcpAuthListSessions`,\n *   `mcpAuthRefresh`, `mcpAuthRevoke`, `mcpAuthStatus`) consumed by\n *   the upcoming `graphorin auth` CLI surface.\n * - Typed errors ({@link MCPConnectionError},\n *   {@link MCPProtocolError}, {@link MCPAuthError},\n *   {@link MCPToolNotFoundError}, {@link MCPCallTimeoutError},\n *   {@link MCPCancelledError}, {@link MCPInvalidConfigError},\n *   {@link MCPTransportNotSupportedError}, {@link GraphorinMCPError}).\n *\n * Stable sub-paths:\n *\n * ```ts\n * import { createMCPClient } from '@graphorin/mcp/client';\n * import { createOAuthAuthorizationProvider } from '@graphorin/mcp/oauth';\n * import { formatMCPServerName, validateMCPServerConfig } from '@graphorin/mcp/helpers';\n * import { MCPConnectionError } from '@graphorin/mcp/errors';\n * import type { MCPTransportConfig, ServerIdentity } from '@graphorin/mcp/transport';\n * ```\n *\n * @packageDocumentation\n */\n\n/** Canonical version constant. Mirrors the `package.json` version. */\nexport const VERSION = '0.5.0';\n\nexport * from './client/index.js';\nexport * from './errors/index.js';\nexport * from './helpers/index.js';\nexport * from './oauth/index.js';\nexport * from './transport/index.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,MAAa,UAAU"}

package/dist/oauth/bridge.d.ts

@@ -0,0 +1,59 @@
+import { OAuthSession } from "@graphorin/security/oauth";
+import * as _graphorin_core_contracts0 from "@graphorin/core/contracts";
+import { OAuthServerStore } from "@graphorin/core/contracts";
+
+//#region src/oauth/bridge.d.ts
+
+/** Options accepted by {@link createOAuthAuthorizationProvider}. */
+interface OAuthAuthorizationProviderOptions {
+  /**
+   * Secrets store the persisted tokens resolve from (SPL-1) — with it,
+   * the bridge issues Authorization headers across process restarts.
+   */
+  readonly secretsStore?: _graphorin_core_contracts0.SecretsStore;
+  /** Stable identifier of the persisted OAuth server (`serverId`). */
+  readonly serverId: string;
+  /** Persistent storage. */
+  readonly storage: OAuthServerStore;
+  /**
+   * Time-to-refresh window in milliseconds. When the session is
+   * within `refreshAheadMs` of expiry the provider triggers a
+   * refresh on the next request. Defaults to 5 minutes.
+   */
+  readonly refreshAheadMs?: number;
+  /** Optional per-request `AbortSignal` (forwarded to refresh). */
+  readonly signal?: AbortSignal;
+}
+/**
+ * Live authorization-header provider returned by
+ * {@link createOAuthAuthorizationProvider}.
+ *
+ * @stable
+ */
+interface OAuthAuthorizationProvider {
+  /** Resolve an `Authorization: Bearer ...` header. */
+  resolveHeader(): Promise<string>;
+  /** Force a refresh, regardless of expiry. */
+  refresh(): Promise<OAuthSession>;
+  /** Persist the most recently observed expiry timestamp. */
+  readonly serverId: string;
+}
+/**
+ * Build a provider that resolves the `Authorization` header value the
+ * Streamable HTTP / SSE MCP transports send on every request.
+ *
+ * The provider:
+ *
+ * 1. Loads the persisted session metadata from the supplied store.
+ * 2. Refreshes the session when it is within `refreshAheadMs` of
+ *    expiry.
+ * 3. Wraps every refresh failure in {@link MCPAuthError} carrying a
+ *    `hint` that points the operator to the upcoming
+ *    `graphorin auth refresh` CLI.
+ *
+ * @stable
+ */
+declare function createOAuthAuthorizationProvider(options: OAuthAuthorizationProviderOptions): OAuthAuthorizationProvider;
+//#endregion
+export { OAuthAuthorizationProvider, OAuthAuthorizationProviderOptions, createOAuthAuthorizationProvider };
+//# sourceMappingURL=bridge.d.ts.map

package/dist/oauth/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","names":[],"sources":["../../src/oauth/bridge.ts"],"sourcesContent":[],"mappings":";;;;;;;AA0EgB,UAlDC,iCAAA,CAmDN;;;;;0BAnDuC,0BAAA,CAKY;;;;oBAI1C;;;;;;;;oBAQA;;;;;;;;UASH,0BAAA;;mBAEE;;aAEN,QAAQ;;;;;;;;;;;;;;;;;;;iBAoBL,gCAAA,UACL,oCACR"}

package/dist/oauth/bridge.js

@@ -0,0 +1,75 @@
+import { MCPAuthError } from "../errors/index.js";
+import { GraphorinOAuthError, emitOAuthLifecycle, refreshOAuthSession } from "@graphorin/security/oauth";
+
+//#region src/oauth/bridge.ts
+/**
+* Build a provider that resolves the `Authorization` header value the
+* Streamable HTTP / SSE MCP transports send on every request.
+*
+* The provider:
+*
+* 1. Loads the persisted session metadata from the supplied store.
+* 2. Refreshes the session when it is within `refreshAheadMs` of
+*    expiry.
+* 3. Wraps every refresh failure in {@link MCPAuthError} carrying a
+*    `hint` that points the operator to the upcoming
+*    `graphorin auth refresh` CLI.
+*
+* @stable
+*/
+function createOAuthAuthorizationProvider(options) {
+	const refreshAheadMs = options.refreshAheadMs ?? 5 * 6e4;
+	let activeSession;
+	async function loadOrRefresh(force) {
+		const record = await options.storage.get(options.serverId);
+		if (record === null) throw new MCPAuthError(`OAuth server '${options.serverId}' is not registered.`, {
+			hint: `run 'graphorin auth login --mcp ${options.serverId} --url <server-url>' to register the OAuth server.`,
+			metadata: { server: options.serverId }
+		});
+		const expiresAt = record.expiresAt;
+		if (!(force || activeSession === void 0 || expiresAt !== void 0 && expiresAt - Date.now() < refreshAheadMs) && activeSession !== void 0) return activeSession;
+		try {
+			const session = await refreshOAuthSession(options.storage, options.serverId, {
+				...options.signal === void 0 ? {} : { signal: options.signal },
+				...options.secretsStore === void 0 ? {} : { secretsStore: options.secretsStore }
+			});
+			activeSession = session;
+			return session;
+		} catch (cause) {
+			if (cause instanceof GraphorinOAuthError) {
+				emitOAuthLifecycle({
+					type: "mcp.auth.expired",
+					serverId: options.serverId,
+					ts: Date.now(),
+					reason: cause.kind,
+					metadata: { serverUrl: record.serverUrl }
+				});
+				throw new MCPAuthError(`MCP OAuth session for '${options.serverId}' could not be refreshed: ${cause.message}`, {
+					hint: `run 'graphorin auth refresh --mcp ${options.serverId}' to recover.`,
+					metadata: { server: options.serverId },
+					cause
+				});
+			}
+			throw new MCPAuthError(`MCP OAuth session for '${options.serverId}' could not be refreshed.`, {
+				hint: `run 'graphorin auth refresh --mcp ${options.serverId}' to recover.`,
+				metadata: { server: options.serverId },
+				cause
+			});
+		}
+	}
+	return Object.freeze({
+		serverId: options.serverId,
+		async resolveHeader() {
+			const session = await loadOrRefresh(false);
+			const tokenType = session.tokenType.length === 0 ? "Bearer" : session.tokenType;
+			return session.accessToken.use((raw) => `${tokenType} ${raw}`);
+		},
+		async refresh() {
+			return loadOrRefresh(true);
+		}
+	});
+}
+
+//#endregion
+export { createOAuthAuthorizationProvider };
+//# sourceMappingURL=bridge.js.map

package/dist/oauth/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","names":["activeSession: OAuthSession | undefined"],"sources":["../../src/oauth/bridge.ts"],"sourcesContent":["/**\n * Bridge between the MCP transport's bearer-token requirement and the\n * outbound OAuth subsystem in `@graphorin/security/oauth`.\n *\n * The bridge resolves an authorization header from a stored\n * {@link OAuthSession}, refreshes the token automatically when it is\n * within the configured pre-expiry window, and surfaces every\n * lifecycle transition (`oauth.granted` / `oauth.refreshed` /\n * `oauth.revoked` / `mcp.auth.expired`) to subscribers.\n *\n * @packageDocumentation\n */\n\nimport type { OAuthServerStore } from '@graphorin/core/contracts';\nimport type { OAuthSession } from '@graphorin/security/oauth';\nimport {\n  emitOAuthLifecycle,\n  GraphorinOAuthError,\n  refreshOAuthSession,\n} from '@graphorin/security/oauth';\n\nimport { MCPAuthError } from '../errors/index.js';\n\n/** Options accepted by {@link createOAuthAuthorizationProvider}. */\nexport interface OAuthAuthorizationProviderOptions {\n  /**\n   * Secrets store the persisted tokens resolve from (SPL-1) — with it,\n   * the bridge issues Authorization headers across process restarts.\n   */\n  readonly secretsStore?: import('@graphorin/core/contracts').SecretsStore;\n  /** Stable identifier of the persisted OAuth server (`serverId`). */\n  readonly serverId: string;\n  /** Persistent storage. */\n  readonly storage: OAuthServerStore;\n  /**\n   * Time-to-refresh window in milliseconds. When the session is\n   * within `refreshAheadMs` of expiry the provider triggers a\n   * refresh on the next request. Defaults to 5 minutes.\n   */\n  readonly refreshAheadMs?: number;\n  /** Optional per-request `AbortSignal` (forwarded to refresh). */\n  readonly signal?: AbortSignal;\n}\n\n/**\n * Live authorization-header provider returned by\n * {@link createOAuthAuthorizationProvider}.\n *\n * @stable\n */\nexport interface OAuthAuthorizationProvider {\n  /** Resolve an `Authorization: Bearer ...` header. */\n  resolveHeader(): Promise<string>;\n  /** Force a refresh, regardless of expiry. */\n  refresh(): Promise<OAuthSession>;\n  /** Persist the most recently observed expiry timestamp. */\n  readonly serverId: string;\n}\n\n/**\n * Build a provider that resolves the `Authorization` header value the\n * Streamable HTTP / SSE MCP transports send on every request.\n *\n * The provider:\n *\n * 1. Loads the persisted session metadata from the supplied store.\n * 2. Refreshes the session when it is within `refreshAheadMs` of\n *    expiry.\n * 3. Wraps every refresh failure in {@link MCPAuthError} carrying a\n *    `hint` that points the operator to the upcoming\n *    `graphorin auth refresh` CLI.\n *\n * @stable\n */\nexport function createOAuthAuthorizationProvider(\n  options: OAuthAuthorizationProviderOptions,\n): OAuthAuthorizationProvider {\n  const refreshAheadMs = options.refreshAheadMs ?? 5 * 60_000;\n  let activeSession: OAuthSession | undefined;\n\n  async function loadOrRefresh(force: boolean): Promise<OAuthSession> {\n    const record = await options.storage.get(options.serverId);\n    if (record === null) {\n      throw new MCPAuthError(`OAuth server '${options.serverId}' is not registered.`, {\n        hint: `run 'graphorin auth login --mcp ${options.serverId} --url <server-url>' to register the OAuth server.`,\n        metadata: { server: options.serverId },\n      });\n    }\n    const expiresAt = record.expiresAt;\n    const now = Date.now();\n    const stale =\n      force ||\n      activeSession === undefined ||\n      (expiresAt !== undefined && expiresAt - now < refreshAheadMs);\n    if (!stale && activeSession !== undefined) return activeSession;\n    try {\n      const session = await refreshOAuthSession(options.storage, options.serverId, {\n        ...(options.signal === undefined ? {} : { signal: options.signal }),\n        ...(options.secretsStore === undefined ? {} : { secretsStore: options.secretsStore }),\n      });\n      activeSession = session;\n      return session;\n    } catch (cause) {\n      if (cause instanceof GraphorinOAuthError) {\n        emitOAuthLifecycle({\n          type: 'mcp.auth.expired',\n          serverId: options.serverId,\n          ts: Date.now(),\n          reason: cause.kind,\n          metadata: { serverUrl: record.serverUrl },\n        });\n        throw new MCPAuthError(\n          `MCP OAuth session for '${options.serverId}' could not be refreshed: ${cause.message}`,\n          {\n            hint: `run 'graphorin auth refresh --mcp ${options.serverId}' to recover.`,\n            metadata: { server: options.serverId },\n            cause,\n          },\n        );\n      }\n      throw new MCPAuthError(\n        `MCP OAuth session for '${options.serverId}' could not be refreshed.`,\n        {\n          hint: `run 'graphorin auth refresh --mcp ${options.serverId}' to recover.`,\n          metadata: { server: options.serverId },\n          cause,\n        },\n      );\n    }\n  }\n\n  return Object.freeze({\n    serverId: options.serverId,\n    async resolveHeader(): Promise<string> {\n      const session = await loadOrRefresh(false);\n      const tokenType = session.tokenType.length === 0 ? 'Bearer' : session.tokenType;\n      return session.accessToken.use((raw) => `${tokenType} ${raw}`);\n    },\n    async refresh(): Promise<OAuthSession> {\n      return loadOrRefresh(true);\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA0EA,SAAgB,iCACd,SAC4B;CAC5B,MAAM,iBAAiB,QAAQ,kBAAkB,IAAI;CACrD,IAAIA;CAEJ,eAAe,cAAc,OAAuC;EAClE,MAAM,SAAS,MAAM,QAAQ,QAAQ,IAAI,QAAQ,SAAS;AAC1D,MAAI,WAAW,KACb,OAAM,IAAI,aAAa,iBAAiB,QAAQ,SAAS,uBAAuB;GAC9E,MAAM,mCAAmC,QAAQ,SAAS;GAC1D,UAAU,EAAE,QAAQ,QAAQ,UAAU;GACvC,CAAC;EAEJ,MAAM,YAAY,OAAO;AAMzB,MAAI,EAHF,SACA,kBAAkB,UACjB,cAAc,UAAa,YAJlB,KAAK,KAAK,GAI0B,mBAClC,kBAAkB,OAAW,QAAO;AAClD,MAAI;GACF,MAAM,UAAU,MAAM,oBAAoB,QAAQ,SAAS,QAAQ,UAAU;IAC3E,GAAI,QAAQ,WAAW,SAAY,EAAE,GAAG,EAAE,QAAQ,QAAQ,QAAQ;IAClE,GAAI,QAAQ,iBAAiB,SAAY,EAAE,GAAG,EAAE,cAAc,QAAQ,cAAc;IACrF,CAAC;AACF,mBAAgB;AAChB,UAAO;WACA,OAAO;AACd,OAAI,iBAAiB,qBAAqB;AACxC,uBAAmB;KACjB,MAAM;KACN,UAAU,QAAQ;KAClB,IAAI,KAAK,KAAK;KACd,QAAQ,MAAM;KACd,UAAU,EAAE,WAAW,OAAO,WAAW;KAC1C,CAAC;AACF,UAAM,IAAI,aACR,0BAA0B,QAAQ,SAAS,4BAA4B,MAAM,WAC7E;KACE,MAAM,qCAAqC,QAAQ,SAAS;KAC5D,UAAU,EAAE,QAAQ,QAAQ,UAAU;KACtC;KACD,CACF;;AAEH,SAAM,IAAI,aACR,0BAA0B,QAAQ,SAAS,4BAC3C;IACE,MAAM,qCAAqC,QAAQ,SAAS;IAC5D,UAAU,EAAE,QAAQ,QAAQ,UAAU;IACtC;IACD,CACF;;;AAIL,QAAO,OAAO,OAAO;EACnB,UAAU,QAAQ;EAClB,MAAM,gBAAiC;GACrC,MAAM,UAAU,MAAM,cAAc,MAAM;GAC1C,MAAM,YAAY,QAAQ,UAAU,WAAW,IAAI,WAAW,QAAQ;AACtE,UAAO,QAAQ,YAAY,KAAK,QAAQ,GAAG,UAAU,GAAG,MAAM;;EAEhE,MAAM,UAAiC;AACrC,UAAO,cAAc,KAAK;;EAE7B,CAAC"}

package/dist/oauth/index.d.ts

@@ -0,0 +1,3 @@
+import { OAuthAuthorizationProvider, OAuthAuthorizationProviderOptions, createOAuthAuthorizationProvider } from "./bridge.js";
+import { mcpAuthListSessions, mcpAuthLogin, mcpAuthRefresh, mcpAuthRevoke, mcpAuthStatus } from "./library.js";
+export { type OAuthAuthorizationProvider, type OAuthAuthorizationProviderOptions, createOAuthAuthorizationProvider, mcpAuthListSessions, mcpAuthLogin, mcpAuthRefresh, mcpAuthRevoke, mcpAuthStatus };

package/dist/oauth/index.js

@@ -0,0 +1,4 @@
+import { createOAuthAuthorizationProvider } from "./bridge.js";
+import { mcpAuthListSessions, mcpAuthLogin, mcpAuthRefresh, mcpAuthRevoke, mcpAuthStatus } from "./library.js";
+
+export { createOAuthAuthorizationProvider, mcpAuthListSessions, mcpAuthLogin, mcpAuthRefresh, mcpAuthRevoke, mcpAuthStatus };

package/dist/oauth/library.d.ts

@@ -0,0 +1,23 @@
+import { LoginInteractiveOptions, LoginInteractiveResult, OAuthSession, OAuthSessionMetadata, OAuthStatusSnapshot } from "@graphorin/security/oauth";
+import { OAuthServerStore } from "@graphorin/core/contracts";
+
+//#region src/oauth/library.d.ts
+
+/** Drive `graphorin auth login --mcp <id>`. */
+declare function mcpAuthLogin(options: LoginInteractiveOptions): Promise<LoginInteractiveResult>;
+/** Drive `graphorin auth list --mcp`. */
+declare function mcpAuthListSessions(storage: OAuthServerStore): Promise<ReadonlyArray<OAuthSessionMetadata>>;
+/** Drive `graphorin auth refresh --mcp <id>`. */
+declare function mcpAuthRefresh(storage: OAuthServerStore, serverId: string, options?: {
+  readonly signal?: AbortSignal;
+}): Promise<OAuthSession>;
+/** Drive `graphorin auth revoke --mcp <id>`. */
+declare function mcpAuthRevoke(storage: OAuthServerStore, serverId: string, options?: {
+  readonly reason?: string;
+  readonly signal?: AbortSignal;
+}): Promise<void>;
+/** Drive `graphorin auth status --mcp`. */
+declare function mcpAuthStatus(storage: OAuthServerStore): Promise<OAuthStatusSnapshot>;
+//#endregion
+export { mcpAuthListSessions, mcpAuthLogin, mcpAuthRefresh, mcpAuthRevoke, mcpAuthStatus };
+//# sourceMappingURL=library.d.ts.map

package/dist/oauth/library.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"library.d.ts","names":[],"sources":["../../src/oauth/library.ts"],"sourcesContent":[],"mappings":";;;;;;AAmCG,iBATmB,YAAA,CASnB,OAAA,EARQ,uBAQR,CAAA,EAPA,OAOA,CAPQ,sBAOR,CAAA;;AAKmB,iBAPA,mBAAA,CAOc,OAAA,EANzB,gBAMyB,CAAA,EALjC,OAKiC,CALzB,aAKyB,CALX,oBAKW,CAAA,CAAA;;AAGL,iBAHT,cAAA,CAGS,OAAA,EAFpB,gBAEoB,EAAA,QAAA,EAAA,MAAA,EAAA,OAC5B,CAD4B,EAAA;EACpB,SAAA,MAAA,CAAA,EADoB,WACpB;CAAR,CAAA,EAAA,OAAA,CAAQ,YAAR,CAAA;;AAKmB,iBAAA,aAAA,CAAa,OAAA,EACxB,gBADwB,EAAA,QAAA,EAAA,MAAA,EAAA,OAIhC,CAJgC,EAAA;EACxB,SAAA,MAAA,CAAA,EAAA,MAAA;EAE8C,SAAA,MAAA,CAAA,EAAA,WAAA;CACtD,CAAA,EAAA,OAAA,CAAA,IAAA,CAAA;;AAKmB,iBAAA,aAAA,CAAa,OAAA,EAAU,gBAAV,CAAA,EAA6B,OAA7B,CAAqC,mBAArC,CAAA"}

package/dist/oauth/library.js

@@ -0,0 +1,27 @@
+import { getOAuthStatus, listOAuthSessions, loginInteractive, refreshOAuthSession, revokeOAuthSession } from "@graphorin/security/oauth";
+
+//#region src/oauth/library.ts
+/** Drive `graphorin auth login --mcp <id>`. */
+async function mcpAuthLogin(options) {
+	return loginInteractive(options);
+}
+/** Drive `graphorin auth list --mcp`. */
+async function mcpAuthListSessions(storage) {
+	return listOAuthSessions(storage);
+}
+/** Drive `graphorin auth refresh --mcp <id>`. */
+async function mcpAuthRefresh(storage, serverId, options = {}) {
+	return refreshOAuthSession(storage, serverId, options);
+}
+/** Drive `graphorin auth revoke --mcp <id>`. */
+async function mcpAuthRevoke(storage, serverId, options = {}) {
+	await revokeOAuthSession(storage, serverId, options);
+}
+/** Drive `graphorin auth status --mcp`. */
+async function mcpAuthStatus(storage) {
+	return getOAuthStatus(storage);
+}
+
+//#endregion
+export { mcpAuthListSessions, mcpAuthLogin, mcpAuthRefresh, mcpAuthRevoke, mcpAuthStatus };
+//# sourceMappingURL=library.js.map

package/dist/oauth/library.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"library.js","names":[],"sources":["../../src/oauth/library.ts"],"sourcesContent":["/**\n * Thin re-export wrappers for the OAuth library functions consumed by\n * the upcoming `graphorin auth login | list | refresh | revoke |\n * status` CLI surface (Phase 15). The wrappers attach an\n * `mcpServerId` audit tag so downstream observers can attribute\n * events to the MCP subsystem rather than to a generic OAuth call\n * site.\n *\n * @packageDocumentation\n */\n\nimport type { OAuthServerStore } from '@graphorin/core/contracts';\nimport {\n  getOAuthStatus,\n  type LoginInteractiveOptions,\n  type LoginInteractiveResult,\n  listOAuthSessions,\n  loginInteractive,\n  type OAuthSession,\n  type OAuthSessionMetadata,\n  type OAuthStatusSnapshot,\n  refreshOAuthSession,\n  revokeOAuthSession,\n} from '@graphorin/security/oauth';\n\n/** Drive `graphorin auth login --mcp <id>`. */\nexport async function mcpAuthLogin(\n  options: LoginInteractiveOptions,\n): Promise<LoginInteractiveResult> {\n  return loginInteractive(options);\n}\n\n/** Drive `graphorin auth list --mcp`. */\nexport async function mcpAuthListSessions(\n  storage: OAuthServerStore,\n): Promise<ReadonlyArray<OAuthSessionMetadata>> {\n  return listOAuthSessions(storage);\n}\n\n/** Drive `graphorin auth refresh --mcp <id>`. */\nexport async function mcpAuthRefresh(\n  storage: OAuthServerStore,\n  serverId: string,\n  options: { readonly signal?: AbortSignal } = {},\n): Promise<OAuthSession> {\n  return refreshOAuthSession(storage, serverId, options);\n}\n\n/** Drive `graphorin auth revoke --mcp <id>`. */\nexport async function mcpAuthRevoke(\n  storage: OAuthServerStore,\n  serverId: string,\n  options: { readonly reason?: string; readonly signal?: AbortSignal } = {},\n): Promise<void> {\n  await revokeOAuthSession(storage, serverId, options);\n}\n\n/** Drive `graphorin auth status --mcp`. */\nexport async function mcpAuthStatus(storage: OAuthServerStore): Promise<OAuthStatusSnapshot> {\n  return getOAuthStatus(storage);\n}\n"],"mappings":";;;;AA0BA,eAAsB,aACpB,SACiC;AACjC,QAAO,iBAAiB,QAAQ;;;AAIlC,eAAsB,oBACpB,SAC8C;AAC9C,QAAO,kBAAkB,QAAQ;;;AAInC,eAAsB,eACpB,SACA,UACA,UAA6C,EAAE,EACxB;AACvB,QAAO,oBAAoB,SAAS,UAAU,QAAQ;;;AAIxD,eAAsB,cACpB,SACA,UACA,UAAuE,EAAE,EAC1D;AACf,OAAM,mBAAmB,SAAS,UAAU,QAAQ;;;AAItD,eAAsB,cAAc,SAAyD;AAC3F,QAAO,eAAe,QAAQ"}