feat: improve actor tool output

Author: MQ37

src/const.ts

@@ -8,6 +8,15 @@ export const ACTOR_RUN_DATASET_OUTPUT_MAX_ITEMS = 5;
 // Actor run const
 export const ACTOR_MAX_MEMORY_MBYTES = 4_096; // If the Actor requires 8GB of memory, free users can't run actors-mcp-server and requested Actor
 
+// Tool output
+/**
+ * Usual tool output limit is 25k tokens, let's use 20k
+ * just in case where 1 token =~ 4 characters thus 80k chars.
+ * This is primarily used for Actor tool call output, but we can then
+ * reuse this in other tools as well.
+ */
+export const TOOL_MAX_OUTPUT_CHARS = 80000;
+
 // MCP Server
 export const SERVER_NAME = 'apify-mcp-server';
 export const SERVER_VERSION = '1.0.0';
@@ -20,6 +29,7 @@ export enum HelperTools {
     ACTOR_CALL = 'call-actor',
     ACTOR_GET = 'get-actor',
     ACTOR_GET_DETAILS = 'fetch-actor-details',
+    ACTOR_OUTPUT_GET = 'get-actor-output',
     ACTOR_REMOVE = 'remove-actor',
     ACTOR_RUNS_ABORT = 'abort-actor-run',
     ACTOR_RUNS_GET = 'get-actor-run',
@@ -54,12 +64,12 @@ export const APIFY_DOCS_CACHE_MAX_SIZE = 500;
 export const APIFY_DOCS_CACHE_TTL_SECS = 60 * 60; // 1 hour
 
 export const ACTOR_PRICING_MODEL = {
-    /** Rental actors */
+    /** Rental Actors */
     FLAT_PRICE_PER_MONTH: 'FLAT_PRICE_PER_MONTH',
     FREE: 'FREE',
-    /** Pay per result (PPR) actors */
+    /** Pay per result (PPR) Actors */
     PRICE_PER_DATASET_ITEM: 'PRICE_PER_DATASET_ITEM',
-    /** Pay per event (PPE) actors */
+    /** Pay per event (PPE) Actors */
     PAY_PER_EVENT: 'PAY_PER_EVENT',
 } as const;
 

src/main.ts

@@ -44,10 +44,10 @@ if (STANDBY_MODE) {
         await Actor.fail('If you need to debug a specific Actor, please provide the debugActor and debugActorInput fields in the input');
     }
     const options = { memory: input.maxActorMemoryBytes } as ActorCallOptions;
-    const { items } = await callActorGetDataset(input.debugActor!, input.debugActorInput!, process.env.APIFY_TOKEN, options);
+    const { previewItems } = await callActorGetDataset(input.debugActor!, input.debugActorInput!, process.env.APIFY_TOKEN, options);
 
-    await Actor.pushData(items);
-    log.info('Pushed items to dataset', { itemCount: items.count });
+    await Actor.pushData(previewItems);
+    log.info('Pushed items to dataset', { itemCount: previewItems.length });
     await Actor.exit();
 }
 

src/mcp/proxy.ts

@@ -1,8 +1,8 @@
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import Ajv from 'ajv';
 
 import { fixedAjvCompile } from '../tools/utils.js';
 import type { ActorMcpTool, ToolEntry } from '../types.js';
+import { ajv } from '../utils/ajv.js';
 import { getMCPServerID, getProxyMCPServerToolName } from './utils.js';
 
 export async function getMCPServerTools(
@@ -14,8 +14,6 @@ export async function getMCPServerTools(
     const res = await client.listTools();
     const { tools } = res;
 
-    const ajv = new Ajv({ coerceTypes: 'array', strict: false });
-
     const compiledTools: ToolEntry[] = [];
     for (const tool of tools) {
         const mcpTool: ActorMcpTool = {

src/mcp/server.ts

@@ -31,6 +31,7 @@ import { prompts } from '../prompts/index.js';
 import { callActorGetDataset, defaultTools, getActorsAsTools, toolCategories } from '../tools/index.js';
 import { decodeDotPropertyNames } from '../tools/utils.js';
 import type { ActorMcpTool, ActorTool, HelperTool, ToolEntry } from '../types.js';
+import { buildActorResponseContent } from '../utils/actor-response.js';
 import { createProgressTracker } from '../utils/progress.js';
 import { getToolPublicFieldOnly } from '../utils/tools.js';
 import { connectMCPClient } from './client.js';
@@ -524,21 +525,15 @@ export class ActorsMcpServer {
 
                     try {
                         log.info('Calling Actor', { actorName: actorTool.actorFullName, input: args });
-                        const { runId, datasetId, items } = await callActorGetDataset(
+                        const callResult = await callActorGetDataset(
                             actorTool.actorFullName,
                             args,
                             apifyToken as string,
                             callOptions,
                             progressTracker,
                         );
-                        const content = [
-                            { type: 'text', text: `Actor finished with runId: ${runId}, datasetId ${datasetId}` },
-                        ];
 
-                        const itemContents = items.items.map((item: Record<string, unknown>) => {
-                            return { type: 'text', text: JSON.stringify(item) };
-                        });
-                        content.push(...itemContents);
+                        const content = buildActorResponseContent(actorTool.actorFullName, callResult);
                         return { content };
                     } finally {
                         if (progressTracker) {

src/tools/actor.ts

@@ -1,6 +1,5 @@
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { Ajv } from 'ajv';
-import type { ActorCallOptions, ActorRun, PaginatedList } from 'apify-client';
+import type { ActorCallOptions, ActorRun } from 'apify-client';
 import { z } from 'zod';
 import zodToJsonSchema from 'zod-to-json-schema';
 
@@ -11,41 +10,47 @@ import {
     ACTOR_ADDITIONAL_INSTRUCTIONS,
     ACTOR_MAX_MEMORY_MBYTES,
     HelperTools,
+    TOOL_MAX_OUTPUT_CHARS,
 } from '../const.js';
 import { getActorMCPServerPath, getActorMCPServerURL } from '../mcp/actors.js';
 import { connectMCPClient } from '../mcp/client.js';
 import { getMCPServerTools } from '../mcp/proxy.js';
 import { actorDefinitionPrunedCache } from '../state.js';
-import type { ActorDefinitionStorage, ActorInfo, ToolEntry } from '../types.js';
-import { getActorDefinitionStorageFieldNames } from '../utils/actor.js';
+import type { ActorDefinitionStorage, ActorInfo, DatasetItem, ToolEntry } from '../types.js';
+import { ensureOutputWithinCharLimit, getActorDefinitionStorageFieldNames } from '../utils/actor.js';
 import { fetchActorDetails } from '../utils/actor-details.js';
-import { getValuesByDotKeys } from '../utils/generic.js';
+import { buildActorResponseContent } from '../utils/actor-response.js';
+import { ajv } from '../utils/ajv.js';
 import type { ProgressTracker } from '../utils/progress.js';
+import type { JsonSchemaProperty } from '../utils/schema-generation.js';
+import { generateSchemaFromItems } from '../utils/schema-generation.js';
 import { getActorDefinition } from './build.js';
 import { actorNameToToolName, fixedAjvCompile, getToolSchemaID, transformActorInputSchemaProperties } from './utils.js';
 
-const ajv = new Ajv({ coerceTypes: 'array', strict: false });
-
 // Define a named return type for callActorGetDataset
 export type CallActorGetDatasetResult = {
     runId: string;
     datasetId: string;
-    items: PaginatedList<Record<string, unknown>>;
+    itemCount: number;
+    schema: JsonSchemaProperty;
+    previewItems: DatasetItem[];
 };
 
 /**
- * Calls an Apify actor and retrieves the dataset items.
+ * Calls an Apify Actor and retrieves metadata about the dataset results.
  *
+ * This function executes an Actor and returns summary information instead with a result items preview of the full dataset
+ * to prevent overwhelming responses. The actual data can be retrieved using the get-actor-output tool.
  *
  * It requires the `APIFY_TOKEN` environment variable to be set.
  * If the `APIFY_IS_AT_HOME` the dataset items are pushed to the Apify dataset.
  *
- * @param {string} actorName - The name of the actor to call.
- * @param {ActorCallOptions} callOptions - The options to pass to the actor.
+ * @param {string} actorName - The name of the Actor to call.
+ * @param {ActorCallOptions} callOptions - The options to pass to the Actor.
  * @param {unknown} input - The input to pass to the actor.
  * @param {string} apifyToken - The Apify token to use for authentication.
  * @param {ProgressTracker} progressTracker - Optional progress tracker for real-time updates.
- * @returns {Promise<{ actorRun: any, items: object[] }>} - A promise that resolves to an object containing the actor run and dataset items.
+ * @returns {Promise<CallActorGetDatasetResult>} - A promise that resolves to metadata about the Actor run and dataset.
  * @throws {Error} - Throws an error if the `APIFY_TOKEN` is not set
  */
 export async function callActorGetDataset(
@@ -59,7 +64,7 @@ export async function callActorGetDataset(
         const client = new ApifyClient({ token: apifyToken });
         const actorClient = client.actor(actorName);
 
-        // Start the actor run but don't wait for completion
+        // Start the Actor run but don't wait for completion
         const actorRun: ActorRun = await actorClient.start(input, callOptions);
 
         // Start progress tracking if tracker is provided
@@ -71,34 +76,45 @@ export async function callActorGetDataset(
         const completedRun = await client.run(actorRun.id).waitForFinish();
 
         const dataset = client.dataset(completedRun.defaultDatasetId);
-        const [items, defaultBuild] = await Promise.all([
+        const [datasetItems, defaultBuild] = await Promise.all([
             dataset.listItems(),
             (await actorClient.defaultBuild()).get(),
         ]);
 
-        // Get important properties from storage view definitions and if available return only those properties
+        // Generate schema using the shared utility
+        const generatedSchema = generateSchemaFromItems(datasetItems.items, {
+            clean: true,
+            arrayMode: 'all',
+        });
+        const schema = generatedSchema || { type: 'object', properties: {} };
+
+        /**
+         * Get important fields that are using in any dataset view as they MAY be used in filtering to ensure the output fits
+         * the tool output limits. Client has to use the get-actor-output tool to retrieve the full dataset or filtered out fields.
+         */
         const storageDefinition = defaultBuild?.actorDefinition?.storages?.dataset as ActorDefinitionStorage | undefined;
         const importantProperties = getActorDefinitionStorageFieldNames(storageDefinition || {});
-        if (importantProperties.length > 0) {
-            items.items = items.items.map((item) => {
-                return getValuesByDotKeys(item, importantProperties);
-            });
-        }
-
-        log.debug('Actor finished', { actorName, itemCount: items.count });
-        return { runId: actorRun.id, datasetId: completedRun.defaultDatasetId, items };
+        const previewItems = ensureOutputWithinCharLimit(datasetItems.items, importantProperties, TOOL_MAX_OUTPUT_CHARS);
+
+        return {
+            runId: actorRun.id,
+            datasetId: completedRun.defaultDatasetId,
+            itemCount: datasetItems.count,
+            schema,
+            previewItems,
+        };
     } catch (error) {
-        log.error('Error calling actor', { error, actorName, input });
+        log.error('Error calling Actor', { error, actorName, input });
         throw new Error(`Error calling Actor: ${error}`);
     }
 }
 
 /**
  * This function is used to fetch normal non-MCP server Actors as a tool.
  *
- * Fetches actor input schemas by Actor IDs or Actor full names and creates MCP tools.
+ * Fetches Actor input schemas by Actor IDs or Actor full names and creates MCP tools.
  *
- * This function retrieves the input schemas for the specified actors and compiles them into MCP tools.
+ * This function retrieves the input schemas for the specified Actors and compiles them into MCP tools.
  * It uses the AJV library to validate the input schemas.
  *
  * Tool name can't contain /, so it is replaced with _
@@ -201,7 +217,7 @@ export async function getActorsAsTools(
     actorIdsOrNames: string[],
     apifyToken: string,
 ): Promise<ToolEntry[]> {
-    log.debug('Fetching actors as tools', { actorNames: actorIdsOrNames });
+    log.debug('Fetching Actors as tools', { actorNames: actorIdsOrNames });
 
     const actorsInfo: (ActorInfo | null)[] = await Promise.all(
         actorIdsOrNames.map(async (actorIdOrName) => {
@@ -298,7 +314,7 @@ The step parameter enforces this workflow - you cannot call an Actor without fir
 
             try {
                 if (step === 'info') {
-                    // Step 1: Return actor card and schema directly
+                    // Step 1: Return Actor card and schema directly
                     const details = await fetchActorDetails(apifyToken, actorName);
                     if (!details) {
                         return {
@@ -342,23 +358,15 @@ The step parameter enforces this workflow - you cannot call an Actor without fir
                     }
                 }
 
-                const { runId, datasetId, items } = await callActorGetDataset(
+                const callResult = await callActorGetDataset(
                     actorName,
                     input,
                     apifyToken,
                     callOptions,
                     progressTracker,
                 );
 
-                const content = [
-                    { type: 'text', text: `Actor finished with runId: ${runId}, datasetId ${datasetId}` },
-                ];
-
-                const itemContents = items.items.map((item: Record<string, unknown>) => ({
-                    type: 'text',
-                    text: JSON.stringify(item),
-                }));
-                content.push(...itemContents);
+                const content = buildActorResponseContent(actorName, callResult);
 
                 return { content };
             } catch (error) {

src/tools/build.ts

@@ -1,4 +1,3 @@
-import { Ajv } from 'ajv';
 import { z } from 'zod';
 import zodToJsonSchema from 'zod-to-json-schema';
 
@@ -13,10 +12,9 @@ import type {
     ISchemaProperties,
     ToolEntry,
 } from '../types.js';
+import { ajv } from '../utils/ajv.js';
 import { filterSchemaProperties, shortenProperties } from './utils.js';
 
-const ajv = new Ajv({ coerceTypes: 'array', strict: false });
-
 /**
  * Get Actor input schema by Actor name.
  * First, fetch the Actor details to get the default build tag and buildId.