@adcp/sdk 5.23.0

package/dist/lib/errors/index.js

@@ -0,0 +1,446 @@
+"use strict";
+// Custom error classes for ADCP client library
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VersionUnsupportedError = exports.FeatureUnsupportedError = exports.IdempotencyExpiredError = exports.IdempotencyConflictError = exports.AuthenticationRequiredError = exports.ConfigurationError = exports.InvalidContextError = exports.MissingInputHandlerError = exports.ValidationError = exports.ProtocolError = exports.UnsupportedTaskError = exports.AgentNotFoundError = exports.TaskAbortedError = exports.DeferredTaskError = exports.MaxClarificationError = exports.TaskTimeoutError = exports.ADCPError = void 0;
+exports.is401Error = is401Error;
+exports.adcpErrorToTypedError = adcpErrorToTypedError;
+exports.isADCPError = isADCPError;
+exports.isErrorOfType = isErrorOfType;
+exports.extractErrorInfo = extractErrorInfo;
+/**
+ * Base class for all ADCP client errors
+ */
+class ADCPError extends Error {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.details = details;
+        this.name = this.constructor.name;
+    }
+}
+exports.ADCPError = ADCPError;
+/**
+ * Error thrown when a task times out
+ */
+class TaskTimeoutError extends ADCPError {
+    taskId;
+    timeout;
+    code = 'TASK_TIMEOUT';
+    constructor(taskId, timeout) {
+        super(`Task ${taskId} timed out after ${timeout}ms`);
+        this.taskId = taskId;
+        this.timeout = timeout;
+    }
+}
+exports.TaskTimeoutError = TaskTimeoutError;
+/**
+ * Error thrown when maximum clarification attempts are exceeded
+ */
+class MaxClarificationError extends ADCPError {
+    taskId;
+    maxAttempts;
+    code = 'MAX_CLARIFICATIONS';
+    constructor(taskId, maxAttempts) {
+        super(`Task ${taskId} exceeded maximum clarification attempts: ${maxAttempts}`);
+        this.taskId = taskId;
+        this.maxAttempts = maxAttempts;
+    }
+}
+exports.MaxClarificationError = MaxClarificationError;
+/**
+ * Error thrown when a task is deferred to human
+ * Contains the token needed to resume the task
+ */
+class DeferredTaskError extends ADCPError {
+    token;
+    code = 'TASK_DEFERRED';
+    constructor(token) {
+        super(`Task deferred with token: ${token}`);
+        this.token = token;
+    }
+}
+exports.DeferredTaskError = DeferredTaskError;
+/**
+ * Error thrown when a task is aborted
+ */
+class TaskAbortedError extends ADCPError {
+    taskId;
+    reason;
+    code = 'TASK_ABORTED';
+    constructor(taskId, reason) {
+        super(`Task ${taskId} aborted: ${reason || 'No reason provided'}`);
+        this.taskId = taskId;
+        this.reason = reason;
+    }
+}
+exports.TaskAbortedError = TaskAbortedError;
+/**
+ * Error thrown when an agent is not found
+ */
+class AgentNotFoundError extends ADCPError {
+    agentId;
+    availableAgents;
+    code = 'AGENT_NOT_FOUND';
+    constructor(agentId, availableAgents) {
+        super(`Agent '${agentId}' not found. Available agents: ${availableAgents.join(', ')}`);
+        this.agentId = agentId;
+        this.availableAgents = availableAgents;
+    }
+}
+exports.AgentNotFoundError = AgentNotFoundError;
+/**
+ * Error thrown when an agent doesn't support a task
+ */
+class UnsupportedTaskError extends ADCPError {
+    agentId;
+    taskName;
+    supportedTasks;
+    code = 'UNSUPPORTED_TASK';
+    constructor(agentId, taskName, supportedTasks) {
+        const tasksMsg = supportedTasks ? ` Supported tasks: ${supportedTasks.join(', ')}` : '';
+        super(`Agent '${agentId}' does not support task '${taskName}'.${tasksMsg}`);
+        this.agentId = agentId;
+        this.taskName = taskName;
+        this.supportedTasks = supportedTasks;
+    }
+}
+exports.UnsupportedTaskError = UnsupportedTaskError;
+/**
+ * Error thrown when protocol communication fails
+ */
+class ProtocolError extends ADCPError {
+    protocol;
+    originalError;
+    code = 'PROTOCOL_ERROR';
+    constructor(protocol, message, originalError) {
+        super(`${protocol.toUpperCase()} protocol error: ${message}`);
+        this.protocol = protocol;
+        this.originalError = originalError;
+        this.details = { originalError };
+    }
+}
+exports.ProtocolError = ProtocolError;
+/**
+ * Error thrown when validation fails
+ */
+class ValidationError extends ADCPError {
+    field;
+    value;
+    constraint;
+    code = 'VALIDATION_ERROR';
+    constructor(field, value, constraint) {
+        super(`Validation failed for field '${field}': ${constraint}`);
+        this.field = field;
+        this.value = value;
+        this.constraint = constraint;
+        this.details = { field, value, constraint };
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Error thrown when input handler is missing but required
+ */
+class MissingInputHandlerError extends ADCPError {
+    taskId;
+    question;
+    code = 'MISSING_INPUT_HANDLER';
+    constructor(taskId, question) {
+        super(`Agent requested input but no handler provided. Task: ${taskId}, Question: ${question}`);
+        this.taskId = taskId;
+        this.question = question;
+    }
+}
+exports.MissingInputHandlerError = MissingInputHandlerError;
+/**
+ * Error thrown when conversation context is invalid
+ */
+class InvalidContextError extends ADCPError {
+    contextId;
+    code = 'INVALID_CONTEXT';
+    constructor(contextId, reason) {
+        super(`Invalid conversation context '${contextId}': ${reason}`);
+        this.contextId = contextId;
+    }
+}
+exports.InvalidContextError = InvalidContextError;
+/**
+ * Error thrown when configuration is invalid
+ */
+class ConfigurationError extends ADCPError {
+    configField;
+    code = 'CONFIGURATION_ERROR';
+    constructor(message, configField) {
+        super(`Configuration error: ${message}`);
+        this.configField = configField;
+        this.details = { configField };
+    }
+}
+exports.ConfigurationError = ConfigurationError;
+/**
+ * Error thrown when authentication is required to access an MCP endpoint
+ *
+ * This error is thrown during MCP endpoint discovery when the server returns
+ * a 401 Unauthorized response. If the server supports OAuth, the error includes
+ * the OAuth metadata to help clients initiate the authentication flow.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.getProducts({ brief: 'test' });
+ * } catch (error) {
+ *   if (error instanceof AuthenticationRequiredError) {
+ *     if (error.oauthMetadata) {
+ *       // Redirect user to OAuth flow
+ *       const authUrl = error.oauthMetadata.authorization_endpoint;
+ *       console.log(`Please authenticate at: ${authUrl}`);
+ *     } else {
+ *       console.log('Authentication required but OAuth not available');
+ *     }
+ *   }
+ * }
+ * ```
+ */
+class AuthenticationRequiredError extends ADCPError {
+    agentUrl;
+    oauthMetadata;
+    code = 'AUTHENTICATION_REQUIRED';
+    constructor(agentUrl, oauthMetadata, message) {
+        const defaultMessage = oauthMetadata
+            ? `Authentication required for ${agentUrl}. OAuth available at: ${oauthMetadata.authorization_endpoint}`
+            : `Authentication required for ${agentUrl}. No OAuth metadata available - provide auth_token in agent config.`;
+        super(message || defaultMessage);
+        this.agentUrl = agentUrl;
+        this.oauthMetadata = oauthMetadata;
+        this.details = { agentUrl, oauthMetadata };
+    }
+    /**
+     * Check if OAuth authentication is available
+     */
+    get hasOAuth() {
+        return this.oauthMetadata !== undefined;
+    }
+    /**
+     * Get the authorization URL if OAuth is available
+     */
+    get authorizationUrl() {
+        return this.oauthMetadata?.authorization_endpoint;
+    }
+}
+exports.AuthenticationRequiredError = AuthenticationRequiredError;
+/**
+ * Error thrown when a request reused an `idempotency_key` with a different
+ * canonical payload within the seller's replay window.
+ *
+ * Recovery: `correctable` — the caller either reused a key by mistake (mint
+ * a fresh UUID v4 for the new request) or re-planned with a different payload
+ * (an agent whose LLM re-ran and emitted a different request must treat that
+ * as a new intent, not a retry).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.createMediaBuy({...});
+ * } catch (error) {
+ *   if (error instanceof IdempotencyConflictError) {
+ *     // Either the key was reused by mistake, or the agent re-planned with
+ *     // a different payload. Mint a fresh key and try again.
+ *   }
+ * }
+ * ```
+ */
+class IdempotencyConflictError extends ADCPError {
+    code = 'IDEMPOTENCY_CONFLICT';
+    // Exposed via the getter so `console.log(err)` and JSON.stringify don't
+    // leak the key (it's a retry-pattern oracle within the seller's TTL).
+    // Callers reading `err.idempotencyKey` get it normally.
+    idempotencyKey;
+    constructor(idempotencyKey, message) {
+        super(message ||
+            'idempotency_key was used earlier with a different canonical payload. ' +
+                'Use a fresh UUID v4 for the new request, or resend the exact original payload to get the cached response.');
+        Object.defineProperty(this, 'idempotencyKey', {
+            value: idempotencyKey,
+            enumerable: false,
+            writable: false,
+            configurable: false,
+        });
+    }
+}
+exports.IdempotencyConflictError = IdempotencyConflictError;
+/**
+ * Error thrown when a request carries an `idempotency_key` that is past the
+ * seller's declared replay window (plus clock-skew tolerance).
+ *
+ * Recovery: `correctable`. If the caller knows the prior call succeeded
+ * (e.g., they saw the response once, then crashed), they SHOULD fall back
+ * to a natural-key lookup (e.g., `get_media_buys` by
+ * `context.internal_campaign_id`) rather than minting a new key — otherwise
+ * the seller treats the new request as fresh and silently creates a duplicate.
+ *
+ * If the caller doesn't know whether the prior call succeeded, a fresh key
+ * is safe.
+ */
+class IdempotencyExpiredError extends ADCPError {
+    code = 'IDEMPOTENCY_EXPIRED';
+    // Non-enumerable so `console.log(err)` / JSON.stringify don't leak it —
+    // same reasoning as IdempotencyConflictError.idempotencyKey.
+    idempotencyKey;
+    constructor(idempotencyKey, message) {
+        super(message ||
+            "idempotency_key is past the seller's replay window. " +
+                'If you know the prior call succeeded, look up the resource by natural key before retrying. Otherwise, mint a fresh UUID v4.');
+        Object.defineProperty(this, 'idempotencyKey', {
+            value: idempotencyKey,
+            enumerable: false,
+            writable: false,
+            configurable: false,
+        });
+    }
+}
+exports.IdempotencyExpiredError = IdempotencyExpiredError;
+/**
+ * Error thrown when a required feature is not supported by the seller
+ */
+class FeatureUnsupportedError extends ADCPError {
+    unsupportedFeatures;
+    declaredFeatures;
+    agentUrl;
+    code = 'FEATURE_UNSUPPORTED';
+    constructor(unsupportedFeatures, declaredFeatures, agentUrl) {
+        const missing = unsupportedFeatures.join(', ');
+        const declared = declaredFeatures.length > 0 ? declaredFeatures.join(', ') : '(none)';
+        const urlPart = agentUrl ? ` at ${agentUrl}` : '';
+        super(`Seller${urlPart} does not support: ${missing}\n  Declared features: ${declared}`);
+        this.unsupportedFeatures = unsupportedFeatures;
+        this.declaredFeatures = declaredFeatures;
+        this.agentUrl = agentUrl;
+    }
+}
+exports.FeatureUnsupportedError = FeatureUnsupportedError;
+/**
+ * Error thrown when a mutating call would dispatch to a seller whose
+ * capabilities cannot be corroborated as v3. Provides an explicit
+ * pre-flight signal so callers don't silently mutate state on agents
+ * that have not negotiated the expected major version.
+ *
+ * Agent URL is exposed on the instance (`agentUrl`) but omitted from the
+ * default message to avoid leaking seller identity into shared log sinks.
+ */
+class VersionUnsupportedError extends ADCPError {
+    taskType;
+    reason;
+    actualVersion;
+    agentUrl;
+    code = 'VERSION_UNSUPPORTED';
+    constructor(taskType, reason, actualVersion, agentUrl) {
+        super(`Refusing to dispatch mutating task '${taskType}': ` +
+            VersionUnsupportedError.explain(reason, actualVersion) +
+            ` Pass allowV2: true or requireV3ForMutations: false to override.`);
+        this.taskType = taskType;
+        this.reason = reason;
+        this.actualVersion = actualVersion;
+        this.agentUrl = agentUrl;
+    }
+    static explain(reason, actualVersion) {
+        switch (reason) {
+            case 'version':
+                return `seller advertises major version '${actualVersion}' but v3 is required.`;
+            case 'idempotency':
+                return `seller reports v3 but omits adcp.idempotency.replay_ttl_seconds (required by spec).`;
+            case 'synthetic':
+                return `capabilities were synthesized from a tool list — v3 claim is unverifiable.`;
+        }
+    }
+}
+exports.VersionUnsupportedError = VersionUnsupportedError;
+/**
+ * Check if an error indicates a 401 Unauthorized response
+ *
+ * This helper centralizes the fragile logic of detecting 401 errors from
+ * various sources (HTTP status codes, error messages, wrapped errors).
+ * Used during endpoint discovery to detect authentication requirements.
+ *
+ * @param error - The error to check
+ * @param got401Flag - Optional flag that was set by tracking HTTP responses
+ * @returns true if the error appears to be a 401 authentication error
+ */
+function is401Error(error, got401Flag = false) {
+    if (got401Flag) {
+        return true;
+    }
+    if (!error) {
+        return false;
+    }
+    // Check for status property (common in HTTP errors). MCP SDK's
+    // `StreamableHTTPClientTransport` throws errors with the HTTP status on
+    // `.code`, so we check that too.
+    const errorObj = error;
+    const status = errorObj?.status ||
+        errorObj?.response?.status ||
+        errorObj?.cause?.status ||
+        errorObj?.code;
+    if (status === 401) {
+        return true;
+    }
+    // Fall back to string matching in error message. Use word boundaries so
+    // we don't misidentify things like "product prod-401-xyz" as an HTTP 401,
+    // and require "Unauthorized" as a whole word rather than as a substring.
+    const message = errorObj?.message || '';
+    return /\b401\b/.test(message) || /\bunauthorized\b/i.test(message);
+}
+/**
+ * Map a structured AdCP error (code + message) to a typed ADCPError subclass
+ * when the code has a dedicated class. Returns `undefined` for codes that
+ * don't have a typed mapping — callers should continue to use the untyped
+ * `AdcpErrorInfo` for those.
+ *
+ * Pass the `idempotencyKey` the SDK sent so the constructed error carries it
+ * for the caller's recovery logic. The server intentionally omits the key
+ * from error bodies (it's a read-oracle), so the transport-layer caller is
+ * the authoritative source.
+ */
+function adcpErrorToTypedError(adcpError, idempotencyKey) {
+    switch (adcpError.code) {
+        case 'IDEMPOTENCY_CONFLICT':
+            return new IdempotencyConflictError(idempotencyKey, adcpError.message);
+        case 'IDEMPOTENCY_EXPIRED':
+            return new IdempotencyExpiredError(idempotencyKey, adcpError.message);
+        default:
+            return undefined;
+    }
+}
+/**
+ * Type guard to check if an error is an ADCP error
+ */
+function isADCPError(error) {
+    return error instanceof ADCPError;
+}
+/**
+ * Type guard to check if an error is a specific ADCP error type
+ */
+function isErrorOfType(error, ErrorClass) {
+    return error instanceof ErrorClass;
+}
+/**
+ * Utility to extract error information for logging/debugging
+ */
+function extractErrorInfo(error) {
+    if (isADCPError(error)) {
+        return {
+            message: error.message,
+            code: error.code,
+            details: error.details,
+            stack: error.stack,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            message: error.message,
+            stack: error.stack,
+        };
+    }
+    return {
+        message: String(error),
+    };
+}
+//# sourceMappingURL=index.js.map

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

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

package/dist/lib/express-mcp/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Express middleware that normalizes the `Accept` header so requests reach
+ * `StreamableHTTPServerTransport` without tripping its 406 check.
+ *
+ * The MCP SDK's POST handler requires both `application/json` and
+ * `text/event-stream` in `Accept` even when constructed with
+ * `enableJsonResponse: true` (pure request/response mode — no SSE in play).
+ * Buyer agents and validators that send `Accept: application/json` hit a
+ * 406 Not Acceptable.
+ *
+ * This middleware rewrites `Accept: application/json` (JSON alone) to
+ * `application/json, text/event-stream` on the incoming request, so the
+ * transport's strict check passes. Headers that already advertise both,
+ * or don't advertise JSON, are left alone.
+ *
+ * The rewrite touches BOTH `req.headers.accept` AND the matching entries in
+ * `req.rawHeaders`. `StreamableHTTPServerTransport.handleRequest` runs the
+ * incoming `IncomingMessage` through `@hono/node-server`'s
+ * `newHeadersFromIncoming`, which rebuilds the Fetch `Headers` from
+ * `rawHeaders` and ignores `req.headers`. Patching only the parsed map
+ * leaves the transport reading the original unmodified value and the 406
+ * still fires — the pair has to move together.
+ *
+ * **Edge case, intentionally NOT auto-synthesized:** if `req.headers.accept`
+ * exists but `req.rawHeaders` has no Accept entry (some reverse proxies
+ * mutate `req.headers` without rebuilding `rawHeaders`), the middleware
+ * still patches `req.headers.accept` but leaves `rawHeaders` as-is. The
+ * transport then sees no Accept at all on the `rawHeaders` rebuild and
+ * falls through to its missing-Accept path. Adding a phantom `['Accept',
+ * '…']` pair would diverge `req.rawHeaders` from the wire-level headers
+ * and can confuse other middleware (RFC 9421 verifiers, request-signing
+ * canonicalizers) that use `rawHeaders` as authoritative. If you hit
+ * this divergence in practice, fix the upstream proxy — don't monkey-
+ * patch here.
+ *
+ * Mount BEFORE the MCP transport handler:
+ *
+ * ```ts
+ * import express from 'express';
+ * import { mcpAcceptHeaderMiddleware } from '@adcp/sdk/express-mcp';
+ *
+ * const app = express();
+ * app.use('/mcp', mcpAcceptHeaderMiddleware());
+ * // then mount the MCP transport (StreamableHTTPServerTransport.handleRequest)
+ * ```
+ *
+ * This is a local escape hatch pending upstream SDK fix
+ * (https://github.com/modelcontextprotocol/typescript-sdk/issues/1944).
+ * Remove once the SDK loosens the Accept check for `enableJsonResponse: true`.
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+/** Minimal next callback shape — avoids a dependency on `@types/express`. */
+type NextFn = (err?: unknown) => void;
+/** Minimal Express-compatible handler signature. */
+export type McpAcceptHeaderHandler = (req: IncomingMessage, res: ServerResponse, next: NextFn) => void;
+/**
+ * Create the middleware. No options today; exported as a factory for
+ * symmetry with Express convention and future extensibility.
+ */
+export declare function mcpAcceptHeaderMiddleware(): McpAcceptHeaderHandler;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/express-mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/express-mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,MAAM,CAAC;AAE5D,6EAA6E;AAC7E,KAAK,MAAM,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAEtC,oDAAoD;AACpD,MAAM,MAAM,sBAAsB,GAAG,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAmBvG;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,sBAAsB,CAyBlE"}

package/dist/lib/express-mcp/index.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * Express middleware that normalizes the `Accept` header so requests reach
+ * `StreamableHTTPServerTransport` without tripping its 406 check.
+ *
+ * The MCP SDK's POST handler requires both `application/json` and
+ * `text/event-stream` in `Accept` even when constructed with
+ * `enableJsonResponse: true` (pure request/response mode — no SSE in play).
+ * Buyer agents and validators that send `Accept: application/json` hit a
+ * 406 Not Acceptable.
+ *
+ * This middleware rewrites `Accept: application/json` (JSON alone) to
+ * `application/json, text/event-stream` on the incoming request, so the
+ * transport's strict check passes. Headers that already advertise both,
+ * or don't advertise JSON, are left alone.
+ *
+ * The rewrite touches BOTH `req.headers.accept` AND the matching entries in
+ * `req.rawHeaders`. `StreamableHTTPServerTransport.handleRequest` runs the
+ * incoming `IncomingMessage` through `@hono/node-server`'s
+ * `newHeadersFromIncoming`, which rebuilds the Fetch `Headers` from
+ * `rawHeaders` and ignores `req.headers`. Patching only the parsed map
+ * leaves the transport reading the original unmodified value and the 406
+ * still fires — the pair has to move together.
+ *
+ * **Edge case, intentionally NOT auto-synthesized:** if `req.headers.accept`
+ * exists but `req.rawHeaders` has no Accept entry (some reverse proxies
+ * mutate `req.headers` without rebuilding `rawHeaders`), the middleware
+ * still patches `req.headers.accept` but leaves `rawHeaders` as-is. The
+ * transport then sees no Accept at all on the `rawHeaders` rebuild and
+ * falls through to its missing-Accept path. Adding a phantom `['Accept',
+ * '…']` pair would diverge `req.rawHeaders` from the wire-level headers
+ * and can confuse other middleware (RFC 9421 verifiers, request-signing
+ * canonicalizers) that use `rawHeaders` as authoritative. If you hit
+ * this divergence in practice, fix the upstream proxy — don't monkey-
+ * patch here.
+ *
+ * Mount BEFORE the MCP transport handler:
+ *
+ * ```ts
+ * import express from 'express';
+ * import { mcpAcceptHeaderMiddleware } from '@adcp/sdk/express-mcp';
+ *
+ * const app = express();
+ * app.use('/mcp', mcpAcceptHeaderMiddleware());
+ * // then mount the MCP transport (StreamableHTTPServerTransport.handleRequest)
+ * ```
+ *
+ * This is a local escape hatch pending upstream SDK fix
+ * (https://github.com/modelcontextprotocol/typescript-sdk/issues/1944).
+ * Remove once the SDK loosens the Accept check for `enableJsonResponse: true`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpAcceptHeaderMiddleware = mcpAcceptHeaderMiddleware;
+const JSON_TYPE = 'application/json';
+const SSE_TYPE = 'text/event-stream';
+/**
+ * Does the raw `Accept` value advertise `type`? Case-insensitive, tolerant
+ * of parameters (`application/json;q=0.9`) and surrounding whitespace.
+ */
+function acceptsType(accept, type) {
+    const lower = accept.toLowerCase();
+    const target = type.toLowerCase();
+    for (const raw of lower.split(',')) {
+        const mediaType = raw.split(';')[0]?.trim();
+        if (mediaType === target)
+            return true;
+    }
+    return false;
+}
+/**
+ * Create the middleware. No options today; exported as a factory for
+ * symmetry with Express convention and future extensibility.
+ */
+function mcpAcceptHeaderMiddleware() {
+    return function mcpAcceptHeader(req, _res, next) {
+        const accept = req.headers.accept;
+        // No Accept header at all — leave it to the SDK to handle however it does.
+        if (typeof accept !== 'string' || accept.length === 0) {
+            next();
+            return;
+        }
+        const hasJson = acceptsType(accept, JSON_TYPE);
+        const hasSse = acceptsType(accept, SSE_TYPE);
+        // Only rewrite the JSON-only case. If the request already advertises
+        // both, or doesn't advertise JSON at all (e.g. `*/*`, a stray
+        // `text/plain`, or a malformed value), leave the header untouched and
+        // let the transport decide.
+        if (hasJson && !hasSse) {
+            const rewritten = `${JSON_TYPE}, ${SSE_TYPE}`;
+            req.headers.accept = rewritten;
+            rewriteRawAcceptHeader(req, rewritten);
+        }
+        next();
+    };
+}
+/**
+ * Rewrite every `Accept` entry in `req.rawHeaders` to `rewritten`.
+ *
+ * `rawHeaders` is a flat `[name, value, name, value, ...]` array where
+ * header names preserve the wire-level casing. The scan is case-insensitive
+ * so `Accept` / `ACCEPT` / `accept` all match. Duplicates (rare, but
+ * allowed by HTTP) are ALL rewritten so a later copy can't shadow the
+ * patched one. If the header is absent we don't append — adding it here
+ * would diverge from the pre-middleware request shape and could surprise
+ * other middleware that reads `rawHeaders` directly.
+ */
+function rewriteRawAcceptHeader(req, rewritten) {
+    const raw = req.rawHeaders;
+    if (!Array.isArray(raw))
+        return;
+    for (let i = 0; i < raw.length - 1; i += 2) {
+        const name = raw[i];
+        if (typeof name === 'string' && name.toLowerCase() === 'accept') {
+            raw[i + 1] = rewritten;
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/express-mcp/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;;AA+BH,8DAyBC;AA9CD,MAAM,SAAS,GAAG,kBAAkB,CAAC;AACrC,MAAM,QAAQ,GAAG,mBAAmB,CAAC;AAErC;;;GAGG;AACH,SAAS,WAAW,CAAC,MAAc,EAAE,IAAY;IAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QAC5C,IAAI,SAAS,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC;IACxC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,SAAgB,yBAAyB;IACvC,OAAO,SAAS,eAAe,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI;QAC7C,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC;QAElC,2EAA2E;QAC3E,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtD,IAAI,EAAE,CAAC;YACP,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAE7C,qEAAqE;QACrE,8DAA8D;QAC9D,sEAAsE;QACtE,4BAA4B;QAC5B,IAAI,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC;YACvB,MAAM,SAAS,GAAG,GAAG,SAAS,KAAK,QAAQ,EAAE,CAAC;YAC9C,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;YAC/B,sBAAsB,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QACzC,CAAC;QAED,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,sBAAsB,CAAC,GAAoB,EAAE,SAAiB;IACrE,MAAM,GAAG,GAAI,GAAgC,CAAC,UAAU,CAAC;IACzD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO;IAChC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,QAAQ,EAAE,CAAC;YAChE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,SAAS,CAAC;QACzB,CAAC;IACH,CAAC;AACH,CAAC"}