Merge remote-tracking branch 'origin/master' into feat/progress-notification

Author: MichalKalita

.actor/ACTOR.md

@@ -3,14 +3,25 @@
 All notable changes to this project will be documented in this file.
 
 <!-- git-cliff-unreleased-start -->
-## 0.2.14 - **not yet released**
+## 0.2.15 - **not yet released**
+
+### 🚀 Features
+
+- Add video tutorial into the Actor README. Simplify README ([#175](https://github.com/apify/actors-mcp-server/pull/175)) ([3547521](https://github.com/apify/actors-mcp-server/commit/3547521e23bbf9a5d49cb75f8ff275e88dfe5be4)) by [@jirispilka](https://github.com/jirispilka), closes [#138](https://github.com/apify/actors-mcp-server/issues/138), [#148](https://github.com/apify/actors-mcp-server/issues/148)
+
+
+<!-- git-cliff-unreleased-end -->
+## [0.2.14](https://github.com/apify/actors-mcp-server/releases/tag/v0.2.14) (2025-07-17)
+
+### 🚀 Features
+
+- Add tool selection by feature param ([#172](https://github.com/apify/actors-mcp-server/pull/172)) ([f3b2e4f](https://github.com/apify/actors-mcp-server/commit/f3b2e4f1d204ab01cd0783bbc9930bfc2f84a539)) by [@MQ37](https://github.com/MQ37), closes [#166](https://github.com/apify/actors-mcp-server/issues/166)
 
 ### 🐛 Bug Fixes
 
 - Encode Actor input fields containing dots ([#170](https://github.com/apify/actors-mcp-server/pull/170)) ([8dbdc7b](https://github.com/apify/actors-mcp-server/commit/8dbdc7b53da50137fd118631404312c71d8f4381)) by [@MQ37](https://github.com/MQ37)
 
 
-<!-- git-cliff-unreleased-end -->
 ## [0.2.13](https://github.com/apify/actors-mcp-server/releases/tag/v0.2.13) (2025-07-15)
 
 ### 🐛 Bug Fixes

CHANGELOG.md

@@ -94,7 +94,17 @@ One of the powerful features of MCP with Apify is dynamic actor tooling – the
 
 - Actor discovery and management: Search for Actors (`search-actors`), view details (`get-actor-details`), and dynamically add them (`add-actor`).
 - Apify documentation: Search Apify documentation (`search-apify-docs`) and fetch specific documents (`fetch-apify-docs`).
-- Built-in help tool: A static helper (`apify-actor-help-tool`) that returns usage info for the Apify MCP Server.
+- Actor runs (*): Get a list of your Actor runs (`get-actor-run-list`), specific run details (`get-actor-run`), and logs from a specific Actor run (`get-actor-log`).
+- Apify storage (*): Access datasets (`get-dataset`, `get-dataset-items`, `get-dataset-list`), key-value stores (`get-key-value-store`, `get-key-value-store-keys`, `get-key-value-store-record`, `get-key-value-store-records`), and their records.
+
+**Note**: Helper tool categories marked with (*) are not enabled by default in the MCP server and must be explicitly enabled using the `tools` argument (either the `--tools` command line argument for the stdio server or the `?tools` URL query parameter for the remote MCP server). The `tools` argument is a comma-separated list of categories with the following possible values:
+
+- `docs`: Search and fetch Apify documentation tools.
+- `runs`: Get Actor runs list, run details, and logs from a specific Actor run.
+- `storage`: Access datasets, key-value stores, and their records.
+- `preview`: Experimental tools in preview mode.
+
+For example, to enable all tools, use `npx @apify/actors-mcp-server --tools docs,runs,storage,preview` or `https://mcp.apify.com/?tools=docs,runs,storage,preview`.
 
 ## Prompt & Resources
 

README.md

@@ -1,6 +1,6 @@
 {
   "name": "@apify/actors-mcp-server",
-  "version": "0.2.14",
+  "version": "0.2.15",
   "type": "module",
   "description": "Model Context Protocol Server for Apify",
   "engines": {

package-lock.json

@@ -13,26 +13,9 @@ import log from '@apify/log';
 
 import { ActorsMcpServer } from '../mcp/server.js';
 import { parseInputParamsFromUrl } from '../mcp/utils.js';
-import { getActorsAsTools } from '../tools/actor.js';
 import { getHelpMessage, HEADER_READINESS_PROBE, Routes } from './const.js';
 import { getActorRunData } from './utils.js';
 
-/**
- * Helper function to load tools and actors based on input parameters
- * @param mcpServer The MCP server instance
- * @param url The request URL to parse parameters from
- * @param apifyToken The Apify token for authentication
- */
-async function loadToolsAndActors(mcpServer: ActorsMcpServer, url: string, apifyToken: string): Promise<void> {
-    const input = parseInputParamsFromUrl(url);
-    if (input.actors || input.enableAddingActors) {
-        await mcpServer.loadToolsFromUrl(url, apifyToken);
-    }
-    if (!input.actors) {
-        await mcpServer.loadDefaultActors(apifyToken);
-    }
-}
-
 export function createExpressApp(
     host: string,
     mcpServerOptions: {
@@ -85,13 +68,21 @@ export function createExpressApp(
         try {
             log.info(`Received GET message at: ${Routes.SSE}`);
             const mcpServer = new ActorsMcpServer(mcpServerOptions, false);
-            // Load tools from Actor input for backwards compatibility
-            if (mcpServerOptions.actors && mcpServerOptions.actors.length > 0) {
-                const tools = await getActorsAsTools(mcpServerOptions.actors, process.env.APIFY_TOKEN as string);
-                mcpServer.upsertTools(tools);
-            }
-            await loadToolsAndActors(mcpServer, req.url, process.env.APIFY_TOKEN as string);
             const transport = new SSEServerTransport(Routes.MESSAGE, res);
+
+            // 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('[SSE] Loading tools from URL', { sessionId: transport.sessionId });
+                await mcpServer.loadToolsFromUrl(req.url, apifyToken);
+            }
+            // Load default tools if no actors are specified
+            if (!input.actors) {
+                log.debug('[SSE] Loading default tools', { sessionId: transport.sessionId });
+                await mcpServer.loadDefaultActors(apifyToken);
+            }
+
             transportsSSE[transport.sessionId] = transport;
             mcpServers[transport.sessionId] = mcpServer;
             await mcpServer.connect(transport);
@@ -164,13 +155,20 @@ export function createExpressApp(
                     enableJsonResponse: false, // Use SSE response mode
                 });
                 const mcpServer = new ActorsMcpServer(mcpServerOptions, false);
-                // Load tools from Actor input for backwards compatibility
-                if (mcpServerOptions.actors && mcpServerOptions.actors.length > 0) {
-                    const tools = await getActorsAsTools(mcpServerOptions.actors, process.env.APIFY_TOKEN as string);
-                    mcpServer.upsertTools(tools);
-                }
+
                 // Load MCP server tools
-                await loadToolsAndActors(mcpServer, req.url, process.env.APIFY_TOKEN as string);
+                const apifyToken = process.env.APIFY_TOKEN as string;
+                const input = parseInputParamsFromUrl(req.url);
+                if (input.actors || input.enableAddingActors || input.tools) {
+                    log.debug('[Streamable] Loading tools from URL', { sessionId: transport.sessionId });
+                    await mcpServer.loadToolsFromUrl(req.url, apifyToken);
+                }
+                // Load default tools if no actors are specified
+                if (!input.actors) {
+                    log.debug('[Streamable] Loading default tools', { sessionId: transport.sessionId });
+                    await mcpServer.loadDefaultActors(apifyToken);
+                }
+
                 // Connect the transport to the MCP server BEFORE handling the request
                 await mcpServer.connect(transport);
 

package.json

@@ -3,7 +3,7 @@
  */
 import log from '@apify/log';
 
-import type { Input } from './types.js';
+import type { Input, ToolCategory } from './types.js';
 
 /**
  * Process input parameters, split Actors string into an array
@@ -30,7 +30,8 @@ export function processInput(originalInput: Partial<Input>): Input {
         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');
+    if (input.tools && typeof input.tools === 'string') {
+        input.tools = input.tools.split(',').map((tool: string) => tool.trim()) as ToolCategory[];
+    }
     return input;
 }

src/actor/server.ts

@@ -23,7 +23,7 @@ import {
     SERVER_NAME,
     SERVER_VERSION,
 } from '../const.js';
-import { addRemoveTools, betaTools, callActorGetDataset, defaultTools, getActorsAsTools } from '../tools/index.js';
+import { addRemoveTools, callActorGetDataset, defaultTools, getActorsAsTools, toolCategories } from '../tools/index.js';
 import { actorNameToToolName, decodeDotPropertyNames } from '../tools/utils.js';
 import type { ActorMcpTool, ActorTool, HelperTool, ToolEntry } from '../types.js';
 import { createProgressTracker } from '../utils/progress.js';
@@ -34,7 +34,6 @@ import { processParamsGetTools } from './utils.js';
 type ActorsMcpServerOptions = {
     enableAddingActors?: boolean;
     enableDefaultActors?: boolean;
-    enableBeta?: boolean; // Enable beta features
 };
 
 type ToolsChangedHandler = (toolNames: string[]) => void;
@@ -53,7 +52,6 @@ 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(
             {
@@ -79,10 +77,6 @@ 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);
@@ -173,7 +167,11 @@ export class ActorsMcpServer {
         const loadedTools = this.listAllToolNames();
         const actorsToLoad: string[] = [];
         const toolsToLoad: ToolEntry[] = [];
-        const internalToolMap = new Map([...defaultTools, ...addRemoveTools, ...betaTools].map((tool) => [tool.tool.name, tool]));
+        const internalToolMap = new Map([
+            ...defaultTools,
+            ...addRemoveTools,
+            ...Object.values(toolCategories).flat(),
+        ].map((tool) => [tool.tool.name, tool]));
 
         for (const tool of toolNames) {
             // Skip if the tool is already loaded

src/input.ts

@@ -2,8 +2,8 @@ import { createHash } from 'node:crypto';
 import { parse } from 'node:querystring';
 
 import { processInput } from '../input.js';
-import { addRemoveTools, betaTools, getActorsAsTools } from '../tools/index.js';
-import type { Input, ToolEntry } from '../types.js';
+import type { Input } from '../types.js';
+import { loadToolsFromInput } from '../utils/tools-loader.js';
 import { MAX_TOOL_NAME_LENGTH, SERVER_ID_LENGTH } from './const.js';
 
 /**
@@ -34,26 +34,14 @@ export function getProxyMCPServerToolName(url: string, toolName: string): string
 }
 
 /**
- * Process input parameters and get tools
+ * Process input parameters from URL and get tools
  * If URL contains query parameter `actors`, return tools from Actors otherwise return null.
  * @param url
  * @param apifyToken
  */
 export async function processParamsGetTools(url: string, apifyToken: string) {
     const input = parseInputParamsFromUrl(url);
-    let tools: ToolEntry[] = [];
-    if (input.actors) {
-        const actors = input.actors as string[];
-        // Normal Actors as a tool
-        tools = await getActorsAsTools(actors, apifyToken);
-    }
-    if (input.enableAddingActors) {
-        tools.push(...addRemoveTools);
-    }
-    if (input.beta) {
-        tools.push(...betaTools);
-    }
-    return tools;
+    return await loadToolsFromInput(input, apifyToken);
 }
 
 export function parseInputParamsFromUrl(url: string): Input {

src/mcp/server.ts

@@ -22,9 +22,10 @@ import { hideBin } from 'yargs/helpers';
 
 import log from '@apify/log';
 
-import { defaults } from './const.js';
 import { ActorsMcpServer } from './mcp/server.js';
-import { getActorsAsTools } from './tools/index.js';
+import { toolCategories } from './tools/index.js';
+import type { Input, ToolCategory } from './types.js';
+import { loadToolsFromInput } from './utils/tools-loader.js';
 
 // Keeping this interface here and not types.ts since
 // it is only relevant to the CLI/STDIO transport in this file
@@ -36,7 +37,8 @@ interface CliArgs {
     enableAddingActors: boolean;
     /** @deprecated */
     enableActorAutoLoading: boolean;
-    beta: boolean;
+    /** Tool categories to include */
+    tools?: string;
 }
 
 // Configure logging, set to ERROR
@@ -47,24 +49,35 @@ const argv = yargs(hideBin(process.argv))
     .usage('Usage: $0 [options]')
     .option('actors', {
         type: 'string',
-        describe: 'Comma-separated list of Actor full names to add to the server',
+        describe: 'Comma-separated list of Actor full names to add to the server.',
         example: 'apify/google-search-scraper,apify/instagram-scraper',
     })
     .option('enable-adding-actors', {
         type: 'boolean',
         default: true,
-        describe: 'Enable dynamically adding Actors as tools based on user requests',
+        describe: 'Enable dynamically adding Actors as tools based on user requests.',
     })
     .option('enableActorAutoLoading', {
         type: 'boolean',
         default: true,
         hidden: true,
-        describe: 'Deprecated: use enable-adding-actors instead',
+        describe: 'Deprecated: use enable-adding-actors instead.',
     })
-    .option('beta', {
-        type: 'boolean',
-        default: false,
-        describe: 'Enable beta features',
+    .options('tools', {
+        type: 'string',
+        describe: `Comma-separated list of specific tool categories to enable.
+
+Available choices: ${Object.keys(toolCategories).join(', ')}
+
+Tool categories are as follows:
+- docs: Search and fetch Apify documentation tools.
+- runs: Get Actor runs list, run details, and logs from a specific Actor run.
+- storage: Access datasets, key-value stores, and their records.
+- preview: Experimental tools in preview mode.
+
+Note: Tools that enable you to search Actors from the Apify Store and get their details are always enabled by default.
+`,
+        example: 'docs,runs,storage',
     })
     .help('help')
     .alias('h', 'help')
@@ -73,13 +86,14 @@ const argv = yargs(hideBin(process.argv))
         'To connect, set your MCP client server command to `npx @apify/actors-mcp-server`'
         + ' and set the environment variable `APIFY_TOKEN` to your Apify API token.\n',
     )
-    .epilogue('For more information, visit https://github.com/apify/actors-mcp-server')
+    .epilogue('For more information, visit https://mcp.apify.com or https://github.com/apify/actors-mcp-server')
     .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()) : [];
-const enableBeta = argv.beta;
+// Keys of the tool categories to enable
+const toolCategoryKeys = argv.tools ? argv.tools.split(',').map((t: string) => t.trim()) : [];
 
 // Validate environment
 if (!process.env.APIFY_TOKEN) {
@@ -88,8 +102,18 @@ if (!process.env.APIFY_TOKEN) {
 }
 
 async function main() {
-    const mcpServer = new ActorsMcpServer({ enableAddingActors, enableDefaultActors: false, enableBeta });
-    const tools = await getActorsAsTools(actorList.length ? actorList : defaults.actors, process.env.APIFY_TOKEN as string);
+    const mcpServer = new ActorsMcpServer({ enableAddingActors, enableDefaultActors: false });
+
+    // Create an Input object from CLI arguments
+    const input: Input = {
+        actors: actorList.length ? 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);
+
     mcpServer.upsertTools(tools);
 
     // Start server