feat(input): allow empty tools and actors to allow greater control of exposed tools

MQ37 · MQ37 · commit 42e32bd2d86c · 2025-08-12T16:01:59.000+02:00
diff --git a/src/actor/server.ts b/src/actor/server.ts
@@ -12,7 +12,6 @@ import express from 'express';
 import log from '@apify/log';
 
 import { ActorsMcpServer } from '../mcp/server.js';
-import { parseInputParamsFromUrl } from '../mcp/utils.js';
 import { getHelpMessage, HEADER_READINESS_PROBE, Routes, TransportType } from './const.js';
 import { getActorRunData } from './utils.js';
 
@@ -80,16 +79,8 @@ export function createExpressApp(
 
             // Load MCP server tools
             const apifyToken = process.env.APIFY_TOKEN as string;
-            const input = parseInputParamsFromUrl(req.url);
-            if (input.actors || input.enableAddingActors || input.tools) {
-                log.debug('Loading tools from URL', { sessionId: transport.sessionId, tr: TransportType.SSE });
-                await mcpServer.loadToolsFromUrl(req.url, apifyToken);
-            }
-            // Load default tools if no actors are specified
-            if (!input.actors) {
-                log.debug('Loading default tools', { sessionId: transport.sessionId, tr: TransportType.SSE });
-                await mcpServer.loadDefaultActors(apifyToken);
-            }
+            log.debug('Loading tools from URL', { sessionId: transport.sessionId, tr: TransportType.SSE });
+            await mcpServer.loadToolsFromUrl(req.url, apifyToken);
 
             transportsSSE[transport.sessionId] = transport;
             mcpServers[transport.sessionId] = mcpServer;
@@ -170,16 +161,8 @@ export function createExpressApp(
 
                 // Load MCP server tools
                 const apifyToken = process.env.APIFY_TOKEN as string;
-                const input = parseInputParamsFromUrl(req.url);
-                if (input.actors || input.enableAddingActors || input.tools) {
-                    log.debug('Loading tools from URL', { sessionId: transport.sessionId, tr: TransportType.HTTP });
-                    await mcpServer.loadToolsFromUrl(req.url, apifyToken);
-                }
-                // Load default tools if no actors are specified
-                if (!input.actors) {
-                    log.debug('Loading default tools', { sessionId: transport.sessionId, tr: TransportType.HTTP });
-                    await mcpServer.loadDefaultActors(apifyToken);
-                }
+                log.debug('Loading tools from URL', { sessionId: transport.sessionId, tr: TransportType.HTTP });
+                await mcpServer.loadToolsFromUrl(req.url, apifyToken);
 
                 // Connect the transport to the MCP server BEFORE handling the request
                 await mcpServer.connect(transport);
diff --git a/src/index-internals.ts b/src/index-internals.ts
@@ -4,7 +4,7 @@
 
 import { defaults, HelperTools } from './const.js';
 import { parseInputParamsFromUrl, processParamsGetTools } from './mcp/utils.js';
-import { addRemoveTools, defaultTools, getActorsAsTools, toolCategories, toolCategoriesEnabledByDefault } from './tools/index.js';
+import { defaultTools, getActorsAsTools, toolCategories, toolCategoriesEnabledByDefault } from './tools/index.js';
 import { actorNameToToolName } from './tools/utils.js';
 import type { ToolCategory } from './types.js';
 import { getToolPublicFieldOnly } from './utils/tools.js';
@@ -15,7 +15,6 @@ export {
     HelperTools,
     defaults,
     defaultTools,
-    addRemoveTools,
     toolCategories,
     toolCategoriesEnabledByDefault,
     type ToolCategory,
diff --git a/src/input.ts b/src/input.ts
@@ -17,6 +17,12 @@ export function processInput(originalInput: Partial<Input>): Input {
     if (input.actors && typeof input.actors === 'string') {
         input.actors = input.actors.split(',').map((format: string) => format.trim()) as string[];
     }
+    /**
+     * Replace empty string with empty array to prevent invalid Actor API error.
+     */
+    if (input.actors === '') {
+        input.actors = [];
+    }
 
     // enableAddingActors is deprecated, use enableActorAutoLoading instead
     if (input.enableAddingActors === undefined) {
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
@@ -75,9 +75,6 @@ export class ActorsMcpServer {
         this.setupToolHandlers();
         this.setupPromptHandlers();
 
-        // Add default tools
-        this.upsertTools(defaultTools);
-
         // Add tools to dynamically load Actors
         if (this.options.enableAddingActors) {
             this.enableDynamicActorTools();
@@ -213,7 +210,6 @@ export class ActorsMcpServer {
         if (this.toolsChangedHandler) {
             this.unregisterToolsChangedHandler();
         }
-        this.upsertTools(defaultTools);
         if (this.options.enableAddingActors) {
             this.enableDynamicActorTools();
         }
@@ -244,14 +240,6 @@ export class ActorsMcpServer {
         }
     }
 
-    /**
-     * @deprecated Use `loadDefaultActors` instead.
-     * Loads default tools if not already loaded.
-     */
-    public async loadDefaultTools(apifyToken: string) {
-        await this.loadDefaultActors(apifyToken);
-    }
-
     /**
      * Loads tools from URL params.
      *
diff --git a/src/stdio.ts b/src/stdio.ts
@@ -90,10 +90,14 @@ Note: Tools that enable you to search Actors from the Apify Store and get their
     .parseSync() as CliArgs;
 
 const enableAddingActors = argv.enableAddingActors && argv.enableActorAutoLoading;
-const actors = argv.actors as string || '';
-const actorList = actors ? actors.split(',').map((a: string) => a.trim()) : [];
-// Keys of the tool categories to enable
-const toolCategoryKeys = argv.tools ? argv.tools.split(',').map((t: string) => t.trim()) : [];
+// Split actors argument, trim whitespace, and filter out empty strings
+const actorList = argv.actors !== undefined
+    ? argv.actors.split(',').map((a: string) => a.trim()).filter((a: string) => a.length > 0)
+    : undefined;
+// Split tools argument, trim whitespace, and filter out empty strings
+const toolCategoryKeys = argv.tools !== undefined
+    ? argv.tools.split(',').map((t: string) => t.trim()).filter((t: string) => t.length > 0)
+    : undefined;
 
 // Propagate log.error to console.error for easier debugging
 const originalError = log.error.bind(log);
@@ -114,13 +118,13 @@ async function main() {
 
     // Create an Input object from CLI arguments
     const input: Input = {
-        actors: actorList.length ? actorList : [],
+        actors: actorList,
         enableAddingActors,
         tools: toolCategoryKeys as ToolCategory[],
     };
 
     // Use the shared tools loading logic
-    const tools = await loadToolsFromInput(input, process.env.APIFY_TOKEN as string, actorList.length === 0);
+    const tools = await loadToolsFromInput(input, process.env.APIFY_TOKEN as string);
 
     mcpServer.upsertTools(tools);
 
diff --git a/src/tools/index.ts b/src/tools/index.ts
@@ -1,5 +1,6 @@
 // Import specific tools that are being used
 import type { ToolCategory } from '../types.js';
+import { getExpectedToolsByCategories } from '../utils/tools.js';
 import { callActor, callActorGetDataset, getActorsAsTools } from './actor.js';
 import { getDataset, getDatasetItems, getDatasetSchema } from './dataset.js';
 import { getUserDatasetsList } from './dataset_collection.js';
@@ -14,6 +15,14 @@ import { searchApifyDocsTool } from './search-apify-docs.js';
 import { searchActors } from './store_collection.js';
 
 export const toolCategories = {
+    'actor-discovery': [
+        getActorDetailsTool,
+        searchActors,
+        /**
+         * TODO: we should add the add-actor tool here but we would need to change the configuraton
+         * interface around the ?enableAddingActors
+         */
+    ],
     docs: [
         searchApifyDocsTool,
         fetchApifyDocsTool,
@@ -38,16 +47,15 @@ export const toolCategories = {
     ],
 };
 export const toolCategoriesEnabledByDefault: ToolCategory[] = [
+    'actor-discovery',
     'docs',
 ];
 
-export const defaultTools = [
-    getActorDetailsTool,
-    searchActors,
-    // Add the tools from the enabled categories
-    ...toolCategoriesEnabledByDefault.map((key) => toolCategories[key]).flat(),
-];
+export const defaultTools = getExpectedToolsByCategories(toolCategoriesEnabledByDefault);
 
+/**
+ * Tools related to `enableAddingActors` param for dynamic Actor adding.
+ */
 export const addRemoveTools = [
     addTool,
 ];
diff --git a/src/types.ts b/src/types.ts
@@ -213,7 +213,12 @@ export interface InternalTool extends ToolBase {
 export type ToolCategory = keyof typeof toolCategories;
 
 export type Input = {
-    actors: string[] | string;
+    /**
+     * When `actors` is undefined that means the default Actors should be loaded.
+     * If it as empty string or empty array then no Actors should be loaded.
+     * Otherwise the specified Actors should be loaded.
+     */
+    actors?: string[] | string;
     /**
     * @deprecated Use `enableAddingActors` instead.
     */
@@ -222,7 +227,12 @@ export type Input = {
     maxActorMemoryBytes?: number;
     debugActor?: string;
     debugActorInput?: unknown;
-    /** Tool categories to include */
+    /**
+     * Tool categories to include
+     * When `tools` is undefined that means the default tools categories should be loaded.
+     * If it as empty string or empty array then no tools should be loaded.
+     * Otherwise the specified tools categories should be loaded.
+     */
     tools?: ToolCategory[] | string;
 };
 
diff --git a/src/utils/tools-loader.ts b/src/utils/tools-loader.ts
@@ -4,31 +4,30 @@
  */
 
 import { defaults } from '../const.js';
-import { addRemoveTools, getActorsAsTools, toolCategories } from '../tools/index.js';
+import { addRemoveTools, getActorsAsTools, toolCategories, toolCategoriesEnabledByDefault } from '../tools/index.js';
 import type { Input, ToolCategory, ToolEntry } from '../types.js';
+import { getExpectedToolsByCategories } from './tools.js';
 
 /**
  * Load tools based on the provided Input object.
  * This function is used by both the stdio.ts and the processParamsGetTools function.
  *
  * @param input The processed Input object
  * @param apifyToken The Apify API token
- * @param useDefaultActors Whether to use default actors if no actors are specified
  * @returns An array of tool entries
  */
 export async function loadToolsFromInput(
     input: Input,
     apifyToken: string,
-    useDefaultActors = false,
 ): Promise<ToolEntry[]> {
     let tools: ToolEntry[] = [];
 
     // Load actors as tools
-    if (input.actors && (Array.isArray(input.actors) ? input.actors.length > 0 : input.actors)) {
+    if (input.actors !== undefined) {
         const actors = Array.isArray(input.actors) ? input.actors : [input.actors];
         tools = await getActorsAsTools(actors, apifyToken);
-    } else if (useDefaultActors) {
-        // Use default actors if no actors are specified and useDefaultActors is true
+    } else {
+        // Use default actors if no actors are specified
         tools = await getActorsAsTools(defaults.actors, apifyToken);
     }
 
@@ -38,12 +37,14 @@ export async function loadToolsFromInput(
     }
 
     // Add tools from enabled categories
-    if (input.tools) {
+    if (input.tools !== undefined) {
         const toolKeys = Array.isArray(input.tools) ? input.tools : [input.tools];
         for (const toolKey of toolKeys) {
             const keyTools = toolCategories[toolKey as ToolCategory] || [];
             tools.push(...keyTools);
         }
+    } else {
+        tools.push(...getExpectedToolsByCategories(toolCategoriesEnabledByDefault));
     }
 
     return tools;
diff --git a/src/utils/tools.ts b/src/utils/tools.ts
@@ -1,4 +1,5 @@
-import type { ToolBase } from '../types.js';
+import { toolCategories } from '../tools/index.js';
+import type { ToolBase, ToolCategory, ToolEntry } from '../types.js';
 
 /**
  * Returns a public version of the tool containing only fields that should be exposed publicly.
@@ -11,3 +12,18 @@ export function getToolPublicFieldOnly(tool: ToolBase) {
         inputSchema: tool.inputSchema,
     };
 }
+
+/**
+ * Returns the tool objects for the given category names using toolCategories.
+ */
+export function getExpectedToolsByCategories(categories: ToolCategory[]): ToolEntry[] {
+    return categories
+        .flatMap((category) => toolCategories[category] || []);
+}
+
+/**
+ * Returns the tool names for the given category names using getExpectedToolsByCategories.
+ */
+export function getExpectedToolNamesByCategories(categories: ToolCategory[]): string[] {
+    return getExpectedToolsByCategories(categories).map((tool) => tool.tool.name);
+}
diff --git a/tests/const.ts b/tests/const.ts
@@ -1,8 +1,9 @@
+import { toolCategoriesEnabledByDefault } from '../dist/index-internals.js';
 import { defaults } from '../src/const.js';
-import { defaultTools } from '../src/tools/index.js';
 import { actorNameToToolName } from '../src/tools/utils.js';
+import { getExpectedToolNamesByCategories } from '../src/utils/tools.js';
 
 export const ACTOR_PYTHON_EXAMPLE = 'apify/python-example';
 export const ACTOR_MCP_SERVER_ACTOR_NAME = 'apify/actors-mcp-server';
-export const DEFAULT_TOOL_NAMES = defaultTools.map((tool) => tool.tool.name);
+export const DEFAULT_TOOL_NAMES = getExpectedToolNamesByCategories(toolCategoriesEnabledByDefault);
 export const DEFAULT_ACTOR_NAMES = defaults.actors.map((tool) => actorNameToToolName(tool));
diff --git a/tests/helpers.ts b/tests/helpers.ts
@@ -22,13 +22,13 @@ export async function createMcpSseClient(
     }
     const url = new URL(serverUrl);
     const { actors, enableAddingActors, tools } = options || {};
-    if (actors) {
+    if (actors !== undefined) {
         url.searchParams.append('actors', actors.join(','));
     }
     if (enableAddingActors !== undefined) {
         url.searchParams.append('enableAddingActors', enableAddingActors.toString());
     }
-    if (tools && tools.length > 0) {
+    if (tools !== undefined) {
         url.searchParams.append('tools', tools.join(','));
     }
 
@@ -61,13 +61,13 @@ export async function createMcpStreamableClient(
     }
     const url = new URL(serverUrl);
     const { actors, enableAddingActors, tools } = options || {};
-    if (actors) {
+    if (actors !== undefined) {
         url.searchParams.append('actors', actors.join(','));
     }
     if (enableAddingActors !== undefined) {
         url.searchParams.append('enableAddingActors', enableAddingActors.toString());
     }
-    if (tools && tools.length > 0) {
+    if (tools !== undefined) {
         url.searchParams.append('tools', tools.join(','));
     }
 
@@ -99,13 +99,13 @@ export async function createMcpStdioClient(
     }
     const { actors, enableAddingActors, tools } = options || {};
     const args = ['dist/stdio.js'];
-    if (actors) {
+    if (actors !== undefined) {
         args.push('--actors', actors.join(','));
     }
     if (enableAddingActors !== undefined) {
         args.push('--enable-adding-actors', enableAddingActors.toString());
     }
-    if (tools && tools.length > 0) {
+    if (tools !== undefined) {
         args.push('--tools', tools.join(','));
     }
 
diff --git a/tests/integration/internals.test.ts b/tests/integration/internals.test.ts
diff --git a/tests/integration/suite.ts b/tests/integration/suite.ts

Original file line number	Diff line number	Diff line change
`@@ -75,9 +75,6 @@ export class ActorsMcpServer {`
`75`	`75`	`this.setupToolHandlers();`
`76`	`76`	`this.setupPromptHandlers();`
`77`	`77`
`78`		`- // Add default tools`
`79`		`- this.upsertTools(defaultTools);`
`80`		`-`
`81`	`78`	`// Add tools to dynamically load Actors`
`82`	`79`	`if (this.options.enableAddingActors) {`
`83`	`80`	`this.enableDynamicActorTools();`
`@@ -213,7 +210,6 @@ export class ActorsMcpServer {`
`213`	`210`	`if (this.toolsChangedHandler) {`
`214`	`211`	`this.unregisterToolsChangedHandler();`
`215`	`212`	`}`
`216`		`- this.upsertTools(defaultTools);`
`217`	`213`	`if (this.options.enableAddingActors) {`
`218`	`214`	`this.enableDynamicActorTools();`
`219`	`215`	`}`
`@@ -244,14 +240,6 @@ export class ActorsMcpServer {`
`244`	`240`	`}`
`245`	`241`	`}`
`246`	`242`
`247`		`- /**`
`248`		- * @deprecated Use `loadDefaultActors` instead.
`249`		`- * Loads default tools if not already loaded.`
`250`		`- */`
`251`		`- public async loadDefaultTools(apifyToken: string) {`
`252`		`- await this.loadDefaultActors(apifyToken);`
`253`		`- }`
`254`		`-`
`255`	`243`	`/**`
`256`	`244`	`* Loads tools from URL params.`
`257`	`245`	`*`