fix: Provide better output. Fix datasetId in examples (#293)

* fix: Provide better output. Fix datasetId in examples

Author: jirispilka

README.md

@@ -26,7 +26,7 @@ The Apify Model Context Protocol (MCP) server at [**mcp.apify.com**](https://mcp
 >
 > It supports OAuth, so you can connect from clients like Claude.ai or Visual Studio Code with just the URL.
 
-![Apify-MCP-server](docs/actors-mcp-server.png)
+![Apify-MCP-server](https://raw.githubusercontent.com/apify/apify-mcp-server/refs/heads/master/docs/apify-mcp-server.png)
 
 ## Table of Contents
 - [🌐 Introducing the Apify MCP server](#-introducing-the-apify-mcp-server)

docs/actors-mcp-server.png renamed to docs/apify-mcp-server.png

@@ -306,11 +306,10 @@ const callActorArgs = z.object({
     actor: z.string()
         .describe('The name of the Actor to call. For example, "apify/rag-web-browser".'),
     step: z.enum(['info', 'call'])
-        .default('info')
         .describe(`Step to perform: "info" to get Actor details and input schema (required first step), "call" to run the Actor (only after getting info).`),
     input: z.object({}).passthrough()
         .optional()
-        .describe(`The input JSON to pass to the Actor. For example, {"query": "apify", "maxResults": 5, "outputFormats": ["markdown"]}. Required only when step is "call".`),
+        .describe(`The input JSON to pass to the Actor. For example, {"query": "apify", "maxResults": 5}. Must be used only when step="call".`),
     callOptions: z.object({
         memory: z.number()
             .min(128, 'Memory must be at least 128 MB')
@@ -369,6 +368,9 @@ EXAMPLES:
             const { args, apifyToken, progressTracker, extra, apifyMcpServer } = toolArgs;
             const { actor: actorName, step, input, callOptions } = callActorArgs.parse(args);
 
+            // If input is provided but step is not "call", we assume the user wants to call the Actor
+            const performStep = input && step !== 'call' ? 'call' : step;
+
             // Parse special format: actor:tool
             const mcpToolMatch = actorName.match(/^(.+):(.+)$/);
             let baseActorName = actorName;
@@ -382,7 +384,7 @@ EXAMPLES:
             // For definition resolution we always use token-based client; Skyfire is only for actual Actor runs
             const apifyClientForDefinition = new ApifyClient({ token: apifyToken });
             // Resolve MCP server URL
-            const needsMcpUrl = mcpToolName !== undefined || step === 'info';
+            const needsMcpUrl = mcpToolName !== undefined || performStep === 'info';
             const mcpServerUrlOrFalse = needsMcpUrl ? await getActorMcpUrlCached(baseActorName, apifyClientForDefinition) : false;
             const isActorMcpServer = mcpServerUrlOrFalse && typeof mcpServerUrlOrFalse === 'string';
 
@@ -392,7 +394,7 @@ EXAMPLES:
             }
 
             try {
-                if (step === 'info') {
+                if (performStep === 'info') {
                     if (isActorMcpServer) {
                         // MCP server: list tools
                         const mcpServerUrl = mcpServerUrlOrFalse;
@@ -419,19 +421,16 @@ EXAMPLES:
                             return buildMCPResponse([`Actor information for '${baseActorName}' was not found. Please check the Actor ID or name and ensure the Actor exists.`]);
                         }
                         const content = [
-                            // TODO: update result to say: this is result of info step, you must now call again with step=call and proper input
-                            { type: 'text', text: `Input schema: \n${JSON.stringify(details.inputSchema, null, 0)}` },
+                            `Actor name: ${actorName}`,
+                            `Input schema: \n${JSON.stringify(details.inputSchema, null, 0)}`,
+                            `To run Actor, use step="call" with Actor name format: "${actorName}"`,
                         ];
-                        /**
-                         * Add Skyfire instructions also in the info step since clients are most likely truncating the long tool description of the call-actor.
-                         */
+                        // Add Skyfire instructions also in the info performStep since clients are most likely truncating
+                        // the long tool description of the call-actor.
                         if (apifyMcpServer.options.skyfireMode) {
-                            content.push({
-                                type: 'text',
-                                text: SKYFIRE_TOOL_INSTRUCTIONS,
-                            });
+                            content.push(SKYFIRE_TOOL_INSTRUCTIONS);
                         }
-                        return { content };
+                        return buildMCPResponse(content);
                     }
                 }
 
@@ -496,12 +495,14 @@ EXAMPLES:
 
                 if (!actor.tool.ajvValidate(input)) {
                     const { errors } = actor.tool.ajvValidate;
+                    const content = [
+                        `Input validation failed for Actor '${actorName}'. Please ensure your input matches the Actor's input schema.`,
+                        `Input schema:\n${JSON.stringify(actor.tool.inputSchema)}`,
+                    ];
                     if (errors && errors.length > 0) {
-                        return buildMCPResponse([
-                            `Input validation failed for Actor '${actorName}': ${errors.map((e) => e.message).join(', ')}`,
-                            `Input schema:\n${JSON.stringify(actor.tool.inputSchema)}`,
-                        ]);
+                        content.push(`Validation errors: ${errors.map((e) => e.message).join(', ')}`);
                     }
+                    return buildMCPResponse(content);
                 }
 
                 const callResult = await callActorGetDataset(
@@ -523,7 +524,7 @@ EXAMPLES:
 
                 return { content };
             } catch (error) {
-                log.error('Failed to call Actor', { error, actorName, step });
+                log.error('Failed to call Actor', { error, actorName, performStep });
                 return buildMCPResponse([`Failed to call Actor '${actorName}': ${error instanceof Error ? error.message : String(error)}`]);
             }
         },

src/tools/actor.ts

@@ -55,7 +55,7 @@ USAGE:
 - Use when you need dataset metadata to understand its structure before fetching items.
 
 USAGE EXAMPLES:
-- user_input: Show info for dataset 8TtYhCwKzQeQk7dJx
+- user_input: Show info for dataset xyz123
 - user_input: What fields does username~my-dataset have?`,
         inputSchema: zodToJsonSchema(getDatasetArgs),
         ajvValidate: ajv.compile(zodToJsonSchema(getDatasetArgs)),
@@ -90,7 +90,7 @@ USAGE:
 - Use when you need to read data from a dataset (all items or only selected fields).
 
 USAGE EXAMPLES:
-- user_input: Get first 100 items from dataset 8TtYhCwKzQeQk7dJx
+- user_input: Get first 100 items from dataset abd123
 - user_input: Get only metadata.url and title from dataset username~my-dataset (flatten metadata)`,
         inputSchema: zodToJsonSchema(getDatasetItemsArgs),
         ajvValidate: ajv.compile(zodToJsonSchema(getDatasetItemsArgs)),
@@ -152,7 +152,7 @@ USAGE:
 - Use when you need to infer the structure of dataset items for downstream processing or validation.
 
 USAGE EXAMPLES:
-- user_input: Generate schema for dataset 8TtYhCwKzQeQk7dJx using 10 items
+- user_input: Generate schema for dataset 34das2 using 10 items
 - user_input: Show schema of username~my-dataset (clean items only)`,
         inputSchema: zodToJsonSchema(getDatasetSchemaArgs),
         ajvValidate: ajv.compile(zodToJsonSchema(getDatasetSchemaArgs)),

src/tools/dataset.ts

@@ -82,7 +82,7 @@ USAGE:
 USAGE EXAMPLES:
 - user_input: Get data of my last Actor run
 - user_input: Get number_of_likes from my dataset
-- user_input: Return only crawl.statusCode and url from dataset 8TtYhCwKzQeQk7dJx
+- user_input: Return only crawl.statusCode and url from dataset aab123
 
 Note: This tool is automatically included if the Apify MCP Server is configured with any Actor tools (e.g., "apify-slash-rag-web-browser") or tools that can interact with Actors (e.g., "call-actor", "add-actor").`,
         inputSchema: zodToJsonSchema(getActorOutputArgs),

src/tools/get-actor-output.ts

@@ -28,7 +28,7 @@ USAGE:
 
 USAGE EXAMPLES:
 - user_input: Show info for key-value store username~my-store
-- user_input: Get details for store 8TtYhCwKzQeQk7dJx`,
+- user_input: Get details for store adb123`,
         inputSchema: zodToJsonSchema(getKeyValueStoreArgs),
         ajvValidate: ajv.compile(zodToJsonSchema(getKeyValueStoreArgs)),
         call: async (toolArgs) => {
@@ -71,7 +71,7 @@ USAGE:
 
 USAGE EXAMPLES:
 - user_input: List first 100 keys in store username~my-store
-- user_input: Continue listing keys in store 8TtYhCwKzQeQk7dJx from key data.json`,
+- user_input: Continue listing keys in store a123 from key data.json`,
         inputSchema: zodToJsonSchema(getKeyValueStoreKeysArgs),
         ajvValidate: ajv.compile(zodToJsonSchema(getKeyValueStoreKeysArgs)),
         call: async (toolArgs) => {
@@ -111,7 +111,7 @@ USAGE:
 - Use when you need to retrieve a specific record (JSON, text, or binary) from a store.
 
 USAGE EXAMPLES:
-- user_input: Get record INPUT from store 8TtYhCwKzQeQk7dJx
+- user_input: Get record INPUT from store abc123
 - user_input: Get record data.json from store username~my-store`,
         inputSchema: zodToJsonSchema(getKeyValueStoreRecordArgs),
         ajvValidate: ajv.compile(zodToJsonSchema(getKeyValueStoreRecordArgs)),