/**
 * MCP protocol generation model ("MCP v2", specification 2026-07-28).
 *
 * Canonical authority (verified against the primary sources, not secondary
 * summaries):
 * - https://modelcontextprotocol.io/specification/2026-07-28/basic
 * - https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http
 * - https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning
 * - https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr
 * - https://modelcontextprotocol.io/specification/2026-07-28/server/discover
 * - https://modelcontextprotocol.io/specification/2026-07-28/server/utilities/caching
 * - schema source of truth: modelcontextprotocol/specification schema/2026-07-28/schema.ts
 *
 * 2026-07-28 ("modern" era) removes the initialize/initialized handshake,
 * protocol sessions (`Mcp-Session-Id`), the standalone GET SSE stream, and
 * `Last-Event-ID` replay from the core request path. Every request carries its
 * protocol version, client identity, and client capabilities in `_meta`, and
 * Streamable HTTP mirrors selected fields into `MCP-Protocol-Version`,
 * `Mcp-Method`, and `Mcp-Name` headers.
 */
/** The modern (stateless) protocol revision implemented by this client. */
export declare const MCP_PROTOCOL_VERSION_2026_07_28 = "2026-07-28";
/** Legacy (initialize handshake) revision this client speaks for compatibility. */
export declare const MCP_PROTOCOL_VERSION_LEGACY = "2025-03-26";
/** Modern-era revisions this client can speak, most preferred first. */
export declare const MCP_MODERN_PROTOCOL_VERSIONS: readonly string[];
/** Protocol generation: modern = per-request metadata (2026-07-28+), legacy = initialize handshake. */
export type MCPProtocolEra = "modern" | "legacy";
/**
 * Per-server protocol preference from configuration.
 * - `auto`: attempt modern first; bounded, observable legacy fallback per the
 *   specification's era-detection rules. Default when unset.
 * - `2026-07-28`: strict modern-only; never initializes a legacy session.
 * - `legacy`: bounded compatibility mode; always uses the legacy handshake.
 */
export type MCPProtocolPreference = "auto" | "2026-07-28" | "legacy";
export declare const MCP_PROTOCOL_PREFERENCES: readonly MCPProtocolPreference[];
export declare function isMCPProtocolPreference(value: unknown): value is MCPProtocolPreference;
/** Resolve the effective preference; `auto` when unset. */
export declare function resolveMCPProtocolPreference(value: MCPProtocolPreference | undefined): MCPProtocolPreference;
/** True when a version string names a modern-era revision (date-based, >= 2026-07-28). */
export declare function isModernProtocolVersion(version: string): boolean;
/** Headers do not match the request body, or required headers are missing/malformed. */
export declare const MCP_ERROR_HEADER_MISMATCH = -32020;
/** The request requires a client capability the client did not declare. */
export declare const MCP_ERROR_MISSING_REQUIRED_CLIENT_CAPABILITY = -32021;
/** The server does not implement the requested protocol version. */
export declare const MCP_ERROR_UNSUPPORTED_PROTOCOL_VERSION = -32022;
/** Standard JSON-RPC method-not-found (modern servers pair it with HTTP 404). */
export declare const JSONRPC_ERROR_METHOD_NOT_FOUND = -32601;
/** Standard JSON-RPC invalid-params (modern servers reject missing `_meta` with it). */
export declare const JSONRPC_ERROR_INVALID_PARAMS = -32602;
export declare const MCP_META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion";
export declare const MCP_META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo";
export declare const MCP_META_CLIENT_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
export declare const MCP_META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
/** Client identity advertised in modern per-request `_meta`. */
export interface MCPModernClientContext {
    protocolVersion: string;
    clientInfo: {
        name: string;
        version: string;
    };
    /** Capabilities relevant to requests, e.g. `{ roots: {...}, elicitation: {...} }`. */
    capabilities: Record<string, unknown>;
}
/**
 * Build the `_meta` object every modern request MUST carry. Callers merge this
 * into `params._meta`, preserving any pre-existing keys (e.g. `progressToken`).
 */
export declare function buildModernRequestMeta(context: MCPModernClientContext): Record<string, unknown>;
/** Merge modern `_meta` into request params without clobbering existing keys. */
export declare function withModernMeta(params: Record<string, unknown>, context: MCPModernClientContext): Record<string, unknown>;
/** RFC 9110 field-value safe set: visible ASCII, space, and horizontal tab. */
export declare function isPlainAsciiHeaderValue(value: string): boolean;
/**
 * Encode a value for `Mcp-Name` / `Mcp-Param-{Name}` headers: plain ASCII when
 * safe, otherwise the `=?base64?<base64-utf8>?=` sentinel. Values already
 * matching the sentinel pattern MUST also be encoded to avoid ambiguity.
 */
export declare function encodeMcpHeaderValue(value: string): string;
/**
 * Build the mirrored headers a modern Streamable HTTP request MUST carry:
 * `MCP-Protocol-Version` (must equal the `_meta` version), `Mcp-Method`, and —
 * for `tools/call`, `resources/read`, `prompts/get` — `Mcp-Name`.
 */
export declare function buildModernMcpHeaders(input: {
    protocolVersion: string;
    method: string;
    params?: Record<string, unknown>;
}): Record<string, string>;
/** A validated binding from a tool inputSchema property to an `Mcp-Param-*` header. */
export interface McpHeaderParamBinding {
    /** Exact property path (chain of `properties` keys) in the call arguments. */
    propertyPath: string[];
    /** The `name` portion of the `Mcp-Param-{name}` header. */
    headerName: string;
    /** Primitive type of the annotated property. */
    propertyType: "string" | "integer" | "boolean";
}
export interface XMcpHeaderBindingsResult {
    bindings: McpHeaderParamBinding[];
    /** Human-readable reasons the tool definition is invalid for HTTP mirroring. */
    violations: string[];
}
/**
 * Collect `x-mcp-header` bindings from a tool `inputSchema`, enforcing the
 * specification constraints: field-name token syntax, primitive (non-number)
 * types, case-insensitive uniqueness, and static reachability via `properties`
 * chains only. Any violation invalidates the tool definition for HTTP clients.
 */
export declare function collectXMcpHeaderBindings(inputSchema: unknown): XMcpHeaderBindingsResult;
/**
 * Extract `Mcp-Param-{name}` headers from tool call arguments per validated
 * bindings. Missing or null values omit the header, per the specification.
 */
export declare function buildXMcpParamHeaders(bindings: readonly McpHeaderParamBinding[], args: Record<string, unknown>): Record<string, string>;
/** Failure classes for a modern probe request. */
export type MCPProbeFailureClass = 
/** Recognized modern JSON-RPC error: the server speaks a modern revision. */
"modern-error"
/** 4xx without a recognized modern error body: legacy-era server signal. */
 | "legacy-signal"
/** 401/403 (and WWW-Authenticate challenges): never a downgrade signal. */
 | "auth-failure"
/** Anything else (5xx, network, malformed payload): not a downgrade signal. */
 | "other-failure";
export interface MCPProbeClassification {
    class: MCPProbeFailureClass;
    /** Protocol-defined modern error code when recognized. */
    modernErrorCode?: number;
    /** `data.supported` from an UnsupportedProtocolVersionError, when present. */
    supportedVersions?: string[];
    /** `data.requested` from an UnsupportedProtocolVersionError, when present. */
    requestedVersion?: string;
}
/**
 * Classify a failed modern probe per the specification's era-detection rules:
 * recognized modern JSON-RPC errors identify a modern server; a 400/404/405
 * without one identifies a legacy server; auth and security failures are never
 * era signals and must never authorize a downgrade.
 */
export declare function classifyMcpProbeFailure(status: number, parsedBody: unknown): MCPProbeClassification;
/** Lifecycle state of a protocol feature, mirroring the specification's feature lifecycle. */
export type MCPFeatureLifecycle = "active" | "deprecated" | "removed";
export interface MCPProtocolFeatureState {
    feature: string;
    lifecycle: MCPFeatureLifecycle;
    /** Secret-free explanation shown in diagnostics. */
    note?: string;
}
/** How the effective era/version was reached. */
export type MCPNegotiationState = 
/** No negotiation attempt has completed yet. */
"pending"
/** Modern era confirmed (probe or direct modern request succeeded). */
 | "modern"
/** Modern era after selecting a mutually supported version from UnsupportedProtocolVersionError. */
 | "modern-version-retry"
/** Legacy era via era detection (legacy server signal) under `auto`. */
 | "legacy-fallback"
/** Legacy era because configuration forced it (`legacy`) or the transport is stdio. */
 | "legacy-forced"
/** Negotiation failed; the connection could not be established. */
 | "failed";
/** Machine-readable reasons a legacy fallback was engaged (never auth/security driven). */
export type MCPDowngradeReason = 
/** `protocol: "legacy"` configured explicitly. */
"preference-legacy"
/** stdio transport has no per-request HTTP signals; legacy handshake retained. */
 | "stdio-transport"
/** Probe returned 400/404/405 without a recognized modern error body. */
 | "legacy-server-signal"
/** A modern server advertised only legacy-era versions in `supported`. */
 | "server-advertised-legacy-only";
/**
 * One authoritative, secret-free observation of a server's negotiated protocol
 * state. Consumed by `/extensions` (#4291) and customization doctor (#4288);
 * contains no credentials, tokens, metadata documents, or header values.
 */
export interface MCPProtocolObservation {
    /** Configured preference (defaults to `auto`). */
    preference: MCPProtocolPreference;
    /** Effective protocol version in use, once negotiated. */
    effectiveVersion: string | null;
    /** Effective era, once negotiated. */
    era: MCPProtocolEra | null;
    /** How the effective state was reached. */
    negotiation: MCPNegotiationState;
    /** Why a legacy fallback engaged; null unless `negotiation` is a legacy state. */
    downgradeReason: MCPDowngradeReason | null;
    /** Versions the server advertised (via server/discover or version errors). */
    supportedVersions: string[];
    /** Self-reported server identity (display only; never security-relevant). */
    serverInfo: {
        name: string;
        version: string;
    } | null;
    /** Lifecycle visibility for protocol features (legacy session behavior, etc). */
    features: MCPProtocolFeatureState[];
    /** v2 capability state observed for this connection. */
    capabilities: {
        /** server/discover answered (optional per spec; absence does not block calls). */
        discover: "yes" | "no" | "unknown";
        /** Server advertised tools capability. */
        tools: boolean;
        /** Server advertised resources capability. */
        resources: boolean;
        /** Server advertised prompts capability. */
        prompts: boolean;
    };
}
/** Initial observation before negotiation completes. */
export declare function createMCPProtocolObservation(preference: MCPProtocolPreference): MCPProtocolObservation;
/** Legacy session/transport features reported as deprecated under the feature lifecycle. */
export declare function legacyEraFeatureStates(): MCPProtocolFeatureState[];
/** Finalize an observation for a negotiated modern connection. */
export declare function modernEraObservation(input: {
    preference: MCPProtocolPreference;
    effectiveVersion: string;
    negotiation: "modern" | "modern-version-retry";
    supportedVersions?: string[];
    serverInfo?: {
        name: string;
        version: string;
    } | null;
    capabilities?: {
        tools?: boolean;
        resources?: boolean;
        prompts?: boolean;
    };
    discover: "yes" | "no" | "unknown";
}): MCPProtocolObservation;
/** Finalize an observation for a negotiated legacy connection. */
export declare function legacyEraObservation(input: {
    preference: MCPProtocolPreference;
    effectiveVersion: string;
    negotiation: "legacy-fallback" | "legacy-forced";
    downgradeReason: MCPDowngradeReason;
    serverInfo?: {
        name: string;
        version: string;
    } | null;
    capabilities?: {
        tools?: boolean;
        resources?: boolean;
        prompts?: boolean;
    };
}): MCPProtocolObservation;
/** Cache scope hint: public results may cross authorization contexts; private must not. */
export type MCPCacheScope = "public" | "private";
/** Server-supplied caching hints carried on cacheable `complete` results. */
export interface MCPCacheHints {
    /** Milliseconds the result may be considered fresh; absent/negative means 0. */
    ttlMs?: number;
    cacheScope?: MCPCacheScope;
}
/** Normalize raw hints: negative ttlMs is treated as 0 per the specification. */
export declare function normalizeMcpCacheHints(raw: unknown): MCPCacheHints | undefined;
/** Result type marker for interim input requests. */
export declare const MCP_RESULT_TYPE_INPUT_REQUIRED = "input_required";
export declare const MCP_RESULT_TYPE_COMPLETE = "complete";
/** Input request methods a server may embed in an InputRequiredResult. */
export declare const MCP_INPUT_REQUEST_METHODS: Set<string>;
export interface MCPInputRequiredData {
    inputRequests: Record<string, {
        method: string;
        params?: Record<string, unknown>;
    }>;
    requestState?: string;
}
/**
 * Extract MRTR input data from a JSON-RPC result. Returns null when the result
 * is a normal `complete` result (including legacy results with no resultType,
 * which the specification requires clients to treat as `"complete"`).
 * Throws on a malformed `input_required` payload.
 */
export declare function extractMcpInputRequired(result: unknown): MCPInputRequiredData | null;