@wrongstack/mcp 1.0.32 → 1.0.35

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,13 @@
1
+ import type { ClientHttpConnectionHost } from './client-http-connection.js';
2
+ import type { MCPClientInternals } from './client-internals.js';
3
+ import type { ClientStdioHost } from './client-stdio.js';
4
+ import type { ClientStdioProtocolHost } from './client-stdio-protocol.js';
5
+ /**
6
+ * Host views `MCPClient` hands to the transport connectors and the stdio
7
+ * protocol reader. Every accessor reads/writes the client's live field, so
8
+ * the delegated code observes the same state the class does.
9
+ */
10
+ export declare function buildClientHttpConnectionHost(self: MCPClientInternals): ClientHttpConnectionHost;
11
+ export declare function buildClientStdioHost(self: MCPClientInternals): ClientStdioHost;
12
+ export declare function buildClientStdioProtocolHost(self: MCPClientInternals): ClientStdioProtocolHost;
13
+ //# sourceMappingURL=client-hosts.d.ts.map
@@ -1,7 +1,7 @@
1
1
  import type { MCPClientOptions, ToolsChangedListener } from './client-types.js';
2
2
  import type { ConnectionState, MCPTool } from './contracts.js';
3
3
  import type { ServerRequestResponder } from './elicitation.js';
4
- import type { MCPServerMetadata } from './protocol.js';
4
+ import type { MCPLogMessageNotification, MCPProgressNotification, MCPServerMetadata } from './protocol.js';
5
5
  import { SSETransport, StreamableHTTPTransport } from './transport.js';
6
6
  export interface ClientHttpConnectionHost {
7
7
  opts: MCPClientOptions;
@@ -13,6 +13,8 @@ export interface ClientHttpConnectionHost {
13
13
  toolsChangedListeners: Set<ToolsChangedListener>;
14
14
  emitCapabilityChanged: (capability: 'resources' | 'prompts') => void;
15
15
  emitResourceUpdated: (uri: string) => void;
16
+ emitProgress: (progress: MCPProgressNotification) => void;
17
+ emitLogMessage: (log: MCPLogMessageNotification) => void;
16
18
  _serverMetadata: MCPServerMetadata | undefined;
17
19
  httpTransport: StreamableHTTPTransport | undefined;
18
20
  serverRequests: ServerRequestResponder;
@@ -0,0 +1,60 @@
1
+ import type { ChildProcess } from 'node:child_process';
2
+ import type { StringDecoder } from 'node:string_decoder';
3
+ import type { ExitListener, JsonRpcServerRequest, MCPClientOptions, MCPListChangedListener, MCPLogMessageListener, MCPProgressListener, MCPResourceUpdatedListener, ToolsChangedListener } from './client-types.js';
4
+ import type { ConnectionState, JsonRpcResponse, MCPTool } from './contracts.js';
5
+ import type { ServerRequestResponder } from './elicitation.js';
6
+ import type { MCPServerMetadata } from './protocol.js';
7
+ import type { SSETransport, StreamableHTTPTransport } from './transport.js';
8
+ /** One in-flight stdio JSON-RPC call, keyed by id in {@link MCPClientInternals.pending}. */
9
+ export interface PendingStdioRequest {
10
+ resolve: (res: JsonRpcResponse) => void;
11
+ reject: (err: Error) => void;
12
+ timer: NodeJS.Timeout;
13
+ }
14
+ /**
15
+ * The private state and private methods of `MCPClient`, as seen by the free
16
+ * functions its method bodies were extracted into (client-hosts,
17
+ * client-stdio-request, client-lifecycle). The class keeps these members
18
+ * private to its consumers and hands itself to those functions through this
19
+ * structural view.
20
+ */
21
+ export interface MCPClientInternals {
22
+ readonly opts: MCPClientOptions;
23
+ state: ConnectionState;
24
+ child: ChildProcess | undefined;
25
+ nextId: number;
26
+ readonly pending: Map<number, PendingStdioRequest>;
27
+ rxParts: string[];
28
+ rxBuffer: string;
29
+ rxBufferBytes: number;
30
+ rxDecoder: StringDecoder;
31
+ _tools: MCPTool[];
32
+ _serverMetadata: MCPServerMetadata | undefined;
33
+ _toolsCache: MCPTool[] | undefined;
34
+ _drainPending: boolean;
35
+ _lastNotifySkipped: boolean;
36
+ toolCatalogVersion: number;
37
+ toolCatalogRevision: number;
38
+ sseTransport: SSETransport | undefined;
39
+ httpTransport: StreamableHTTPTransport | undefined;
40
+ readonly exitListeners: Set<ExitListener>;
41
+ readonly toolsChangedListeners: Set<ToolsChangedListener>;
42
+ readonly resourcesChangedListeners: Set<MCPListChangedListener>;
43
+ readonly promptsChangedListeners: Set<MCPListChangedListener>;
44
+ readonly resourceUpdatedListeners: Set<MCPResourceUpdatedListener>;
45
+ readonly progressListeners: Set<MCPProgressListener>;
46
+ readonly logMessageListeners: Set<MCPLogMessageListener>;
47
+ readonly disconnectListeners: Set<() => void>;
48
+ readonly serverRequests: ServerRequestResponder;
49
+ request(method: string, params: unknown, timeoutMs?: number | undefined, opts?: {
50
+ signal?: AbortSignal | undefined;
51
+ }): Promise<JsonRpcResponse>;
52
+ notify(method: string, params: unknown): Promise<void>;
53
+ failPending(reason: string): void;
54
+ onData(s: string): void;
55
+ onLine(line: string): void;
56
+ close(): Promise<void>;
57
+ handleServerRequest(request: JsonRpcServerRequest): Promise<void>;
58
+ handleToolsListChanged(): Promise<void>;
59
+ }
60
+ //# sourceMappingURL=client-internals.d.ts.map
@@ -0,0 +1,22 @@
1
+ import type { MCPClientInternals } from './client-internals.js';
2
+ import type { MCPRequestOptions } from './client-types.js';
3
+ import type { MCPLogMessageNotification, MCPProgressNotification } from './protocol.js';
4
+ /** Invoke every listener with `args`; a throwing listener never stops the rest. */
5
+ export declare function notifyListeners<A extends unknown[]>(listeners: Iterable<(...args: A) => void>, ...args: A): void;
6
+ /** Body of `MCPClient.close()` — stop the stdio child, fail pending calls, close transports. */
7
+ export declare function closeClient(self: MCPClientInternals): Promise<void>;
8
+ /** Body of `MCPClient.requestCapability()` — gate on the advertised capability, then request. */
9
+ export declare function requestCapability<T>(self: MCPClientInternals, capability: 'resources' | 'prompts', method: string, params: unknown, parse: (value: unknown) => T, opts: MCPRequestOptions): Promise<T>;
10
+ export declare function requireResourceSubscriptions(self: MCPClientInternals, method: string): void;
11
+ /**
12
+ * L2-C: refresh the cached tool list when the server announces a
13
+ * `tools/list_changed`. Listeners (the registry) re-wrap and
14
+ * re-register. Failures are swallowed — a stale cache is preferable
15
+ * to a hard crash on a transient notification glitch.
16
+ */
17
+ export declare function refreshToolsOnListChanged(self: MCPClientInternals): Promise<void>;
18
+ export declare function emitResourceUpdated(self: MCPClientInternals, uri: string): void;
19
+ export declare function emitProgress(self: MCPClientInternals, progress: MCPProgressNotification): void;
20
+ export declare function emitLogMessage(self: MCPClientInternals, log: MCPLogMessageNotification): void;
21
+ export declare function emitCapabilityChanged(self: MCPClientInternals, capability: 'resources' | 'prompts'): void;
22
+ //# sourceMappingURL=client-lifecycle.d.ts.map
@@ -1,6 +1,7 @@
1
1
  import type { JsonRpcServerRequest, MCPClientOptions } from './client-types.js';
2
2
  import type { JsonRpcResponse } from './contracts.js';
3
3
  import type { ServerRequestResponder } from './elicitation.js';
4
+ import { type MCPLogMessageNotification, type MCPProgressNotification } from './protocol.js';
4
5
  export interface ClientStdioProtocolHost {
5
6
  rxBufferBytes: number;
6
7
  rxParts: string[];
@@ -13,6 +14,8 @@ export interface ClientStdioProtocolHost {
13
14
  handleToolsListChanged(): Promise<void>;
14
15
  emitCapabilityChanged(capability: 'resources' | 'prompts'): void;
15
16
  emitResourceUpdated(uri: string): void;
17
+ emitProgress(progress: MCPProgressNotification): void;
18
+ emitLogMessage(log: MCPLogMessageNotification): void;
16
19
  readonly pending: Map<number, {
17
20
  resolve: (res: JsonRpcResponse) => void;
18
21
  reject: (err: Error) => void;
@@ -0,0 +1,21 @@
1
+ import type { MCPClientInternals, PendingStdioRequest } from './client-internals.js';
2
+ import type { JsonRpcResponse } from './contracts.js';
3
+ /**
4
+ * The effective per-request timeout: an explicit positive `timeoutMs` wins,
5
+ * then the client's configured `requestTimeoutMs`, then the package default.
6
+ */
7
+ export declare function resolveRequestTimeoutMs(configuredMs: number | undefined, timeoutMs: number | undefined): number;
8
+ /**
9
+ * Send one JSON-RPC request over the stdio child and settle it from the
10
+ * matching response line (routed by `receiveStdioLine` through `pending`).
11
+ */
12
+ export declare function sendStdioRequest(self: MCPClientInternals, method: string, params: unknown, effectiveTimeoutMs: number, opts?: {
13
+ signal?: AbortSignal | undefined;
14
+ }): Promise<JsonRpcResponse>;
15
+ /**
16
+ * Reject every in-flight stdio request. Used when the underlying
17
+ * transport dies — without this, callers awaiting `tools/call` over a
18
+ * killed stdio child or a closed transport would hang indefinitely.
19
+ */
20
+ export declare function failPendingRequests(pending: Map<number, PendingStdioRequest>, reason: string): void;
21
+ //# sourceMappingURL=client-stdio-request.d.ts.map
@@ -1,6 +1,7 @@
1
1
  import type { MCPAuthorizationProvider } from './authorization.js';
2
2
  import type { MCPTool } from './contracts.js';
3
3
  import type { MCPClientElicitationHandler } from './elicitation.js';
4
+ import type { MCPLogMessageNotification, MCPProgressNotification } from './protocol.js';
4
5
  export type Transport = 'stdio' | 'sse' | 'streamable-http';
5
6
  export interface MCPClientOptions {
6
7
  name: string;
@@ -67,4 +68,11 @@ export type ToolsChangedListener = (name: string, tools: MCPTool[]) => void;
67
68
  export type MCPListChangedListener = (name: string) => void;
68
69
  /** `notifications/resources/updated` — the payload of a live subscription. */
69
70
  export type MCPResourceUpdatedListener = (name: string, uri: string) => void;
71
+ /**
72
+ * `notifications/progress` (2024-11-05 progress utility) — in-flight progress
73
+ * for a request that carried a `params._meta.progressToken`.
74
+ */
75
+ export type MCPProgressListener = (name: string, progress: MCPProgressNotification) => void;
76
+ /** `notifications/message` (2024-11-05 logging utility) — a server log line. */
77
+ export type MCPLogMessageListener = (name: string, log: MCPLogMessageNotification) => void;
70
78
  //# sourceMappingURL=client-types.d.ts.map
package/dist/client.d.ts CHANGED
@@ -1,4 +1,5 @@
1
- import type { ExitListener, MCPClientOptions, MCPListChangedListener, MCPPageOptions, MCPRequestOptions, MCPResourceUpdatedListener, ToolsChangedListener } from './client-types.js';
1
+ import { StringDecoder } from 'node:string_decoder';
2
+ import type { ExitListener, JsonRpcServerRequest, MCPClientOptions, MCPListChangedListener, MCPLogMessageListener, MCPPageOptions, MCPProgressListener, MCPRequestOptions, MCPResourceUpdatedListener, ToolsChangedListener } from './client-types.js';
2
3
  import type { ConnectionState, JsonRpcResponse, MCPTool, ToolCallResult } from './contracts.js';
3
4
  import { ServerRequestResponder, type UrlElicitation } from './elicitation.js';
4
5
  import type { MCPGetPromptResult, MCPListPromptsResult, MCPListResourcesResult, MCPListResourceTemplatesResult, MCPReadResourceResult, MCPServerMetadata } from './protocol.js';
@@ -10,7 +11,7 @@ export declare class MCPClient {
10
11
  private readonly capabilityClient;
11
12
  private state;
12
13
  private child?;
13
- private nextId;
14
+ protected nextId: number;
14
15
  /**
15
16
  * In-flight JSON-RPC calls keyed by id. `resolve` settles the call; `reject`
16
17
  * is invoked from {@link failPending} when the underlying transport dies
@@ -24,9 +25,9 @@ export declare class MCPClient {
24
25
  * multi-MiB tools/call result.
25
26
  */
26
27
  private rxParts;
27
- private get rxBuffer();
28
- private set rxBuffer(value);
29
- private rxBufferBytes;
28
+ protected get rxBuffer(): string;
29
+ protected set rxBuffer(value: string);
30
+ protected rxBufferBytes: number;
30
31
  /**
31
32
  * Incremental UTF-8 decoder for the stdio rx path. A pipe read boundary can
32
33
  * land inside a multi-byte sequence; decoding each chunk with
@@ -34,18 +35,18 @@ export declare class MCPClient {
34
35
  * JSON-RPC payload. StringDecoder withholds the partial sequence until the
35
36
  * chunk that completes it (same remedy as `readFileHead` in core utils).
36
37
  */
37
- private rxDecoder;
38
+ protected rxDecoder: StringDecoder;
38
39
  private _tools;
39
40
  /** Server-declared handshake metadata. Populated for stdio in the first protocol slice. */
40
41
  private _serverMetadata?;
41
42
  /** Cached tool list — survives reconnects so the registry can re-register without re-discovering. */
42
43
  private _toolsCache?;
43
- private _drainPending;
44
+ protected _drainPending: boolean;
44
45
  private _lastNotifySkipped;
45
46
  private closePromise?;
46
47
  private connectPromise?;
47
- private toolCatalogVersion;
48
- private toolCatalogRevision;
48
+ protected toolCatalogVersion: number;
49
+ protected toolCatalogRevision: number;
49
50
  private sseTransport?;
50
51
  private httpTransport?;
51
52
  /** Notified when the stdio child process exits so the registry can attempt reconnect. */
@@ -55,6 +56,10 @@ export declare class MCPClient {
55
56
  private readonly resourcesChangedListeners;
56
57
  private readonly promptsChangedListeners;
57
58
  private readonly resourceUpdatedListeners;
59
+ private readonly progressListeners;
60
+ private readonly logMessageListeners;
61
+ /** Per-request `progressToken` source for calls that opt into progress. */
62
+ private progressTokenCounter;
58
63
  /** Notified when an HTTP transport (SSE or streamable-http) disconnects. */
59
64
  private readonly disconnectListeners;
60
65
  /** Answers server→client requests (ping, elicitation) on every transport. */
@@ -85,6 +90,13 @@ export declare class MCPClient {
85
90
  callTool(name: string, input: unknown, opts?: {
86
91
  signal?: AbortSignal | undefined;
87
92
  }): Promise<ToolCallResult>;
93
+ /**
94
+ * Fresh `params._meta.progressToken` for a request that opts into
95
+ * `notifications/progress`. Unique per client, so
96
+ * `(server name, token)` identifies the in-flight request a progress
97
+ * notification belongs to.
98
+ */
99
+ private nextProgressToken;
88
100
  /**
89
101
  * Put the pages of a `-32042` tool-call error to the user (consent first,
90
102
  * nothing opened without it), on the run whose call got the error.
@@ -99,39 +111,43 @@ export declare class MCPClient {
99
111
  getPrompt(name: string, args?: Record<string, string> | undefined, opts?: MCPRequestOptions): Promise<MCPGetPromptResult>;
100
112
  close(): Promise<void>;
101
113
  private closeInner;
114
+ /**
115
+ * This client as the structural view its extracted method bodies take
116
+ * (see client-internals.ts). Members read only through this view are
117
+ * `protected` rather than `private` so `noUnusedLocals` sees them as used;
118
+ * either way they stay hidden from consumers.
119
+ */
120
+ private internals;
102
121
  private request;
103
- private requestCapability;
104
- private requireResourceSubscriptions;
105
122
  /**
106
123
  * Reject every in-flight {@link request} call. Used when the underlying
107
124
  * transport dies — without this, callers awaiting `tools/call` over a
108
125
  * killed stdio child or a closed transport would hang indefinitely.
109
126
  */
110
- private failPending;
111
- private notify;
112
- private onData;
113
- private onLine;
114
- private handleServerRequest;
127
+ protected failPending(reason: string): void;
128
+ protected notify(method: string, params: unknown): Promise<void>;
129
+ protected onData(s: string): void;
130
+ protected onLine(line: string): void;
131
+ protected handleServerRequest(request: JsonRpcServerRequest): Promise<void>;
115
132
  /**
116
133
  * L2-C: refresh the cached tool list when the server announces a
117
134
  * `tools/list_changed`. Listeners (the registry) re-wrap and
118
135
  * re-register. Failures are swallowed — a stale cache is preferable
119
136
  * to a hard crash on a transient notification glitch.
120
137
  */
121
- private handleToolsListChanged;
138
+ protected handleToolsListChanged(): Promise<void>;
122
139
  addToolsChangedListener(listener: ToolsChangedListener): void;
123
140
  removeToolsChangedListener(listener: ToolsChangedListener): void;
124
141
  addResourcesChangedListener(listener: MCPListChangedListener): void;
125
142
  removeResourcesChangedListener(listener: MCPListChangedListener): void;
126
143
  addResourceUpdatedListener(listener: MCPResourceUpdatedListener): void;
127
144
  removeResourceUpdatedListener(listener: MCPResourceUpdatedListener): void;
145
+ addProgressListener(listener: MCPProgressListener): void;
146
+ removeProgressListener(listener: MCPProgressListener): void;
147
+ addLogMessageListener(listener: MCPLogMessageListener): void;
148
+ removeLogMessageListener(listener: MCPLogMessageListener): void;
128
149
  addPromptsChangedListener(listener: MCPListChangedListener): void;
129
150
  removePromptsChangedListener(listener: MCPListChangedListener): void;
130
- private emitResourceUpdated;
131
- private emitCapabilityChanged;
132
- private clientHttpConnectionHost;
133
- private clientStdioHost;
134
- private clientStdioProtocolHost;
135
151
  }
136
152
  export type { MCPClientOptions, MCPListChangedListener, MCPPageOptions, MCPRequestOptions, MCPResourceUpdatedListener, Transport, } from './client-types.js';
137
153
  //# sourceMappingURL=client.d.ts.map
@@ -14,11 +14,15 @@
14
14
  * promise about what the peer may then use.
15
15
  *
16
16
  * WrongStack speaks the 2024-11-05 shape: tools, resources, prompts,
17
- * pagination, list_changed, resource subscriptions and cancellation. It does
18
- * NOT implement sampling (deliberately denied — see below), nor most additions
19
- * of later revisions: resource links, `completion/complete`, or progress
20
- * notifications. Listing a newer revision here would advertise capabilities
21
- * that are not there.
17
+ * pagination, list_changed, resource subscriptions, cancellation, and
18
+ * progress notifications (`notifications/progress`, with a
19
+ * `params._meta.progressToken` sent on every `tools/call`). It does
20
+ * NOT implement sampling (deliberately denied — see below), nor resource links
21
+ * (added by a later revision). It is also short of the 2024-11-05 shape
22
+ * itself in two places: `completion/complete` and client-initiated `ping`
23
+ * are 2024-11-05 and not implemented/not sent. Those are gaps in the
24
+ * revision we claim, not deferrals — recorded here so the list is not read
25
+ * as full conformance.
22
26
  *
23
27
  * Known drift, accepted: the HTTP layer already implements Streamable HTTP
24
28
  * (added 2025-03-26), the `MCP-Protocol-Version` header and OAuth resource
@@ -54,6 +58,46 @@ export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
54
58
  * the mismatch.
55
59
  */
56
60
  export declare function negotiateProtocolVersion(requested: unknown): string;
61
+ /**
62
+ * Decide which revision to speak *after* a server has answered `initialize`.
63
+ *
64
+ * The mirror image of {@link negotiateProtocolVersion}, and the client-side
65
+ * half of the same handshake rule. A server that cannot honour the revision we
66
+ * asked for replies with its own latest — which is a statement about the
67
+ * server, not a grant. Adopting it verbatim (what every transport used to do:
68
+ * `this.protocolVersion = serverMetadata.protocolVersion`) silently moved us
69
+ * onto a revision whose semantics we do not implement, and the value was then
70
+ * echoed back in the `MCP-Protocol-Version` header, so we told the server we
71
+ * spoke a protocol we were not speaking.
72
+ *
73
+ * The revision we claim is ours to keep, never the server's to assign. The
74
+ * version the server reported stays in `getServerMetadata()` for diagnostics;
75
+ * it does not drive our requests, and we do not speak it.
76
+ *
77
+ * On an unsupported revision this THROWS. `2024-11-05` lifecycle is explicit:
78
+ * "If the client does not support the version in the server's response, it
79
+ * SHOULD disconnect." Every transport already unwinds on a connect throw —
80
+ * `abort()`s its controller and marks `failed`, and `MCPClient.connect` runs
81
+ * `close()` before rethrowing, which for stdio terminates the child process.
82
+ * So throwing here IS the disconnect, and the reason is recorded first as a
83
+ * structured warn line because the generic connect-failure log that follows
84
+ * would otherwise bury it.
85
+ */
86
+ export declare function assertSupportedServerProtocolVersion(serverName: string, reported: string): string;
87
+ /**
88
+ * A refused `initialize` revision, as a type rather than a message pattern.
89
+ *
90
+ * The refusal is deterministic — the same server will answer the same way on
91
+ * every retry — so the registry's connect loop treats it as terminal instead
92
+ * of spending its remaining attempts (and every later demand-wake) on a
93
+ * handshake that can never succeed. Match on this class, never on the text.
94
+ */
95
+ export declare class MCPUnsupportedProtocolVersionError extends Error {
96
+ readonly serverName: string;
97
+ readonly reported: string;
98
+ readonly name = "MCPUnsupportedProtocolVersionError";
99
+ constructor(serverName: string, reported: string, message: string);
100
+ }
57
101
  export declare const MCP_CONSTANTS: Readonly<{
58
102
  /** MCP protocol version advertised during handshake: the newest we implement. */
59
103
  readonly PROTOCOL_VERSION: string;
@@ -89,8 +133,15 @@ export declare const MCP_CONSTANTS: Readonly<{
89
133
  /** How often the idle sweep runs (kept well below the timeout). */
90
134
  SWEEP_INTERVAL_MS: 30000;
91
135
  }>;
92
- /** JSON-RPC response timeout for outstanding requests. */
93
- readonly RESPONSE_TIMEOUT_MS: 500;
136
+ /**
137
+ * Default per-request timeout for JSON-RPC requests, used when a server
138
+ * config sets no `requestTimeoutMs`.
139
+ *
140
+ * This is the single source for the three fallbacks that each spelled the
141
+ * same number out inline (the HTTP request-timeout signal, the HTTP
142
+ * transport's per-request default, and `MCPClient.request`).
143
+ */
144
+ readonly REQUEST_TIMEOUT_MS: 60000;
94
145
  /** Max buffer size for the SSE reader. */
95
146
  readonly SSE_READER_MAX_BUFFER: number;
96
147
  /** Max characters logged from a request body. */
@@ -13,6 +13,40 @@
13
13
  export type ConnectionState = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'failed'
14
14
  /** Lazy server: registered from a cached manifest, process not spawned. */
15
15
  | 'dormant';
16
+ /**
17
+ * `ToolAnnotations` — optional properties describing a tool's behaviour, added
18
+ * in spec 2025-03-26 (PR #185) and unchanged in 2026-07-28.
19
+ *
20
+ * Verified against `schema/2025-03-26/schema.ts` and `schema/2026-07-28/schema.ts`:
21
+ * exactly these five fields, with the spec's own defaults documented below.
22
+ *
23
+ * These are the SERVER'S CLAIMS about itself. The spec is explicit that clients
24
+ * MUST treat annotations as untrusted unless the server is trusted, so this
25
+ * type is metadata to surface and record — never an input to a permission
26
+ * decision.
27
+ */
28
+ export interface MCPToolAnnotations {
29
+ /** Human-readable title for display purposes. */
30
+ title?: string | undefined;
31
+ /** True when the tool does not modify its environment. Spec default: `false`. */
32
+ readOnlyHint?: boolean | undefined;
33
+ /**
34
+ * True when the tool may perform destructive updates; false when it only
35
+ * makes additive ones. Meaningful only when `readOnlyHint` is false.
36
+ * Spec default: `true`.
37
+ */
38
+ destructiveHint?: boolean | undefined;
39
+ /**
40
+ * True when repeating the call with the same arguments has no further
41
+ * effect. Meaningful only when `readOnlyHint` is false. Spec default: `false`.
42
+ */
43
+ idempotentHint?: boolean | undefined;
44
+ /**
45
+ * True when the tool interacts with the outside world (network, third-party
46
+ * APIs) rather than only the local environment. Spec default: `true`.
47
+ */
48
+ openWorldHint?: boolean | undefined;
49
+ }
16
50
  /** Minimal MCP tool descriptor returned by `tools/list`. */
17
51
  export interface MCPTool {
18
52
  name: string;
@@ -20,6 +54,8 @@ export interface MCPTool {
20
54
  inputSchema: Record<string, unknown>;
21
55
  /** JSON Schema of the tool's `structuredContent` (spec 2025-06-18). */
22
56
  outputSchema?: Record<string, unknown> | undefined;
57
+ /** Server-claimed behaviour hints (spec 2025-03-26). Untrusted: display only. */
58
+ annotations?: MCPToolAnnotations | undefined;
23
59
  }
24
60
  /**
25
61
  * URL-mode elicitation (spec 2025-11-25): the server asks the user to open a
package/dist/index.d.ts CHANGED
@@ -6,7 +6,7 @@ export { MCPClient, type MCPClientOptions, type MCPListChangedListener, type MCP
6
6
  export { mcpEnvPlaceholders } from './config-env.js';
7
7
  export { MCP_CONSTANTS, negotiateProtocolVersion, SUPPORTED_PROTOCOL_VERSIONS, } from './constants.js';
8
8
  export { DEFAULT_MCP_INSERTION_MAX_BYTES, DEFAULT_MCP_RESOURCE_SCHEMES, type MCPContentProvenance, type MCPInsertionPolicy, type MCPPromptInsertion, type MCPResourceInsertion, preparePromptInsertion, prepareResourceInsertion, } from './content-selection.js';
9
- export type { ConnectionState, JsonRpcResponse, MCPTool, ToolCallResult, } from './contracts.js';
9
+ export type { ConnectionState, JsonRpcResponse, MCPTool, MCPToolAnnotations, ToolCallResult, } from './contracts.js';
10
10
  export type { ElicitationField, ElicitationRequester, MCPElicitationHandler, MCPElicitationRequest, MCPElicitationResult, } from './elicitation.js';
11
11
  export { elicitViaUserInput } from './elicitation-form.js';
12
12
  export { addMcp, disableMcp, discoverMcp, enableMcp, listMcp, MCP_ENV_MASK, type McpManageDeps, type McpOpResult, type McpServerInfo, type McpServerInput, removeMcp, restartMcp, updateMcp, } from './manage.js';