fix: improve generic actor-call tool and hide it behind beta flag (#164)

fix generic actorl-call and move it behind beta flag ?beta=1 or --beta

Author: MQ37

src/input.ts

@@ -29,5 +29,8 @@ export function processInput(originalInput: Partial<Input>): Input {
     } else {
         input.enableAddingActors = input.enableAddingActors === true || input.enableAddingActors === 'true';
     }
+
+    // If beta present, set input.beta to true
+    input.beta = input.beta !== undefined && (input.beta !== false && input.beta !== 'false');
     return input;
 }

src/mcp/server.ts

@@ -23,7 +23,7 @@ import {
     SERVER_NAME,
     SERVER_VERSION,
 } from '../const.js';
-import { addRemoveTools, callActorGetDataset, defaultTools, getActorsAsTools } from '../tools/index.js';
+import { addRemoveTools, betaTools, callActorGetDataset, defaultTools, getActorsAsTools } from '../tools/index.js';
 import { actorNameToToolName } from '../tools/utils.js';
 import type { ActorMcpTool, ActorTool, HelperTool, ToolEntry } from '../types.js';
 import { connectMCPClient } from './client.js';
@@ -33,6 +33,7 @@ import { processParamsGetTools } from './utils.js';
 type ActorsMcpServerOptions = {
     enableAddingActors?: boolean;
     enableDefaultActors?: boolean;
+    enableBeta?: boolean; // Enable beta features
 };
 
 type ToolsChangedHandler = (toolNames: string[]) => void;
@@ -51,6 +52,7 @@ export class ActorsMcpServer {
         this.options = {
             enableAddingActors: options.enableAddingActors ?? true,
             enableDefaultActors: options.enableDefaultActors ?? true, // Default to true for backward compatibility
+            enableBeta: options.enableBeta ?? false, // Disabled by default
         };
         this.server = new Server(
             {
@@ -76,6 +78,10 @@ export class ActorsMcpServer {
             this.enableDynamicActorTools();
         }
 
+        if (this.options.enableBeta) {
+            this.upsertTools(betaTools, false);
+        }
+
         // Initialize automatically for backward compatibility
         this.initialize().catch((error) => {
             log.error('Failed to initialize server:', error);

src/mcp/utils.ts

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
 import { parse } from 'node:querystring';
 
 import { processInput } from '../input.js';
-import { addRemoveTools, getActorsAsTools } from '../tools/index.js';
+import { addRemoveTools, betaTools, getActorsAsTools } from '../tools/index.js';
 import type { Input, ToolEntry } from '../types.js';
 import { MAX_TOOL_NAME_LENGTH, SERVER_ID_LENGTH } from './const.js';
 
@@ -50,6 +50,9 @@ export async function processParamsGetTools(url: string, apifyToken: string) {
     if (input.enableAddingActors) {
         tools.push(...addRemoveTools);
     }
+    if (input.beta) {
+        tools.push(...betaTools);
+    }
     return tools;
 }
 

src/stdio.ts

@@ -36,6 +36,7 @@ interface CliArgs {
     enableAddingActors: boolean;
     /** @deprecated */
     enableActorAutoLoading: boolean;
+    beta: boolean;
 }
 
 // Configure logging, set to ERROR
@@ -60,6 +61,11 @@ const argv = yargs(hideBin(process.argv))
         hidden: true,
         describe: 'Deprecated: use enable-adding-actors instead',
     })
+    .option('beta', {
+        type: 'boolean',
+        default: false,
+        describe: 'Enable beta features',
+    })
     .help('help')
     .alias('h', 'help')
     .version(false)
@@ -73,6 +79,7 @@ const argv = yargs(hideBin(process.argv))
 const enableAddingActors = argv.enableAddingActors && argv.enableActorAutoLoading;
 const actors = argv.actors as string || '';
 const actorList = actors ? actors.split(',').map((a: string) => a.trim()) : [];
+const enableBeta = argv.beta;
 
 // Validate environment
 if (!process.env.APIFY_TOKEN) {
@@ -81,7 +88,7 @@ if (!process.env.APIFY_TOKEN) {
 }
 
 async function main() {
-    const mcpServer = new ActorsMcpServer({ enableAddingActors, enableDefaultActors: false });
+    const mcpServer = new ActorsMcpServer({ enableAddingActors, enableDefaultActors: false, enableBeta });
     const tools = await getActorsAsTools(actorList.length ? actorList : defaults.actors, process.env.APIFY_TOKEN as string);
     mcpServer.upsertTools(tools);
 

src/tools/actor.ts

@@ -292,9 +292,9 @@ export const getActor: ToolEntry = {
 
 const callActorArgs = z.object({
     actor: z.string()
-        .describe('The name of the Actor to call.'),
+        .describe('The name of the Actor to call. For example, "apify/instagram-scraper".'),
     input: z.object({}).passthrough()
-        .describe('The input JSON to pass to the Actor.'),
+        .describe('The input JSON to pass to the Actor. For example, {"query": "apify", "maxItems": 10}.'),
     callOptions: z.object({
         memory: z.number().optional(),
         timeout: z.number().optional(),
@@ -307,7 +307,7 @@ export const callActor: ToolEntry = {
     tool: {
         name: HelperTools.ACTOR_CALL,
         actorFullName: HelperTools.ACTOR_CALL,
-        description: `Call Actor and get dataset results. Call without input and result response with requred input properties. Actor MUST be added before calling, use ${HelperTools.ACTOR_ADD} tool before.`,
+        description: `Call an Actor and get the Actor run results. If you are not sure about the Actor input, you MUST get the Actor details first, which also returns the input schema using ${HelperTools.ACTOR_GET_DETAILS}. The Actor MUST be added before calling; use the ${HelperTools.ACTOR_ADD} tool first. By default, the Apify MCP server makes newly added Actors available as tools for calling. Use this tool ONLY if you cannot call the newly added tool directly, and NEVER call this tool before first trying to call the tool directly. For example, when you add an Actor "apify/instagram-scraper" using the ${HelperTools.ACTOR_ADD} tool, the Apify MCP server will add a new tool ${actorNameToToolName('apify/instagram-scraper')} that you can call directly. If calling this tool does not work, then and ONLY then MAY you use this tool as a backup.`,
         inputSchema: zodToJsonSchema(callActorArgs),
         ajvValidate: ajv.compile(zodToJsonSchema(callActorArgs)),
         call: async (toolArgs) => {
@@ -316,12 +316,12 @@ export const callActor: ToolEntry = {
 
             const actors = apifyMcpServer.listActorToolNames();
             if (!actors.includes(actorName)) {
-                const toolsText = actors.length > 0 ? `Available Actors are: ${actors.join(', ')}` : 'Not added Actors yet.';
+                const toolsText = actors.length > 0 ? `Available Actors are: ${actors.join(', ')}` : 'No Actors have been added yet.';
                 if (apifyMcpServer.tools.has(HelperTools.ACTOR_ADD)) {
                     return {
                         content: [{
                             type: 'text',
-                            text: `Actor '${actorName}' is not added. Add it with tool '${HelperTools.ACTOR_ADD}'. ${toolsText}`,
+                            text: `Actor '${actorName}' is not added. Add it with the '${HelperTools.ACTOR_ADD}' tool. ${toolsText}`,
                         }],
                     };
                 }

src/tools/get-actor-details.ts

@@ -48,7 +48,7 @@ export const getActorDetailsTool: ToolEntry = {
         name: HelperTools.ACTOR_GET_DETAILS,
         description: `Retrieve information about an Actor by its ID or full name.
 The Actor name is always composed of "username/name", for example, "apify/rag-web-browser".
-This tool returns information about the Actor, including whether it is public or deprecated, when it was created or modified, the categories in which the Actor is listed, a description, a README (the Actor's documentation), the input schema, and usage statistics—such as how many users are using it and the number of failed runs of the Actor.
+This tool returns information about the Actor, including whether it is public or deprecated, when it was created or modified, the categories in which the Actor is listed, a description, a README (the Actor's documentation), the input schema, and usage statistics - such as how many users are using it and the number of failed runs of the Actor.
 For example, use this tool when a user wants to know more about a specific Actor or wants to use optional or advanced parameters of the Actor that are not listed in the default Actor tool input schema - so you know the details and how to pass them.`,
         inputSchema: zodToJsonSchema(getActorDetailsToolArgsSchema),
         ajvValidate: ajv.compile(zodToJsonSchema(getActorDetailsToolArgsSchema)),

src/tools/helpers.ts

@@ -45,8 +45,7 @@ A tool is an Actor or MCP server that can be called by the user.
 Do not execute the tool, only add it and list it in the available tools. 
 For example, when a user wants to scrape a website, first search for relevant Actors
 using ${HelperTools.STORE_SEARCH} tool, and once the user selects one they want to use, 
-add it as a tool to the Apify MCP server.
-If added tools is not available, use generic tool ${HelperTools.ACTOR_CALL} to call added Actor directly.`,
+add it as a tool to the Apify MCP server.`,
         inputSchema: zodToJsonSchema(addToolArgsSchema),
         ajvValidate: ajv.compile(zodToJsonSchema(addToolArgsSchema)),
         // TODO: I don't like that we are passing apifyMcpServer and mcpServer to the tool

src/tools/index.ts

@@ -20,14 +20,17 @@ export const defaultTools = [
     // getUserRunsList,
     // getUserDatasetsList,
     // getUserKeyValueStoresList,
-    callActor,
     getActorDetailsTool,
     helpTool,
     searchActors,
     searchApifyDocsTool,
     fetchApifyDocsTool,
 ];
 
+export const betaTools = [
+    callActor,
+];
+
 export const addRemoveTools = [
     addTool,
     // removeTool,

src/types.ts

@@ -223,6 +223,8 @@ export type Input = {
     maxActorMemoryBytes?: number;
     debugActor?: string;
     debugActorInput?: unknown;
+    /** Enable beta features flag */
+    beta?: boolean | string;
 };
 
 // Utility type to get a union of values from an object type

tests/helpers.ts

@@ -9,6 +9,7 @@ import { HelperTools } from '../src/const.js';
 export interface McpClientOptions {
     actors?: string[];
     enableAddingActors?: boolean;
+    enableBeta?: boolean; // Optional, used for beta features
 }
 
 export async function createMcpSseClient(
@@ -19,13 +20,16 @@ export async function createMcpSseClient(
         throw new Error('APIFY_TOKEN environment variable is not set.');
     }
     const url = new URL(serverUrl);
-    const { actors, enableAddingActors } = options || {};
+    const { actors, enableAddingActors, enableBeta } = options || {};
     if (actors) {
         url.searchParams.append('actors', actors.join(','));
     }
     if (enableAddingActors !== undefined) {
         url.searchParams.append('enableAddingActors', enableAddingActors.toString());
     }
+    if (enableBeta !== undefined) {
+        url.searchParams.append('beta', enableBeta.toString());
+    }
 
     const transport = new SSEClientTransport(
         url,
@@ -55,13 +59,16 @@ export async function createMcpStreamableClient(
         throw new Error('APIFY_TOKEN environment variable is not set.');
     }
     const url = new URL(serverUrl);
-    const { actors, enableAddingActors } = options || {};
+    const { actors, enableAddingActors, enableBeta } = options || {};
     if (actors) {
         url.searchParams.append('actors', actors.join(','));
     }
     if (enableAddingActors !== undefined) {
         url.searchParams.append('enableAddingActors', enableAddingActors.toString());
     }
+    if (enableBeta !== undefined) {
+        url.searchParams.append('beta', enableBeta.toString());
+    }
 
     const transport = new StreamableHTTPClientTransport(
         url,
@@ -89,14 +96,17 @@ export async function createMcpStdioClient(
     if (!process.env.APIFY_TOKEN) {
         throw new Error('APIFY_TOKEN environment variable is not set.');
     }
-    const { actors, enableAddingActors } = options || {};
+    const { actors, enableAddingActors, enableBeta } = options || {};
     const args = ['dist/stdio.js'];
     if (actors) {
         args.push('--actors', actors.join(','));
     }
     if (enableAddingActors !== undefined) {
         args.push('--enable-adding-actors', enableAddingActors.toString());
     }
+    if (enableBeta !== undefined) {
+        args.push('--beta', enableBeta.toString());
+    }
     const transport = new StdioClientTransport({
         command: 'node',
         args,