@apify/actors-mcp-server 0.10.5-beta.0 → 0.10.5-beta.10

package/dist/mcp/server.js

@@ -8,7 +8,7 @@ import { randomUUID } from 'node:crypto';
 import { getUiCapability, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/server';
 import { InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental/tasks/stores/in-memory.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { CallToolRequestSchema, CallToolResultSchema, CancelTaskRequestSchema, ErrorCode, GetPromptRequestSchema, GetTaskPayloadRequestSchema, GetTaskRequestSchema, InitializeRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListTasksRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, ServerNotificationSchema, SetLevelRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, CallToolResultSchema, CancelTaskRequestSchema, ErrorCode, GetPromptRequestSchema, GetTaskPayloadRequestSchema, GetTaskRequestSchema, InitializeRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListTasksRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, RELATED_TASK_META_KEY, ServerNotificationSchema, SetLevelRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import dedent from 'dedent';
 import log from '@apify/log';
 import { parseBooleanOrNull } from '@apify/utilities';
@@ -19,14 +19,13 @@ import { prompts } from '../prompts/index.js';
 import { createResourceService } from '../resources/resource_service.js';
 import { resolveAvailableWidgets } from '../resources/widgets.js';
 import { getTelemetryEnv, trackToolCall } from '../telemetry.js';
-import { appsActorExecutor } from '../tools/apps/actor_executor.js';
+import { actorExecutor } from '../tools/actor_executor.js';
 import { buildPermissionApprovalResponse, isPermissionApprovalError } from '../tools/core/call_actor_common.js';
-import { defaultActorExecutor } from '../tools/default/actor_executor.js';
 import { getActorsAsTools } from '../tools/index.js';
 import { decodeDotPropertyNames, legacyToolNameToNew } from '../tools/utils.js';
 import { ServerMode } from '../types.js';
 import { getHttpStatusCode, logHttpError } from '../utils/logging.js';
-import { buildMCPResponse, getToolCallErrorUserText } from '../utils/mcp.js';
+import { buildMCPResponse, computeToolResponseSizeBytes, getToolCallErrorUserText } from '../utils/mcp.js';
 import { buildPaymentRequiredResponse } from '../utils/payment_errors.js';
 import { createProgressTracker } from '../utils/progress.js';
 import { parseServerMode, resolveServerMode } from '../utils/server_mode.js';
@@ -39,11 +38,6 @@ import { getPackageVersion } from '../utils/version.js';
 import { connectMCPClient } from './client.js';
 import { EXTERNAL_TOOL_CALL_TIMEOUT_MSEC, LOG_LEVEL_MAP } from './const.js';
 import { createTaskCancellationWatcher, isTaskCancelled, parseInputParamsFromUrl } from './utils.js';
-/** Mode → actor executor. Add new modes here. */
-const actorExecutorsByMode = {
-    [ServerMode.DEFAULT]: defaultActorExecutor,
-    [ServerMode.APPS]: appsActorExecutor,
-};
 /**
  * Returns true when the initialize request advertises the MCP Apps UI extension
  * with the widget MIME type. Used to resolve `'auto'` server mode.
@@ -57,6 +51,33 @@ function isUiSupportedByClient(request) {
     const uiCap = getUiCapability((_a = request === null || request === void 0 ? void 0 : request.params) === null || _a === void 0 ? void 0 : _a.capabilities);
     return (_c = (_b = uiCap === null || uiCap === void 0 ? void 0 : uiCap.mimeTypes) === null || _b === void 0 ? void 0 : _b.includes(RESOURCE_MIME_TYPE)) !== null && _c !== void 0 ? _c : false;
 }
+/** Send notifications/tasks/status for taskId. Routes via session transport (no relatedRequestId).
+ *  Swallows errors — notifications are advisory. */
+export async function emitTaskStatusNotification(taskId, mcpSessionId, taskStore, server) {
+    try {
+        const task = await taskStore.getTask(taskId, mcpSessionId);
+        if (!task)
+            return;
+        // Per spec: notifications/tasks/status MUST NOT carry _meta.related-task (task ID is in params).
+        // Called without options so the notification routes through the session transport,
+        // not the request-scoped stream (which closes once the initial { task } response is flushed).
+        await server.notification({
+            method: 'notifications/tasks/status',
+            params: {
+                taskId: task.taskId,
+                status: task.status,
+                createdAt: task.createdAt,
+                lastUpdatedAt: task.lastUpdatedAt,
+                ttl: task.ttl,
+                ...(task.statusMessage != null && { statusMessage: task.statusMessage }),
+                ...(task.pollInterval != null && { pollInterval: task.pollInterval }),
+            },
+        });
+    }
+    catch {
+        // Silent fail — notifications are advisory
+    }
+}
 /**
  * Create Apify MCP server
  */
@@ -121,13 +142,6 @@ export class ActorsMcpServer {
             writable: true,
             value: void 0
         });
-        /** Mode-specific executor for direct actor tools (`type: 'actor'`). Finalized with `serverMode`. */
-        Object.defineProperty(this, "actorExecutor", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
         /**
          * Raw option captured from `options.serverMode` (or the legacy `uiMode`). Re-resolved
          * inside the initialize handler when set to `'auto'`; explicit `'default'`/`'apps'`
@@ -211,7 +225,6 @@ export class ActorsMcpServer {
         // client capabilities are known (only for 'auto').
         this.serverMode = resolveServerMode(this.serverModeOption, false);
         this.serverModeResolved = this.serverModeOption !== 'auto';
-        this.actorExecutor = actorExecutorsByMode[this.serverMode];
         const { setupSigintHandler = true } = options;
         this.server = new Server({
             name: SERVER_NAME,
@@ -300,7 +313,6 @@ export class ActorsMcpServer {
                 const resolved = resolveServerMode('auto', this.clientSupportsUi);
                 if (resolved !== this.serverMode) {
                     this.serverMode = resolved;
-                    this.actorExecutor = actorExecutorsByMode[this.serverMode];
                 }
                 this.serverModeResolved = true;
             }
@@ -684,7 +696,15 @@ export class ActorsMcpServer {
             if (task.status !== 'completed' && task.status !== 'failed') {
                 throw new McpError(ErrorCode.InvalidParams, `Task "${taskId}" is not completed yet. Current status: ${task.status}`);
             }
-            return await this.taskStore.getTaskResult(taskId, mcpSessionId);
+            const result = await this.taskStore.getTaskResult(taskId, mcpSessionId);
+            // taskId is not in the result body — _meta.related-task lets clients correlate them
+            return {
+                ...result,
+                _meta: {
+                    ...result._meta,
+                    [RELATED_TASK_META_KEY]: { taskId },
+                },
+            };
         });
         // Cancel task
         this.server.setRequestHandler(CancelTaskRequestSchema, async (request) => {
@@ -713,6 +733,7 @@ export class ActorsMcpServer {
             await this.taskStore.updateTaskStatus(taskId, 'cancelled', 'Cancelled by client', mcpSessionId);
             const updatedTask = await this.taskStore.getTask(taskId, mcpSessionId);
             log.debug('[CancelTaskRequestSchema] Task cancelled successfully', { taskId, mcpSessionId });
+            await emitTaskStatusNotification(taskId, mcpSessionId, this.taskStore, this.server);
             return updatedTask;
         });
     }
@@ -755,6 +776,12 @@ export class ActorsMcpServer {
             let callDiagnostics = {};
             let shouldTrackTelemetry = true;
             let resolvedToolName = name;
+            // Captured by `captureResult` so the `finally` block can measure response size for telemetry.
+            let toolResult = null;
+            const captureResult = (r) => {
+                toolResult = r;
+                return r;
+            };
             const failInvalidParams = async (message, details, logFields) => {
                 toolStatus = TOOL_STATUS.SOFT_FAIL;
                 callDiagnostics = details;
@@ -869,11 +896,11 @@ export class ActorsMcpServer {
                 if (request.params.task) {
                     const task = await this.taskStore.createTask({
                         ttl: request.params.task.ttl,
-                    }, `call-tool-${name}-${randomUUID()}`, request);
+                    }, `call-tool-${name}-${randomUUID()}`, request, mcpSessionId);
                     log.debug('Created task for tool execution', { taskId: task.taskId, toolName: tool.name, mcpSessionId });
                     // Execute the tool asynchronously and update task status
-                    setImmediate(async () => {
-                        await this.executeToolAndUpdateTask({
+                    setImmediate(() => {
+                        this.executeToolAndUpdateTask({
                             taskId: task.taskId,
                             tool,
                             toolArgs: toolArgs,
@@ -887,7 +914,7 @@ export class ActorsMcpServer {
                             actorName,
                             actorId,
                             userRentedActorIds,
-                        });
+                        }).catch((error) => log.error('executeToolAndUpdateTask failed unexpectedly', { taskId: task.taskId, error }));
                     });
                     // Return the task immediately; execution continues asynchronously
                     shouldTrackTelemetry = false;
@@ -901,12 +928,15 @@ export class ActorsMcpServer {
                         failure_http_status: 402,
                         ...buildActorFields(actorName, actorId),
                     };
-                    return paymentRequiredResult;
+                    return captureResult(paymentRequiredResult);
                 }
                 // Handle internal tool
                 if (tool.type === 'internal') {
-                    // Only create a progress tracker for call-actor tool
-                    const progressTracker = tool.name === 'call-actor'
+                    // Tools that may emit notifications/progress during a sync wait must be opted in here.
+                    // call-actor: emits during start+waitForFinish. get-actor-run: emits when waitSecs > 0.
+                    const progressTrackerOptIn = tool.name === HelperTools.ACTOR_CALL
+                        || tool.name === HelperTools.ACTOR_RUNS_GET;
+                    const progressTracker = progressTrackerOptIn
                         ? createProgressTracker(progressToken, extra.sendNotification)
                         : null;
                     try {
@@ -926,7 +956,7 @@ export class ActorsMcpServer {
                         const diag = extractToolTelemetry(res, actorName, actorId);
                         toolStatus = diag.toolStatus;
                         callDiagnostics = { ...callDiagnostics, ...diag.callDiagnostics };
-                        return res;
+                        return captureResult(res);
                     }
                     finally {
                         progressTracker === null || progressTracker === void 0 ? void 0 : progressTracker.stop();
@@ -945,7 +975,7 @@ export class ActorsMcpServer {
                             await this.server.sendLoggingMessage({ level: 'error', data: msg });
                             toolStatus = TOOL_STATUS.SOFT_FAIL;
                             callDiagnostics = { ...callDiagnostics, failure_category: FAILURE_CATEGORY.INTERNAL_ERROR };
-                            return buildMCPResponse({ texts: [msg], isError: true });
+                            return captureResult(buildMCPResponse({ texts: [msg], isError: true }));
                         }
                         // Only set up notification handlers if progressToken is provided by the client
                         if (progressToken !== undefined && progressToken !== null) {
@@ -985,7 +1015,7 @@ export class ActorsMcpServer {
                             toolStatus = TOOL_STATUS.SOFT_FAIL;
                             callDiagnostics = { failure_category: FAILURE_CATEGORY.INTERNAL_ERROR, ...buildActorFields(actorName, actorId) };
                         }
-                        return { ...res };
+                        return captureResult({ ...res });
                     }
                     catch (error) {
                         toolStatus = getToolStatusFromError(error, Boolean((_e = extra.signal) === null || _e === void 0 ? void 0 : _e.aborted));
@@ -1000,10 +1030,10 @@ export class ActorsMcpServer {
                             toolName: tool.originToolName,
                             failureCategory: callDiagnostics.failure_category,
                         });
-                        return buildMCPResponse({
+                        return captureResult(buildMCPResponse({
                             texts: [`Failed to call MCP tool '${tool.originToolName}' on Actor '${tool.actorId}': ${error instanceof Error ? error.message : String(error)}. The MCP server may be temporarily unavailable.`],
                             isError: true,
-                        });
+                        }));
                     }
                     finally {
                         if (client)
@@ -1015,7 +1045,7 @@ export class ActorsMcpServer {
                     const progressTracker = createProgressTracker(progressToken, extra.sendNotification);
                     try {
                         log.info('Calling Actor', { toolName: tool.name, actorName: tool.actorFullName, mcpSessionId, input: logSafeArgs });
-                        const executorResult = await this.actorExecutor.executeActorTool({
+                        const executorResult = await actorExecutor.executeActorTool({
                             actorFullName: tool.actorFullName,
                             input: toolArgs,
                             apifyClient: apifyClient,
@@ -1023,14 +1053,15 @@ export class ActorsMcpServer {
                             progressTracker,
                             abortSignal: extra.signal,
                             mcpSessionId,
+                            datasetItemsSchema: tool.datasetItemsSchema,
                         });
                         if (!executorResult) {
                             toolStatus = TOOL_STATUS.ABORTED;
                             // Receivers of cancellation notifications SHOULD NOT send a response for the cancelled request
                             // https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/cancellation#behavior-requirements
-                            return {};
+                            return captureResult({});
                         }
-                        return executorResult;
+                        return captureResult(executorResult);
                     }
                     finally {
                         if (progressTracker) {
@@ -1052,7 +1083,7 @@ export class ActorsMcpServer {
                         failure_http_status: 402,
                         ...buildActorFields(actorName, actorId),
                     };
-                    return buildPaymentRequiredResponse(error);
+                    return captureResult(buildPaymentRequiredResponse(error));
                 }
                 if (isPermissionApprovalError(error)) {
                     toolStatus = TOOL_STATUS.SOFT_FAIL;
@@ -1062,7 +1093,7 @@ export class ActorsMcpServer {
                         ...buildActorFields(actorName, actorId),
                     };
                     logHttpError(error, 'Permission approval required while calling tool', { toolName: name, mcpSessionId });
-                    return buildPermissionApprovalResponse(error);
+                    return captureResult(buildPermissionApprovalResponse(error));
                 }
                 // Re-throw MCP protocol errors (e.g. from failInvalidParams) so the SDK
                 // returns them as JSON-RPC errors. failInvalidParams already set callDiagnostics
@@ -1093,11 +1124,11 @@ export class ActorsMcpServer {
                     validationMissingProperty: callDiagnostics.validation_missing_property,
                     validationAdditionalProperty: callDiagnostics.validation_additional_property,
                 });
-                return buildMCPResponse({
+                return captureResult(buildMCPResponse({
                     texts: [getToolCallErrorUserText(name, error)],
                     isError: true,
                     telemetry: { toolStatus },
-                });
+                }));
             }
             finally {
                 if (shouldTrackTelemetry) {
@@ -1109,6 +1140,7 @@ export class ActorsMcpServer {
                         telemetryData,
                         userId,
                         callDiagnostics,
+                        responseSizeBytes: computeToolResponseSizeBytes(toolResult),
                     });
                 }
             }
@@ -1137,6 +1169,7 @@ export class ActorsMcpServer {
             mcpSessionId: params.mcpSessionId,
             toolStatus: params.toolStatus,
             durationMs,
+            ...(params.responseSizeBytes !== undefined && { responseSizeBytes: params.responseSizeBytes }),
             ...(params.taskId !== undefined && { taskId: params.taskId }),
         });
         if (params.telemetryData) {
@@ -1144,6 +1177,7 @@ export class ActorsMcpServer {
                 ...params.telemetryData,
                 tool_status: params.toolStatus,
                 tool_exec_time_ms: durationMs,
+                ...(params.responseSizeBytes !== undefined && { tool_response_size_bytes: params.responseSizeBytes }),
                 // Always include actor_name/actor_id; failure-specific fields are only present when callDiagnostics has them.
                 ...params.callDiagnostics,
             };
@@ -1177,7 +1211,7 @@ export class ActorsMcpServer {
         // Prepare telemetry before try-catch so it's accessible to both paths.
         // This avoids re-fetching user data in the error handler.
         const { telemetryData, userId } = await this.prepareTelemetryData(getToolFullName(tool), mcpSessionId, apifyToken);
-        const finishTaskTracking = (status, diagnostics) => {
+        const finishTaskTracking = (status, diagnostics, responseSizeBytes) => {
             this.logToolCallAndTelemetry({
                 toolName: tool.name,
                 mcpSessionId,
@@ -1187,6 +1221,7 @@ export class ActorsMcpServer {
                 telemetryData,
                 userId,
                 callDiagnostics: diagnostics,
+                responseSizeBytes,
             });
         };
         // Once a task is cancelled the spec forbids writing a result; every storage path
@@ -1229,6 +1264,7 @@ export class ActorsMcpServer {
                     return;
                 throw err;
             }
+            await emitTaskStatusNotification(taskId, mcpSessionId, this.taskStore, this.server);
             // Execute the tool and get the result
             let result = {};
             // Check payment validation (already computed by prepareToolCallContext in the caller)
@@ -1241,13 +1277,12 @@ export class ActorsMcpServer {
                 };
                 result = paymentRequiredResult;
             }
-            // Callback to propagate Actor run statusMessage into the task store.
-            // Clients retrieve it via tasks/get and tasks/list polling.
-            // TODO: Also send notifications/tasks/status so clients get real-time push updates
+            // Callback to propagate Actor run statusMessage into the task store and emit a push notification.
             // TODO(TC-3): cancel arriving while this is scheduled throws cancelled → working;
             // currently swallowed by progress.ts's tick catch — guard or catch explicitly.
             const onStatusMessage = async (message) => {
                 await this.taskStore.updateTaskStatus(taskId, 'working', message, mcpSessionId);
+                await emitTaskStatusNotification(taskId, mcpSessionId, this.taskStore, this.server);
             };
             // Handle internal tool execution in task mode
             if (toolStatus === TOOL_STATUS.SUCCEEDED && tool.type === 'internal') {
@@ -1264,6 +1299,7 @@ export class ActorsMcpServer {
                         userRentedActorIds,
                         progressTracker,
                         mcpSessionId,
+                        taskMode: true,
                     });
                     const diag = extractToolTelemetry(res, actorName, actorId);
                     toolStatus = diag.toolStatus;
@@ -1281,7 +1317,7 @@ export class ActorsMcpServer {
                 const progressTracker = createProgressTracker(progressToken, extra.sendNotification, taskId, onStatusMessage);
                 try {
                     log.info('Calling Actor for task', { taskId, toolName: tool.name, actorName: tool.actorFullName, mcpSessionId, input: logSafeArgs });
-                    const executorResult = await this.actorExecutor.executeActorTool({
+                    const executorResult = await actorExecutor.executeActorTool({
                         actorFullName: tool.actorFullName,
                         input: toolArgs,
                         apifyClient,
@@ -1289,6 +1325,8 @@ export class ActorsMcpServer {
                         progressTracker,
                         abortSignal: cancelWatcher.signal,
                         mcpSessionId,
+                        datasetItemsSchema: tool.datasetItemsSchema,
+                        taskMode: true,
                     });
                     if (!executorResult) {
                         toolStatus = TOOL_STATUS.ABORTED;
@@ -1316,7 +1354,8 @@ export class ActorsMcpServer {
             });
             await this.taskStore.storeTaskResult(taskId, 'completed', result, mcpSessionId);
             log.debug('Task completed successfully', { taskId, toolName: tool.name, mcpSessionId });
-            finishTaskTracking(toolStatus, callDiagnostics);
+            await emitTaskStatusNotification(taskId, mcpSessionId, this.taskStore, this.server);
+            finishTaskTracking(toolStatus, callDiagnostics, computeToolResponseSizeBytes(result));
         }
         catch (error) {
             // Handle 402 Payment Required — return structured x402 result so clients can auto-pay
@@ -1327,12 +1366,14 @@ export class ActorsMcpServer {
                 // so guard storeTaskResult against a cancel that raced with this 402.
                 if (await skipIfTaskCancelled(', skipping 402 result storage', TOOL_STATUS.ABORTED, { ...buildActorFields(actorName, actorId) }))
                     return;
-                await this.taskStore.storeTaskResult(taskId, 'completed', buildPaymentRequiredResponse(error), mcpSessionId);
+                const paymentResponse = buildPaymentRequiredResponse(error);
+                await this.taskStore.storeTaskResult(taskId, 'completed', paymentResponse, mcpSessionId);
+                await emitTaskStatusNotification(taskId, mcpSessionId, this.taskStore, this.server);
                 finishTaskTracking(TOOL_STATUS.SOFT_FAIL, {
                     failure_category: FAILURE_CATEGORY.INVALID_INPUT,
                     failure_http_status: 402,
                     ...buildActorFields(actorName, actorId),
-                });
+                }, computeToolResponseSizeBytes(paymentResponse));
                 return;
             }
             if (isPermissionApprovalError(error)) {
@@ -1341,12 +1382,14 @@ export class ActorsMcpServer {
                 // so guard storeTaskResult against a cancel that raced with this approval error.
                 if (await skipIfTaskCancelled(', skipping permission-approval result storage', TOOL_STATUS.ABORTED, { ...buildActorFields(actorName, actorId) }))
                     return;
-                await this.taskStore.storeTaskResult(taskId, 'completed', buildPermissionApprovalResponse(error), mcpSessionId);
+                const approvalResponse = buildPermissionApprovalResponse(error);
+                await this.taskStore.storeTaskResult(taskId, 'completed', approvalResponse, mcpSessionId);
+                await emitTaskStatusNotification(taskId, mcpSessionId, this.taskStore, this.server);
                 finishTaskTracking(TOOL_STATUS.SOFT_FAIL, {
                     failure_category: FAILURE_CATEGORY.PERMISSION_APPROVAL_REQUIRED,
                     failure_http_status: error.statusCode,
                     ...buildActorFields(actorName, actorId),
-                });
+                }, computeToolResponseSizeBytes(approvalResponse));
                 return;
             }
             toolStatus = getToolStatusFromError(error, Boolean(cancelWatcher.signal.aborted));
@@ -1395,15 +1438,17 @@ export class ActorsMcpServer {
                 taskId,
                 mcpSessionId,
             });
-            await this.taskStore.storeTaskResult(taskId, 'failed', {
+            const failedResult = {
                 content: [{
                         type: 'text',
                         text: userText,
                     }],
                 isError: true,
                 internalToolStatus: toolStatus,
-            }, mcpSessionId);
-            finishTaskTracking(toolStatus, callDiagnostics);
+            };
+            await this.taskStore.storeTaskResult(taskId, 'failed', failedResult, mcpSessionId);
+            await emitTaskStatusNotification(taskId, mcpSessionId, this.taskStore, this.server);
+            finishTaskTracking(toolStatus, callDiagnostics, computeToolResponseSizeBytes(failedResult));
         }
         finally {
             cancelWatcher.dispose();