feat: add outputSchema option to fetch-actor-details tools (#413)

* feat: add outputSchema option to fetch-actor-details tools

- Add outputSchema boolean option to actorDetailsOutputOptionsSchema
- Pass actorOutputSchema through meta from internal server
- Add typeObjectToString utility for human-readable type display
- Include outputSchema in structured response content
- Update fetch-actor-details and fetch-actor-details-internal tools

* feat: add previewOutput option to call-actor tool and fix outputSchema type

## Summary

- Add optional `previewOutput` parameter (default: true) to call-actor tool for controlling dataset preview in responses
- Fix `outputSchema` field type in actorDetailsOutputSchema from string to object
- Reduce context clutter when users plan to fetch specific fields via get-actor-output tool

## Technical Changes

- Add `previewOutput` boolean parameter to callActorArgs Zod schema with contextual description
- Pass `previewOutput` through callActorGetDataset to conditionally skip preview items extraction
- Update buildActorResponseContent to handle both preview modes with appropriate messaging
- Change actorDetailsOutputSchema.outputSchema type from 'string' to 'object' to match actual data
- Add 2 integration tests for previewOutput feature (true and false modes)

## Backward Compatibility

- previewOutput defaults to true, maintaining existing behavior
- No breaking changes to public API

Author: MQ37

src/mcp/server.ts

@@ -617,6 +617,7 @@ export class ActorsMcpServer {
             const metaApifyToken = meta?.apifyToken;
             const apifyToken = (metaApifyToken || this.options.token || process.env.APIFY_TOKEN) as string;
             const userRentedActorIds = meta?.userRentedActorIds;
+            const actorOutputSchema = meta?.actorOutputSchema;
             // mcpSessionId was injected upstream it is important and required for long running tasks as the store uses it and there is not other way to pass it
             const mcpSessionId = meta?.mcpSessionId;
             if (!mcpSessionId) {
@@ -764,6 +765,7 @@ Please remove the "task" parameter from the tool call request or use a different
                         mcpServer: this.server,
                         apifyToken,
                         userRentedActorIds,
+                        actorOutputSchema,
                         progressTracker,
                     }) as object;
 

src/tools/actor.ts

@@ -65,6 +65,7 @@ export async function callActorGetDataset(
     callOptions: ActorCallOptions | undefined = undefined,
     progressTracker?: ProgressTracker | null,
     abortSignal?: AbortSignal,
+    previewOutput = true,
 ): Promise<CallActorGetDatasetResult | null> {
     const CLIENT_ABORT = Symbol('CLIENT_ABORT'); // Just internal symbol to identify client abort
     const actorClient = apifyClient.actor(actorName);
@@ -123,7 +124,9 @@ export async function callActorGetDataset(
      */
     const storageDefinition = defaultBuild?.actorDefinition?.storages?.dataset as ActorDefinitionStorage | undefined;
     const importantProperties = getActorDefinitionStorageFieldNames(storageDefinition || {});
-    const previewItems = ensureOutputWithinCharLimit(datasetItems.items, importantProperties, TOOL_MAX_OUTPUT_CHARS);
+    const previewItems = previewOutput
+        ? ensureOutputWithinCharLimit(datasetItems.items, importantProperties, TOOL_MAX_OUTPUT_CHARS)
+        : [];
 
     return {
         runId: actorRun.id,
@@ -345,6 +348,9 @@ For MCP server Actors, use format "actorName:toolName" to call a specific tool (
     async: z.boolean()
         .optional()
         .describe(`When true: starts the run and returns immediately with runId. When false or not provided: waits for completion and returns results immediately. Default: true when UI mode is enabled (enforced), false otherwise. Note: When UI mode is enabled, async is always true regardless of this parameter and the widget automatically tracks progress.`),
+    previewOutput: z.boolean()
+        .optional()
+        .describe('When true (default): includes preview items. When false: metadata only (reduces context). Use when fetching fields via get-actor-output.'),
     callOptions: z.object({
         memory: z.number()
             .min(128, 'Memory must be at least 128 MB')
@@ -432,7 +438,7 @@ export const callActor: ToolEntry = {
     },
     call: async (toolArgs: InternalToolArgs) => {
         const { args, apifyToken, progressTracker, extra, apifyMcpServer } = toolArgs;
-        const { actor: actorName, input, async, callOptions } = callActorArgs.parse(args);
+        const { actor: actorName, input, async, previewOutput = true, callOptions } = callActorArgs.parse(args);
 
         // Parse special format: actor:tool
         const mcpToolMatch = actorName.match(/^(.+):(.+)$/);
@@ -605,6 +611,7 @@ Do NOT proactively poll using ${HelperTools.ACTOR_RUNS_GET}. Wait for the widget
                 callOptions,
                 progressTracker,
                 extra.signal,
+                previewOutput,
             );
 
             if (!callResult) {
@@ -613,7 +620,7 @@ Do NOT proactively poll using ${HelperTools.ACTOR_RUNS_GET}. Wait for the widget
                 return {};
             }
 
-            const content = buildActorResponseContent(actorName, callResult);
+            const content = buildActorResponseContent(actorName, callResult, previewOutput);
 
             return { content };
         } catch (error) {

src/tools/fetch-actor-details-internal.ts

@@ -49,7 +49,7 @@ but the user did NOT explicitly ask for Actor details presentation.`,
         openWorldHint: false,
     },
     call: async (toolArgs: InternalToolArgs) => {
-        const { args, apifyToken, apifyMcpServer } = toolArgs;
+        const { args, apifyToken, apifyMcpServer, actorOutputSchema } = toolArgs;
         const parsed = fetchActorDetailsInternalArgsSchema.parse(args);
         const apifyClient = new ApifyClient({ token: apifyToken });
 
@@ -68,6 +68,7 @@ but the user did NOT explicitly ask for Actor details presentation.`,
             cardOptions,
             apifyClient,
             apifyToken,
+            actorOutputSchema,
             skyfireMode: apifyMcpServer?.options.skyfireMode,
         });
 

src/tools/fetch-actor-details.ts

@@ -54,7 +54,7 @@ EXAMPLES:
         openWorldHint: false,
     },
     call: async (toolArgs: InternalToolArgs) => {
-        const { args, apifyToken, apifyMcpServer } = toolArgs;
+        const { args, apifyToken, apifyMcpServer, actorOutputSchema } = toolArgs;
         const parsed = fetchActorDetailsToolArgsSchema.parse(args);
         const apifyClient = new ApifyClient({ token: apifyToken });
 
@@ -106,6 +106,7 @@ An interactive widget has been rendered with detailed Actor information.
             cardOptions,
             apifyClient,
             apifyToken,
+            actorOutputSchema,
             skyfireMode: apifyMcpServer?.options.skyfireMode,
         });
 

src/tools/structured-output-schemas.ts

@@ -128,6 +128,7 @@ export const actorDetailsOutputSchema = {
         actorInfo: actorInfoSchema,
         readme: { type: 'string', description: 'Actor README documentation.' },
         inputSchema: { type: 'object' as const, description: 'Actor input schema.' }, // Literal type required for MCP SDK type compatibility
+        outputSchema: { type: 'object' as const, description: 'Output schema inferred from successful runs.' },
     },
 };
 

src/types.ts

@@ -128,6 +128,8 @@ export type InternalToolArgs = {
     apifyToken: string;
     /** List of Actor IDs that the user has rented */
     userRentedActorIds?: string[];
+    /** Actor output schema as type object (injected by internal server) */
+    actorOutputSchema?: Record<string, unknown> | null;
     /** Optional progress tracker for long running internal tools, like call-actor */
     progressTracker?: ProgressTracker | null;
 };
@@ -459,6 +461,8 @@ export type ApifyRequestParams = {
         apifyToken?: string;
         /** List of Actor IDs that the user has rented */
         userRentedActorIds?: string[];
+        /** Actor output schema as type object (injected by internal server) */
+        actorOutputSchema?: Record<string, unknown> | null;
         /** Progress token for out-of-band progress notifications (standard MCP) */
         progressToken?: string | number;
         /** Allow other metadata fields */

src/utils/actor-details.ts

@@ -11,6 +11,50 @@ import { formatActorToActorCard, formatActorToStructuredCard } from './actor-car
 import { logHttpError } from './logging.js';
 import { buildMCPResponse } from './mcp.js';
 
+/**
+ * Convert a type object to TypeScript-like string representation.
+ * Used for human-readable text output.
+ *
+ * Example:
+ * Input:  { first_number: "number", tags: ["string"], user: { name: "string" } }
+ * Output: "{ first_number: number, tags: string[], user: { name: string } }"
+ */
+function typeObjectToString(obj: Record<string, unknown>): string {
+    const pairs: string[] = [];
+
+    for (const [key, value] of Object.entries(obj)) {
+        if (Array.isArray(value)) {
+            // Array type
+            const itemType = typeValueToString(value[0]);
+            pairs.push(`${key}: ${itemType}[]`);
+        } else if (typeof value === 'object' && value !== null) {
+            // Nested object type
+            const nestedStr = typeObjectToString(value as Record<string, unknown>);
+            pairs.push(`${key}: ${nestedStr}`);
+        } else if (typeof value === 'string') {
+            // Primitive type
+            pairs.push(`${key}: ${value}`);
+        }
+    }
+
+    return `{ ${pairs.join(', ')} }`;
+}
+
+/**
+ * Convert a single type value to string.
+ */
+function typeValueToString(value: unknown): string {
+    if (Array.isArray(value)) {
+        const itemType = typeValueToString(value[0]);
+        return `${itemType}[]`;
+    } if (typeof value === 'object' && value !== null) {
+        return typeObjectToString(value as Record<string, unknown>);
+    } if (typeof value === 'string') {
+        return value;
+    }
+    return 'unknown';
+}
+
 // Keep the type here since it is a self-contained module
 export type ActorDetailsResult = {
     actorInfo: Actor;
@@ -98,7 +142,7 @@ export function processActorDetailsForResponse(details: ActorDetailsResult) {
  * Used by both public and internal fetch-actor-details tools.
  *
  * Behavior:
- * - If output is undefined or empty object: use defaults (all true except mcpTools)
+ * - If output is undefined or empty object: use defaults (all true except mcpTools and outputSchema)
  * - If any property is explicitly set: only include sections with explicit true values
  */
 export const actorDetailsOutputOptionsSchema = z.object({
@@ -109,6 +153,7 @@ export const actorDetailsOutputOptionsSchema = z.object({
     metadata: z.boolean().optional().describe('Include developer, categories, last modified date, and deprecation status.'),
     inputSchema: z.boolean().optional().describe('Include required input parameters schema.'),
     readme: z.boolean().optional().describe('Include full README documentation.'),
+    outputSchema: z.boolean().optional().describe('Include inferred output schema from recent successful runs (TypeScript type).'),
     mcpTools: z.boolean().optional().describe('List available tools (only for MCP server Actors).'),
 });
 
@@ -120,6 +165,7 @@ export const actorDetailsOutputDefaults = {
     metadata: true,
     inputSchema: true,
     readme: true,
+    outputSchema: false,
     mcpTools: false,
 };
 
@@ -145,6 +191,7 @@ export function resolveOutputOptions(output?: z.infer<typeof actorDetailsOutputO
         metadata: output?.metadata === true,
         inputSchema: output?.inputSchema === true,
         readme: output?.readme === true,
+        outputSchema: output?.outputSchema === true,
         mcpTools: output?.mcpTools === true,
     };
 }
@@ -224,7 +271,7 @@ You can search for available Actors using the tool: ${HelperTools.STORE_SEARCH}.
 
 /**
  * Build text and structured response for actor details.
- * Handles all resolved output options: description, stats, readme, inputSchema, mcpTools.
+ * Handles all resolved output options: description, stats, readme, inputSchema, outputSchema, mcpTools.
  * All output properties should be boolean (resolved via resolveOutputOptions).
  */
 export async function buildActorDetailsTextResponse(options: {
@@ -238,17 +285,19 @@ export async function buildActorDetailsTextResponse(options: {
         metadata: boolean;
         readme: boolean;
         inputSchema: boolean;
+        outputSchema: boolean;
         mcpTools: boolean;
     };
     cardOptions: ActorCardOptions;
     apifyClient: ApifyClient;
     apifyToken: string;
+    actorOutputSchema?: Record<string, unknown> | null;
     skyfireMode?: boolean;
 }): Promise<{
     texts: string[];
     structuredContent: Record<string, unknown>;
 }> {
-    const { actorName, details, output, cardOptions, apifyClient, apifyToken, skyfireMode } = options;
+    const { actorName, details, output, cardOptions, apifyClient, apifyToken, actorOutputSchema, skyfireMode } = options;
 
     const actorUrl = `https://apify.com/${details.actorInfo.username}/${details.actorInfo.name}`;
     const formattedReadme = details.readme.replace(/^# /, `# [README](${actorUrl}/readme): `);
@@ -276,6 +325,16 @@ export async function buildActorDetailsTextResponse(options: {
         texts.push(`# [Input schema](${actorUrl}/input)\n\`\`\`json\n${JSON.stringify(details.inputSchema)}\n\`\`\``);
     }
 
+    // Add output schema if requested
+    if (output.outputSchema) {
+        if (actorOutputSchema && Object.keys(actorOutputSchema).length > 0) {
+            const typeString = typeObjectToString(actorOutputSchema);
+            texts.push(`# Output Schema (TypeScript)\nInferred from recent successful runs:\n\`\`\`typescript\ntype ActorOutput = ${typeString}\n\`\`\``);
+        } else {
+            texts.push(`# Output Schema\nNo output schema available. The Actor may not have recent successful runs, or the output structure could not be determined.`);
+        }
+    }
+
     // Handle MCP tools
     if (output.mcpTools) {
         const message = await getMcpToolsMessage(actorName, apifyClient, apifyToken, skyfireMode);
@@ -287,6 +346,7 @@ export async function buildActorDetailsTextResponse(options: {
         actorInfo: needsCard ? details.actorCardStructured : undefined,
         readme: output.readme ? formattedReadme : undefined,
         inputSchema: output.inputSchema ? details.inputSchema : undefined,
+        outputSchema: output.outputSchema ? actorOutputSchema : undefined,
     };
 
     return { texts, structuredContent };

src/utils/actor-response.ts

@@ -13,11 +13,13 @@ import type { CallActorGetDatasetResult } from '../tools/actor.js';
  *
  * @param actorName - The name of the actor.
  * @param result - The result from callActorGetDataset.
+ * @param previewOutput - Whether to include preview items (default: true).
  * @returns The content array for the tool response.
  */
 export function buildActorResponseContent(
     actorName: string,
     result: CallActorGetDatasetResult,
+    previewOutput = true,
 ): ({ type: 'text'; text: string })[] {
     const { runId, datasetId, itemCount, schema } = result;
 
@@ -46,9 +48,16 @@ Above this text block is a preview of the Actor output containing ${result.previ
 If you need to retrieve additional data, use the "get-actor-output" tool with: datasetId: "${datasetId}". Be sure to limit the number of results when using the "get-actor-output" tool, since you never know how large the items may be, and they might exceed the output limits.
 `;
 
+    const getEmptyPreviewMessage = () => {
+        if (previewOutput) {
+            return `No items available for preview—either the Actor did not return any items or they are too large for preview. Use the "get-actor-output" tool with datasetId: "${result.datasetId}" to retrieve results.`;
+        }
+        return `Preview skipped (previewOutput: false). Use the "get-actor-output" tool with datasetId: "${result.datasetId}" to retrieve results or specific fields.`;
+    };
+
     const itemsPreviewText = result.previewItems.length > 0
         ? JSON.stringify(result.previewItems)
-        : `No items available for preview—either the Actor did not return any items or they are too large for preview. In this case, use the "get-actor-output" tool.`;
+        : getEmptyPreviewMessage();
 
     // Build content array
     return [