feat: Improve error handling (required for claude connector)

jirispilka · jirispilka · commit 602cc2838f66 · 2025-11-10T14:11:45.000+01:00
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
@@ -179,7 +179,7 @@ export class ActorsMcpServer {
     * Loads missing toolNames from a provided list of tool names.
     * Skips toolNames that are already loaded and loads only the missing ones.
     * @param toolNames - Array of tool names to ensure are loaded
-    * @param apifyToken - Apify API token for authentication
+    * @param apifyClient
     */
     public async loadToolsByName(toolNames: string[], apifyClient: ApifyClient) {
         const loadedTools = this.listAllToolNames();
@@ -214,7 +214,7 @@ export class ActorsMcpServer {
      * Load actors as tools, upsert them to the server, and return the tool entries.
      * This is a public method that wraps getActorsAsTools and handles the upsert operation.
      * @param actorIdsOrNames - Array of actor IDs or names to load as tools
-     * @param apifyToken - Apify API token for authentication
+     * @param apifyClient - Apify API token for authentication
      * @returns Promise<ToolEntry[]> - Array of loaded tool entries
      */
     public async loadActorsAsTools(actorIdsOrNames: string[], apifyClient: ApifyClient): Promise<ToolEntry[]> {
@@ -482,7 +482,9 @@ export class ActorsMcpServer {
 
             // Validate token
             if (!apifyToken && !this.options.skyfireMode) {
-                const msg = 'APIFY_TOKEN is required. It must be set in the environment variables or passed as a parameter in the body.';
+                const msg = `APIFY_TOKEN is required but was not provided.
+Please set the APIFY_TOKEN environment variable or pass it as a parameter in the request body.
+You can obtain your Apify token from https://console.apify.com/account/integrations.`;
                 log.error(msg);
                 await this.server.sendLoggingMessage({ level: 'error', data: msg });
                 throw new McpError(
@@ -506,7 +508,10 @@ export class ActorsMcpServer {
             const tool = Array.from(this.tools.values())
                 .find((t) => t.name === name || (t.type === 'actor' && t.actorFullName === name));
             if (!tool) {
-                const msg = `Tool ${name} not found. Available tools: ${this.listToolNames().join(', ')}`;
+                const availableTools = this.listToolNames();
+                const msg = `Tool "${name}" was not found.
+Available tools: ${availableTools.length > 0 ? availableTools.join(', ') : 'none'}.
+Please verify the tool name is correct. You can list all available tools using the tools/list request.`;
                 log.error(msg);
                 await this.server.sendLoggingMessage({ level: 'error', data: msg });
                 throw new McpError(
@@ -515,7 +520,8 @@ export class ActorsMcpServer {
                 );
             }
             if (!args) {
-                const msg = `Missing arguments for tool ${name}`;
+                const msg = `Missing arguments for tool "${name}".
+Please provide the required arguments for this tool. Check the tool's input schema to see what parameters are required.`;
                 log.error(msg);
                 await this.server.sendLoggingMessage({ level: 'error', data: msg });
                 throw new McpError(
@@ -528,7 +534,11 @@ export class ActorsMcpServer {
             args = decodeDotPropertyNames(args);
             log.debug('Validate arguments for tool', { toolName: tool.name, input: args });
             if (!tool.ajvValidate(args)) {
-                const msg = `Invalid arguments for tool ${tool.name}: args: ${JSON.stringify(args)} error: ${JSON.stringify(tool?.ajvValidate.errors)}`;
+                const errors = tool?.ajvValidate.errors || [];
+                const errorMessages = errors.map((e: { message?: string; instancePath?: string }) => `${e.instancePath || 'root'}: ${e.message || 'validation error'}`).join('; ');
+                const msg = `Invalid arguments for tool "${tool.name}".
+Validation errors: ${errorMessages}.
+Please check the tool's input schema and ensure all required parameters are provided with correct types and values.`;
                 log.error(msg);
                 await this.server.sendLoggingMessage({ level: 'error', data: msg });
                 throw new McpError(
@@ -568,14 +578,11 @@ export class ActorsMcpServer {
                     try {
                         client = await connectMCPClient(tool.serverUrl, apifyToken);
                         if (!client) {
-                            const msg = `Failed to connect to MCP server ${tool.serverUrl}`;
+                            const msg = `Failed to connect to MCP server at "${tool.serverUrl}".
+Please verify the server URL is correct and accessible, and ensure you have a valid Apify token with appropriate permissions.`;
                             log.error(msg);
                             await this.server.sendLoggingMessage({ level: 'error', data: msg });
-                            return {
-                                content: [
-                                    { type: 'text', text: msg },
-                                ],
-                            };
+                            return buildMCPResponse([msg]);
                         }
 
                         // Only set up notification handlers if progressToken is provided by the client
@@ -616,12 +623,7 @@ export class ActorsMcpServer {
                     if (this.options.skyfireMode
                         && args['skyfire-pay-id'] === undefined
                     ) {
-                        return {
-                            content: [{
-                                type: 'text',
-                                text: SKYFIRE_TOOL_INSTRUCTIONS,
-                            }],
-                        };
+                        return buildMCPResponse([SKYFIRE_TOOL_INSTRUCTIONS]);
                     }
 
                     // Create progress tracker if progressToken is available
@@ -666,11 +668,15 @@ export class ActorsMcpServer {
                 log.error('Error occurred while calling tool', { toolName: name, error });
                 const errorMessage = (error instanceof Error) ? error.message : 'Unknown error';
                 return buildMCPResponse([
-                    `Error calling tool ${name}: ${errorMessage}`,
+                    `Error calling tool "${name}": ${errorMessage}.
+Please verify the tool name, input parameters, and ensure all required resources are available.`,
                 ]);
             }
 
-            const msg = `Unknown tool: ${name}`;
+            const availableTools = this.listToolNames();
+            const msg = `Unknown tool type for "${name}".
+Available tools: ${availableTools.length > 0 ? availableTools.join(', ') : 'none'}.
+Please verify the tool name and ensure the tool is properly registered.`;
             log.error(msg);
             await this.server.sendLoggingMessage({
                 level: 'error',
diff --git a/src/tools/actor.ts b/src/tools/actor.ts
@@ -386,7 +386,9 @@ EXAMPLES:
 
         // Standby Actors, thus MCPs, are not supported in Skyfire mode
         if (isActorMcpServer && apifyMcpServer.options.skyfireMode) {
-            return buildMCPResponse([`MCP server Actors are not supported in Skyfire mode. Please use a regular Apify token without Skyfire.`]);
+            return buildMCPResponse([
+                `This Actor (${actorName}) is an MCP server and cannot be accessed using a Skyfire token. To use this Actor, please provide a valid Apify token instead of a Skyfire token.`,
+            ]);
         }
 
         try {
@@ -414,7 +416,9 @@ EXAMPLES:
                     // Regular actor: return schema
                     const details = await fetchActorDetails(apifyClientForDefinition, baseActorName);
                     if (!details) {
-                        return buildMCPResponse([`Actor information for '${baseActorName}' was not found. Please check the Actor ID or name and ensure the Actor exists.`]);
+                        return buildMCPResponse([`Actor information for '${baseActorName}' was not found.
+Please verify Actor ID or name format (e.g., "username/name" like "apify/rag-web-browser") and ensure that the Actor exists.
+You can search for available Actors using the tool: ${HelperTools.STORE_SEARCH}.`]);
                     }
                     const content = [
                         `Actor name: ${actorName}`,
@@ -493,7 +497,9 @@ EXAMPLES:
             const [actor] = await getActorsAsTools([actorName], apifyClient);
 
             if (!actor) {
-                return buildMCPResponse([`Actor '${actorName}' was not found.`]);
+                return buildMCPResponse([`Actor '${actorName}' was not found.
+Please verify Actor ID or name format (e.g., "username/name" like "apify/rag-web-browser") and ensure that the Actor exists.
+You can search for available Actors using the tool: ${HelperTools.STORE_SEARCH}.`]);
             }
 
             if (!actor.ajvValidate(input)) {
@@ -528,7 +534,9 @@ EXAMPLES:
             return { content };
         } catch (error) {
             log.error('Failed to call Actor', { error, actorName, performStep });
-            return buildMCPResponse([`Failed to call Actor '${actorName}': ${error instanceof Error ? error.message : String(error)}`]);
+            return buildMCPResponse([`Failed to call Actor '${actorName}': ${error instanceof Error ? error.message : String(error)}.
+Please verify the Actor name, input parameters, and ensure the Actor exists.
+You can search for available Actors using the tool: ${HelperTools.STORE_SEARCH}, or get Actor details using: ${HelperTools.ACTOR_GET_DETAILS}.`]);
         }
     },
 };
diff --git a/src/tools/fetch-actor-details.ts b/src/tools/fetch-actor-details.ts
@@ -6,6 +6,7 @@ import { HelperTools } from '../const.js';
 import type { InternalToolArgs, ToolEntry, ToolInputSchema } from '../types.js';
 import { fetchActorDetails } from '../utils/actor-details.js';
 import { ajv } from '../utils/ajv.js';
+import { buildMCPResponse } from '../utils/mcp.js';
 
 const fetchActorDetailsToolArgsSchema = z.object({
     actor: z.string()
@@ -35,26 +36,28 @@ USAGE EXAMPLES:
         const apifyClient = new ApifyClient({ token: apifyToken });
         const details = await fetchActorDetails(apifyClient, parsed.actor);
         if (!details) {
-            return {
-                content: [{ type: 'text', text: `Actor information for '${parsed.actor}' was not found. Please check the Actor ID or name and ensure the Actor exists.` }],
-            };
+            const texts = [`Actor information for '${parsed.actor}' was not found.
+Please verify Actor ID or name format and ensure that the Actor exists.
+You can search for available Actors using the tool: ${HelperTools.STORE_SEARCH}.`,
+            ];
+            return buildMCPResponse(texts);
         }
 
         const actorUrl = `https://apify.com/${details.actorInfo.username}/${details.actorInfo.name}`;
         // Add link to README title
         details.readme = details.readme.replace(/^# /, `# [README](${actorUrl}/readme): `);
 
-        const content = [
-            { type: 'text', text: `# Actor information\n${details.actorCard}` },
-            { type: 'text', text: `${details.readme}` },
+        const texts = [
+            `# Actor information\n${details.actorCard}`,
+            `${details.readme}`,
         ];
 
         // Include input schema if it has properties
         if (details.inputSchema.properties || Object.keys(details.inputSchema.properties).length !== 0) {
-            content.push({ type: 'text', text: `# [Input schema](${actorUrl}/input)\n\`\`\`json\n${JSON.stringify(details.inputSchema)}\n\`\`\`` });
+            texts.push(`# [Input schema](${actorUrl}/input)\n\`\`\`json\n${JSON.stringify(details.inputSchema)}\n\`\`\``);
         }
         // Return the actor card, README, and input schema (if it has non-empty properties) as separate text blocks
         // This allows better formatting in the final output
-        return { content };
+        return buildMCPResponse(texts);
     },
 } as const;
diff --git a/src/tools/fetch-apify-docs.ts b/src/tools/fetch-apify-docs.ts
@@ -8,6 +8,7 @@ import { fetchApifyDocsCache } from '../state.js';
 import type { InternalToolArgs, ToolEntry, ToolInputSchema } from '../types.js';
 import { ajv } from '../utils/ajv.js';
 import { htmlToMarkdown } from '../utils/html-to-md.js';
+import { buildMCPResponse } from '../utils/mcp.js';
 
 const fetchApifyDocsToolArgsSchema = z.object({
     url: z.string()
@@ -38,12 +39,9 @@ USAGE EXAMPLES:
 
         // Only allow URLs starting with https://docs.apify.com
         if (!url.startsWith('https://docs.apify.com')) {
-            return {
-                content: [{
-                    type: 'text',
-                    text: `Only URLs starting with https://docs.apify.com are allowed.`,
-                }],
-            };
+            return buildMCPResponse([`Invalid URL: "${url}".
+Only URLs starting with "https://docs.apify.com" are allowed.
+Please provide a valid Apify documentation URL. You can find documentation URLs using the ${HelperTools.DOCS_SEARCH} tool.`]);
         }
 
         // Cache URL without fragment to avoid fetching the same page multiple times
@@ -53,12 +51,9 @@ USAGE EXAMPLES:
             try {
                 const response = await fetch(url);
                 if (!response.ok) {
-                    return {
-                        content: [{
-                            type: 'text',
-                            text: `Failed to fetch the documentation page at ${url}. Status: ${response.status} ${response.statusText}`,
-                        }],
-                    };
+                    return buildMCPResponse([`Failed to fetch the documentation page at "${url}".
+HTTP Status: ${response.status} ${response.statusText}.
+Please verify the URL is correct and accessible. You can search for available documentation pages using the ${HelperTools.DOCS_SEARCH} tool.`]);
                 }
                 const html = await response.text();
                 markdown = htmlToMarkdown(html);
@@ -67,20 +62,12 @@ USAGE EXAMPLES:
                 fetchApifyDocsCache.set(urlWithoutFragment, markdown);
             } catch (error) {
                 log.error('Failed to fetch the documentation page', { url, error });
-                return {
-                    content: [{
-                        type: 'text',
-                        text: `Failed to fetch the documentation page at ${url}. Please check the URL and try again.`,
-                    }],
-                };
+                return buildMCPResponse([`Failed to fetch the documentation page at "${url}".
+Error: ${error instanceof Error ? error.message : String(error)}.
+Please verify the URL is correct and accessible. You can search for available documentation pages using the ${HelperTools.DOCS_SEARCH} tool.`]);
             }
         }
 
-        return {
-            content: [{
-                type: 'text',
-                text: `Fetched content from ${url}:\n\n${markdown}`,
-            }],
-        };
+        return buildMCPResponse([`Fetched content from ${url}:\n\n${markdown}`]);
     },
 } as const;
diff --git a/src/tools/search-apify-docs.ts b/src/tools/search-apify-docs.ts
@@ -5,6 +5,7 @@ import { HelperTools } from '../const.js';
 import type { InternalToolArgs, ToolEntry, ToolInputSchema } from '../types.js';
 import { ajv } from '../utils/ajv.js';
 import { searchApifyDocsCached } from '../utils/apify-docs.js';
+import { buildMCPResponse } from '../utils/mcp.js';
 
 const searchApifyDocsToolArgsSchema = z.object({
     query: z.string()
@@ -30,24 +31,24 @@ export const searchApifyDocsTool: ToolEntry = {
     type: 'internal',
     name: HelperTools.DOCS_SEARCH,
     description: `Search Apify documentation using full-text search.
-    You can use it to find relevant documentation based on keywords.
-    Apify documentation has information about Apify console, Actors (development
-    (actor.json, input schema, dataset schema, dockerfile), deployment, builds, runs),
-    schedules, storages (datasets, key-value store), Proxy, Integrations,
-    Apify Academy (crawling and webscraping with Crawlee),
+You can use it to find relevant documentation based on keywords.
+Apify documentation has information about Apify console, Actors (development
+(actor.json, input schema, dataset schema, dockerfile), deployment, builds, runs),
+schedules, storages (datasets, key-value store), Proxy, Integrations,
+Apify Academy (crawling and webscraping with Crawlee),
 
-    The results will include the URL of the documentation page, a fragment identifier (if available),
-    and a limited piece of content that matches the search query.
+The results will include the URL of the documentation page, a fragment identifier (if available),
+and a limited piece of content that matches the search query.
 
-    Fetch the full content of the document using the ${HelperTools.DOCS_FETCH} tool by providing the URL.
+Fetch the full content of the document using the ${HelperTools.DOCS_FETCH} tool by providing the URL.
 
-    USAGE:
-    - Use when user asks about Apify documentation, Actor development, Crawlee, or Apify platform.
+USAGE:
+- Use when user asks about Apify documentation, Actor development, Crawlee, or Apify platform.
 
-    USAGE EXAMPLES:
-    - query: How to use create Apify Actor?
-    - query: How to define Actor input schema?
-    - query: How scrape with Crawlee?`,
+USAGE EXAMPLES:
+- query: How to use create Apify Actor?
+- query: How to define Actor input schema?
+- query: How scrape with Crawlee?`,
     inputSchema: zodToJsonSchema(searchApifyDocsToolArgsSchema) as ToolInputSchema,
     ajvValidate: ajv.compile(zodToJsonSchema(searchApifyDocsToolArgsSchema)),
     call: async (toolArgs: InternalToolArgs) => {
@@ -60,24 +61,16 @@ export const searchApifyDocsTool: ToolEntry = {
         const results = resultsRaw.slice(parsed.offset, parsed.offset + parsed.limit);
 
         if (results.length === 0) {
-            return {
-                content: [{
-                    type: 'text',
-                    text: `No results found for the query "${query}" with limit ${parsed.limit} and offset ${parsed.offset}. Try a different query or adjust the limit and offset.`,
-                }],
-            };
+            return buildMCPResponse([`No results found for the query "${query}" with limit ${parsed.limit} and offset ${parsed.offset}.
+Please try a different query with different keywords, or adjust the limit and offset parameters.
+You can also try using more specific or alternative keywords related to your search topic.`]);
         }
 
         const textContent = `You can use the Apify docs fetch tool to retrieve the full content of a document by its URL. The document fragment refers to the section of the content containing the relevant part for the search result item.
 Search results for "${query}":
 
 ${results.map((result) => `- Document URL: ${result.url}${result.fragment ? `\n  Document fragment: ${result.fragment}` : ''}
   Content: ${result.content}`).join('\n\n')}`;
-        return {
-            content: [{
-                type: 'text',
-                text: textContent,
-            }],
-        };
+        return buildMCPResponse([textContent]);
     },
 } as const;
diff --git a/src/tools/store_collection.ts b/src/tools/store_collection.ts
