@wrongstack/mcp 1.0.33 → 1.0.36

package/dist/client-hosts.d.ts

@@ -0,0 +1,13 @@
+import type { ClientHttpConnectionHost } from './client-http-connection.js';
+import type { MCPClientInternals } from './client-internals.js';
+import type { ClientStdioHost } from './client-stdio.js';
+import type { ClientStdioProtocolHost } from './client-stdio-protocol.js';
+/**
+ * Host views `MCPClient` hands to the transport connectors and the stdio
+ * protocol reader. Every accessor reads/writes the client's live field, so
+ * the delegated code observes the same state the class does.
+ */
+export declare function buildClientHttpConnectionHost(self: MCPClientInternals): ClientHttpConnectionHost;
+export declare function buildClientStdioHost(self: MCPClientInternals): ClientStdioHost;
+export declare function buildClientStdioProtocolHost(self: MCPClientInternals): ClientStdioProtocolHost;
+//# sourceMappingURL=client-hosts.d.ts.map

package/dist/client-http-connection.d.ts

@@ -1,7 +1,7 @@
 import type { MCPClientOptions, ToolsChangedListener } from './client-types.js';
 import type { ConnectionState, MCPTool } from './contracts.js';
 import type { ServerRequestResponder } from './elicitation.js';
-import type { MCPServerMetadata } from './protocol.js';
+import type { MCPLogMessageNotification, MCPProgressNotification, MCPServerMetadata } from './protocol.js';
 import { SSETransport, StreamableHTTPTransport } from './transport.js';
 export interface ClientHttpConnectionHost {
     opts: MCPClientOptions;
@@ -10,9 +10,12 @@ export interface ClientHttpConnectionHost {
     disconnectListeners: Set<() => void>;
     _tools: MCPTool[];
     _toolsCache: MCPTool[] | undefined;
+    readonly toolCatalogVersion: number;
     toolsChangedListeners: Set<ToolsChangedListener>;
     emitCapabilityChanged: (capability: 'resources' | 'prompts') => void;
     emitResourceUpdated: (uri: string) => void;
+    emitProgress: (progress: MCPProgressNotification) => void;
+    emitLogMessage: (log: MCPLogMessageNotification) => void;
     _serverMetadata: MCPServerMetadata | undefined;
     httpTransport: StreamableHTTPTransport | undefined;
     serverRequests: ServerRequestResponder;

package/dist/client-internals.d.ts

@@ -0,0 +1,60 @@
+import type { ChildProcess } from 'node:child_process';
+import type { StringDecoder } from 'node:string_decoder';
+import type { ExitListener, JsonRpcServerRequest, MCPClientOptions, MCPListChangedListener, MCPLogMessageListener, MCPProgressListener, MCPResourceUpdatedListener, ToolsChangedListener } from './client-types.js';
+import type { ConnectionState, JsonRpcResponse, MCPTool } from './contracts.js';
+import type { ServerRequestResponder } from './elicitation.js';
+import type { MCPServerMetadata } from './protocol.js';
+import type { SSETransport, StreamableHTTPTransport } from './transport.js';
+/** One in-flight stdio JSON-RPC call, keyed by id in {@link MCPClientInternals.pending}. */
+export interface PendingStdioRequest {
+    resolve: (res: JsonRpcResponse) => void;
+    reject: (err: Error) => void;
+    timer: NodeJS.Timeout;
+}
+/**
+ * The private state and private methods of `MCPClient`, as seen by the free
+ * functions its method bodies were extracted into (client-hosts,
+ * client-stdio-request, client-lifecycle). The class keeps these members
+ * private to its consumers and hands itself to those functions through this
+ * structural view.
+ */
+export interface MCPClientInternals {
+    readonly opts: MCPClientOptions;
+    state: ConnectionState;
+    child: ChildProcess | undefined;
+    nextId: number;
+    readonly pending: Map<number, PendingStdioRequest>;
+    rxParts: string[];
+    rxBuffer: string;
+    rxBufferBytes: number;
+    rxDecoder: StringDecoder;
+    _tools: MCPTool[];
+    _serverMetadata: MCPServerMetadata | undefined;
+    _toolsCache: MCPTool[] | undefined;
+    _drainPending: boolean;
+    _lastNotifySkipped: boolean;
+    toolCatalogVersion: number;
+    toolCatalogRevision: number;
+    sseTransport: SSETransport | undefined;
+    httpTransport: StreamableHTTPTransport | undefined;
+    readonly exitListeners: Set<ExitListener>;
+    readonly toolsChangedListeners: Set<ToolsChangedListener>;
+    readonly resourcesChangedListeners: Set<MCPListChangedListener>;
+    readonly promptsChangedListeners: Set<MCPListChangedListener>;
+    readonly resourceUpdatedListeners: Set<MCPResourceUpdatedListener>;
+    readonly progressListeners: Set<MCPProgressListener>;
+    readonly logMessageListeners: Set<MCPLogMessageListener>;
+    readonly disconnectListeners: Set<() => void>;
+    readonly serverRequests: ServerRequestResponder;
+    request(method: string, params: unknown, timeoutMs?: number | undefined, opts?: {
+        signal?: AbortSignal | undefined;
+    }): Promise<JsonRpcResponse>;
+    notify(method: string, params: unknown): Promise<void>;
+    failPending(reason: string): void;
+    onData(s: string): void;
+    onLine(line: string): void;
+    close(): Promise<void>;
+    handleServerRequest(request: JsonRpcServerRequest): Promise<void>;
+    handleToolsListChanged(): Promise<void>;
+}
+//# sourceMappingURL=client-internals.d.ts.map

package/dist/client-lifecycle.d.ts

@@ -0,0 +1,22 @@
+import type { MCPClientInternals } from './client-internals.js';
+import type { MCPRequestOptions } from './client-types.js';
+import type { MCPLogMessageNotification, MCPProgressNotification } from './protocol.js';
+/** Invoke every listener with `args`; a throwing listener never stops the rest. */
+export declare function notifyListeners<A extends unknown[]>(listeners: Iterable<(...args: A) => void>, ...args: A): void;
+/** Body of `MCPClient.close()` — stop the stdio child, fail pending calls, close transports. */
+export declare function closeClient(self: MCPClientInternals): Promise<void>;
+/** Body of `MCPClient.requestCapability()` — gate on the advertised capability, then request. */
+export declare function requestCapability<T>(self: MCPClientInternals, capability: 'resources' | 'prompts', method: string, params: unknown, parse: (value: unknown) => T, opts: MCPRequestOptions): Promise<T>;
+export declare function requireResourceSubscriptions(self: MCPClientInternals, method: string): void;
+/**
+ * L2-C: refresh the cached tool list when the server announces a
+ * `tools/list_changed`. Listeners (the registry) re-wrap and
+ * re-register. Failures are swallowed — a stale cache is preferable
+ * to a hard crash on a transient notification glitch.
+ */
+export declare function refreshToolsOnListChanged(self: MCPClientInternals): Promise<void>;
+export declare function emitResourceUpdated(self: MCPClientInternals, uri: string): void;
+export declare function emitProgress(self: MCPClientInternals, progress: MCPProgressNotification): void;
+export declare function emitLogMessage(self: MCPClientInternals, log: MCPLogMessageNotification): void;
+export declare function emitCapabilityChanged(self: MCPClientInternals, capability: 'resources' | 'prompts'): void;
+//# sourceMappingURL=client-lifecycle.d.ts.map

package/dist/client-stdio-protocol.d.ts

@@ -1,6 +1,7 @@
 import type { JsonRpcServerRequest, MCPClientOptions } from './client-types.js';
 import type { JsonRpcResponse } from './contracts.js';
 import type { ServerRequestResponder } from './elicitation.js';
+import { type MCPLogMessageNotification, type MCPProgressNotification } from './protocol.js';
 export interface ClientStdioProtocolHost {
     rxBufferBytes: number;
     rxParts: string[];
@@ -13,6 +14,8 @@ export interface ClientStdioProtocolHost {
     handleToolsListChanged(): Promise<void>;
     emitCapabilityChanged(capability: 'resources' | 'prompts'): void;
     emitResourceUpdated(uri: string): void;
+    emitProgress(progress: MCPProgressNotification): void;
+    emitLogMessage(log: MCPLogMessageNotification): void;
     readonly pending: Map<number, {
         resolve: (res: JsonRpcResponse) => void;
         reject: (err: Error) => void;

package/dist/client-stdio-request.d.ts

@@ -0,0 +1,23 @@
+import type { MCPClientInternals, PendingStdioRequest } from './client-internals.js';
+import type { JsonRpcResponse } from './contracts.js';
+/**
+ * The effective per-request timeout: an explicit positive `timeoutMs` wins,
+ * then the client's configured `requestTimeoutMs`, then the package default.
+ * Capped at the largest timer delay: Node turns a longer one into 1 ms, which
+ * timed out every request to a server configured to "never" time out.
+ */
+export declare function resolveRequestTimeoutMs(configuredMs: number | undefined, timeoutMs: number | undefined): number;
+/**
+ * Send one JSON-RPC request over the stdio child and settle it from the
+ * matching response line (routed by `receiveStdioLine` through `pending`).
+ */
+export declare function sendStdioRequest(self: MCPClientInternals, method: string, params: unknown, effectiveTimeoutMs: number, opts?: {
+    signal?: AbortSignal | undefined;
+}): Promise<JsonRpcResponse>;
+/**
+ * Reject every in-flight stdio request. Used when the underlying
+ * transport dies — without this, callers awaiting `tools/call` over a
+ * killed stdio child or a closed transport would hang indefinitely.
+ */
+export declare function failPendingRequests(pending: Map<number, PendingStdioRequest>, reason: string): void;
+//# sourceMappingURL=client-stdio-request.d.ts.map

package/dist/client-types.d.ts

@@ -1,6 +1,7 @@
 import type { MCPAuthorizationProvider } from './authorization.js';
 import type { MCPTool } from './contracts.js';
 import type { MCPClientElicitationHandler } from './elicitation.js';
+import type { MCPLogMessageNotification, MCPProgressNotification } from './protocol.js';
 export type Transport = 'stdio' | 'sse' | 'streamable-http';
 export interface MCPClientOptions {
     name: string;
@@ -67,4 +68,11 @@ export type ToolsChangedListener = (name: string, tools: MCPTool[]) => void;
 export type MCPListChangedListener = (name: string) => void;
 /** `notifications/resources/updated` — the payload of a live subscription. */
 export type MCPResourceUpdatedListener = (name: string, uri: string) => void;
+/**
+ * `notifications/progress` (2024-11-05 progress utility) — in-flight progress
+ * for a request that carried a `params._meta.progressToken`.
+ */
+export type MCPProgressListener = (name: string, progress: MCPProgressNotification) => void;
+/** `notifications/message` (2024-11-05 logging utility) — a server log line. */
+export type MCPLogMessageListener = (name: string, log: MCPLogMessageNotification) => void;
 //# sourceMappingURL=client-types.d.ts.map

package/dist/client.d.ts

@@ -1,7 +1,8 @@
-import type { ExitListener, MCPClientOptions, MCPListChangedListener, MCPPageOptions, MCPRequestOptions, MCPResourceUpdatedListener, ToolsChangedListener } from './client-types.js';
+import { StringDecoder } from 'node:string_decoder';
+import type { ExitListener, JsonRpcServerRequest, MCPClientOptions, MCPListChangedListener, MCPLogMessageListener, MCPPageOptions, MCPProgressListener, MCPRequestOptions, MCPResourceUpdatedListener, ToolsChangedListener } from './client-types.js';
 import type { ConnectionState, JsonRpcResponse, MCPTool, ToolCallResult } from './contracts.js';
 import { ServerRequestResponder, type UrlElicitation } from './elicitation.js';
-import type { MCPGetPromptResult, MCPListPromptsResult, MCPListResourcesResult, MCPListResourceTemplatesResult, MCPReadResourceResult, MCPServerMetadata } from './protocol.js';
+import { type MCPCompletionReference, type MCPCompletionResult, type MCPGetPromptResult, type MCPListPromptsResult, type MCPListResourcesResult, type MCPListResourceTemplatesResult, type MCPReadResourceResult, type MCPServerMetadata } from './protocol.js';
 export { forceKillTree } from './client-process.js';
 export { quoteWindowsArg } from './client-protocol-helpers.js';
 export type { ConnectionState, JsonRpcResponse, MCPTool, ToolCallResult };
@@ -10,7 +11,7 @@ export declare class MCPClient {
     private readonly capabilityClient;
     private state;
     private child?;
-    private nextId;
+    protected nextId: number;
     /**
      * In-flight JSON-RPC calls keyed by id. `resolve` settles the call; `reject`
      * is invoked from {@link failPending} when the underlying transport dies
@@ -24,9 +25,9 @@ export declare class MCPClient {
      * multi-MiB tools/call result.
      */
     private rxParts;
-    private get rxBuffer();
-    private set rxBuffer(value);
-    private rxBufferBytes;
+    protected get rxBuffer(): string;
+    protected set rxBuffer(value: string);
+    protected rxBufferBytes: number;
     /**
      * Incremental UTF-8 decoder for the stdio rx path. A pipe read boundary can
      * land inside a multi-byte sequence; decoding each chunk with
@@ -34,18 +35,18 @@ export declare class MCPClient {
      * JSON-RPC payload. StringDecoder withholds the partial sequence until the
      * chunk that completes it (same remedy as `readFileHead` in core utils).
      */
-    private rxDecoder;
+    protected rxDecoder: StringDecoder;
     private _tools;
     /** Server-declared handshake metadata. Populated for stdio in the first protocol slice. */
     private _serverMetadata?;
     /** Cached tool list — survives reconnects so the registry can re-register without re-discovering. */
     private _toolsCache?;
-    private _drainPending;
+    protected _drainPending: boolean;
     private _lastNotifySkipped;
     private closePromise?;
     private connectPromise?;
-    private toolCatalogVersion;
-    private toolCatalogRevision;
+    protected toolCatalogVersion: number;
+    protected toolCatalogRevision: number;
     private sseTransport?;
     private httpTransport?;
     /** Notified when the stdio child process exits so the registry can attempt reconnect. */
@@ -55,6 +56,10 @@ export declare class MCPClient {
     private readonly resourcesChangedListeners;
     private readonly promptsChangedListeners;
     private readonly resourceUpdatedListeners;
+    private readonly progressListeners;
+    private readonly logMessageListeners;
+    /** Per-request `progressToken` source for calls that opt into progress. */
+    private progressTokenCounter;
     /** Notified when an HTTP transport (SSE or streamable-http) disconnects. */
     private readonly disconnectListeners;
     /** Answers server→client requests (ping, elicitation) on every transport. */
@@ -85,6 +90,13 @@ export declare class MCPClient {
     callTool(name: string, input: unknown, opts?: {
         signal?: AbortSignal | undefined;
     }): Promise<ToolCallResult>;
+    /**
+     * Fresh `params._meta.progressToken` for a request that opts into
+     * `notifications/progress`. Unique per client, so
+     * `(server name, token)` identifies the in-flight request a progress
+     * notification belongs to.
+     */
+    private nextProgressToken;
     /**
      * Put the pages of a `-32042` tool-call error to the user (consent first,
      * nothing opened without it), on the run whose call got the error.
@@ -97,41 +109,60 @@ export declare class MCPClient {
     unsubscribeResource(uri: string, opts?: MCPRequestOptions): Promise<void>;
     listPrompts(opts?: MCPPageOptions): Promise<MCPListPromptsResult>;
     getPrompt(name: string, args?: Record<string, string> | undefined, opts?: MCPRequestOptions): Promise<MCPGetPromptResult>;
+    /**
+     * Liveness check (MCP `ping`): the server MUST answer promptly with an
+     * empty result. Works on every transport — a cheap connection health probe
+     * before a long call, and the natural reconnect-readiness check.
+     */
+    ping(opts?: MCPRequestOptions): Promise<void>;
+    /**
+     * Argument autocompletion (MCP `completion/complete`, 2024-11-05). The
+     * server must advertise the `completions` capability; an unsupported
+     * server answers with a JSON-RPC error, which surfaces here as a throw.
+     */
+    complete(ref: MCPCompletionReference, argument: {
+        name: string;
+        value: string;
+    }, opts?: MCPRequestOptions): Promise<MCPCompletionResult>;
     close(): Promise<void>;
     private closeInner;
+    /**
+     * This client as the structural view its extracted method bodies take
+     * (see client-internals.ts). Members read only through this view are
+     * `protected` rather than `private` so `noUnusedLocals` sees them as used;
+     * either way they stay hidden from consumers.
+     */
+    private internals;
     private request;
-    private requestCapability;
-    private requireResourceSubscriptions;
     /**
      * Reject every in-flight {@link request} call. Used when the underlying
      * transport dies — without this, callers awaiting `tools/call` over a
      * killed stdio child or a closed transport would hang indefinitely.
      */
-    private failPending;
-    private notify;
-    private onData;
-    private onLine;
-    private handleServerRequest;
+    protected failPending(reason: string): void;
+    protected notify(method: string, params: unknown): Promise<void>;
+    protected onData(s: string): void;
+    protected onLine(line: string): void;
+    protected handleServerRequest(request: JsonRpcServerRequest): Promise<void>;
     /**
      * L2-C: refresh the cached tool list when the server announces a
      * `tools/list_changed`. Listeners (the registry) re-wrap and
      * re-register. Failures are swallowed — a stale cache is preferable
      * to a hard crash on a transient notification glitch.
      */
-    private handleToolsListChanged;
+    protected handleToolsListChanged(): Promise<void>;
     addToolsChangedListener(listener: ToolsChangedListener): void;
     removeToolsChangedListener(listener: ToolsChangedListener): void;
     addResourcesChangedListener(listener: MCPListChangedListener): void;
     removeResourcesChangedListener(listener: MCPListChangedListener): void;
     addResourceUpdatedListener(listener: MCPResourceUpdatedListener): void;
     removeResourceUpdatedListener(listener: MCPResourceUpdatedListener): void;
+    addProgressListener(listener: MCPProgressListener): void;
+    removeProgressListener(listener: MCPProgressListener): void;
+    addLogMessageListener(listener: MCPLogMessageListener): void;
+    removeLogMessageListener(listener: MCPLogMessageListener): void;
     addPromptsChangedListener(listener: MCPListChangedListener): void;
     removePromptsChangedListener(listener: MCPListChangedListener): void;
-    private emitResourceUpdated;
-    private emitCapabilityChanged;
-    private clientHttpConnectionHost;
-    private clientStdioHost;
-    private clientStdioProtocolHost;
 }
 export type { MCPClientOptions, MCPListChangedListener, MCPPageOptions, MCPRequestOptions, MCPResourceUpdatedListener, Transport, } from './client-types.js';
 //# sourceMappingURL=client.d.ts.map

package/dist/constants.d.ts

@@ -14,11 +14,15 @@
  * promise about what the peer may then use.
  *
  * WrongStack speaks the 2024-11-05 shape: tools, resources, prompts,
- * pagination, list_changed, resource subscriptions and cancellation. It does
- * NOT implement sampling (deliberately denied — see below), nor most additions
- * of later revisions: resource links, `completion/complete`, or progress
- * notifications. Listing a newer revision here would advertise capabilities
- * that are not there.
+ * pagination, list_changed, resource subscriptions, cancellation, and
+ * progress notifications (`notifications/progress`, with a
+ * `params._meta.progressToken` sent on every `tools/call`). It does
+ * NOT implement sampling (deliberately denied — see below), nor resource links
+ * (added by a later revision). It is also short of the 2024-11-05 shape
+ * itself in two places: `completion/complete` and client-initiated `ping`
+ * are 2024-11-05 and not implemented/not sent. Those are gaps in the
+ * revision we claim, not deferrals — recorded here so the list is not read
+ * as full conformance.
  *
  * Known drift, accepted: the HTTP layer already implements Streamable HTTP
  * (added 2025-03-26), the `MCP-Protocol-Version` header and OAuth resource
@@ -54,6 +58,46 @@ export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
  * the mismatch.
  */
 export declare function negotiateProtocolVersion(requested: unknown): string;
+/**
+ * Decide which revision to speak *after* a server has answered `initialize`.
+ *
+ * The mirror image of {@link negotiateProtocolVersion}, and the client-side
+ * half of the same handshake rule. A server that cannot honour the revision we
+ * asked for replies with its own latest — which is a statement about the
+ * server, not a grant. Adopting it verbatim (what every transport used to do:
+ * `this.protocolVersion = serverMetadata.protocolVersion`) silently moved us
+ * onto a revision whose semantics we do not implement, and the value was then
+ * echoed back in the `MCP-Protocol-Version` header, so we told the server we
+ * spoke a protocol we were not speaking.
+ *
+ * The revision we claim is ours to keep, never the server's to assign. The
+ * version the server reported stays in `getServerMetadata()` for diagnostics;
+ * it does not drive our requests, and we do not speak it.
+ *
+ * On an unsupported revision this THROWS. `2024-11-05` lifecycle is explicit:
+ * "If the client does not support the version in the server's response, it
+ * SHOULD disconnect." Every transport already unwinds on a connect throw —
+ * `abort()`s its controller and marks `failed`, and `MCPClient.connect` runs
+ * `close()` before rethrowing, which for stdio terminates the child process.
+ * So throwing here IS the disconnect, and the reason is recorded first as a
+ * structured warn line because the generic connect-failure log that follows
+ * would otherwise bury it.
+ */
+export declare function assertSupportedServerProtocolVersion(serverName: string, reported: string): string;
+/**
+ * A refused `initialize` revision, as a type rather than a message pattern.
+ *
+ * The refusal is deterministic — the same server will answer the same way on
+ * every retry — so the registry's connect loop treats it as terminal instead
+ * of spending its remaining attempts (and every later demand-wake) on a
+ * handshake that can never succeed. Match on this class, never on the text.
+ */
+export declare class MCPUnsupportedProtocolVersionError extends Error {
+    readonly serverName: string;
+    readonly reported: string;
+    readonly name = "MCPUnsupportedProtocolVersionError";
+    constructor(serverName: string, reported: string, message: string);
+}
 export declare const MCP_CONSTANTS: Readonly<{
     /** MCP protocol version advertised during handshake: the newest we implement. */
     readonly PROTOCOL_VERSION: string;
@@ -89,8 +133,15 @@ export declare const MCP_CONSTANTS: Readonly<{
         /** How often the idle sweep runs (kept well below the timeout). */
         SWEEP_INTERVAL_MS: 30000;
     }>;
-    /** JSON-RPC response timeout for outstanding requests. */
-    readonly RESPONSE_TIMEOUT_MS: 500;
+    /**
+     * Default per-request timeout for JSON-RPC requests, used when a server
+     * config sets no `requestTimeoutMs`.
+     *
+     * This is the single source for the three fallbacks that each spelled the
+     * same number out inline (the HTTP request-timeout signal, the HTTP
+     * transport's per-request default, and `MCPClient.request`).
+     */
+    readonly REQUEST_TIMEOUT_MS: 60000;
     /** Max buffer size for the SSE reader. */
     readonly SSE_READER_MAX_BUFFER: number;
     /** Max characters logged from a request body. */

package/dist/contracts.d.ts

@@ -13,6 +13,40 @@
 export type ConnectionState = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'failed'
 /** Lazy server: registered from a cached manifest, process not spawned. */
  | 'dormant';
+/**
+ * `ToolAnnotations` — optional properties describing a tool's behaviour, added
+ * in spec 2025-03-26 (PR #185) and unchanged in 2026-07-28.
+ *
+ * Verified against `schema/2025-03-26/schema.ts` and `schema/2026-07-28/schema.ts`:
+ * exactly these five fields, with the spec's own defaults documented below.
+ *
+ * These are the SERVER'S CLAIMS about itself. The spec is explicit that clients
+ * MUST treat annotations as untrusted unless the server is trusted, so this
+ * type is metadata to surface and record — never an input to a permission
+ * decision.
+ */
+export interface MCPToolAnnotations {
+    /** Human-readable title for display purposes. */
+    title?: string | undefined;
+    /** True when the tool does not modify its environment. Spec default: `false`. */
+    readOnlyHint?: boolean | undefined;
+    /**
+     * True when the tool may perform destructive updates; false when it only
+     * makes additive ones. Meaningful only when `readOnlyHint` is false.
+     * Spec default: `true`.
+     */
+    destructiveHint?: boolean | undefined;
+    /**
+     * True when repeating the call with the same arguments has no further
+     * effect. Meaningful only when `readOnlyHint` is false. Spec default: `false`.
+     */
+    idempotentHint?: boolean | undefined;
+    /**
+     * True when the tool interacts with the outside world (network, third-party
+     * APIs) rather than only the local environment. Spec default: `true`.
+     */
+    openWorldHint?: boolean | undefined;
+}
 /** Minimal MCP tool descriptor returned by `tools/list`. */
 export interface MCPTool {
     name: string;
@@ -20,6 +54,8 @@ export interface MCPTool {
     inputSchema: Record<string, unknown>;
     /** JSON Schema of the tool's `structuredContent` (spec 2025-06-18). */
     outputSchema?: Record<string, unknown> | undefined;
+    /** Server-claimed behaviour hints (spec 2025-03-26). Untrusted: display only. */
+    annotations?: MCPToolAnnotations | undefined;
 }
 /**
  * URL-mode elicitation (spec 2025-11-25): the server asks the user to open a

package/dist/index.d.ts

@@ -6,13 +6,13 @@ export { MCPClient, type MCPClientOptions, type MCPListChangedListener, type MCP
 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 { ConnectionState, JsonRpcResponse, MCPTool, MCPToolAnnotations, 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';
-export { type MCPGetPromptResult, type MCPImplementationInfo, type MCPListPromptsResult, type MCPListResourcesResult, type MCPListResourceTemplatesResult, type MCPPrompt, type MCPPromptArgument, type MCPPromptMessage, type MCPReadResourceResult, type MCPResource, type MCPResourceContents, type MCPResourceTemplate, type MCPServerCapabilities, type MCPServerMetadata, parseGetPromptResult, parseListPromptsResult, parseListResourcesResult, parseListResourceTemplatesResult, parseReadResourceResult, parseServerMetadata, } from './protocol.js';
+export { type MCPCompletionReference, type MCPCompletionResult, type MCPGetPromptResult, type MCPImplementationInfo, type MCPListPromptsResult, type MCPListResourcesResult, type MCPListResourceTemplatesResult, type MCPPrompt, type MCPPromptArgument, type MCPPromptMessage, type MCPReadResourceResult, type MCPResource, type MCPResourceContents, type MCPResourceTemplate, type MCPServerCapabilities, type MCPServerMetadata, parseCompletionResult, parseGetPromptResult, parseListPromptsResult, parseListResourcesResult, parseListResourceTemplatesResult, parseReadResourceResult, parseServerMetadata, } from './protocol.js';
 export { MCPRegistry, type MCPRegistryCatalog, type MCPRegistryOptions } from './registry.js';
 export { MCPServer, type MCPServerCallResult, type MCPServerLogger, type MCPServerOptions, type MCPServerPrompt, type MCPServerResource, type MCPServerTool, type MCPServerToolHost, type ServeHttpHandle, type ServeHttpOptions, type ServeStdioHandle, type ServeStdioOptions, serveHttp, serveStdio, toContentBlocks, } from './server.js';
 export { createVaultBackedMcpAuthorizationProviderFactory, type MCPAuthorizationStateEvent, MCPRefreshingAuthorizationProvider, type MCPRefreshingAuthorizationProviderOptions, type MCPStoredAuthorization, type MCPVaultProviderFactoryOptions, MCPVaultTokenStore, } from './token-store.js';