@wrongstack/mcp 1.0.19 → 1.0.26

package/dist/contracts.d.ts

@@ -18,11 +18,32 @@ export interface MCPTool {
     name: string;
     description?: string | undefined;
     inputSchema: Record<string, unknown>;
+    /** JSON Schema of the tool's `structuredContent` (spec 2025-06-18). */
+    outputSchema?: Record<string, unknown> | undefined;
+}
+/**
+ * URL-mode elicitation (spec 2025-11-25): the server asks the user to open a
+ * web page for something that must not pass through the client — a
+ * third-party sign-in, an API key, a payment. Only the user's consent crosses
+ * the protocol; what happens on the page stays between the user and the server.
+ */
+export interface UrlElicitation {
+    mode: 'url';
+    message: string;
+    url: string;
+    elicitationId: string;
 }
 /** Result envelope returned by an MCP `tools/call`. */
 export interface ToolCallResult {
     content: unknown;
     isError: boolean;
+    /** The typed result object, when the tool returns one (spec 2025-06-18). */
+    structuredContent?: Record<string, unknown> | undefined;
+    /**
+     * Pages the user must open before the call can succeed: the server answered
+     * with a URL-elicitation-required error (`-32042`, spec 2025-11-25).
+     */
+    urlElicitations?: UrlElicitation[] | undefined;
 }
 /** JSON-RPC 2.0 response shape (success or error). */
 export interface JsonRpcResponse {

package/dist/elicitation-form.d.ts

@@ -0,0 +1,26 @@
+import { type ElicitationRequester, type MCPElicitationRequest, type MCPElicitationResult } from './elicitation.js';
+/** Opens a page in the user's browser; given by a host that can. */
+export type OpenUrl = (url: string) => void;
+export interface ElicitViaUserInputOptions {
+    /**
+     * Opens a URL-mode page once the user agrees. Without it the user is only
+     * shown the URL to open themselves (the right thing when the browser is on
+     * another machine than this process).
+     */
+    openUrl?: OpenUrl | undefined;
+}
+/**
+ * Put a server's elicitation in front of the user as a `clarify`-style form on
+ * the run that made the call (or `fallback` when the server asks outside a
+ * call), and turn the answers back into schema-checked content.
+ *
+ * No surface to show it on answers `cancel`; the user dismissing the form is an
+ * explicit `decline`. An answer the schema rejects is asked again with the
+ * reason, a few times, before giving up.
+ *
+ * A URL-mode request asks for consent to open a page instead. Nothing is
+ * fetched or opened before the user agrees, and `accept` then only means they
+ * agreed: the page's outcome reaches the server, not this client.
+ */
+export declare function elicitViaUserInput(request: MCPElicitationRequest, fallback?: ElicitationRequester | undefined, options?: ElicitViaUserInputOptions): Promise<MCPElicitationResult>;
+//# sourceMappingURL=elicitation-form.d.ts.map

package/dist/elicitation.d.ts

@@ -0,0 +1,151 @@
+import type { UserInputRequest, UserInputResponse } from '@wrongstack/core/types';
+import type { UrlElicitation } from './contracts.js';
+export type { UrlElicitation };
+/**
+ * MCP elicitation (`elicitation/create`, client feature since 2025-06-18): a
+ * server asks the user for a small, flat form of values mid-operation.
+ *
+ * The requested schema is deliberately restricted by the spec to a flat object
+ * of primitive properties, so it is parsed into a list of typed fields here and
+ * anything richer is refused as invalid params instead of half-rendered.
+ */
+export type ElicitationValue = string | number | boolean | string[];
+export interface ElicitationOption {
+    value: string;
+    label: string;
+}
+interface ElicitationFieldBase {
+    name: string;
+    title?: string | undefined;
+    description?: string | undefined;
+    required: boolean;
+}
+export type ElicitationField = (ElicitationFieldBase & {
+    kind: 'string';
+    minLength?: number | undefined;
+    maxLength?: number | undefined;
+    format?: string | undefined;
+    default?: string | undefined;
+}) | (ElicitationFieldBase & {
+    kind: 'number' | 'integer';
+    minimum?: number | undefined;
+    maximum?: number | undefined;
+    default?: number | undefined;
+}) | (ElicitationFieldBase & {
+    kind: 'boolean';
+    default?: boolean | undefined;
+}) | (ElicitationFieldBase & {
+    kind: 'enum';
+    options: ElicitationOption[];
+    default?: string | undefined;
+}) | (ElicitationFieldBase & {
+    kind: 'multi-enum';
+    options: ElicitationOption[];
+    minItems?: number | undefined;
+    maxItems?: number | undefined;
+    default?: string[] | undefined;
+});
+export interface ElicitationForm {
+    message: string;
+    fields: ElicitationField[];
+}
+/** What a server can put in front of the user: a form, or a page to open. */
+export type ElicitationPrompt = (ElicitationForm & {
+    mode?: 'form' | undefined;
+}) | UrlElicitation;
+export type MCPElicitationResult = {
+    action: 'accept';
+    content: Record<string, ElicitationValue>;
+} | {
+    action: 'decline';
+} | {
+    action: 'cancel';
+};
+/** The slice of a tool call's run context that can put a form in front of its user. */
+export interface ElicitationRequester {
+    requestUserInput(request: UserInputRequest, signal?: AbortSignal): Promise<UserInputResponse | undefined>;
+}
+/** What a host sees: the form or page, which server asks, and the run that caused it. */
+export type MCPElicitationRequest = ElicitationPrompt & {
+    server: string;
+    /**
+     * Context of the newest in-flight tool call to this server, when there is
+     * one — the run whose user should answer. Undefined when the server asks
+     * outside any tool call.
+     */
+    requester?: ElicitationRequester | undefined;
+    /** Aborts when the server cancels the request, the connection closes, or the wait runs out. */
+    signal: AbortSignal;
+};
+export type MCPElicitationHandler = (request: MCPElicitationRequest) => Promise<MCPElicitationResult>;
+/** The per-connection slice of {@link MCPElicitationHandler} a client is given. */
+export type MCPClientElicitationHandler = (request: ElicitationPrompt & {
+    signal: AbortSignal;
+}) => Promise<MCPElicitationResult>;
+type Parsed<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * A URL-mode request: a web page the user is asked to open. Only `http(s)` is
+ * accepted — the page is handed to the system browser, and a `file:` or
+ * custom-scheme URL would have the operating system run something instead.
+ */
+export declare function parseUrlElicitation(params: unknown): Parsed<UrlElicitation>;
+/**
+ * Check accepted content against the form: every required field present, each
+ * value of its declared kind and within its bounds, nothing the server did not
+ * ask for. Numeric text is coerced so a text box can answer a number field.
+ */
+export declare function validateElicitationContent(fields: readonly ElicitationField[], content: Record<string, unknown>): Parsed<Record<string, ElicitationValue>>;
+type JsonRpcId = number | string;
+export interface ServerRequest {
+    id: JsonRpcId;
+    method: string;
+    params?: unknown;
+}
+export type ServerResponse = {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    result: unknown;
+} | {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    error: {
+        code: number;
+        message: string;
+    };
+};
+/**
+ * Answers the requests an MCP server sends to this client — one per
+ * connection, shared by the stdio, SSE and Streamable HTTP transports so they
+ * cannot drift apart on what the client supports.
+ */
+export declare class ServerRequestResponder {
+    private readonly elicitation?;
+    private readonly pending;
+    constructor(elicitation?: MCPClientElicitationHandler | undefined);
+    /** Client capabilities to declare in `initialize` — only what can be answered. */
+    capabilities(): Record<string, unknown>;
+    /** True while an elicitation waits on the user; request timeouts hold meanwhile. */
+    get awaitingUser(): boolean;
+    answer(request: ServerRequest): Promise<ServerResponse>;
+    /**
+     * Pages a tool call's `-32042` (URL elicitation required) error names, put
+     * to the user one at a time. Returns what the user chose for each; nothing
+     * is opened without their consent, and without a handler every one is
+     * `cancel`.
+     */
+    presentUrl(elicitations: readonly UrlElicitation[], signal: AbortSignal): Promise<Array<{
+        elicitation: UrlElicitation;
+        action: MCPElicitationResult['action'];
+    }>>;
+    /** `notifications/cancelled` from the server: stop waiting for that answer. */
+    cancel(params: unknown): void;
+    /** The connection is gone: abandon every open form. */
+    dispose(): void;
+}
+//# sourceMappingURL=elicitation.d.ts.map

package/dist/index.d.ts

@@ -1,9 +1,14 @@
 export { authorizationHeaderForToken, authorizationServerMetadataUrls, canonicalMcpResource, createMcpAuthorizationRequest, discoverMcpAuthorization, exchangeMcpAuthorizationCode, type MCPAccessToken, type MCPAuthorizationChallenge, type MCPAuthorizationContext, type MCPAuthorizationDiscoveryOptions, type MCPAuthorizationDiscoveryResult, type MCPAuthorizationJsonFetcher, type MCPAuthorizationProvider, type MCPAuthorizationRequestOptions, type MCPAuthorizationServerMetadata, type MCPAuthorizationSession, type MCPProtectedResourceMetadata, type MCPTokenExchangeOptions, type MCPTokenRefreshOptions, type MCPTokenSet, parseAuthorizationServerMetadata, parseMcpAuthorizationCallback, parseMcpBearerChallenge, parseProtectedResourceMetadata, protectedResourceMetadataUrls, refreshMcpAccessToken, validateMcpAuthorizationServerMetadata, } from './authorization.js';
-export { type MCPAuthorizationCompleteInput, MCPAuthorizationManager, type MCPAuthorizationManagerOptions, type MCPAuthorizationStartInput, type MCPAuthorizationStartResult, type MCPAuthorizationStatus, } from './authorization-manager.js';
+export { type MCPOAuthCallbackServer, type MCPOAuthCallbackServerOptions, startMcpOAuthCallbackServer, } from './authorization-callback-server.js';
+export { type MCPAuthorizationCompleteInput, type MCPAuthorizationLoginHandle, type MCPAuthorizationLoginInput, MCPAuthorizationManager, type MCPAuthorizationManagerOptions, type MCPAuthorizationStartInput, type MCPAuthorizationStartResult, type MCPAuthorizationStatus, } from './authorization-manager.js';
+export { type MCPClientRegistration, type MCPClientRegistrationOptions, registerMcpOAuthClient, } from './authorization-registration.js';
 export { MCPClient, type MCPClientOptions, type MCPListChangedListener, type MCPPageOptions, type MCPRequestOptions, type Transport, } from './client.js';
+export { mcpEnvPlaceholders } from './config-env.js';
 export { MCP_CONSTANTS, negotiateProtocolVersion, SUPPORTED_PROTOCOL_VERSIONS, } from './constants.js';
 export { DEFAULT_MCP_INSERTION_MAX_BYTES, DEFAULT_MCP_RESOURCE_SCHEMES, type MCPContentProvenance, type MCPInsertionPolicy, type MCPPromptInsertion, type MCPResourceInsertion, preparePromptInsertion, prepareResourceInsertion, } from './content-selection.js';
 export type { ConnectionState, JsonRpcResponse, MCPTool, ToolCallResult, } from './contracts.js';
+export type { ElicitationField, ElicitationRequester, MCPElicitationHandler, MCPElicitationRequest, MCPElicitationResult, } from './elicitation.js';
+export { elicitViaUserInput } from './elicitation-form.js';
 export { addMcp, disableMcp, discoverMcp, enableMcp, listMcp, MCP_ENV_MASK, type McpManageDeps, type McpOpResult, type McpServerInfo, type McpServerInput, removeMcp, restartMcp, updateMcp, } from './manage.js';
 export { type MCPCapabilityManifest, manifestConfigHash, readCapabilityManifest, readManifest, writeCapabilityManifest, writeManifest, } from './manifest-cache.js';
 export { MCP_OPERATION_LIMITS, type MCPFailureKind, type MCPHealthState, type MCPLatencySummary, type MCPOperationEvent, type MCPOperationKind, type MCPServerOperationalHealth, } from './operations.js';