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

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/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: ['string', 'null'], description: 'TypeScript type skeleton inferred from recent 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 };