@mastra/mcp 2.8.0-alpha.0 → 2.8.0-alpha.2

package/dist/index.js

@@ -15397,6 +15397,57 @@ var TaskRequester = class {
 		};
 	}
 };
+// src/client/tasks/suspend.ts
+const MCP_INPUT_REQUEST_SUSPEND_TYPE = "mcp-input-request";
+const SuspendPayloadSchema = z.object({
+	type: z.literal(MCP_INPUT_REQUEST_SUSPEND_TYPE),
+	serverName: z.string(),
+	toolName: z.string(),
+	taskId: z.string().min(1),
+	createdAt: z.string(),
+	requestedAt: z.string().optional(),
+	requests: TaskInputRequestsSchema
+});
+const ResumeDataSchema = z.object({ inputResponses: z.record(z.string(), z.object({
+	action: z.enum([
+		"accept",
+		"decline",
+		"cancel"
+	]),
+	content: z.record(z.string(), z.unknown()).optional()
+})) });
+/**
+* Reads a resume of a tool call that suspended on MCP task input. Returns `undefined` when the call
+* didn't suspend that way, so other resumes (tool approval, for one) take the normal path.
+*/
+function readInputRequestResume(host, expected) {
+	const raw = host?.suspendPayload;
+	if (!raw || typeof raw !== "object" || raw.type !== "mcp-input-request") return;
+	const payload = SuspendPayloadSchema.safeParse(raw);
+	if (!payload.success) return {
+		ok: false,
+		reason: `the suspended MCP input request is malformed`
+	};
+	if (payload.data.serverName !== expected.serverName || payload.data.toolName !== expected.toolName) return {
+		ok: false,
+		reason: `the suspended MCP input request belongs to another tool`
+	};
+	const resume = ResumeDataSchema.safeParse(host?.resumeData);
+	if (!resume.success) return {
+		ok: false,
+		reason: `resume data must be { inputResponses: { [key]: { action: 'accept' | 'decline' | 'cancel', content? } } }`
+	};
+	const missing = Object.keys(payload.data.requests).filter((key) => !Object.hasOwn(resume.data.inputResponses, key));
+	if (missing.length > 0) return {
+		ok: false,
+		reason: `resume data has no answer for ${missing.join(", ")}`
+	};
+	return {
+		ok: true,
+		payload: payload.data,
+		inputResponses: resume.data.inputResponses
+	};
+}
 // src/client/tasks/wait.ts
 /** Why a task wait stopped without a terminal task. */
 var TaskWaitError = class extends Error {
@@ -15425,12 +15476,6 @@ const defaultSleep = (ms, signal) => new Promise((resolve, reject) => {
 	};
 	signal?.addEventListener("abort", onAbort, { once: true });
 });
-/**
-* Polls a remote task until it reaches a terminal status, answering its input requests on the way.
-*
-* Aborting the signal or exceeding `maxWaitMs` sends `tasks/cancel` (fire-and-forget) and rejects.
-* Each input request key is answered at most once, however many polls list it.
-*/
 async function waitForTask(port, created, options = {}) {
 	const sleep = options.sleep ?? defaultSleep;
 	const now = options.now ?? Date.now;
@@ -15481,7 +15526,21 @@ async function waitForTask(port, created, options = {}) {
 				const { inputRequests } = task;
 				const pending = Object.entries(inputRequests).filter(([key]) => !answered.has(key));
 				if (pending.length > 0) {
-					const responses = await bounded(answerInputRequests(pending, task, options.inputRequests, stop.signal));
+					const supplied = options.inputResponses ?? {};
+					const unanswered = pending.filter(([key]) => !Object.hasOwn(supplied, key));
+					const responses = {};
+					for (const [key] of pending) if (Object.hasOwn(supplied, key)) responses[key] = supplied[key];
+					if (unanswered.length > 0 && !options.inputRequests && options.stopAtInput) {
+						if (Object.keys(responses).length > 0) {
+							for (const key of Object.keys(responses)) answered.add(key);
+							await bounded(port.update(task.taskId, responses, { signal: stop.signal }));
+						}
+						return {
+							...task,
+							inputRequests: Object.fromEntries(unanswered)
+						};
+					}
+					if (unanswered.length > 0) Object.assign(responses, await bounded(answerInputRequests(unanswered, task, options.inputRequests, stop.signal)));
 					for (const key of Object.keys(responses)) answered.add(key);
 					await bounded(port.update(task.taskId, responses, { signal: stop.signal }));
 					task = await poll();
@@ -17001,7 +17060,43 @@ var InternalMastraMCPClient = class extends MastraBase {
 					if (serverMeta.connectFirst) await this.connect();
 					const operationContext = context?.requestContext ?? null;
 					return this.operationContextStore.run(operationContext, async () => {
+						const suspendHost = context?.agent ?? context?.workflow;
+						const toolCallSpan = context?.tracingContext?.currentSpan;
 						const executeToolCall = async () => {
+							const resume = this.taskOptions ? readInputRequestResume(suspendHost, {
+								serverName: this.name,
+								toolName: tool.name
+							}) : void 0;
+							if (resume) {
+								if (!resume.ok) throw new MastraError({
+									id: "MCP_CLIENT_TOOL_TASK_RESUME_INVALID",
+									domain: ErrorDomain.MCP,
+									category: ErrorCategory.USER,
+									text: `Can't resume MCP tool ${tool.name}: ${resume.reason}`,
+									details: {
+										toolName: tool.name,
+										serverName: this.name
+									}
+								});
+								const { payload, inputResponses } = resume;
+								this.log("debug", `Resuming tool ${tool.name} on MCP task ${payload.taskId}`);
+								toolCallSpan?.update({ metadata: { mcpTaskKey: taskKeyOf(payload.taskId) } });
+								const waiting = {
+									taskId: payload.taskId,
+									status: "input_required",
+									createdAt: payload.createdAt,
+									lastUpdatedAt: payload.createdAt,
+									ttlMs: null,
+									inputRequests: payload.requests
+								};
+								const res = await this.awaitToolTask(tool.name, waiting, {
+									signal: context?.abortSignal,
+									writer: context?.writer,
+									suspend: suspendHost?.suspend,
+									inputResponses
+								});
+								return res && finishToolCall(res);
+							}
 							this.log("debug", `Executing tool: ${tool.name}`, {
 								toolArgs: input,
 								runId: context?.runId
@@ -17019,13 +17114,17 @@ var InternalMastraMCPClient = class extends MastraBase {
 								timeout: this.timeout,
 								signal: context?.abortSignal
 							}));
-							const toolCallSpan = context?.tracingContext?.currentSpan;
 							if (toolCallSpan && serverSpan) toolCallSpan.links = [...toolCallSpan.links ?? [], serverSpan];
 							const task = this.taskOptions ? takeTaskHandle(res) : void 0;
 							if (!task) return finishToolCall(res);
 							this.log("debug", `Tool ${tool.name} continues as MCP task ${task.taskId}`);
 							toolCallSpan?.update({ metadata: { mcpTaskKey: taskKeyOf(task.taskId) } });
-							return finishToolCall(await this.awaitToolTask(tool.name, task, context?.abortSignal, context?.writer));
+							const taskResult = await this.awaitToolTask(tool.name, task, {
+								signal: context?.abortSignal,
+								writer: context?.writer,
+								suspend: suspendHost?.suspend
+							});
+							return taskResult && finishToolCall(taskResult);
 						};
 						const finishToolCall = async (res) => {
 							if (res.isError && this.onToolError === "throw") {
@@ -17112,8 +17211,13 @@ var InternalMastraMCPClient = class extends MastraBase {
 			maxRetries: 0
 		};
 	}
-	/** Waits for a remote task created by a tool call and returns its `CallToolResult`. */
-	async awaitToolTask(toolName, task, signal, writer) {
+	/**
+	* Waits for a remote task created by a tool call and returns its `CallToolResult`.
+	*
+	* When the task needs input that no `inputRequests` handler answers and the caller can `suspend`,
+	* suspends with the requests and returns `undefined`, leaving the task open for the answers.
+	*/
+	async awaitToolTask(toolName, task, { signal, writer, suspend, inputResponses }) {
 		const details = {
 			toolName,
 			serverName: this.name,
@@ -17152,6 +17256,8 @@ var InternalMastraMCPClient = class extends MastraBase {
 			}, task, {
 				signal,
 				inputRequests: this.serverConfig.inputRequests,
+				stopAtInput: !this.serverConfig.inputRequests && suspend !== void 0,
+				inputResponses,
 				pollIntervalMs: this.taskOptions?.pollIntervalMs,
 				maxWaitMs: this.taskOptions?.maxWaitMs,
 				onStatus
@@ -17163,6 +17269,17 @@ var InternalMastraMCPClient = class extends MastraBase {
 			throw fail("MCP_CLIENT_TOOL_TASK_POLL_FAILED", `Polling MCP task ${task.taskId} failed: ${reason}`, error);
 		}
 		switch (terminal.status) {
+			case "input_required":
+				await suspend({
+					type: MCP_INPUT_REQUEST_SUSPEND_TYPE,
+					serverName: this.name,
+					toolName,
+					taskId: terminal.taskId,
+					createdAt: terminal.createdAt,
+					requestedAt: (/* @__PURE__ */ new Date()).toISOString(),
+					requests: terminal.inputRequests
+				});
+				return;
 			case "completed": return terminal.result;
 			case "cancelled": throw fail("MCP_CLIENT_TOOL_TASK_CANCELLED", terminal.statusMessage ?? `MCP task ${task.taskId} was cancelled`);
 			case "failed": throw fail("MCP_CLIENT_TOOL_TASK_FAILED", (typeof terminal.error.message === "string" ? terminal.error.message : void 0) ?? terminal.statusMessage ?? `MCP task ${task.taskId} failed`);
@@ -20905,6 +21022,161 @@ function echoes(body, challenge) {
 	const b = Buffer.from(challenge);
 	return a.length === b.length && timingSafeEqual(a, b);
 }
+// src/server/model-output-to-mcp.ts
+const DATA_URI = /^data:([^;,]*)((?:;[^;,]*)*),(.*)$/is;
+/**
+* Maps the value a Mastra tool's `toModelOutput` returns (an AI SDK tool-result output such as
+* `{ type: 'text' }`, `{ type: 'json' }` or `{ type: 'content', value: [...] }`) to MCP content blocks.
+*
+* Returns `undefined` for any other shape, meaning the caller keeps its default result.
+*/
+function modelOutputToMcpContent(value, toolName) {
+	if (!isRecord(value)) return void 0;
+	switch (value.type) {
+		case "text": return typeof value.value === "string" ? success([{
+			type: "text",
+			text: value.value
+		}]) : void 0;
+		case "json": return success([{
+			type: "text",
+			text: stringify(value.value)
+		}]);
+		case "error-text": return typeof value.value === "string" ? {
+			isError: true,
+			content: [{
+				type: "text",
+				text: value.value
+			}]
+		} : void 0;
+		case "error-json": return {
+			isError: true,
+			content: [{
+				type: "text",
+				text: stringify(value.value)
+			}]
+		};
+		case "content": return Array.isArray(value.value) ? success(value.value.map((part, index) => partToBlock(part, toolName, index))) : void 0;
+		default: return;
+	}
+}
+function partToBlock(part, toolName, index) {
+	if (!isRecord(part)) return {
+		type: "text",
+		text: stringify(part)
+	};
+	switch (part.type) {
+		case "text":
+			if (typeof part.text === "string") return {
+				type: "text",
+				text: part.text
+			};
+			break;
+		case "media":
+		case "image-data":
+		case "file-data": {
+			const fallback = part.type === "image-data" ? "image/jpeg" : "application/octet-stream";
+			const mediaType = typeof part.mediaType === "string" && part.mediaType ? part.mediaType : void 0;
+			if (typeof part.data === "string") {
+				const uri = parseDataUri(part.data);
+				if (uri) return mediaBlock(uri.data, mediaType ?? (uri.mediaType || fallback), toolName, index);
+				if (/^data:/i.test(part.data)) break;
+				return mediaBlock(part.data, mediaType ?? fallback, toolName, index);
+			}
+			if (part.data instanceof Uint8Array) return mediaBlock(Buffer.from(part.data).toString("base64"), mediaType ?? fallback, toolName, index);
+			break;
+		}
+		case "image-url":
+		case "file-url": {
+			if (typeof part.url !== "string") break;
+			const uri = parseDataUri(part.url);
+			if (!uri) return {
+				type: "text",
+				text: part.url
+			};
+			const fallback = part.type === "image-url" ? "image/jpeg" : "application/octet-stream";
+			const mediaType = typeof part.mediaType === "string" && part.mediaType ? part.mediaType : void 0;
+			return mediaBlock(uri.data, mediaType ?? (uri.mediaType || fallback), toolName, index);
+		}
+	}
+	return {
+		type: "text",
+		text: stringify(part)
+	};
+}
+function mediaBlock(data, mediaType, toolName, index) {
+	const separator = mediaType.indexOf(";");
+	const mimeType = separator === -1 ? mediaType.toLowerCase() : mediaType.slice(0, separator).toLowerCase() + mediaType.slice(separator);
+	if (mimeType.startsWith("image/")) return {
+		type: "image",
+		data,
+		mimeType
+	};
+	if (mimeType.startsWith("audio/")) return {
+		type: "audio",
+		data,
+		mimeType
+	};
+	return {
+		type: "resource",
+		resource: {
+			uri: `mastra://tool-output/${encodeURIComponent(toolName)}/${index}`,
+			mimeType,
+			blob: data
+		}
+	};
+}
+/**
+* Splits a `data:` URI into its media type (with parameters such as `charset`, minus the `base64`
+* marker) and Base64 payload. Returns `undefined` if it can't be decoded.
+*/
+function parseDataUri(value) {
+	const match = DATA_URI.exec(value);
+	if (!match) return void 0;
+	const [, type = "", params = "", payload = ""] = match;
+	const parameters = params.split(";").map((param) => param.trim()).filter(Boolean);
+	const base64 = parameters.some((param) => param.toLowerCase() === "base64");
+	let data = payload;
+	if (!base64) {
+		const bytes = decodePercentEncoded(payload);
+		if (!bytes) return void 0;
+		data = bytes.toString("base64");
+	}
+	const mediaType = type.trim().toLowerCase();
+	const kept = parameters.filter((param) => param.toLowerCase() !== "base64");
+	return {
+		mediaType: mediaType && kept.length ? [mediaType, ...kept].join(";") : mediaType,
+		data
+	};
+}
+/** Decodes `%XX` escapes as raw octets (RFC 2397), not UTF-8 text. Returns `undefined` for a malformed escape. */
+function decodePercentEncoded(payload) {
+	const input = Buffer.from(payload, "utf8");
+	const output = Buffer.alloc(input.length);
+	let length = 0;
+	for (let index = 0; index < input.length; index++) {
+		if (input[index] !== 37) {
+			output[length++] = input[index];
+			continue;
+		}
+		const hex = input.toString("latin1", index + 1, index + 3);
+		if (!/^[0-9a-f]{2}$/i.test(hex)) return void 0;
+		output[length++] = Number.parseInt(hex, 16);
+		index += 2;
+	}
+	return output.subarray(0, length);
+}
+function success(content) {
+	return {
+		isError: false,
+		content
+	};
+}
+function stringify(value) {
+	return JSON.stringify(value) ?? String(value);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 // src/server/tasks/store.ts
 /** How a principal is stored and shown. Principals can carry user and subject ids, so only their hash is kept. */
 function principalKeyOf(principal) {
@@ -22634,6 +22906,7 @@ var MCPServer = class extends MCPServerBase {
 	tasksInspector;
 	webhooks;
 	legacy;
+	toolResultOptions;
 	tasks;
 	/** Where tasks are kept: `tasks.store`, or the store picked on first use. */
 	taskStore;
@@ -22657,6 +22930,7 @@ var MCPServer = class extends MCPServerBase {
 		this.requestStateCodec = this.createRequestStateCodec(config.requestState);
 		this.eventsOptions = config.eventsOptions ?? {};
 		this.legacy = config.legacy ?? "reject";
+		this.toolResultOptions = config.toolResult ?? {};
 		this.tasks = resolveTasksConfig(config.tasks, {
 			tools: Object.keys(config.tools ?? {}),
 			workflows: Object.keys(config.workflows ?? {}),
@@ -23219,10 +23493,10 @@ var MCPServer = class extends MCPServerBase {
 		});
 		this.setTracedHandler(server, "tools/call", async (request, ctx, trace) => {
 			const name = request.params.name;
-			const tool = this.convertedTools[name];
+			const tool = Object.hasOwn(this.convertedTools, name) ? this.convertedTools[name] : void 0;
 			if (!tool) {
 				this.logger.warn("Unknown tool requested", { tool: name });
-				return errorResult$1(`Unknown tool: ${name}`);
+				throw new ProtocolError$1(ProtocolErrorCode$1.InvalidParams, `Unknown tool: ${name}`);
 			}
 			const args = request.params.arguments ?? {};
 			const argsHash = hashArguments(args);
@@ -23277,7 +23551,7 @@ var MCPServer = class extends MCPServerBase {
 						resumeSchema: execution.resumeSchema
 					});
 				}
-				const result = server.projectCallToolResult(this.toCallToolResult(name, tool, execution.output), this.toolInfo(name, tool).outputSchema);
+				const result = server.projectCallToolResult(await this.completedToolResult(name, tool, execution.output, requestContext), this.toolInfo(name, tool).outputSchema);
 				this.logger.info(`Tool '${name}' finished in ${Date.now() - startedAt}ms.`);
 				return result;
 			} catch (error) {
@@ -23344,7 +23618,7 @@ var MCPServer = class extends MCPServerBase {
 					suspendPayload: options.suspendPayload
 				},
 				initialAttempt: () => ({
-					outcome: settled.then((outcome) => "error" in outcome ? this.toolErrorOutcome(name, outcome.error) : this.toTaskOutcome(name, tool, outcome.execution)),
+					outcome: settled.then((outcome) => "error" in outcome ? this.toolErrorOutcome(name, outcome.error) : this.toTaskOutcome(name, tool, outcome.execution, requestContext)),
 					abort: (reason) => controller.abort(reason)
 				})
 			}) };
@@ -23455,7 +23729,7 @@ var MCPServer = class extends MCPServerBase {
 						suspendPayload,
 						tracingContext: span ? { currentSpan: span } : void 0
 					});
-					return this.toTaskOutcome(name, tool, execution);
+					return await this.toTaskOutcome(name, tool, execution, requestContext);
 				} catch (error) {
 					return this.toolErrorOutcome(name, error);
 				}
@@ -23539,7 +23813,8 @@ var MCPServer = class extends MCPServerBase {
 			}
 		};
 	}
-	toTaskOutcome(name, tool, execution) {
+	/** Never rejects: a failure building the result completes the task with the tool error result. */
+	async toTaskOutcome(name, tool, execution, requestContext) {
 		if (execution.status === "suspended") {
 			this.logger.debug(`Tool task '${name}' requires client input.`);
 			return {
@@ -23549,7 +23824,11 @@ var MCPServer = class extends MCPServerBase {
 			};
 		}
 		if (tool.mcp?.toolType === "agent" && execution.output?.finishReason === "suspended") return completed(errorResult$1(`Agent '${name.slice(4)}' paused for tool approval or input, which MCP tasks don't support yet`));
-		return completed(this.toCallToolResult(name, tool, execution.output));
+		try {
+			return completed(await this.completedToolResult(name, tool, execution.output, requestContext));
+		} catch (error) {
+			return this.toolErrorOutcome(name, error);
+		}
 	}
 	/** A tool that throws inside a task completes it with `isError`, as a synchronous call would answer. */
 	toolErrorOutcome(name, error) {
@@ -23864,6 +24143,34 @@ var MCPServer = class extends MCPServerBase {
 			output
 		};
 	}
+	/**
+	* The result of a tool call that completed: the default result, built from `toModelOutput` when
+	* `toolResult.modelOutput` is on, then passed through `toolResult.transform`. Throws what
+	* `toModelOutput` or `transform` throw.
+	*/
+	async completedToolResult(name, tool, output, requestContext) {
+		let result = this.toCallToolResult(name, tool, output);
+		const { modelOutput = false, transform } = this.toolResultOptions;
+		if (modelOutput && !result.isError && tool.toModelOutput && output != null) {
+			const mapped = modelOutputToMcpContent(await tool.toModelOutput(output), name);
+			if (mapped?.isError) result = {
+				isError: true,
+				content: mapped.content,
+				...result._meta ? { _meta: result._meta } : {}
+			};
+			else if (mapped) result = {
+				...result,
+				content: result.structuredContent !== void 0 ? [...result.content, ...mapped.content] : mapped.content
+			};
+		}
+		if (transform) result = await transform({
+			toolName: name,
+			output,
+			result,
+			requestContext
+		}) ?? result;
+		return result;
+	}
 	toCallToolResult(name, tool, value) {
 		if (isValidationError(value)) {
 			this.logger.warn(`Tool '${name}' rejected its input.`, { error: value.message });