fix: Add isError flag to tool execution errors per MCP spec

jirispilka · jirispilka · commit 6e1bf5e8979b · 2025-11-19T11:17:59.000+01:00
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
@@ -583,7 +583,7 @@ Please check the tool's input schema using ${HelperTools.ACTOR_GET_DETAILS} tool
 Please verify the server URL is correct and accessible, and ensure you have a valid Apify token with appropriate permissions.`;
                             log.softFail(msg, { statusCode: 408 }); // 408 Request Timeout
                             await this.server.sendLoggingMessage({ level: 'error', data: msg });
-                            return buildMCPResponse([msg]);
+                            return buildMCPResponse([msg], true);
                         }
 
                         // Only set up notification handlers if progressToken is provided by the client
@@ -671,7 +671,7 @@ Please verify the server URL is correct and accessible, and ensure you have a va
                 return buildMCPResponse([
                     `Error calling tool "${name}": ${errorMessage}.
 Please verify the tool name, input parameters, and ensure all required resources are available.`,
-                ]);
+                ], true);
             }
 
             const availableTools = this.listToolNames();
diff --git a/src/tools/actor.ts b/src/tools/actor.ts
@@ -410,7 +410,7 @@ EXAMPLES:
         if (isActorMcpServer && apifyMcpServer.options.skyfireMode) {
             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.`,
-            ]);
+            ], true);
         }
 
         try {
@@ -423,7 +423,7 @@ EXAMPLES:
                     try {
                         client = await connectMCPClient(mcpServerUrl, apifyToken);
                         if (!client) {
-                            return buildMCPResponse([`Failed to connect to MCP server ${mcpServerUrl}`]);
+                            return buildMCPResponse([`Failed to connect to MCP server ${mcpServerUrl}`], true);
                         }
                         const toolsResponse = await client.listTools();
 
@@ -440,7 +440,7 @@ EXAMPLES:
                     if (!details) {
                         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}.`]);
+You can search for available Actors using the tool: ${HelperTools.STORE_SEARCH}.`], true);
                     }
                     const content = [
                         `Actor name: ${actorName}`,
@@ -478,28 +478,28 @@ You can search for available Actors using the tool: ${HelperTools.STORE_SEARCH}.
 
             // Step 2: Call the Actor
             if (!input) {
-                return buildMCPResponse([`Input is required when step="call". Please provide the input parameter based on the Actor's input schema.`]);
+                return buildMCPResponse([`Input is required when step="call". Please provide the input parameter based on the Actor's input schema.`], true);
             }
 
             // Handle the case where LLM does not respect instructions when calling MCP server Actors
             // and does not provide the tool name.
             const isMcpToolNameInvalid = mcpToolName === undefined || mcpToolName.trim().length === 0;
             if (isActorMcpServer && isMcpToolNameInvalid) {
-                return buildMCPResponse([CALL_ACTOR_MCP_MISSING_TOOL_NAME_MSG]);
+                return buildMCPResponse([CALL_ACTOR_MCP_MISSING_TOOL_NAME_MSG], true);
             }
 
             // Handle MCP tool calls
             if (mcpToolName) {
                 if (!isActorMcpServer) {
-                    return buildMCPResponse([`Actor '${baseActorName}' is not an MCP server.`]);
+                    return buildMCPResponse([`Actor '${baseActorName}' is not an MCP server.`], true);
                 }
 
                 const mcpServerUrl = mcpServerUrlOrFalse;
                 let client: Client | null = null;
                 try {
                     client = await connectMCPClient(mcpServerUrl, apifyToken);
                     if (!client) {
-                        return buildMCPResponse([`Failed to connect to MCP server ${mcpServerUrl}`]);
+                        return buildMCPResponse([`Failed to connect to MCP server ${mcpServerUrl}`], true);
                     }
 
                     const result = await client.callTool({
@@ -519,7 +519,7 @@ You can search for available Actors using the tool: ${HelperTools.STORE_SEARCH}.
             if (!actor) {
                 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}.`]);
+You can search for available Actors using the tool: ${HelperTools.STORE_SEARCH}.`], true);
             }
 
             if (!actor.ajvValidate(input)) {
@@ -556,7 +556,7 @@ You can search for available Actors using the tool: ${HelperTools.STORE_SEARCH}.
             logHttpError(error, 'Failed to call Actor', { actorName, performStep });
             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}.`]);
+You can search for available Actors using the tool: ${HelperTools.STORE_SEARCH}, or get Actor details using: ${HelperTools.ACTOR_GET_DETAILS}.`], true);
         }
     },
 };
diff --git a/src/tools/build.ts b/src/tools/build.ts
@@ -138,7 +138,7 @@ export const actorDefinitionTool: ToolEntry = {
         try {
             const v = await getActorDefinition(parsed.actorName, apifyClient, parsed.limit);
             if (!v) {
-                return { content: [{ type: 'text', text: `Actor '${parsed.actorName}' not found.` }] };
+                return { content: [{ type: 'text', text: `Actor '${parsed.actorName}' not found.` }], isError: true };
             }
             if (v && v.input && 'properties' in v.input && v.input) {
                 const properties = filterSchemaProperties(v.input.properties as { [key: string]: ISchemaProperties });
@@ -151,6 +151,7 @@ export const actorDefinitionTool: ToolEntry = {
                     type: 'text',
                     text: `Failed to fetch Actor definition: ${error instanceof Error ? error.message : String(error)}`,
                 }],
+                isError: true,
             };
         }
     },
diff --git a/src/tools/dataset.ts b/src/tools/dataset.ts
@@ -68,7 +68,7 @@ USAGE EXAMPLES:
         const client = new ApifyClient({ token: apifyToken });
         const v = await client.dataset(parsed.datasetId).get();
         if (!v) {
-            return { content: [{ type: 'text', text: `Dataset '${parsed.datasetId}' not found.` }] };
+            return { content: [{ type: 'text', text: `Dataset '${parsed.datasetId}' not found.` }], isError: true };
         }
         return { content: [{ type: 'text', text: `\`\`\`json\n${JSON.stringify(v)}\n\`\`\`` }] };
     },
@@ -119,7 +119,7 @@ USAGE EXAMPLES:
             flatten,
         });
         if (!v) {
-            return { content: [{ type: 'text', text: `Dataset '${parsed.datasetId}' not found.` }] };
+            return { content: [{ type: 'text', text: `Dataset '${parsed.datasetId}' not found.` }], isError: true };
         }
         return { content: [{ type: 'text', text: `\`\`\`json\n${JSON.stringify(v)}\n\`\`\`` }] };
     },
@@ -175,7 +175,7 @@ USAGE EXAMPLES:
         });
 
         if (!datasetResponse) {
-            return { content: [{ type: 'text', text: `Dataset '${parsed.datasetId}' not found.` }] };
+            return { content: [{ type: 'text', text: `Dataset '${parsed.datasetId}' not found.` }], isError: true };
         }
 
         const datasetItems = datasetResponse.items;
@@ -192,7 +192,7 @@ USAGE EXAMPLES:
         });
 
         if (!schema) {
-            return { content: [{ type: 'text', text: `Failed to generate schema for dataset '${parsed.datasetId}'.` }] };
+            return { content: [{ type: 'text', text: `Failed to generate schema for dataset '${parsed.datasetId}'.` }], isError: true };
         }
 
         return {
diff --git a/src/tools/fetch-actor-details.ts b/src/tools/fetch-actor-details.ts
@@ -45,7 +45,7 @@ USAGE EXAMPLES:
 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);
+            return buildMCPResponse(texts, true);
         }
 
         const actorUrl = `https://apify.com/${details.actorInfo.username}/${details.actorInfo.name}`;
diff --git a/src/tools/fetch-apify-docs.ts b/src/tools/fetch-apify-docs.ts
@@ -45,7 +45,7 @@ USAGE EXAMPLES:
         if (!url.startsWith('https://docs.apify.com')) {
             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.`]);
+Please provide a valid Apify documentation URL. You can find documentation URLs using the ${HelperTools.DOCS_SEARCH} tool.`], true);
         }
 
         // Cache URL without fragment to avoid fetching the same page multiple times
@@ -61,7 +61,7 @@ Please provide a valid Apify documentation URL. You can find documentation URLs
                     logHttpError(error, 'Failed to fetch the documentation page', { url, statusText: 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.`]);
+Please verify the URL is correct and accessible. You can search for available documentation pages using the ${HelperTools.DOCS_SEARCH} tool.`], true);
                 }
                 const html = await response.text();
                 markdown = htmlToMarkdown(html);
@@ -72,7 +72,7 @@ Please verify the URL is correct and accessible. You can search for available do
                 logHttpError(error, 'Failed to fetch the documentation page', { url });
                 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.`]);
+Please verify the URL is correct and accessible. You can search for available documentation pages using the ${HelperTools.DOCS_SEARCH} tool.`], true);
             }
         }
 
diff --git a/src/tools/get-actor-output.ts b/src/tools/get-actor-output.ts
@@ -136,7 +136,7 @@ Note: This tool is automatically included if the Apify MCP Server is configured
         });
 
         if (!response) {
-            return { content: [{ type: 'text', text: `Dataset '${parsed.datasetId}' not found.` }] };
+            return { content: [{ type: 'text', text: `Dataset '${parsed.datasetId}' not found.` }], isError: true };
         }
 
         let { items } = response;
diff --git a/src/tools/get-html-skeleton.ts b/src/tools/get-html-skeleton.ts
@@ -62,7 +62,7 @@ USAGE EXAMPLES:
         const parsed = getHtmlSkeletonArgs.parse(args);
 
         if (!isValidHttpUrl(parsed.url)) {
-            return buildMCPResponse([`The provided URL is not a valid HTTP or HTTPS URL: ${parsed.url}`]);
+            return buildMCPResponse([`The provided URL is not a valid HTTP or HTTPS URL: ${parsed.url}`], true);
         }
 
         // Try to get from cache first
@@ -81,16 +81,16 @@ USAGE EXAMPLES:
 
             const datasetItems = await client.dataset(run.defaultDatasetId).listItems();
             if (datasetItems.items.length === 0) {
-                return buildMCPResponse([`The scraping Actor (${RAG_WEB_BROWSER}) did not return any output for the URL: ${parsed.url}. Please check the Actor run for more details: ${run.id}`]);
+                return buildMCPResponse([`The scraping Actor (${RAG_WEB_BROWSER}) did not return any output for the URL: ${parsed.url}. Please check the Actor run for more details: ${run.id}`], true);
             }
 
             const firstItem = datasetItems.items[0] as unknown as ScrapedPageItem;
             if (firstItem.crawl.httpStatusMessage.toLocaleLowerCase() !== 'ok') {
-                return buildMCPResponse([`The scraping Actor (${RAG_WEB_BROWSER}) returned an HTTP status ${firstItem.crawl.httpStatusCode} (${firstItem.crawl.httpStatusMessage}) for the URL: ${parsed.url}. Please check the Actor run for more details: ${run.id}`]);
+                return buildMCPResponse([`The scraping Actor (${RAG_WEB_BROWSER}) returned an HTTP status ${firstItem.crawl.httpStatusCode} (${firstItem.crawl.httpStatusMessage}) for the URL: ${parsed.url}. Please check the Actor run for more details: ${run.id}`], true);
             }
 
             if (!firstItem.html) {
-                return buildMCPResponse([`The scraping Actor (${RAG_WEB_BROWSER}) did not return any HTML content for the URL: ${parsed.url}. Please check the Actor run for more details: ${run.id}`]);
+                return buildMCPResponse([`The scraping Actor (${RAG_WEB_BROWSER}) did not return any HTML content for the URL: ${parsed.url}. Please check the Actor run for more details: ${run.id}`], true);
             }
 
             strippedHtml = stripHtml(firstItem.html);
diff --git a/src/tools/run.ts b/src/tools/run.ts
@@ -47,7 +47,7 @@ USAGE EXAMPLES:
         const client = new ApifyClient({ token: apifyToken });
         const v = await client.run(parsed.runId).get();
         if (!v) {
-            return { content: [{ type: 'text', text: `Run with ID '${parsed.runId}' not found.` }] };
+            return { content: [{ type: 'text', text: `Run with ID '${parsed.runId}' not found.` }], isError: true };
         }
         return { content: [{ type: 'text', text: `\`\`\`json\n${JSON.stringify(v)}\n\`\`\`` }] };
     },
diff --git a/src/utils/mcp.ts b/src/utils/mcp.ts
@@ -1,8 +1,11 @@
 /**
  * Helper to build a response for MCP from an array of text strings.
+ * @param texts - Array of text strings to include in the response
+ * @param isError - Optional flag to mark the response as an error (default: false)
  */
-export function buildMCPResponse(texts: string[]) {
+export function buildMCPResponse(texts: string[], isError = false) {
     return {
         content: texts.map((text) => ({ type: 'text', text })),
+        isError,
     };
 }
diff --git a/tests/integration/suite.ts b/tests/integration/suite.ts
@@ -1043,7 +1043,7 @@ export function createIntegrationTestsSuite(
             await client.close();
         });
 
-        it('should return error message when tryging to call MCP server Actor without tool name in actor parameter', async () => {
+        it('should return error message when trying to call MCP server Actor without tool name in actor parameter', async () => {
             client = await createClientFn({ tools: ['actors'] });
 
             const response = await client.callTool({
@@ -1059,6 +1059,7 @@ export function createIntegrationTestsSuite(
             const content = response.content as { text: string }[];
             expect(content.length).toBeGreaterThan(0);
             expect(content[0].text).toContain(CALL_ACTOR_MCP_MISSING_TOOL_NAME_MSG);
+            expect(response.isError).toBe(true);
 
             await client.close();
         });

Original file line number	Diff line number	Diff line change
`@@ -45,7 +45,7 @@ USAGE EXAMPLES:`
`45`	`45`	`Please verify Actor ID or name format and ensure that the Actor exists.`
`46`	`46`	You can search for available Actors using the tool: ${HelperTools.STORE_SEARCH}.`,
`47`	`47`	`];`
`48`		`- return buildMCPResponse(texts);`
	`48`	`+ return buildMCPResponse(texts, true);`
`49`	`49`	`}`
`50`	`50`
`51`	`51`	const actorUrl = `https://apify.com/${details.actorInfo.username}/${details.actorInfo.name}`;
Original file line number	Diff line number	Diff line change
`@@ -136,7 +136,7 @@ Note: This tool is automatically included if the Apify MCP Server is configured`
`136`	`136`	`});`
`137`	`137`
`138`	`138`	`if (!response) {`
`139`		- return { content: [{ type: 'text', text: `Dataset '${parsed.datasetId}' not found.` }] };
	`139`	+ return { content: [{ type: 'text', text: `Dataset '${parsed.datasetId}' not found.` }], isError: true };
`140`	`140`	`}`
`141`	`141`
`142`	`142`	`let { items } = response;`
Original file line number	Diff line number	Diff line change
`@@ -62,7 +62,7 @@ USAGE EXAMPLES:`
`62`	`62`	`const parsed = getHtmlSkeletonArgs.parse(args);`
`63`	`63`
`64`	`64`	`if (!isValidHttpUrl(parsed.url)) {`
`65`		- return buildMCPResponse([`The provided URL is not a valid HTTP or HTTPS URL: ${parsed.url}`]);
	`65`	+ return buildMCPResponse([`The provided URL is not a valid HTTP or HTTPS URL: ${parsed.url}`], true);
`66`	`66`	`}`
`67`	`67`
`68`	`68`	`// Try to get from cache first`
`@@ -81,16 +81,16 @@ USAGE EXAMPLES:`
`81`	`81`
`82`	`82`	`const datasetItems = await client.dataset(run.defaultDatasetId).listItems();`
`83`	`83`	`if (datasetItems.items.length === 0) {`
`84`		- return buildMCPResponse([`The scraping Actor (${RAG_WEB_BROWSER}) did not return any output for the URL: ${parsed.url}. Please check the Actor run for more details: ${run.id}`]);
	`84`	+ return buildMCPResponse([`The scraping Actor (${RAG_WEB_BROWSER}) did not return any output for the URL: ${parsed.url}. Please check the Actor run for more details: ${run.id}`], true);
`85`	`85`	`}`
`86`	`86`
`87`	`87`	`const firstItem = datasetItems.items[0] as unknown as ScrapedPageItem;`
`88`	`88`	`if (firstItem.crawl.httpStatusMessage.toLocaleLowerCase() !== 'ok') {`
`89`		- return buildMCPResponse([`The scraping Actor (${RAG_WEB_BROWSER}) returned an HTTP status ${firstItem.crawl.httpStatusCode} (${firstItem.crawl.httpStatusMessage}) for the URL: ${parsed.url}. Please check the Actor run for more details: ${run.id}`]);
	`89`	+ return buildMCPResponse([`The scraping Actor (${RAG_WEB_BROWSER}) returned an HTTP status ${firstItem.crawl.httpStatusCode} (${firstItem.crawl.httpStatusMessage}) for the URL: ${parsed.url}. Please check the Actor run for more details: ${run.id}`], true);
`90`	`90`	`}`
`91`	`91`
`92`	`92`	`if (!firstItem.html) {`
`93`		- return buildMCPResponse([`The scraping Actor (${RAG_WEB_BROWSER}) did not return any HTML content for the URL: ${parsed.url}. Please check the Actor run for more details: ${run.id}`]);
	`93`	+ return buildMCPResponse([`The scraping Actor (${RAG_WEB_BROWSER}) did not return any HTML content for the URL: ${parsed.url}. Please check the Actor run for more details: ${run.id}`], true);
`94`	`94`	`}`
`95`	`95`
`96`	`96`	`strippedHtml = stripHtml(firstItem.html);`
Original file line number	Diff line number	Diff line change
`@@ -47,7 +47,7 @@ USAGE EXAMPLES:`
`47`	`47`	`const client = new ApifyClient({ token: apifyToken });`
`48`	`48`	`const v = await client.run(parsed.runId).get();`
`49`	`49`	`if (!v) {`
`50`		- return { content: [{ type: 'text', text: `Run with ID '${parsed.runId}' not found.` }] };
	`50`	+ return { content: [{ type: 'text', text: `Run with ID '${parsed.runId}' not found.` }], isError: true };
`51`	`51`	`}`
`52`	`52`	return { content: [{ type: 'text', text: `\`\`\`json\n${JSON.stringify(v)}\n\`\`\`` }] };
`53`	`53`	`},`