@corbits/mcp 0.3.1 → 0.4.0

package/dist/client.js

@@ -1,40 +1,135 @@
-// MCP streamable-HTTP transport client (2025-03-26 spec). Each call sends one
-// request and awaits its one reply, which is all initialize/tools-list/
-// tools-call need; the session `initialize` opens is carried in `session`.
-// No resumption.
+// Streamable-HTTP JSON-RPC client for MCP 2026-07-28, with a legacy
+// fallback. A 2026 server is stateless: `server/discover` then one POST per
+// call, carrying protocol metadata in `_meta` and in `Mcp-*` headers, and no
+// session id. Modern cancellation closes the response stream; only legacy
+// requests send `notifications/cancelled`. No SSE resumption or HTTP+SSE.
 import { type } from "arktype";
-export const McpToolSchema = type({
-    name: "string",
-    "description?": "string",
-    inputSchema: "Record<string, unknown>",
-    "annotations?": {
-        "readOnlyHint?": "boolean",
-        "destructiveHint?": "boolean",
-        "idempotentHint?": "boolean",
-        "openWorldHint?": "boolean",
-    },
-});
+import { createResourceBudget, } from "./client/resource-budget.js";
+import { MCP_PROTOCOL_VERSION, } from "./protocol/types.js";
+import { McpError, McpErrorCode } from "./protocol/errors.js";
+import { MCP_EXT_TASKS, MCP_EXT_UI, MCP_EXT_SKILLS, validateExtensionSettings, } from "./protocol/extensions.js";
+import { McpToolSchema, PromptSchema, PromptResult, ResourceSchema, TemplateSchema, CompletionResult, SkillSchema, TaskHandleSchema, ToolCallResult, DiscoverResult, JsonRpcResponse, validateRequest, validateResult, validateNotification, validateTask, record, validateProgressToken, } from "./protocol/schemas.js";
+import { encodeHeaderValue, paramHeaders, collectHeaderSlots, } from "./protocol/headers.js";
+import { mcpNameFor } from "./protocol/methods.js";
+export { MCP_PROTOCOL_VERSION, McpError, McpErrorCode, MCP_EXT_TASKS, MCP_EXT_UI, MCP_EXT_SKILLS, McpToolSchema, };
+const LEGACY_PROTOCOL_VERSION = "2025-03-26";
+/** Legacy handshake versions, newest first. */
+const LEGACY_VERSIONS = [
+    "2025-11-25",
+    "2025-06-18",
+    "2025-03-26",
+    "2024-11-05",
+];
+const META_PROTOCOL = "io.modelcontextprotocol/protocolVersion";
+const META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo";
+const META_CLIENT_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
+const META_SUBSCRIPTION = "io.modelcontextprotocol/subscriptionId";
+const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
+const CLIENT_INFO = { name: "@corbits/mcp", version: "0.3.1" };
+const UI_MIME_TYPES = ["text/html;profile=mcp-app"];
+const MODERN_ERROR_CODES = new Set([
+    McpErrorCode.HeaderMismatch,
+    McpErrorCode.MissingRequiredClientCapability,
+    McpErrorCode.UnsupportedProtocolVersion,
+]);
 /** The run-time `tools/call` and `initialize` bound when a caller sets none. */
 export const DEFAULT_TIMEOUT_MS = 60_000;
-const PROTOCOL_VERSION = "2025-03-26";
 /** Largest response body or SSE frame read before the stream is cancelled. */
 const MAX_MESSAGE_BYTES = 4 * 1024 * 1024;
-const JsonRpcResponse = type({
-    jsonrpc: "'2.0'",
-    id: "string | number",
-    "result?": "unknown",
-    "error?": { code: "number", message: "string", "data?": "unknown" },
-});
-export class McpError extends Error {
-    /** The HTTP status, when the server answered with a non-2xx one. */
-    status;
-    constructor(message, status) {
-        super(message);
-        this.name = "McpError";
-        this.status = status;
+/** A cursor loop that never ends is a misbehaving server, not a catalog. */
+const MAX_PAGES = 1_000;
+let nextId = 1;
+const activeProgressTokens = new Set();
+function reserveProgressToken(token) {
+    if (token === undefined)
+        return;
+    if (activeProgressTokens.has(token))
+        throw new McpError("progress token is already active");
+    activeProgressTokens.add(token);
+}
+function validationContext(opts) {
+    return {
+        ...opts.validation,
+        era: opts.session !== undefined && !isModernSession(opts.session)
+            ? "legacy"
+            : "modern",
+        extensions: enabledExtensions(opts),
+        ...(opts.session?.capabilities !== undefined
+            ? { serverCapabilities: opts.session.capabilities }
+            : {}),
+        ...(opts.inputSchema !== undefined
+            ? { inputSchema: opts.inputSchema }
+            : {}),
+        ...(opts.outputSchema !== undefined
+            ? { outputSchema: opts.outputSchema }
+            : {}),
+        clientCapabilities: clientCapabilities(opts),
+    };
+}
+export function createMcpRequestTransport(url, defaults = {}) {
+    return {
+        async request(method, params, options = {}) {
+            const opts = { ...defaults, ...options };
+            const callOpts = opts.session === undefined ? asModern(opts) : opts;
+            const { result } = await sendRequest(url, method, params, callOpts);
+            return result;
+        },
+        listen(filter, observer, options = {}) {
+            return mcpListen(url, filter, observer, { ...defaults, ...options });
+        },
+    };
+}
+function isModernSession(session) {
+    return session?.protocolVersion === MCP_PROTOCOL_VERSION;
+}
+function enabledExtensions(opts) {
+    if (opts.extensions !== undefined)
+        return opts.extensions;
+    return opts.session?.extensions ?? [];
+}
+function requireExtension(opts, id) {
+    if (!enabledExtensions(opts).includes(id)) {
+        throw new McpError(`extension ${id} is not enabled`);
     }
 }
-let nextId = 1;
+function clientCapabilities(opts) {
+    if (opts.elicitation !== undefined) {
+        const { elicitation, ...base } = opts;
+        const capabilities = clientCapabilities(base);
+        const modes = {
+            ...(elicitation.form === true ? { form: {} } : {}),
+            ...(elicitation.url === true ? { url: {} } : {}),
+        };
+        const { elicitation: _inherited, ...rest } = capabilities;
+        return {
+            ...rest,
+            ...(Object.keys(modes).length > 0 ? { elicitation: modes } : {}),
+        };
+    }
+    if (opts.clientCapabilities === undefined &&
+        opts.extensions === undefined &&
+        opts.uiMimeTypes === undefined &&
+        opts.session?.clientCapabilities !== undefined) {
+        return opts.session.clientCapabilities;
+    }
+    const extensions = enabledExtensions(opts);
+    validateExtensionSettings(Object.fromEntries(extensions.map((id) => [id, {}])));
+    if (extensions.length === 0)
+        return opts.clientCapabilities ?? {};
+    const advertised = {};
+    for (const id of extensions) {
+        if (id === MCP_EXT_UI) {
+            const mimeTypes = opts.uiMimeTypes ?? opts.session?.uiMimeTypes;
+            advertised[id] = {
+                mimeTypes: [...(mimeTypes ?? UI_MIME_TYPES)],
+            };
+        }
+        else {
+            advertised[id] = {};
+        }
+    }
+    return { ...opts.clientCapabilities, extensions: advertised };
+}
 /** A reply to request `id`: a message carrying `result` or `error` and no
  * `method`, which would make it a server request reusing the id. */
 function isResponseTo(message, id) {
@@ -44,92 +139,250 @@ function isResponseTo(message, id) {
         !("method" in message) &&
         ("result" in message || "error" in message));
 }
-function headersFor(session) {
-    return {
+function isNotification(message) {
+    return (typeof message === "object" &&
+        message !== null &&
+        message.jsonrpc === "2.0" &&
+        typeof message.method === "string" &&
+        !("id" in message));
+}
+function collectHeaders(schema, toolName) {
+    try {
+        return collectHeaderSlots(schema);
+    }
+    catch (cause) {
+        console.warn(`excluding MCP tool ${toolName}: ${cause instanceof Error ? cause.message : String(cause)}`);
+        return undefined;
+    }
+}
+function requestHeaders(opts, method, mcpName, extra) {
+    const headers = {
         "content-type": "application/json",
         accept: "application/json, text/event-stream",
-        ...(session === undefined
-            ? {}
-            : { "mcp-protocol-version": session.protocolVersion }),
-        ...(session?.sessionId === undefined
-            ? {}
-            : { "mcp-session-id": session.sessionId }),
     };
+    if (isModernSession(opts.session)) {
+        headers["MCP-Protocol-Version"] = MCP_PROTOCOL_VERSION;
+        headers["Mcp-Method"] = method;
+        if (mcpName !== undefined)
+            headers["Mcp-Name"] = encodeHeaderValue(mcpName);
+        for (const [key, value] of Object.entries(extra))
+            headers[key] = value;
+        return headers;
+    }
+    if (opts.session !== undefined) {
+        headers["mcp-protocol-version"] = opts.session.protocolVersion;
+        if (opts.session.sessionId !== undefined) {
+            headers["mcp-session-id"] = opts.session.sessionId;
+        }
+    }
+    return headers;
+}
+function progressParams(params, opts, id) {
+    const metadata = params?._meta === undefined ? {} : record(params._meta, "request _meta");
+    const token = opts.progressToken !== undefined
+        ? opts.progressToken
+        : (metadata.progressToken ??
+            (opts.onProgress !== undefined ? id : undefined));
+    if (Object.hasOwn(metadata, "progressToken"))
+        validateProgressToken(metadata.progressToken);
+    if (token !== undefined)
+        validateProgressToken(token);
+    return {
+        ...params,
+        _meta: {
+            ...metadata,
+            ...(token !== undefined ? { progressToken: token } : {}),
+        },
+    };
+}
+function modernParams(params, opts, id) {
+    const base = progressParams(params, opts, id);
+    return {
+        ...base,
+        _meta: {
+            ...record(base._meta),
+            [META_PROTOCOL]: MCP_PROTOCOL_VERSION,
+            [META_CLIENT_INFO]: CLIENT_INFO,
+            [META_CLIENT_CAPABILITIES]: clientCapabilities(opts),
+        },
+    };
+}
+function stripMeta(params) {
+    if (params === undefined)
+        return {};
+    const rest = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (key !== "_meta")
+            rest[key] = value;
+    }
+    return rest;
+}
+/** A fresh request. The aborted call signal must not cancel this notification,
+ * and progress fields belong to the call that was cancelled. */
+function cancellationOpts(opts) {
+    return {
+        ...(opts.fetch !== undefined ? { fetch: opts.fetch } : {}),
+        ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        ...(opts.session !== undefined ? { session: opts.session } : {}),
+        ...(opts.extensions !== undefined ? { extensions: opts.extensions } : {}),
+        ...(opts.uiMimeTypes !== undefined
+            ? { uiMimeTypes: opts.uiMimeTypes }
+            : {}),
+    };
+}
+function deliverProgress(message, token, onProgress, previous) {
+    if (token === undefined || !isNotification(message)) {
+        return previous;
+    }
+    if (message.method !== "notifications/progress")
+        return previous;
+    const params = message.params;
+    if (params === undefined || params.progressToken !== token)
+        return previous;
+    validateNotification("notifications/progress", params);
+    if (typeof params.progress !== "number")
+        return previous;
+    const progress = {
+        progressToken: token,
+        progress: params.progress,
+    };
+    if (typeof params.total === "number")
+        progress.total = params.total;
+    if (typeof params.message === "string")
+        progress.message = params.message;
+    if (previous !== undefined && progress.progress <= previous)
+        throw new McpError("progress must strictly increase");
+    onProgress?.(progress);
+    return progress.progress;
 }
 /**
  * Send one JSON-RPC request over streamable HTTP and return its `result`.
  * Handles both response shapes the spec allows: a direct `application/json`
  * body, and a `text/event-stream` whose `data:` frames each carry a
  * JSON-RPC message -- the first one matching this request's id wins.
+ * Progress notifications on that stream are delivered and not treated as the
+ * response.
  */
 async function sendRequest(url, method, params, opts) {
+    if (method === "resources/read" &&
+        opts.maxDecodedBytes !== undefined &&
+        (!Number.isSafeInteger(opts.maxDecodedBytes) || opts.maxDecodedBytes < 0))
+        throw new McpError("maxDecodedBytes must be a nonnegative safe integer");
     const fetchImpl = opts.fetch ?? fetch;
     const id = nextId++;
-    const timeout = opts.timeoutMs === undefined
-        ? undefined
-        : AbortSignal.timeout(opts.timeoutMs);
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const timeout = AbortSignal.timeout(timeoutMs);
     const signals = [timeout, opts.signal].filter((s) => s !== undefined);
     const signal = signals.length > 0 ? AbortSignal.any(signals) : undefined;
+    const modern = isModernSession(opts.session);
+    const bodyParams = modern
+        ? modernParams(params, opts, id)
+        : progressParams(params, opts, id);
+    if (method !== "initialize")
+        validateRequest(method, bodyParams, validationContext(opts));
+    const progressToken = record(bodyParams._meta).progressToken;
+    let previousProgress;
+    const extra = method === "tools/call"
+        ? paramHeaders(opts.inputSchema, params?.arguments, String(params?.name ?? ""))
+        : {};
     let message;
     let sessionId;
+    const notifyCancel = () => {
+        void sendNotification(url, "notifications/cancelled", cancellationOpts(opts), {
+            requestId: id,
+            reason: "the caller aborted the request",
+        }).catch(() => undefined);
+    };
+    reserveProgressToken(progressToken);
+    if (!modern && method !== "initialize" && opts.signal !== undefined) {
+        opts.signal.addEventListener("abort", notifyCancel, { once: true });
+    }
     try {
         const response = await fetchImpl(url, {
             method: "POST",
-            headers: headersFor(opts.session),
+            headers: requestHeaders(opts, method, mcpNameFor(method, params), extra),
             body: JSON.stringify({
                 jsonrpc: "2.0",
                 id,
                 method,
-                ...(params !== undefined ? { params } : {}),
+                ...(bodyParams !== undefined ? { params: bodyParams } : {}),
             }),
             ...(signal !== undefined ? { signal } : {}),
         });
         if (!response.ok) {
-            await response.body?.cancel();
-            throw new McpError(`MCP server ${url} responded ${response.status} to ${method}`, response.status);
+            throw await errorFrom(response, url, method, signal);
         }
         sessionId = response.headers.get("mcp-session-id") ?? undefined;
         const contentType = response.headers.get("content-type") ?? "";
+        const budget = method === "resources/read" && opts.maxDecodedBytes !== undefined
+            ? createResourceBudget(opts.maxDecodedBytes, contentType.includes("text/event-stream"))
+            : undefined;
         message = contentType.includes("text/event-stream")
-            ? await readSseJsonRpc(response, id, signal)
-            : parseJson(await readCapped(response, signal));
+            ? await readSseJsonRpc(response, id, signal, (frame) => {
+                previousProgress = deliverProgress(frame, progressToken, opts.onProgress, previousProgress);
+            }, budget)
+            : parseJson(await readCapped(response, signal, budget));
     }
     catch (cause) {
         if (opts.signal?.aborted === true) {
-            throw new McpError(`${method} to MCP server ${url} was cancelled`);
+            throw new McpError(`${method} to MCP server ${url} was cancelled`, undefined, undefined, undefined, {
+                cancelled: true,
+            });
         }
         if (timeout?.aborted === true) {
-            throw new McpError(`MCP server ${url} did not answer ${method} within ${String(opts.timeoutMs)}ms`);
+            throw new McpError(`MCP server ${url} did not answer ${method} within ${String(timeoutMs)}ms`, undefined, undefined, undefined, { timedOut: true });
         }
         throw cause;
     }
+    finally {
+        opts.signal?.removeEventListener("abort", notifyCancel);
+        if (progressToken !== undefined)
+            activeProgressTokens.delete(progressToken);
+    }
     const parsed = JsonRpcResponse(message);
-    if (parsed instanceof type.errors || !isResponseTo(message, id)) {
-        throw new McpError(`MCP server ${url} sent a malformed response to ${method}${parsed instanceof type.errors ? `: ${parsed.summary}` : ""}`);
+    if (parsed instanceof type.errors ||
+        !isResponseTo(message, id) ||
+        (parsed.error !== undefined && Object.hasOwn(parsed, "result"))) {
+        throw new McpError(`MCP server ${url} sent a malformed response to ${method}`);
     }
     if (parsed.error !== undefined) {
-        throw new McpError(`MCP server ${url} rejected ${method}: ${parsed.error.message}`);
+        throw new McpError(`MCP server ${url} rejected ${method}: ${parsed.error.message}`, undefined, parsed.error.code, parsed.error.data, { source: "peer" });
     }
+    if (method !== "initialize")
+        validateResult(method, parsed.result, {
+            ...validationContext(opts),
+            // Never accept a caller-supplied validation context as proof of a wire budget.
+            maxDecodedBytes: method === "resources/read" ? opts.maxDecodedBytes : undefined,
+        });
     return { result: parsed.result, sessionId };
 }
 /** Send a JSON-RPC notification; the server answers 202 with no body. */
-async function sendNotification(url, method, opts) {
+async function sendNotification(url, method, opts, params) {
     const fetchImpl = opts.fetch ?? fetch;
-    const timeout = opts.timeoutMs === undefined
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const modern = isModernSession(opts.session);
+    const bodyParams = params === undefined
         ? undefined
-        : AbortSignal.timeout(opts.timeoutMs);
+        : modern
+            ? modernParams(params, cancellationOpts(opts), 0)
+            : params;
     let response;
     try {
         response = await fetchImpl(url, {
             method: "POST",
-            headers: headersFor(opts.session),
-            body: JSON.stringify({ jsonrpc: "2.0", method }),
+            headers: requestHeaders(opts, method, undefined, {}),
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                method,
+                ...(bodyParams !== undefined ? { params: bodyParams } : {}),
+            }),
             ...(timeout !== undefined ? { signal: timeout } : {}),
         });
     }
     catch (cause) {
         if (timeout?.aborted === true) {
-            throw new McpError(`MCP server ${url} did not answer ${method} within ${String(opts.timeoutMs)}ms`);
+            throw new McpError(`MCP server ${url} did not answer ${method} within ${String(opts.timeoutMs)}ms`, undefined, undefined, undefined, { timedOut: true });
         }
         throw cause;
     }
@@ -138,6 +391,50 @@ async function sendNotification(url, method, opts) {
         throw new McpError(`MCP server ${url} responded ${response.status} to ${method}`, response.status);
     }
 }
+async function errorFrom(response, url, method, signal) {
+    if (response.status === 401 || response.status === 403) {
+        void response.body?.cancel().catch(() => undefined);
+        const challenge = response.headers.get("www-authenticate");
+        return new McpError(`MCP server ${url} responded ${response.status} to ${method}`, response.status, undefined, undefined, challenge === null ? undefined : { wwwAuthenticate: challenge });
+    }
+    let code;
+    let data;
+    let detail;
+    try {
+        const text = await readCapped(response, signal);
+        if (text.length > 0) {
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = undefined;
+            }
+            if (typeof parsed === "object" && parsed !== null) {
+                const error = parsed.error;
+                if (typeof error === "object" && error !== null) {
+                    const record = error;
+                    if (typeof record.code === "number" &&
+                        typeof record.message === "string") {
+                        code = record.code;
+                        detail = record.message;
+                        data = record.data;
+                    }
+                }
+            }
+        }
+    }
+    catch (cause) {
+        if (cause instanceof McpError && cause.message.includes("larger than"))
+            throw cause;
+    }
+    const message = detail === undefined
+        ? `MCP server ${url} responded ${response.status} to ${method}`
+        : `MCP server ${url} rejected ${method}: ${detail}`;
+    return new McpError(message, response.status, code, data, {
+        source: code === undefined ? "local" : "peer",
+    });
+}
 function parseJson(text) {
     try {
         return JSON.parse(text);
@@ -150,7 +447,8 @@ function overflow() {
     return new McpError(`MCP server sent a message larger than ${String(MAX_MESSAGE_BYTES)} bytes`);
 }
 /** Read a body's chunks, cancelling the stream when the signal aborts. */
-async function* chunks(response, signal) {
+async function* chunks(response, signal, budget) {
+    signal?.throwIfAborted();
     const body = response.body;
     if (body === null) {
         throw new McpError("MCP server sent a response with no body");
@@ -161,8 +459,11 @@ async function* chunks(response, signal) {
     try {
         for (;;) {
             const { done, value } = await reader.read();
-            if (done)
+            if (done) {
+                budget?.finish();
                 return;
+            }
+            budget?.push(value);
             yield value;
         }
     }
@@ -171,30 +472,29 @@ async function* chunks(response, signal) {
         await reader.cancel().catch(() => undefined);
     }
 }
-async function readCapped(response, signal) {
+async function readCapped(response, signal, budget) {
     const decoder = new TextDecoder();
     let text = "";
     let bytes = 0;
-    for await (const chunk of chunks(response, signal)) {
+    for await (const chunk of chunks(response, signal, budget)) {
         bytes += chunk.byteLength;
-        if (bytes > MAX_MESSAGE_BYTES)
+        if (budget === undefined && bytes > MAX_MESSAGE_BYTES)
             throw overflow();
         text += decoder.decode(chunk, { stream: true });
     }
     return text + decoder.decode();
 }
-/** Read an SSE body and return the first JSON-RPC message whose id matches. */
-async function readSseJsonRpc(response, id, signal) {
+async function* sseMessages(response, signal, budget) {
     const decoder = new TextDecoder();
     let buffer = "";
-    for await (const chunk of chunks(response, signal)) {
+    for await (const chunk of chunks(response, signal, budget)) {
         buffer += decoder.decode(chunk, { stream: true });
         const frames = buffer.split(/\r\n\r\n|\n\n|\r\r/);
         buffer = frames.pop() ?? "";
-        if (buffer.length > MAX_MESSAGE_BYTES)
+        if (budget === undefined && buffer.length > MAX_MESSAGE_BYTES)
             throw overflow();
         for (const frame of frames) {
-            if (frame.length > MAX_MESSAGE_BYTES)
+            if (budget === undefined && frame.length > MAX_MESSAGE_BYTES)
                 throw overflow();
             const dataLines = frame
                 .split(/\r\n|\r|\n/)
@@ -202,30 +502,48 @@ async function readSseJsonRpc(response, id, signal) {
                 .map((line) => line.slice(5).trim());
             if (dataLines.length === 0)
                 continue;
-            let candidate;
             try {
-                candidate = JSON.parse(dataLines.join("\n"));
+                yield JSON.parse(dataLines.join("\n"));
             }
             catch {
-                continue;
+                // A non-JSON data frame is not the response; keep reading.
             }
-            if (isResponseTo(candidate, id))
-                return candidate;
         }
     }
+}
+/** Read an SSE body and return the first JSON-RPC message whose id matches. */
+async function readSseJsonRpc(response, id, signal, onMessage, budget) {
+    for await (const candidate of sseMessages(response, signal, budget)) {
+        if (isResponseTo(candidate, id))
+            return candidate;
+        onMessage(candidate);
+    }
     throw new McpError("MCP server closed the event stream without a matching response");
 }
 const InitializeResult = type({
     "protocolVersion?": "string",
     "serverInfo?": { name: "string", "version?": "string" },
 });
+function serverInfoOf(meta) {
+    const info = meta?.[META_SERVER_INFO];
+    if (typeof info !== "object" || info === null)
+        return undefined;
+    const name = info.name;
+    if (typeof name !== "string")
+        return undefined;
+    const version = info.version;
+    return typeof version === "string" ? { name, version } : { name };
+}
 /** `initialize` handshake followed by `notifications/initialized`. Pass the
- * returned session to every later call on this server. */
+ * returned session to every later call on a legacy server. */
 export async function mcpInitialize(url, opts = {}) {
+    return initializeLegacy(url, opts, LEGACY_PROTOCOL_VERSION);
+}
+async function initializeLegacy(url, opts, protocolVersion) {
     const { result, sessionId } = await sendRequest(url, "initialize", {
-        protocolVersion: PROTOCOL_VERSION,
+        protocolVersion,
         capabilities: {},
-        clientInfo: { name: "@corbits/mcp", version: "0.2.0" },
+        clientInfo: { name: "@corbits/mcp", version: "0.3.1" },
     }, {
         ...(opts.fetch !== undefined ? { fetch: opts.fetch } : {}),
         ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
@@ -239,7 +557,7 @@ export async function mcpInitialize(url, opts = {}) {
         throw new McpError(`MCP server ${url} sent a protocolVersion that is not printable ASCII`);
     }
     const session = {
-        protocolVersion: info.protocolVersion ?? PROTOCOL_VERSION,
+        protocolVersion: info.protocolVersion ?? protocolVersion,
         ...(sessionId !== undefined ? { sessionId } : {}),
         ...(info.serverInfo !== undefined ? { serverInfo: info.serverInfo } : {}),
     };
@@ -249,30 +567,750 @@ export async function mcpInitialize(url, opts = {}) {
     });
     return session;
 }
+function supportedFrom(data) {
+    if (typeof data !== "object" || data === null)
+        return [];
+    const supported = data.supported;
+    if (!Array.isArray(supported))
+        return [];
+    return supported.filter((version) => typeof version === "string");
+}
+function legacyVersion(supported) {
+    return LEGACY_VERSIONS.find((version) => supported.includes(version));
+}
+function shouldFallback(error) {
+    if (!(error instanceof McpError))
+        return false;
+    if (error.status !== undefined &&
+        error.status !== 400 &&
+        error.status !== 404)
+        return false;
+    if (error.cancelled)
+        return false;
+    if (error.timedOut)
+        return true;
+    // Streamable HTTP backward compatibility: inspect HTTP 400 bodies before
+    // falling back. Recognized modern errors require correcting the request,
+    // while empty or unrecognized bodies may come from a legacy session server.
+    if (error.status === 400)
+        return error.code === undefined || !MODERN_ERROR_CODES.has(error.code);
+    // Preserve the existing fallback rules for other transport responses.
+    if (error.code === McpErrorCode.MethodNotFound)
+        return true;
+    if (error.status === 404)
+        return true;
+    if (/unsupported protocol version/i.test(error.message))
+        return true;
+    if (/server not initialized/i.test(error.message))
+        return true;
+    if (error.status !== undefined)
+        return false;
+    if (error.code !== undefined && MODERN_ERROR_CODES.has(error.code))
+        return false;
+    // Malformed responses and any other error are real failures, not legacy.
+    return false;
+}
+/**
+ * Probe `server/discover`. A 2026-07-28 server returns a stateless session:
+ * later calls send no `initialize`, no `notifications/initialized`, and no
+ * `Mcp-Session-Id`. A method-not-found, a timeout, or a server that only
+ * speaks a 2025 (or earlier) version falls back to `initialize`. HTTP 400
+ * also falls back unless its body contains a recognized modern error. Authz
+ * failures, rate limits, server errors, and malformed responses are real
+ * failures and surface to the caller instead of triggering the legacy
+ * handshake.
+ */
+export async function mcpConnect(url, opts = {}) {
+    const probing = {
+        protocolVersion: MCP_PROTOCOL_VERSION,
+        clientCapabilities: clientCapabilities(opts),
+        ...(opts.extensions !== undefined && opts.extensions.length > 0
+            ? { extensions: opts.extensions }
+            : {}),
+        ...(opts.uiMimeTypes !== undefined
+            ? { uiMimeTypes: opts.uiMimeTypes }
+            : {}),
+    };
+    const probeOpts = { ...opts, session: probing };
+    try {
+        const { result } = await sendRequest(url, "server/discover", undefined, probeOpts);
+        const kind = resultKind(result);
+        if (kind !== "complete") {
+            throw new McpError(`MCP server ${url} sent a ${kind} result for server/discover`);
+        }
+        const parsed = DiscoverResult(result);
+        if (parsed instanceof type.errors) {
+            throw new McpError(`MCP server ${url} sent a malformed server/discover result: ${parsed.summary}`);
+        }
+        if (parsed.supportedVersions.includes(MCP_PROTOCOL_VERSION)) {
+            const meta = parsed._meta;
+            const serverInfo = serverInfoOf(meta);
+            return {
+                ...probing,
+                ...(serverInfo !== undefined ? { serverInfo } : {}),
+                capabilities: parsed.capabilities,
+                ...(parsed.instructions !== undefined
+                    ? { instructions: parsed.instructions }
+                    : {}),
+            };
+        }
+        const legacy = legacyVersion(parsed.supportedVersions);
+        if (legacy !== undefined)
+            return initializeLegacy(url, opts, legacy);
+        throw new McpError(`MCP server ${url} does not speak ${MCP_PROTOCOL_VERSION}`, undefined, McpErrorCode.UnsupportedProtocolVersion, { supported: parsed.supportedVersions, requested: MCP_PROTOCOL_VERSION });
+    }
+    catch (cause) {
+        if (cause instanceof McpError &&
+            cause.code === McpErrorCode.UnsupportedProtocolVersion &&
+            (cause.status === undefined ||
+                cause.status === 400 ||
+                cause.status === 404)) {
+            const legacy = legacyVersion(supportedFrom(cause.data));
+            if (legacy !== undefined)
+                return initializeLegacy(url, opts, legacy);
+            throw cause;
+        }
+        if (shouldFallback(cause))
+            return initializeLegacy(url, opts, LEGACY_PROTOCOL_VERSION);
+        throw cause;
+    }
+}
+function resultKind(result) {
+    if (typeof result !== "object" ||
+        result === null ||
+        !("resultType" in result)) {
+        return "complete";
+    }
+    const value = result.resultType;
+    if (value === undefined)
+        return "complete";
+    if (value === "complete" || value === "input_required" || value === "task") {
+        return value;
+    }
+    return "invalid";
+}
+function parseInputRequired(method, params, result, url) {
+    if (typeof result !== "object" || result === null) {
+        throw new McpError(`MCP server ${url} sent a malformed input_required result`);
+    }
+    const record = result;
+    if (record.inputRequests === undefined && record.requestState === undefined) {
+        throw new McpError(`MCP server ${url} sent an input_required result with neither inputRequests nor requestState`);
+    }
+    if (record.requestState !== undefined &&
+        typeof record.requestState !== "string") {
+        throw new McpError(`MCP server ${url} sent a non-string requestState`);
+    }
+    if (record.inputRequests !== undefined) {
+        if (typeof record.inputRequests !== "object" ||
+            record.inputRequests === null ||
+            Array.isArray(record.inputRequests)) {
+            throw new McpError(`MCP server ${url} sent a malformed inputRequests map`);
+        }
+        for (const value of Object.values(record.inputRequests)) {
+            if (typeof value !== "object" ||
+                value === null ||
+                typeof value.method !== "string") {
+                throw new McpError(`MCP server ${url} sent a malformed input request`);
+            }
+        }
+    }
+    return {
+        resultType: "input_required",
+        method,
+        params: stripMeta(params),
+        ...(record._meta !== undefined ? { _meta: record._meta } : {}),
+        ...(record.inputRequests !== undefined
+            ? { inputRequests: record.inputRequests }
+            : {}),
+        ...(typeof record.requestState === "string"
+            ? { requestState: record.requestState }
+            : {}),
+    };
+}
+function parseTask(result, url) {
+    const parsed = TaskHandleSchema(result);
+    if (parsed instanceof type.errors) {
+        throw new McpError(`MCP server ${url} sent a malformed task handle: ${parsed.summary}`);
+    }
+    return { resultType: "task", ...parsed };
+}
+async function requestResult(url, method, params, opts) {
+    const result = await createMcpRequestTransport(url, opts).request(method, params);
+    const kind = resultKind(result);
+    if (kind === "task")
+        return parseTask(result, url);
+    if (kind === "input_required")
+        return parseInputRequired(method, params, result, url);
+    return result;
+}
+function isInputRequired(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        result.resultType === "input_required");
+}
+function isTaskHandle(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        result.resultType === "task");
+}
+function readCache(result, url, method) {
+    if (typeof result !== "object" || result === null)
+        return {};
+    const record = result;
+    const cache = {};
+    if ("ttlMs" in record && record.ttlMs !== undefined) {
+        if (typeof record.ttlMs !== "number") {
+            throw new McpError(`MCP server ${url} sent a non-numeric ttlMs for ${method}`);
+        }
+        cache.ttlMs = record.ttlMs < 0 ? 0 : record.ttlMs;
+    }
+    if ("cacheScope" in record && record.cacheScope !== undefined) {
+        if (record.cacheScope !== "public" && record.cacheScope !== "private") {
+            throw new McpError(`MCP server ${url} sent an invalid cacheScope for ${method}`);
+        }
+        cache.cacheScope = record.cacheScope;
+    }
+    return cache;
+}
+function mergeCache(pages) {
+    let sawTtl = false;
+    let omittedTtl = false;
+    let ttl = Number.POSITIVE_INFINITY;
+    let scope;
+    let scopeOnEveryPage = pages.length > 0;
+    for (const page of pages) {
+        if (page.ttlMs === undefined)
+            omittedTtl = true;
+        else {
+            sawTtl = true;
+            ttl = Math.min(ttl, page.ttlMs);
+        }
+        if (page.cacheScope === undefined)
+            scopeOnEveryPage = false;
+        else if (scope === undefined)
+            scope = page.cacheScope;
+        else if (scope !== page.cacheScope) {
+            throw new McpError("MCP server changed cacheScope between pages");
+        }
+    }
+    const merged = {};
+    if (sawTtl)
+        merged.ttlMs = omittedTtl ? 0 : ttl;
+    if (scopeOnEveryPage && scope !== undefined)
+        merged.cacheScope = scope;
+    return merged;
+}
+function attachCache(items, cache) {
+    if (cache.ttlMs !== undefined) {
+        Object.defineProperty(items, "ttlMs", {
+            value: cache.ttlMs,
+            enumerable: false,
+        });
+    }
+    if (cache.cacheScope !== undefined) {
+        Object.defineProperty(items, "cacheScope", {
+            value: cache.cacheScope,
+            enumerable: false,
+        });
+    }
+    return items;
+}
+function nextCursorOf(result, url, method) {
+    if (typeof result !== "object" ||
+        result === null ||
+        !("nextCursor" in result)) {
+        return undefined;
+    }
+    const cursor = result.nextCursor;
+    if (cursor === undefined)
+        return undefined;
+    if (typeof cursor !== "string") {
+        throw new McpError(`MCP server ${url} sent a non-string nextCursor for ${method}`);
+    }
+    return cursor;
+}
+async function eachPage(url, method, base, opts) {
+    const pages = [];
+    const caches = [];
+    let cursor;
+    for (let page = 0; page < MAX_PAGES; page++) {
+        const params = cursor === undefined ? base : { ...base, cursor };
+        const result = await requestResult(url, method, params !== undefined && Object.keys(params).length > 0
+            ? params
+            : undefined, opts);
+        if (isInputRequired(result) || isTaskHandle(result)) {
+            throw new McpError(`MCP server ${url} sent ${result.resultType} for ${method}`);
+        }
+        pages.push(result);
+        caches.push(readCache(result, url, method));
+        const next = nextCursorOf(result, url, method);
+        if (next === undefined)
+            return { pages, cache: mergeCache(caches) };
+        cursor = next;
+    }
+    throw new McpError(`MCP server ${url} sent more than ${String(MAX_PAGES)} ${method} pages`);
+}
 const ToolsListResult = type({ tools: McpToolSchema.array() });
-/** `tools/list`: the remote server's tool catalog. */
+/** `tools/list`: the remote server's tool catalog, following cursors. */
 export async function mcpListTools(url, opts = {}) {
-    const { result } = await sendRequest(url, "tools/list", undefined, opts);
-    const parsed = ToolsListResult(result);
-    if (parsed instanceof type.errors) {
-        throw new McpError(`MCP server ${url} sent a malformed tools/list result: ${parsed.summary}`);
+    const { pages, cache } = await eachPage(url, "tools/list", undefined, opts);
+    const tools = [];
+    for (const result of pages) {
+        const parsed = ToolsListResult(result);
+        if (parsed instanceof type.errors) {
+            throw new McpError(`MCP server ${url} sent a malformed tools/list result: ${parsed.summary}`);
+        }
+        for (const tool of parsed.tools) {
+            if (collectHeaders(tool.inputSchema, tool.name) === undefined)
+                continue;
+            tools.push(tool);
+        }
     }
-    const names = new Set(parsed.tools.map((tool) => tool.name));
-    if (names.size !== parsed.tools.length) {
+    const names = new Set(tools.map((tool) => tool.name));
+    if (names.size !== tools.length) {
         throw new McpError(`MCP server ${url} sent a tools/list result with duplicate tool names`);
     }
-    return parsed.tools;
+    return attachCache(tools, cache);
 }
 /** `tools/call`: invoke a remote tool by name with JSON arguments. */
-const ToolCallResult = type({
-    content: "unknown",
-    "isError?": "boolean",
-});
 export async function mcpCallTool(url, name, toolArguments, opts = {}) {
-    const { result } = await sendRequest(url, "tools/call", { name, arguments: toolArguments }, opts);
+    const params = { name, arguments: toolArguments };
+    const result = await requestResult(url, "tools/call", params, opts);
+    if (isInputRequired(result) || isTaskHandle(result))
+        return result;
     const parsed = ToolCallResult(result);
     if (parsed instanceof type.errors) {
         throw new McpError(`MCP server ${url} sent a malformed tools/call result for ${name}: ${parsed.summary}`);
     }
+    return {
+        resultType: "complete",
+        content: parsed.content,
+        ...(parsed.isError !== undefined ? { isError: parsed.isError } : {}),
+        ...(parsed.structuredContent !== undefined
+            ? { structuredContent: parsed.structuredContent }
+            : {}),
+        ...(parsed._meta !== undefined ? { _meta: parsed._meta } : {}),
+    };
+}
+/** Retry a call that came back `input_required`, echoing `requestState`. */
+export async function mcpContinue(url, pending, inputResponses, opts = {}) {
+    const params = { ...pending.params, inputResponses };
+    if (pending.requestState !== undefined)
+        params.requestState = pending.requestState;
+    else
+        delete params.requestState;
+    if (pending.method === "tools/call") {
+        return continueMethod(url, pending.method, params, opts, (value) => {
+            const parsed = ToolCallResult(value);
+            if (parsed instanceof type.errors) {
+                throw new McpError(`MCP server ${url} sent a malformed tools/call result: ${parsed.summary}`);
+            }
+            return {
+                resultType: "complete",
+                content: parsed.content,
+                ...(parsed.isError !== undefined ? { isError: parsed.isError } : {}),
+                ...(parsed.structuredContent !== undefined
+                    ? { structuredContent: parsed.structuredContent }
+                    : {}),
+                ...(parsed._meta !== undefined ? { _meta: parsed._meta } : {}),
+            };
+        });
+    }
+    if (pending.method === "prompts/get") {
+        return continueMethod(url, pending.method, params, opts, (value) => {
+            const parsed = PromptResult(value);
+            if (parsed instanceof type.errors) {
+                throw new McpError(`MCP server ${url} sent a malformed prompts/get result: ${parsed.summary}`);
+            }
+            return completePrompt(parsed);
+        });
+    }
+    if (pending.method === "resources/read") {
+        return continueMethod(url, pending.method, params, opts, (value) => completeRead(value, url));
+    }
+    throw new McpError(`cannot retry ${pending.method}`);
+}
+async function continueMethod(url, method, params, opts, complete) {
+    const result = await requestResult(url, method, params, opts);
+    if (isInputRequired(result) || isTaskHandle(result))
+        return result;
+    return complete(result);
+}
+function completePrompt(parsed) {
+    return {
+        resultType: "complete",
+        messages: parsed.messages,
+        ...(parsed.description !== undefined
+            ? { description: parsed.description }
+            : {}),
+        ...(parsed._meta !== undefined ? { _meta: parsed._meta } : {}),
+    };
+}
+/** `prompts/list`, following cursors. */
+export async function mcpListPrompts(url, opts = {}) {
+    const { pages, cache } = await eachPage(url, "prompts/list", undefined, opts);
+    const prompts = [];
+    for (const result of pages) {
+        const parsed = type({ prompts: PromptSchema.array() })(result);
+        if (parsed instanceof type.errors) {
+            throw new McpError(`MCP server ${url} sent a malformed prompts/list result: ${parsed.summary}`);
+        }
+        prompts.push(...parsed.prompts);
+    }
+    return attachCache(prompts, cache);
+}
+/** `prompts/get`. */
+export async function mcpGetPrompt(url, name, args, opts = {}) {
+    const params = { name };
+    if (args !== undefined)
+        params.arguments = args;
+    return continueMethod(url, "prompts/get", params, opts, (result) => {
+        const parsed = PromptResult(result);
+        if (parsed instanceof type.errors) {
+            throw new McpError(`MCP server ${url} sent a malformed prompts/get result: ${parsed.summary}`);
+        }
+        return completePrompt(parsed);
+    });
+}
+function completeRead(result, url) {
+    const parsed = type({
+        contents: "unknown[]",
+        "_meta?": "Record<string, unknown>",
+    })(result);
+    if (parsed instanceof type.errors) {
+        throw new McpError(`MCP server ${url} sent a malformed resources/read result: ${parsed.summary}`);
+    }
+    const cache = readCache(result, url, "resources/read");
+    return {
+        resultType: "complete",
+        contents: parsed.contents,
+        ...(parsed._meta !== undefined ? { _meta: parsed._meta } : {}),
+        ...(cache.ttlMs !== undefined ? { ttlMs: cache.ttlMs } : {}),
+        ...(cache.cacheScope !== undefined ? { cacheScope: cache.cacheScope } : {}),
+    };
+}
+/** `resources/list`, following cursors. */
+export async function mcpListResources(url, opts = {}) {
+    const { pages, cache } = await eachPage(url, "resources/list", undefined, opts);
+    const resources = [];
+    for (const result of pages) {
+        const parsed = type({ resources: ResourceSchema.array() })(result);
+        if (parsed instanceof type.errors) {
+            throw new McpError(`MCP server ${url} sent a malformed resources/list result: ${parsed.summary}`);
+        }
+        resources.push(...parsed.resources);
+    }
+    return attachCache(resources, cache);
+}
+/** `resources/read`. */
+export async function mcpReadResource(url, uri, opts = {}) {
+    return continueMethod(url, "resources/read", { uri }, opts, (result) => completeRead(result, url));
+}
+/** `resources/templates/list`, following cursors. */
+export async function mcpListResourceTemplates(url, opts = {}) {
+    const { pages, cache } = await eachPage(url, "resources/templates/list", undefined, opts);
+    const templates = [];
+    for (const result of pages) {
+        const parsed = type({ resourceTemplates: TemplateSchema.array() })(result);
+        if (parsed instanceof type.errors) {
+            throw new McpError(`MCP server ${url} sent a malformed resources/templates/list result: ${parsed.summary}`);
+        }
+        templates.push(...parsed.resourceTemplates);
+    }
+    return attachCache(templates, cache);
+}
+/** `completion/complete`. */
+export async function mcpComplete(url, ref, argument, opts = {}) {
+    const params = { ref, argument };
+    if (opts.context !== undefined)
+        params.context = { arguments: opts.context };
+    const result = await requestResult(url, "completion/complete", params, opts);
+    if (isInputRequired(result) || isTaskHandle(result)) {
+        throw new McpError(`MCP server ${url} sent ${result.resultType} for completion/complete`);
+    }
+    const parsed = CompletionResult(result);
+    if (parsed instanceof type.errors) {
+        throw new McpError(`MCP server ${url} sent a malformed completion/complete result: ${parsed.summary}`);
+    }
     return parsed;
 }
+/** Extension methods and the listen stream are 2026-only. A missing session
+ * still speaks 2026; a legacy session does not. */
+function asModern(opts) {
+    if (opts.session === undefined) {
+        return {
+            ...opts,
+            session: {
+                protocolVersion: MCP_PROTOCOL_VERSION,
+                clientCapabilities: clientCapabilities(opts),
+                ...(opts.extensions !== undefined && opts.extensions.length > 0
+                    ? { extensions: opts.extensions }
+                    : {}),
+                ...(opts.uiMimeTypes !== undefined
+                    ? { uiMimeTypes: opts.uiMimeTypes }
+                    : {}),
+            },
+        };
+    }
+    if (!isModernSession(opts.session)) {
+        throw new McpError(`this method requires protocol ${MCP_PROTOCOL_VERSION}`);
+    }
+    return opts;
+}
+function subscriptionParams(filter) {
+    const notifications = {};
+    if (filter.toolsListChanged !== undefined) {
+        notifications.toolsListChanged = filter.toolsListChanged;
+    }
+    if (filter.promptsListChanged !== undefined) {
+        notifications.promptsListChanged = filter.promptsListChanged;
+    }
+    if (filter.resourcesListChanged !== undefined) {
+        notifications.resourcesListChanged = filter.resourcesListChanged;
+    }
+    if (filter.resourceSubscriptions !== undefined) {
+        notifications.resourceSubscriptions = [...filter.resourceSubscriptions];
+    }
+    if (filter.taskIds !== undefined)
+        notifications.taskIds = [...filter.taskIds];
+    return { notifications };
+}
+function asNotification(message) {
+    const meta = message.params?._meta;
+    let subscriptionId;
+    if (typeof meta === "object" && meta !== null) {
+        const id = meta[META_SUBSCRIPTION];
+        if (typeof id === "string" || typeof id === "number")
+            subscriptionId = id;
+    }
+    return {
+        method: message.method,
+        ...(message.params !== undefined ? { params: message.params } : {}),
+        ...(subscriptionId !== undefined ? { subscriptionId } : {}),
+    };
+}
+/**
+ * `subscriptions/listen`. Resolves when the server closes the stream with a
+ * result after acknowledgement, or rejects when `signal` aborts and closes
+ * the stream. Long-lived by default; timeoutMs explicitly bounds its lifetime.
+ */
+export async function mcpListen(url, filter, onNotification, opts = {}) {
+    if (filter.taskIds !== undefined)
+        requireExtension(opts, MCP_EXT_TASKS);
+    const callOpts = asModern(opts);
+    const fetchImpl = callOpts.fetch ?? fetch;
+    const id = nextId++;
+    const bodyParams = modernParams(subscriptionParams(filter), callOpts, id);
+    validateRequest("subscriptions/listen", bodyParams, validationContext(callOpts));
+    const progressToken = record(bodyParams._meta).progressToken;
+    const timeout = callOpts.timeoutMs === undefined
+        ? undefined
+        : AbortSignal.timeout(callOpts.timeoutMs);
+    const signals = [timeout, opts.signal].filter((s) => s !== undefined);
+    const signal = signals.length > 0 ? AbortSignal.any(signals) : undefined;
+    reserveProgressToken(progressToken);
+    try {
+        const response = await fetchImpl(url, {
+            method: "POST",
+            headers: requestHeaders(callOpts, "subscriptions/listen", undefined, {}),
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id,
+                method: "subscriptions/listen",
+                params: bodyParams,
+            }),
+            ...(signal !== undefined ? { signal } : {}),
+        });
+        if (!response.ok)
+            throw await errorFrom(response, url, "subscriptions/listen", signal);
+        const contentType = response.headers.get("content-type") ?? "";
+        let acknowledged;
+        const finish = (message) => {
+            const parsed = JsonRpcResponse(message);
+            if (parsed instanceof type.errors ||
+                !isResponseTo(message, id) ||
+                (parsed.error !== undefined && Object.hasOwn(parsed, "result"))) {
+                throw new McpError(`MCP server ${url} sent a malformed response to subscriptions/listen`);
+            }
+            if (parsed.error !== undefined) {
+                throw new McpError(`MCP server ${url} rejected subscriptions/listen: ${parsed.error.message}`, undefined, parsed.error.code, parsed.error.data, { source: "peer" });
+            }
+            if (acknowledged === undefined)
+                throw new McpError("subscription result preceded acknowledgement");
+            const result = validateResult("subscriptions/listen", parsed.result, validationContext(callOpts));
+            const metadata = result._meta;
+            if (metadata?.[META_SUBSCRIPTION] !== id)
+                throw new McpError("subscription result has mismatched subscriptionId");
+        };
+        if (!contentType.includes("text/event-stream")) {
+            finish(parseJson(await readCapped(response, signal)));
+            return;
+        }
+        for await (const message of sseMessages(response, signal)) {
+            if (isNotification(message)) {
+                validateNotification(message.method, message.params, validationContext(callOpts));
+                const notification = asNotification(message);
+                if (notification.subscriptionId !== id)
+                    throw new McpError("subscription notification has mismatched subscriptionId");
+                if (message.method === "notifications/subscriptions/acknowledged") {
+                    if (acknowledged !== undefined)
+                        throw new McpError("duplicate subscription acknowledgement");
+                    acknowledged = message.params?.notifications;
+                    for (const [key, value] of Object.entries(acknowledged)) {
+                        const requested = filter[key];
+                        if (Array.isArray(value)
+                            ? !Array.isArray(requested) ||
+                                value.some((item) => !requested.includes(item))
+                            : value === true && requested !== true)
+                            throw new McpError("subscription acknowledged an unrequested filter");
+                    }
+                }
+                else {
+                    if (acknowledged === undefined)
+                        throw new McpError("subscription notification preceded acknowledgement");
+                    const keys = {
+                        "notifications/tools/list_changed": "toolsListChanged",
+                        "notifications/prompts/list_changed": "promptsListChanged",
+                        "notifications/resources/list_changed": "resourcesListChanged",
+                    };
+                    const key = keys[message.method];
+                    const allowed = key !== undefined
+                        ? acknowledged[key] === true
+                        : message.method === "notifications/resources/updated"
+                            ? Array.isArray(acknowledged.resourceSubscriptions) &&
+                                acknowledged.resourceSubscriptions.includes(message.params?.uri)
+                            : message.method === "notifications/tasks"
+                                ? Array.isArray(acknowledged.taskIds) &&
+                                    acknowledged.taskIds.includes(message.params?.taskId)
+                                : false;
+                    if (!allowed)
+                        throw new McpError("unrequested subscription notification");
+                }
+                onNotification(notification);
+                continue;
+            }
+            if (isResponseTo(message, id)) {
+                finish(message);
+                return;
+            }
+        }
+        throw new McpError("MCP server closed the event stream without a matching response");
+    }
+    catch (cause) {
+        if (opts.signal?.aborted === true) {
+            throw new McpError(`subscriptions/listen to MCP server ${url} was cancelled`, undefined, undefined, undefined, { cancelled: true });
+        }
+        if (timeout?.aborted === true) {
+            throw new McpError(`MCP server ${url} did not answer subscriptions/listen within ${String(callOpts.timeoutMs)}ms`, undefined, undefined, undefined, { timedOut: true });
+        }
+        throw cause;
+    }
+    finally {
+        if (progressToken !== undefined)
+            activeProgressTokens.delete(progressToken);
+    }
+}
+function parseTaskState(result, _url, _method) {
+    return { ...validateTask(result, true), resultType: "complete" };
+}
+/** `tasks/get`. Requires the tasks extension. */
+export async function mcpGetTask(url, taskId, opts = {}) {
+    requireExtension(opts, MCP_EXT_TASKS);
+    const result = await requestResult(url, "tasks/get", { taskId }, asModern(opts));
+    if (isInputRequired(result) || isTaskHandle(result)) {
+        throw new McpError(`MCP server ${url} sent ${result.resultType} for tasks/get`);
+    }
+    return parseTaskState(result, url, "tasks/get");
+}
+/** `tasks/update`. Requires the tasks extension. */
+export async function mcpUpdateTask(url, taskId, inputResponses, opts = {}) {
+    requireExtension(opts, MCP_EXT_TASKS);
+    const result = await requestResult(url, "tasks/update", { taskId, inputResponses }, asModern(opts));
+    if (isInputRequired(result) || isTaskHandle(result)) {
+        throw new McpError(`MCP server ${url} sent ${result.resultType} for tasks/update`);
+    }
+}
+/** `tasks/cancel`. Requires the tasks extension. Cooperative: the server only acknowledges. */
+export async function mcpCancelTask(url, taskId, opts = {}) {
+    requireExtension(opts, MCP_EXT_TASKS);
+    const result = await requestResult(url, "tasks/cancel", { taskId }, asModern(opts));
+    if (isInputRequired(result) || isTaskHandle(result)) {
+        throw new McpError(`MCP server ${url} sent ${result.resultType} for tasks/cancel`);
+    }
+}
+function requireSkills(opts) {
+    requireExtension(opts, MCP_EXT_SKILLS);
+    const extensions = opts.session?.capabilities?.extensions;
+    if (typeof extensions !== "object" ||
+        extensions === null ||
+        !Object.hasOwn(extensions, MCP_EXT_SKILLS)) {
+        throw new McpError("server has not declared the skills extension; discover before calling skills methods");
+    }
+}
+/** `skills/list`, following cursors. Requires the skills extension. */
+export async function mcpListSkills(url, opts = {}) {
+    requireSkills(opts);
+    const { pages, cache } = await eachPage(url, "skills/list", undefined, asModern(opts));
+    const skills = [];
+    for (const result of pages) {
+        const parsed = type({ skills: SkillSchema.array() })(result);
+        if (parsed instanceof type.errors) {
+            throw new McpError(`MCP server ${url} sent a malformed skills/list result: ${parsed.summary}`);
+        }
+        skills.push(...parsed.skills);
+    }
+    return attachCache(skills, cache);
+}
+/** `skills/get`. Requires the skills extension. */
+export async function mcpGetSkill(url, uri, opts = {}) {
+    requireSkills(opts);
+    const result = await requestResult(url, "skills/get", { uri }, asModern(opts));
+    if (isInputRequired(result) || isTaskHandle(result)) {
+        throw new McpError(`MCP server ${url} sent ${result.resultType} for skills/get`);
+    }
+    const parsed = type({ skill: SkillSchema })(result);
+    if (parsed instanceof type.errors) {
+        throw new McpError(`MCP server ${url} sent a malformed skills/get result: ${parsed.summary}`);
+    }
+    const cache = readCache(result, url, "skills/get");
+    return {
+        resultType: "complete",
+        skill: parsed.skill,
+        ...(cache.ttlMs !== undefined ? { ttlMs: cache.ttlMs } : {}),
+        ...(cache.cacheScope !== undefined ? { cacheScope: cache.cacheScope } : {}),
+    };
+}
+function directoryReadEnabled(session) {
+    const capabilities = session?.capabilities;
+    if (typeof capabilities !== "object" || capabilities === null)
+        return false;
+    const extensions = capabilities.extensions;
+    if (typeof extensions !== "object" || extensions === null)
+        return false;
+    const skills = extensions[MCP_EXT_SKILLS];
+    if (typeof skills !== "object" || skills === null)
+        return false;
+    return skills.directoryRead === true;
+}
+/**
+ * `resources/directory/read`. Sent only when the skills extension is enabled
+ * and the server declared `directoryRead`.
+ */
+export async function mcpReadResourceDirectory(url, uri, opts = {}) {
+    requireSkills(opts);
+    const modern = asModern(opts);
+    if (!directoryReadEnabled(modern.session)) {
+        throw new McpError(`MCP server did not declare ${MCP_EXT_SKILLS} directoryRead`);
+    }
+    const { pages, cache } = await eachPage(url, "resources/directory/read", { uri }, modern);
+    const resources = [];
+    for (const result of pages) {
+        const parsed = type({ resources: ResourceSchema.array() })(result);
+        if (parsed instanceof type.errors) {
+            throw new McpError(`MCP server ${url} sent a malformed resources/directory/read result: ${parsed.summary}`);
+        }
+        resources.push(...parsed.resources);
+    }
+    return attachCache(resources, cache);
+}