@agentionai/agents 1.0.2 → 1.2.0

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,90 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.renderContentBlock = renderContentBlock;
4
+ exports.renderToolResult = renderToolResult;
5
+ /**
6
+ * Format the decoded size of a base64 payload for display.
7
+ */
8
+ function formatBase64Size(data) {
9
+ const padding = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
10
+ const bytes = Math.max(0, Math.floor((data.length * 3) / 4) - padding);
11
+ if (bytes < 1024)
12
+ return `${bytes} B`;
13
+ if (bytes < 1024 * 1024)
14
+ return `${(bytes / 1024).toFixed(1)} KB`;
15
+ return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
16
+ }
17
+ /**
18
+ * Render a single MCP content block as text.
19
+ *
20
+ * Text blocks are returned verbatim. Binary blocks (image, audio, blob
21
+ * resources) cannot be represented as text, so they are rendered as a
22
+ * descriptive placeholder carrying their mime type and size — enough for a model
23
+ * to know the content exists and to ask for it another way. Text-bearing
24
+ * resources are inlined under a header naming their URI.
25
+ *
26
+ * Unrecognised block types — content types added to the protocol after this
27
+ * release — are serialised as JSON rather than dropped.
28
+ */
29
+ function renderContentBlock(block) {
30
+ switch (block.type) {
31
+ case "text": {
32
+ return block.text ?? "";
33
+ }
34
+ case "image": {
35
+ const image = block;
36
+ return `[image content: ${image.mimeType ?? "unknown"}, ${formatBase64Size(image.data ?? "")}]`;
37
+ }
38
+ case "audio": {
39
+ const audio = block;
40
+ return `[audio content: ${audio.mimeType ?? "unknown"}, ${formatBase64Size(audio.data ?? "")}]`;
41
+ }
42
+ case "resource": {
43
+ const { resource } = block;
44
+ if (!resource)
45
+ return "[resource]";
46
+ const mime = resource.mimeType ? `, ${resource.mimeType}` : "";
47
+ if (typeof resource.text === "string") {
48
+ return `[resource: ${resource.uri}${mime}]\n${resource.text}`;
49
+ }
50
+ return `[resource: ${resource.uri}${mime}, ${formatBase64Size(resource.blob ?? "")}]`;
51
+ }
52
+ case "resource_link": {
53
+ const link = block;
54
+ const name = link.name ? ` (${link.name})` : "";
55
+ const description = link.description ? ` — ${link.description}` : "";
56
+ return `[resource link: ${link.uri}${name}${description}]`;
57
+ }
58
+ default: {
59
+ return `[${block.type} content: ${JSON.stringify(block)}]`;
60
+ }
61
+ }
62
+ }
63
+ /**
64
+ * Convert a raw MCP `CallToolResult` into the value handed to the agent.
65
+ *
66
+ * Resolution order:
67
+ * 1. When the result has content blocks, every block is rendered and the
68
+ * segments are joined with newlines. `structuredContent` is appended as JSON
69
+ * when the result carries no text block, so structured output is never lost
70
+ * behind a binary-only result.
71
+ * 2. Otherwise `structuredContent` is returned as-is, so tools with an
72
+ * `outputSchema` keep giving the agent a real object.
73
+ * 3. Otherwise the whole result is JSON-serialised.
74
+ */
75
+ function renderToolResult(result) {
76
+ const blocks = Array.isArray(result?.content) ? result.content : [];
77
+ if (blocks.length > 0) {
78
+ const segments = blocks.map(renderContentBlock);
79
+ const hasText = blocks.some((block) => block.type === "text");
80
+ if (!hasText && result?.structuredContent !== undefined) {
81
+ segments.push(JSON.stringify(result.structuredContent));
82
+ }
83
+ return segments.join("\n");
84
+ }
85
+ if (result?.structuredContent !== undefined) {
86
+ return result.structuredContent;
87
+ }
88
+ return JSON.stringify(result ?? null);
89
+ }
90
+ //# sourceMappingURL=content.js.map
@@ -0,0 +1,62 @@
1
+ import type { MCPCallToolResult } from "./types";
2
+ /**
3
+ * Base error class for all MCP-related errors.
4
+ */
5
+ export declare class MCPError extends Error {
6
+ constructor(message: string);
7
+ }
8
+ /**
9
+ * Thrown when a tool is executed while the client has no usable connection —
10
+ * either because {@link MCPClient.connect} was never called, or because the
11
+ * transport dropped and could not be restored.
12
+ */
13
+ export declare class MCPNotConnectedError extends MCPError {
14
+ /** Name of the tool that was called. */
15
+ toolName: string;
16
+ /** Connection state at the time of the call. */
17
+ state: string;
18
+ constructor(message: string,
19
+ /** Name of the tool that was called. */
20
+ toolName: string,
21
+ /** Connection state at the time of the call. */
22
+ state: string);
23
+ }
24
+ /**
25
+ * Thrown when a `tools/call` request fails at the transport or protocol level —
26
+ * a timeout, an aborted signal, or an error raised by the MCP SDK.
27
+ *
28
+ * The originating error is kept on {@link MCPCallError.cause}, which is how a host
29
+ * tells a deliberate cancellation (`cause.name === "AbortError"`) apart from a
30
+ * server-side failure.
31
+ */
32
+ export declare class MCPCallError extends MCPError {
33
+ /** Name of the tool that was called. */
34
+ toolName: string;
35
+ /** The underlying error thrown by the MCP SDK, or the abort reason. */
36
+ cause?: unknown | undefined;
37
+ constructor(message: string,
38
+ /** Name of the tool that was called. */
39
+ toolName: string,
40
+ /** The underlying error thrown by the MCP SDK, or the abort reason. */
41
+ cause?: unknown | undefined);
42
+ }
43
+ /**
44
+ * Thrown when an MCP server returns a result flagged with `isError: true`.
45
+ *
46
+ * This is a *tool-level* failure: the call itself succeeded at the protocol
47
+ * level, but the tool reported that it could not do its job. Agents catch it and
48
+ * pass the message back to the model as a failed tool result, which is what
49
+ * distinguishes it from a result the model would otherwise read as success.
50
+ */
51
+ export declare class MCPToolError extends MCPError {
52
+ /** Name of the tool that reported the failure. */
53
+ toolName: string;
54
+ /** The raw `CallToolResult`, including any non-text content blocks. */
55
+ result: MCPCallToolResult;
56
+ constructor(message: string,
57
+ /** Name of the tool that reported the failure. */
58
+ toolName: string,
59
+ /** The raw `CallToolResult`, including any non-text content blocks. */
60
+ result: MCPCallToolResult);
61
+ }
62
+ //# sourceMappingURL=errors.d.ts.map
@@ -0,0 +1,74 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.MCPToolError = exports.MCPCallError = exports.MCPNotConnectedError = exports.MCPError = void 0;
4
+ /**
5
+ * Base error class for all MCP-related errors.
6
+ */
7
+ class MCPError extends Error {
8
+ constructor(message) {
9
+ super(message);
10
+ this.name = "MCPError";
11
+ }
12
+ }
13
+ exports.MCPError = MCPError;
14
+ /**
15
+ * Thrown when a tool is executed while the client has no usable connection —
16
+ * either because {@link MCPClient.connect} was never called, or because the
17
+ * transport dropped and could not be restored.
18
+ */
19
+ class MCPNotConnectedError extends MCPError {
20
+ constructor(message,
21
+ /** Name of the tool that was called. */
22
+ toolName,
23
+ /** Connection state at the time of the call. */
24
+ state) {
25
+ super(message);
26
+ this.toolName = toolName;
27
+ this.state = state;
28
+ this.name = "MCPNotConnectedError";
29
+ }
30
+ }
31
+ exports.MCPNotConnectedError = MCPNotConnectedError;
32
+ /**
33
+ * Thrown when a `tools/call` request fails at the transport or protocol level —
34
+ * a timeout, an aborted signal, or an error raised by the MCP SDK.
35
+ *
36
+ * The originating error is kept on {@link MCPCallError.cause}, which is how a host
37
+ * tells a deliberate cancellation (`cause.name === "AbortError"`) apart from a
38
+ * server-side failure.
39
+ */
40
+ class MCPCallError extends MCPError {
41
+ constructor(message,
42
+ /** Name of the tool that was called. */
43
+ toolName,
44
+ /** The underlying error thrown by the MCP SDK, or the abort reason. */
45
+ cause) {
46
+ super(message);
47
+ this.toolName = toolName;
48
+ this.cause = cause;
49
+ this.name = "MCPCallError";
50
+ }
51
+ }
52
+ exports.MCPCallError = MCPCallError;
53
+ /**
54
+ * Thrown when an MCP server returns a result flagged with `isError: true`.
55
+ *
56
+ * This is a *tool-level* failure: the call itself succeeded at the protocol
57
+ * level, but the tool reported that it could not do its job. Agents catch it and
58
+ * pass the message back to the model as a failed tool result, which is what
59
+ * distinguishes it from a result the model would otherwise read as success.
60
+ */
61
+ class MCPToolError extends MCPError {
62
+ constructor(message,
63
+ /** Name of the tool that reported the failure. */
64
+ toolName,
65
+ /** The raw `CallToolResult`, including any non-text content blocks. */
66
+ result) {
67
+ super(message);
68
+ this.toolName = toolName;
69
+ this.result = result;
70
+ this.name = "MCPToolError";
71
+ }
72
+ }
73
+ exports.MCPToolError = MCPToolError;
74
+ //# sourceMappingURL=errors.js.map
@@ -58,7 +58,25 @@
58
58
  * authProvider: myOAuthProvider,
59
59
  * });
60
60
  * ```
61
+ *
62
+ * @example Cancellation, timeouts and a connection that drops
63
+ * ```typescript
64
+ * import { MCPClient, MCPClientEvent } from "@agentionai/agents";
65
+ *
66
+ * const turn = new AbortController();
67
+ * const mcp = MCPClient.fromUrl("https://my-mcp-server.com/mcp", {
68
+ * callOptions: () => ({ signal: turn.signal, timeout: 20_000 }),
69
+ * reconnect: { enabled: true, maxRetries: 10 },
70
+ * });
71
+ *
72
+ * mcp.on(MCPClientEvent.DISCONNECTED, ({ willReconnect }) => {
73
+ * console.warn("MCP connection lost", { willReconnect });
74
+ * });
75
+ * mcp.on(MCPClientEvent.TOOLS_CHANGED, ({ tools }) => agent.addTools(tools));
76
+ * ```
61
77
  */
62
- export { MCPClient } from "./MCPClient";
63
- export type { MCPStdioConfig, MCPHttpConfig, MCPClientOptions } from "./types";
78
+ export { MCPClient, MCPClientEvent } from "./MCPClient";
79
+ export { MCPError, MCPCallError, MCPNotConnectedError, MCPToolError } from "./errors";
80
+ export { renderContentBlock, renderToolResult } from "./content";
81
+ export type { MCPStdioConfig, MCPHttpConfig, MCPClientOptions, MCPOAuthClientProvider, MCPCallOptionsSource, MCPToolCallOptions, MCPToolCallContext, MCPToolResultFormatter, MCPReconnectOptions, MCPConnectionState, MCPProgress, MCPCallToolResult, MCPContentBlock, MCPTextContent, MCPImageContent, MCPAudioContent, MCPEmbeddedResourceContent, MCPResourceLinkContent, MCPClientEventMap, MCPConnectedEvent, MCPDisconnectedEvent, MCPReconnectingEvent, MCPToolsChangedEvent, } from "./types";
64
82
  //# sourceMappingURL=index.d.ts.map
package/dist/mcp/index.js CHANGED
@@ -59,9 +59,34 @@
59
59
  * authProvider: myOAuthProvider,
60
60
  * });
61
61
  * ```
62
+ *
63
+ * @example Cancellation, timeouts and a connection that drops
64
+ * ```typescript
65
+ * import { MCPClient, MCPClientEvent } from "@agentionai/agents";
66
+ *
67
+ * const turn = new AbortController();
68
+ * const mcp = MCPClient.fromUrl("https://my-mcp-server.com/mcp", {
69
+ * callOptions: () => ({ signal: turn.signal, timeout: 20_000 }),
70
+ * reconnect: { enabled: true, maxRetries: 10 },
71
+ * });
72
+ *
73
+ * mcp.on(MCPClientEvent.DISCONNECTED, ({ willReconnect }) => {
74
+ * console.warn("MCP connection lost", { willReconnect });
75
+ * });
76
+ * mcp.on(MCPClientEvent.TOOLS_CHANGED, ({ tools }) => agent.addTools(tools));
77
+ * ```
62
78
  */
63
79
  Object.defineProperty(exports, "__esModule", { value: true });
64
- exports.MCPClient = void 0;
80
+ exports.renderToolResult = exports.renderContentBlock = exports.MCPToolError = exports.MCPNotConnectedError = exports.MCPCallError = exports.MCPError = exports.MCPClientEvent = exports.MCPClient = void 0;
65
81
  var MCPClient_1 = require("./MCPClient");
66
82
  Object.defineProperty(exports, "MCPClient", { enumerable: true, get: function () { return MCPClient_1.MCPClient; } });
83
+ Object.defineProperty(exports, "MCPClientEvent", { enumerable: true, get: function () { return MCPClient_1.MCPClientEvent; } });
84
+ var errors_1 = require("./errors");
85
+ Object.defineProperty(exports, "MCPError", { enumerable: true, get: function () { return errors_1.MCPError; } });
86
+ Object.defineProperty(exports, "MCPCallError", { enumerable: true, get: function () { return errors_1.MCPCallError; } });
87
+ Object.defineProperty(exports, "MCPNotConnectedError", { enumerable: true, get: function () { return errors_1.MCPNotConnectedError; } });
88
+ Object.defineProperty(exports, "MCPToolError", { enumerable: true, get: function () { return errors_1.MCPToolError; } });
89
+ var content_1 = require("./content");
90
+ Object.defineProperty(exports, "renderContentBlock", { enumerable: true, get: function () { return content_1.renderContentBlock; } });
91
+ Object.defineProperty(exports, "renderToolResult", { enumerable: true, get: function () { return content_1.renderToolResult; } });
67
92
  //# sourceMappingURL=index.js.map
@@ -1,3 +1,4 @@
1
+ import type { Tool } from "../tools/Tool";
1
2
  /**
2
3
  * Configuration for connecting to an MCP server via stdio (local process).
3
4
  */
@@ -9,6 +10,44 @@ export interface MCPStdioConfig {
9
10
  /** Environment variables for the spawned process */
10
11
  env?: Record<string, string>;
11
12
  }
13
+ /**
14
+ * Structural equivalent of the MCP SDK's `OAuthClientProvider`.
15
+ *
16
+ * `@modelcontextprotocol/sdk` is an optional peer dependency, so this type is
17
+ * declared here rather than imported: a type-only import would still have to be
18
+ * resolved by `tsc`, which would break the build of every consumer that does not
19
+ * install the SDK. TypeScript's structural typing means an SDK
20
+ * `OAuthClientProvider` satisfies this interface directly — `MCPClient.spec.ts`
21
+ * asserts that at compile time so drift in the SDK is caught by the test run.
22
+ *
23
+ * @example
24
+ * ```typescript
25
+ * import { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
26
+ *
27
+ * const myOAuthProvider: OAuthClientProvider = { ... };
28
+ * const mcp = MCPClient.fromUrl("https://my-server.com/mcp", {
29
+ * authProvider: myOAuthProvider,
30
+ * });
31
+ * ```
32
+ */
33
+ export interface MCPOAuthClientProvider {
34
+ /** URL the user agent is redirected to after authorization. */
35
+ readonly redirectUrl: string | URL | undefined;
36
+ /** Metadata describing this OAuth client. */
37
+ readonly clientMetadata: any;
38
+ /** Loads previously registered client information, if any. */
39
+ clientInformation(): any;
40
+ /** Loads the OAuth tokens for the current session, if any. */
41
+ tokens(): any;
42
+ /** Persists new OAuth tokens after a successful authorization. */
43
+ saveTokens(tokens: any): void | Promise<void>;
44
+ /** Redirects the user agent to begin the authorization flow. */
45
+ redirectToAuthorization(authorizationUrl: URL): void | Promise<void>;
46
+ /** Persists the PKCE code verifier for the current session. */
47
+ saveCodeVerifier(codeVerifier: string): void | Promise<void>;
48
+ /** Loads the PKCE code verifier for the current session. */
49
+ codeVerifier(): string | Promise<string>;
50
+ }
12
51
  /**
13
52
  * Configuration for connecting to an MCP server via HTTP (remote URL).
14
53
  */
@@ -19,19 +58,165 @@ export interface MCPHttpConfig {
19
58
  headers?: Record<string, string>;
20
59
  /**
21
60
  * Optional OAuth provider for dynamic authorization.
22
- * Implement the `OAuthClientProvider` interface from `@modelcontextprotocol/sdk`
23
- * and pass it here for OAuth 2.0 + PKCE flows.
61
+ * Pass an `OAuthClientProvider` from `@modelcontextprotocol/sdk/client/auth.js`
62
+ * for OAuth 2.0 + PKCE flows.
24
63
  *
25
- * @example
26
- * ```typescript
27
- * import { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
28
- *
29
- * const mcp = MCPClient.fromUrl("https://my-server.com/mcp", {
30
- * authProvider: myOAuthProvider,
31
- * });
32
- * ```
64
+ * @see {@link MCPOAuthClientProvider}
65
+ */
66
+ authProvider?: MCPOAuthClientProvider;
67
+ }
68
+ /**
69
+ * Progress notification emitted by an MCP server during a long-running tool call.
70
+ */
71
+ export interface MCPProgress {
72
+ /** Amount of work completed so far. */
73
+ progress: number;
74
+ /** Total amount of work, when the server knows it. */
75
+ total?: number;
76
+ /** Human-readable description of the current step. */
77
+ message?: string;
78
+ }
79
+ /**
80
+ * Per-request options forwarded to the MCP SDK's `Client.callTool()`.
81
+ *
82
+ * These map one-to-one onto the SDK's `RequestOptions`.
83
+ */
84
+ export interface MCPToolCallOptions {
85
+ /**
86
+ * Cancels the in-flight call. The tool rejects with an abort error as soon as
87
+ * the signal fires, which lets a host interrupt an agent turn that is blocked
88
+ * on a hung server.
89
+ */
90
+ signal?: AbortSignal;
91
+ /**
92
+ * Timeout in milliseconds for this call.
93
+ * @default 60000 (the MCP SDK's `DEFAULT_REQUEST_TIMEOUT_MSEC`)
94
+ */
95
+ timeout?: number;
96
+ /** Reset the timeout every time a progress notification arrives. */
97
+ resetTimeoutOnProgress?: boolean;
98
+ /** Hard ceiling in milliseconds, regardless of progress notifications. */
99
+ maxTotalTimeout?: number;
100
+ /** Invoked for each progress notification the server sends. */
101
+ onprogress?: (progress: MCPProgress) => void;
102
+ }
103
+ /**
104
+ * Identifies the call that options or a formatter are being resolved for.
105
+ */
106
+ export interface MCPToolCallContext {
107
+ /** Name of the MCP tool being called. */
108
+ toolName: string;
109
+ /** Arguments the agent passed to the tool. */
110
+ input: Record<string, unknown>;
111
+ }
112
+ /**
113
+ * Default call options for an {@link MCPClient} — either a fixed object or a
114
+ * function resolved fresh on every call.
115
+ *
116
+ * The function form is the one to reach for when the signal changes per agent
117
+ * turn: return the current turn's `AbortController.signal` and every subsequent
118
+ * tool call picks it up.
119
+ */
120
+ export type MCPCallOptionsSource = MCPToolCallOptions | ((context: MCPToolCallContext) => MCPToolCallOptions | undefined);
121
+ /** A text block in an MCP tool result. */
122
+ export interface MCPTextContent {
123
+ type: "text";
124
+ text: string;
125
+ }
126
+ /** An image block in an MCP tool result. `data` is base64-encoded. */
127
+ export interface MCPImageContent {
128
+ type: "image";
129
+ data: string;
130
+ mimeType: string;
131
+ }
132
+ /** An audio block in an MCP tool result. `data` is base64-encoded. */
133
+ export interface MCPAudioContent {
134
+ type: "audio";
135
+ data: string;
136
+ mimeType: string;
137
+ }
138
+ /** A resource embedded directly in an MCP tool result. */
139
+ export interface MCPEmbeddedResourceContent {
140
+ type: "resource";
141
+ resource: {
142
+ uri: string;
143
+ mimeType?: string;
144
+ /** Present for text resources. */
145
+ text?: string;
146
+ /** Present for binary resources, base64-encoded. */
147
+ blob?: string;
148
+ };
149
+ }
150
+ /** A reference to a resource the client can read separately. */
151
+ export interface MCPResourceLinkContent {
152
+ type: "resource_link";
153
+ uri: string;
154
+ name: string;
155
+ description?: string;
156
+ mimeType?: string;
157
+ size?: number;
158
+ }
159
+ /**
160
+ * A single block of an MCP tool result. The open-ended member keeps forward
161
+ * compatibility with content types added to the protocol later.
162
+ */
163
+ export type MCPContentBlock = MCPTextContent | MCPImageContent | MCPAudioContent | MCPEmbeddedResourceContent | MCPResourceLinkContent | {
164
+ type: string;
165
+ [key: string]: unknown;
166
+ };
167
+ /**
168
+ * The raw `CallToolResult` returned by an MCP server.
169
+ */
170
+ export interface MCPCallToolResult {
171
+ /** Content blocks produced by the tool. */
172
+ content?: MCPContentBlock[];
173
+ /** Structured output, when the tool declares an `outputSchema`. */
174
+ structuredContent?: Record<string, unknown>;
175
+ /** Set by the server when the tool itself failed. */
176
+ isError?: boolean;
177
+ [key: string]: unknown;
178
+ }
179
+ /**
180
+ * Converts a raw MCP tool result into the value the agent receives.
181
+ *
182
+ * Supply one to take full control of how results reach the model — for example
183
+ * to turn image blocks into multimodal content instead of text placeholders.
184
+ * Returning from the formatter suppresses the built-in rendering entirely;
185
+ * throwing surfaces as a tool error.
186
+ */
187
+ export type MCPToolResultFormatter = (result: MCPCallToolResult, context: MCPToolCallContext) => unknown;
188
+ /**
189
+ * Automatic reconnection behaviour for a dropped transport.
190
+ */
191
+ export interface MCPReconnectOptions {
192
+ /**
193
+ * Reconnect automatically when the transport closes unexpectedly.
194
+ * @default false
195
+ */
196
+ enabled?: boolean;
197
+ /**
198
+ * Maximum number of consecutive reconnect attempts before giving up.
199
+ * Pass `Infinity` to retry forever.
200
+ * @default 5
201
+ */
202
+ maxRetries?: number;
203
+ /**
204
+ * Delay before the first retry, in milliseconds. Subsequent delays grow by
205
+ * {@link MCPReconnectOptions.backoffFactor} up to
206
+ * {@link MCPReconnectOptions.maxDelayMs}.
207
+ * @default 500
208
+ */
209
+ initialDelayMs?: number;
210
+ /**
211
+ * Upper bound for the backoff delay, in milliseconds.
212
+ * @default 30000
33
213
  */
34
- authProvider?: unknown;
214
+ maxDelayMs?: number;
215
+ /**
216
+ * Multiplier applied to the delay after each failed attempt.
217
+ * @default 2
218
+ */
219
+ backoffFactor?: number;
35
220
  }
36
221
  /**
37
222
  * Options shared by all MCPClient connection types.
@@ -47,5 +232,87 @@ export interface MCPClientOptions {
47
232
  * @default "1.0.0"
48
233
  */
49
234
  clientVersion?: string;
235
+ /**
236
+ * Default options applied to every tool call — most importantly `signal` and
237
+ * `timeout`. Pass a function to resolve them per call.
238
+ *
239
+ * @see {@link MCPClient.setCallOptions} to change them after construction.
240
+ */
241
+ callOptions?: MCPCallOptionsSource;
242
+ /**
243
+ * Throw when a server marks a result with `isError: true`.
244
+ *
245
+ * Agents catch tool errors and hand the message back to the model as a failed
246
+ * tool result, so leaving this on means a tool-level failure is never mistaken
247
+ * for a successful one. Set to `false` to receive the rendered error content
248
+ * as an ordinary return value instead.
249
+ *
250
+ * @default true
251
+ */
252
+ throwOnToolError?: boolean;
253
+ /**
254
+ * Override how a raw MCP result is converted into the agent-visible value.
255
+ */
256
+ formatResult?: MCPToolResultFormatter;
257
+ /**
258
+ * Automatic reconnection after an unexpected transport close.
259
+ * @default { enabled: false }
260
+ */
261
+ reconnect?: MCPReconnectOptions;
262
+ /**
263
+ * Re-run tool discovery when the server sends `notifications/tools/list_changed`.
264
+ * @default true
265
+ */
266
+ refreshToolsOnListChanged?: boolean;
267
+ }
268
+ /**
269
+ * Lifecycle state of an {@link MCPClient}'s connection.
270
+ *
271
+ * - `disconnected` — never connected, or disconnected on purpose
272
+ * - `connecting` — {@link MCPClient.connect} is in flight
273
+ * - `connected` — usable
274
+ * - `reconnecting` — the transport dropped and a retry is scheduled or running
275
+ * - `failed` — the transport dropped and reconnection gave up
276
+ */
277
+ export type MCPConnectionState = "disconnected" | "connecting" | "connected" | "reconnecting" | "failed";
278
+ /** Payload of {@link MCPClientEvent.CONNECTED}. */
279
+ export interface MCPConnectedEvent {
280
+ tools: Tool<unknown>[];
281
+ }
282
+ /** Payload of {@link MCPClientEvent.DISCONNECTED}. */
283
+ export interface MCPDisconnectedEvent {
284
+ /** The transport error, when the close was caused by one. */
285
+ error?: Error;
286
+ /** `true` when the close was requested via {@link MCPClient.disconnect}. */
287
+ deliberate: boolean;
288
+ /** `true` when a reconnect attempt has been scheduled. */
289
+ willReconnect: boolean;
290
+ }
291
+ /** Payload of {@link MCPClientEvent.RECONNECTING}. */
292
+ export interface MCPReconnectingEvent {
293
+ /** 1-based attempt counter. */
294
+ attempt: number;
295
+ /** Delay waited before this attempt, in milliseconds. */
296
+ delayMs: number;
297
+ }
298
+ /** Payload of {@link MCPClientEvent.TOOLS_CHANGED}. */
299
+ export interface MCPToolsChangedEvent {
300
+ /** The full, current tool list. */
301
+ tools: Tool<unknown>[];
302
+ /** Names present now that were not present before. */
303
+ added: string[];
304
+ /** Names present before that are gone now. */
305
+ removed: string[];
306
+ }
307
+ /**
308
+ * Maps each {@link MCPClientEvent} name to its listener payload.
309
+ */
310
+ export interface MCPClientEventMap {
311
+ connected: MCPConnectedEvent;
312
+ disconnected: MCPDisconnectedEvent;
313
+ reconnecting: MCPReconnectingEvent;
314
+ reconnected: MCPConnectedEvent;
315
+ toolsChanged: MCPToolsChangedEvent;
316
+ error: Error;
50
317
  }
51
318
  //# sourceMappingURL=types.d.ts.map
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@agentionai/agents",
3
3
  "author": "Laurent Zuijdwijk",
4
- "version": "1.0.2",
4
+ "version": "1.2.0",
5
5
  "description": "Agent Library",
6
6
  "main": "dist/index.js",
7
7
  "types": "dist/index.d.ts",
@@ -113,6 +113,7 @@
113
113
  "@google/generative-ai": "^0.24.1",
114
114
  "@lancedb/lancedb": "^0.23.0",
115
115
  "@mistralai/mistralai": "^1.13.0",
116
+ "@modelcontextprotocol/sdk": "^1.30.0",
116
117
  "@types/jest": "^29.5.0",
117
118
  "@types/node": "^18.15.11",
118
119
  "apache-arrow": "^18.1.0",