@corbits/mcp 0.3.0 → 0.4.0

package/dist/auth/login.js

@@ -0,0 +1,175 @@
+import { buildAuthorizeUrl, exchangeCode, generatePkce, generateState, refreshTokenRequest, OAuthDiscoveryError, } from "@corbits/oauth-core";
+import { type } from "arktype";
+import { assertAuthorizationCallbackIssuer, assertCrossOriginAuthorizationIssuer, mcpClientConfig, preferredMcpClientRegistration, readAuthorizationCallback, registerMcpClient, resolveStoredMcpClient, } from "../oauth-discovery.js";
+import { secureOAuthFetch } from "./http.js";
+const Token = type({
+    access_token: "string > 0",
+    token_type: "string",
+    "refresh_token?": "string > 0",
+    "expires_in?": "number >= 0",
+    "scope?": "string",
+});
+function tokensFromResponse(raw, now, previous) {
+    const response = Token(raw);
+    if (response instanceof type.errors ||
+        response.token_type.toLowerCase() !== "bearer")
+        throw new OAuthDiscoveryError("Invalid bearer token response");
+    const refresh = response.refresh_token ?? previous?.refresh;
+    return {
+        access: response.access_token,
+        ...(refresh !== undefined ? { refresh } : {}),
+        ...(response.expires_in !== undefined
+            ? { expiresAt: now + response.expires_in * 1000 }
+            : {}),
+        ...(response.scope !== undefined
+            ? { scope: response.scope }
+            : previous?.scope !== undefined
+                ? { scope: previous.scope }
+                : {}),
+    };
+}
+/** Performs real DCR only when neither issuer-bound pre-registration nor CIMD applies. */
+export async function prepareMcpClient(opts) {
+    const issuer = opts.entry.authorizationServer.issuer;
+    if (opts.storedClient !== undefined) {
+        resolveStoredMcpClient(issuer, opts.storedClient);
+        return { ...opts.storedClient };
+    }
+    const plan = preferredMcpClientRegistration({
+        authorizationServer: opts.entry.authorizationServer,
+        ...(opts.clientMetadataUrl !== undefined
+            ? { clientMetadataUrl: opts.clientMetadataUrl }
+            : {}),
+    });
+    if (plan.mechanism === "client-id-metadata")
+        return { kind: "cimd", clientId: plan.clientId };
+    if (plan.mechanism === "pre-registered")
+        return { kind: "pre-registered", clientId: plan.clientId, issuer };
+    const registered = await registerMcpClient({
+        registrationEndpoint: plan.registrationEndpoint,
+        issuer,
+        redirectUris: [opts.redirectUri],
+        clientName: opts.clientName,
+        ...(opts.applicationType !== undefined
+            ? { applicationType: opts.applicationType }
+            : {}),
+        ...(opts.entry.authorizationServer.grantTypesSupported !== undefined
+            ? {
+                grantTypesSupported: opts.entry.authorizationServer.grantTypesSupported,
+            }
+            : {}),
+        ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+    });
+    return { kind: "dynamic", clientId: registered.clientId, issuer };
+}
+/** A one-use callback session. The host mounts its registered callback route,
+ * passes the full URLSearchParams here, then persists secrets server-side.
+ * Unlike oauth-core BaseTokens this contract permits access-token-only grants.
+ * No automatic tool replay, persistence, browser opening or grant widening. */
+export function createMcpAuthorizationSession(opts) {
+    if (!opts.tenantId || !opts.principalId)
+        throw new OAuthDiscoveryError("Login requires host-bound tenant and principal");
+    const client = resolveStoredMcpClient(opts.entry.authorizationServer.issuer, opts.client);
+    const config = mcpClientConfig(opts.entry, {
+        ...opts.config,
+        clientId: client.clientId,
+    });
+    const pkce = generatePkce();
+    const state = generateState();
+    const now = opts.now ?? Date.now;
+    const expiresAt = now() + (opts.expiresInMs ?? 300_000);
+    const binding = Object.freeze({
+        tenantId: opts.tenantId,
+        principalId: opts.principalId,
+        issuer: opts.entry.authorizationServer.issuer,
+        resource: opts.entry.resourceUrl,
+        clientId: client.clientId,
+    });
+    let consumed = false;
+    let locked = false;
+    let exchanged;
+    const authorizeUrl = new URL(buildAuthorizeUrl(config, pkce, state));
+    if (config.scopes.length === 0)
+        authorizeUrl.searchParams.delete("scope");
+    return {
+        authorizeUrl: authorizeUrl.toString(),
+        binding,
+        cancel() {
+            consumed = true;
+        },
+        async complete(params) {
+            if (consumed || locked || now() >= expiresAt)
+                throw new OAuthDiscoveryError("Authorization session expired or already consumed");
+            if (params.getAll("state").length !== 1 || params.get("state") !== state)
+                throw new OAuthDiscoveryError("Authorization state mismatch");
+            const issuerOptions = {
+                recordedIssuer: binding.issuer,
+                ...(opts.entry.authorizationServer
+                    .authorizationResponseIssParameterSupported !== undefined
+                    ? {
+                        authorizationResponseIssParameterSupported: opts.entry.authorizationServer
+                            .authorizationResponseIssParameterSupported,
+                    }
+                    : {}),
+            };
+            assertAuthorizationCallbackIssuer(params, issuerOptions);
+            assertCrossOriginAuthorizationIssuer(params, opts.entry.authorizationServer);
+            // An authentic terminal denial consumes the one-use session. A code does
+            // not: cancellation during exchange must skip persistence, and a persist
+            // failure must leave the exchanged grant retryable.
+            locked = true;
+            try {
+                if (exchanged === undefined) {
+                    let code;
+                    try {
+                        ({ code } = readAuthorizationCallback(params, issuerOptions));
+                    }
+                    catch (error) {
+                        consumed = true;
+                        throw error;
+                    }
+                    let tokens;
+                    try {
+                        tokens = tokensFromResponse(await exchangeCode(config, code, pkce.verifier, secureOAuthFetch(opts.fetchImpl)), now());
+                    }
+                    catch {
+                        throw new OAuthDiscoveryError("OAuth code exchange failed");
+                    }
+                    if (consumed || now() >= expiresAt)
+                        throw new OAuthDiscoveryError("Authorization session expired or already consumed");
+                    exchanged = tokens;
+                }
+                else if (consumed || now() >= expiresAt)
+                    throw new OAuthDiscoveryError("Authorization session expired or already consumed");
+                await opts.persist(binding, exchanged);
+                consumed = true;
+            }
+            finally {
+                if (!consumed)
+                    locked = false;
+            }
+        },
+    };
+}
+/** Refresh under the same recorded issuer/resource/client binding. */
+export async function refreshMcpOAuthTokens(opts) {
+    const { clientId } = resolveStoredMcpClient(opts.entry.authorizationServer.issuer, opts.client);
+    if (opts.binding.issuer !== opts.entry.authorizationServer.issuer ||
+        opts.binding.resource !== opts.entry.resourceUrl ||
+        opts.binding.clientId !== clientId)
+        throw new OAuthDiscoveryError("OAuth refresh binding mismatch");
+    if (opts.tokens.refresh === undefined)
+        throw new OAuthDiscoveryError("Access-token-only grant requires a new authorization");
+    try {
+        const response = await refreshTokenRequest({
+            clientId,
+            tokenUrl: opts.entry.authorizationServer.tokenEndpoint,
+            resource: opts.binding.resource,
+            tokenTimeoutMs: 30_000,
+        }, opts.tokens.refresh, secureOAuthFetch(opts.fetchImpl));
+        return tokensFromResponse(response, (opts.now ?? Date.now)(), opts.tokens);
+    }
+    catch {
+        throw new OAuthDiscoveryError("OAuth refresh failed");
+    }
+}

package/dist/auth/oauth-http.d.ts

@@ -0,0 +1,6 @@
+import type { FetchLike } from "../protocol/types.js";
+/** Compatibility facade retaining oauth-core error identity for OAuth callers. */
+export declare function assertOAuthUrl(raw: string, issuer?: boolean): URL;
+export declare function assertRedirectUri(raw: string): URL;
+/** Use for every oauth-core token call: its default fetch follows redirects. */
+export declare function secureOAuthFetch(inner?: FetchLike): typeof fetch;

package/dist/auth/oauth-http.js

@@ -0,0 +1,32 @@
+import { OAuthDiscoveryError } from "@corbits/oauth-core";
+import { assertAuthServerUrl, assertAuthRedirectUri, McpAuthUrlError, } from "./url-policy.js";
+function withOAuthError(validate) {
+    try {
+        return validate();
+    }
+    catch (error) {
+        if (error instanceof McpAuthUrlError)
+            throw new OAuthDiscoveryError(error.detail);
+        throw error;
+    }
+}
+/** Compatibility facade retaining oauth-core error identity for OAuth callers. */
+export function assertOAuthUrl(raw, issuer = false) {
+    return withOAuthError(() => assertAuthServerUrl(raw, issuer));
+}
+export function assertRedirectUri(raw) {
+    return withOAuthError(() => assertAuthRedirectUri(raw));
+}
+/** Use for every oauth-core token call: its default fetch follows redirects. */
+export function secureOAuthFetch(inner = globalThis.fetch) {
+    const wrapped = async (input, init) => {
+        assertOAuthUrl(input instanceof Request ? input.url : String(input));
+        const response = await inner(input, { ...init, redirect: "error" });
+        if ((response.status >= 300 && response.status < 400) ||
+            response.redirected) {
+            throw new OAuthDiscoveryError("OAuth endpoint redirect refused");
+        }
+        return response;
+    };
+    return Object.assign(wrapped, { preconnect: globalThis.fetch.preconnect });
+}

package/dist/auth/resource-server.d.ts

@@ -0,0 +1,25 @@
+import { type McpAuthOperation, type McpAuthPolicy, type McpIdentity } from "./contracts.js";
+export type McpResourceServerOptions = {
+    resource: string;
+    resourceMetadataUrl: string;
+    authorizationServers: readonly string[];
+    scopesSupported?: readonly string[];
+    /** Must verify signature/algorithm/key trust or introspection, revocation and
+     * token type. Decoding a JWT is NOT verification. Returns trusted claims,
+     * expiresAt/notBefore in epoch milliseconds, and a host-assigned identity.
+     * Never map identity from unverified request params. */
+    verifyAccessToken(token: string, context: {
+        resource: string;
+        issuers: readonly string[];
+        signal: AbortSignal;
+    }): Promise<unknown>;
+    authorize(identity: McpIdentity, operation: McpAuthOperation): boolean | Promise<boolean>;
+    requiredScopes?(operation: McpAuthOperation): readonly string[];
+    now?: () => number;
+};
+/** No token implementation or public-mode bypass is implied by this seam. */
+export declare function createMcpResourceServerAuth(opts: McpResourceServerOptions): {
+    policy: McpAuthPolicy;
+    metadataResponse(): Response;
+    challenge(status: 401 | 403, scopes?: readonly string[]): Response;
+};

package/dist/auth/resource-server.js

@@ -0,0 +1,94 @@
+import { type } from "arktype";
+import { assertAuthServerUrl } from "./url-policy.js";
+import { validateMcpIdentity, } from "./contracts.js";
+const VerifiedToken = type({
+    issuer: "string > 0",
+    audience: "string[]",
+    expiresAt: "number",
+    "notBefore?": "number",
+    identity: "unknown",
+});
+function quote(value) {
+    if (/[^\x20-\x7e]/.test(value))
+        throw new Error("Invalid authentication challenge value");
+    return `"${value.replace(/["\\]/g, "\\$&")}"`;
+}
+/** No token implementation or public-mode bypass is implied by this seam. */
+export function createMcpResourceServerAuth(opts) {
+    assertAuthServerUrl(opts.resource);
+    assertAuthServerUrl(opts.resourceMetadataUrl);
+    if (opts.authorizationServers.length === 0)
+        throw new Error("At least one authorization server is required");
+    const issuers = Object.freeze([...opts.authorizationServers]);
+    for (const issuer of issuers)
+        assertAuthServerUrl(issuer, true);
+    const policy = {
+        async authenticate(request) {
+            // RFC 6750 bearer use is header-only: query tokens never authenticate.
+            if (new URL(request.url).searchParams.has("access_token"))
+                return null;
+            const match = /^Bearer +([A-Za-z0-9\-._~+/]+=*)$/i.exec(request.headers.get("authorization") ?? "");
+            if (!match?.[1])
+                return null;
+            try {
+                const claims = VerifiedToken(await opts.verifyAccessToken(match[1], {
+                    resource: opts.resource,
+                    issuers,
+                    signal: request.signal,
+                }));
+                if (claims instanceof type.errors)
+                    return null;
+                const now = (opts.now ?? Date.now)();
+                if (!issuers.includes(claims.issuer) ||
+                    !claims.audience.includes(opts.resource) ||
+                    !Number.isFinite(claims.expiresAt) ||
+                    claims.expiresAt <= now ||
+                    (claims.notBefore !== undefined &&
+                        (!Number.isFinite(claims.notBefore) || claims.notBefore > now)))
+                    return null;
+                return validateMcpIdentity(claims.identity);
+            }
+            catch {
+                return null;
+            }
+        },
+        async authorize(identity, operation) {
+            try {
+                const validated = validateMcpIdentity(identity);
+                if (!operation.resource || !operation.action)
+                    return false;
+                const scopes = opts.requiredScopes?.(operation) ?? [];
+                if (!scopes.every((scope) => validated.scopes.includes(scope)))
+                    return false;
+                return (await opts.authorize(validated, operation)) === true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+    return {
+        policy,
+        metadataResponse: () => Response.json({
+            resource: opts.resource,
+            authorization_servers: issuers,
+            ...(opts.scopesSupported !== undefined
+                ? { scopes_supported: [...opts.scopesSupported] }
+                : {}),
+        }),
+        challenge(status, scopes) {
+            const fields = [`resource_metadata=${quote(opts.resourceMetadataUrl)}`];
+            if (status === 403)
+                fields.push('error="insufficient_scope"');
+            if (scopes !== undefined)
+                fields.push(`scope=${quote(scopes.join(" "))}`);
+            return new Response(null, {
+                status,
+                headers: {
+                    "www-authenticate": `Bearer ${fields.join(", ")}`,
+                    "cache-control": "no-store",
+                },
+            });
+        },
+    };
+}

package/dist/auth/url-policy.d.ts

@@ -0,0 +1,10 @@
+/** Neutral URL-policy error. Keep the existing diagnostic name/message, without
+ * loading the optional OAuth implementation solely to construct an exception.
+ * OAuth-facing facades translate this to the actual oauth-core error class. */
+export declare class McpAuthUrlError extends Error {
+    readonly detail: string;
+    constructor(detail: string);
+}
+/** OAuth endpoints have no cleartext exception, including internal hosts. */
+export declare function assertAuthServerUrl(raw: string, issuer?: boolean): URL;
+export declare function assertAuthRedirectUri(raw: string): URL;

package/dist/auth/url-policy.js

@@ -0,0 +1,35 @@
+import { parseMcpEndpoint } from "../url.js";
+/** Neutral URL-policy error. Keep the existing diagnostic name/message, without
+ * loading the optional OAuth implementation solely to construct an exception.
+ * OAuth-facing facades translate this to the actual oauth-core error class. */
+export class McpAuthUrlError extends Error {
+    detail;
+    constructor(detail) {
+        super(`OAuth discovery failed: ${detail}`);
+        this.name = "OAuthDiscoveryError";
+        this.detail = detail;
+    }
+}
+/** OAuth endpoints have no cleartext exception, including internal hosts. */
+export function assertAuthServerUrl(raw, issuer = false) {
+    let url;
+    try {
+        url = parseMcpEndpoint(raw);
+    }
+    catch {
+        throw new McpAuthUrlError("Invalid OAuth URL");
+    }
+    if (url.protocol !== "https:" ||
+        (issuer && (url.search !== "" || raw.includes("?")))) {
+        throw new McpAuthUrlError("OAuth URL must use HTTPS; issuer must not contain a query");
+    }
+    return url;
+}
+export function assertAuthRedirectUri(raw) {
+    try {
+        return parseMcpEndpoint(raw);
+    }
+    catch {
+        throw new McpAuthUrlError("Invalid OAuth redirect URI: HTTPS or loopback HTTP required");
+    }
+}

package/dist/client/resource-budget.d.ts

@@ -0,0 +1 @@
+export { createResourceBudget, type ResourceBudget, } from "../protocol/resource-budget.js";

package/dist/client/resource-budget.js

@@ -0,0 +1 @@
+export { createResourceBudget, } from "../protocol/resource-budget.js";

package/dist/client/transport.d.ts

@@ -0,0 +1,10 @@
+import type { McpClientOptions, McpNotification } from "../client.js";
+import type { McpSubscriptionFilter, McpValidationContext } from "../protocol/types.js";
+export interface McpRequestOptions extends McpClientOptions {
+    validation?: McpValidationContext;
+}
+/** Extensions receive this interface rather than importing the client facade. */
+export interface McpRequestTransport {
+    request(method: string, params?: Record<string, unknown>, options?: McpRequestOptions): Promise<Record<string, unknown>>;
+    listen(filter: McpSubscriptionFilter, observer: (notification: McpNotification) => void, options?: McpRequestOptions): Promise<void>;
+}

package/dist/client/transport.js

@@ -0,0 +1 @@
+export {};

package/dist/client.d.ts

@@ -1,37 +1,116 @@
-import type { FetchLike } from "@intx/harness";
-export declare const McpToolSchema: import("arktype/internal/variants/object.ts").ObjectType<{
-    name: string;
-    inputSchema: Record<string, unknown>;
-    description?: string;
-    annotations?: {
-        readOnlyHint?: boolean;
-        destructiveHint?: boolean;
-        idempotentHint?: boolean;
-        openWorldHint?: boolean;
-    };
-}, {}>;
-export type McpTool = typeof McpToolSchema.infer;
+import { MCP_PROTOCOL_VERSION, type FetchLike, type McpValidationContext, type TaskStatus, type McpSubscriptionFilter } from "./protocol/types.js";
+import { McpError, McpErrorCode } from "./protocol/errors.js";
+import { MCP_EXT_TASKS, MCP_EXT_UI, MCP_EXT_SKILLS } from "./protocol/extensions.js";
+import { McpToolSchema, type McpTool, PromptSchema, ResourceSchema, TemplateSchema, CompletionResult, SkillSchema } from "./protocol/schemas.js";
+import type { McpRequestTransport } from "./client/transport.js";
+export { MCP_PROTOCOL_VERSION, McpError, McpErrorCode, MCP_EXT_TASKS, MCP_EXT_UI, MCP_EXT_SKILLS, McpToolSchema, };
+export type { McpTool, McpSubscriptionFilter };
+export type { McpRequestTransport, McpRequestOptions, } from "./client/transport.js";
+export type McpCacheScope = "public" | "private";
+export type McpToolList = McpTool[] & {
+    ttlMs?: number;
+    cacheScope?: McpCacheScope;
+};
 export interface McpToolResult {
+    /** `"complete"` on a resolved result; absent while the call awaits input
+     * or runs a task. Optional so resolved results keep the previous contract. */
+    resultType?: "complete";
     content: unknown;
     isError?: boolean;
+    structuredContent?: unknown;
+    /** Tool-result metadata, including MCP Apps `_meta.ui` when the server sent it. */
+    _meta?: Record<string, unknown>;
+}
+export interface McpInputRequired {
+    resultType: "input_required";
+    /** The method to retry. */
+    method: string;
+    /** Original params, without `_meta`, to send again with `inputResponses`. */
+    params: Record<string, unknown>;
+    inputRequests?: Record<string, unknown>;
+    /** Opaque server state. Echoed verbatim on retry; never inspected. */
+    requestState?: string;
+    _meta?: Record<string, unknown>;
+}
+export type McpTaskStatus = TaskStatus;
+export interface McpTaskHandle {
+    resultType: "task";
+    taskId: string;
+    status: McpTaskStatus;
+    createdAt: string;
+    lastUpdatedAt: string;
+    ttlMs: number | null;
+    pollIntervalMs?: number;
+    statusMessage?: string;
+    _meta?: Record<string, unknown>;
+}
+export interface McpTask {
+    resultType: "complete";
+    taskId: string;
+    status: McpTaskStatus;
+    createdAt: string;
+    lastUpdatedAt: string;
+    ttlMs: number | null;
+    pollIntervalMs?: number;
+    statusMessage?: string;
+    inputRequests?: Record<string, unknown>;
+    result?: Record<string, unknown>;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+    _meta?: Record<string, unknown>;
 }
+export type McpToolCallResult = McpToolResult | McpInputRequired | McpTaskHandle;
+export interface McpProgress {
+    progressToken: string | number;
+    progress: number;
+    total?: number;
+    message?: string;
+}
+export type McpClientCapabilities = Record<string, unknown>;
 export interface McpClientOptions {
     /** Injectable `fetch` for tests and mediated-credential handles. */
     fetch?: FetchLike;
-    /** Abort the request, including reading its body, after this long. */
+    /** Abort the request and body after this long (default 60s).
+     * subscriptions/listen has no default deadline; set this to bound its lifetime. */
     timeoutMs?: number;
     /** Abort the request when this fires, e.g. a cancelled tool call. */
     signal?: AbortSignal;
-    /** The session `mcpInitialize` opened; required by stateful servers. */
+    /** The session `mcpConnect` or `mcpInitialize` opened. */
     session?: McpSession;
+    /**
+     * Extension ids to advertise in `clientCapabilities.extensions`.
+     * Unlisted extensions are not advertised and their methods are not sent.
+     */
+    extensions?: readonly string[];
+    /** MIME types advertised for `io.modelcontextprotocol/ui`. */
+    uiMimeTypes?: readonly string[];
+    /** Receives `notifications/progress` from this call's response stream. */
+    onProgress?: (progress: McpProgress) => void;
+    /** Progress token. Defaults to the request id when `onProgress` is set. */
+    progressToken?: string | number;
+    /** Tool `inputSchema`, so `x-mcp-header` parameters are mirrored into headers. */
+    inputSchema?: Record<string, unknown>;
+    /** Validate successful structured tool output when its catalog schema is known. */
+    outputSchema?: Record<string, unknown>;
+    /** resources/read only: bound aggregate decoded text/blob bytes while streaming.
+     * Capped at 16 MiB decoded, with bounded JSON/base64 encoding overhead and
+     * a separate 64 KiB envelope cap. Unbounded reads retain the 4 MiB default. */
+    maxDecodedBytes?: number;
+    /** Optional host capabilities; never inferred from installed code. */
+    clientCapabilities?: McpClientCapabilities;
+    /** Advertise only modes for which the caller has configured user-facing host services. */
+    elicitation?: {
+        form?: boolean;
+        url?: boolean;
+    };
+    validation?: McpValidationContext;
 }
 /** The run-time `tools/call` and `initialize` bound when a caller sets none. */
 export declare const DEFAULT_TIMEOUT_MS = 60000;
-export declare class McpError extends Error {
-    /** The HTTP status, when the server answered with a non-2xx one. */
-    readonly status: number | undefined;
-    constructor(message: string, status?: number);
-}
+export declare function createMcpRequestTransport(url: string, defaults?: McpClientOptions): McpRequestTransport;
 declare const InitializeResult: import("arktype/internal/variants/object.ts").ObjectType<{
     protocolVersion?: string;
     serverInfo?: {
@@ -43,15 +122,118 @@ export type McpServerInfo = typeof InitializeResult.infer;
 export type McpSession = {
     /** The negotiated version, sent as `MCP-Protocol-Version`. */
     readonly protocolVersion: string;
-    /** The `Mcp-Session-Id` a stateful server assigned, if any. */
+    /** The `Mcp-Session-Id` a stateful legacy server assigned, if any. */
     readonly sessionId?: string;
     /** The server's own identification, for a caller that shows it. */
     readonly serverInfo?: NonNullable<McpServerInfo["serverInfo"]>;
+    /** Server capabilities from `server/discover`. Absent on the legacy path. */
+    readonly capabilities?: Record<string, unknown>;
+    /** Capabilities this client advertised for the modern session. */
+    readonly clientCapabilities?: McpClientCapabilities;
+    /** Extension ids opted in when the session was opened. */
+    readonly extensions?: readonly string[];
+    readonly uiMimeTypes?: readonly string[];
+    readonly instructions?: string;
 };
 /** `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 declare function mcpInitialize(url: string, opts?: McpClientOptions): Promise<McpSession>;
-/** `tools/list`: the remote server's tool catalog. */
-export declare function mcpListTools(url: string, opts?: McpClientOptions): Promise<McpTool[]>;
-export declare function mcpCallTool(url: string, name: string, toolArguments: Record<string, unknown>, opts?: McpClientOptions): Promise<McpToolResult>;
-export {};
+/**
+ * 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 declare function mcpConnect(url: string, opts?: McpClientOptions): Promise<McpSession>;
+type PageCache = {
+    ttlMs?: number;
+    cacheScope?: McpCacheScope;
+};
+/** `tools/list`: the remote server's tool catalog, following cursors. */
+export declare function mcpListTools(url: string, opts?: McpClientOptions): Promise<McpToolList>;
+/** `tools/call`: invoke a remote tool by name with JSON arguments. */
+export declare function mcpCallTool(url: string, name: string, toolArguments: Record<string, unknown>, opts?: McpClientOptions): Promise<McpToolCallResult>;
+/** Retry a call that came back `input_required`, echoing `requestState`. */
+export declare function mcpContinue(url: string, pending: McpInputRequired, inputResponses: Record<string, unknown>, opts?: McpClientOptions): Promise<McpToolCallResult | McpPromptResult | McpResourceReadResult>;
+export type McpPrompt = typeof PromptSchema.infer;
+export type McpPromptList = McpPrompt[] & PageCache;
+export type McpPromptResult = {
+    resultType: "complete";
+    description?: string;
+    messages: unknown[];
+    _meta?: Record<string, unknown>;
+} | McpInputRequired | McpTaskHandle;
+/** `prompts/list`, following cursors. */
+export declare function mcpListPrompts(url: string, opts?: McpClientOptions): Promise<McpPromptList>;
+/** `prompts/get`. */
+export declare function mcpGetPrompt(url: string, name: string, args: Record<string, string> | undefined, opts?: McpClientOptions): Promise<McpPromptResult>;
+export type McpResource = typeof ResourceSchema.infer;
+export type McpResourceList = McpResource[] & PageCache;
+export type McpResourceTemplate = typeof TemplateSchema.infer;
+export type McpResourceTemplateList = McpResourceTemplate[] & PageCache;
+export type McpResourceReadResult = {
+    resultType: "complete";
+    contents: unknown[];
+    _meta?: Record<string, unknown>;
+    ttlMs?: number;
+    cacheScope?: McpCacheScope;
+} | McpInputRequired | McpTaskHandle;
+/** `resources/list`, following cursors. */
+export declare function mcpListResources(url: string, opts?: McpClientOptions): Promise<McpResourceList>;
+/** `resources/read`. */
+export declare function mcpReadResource(url: string, uri: string, opts?: McpClientOptions): Promise<McpResourceReadResult>;
+/** `resources/templates/list`, following cursors. */
+export declare function mcpListResourceTemplates(url: string, opts?: McpClientOptions): Promise<McpResourceTemplateList>;
+export type McpCompletion = typeof CompletionResult.infer;
+export type McpCompletionRef = {
+    readonly type: "ref/prompt";
+    readonly name: string;
+} | {
+    readonly type: "ref/resource";
+    readonly uri: string;
+};
+/** `completion/complete`. */
+export declare function mcpComplete(url: string, ref: McpCompletionRef, argument: {
+    name: string;
+    value: string;
+}, opts?: McpClientOptions & {
+    context?: Record<string, string>;
+}): Promise<McpCompletion>;
+export type McpNotification = {
+    method: string;
+    params?: Record<string, unknown>;
+    subscriptionId?: string | number;
+};
+/**
+ * `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 declare function mcpListen(url: string, filter: McpSubscriptionFilter, onNotification: (notification: McpNotification) => void, opts?: McpClientOptions): Promise<void>;
+/** `tasks/get`. Requires the tasks extension. */
+export declare function mcpGetTask(url: string, taskId: string, opts?: McpClientOptions): Promise<McpTask>;
+/** `tasks/update`. Requires the tasks extension. */
+export declare function mcpUpdateTask(url: string, taskId: string, inputResponses: Record<string, unknown>, opts?: McpClientOptions): Promise<void>;
+/** `tasks/cancel`. Requires the tasks extension. Cooperative: the server only acknowledges. */
+export declare function mcpCancelTask(url: string, taskId: string, opts?: McpClientOptions): Promise<void>;
+export type McpSkill = typeof SkillSchema.infer;
+export type McpSkillList = McpSkill[] & PageCache;
+/** `skills/list`, following cursors. Requires the skills extension. */
+export declare function mcpListSkills(url: string, opts?: McpClientOptions): Promise<McpSkillList>;
+export type McpSkillResult = {
+    resultType: "complete";
+    skill: McpSkill;
+    ttlMs?: number;
+    cacheScope?: McpCacheScope;
+};
+/** `skills/get`. Requires the skills extension. */
+export declare function mcpGetSkill(url: string, uri: string, opts?: McpClientOptions): Promise<McpSkillResult>;
+/**
+ * `resources/directory/read`. Sent only when the skills extension is enabled
+ * and the server declared `directoryRead`.
+ */
+export declare function mcpReadResourceDirectory(url: string, uri: string, opts?: McpClientOptions): Promise<McpResourceList>;