feat: structured output for the crucial tools (#349)

* feat: add structured output to the crucial tools

* refactor: extract shared output schemas to reduce duplication

Extract duplicate JSON schema definitions from fetch-actor-details and
store-search tools into a centralized src/tools/schemas.ts module. This
eliminates ~170 lines of duplicated code while making schemas easier to
maintain and reuse across tools.

Schemas extracted:
- developerSchema
- pricingSchema
- statsSchema
- actorInfoSchema (reused by both tools)
- actorDetailsOutputSchema
- actorSearchOutputSchema

* fix: remove incorrect 1000x multiplication in pricing values

Remove the multiplication by 1000 in pricingInfoToStructured for PRICE_PER_DATASET_ITEM
model. The pricePerUnit field now correctly represents the actual price per unit,
making the naming consistent and accurate across all pricing models.

Also add JSDoc clarifying that the function transforms API response to match
unstructured text output format for consistency.

* refactor: extract test validation logic to reduce duplication across structured output tests

* fix typo

* fix: links in README.md

* Update src/tools/schemas.ts

Co-authored-by: Jiří Spilka <[email protected]>

* Update src/tools/schemas.ts

Co-authored-by: Jiří Spilka <[email protected]>

* Update src/tools/schemas.ts

Co-authored-by: Jiří Spilka <[email protected]>

* Update src/tools/schemas.ts

Co-authored-by: Jiří Spilka <[email protected]>

* Update src/tools/schemas.ts

Co-authored-by: Jiří Spilka <[email protected]>

* Update src/tools/schemas.ts

Co-authored-by: Jiří Spilka <[email protected]>

* Update src/tools/schemas.ts

Co-authored-by: Jiří Spilka <[email protected]>

* address review comments

* fix build

---------

Co-authored-by: Jiri Spilka <[email protected]>
Co-authored-by: Jiří Spilka <[email protected]>

Author: MQ37

README.md

@@ -31,10 +31,10 @@ The Apify Model Context Protocol (MCP) server at [**mcp.apify.com**](https://mcp
 ## Table of Contents
 - [🌐 Introducing the Apify MCP server](#-introducing-the-apify-mcp-server)
 - [🚀 Quickstart](#-quickstart)
-- [🤖 MCP clients and examples](#-mcp-clients-and-examples)
+- [🤖 MCP clients](#-mcp-clients)
 - [🪄 Try Apify MCP instantly](#-try-apify-mcp-instantly)
 - [🛠️ Tools, resources, and prompts](#-tools-resources-and-prompts)
-- [📊 Telemetry](#telemetry)
+- [📊 Telemetry](#-telemetry)
 - [🐛 Troubleshooting (local MCP server)](#-troubleshooting-local-mcp-server)
 - [⚙️ Development](#-development)
 - [🤝 Contributing](#-contributing)

src/tools/actor.ts

@@ -373,6 +373,7 @@ Step 2: Call Actor (step="call")
 EXAMPLES:
 - user_input: Get instagram posts using apify/instagram-scraper`,
     inputSchema: zodToJsonSchema(callActorArgs) as ToolInputSchema,
+    // For now we are not adding the strucuted output schema since this tool is quite complex and has multiple possible ends states
     ajvValidate: ajv.compile({
         ...zodToJsonSchema(callActorArgs),
         // Additional props true to allow skyfire-pay-id
@@ -445,13 +446,11 @@ EXAMPLES:
                     // Regular Actor: return schema
                     const details = await fetchActorDetails(apifyClientForDefinition, baseActorName);
                     if (!details) {
-                        return buildMCPResponse({
-                            texts: [`Actor information for '${baseActorName}' was not found.
+                        return buildMCPResponse({ texts: [`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}.`],
-                            isError: true,
-                            toolStatus: TOOL_STATUS.SOFT_FAIL,
-                        });
+                        isError: true,
+                        toolStatus: TOOL_STATUS.SOFT_FAIL });
                     }
                     const content = [
                         `Actor name: ${actorName}`,
@@ -541,13 +540,11 @@ You can search for available Actors using the tool: ${HelperTools.STORE_SEARCH}.
             const [actor] = await getActorsAsTools([actorName], apifyClient);
 
             if (!actor) {
-                return buildMCPResponse({
-                    texts: [`Actor '${actorName}' was not found.
+                return buildMCPResponse({ texts: [`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}.`],
-                    isError: true,
-                    toolStatus: TOOL_STATUS.SOFT_FAIL,
-                });
+                isError: true,
+                toolStatus: TOOL_STATUS.SOFT_FAIL });
             }
 
             if (!actor.ajvValidate(input)) {
@@ -583,12 +580,10 @@ You can search for available Actors using the tool: ${HelperTools.STORE_SEARCH}.
         } catch (error) {
             logHttpError(error, 'Failed to call Actor', { actorName, performStep });
             // Let the server classify the error; we only mark it as an MCP error response
-            return buildMCPResponse({
-                texts: [`Failed to call Actor '${actorName}': ${error instanceof Error ? error.message : String(error)}.
+            return buildMCPResponse({ texts: [`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}.`],
-                isError: true,
-            });
+            isError: true });
         }
     },
 };

src/tools/fetch-actor-details.ts

@@ -7,6 +7,7 @@ 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';
+import { actorDetailsOutputSchema } from './structured-output-schemas.js';
 
 const fetchActorDetailsToolArgsSchema = z.object({
     actor: z.string()
@@ -29,6 +30,7 @@ USAGE EXAMPLES:
 - user_input: What is the input schema for apify/rag-web-browser?
 - user_input: What is the pricing for apify/instagram-scraper?`,
     inputSchema: zodToJsonSchema(fetchActorDetailsToolArgsSchema) as ToolInputSchema,
+    outputSchema: actorDetailsOutputSchema,
     ajvValidate: ajv.compile(zodToJsonSchema(fetchActorDetailsToolArgsSchema)),
     annotations: {
         title: 'Fetch Actor details',
@@ -65,6 +67,11 @@ You can search for available Actors using the tool: ${HelperTools.STORE_SEARCH}.
         }
         // 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 buildMCPResponse({ texts });
+        const structuredContent = {
+            actorInfo: details.actorCardStructured,
+            readme: details.readme,
+            inputSchema: details.inputSchema,
+        };
+        return buildMCPResponse({ texts, structuredContent });
     },
 } as const;

src/tools/fetch-apify-docs.ts

@@ -8,6 +8,7 @@ import { ajv } from '../utils/ajv.js';
 import { htmlToMarkdown } from '../utils/html-to-md.js';
 import { logHttpError } from '../utils/logging.js';
 import { buildMCPResponse } from '../utils/mcp.js';
+import { fetchApifyDocsToolOutputSchema } from './structured-output-schemas.js';
 
 const fetchApifyDocsToolArgsSchema = z.object({
     url: z.string()
@@ -28,6 +29,7 @@ USAGE EXAMPLES:
 - user_input: Fetch https://docs.apify.com/platform/actors/running#builds
 - user_input: Fetch https://docs.apify.com/academy`,
     inputSchema: zodToJsonSchema(fetchApifyDocsToolArgsSchema) as ToolInputSchema,
+    outputSchema: fetchApifyDocsToolOutputSchema,
     ajvValidate: ajv.compile(zodToJsonSchema(fetchApifyDocsToolArgsSchema)),
     annotations: {
         title: 'Fetch Apify docs',
@@ -43,13 +45,11 @@ USAGE EXAMPLES:
 
         // Only allow URLs starting with https://docs.apify.com
         if (!url.startsWith('https://docs.apify.com')) {
-            return buildMCPResponse({
-                texts: [`Invalid URL: "${url}".
+            return buildMCPResponse({ texts: [`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.`],
-                isError: true,
-                toolStatus: TOOL_STATUS.SOFT_FAIL,
-            });
+            isError: true,
+            toolStatus: TOOL_STATUS.SOFT_FAIL });
         }
 
         // Cache URL without fragment to avoid fetching the same page multiple times
@@ -91,6 +91,6 @@ Please verify the URL is correct and accessible. You can search for available do
             }
         }
 
-        return buildMCPResponse({ texts: [`Fetched content from ${url}:\n\n${markdown}`] });
+        return buildMCPResponse({ texts: [`Fetched content from ${url}:\n\n${markdown}`], structuredContent: { url, content: markdown } });
     },
 } as const;

src/tools/run.ts

@@ -48,11 +48,9 @@ USAGE EXAMPLES:
         const client = new ApifyClient({ token: apifyToken });
         const v = await client.run(parsed.runId).get();
         if (!v) {
-            return buildMCPResponse({
-                texts: [`Run with ID '${parsed.runId}' not found.`],
+            return buildMCPResponse({ texts: [`Run with ID '${parsed.runId}' not found.`],
                 isError: true,
-                toolStatus: TOOL_STATUS.SOFT_FAIL,
-            });
+                toolStatus: TOOL_STATUS.SOFT_FAIL });
         }
         const texts = [`\`\`\`json\n${JSON.stringify(v, null, 2)}\n\`\`\``];
         return buildMCPResponse({ texts });
@@ -84,6 +82,7 @@ USAGE EXAMPLES:
 - user_input: Show last 20 lines of logs for run y2h7sK3Wc
 - user_input: Get logs for run y2h7sK3Wc`,
     inputSchema: zodToJsonSchema(GetRunLogArgs) as ToolInputSchema,
+    // It does not make sense to add structured output here since the log API just returns plain text
     ajvValidate: ajv.compile(zodToJsonSchema(GetRunLogArgs)),
     annotations: {
         title: 'Get Actor run log',

src/tools/run_collection.ts

@@ -5,6 +5,7 @@ import { ApifyClient } from '../apify-client.js';
 import { HelperTools } from '../const.js';
 import type { InternalToolArgs, ToolEntry, ToolInputSchema } from '../types.js';
 import { ajv } from '../utils/ajv.js';
+import { buildMCPResponse } from '../utils/mcp.js';
 
 const getUserRunsListArgs = z.object({
     offset: z.number()
@@ -50,6 +51,8 @@ USAGE EXAMPLES:
         const parsed = getUserRunsListArgs.parse(args);
         const client = new ApifyClient({ token: apifyToken });
         const runs = await client.runs().list({ limit: parsed.limit, offset: parsed.offset, desc: parsed.desc, status: parsed.status });
-        return { content: [{ type: 'text', text: `\`\`\`json\n${JSON.stringify(runs)}\n\`\`\`` }] };
+        return buildMCPResponse({
+            texts: [`\`\`\`json\n${JSON.stringify(runs)}\n\`\`\``],
+        });
     },
 } as const;

src/tools/search-apify-docs.ts

@@ -6,6 +6,7 @@ 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';
+import { searchApifyDocsToolOutputSchema } from './structured-output-schemas.js';
 
 const searchApifyDocsToolArgsSchema = z.object({
     query: z.string()
@@ -50,6 +51,7 @@ USAGE EXAMPLES:
 - query: How to define Actor input schema?
 - query: How scrape with Crawlee?`,
     inputSchema: zodToJsonSchema(searchApifyDocsToolArgsSchema) as ToolInputSchema,
+    outputSchema: searchApifyDocsToolOutputSchema,
     ajvValidate: ajv.compile(zodToJsonSchema(searchApifyDocsToolArgsSchema)),
     annotations: {
         title: 'Search Apify docs',
@@ -66,18 +68,23 @@ USAGE EXAMPLES:
         const results = resultsRaw.slice(parsed.offset, parsed.offset + parsed.limit);
 
         if (results.length === 0) {
-            return buildMCPResponse({
-                texts: [`No results found for the query "${query}" with limit ${parsed.limit} and offset ${parsed.offset}.
+            return buildMCPResponse({ texts: [`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.`],
-            });
+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 buildMCPResponse({ texts: [textContent] });
+   Content: ${result.content}`).join('\n\n')}`;
+        const structuredContent = {
+            results: results.map((result) => ({
+                url: result.url,
+                fragment: result.fragment,
+                content: result.content,
+            })),
+        };
+        return buildMCPResponse({ texts: [textContent], structuredContent });
     },
 } as const;

src/tools/store_collection.ts

@@ -5,9 +5,10 @@ import zodToJsonSchema from 'zod-to-json-schema';
 import { ApifyClient } from '../apify-client.js';
 import { ACTOR_SEARCH_ABOVE_LIMIT, HelperTools } from '../const.js';
 import type { ActorPricingModel, ExtendedActorStoreList, InternalToolArgs, ToolEntry, ToolInputSchema } from '../types.js';
-import { formatActorToActorCard } from '../utils/actor-card.js';
+import { formatActorToActorCard, formatActorToStructuredCard } from '../utils/actor-card.js';
 import { ajv } from '../utils/ajv.js';
 import { buildMCPResponse } from '../utils/mcp.js';
+import { actorSearchOutputSchema } from './structured-output-schemas.js';
 
 export async function searchActorsByKeywords(
     search: string,
@@ -124,6 +125,7 @@ Returns list of Actor cards with the following info:
 - **Rating:** Out of 5 (if available)
 `,
     inputSchema: zodToJsonSchema(searchActorsArgsSchema) as ToolInputSchema,
+    outputSchema: actorSearchOutputSchema,
     ajvValidate: ajv.compile(zodToJsonSchema(searchActorsArgsSchema)),
     annotations: {
         title: 'Search Actors',
@@ -144,25 +146,34 @@ Returns list of Actor cards with the following info:
         const actorCards = actors.length === 0 ? [] : actors.map(formatActorToActorCard);
 
         if (actorCards.length === 0) {
-            return buildMCPResponse({
-                texts: [`No Actors were found for the search query "${parsed.keywords}".
-Please try different keywords or simplify your query. Consider using more specific platform names (e.g., "Instagram", "Twitter") and data types (e.g., "posts", "products") rather than generic terms like "scraper" or "crawler".`],
-            });
+            return buildMCPResponse({ texts: [`No Actors were found for the search query "${parsed.keywords}".
+ Please try different keywords or simplify your query. Consider using more specific platform names (e.g., "Instagram", "Twitter") and data types (e.g., "posts", "products") rather than generic terms like "scraper" or "crawler".`] });
         }
 
         const actorsText = actorCards.join('\n\n');
 
-        return buildMCPResponse({ texts: [`
-# Search results:
-- **Search query:** ${parsed.keywords}
-- **Number of Actors found:** ${actorCards.length}
+        // Generate structured cards for the actors
+        const structuredActorCards = actors.map(formatActorToStructuredCard);
 
-# Actors:
+        const texts = [`
+ # Search results:
+ - **Search query:** ${parsed.keywords}
+ - **Number of Actors found:** ${actorCards.length}
 
-${actorsText}
+ # Actors:
 
-If you need more detailed information about any of these Actors, including their input schemas and usage instructions, please use the ${HelperTools.ACTOR_GET_DETAILS} tool with the specific Actor name.
-If the search did not return relevant results, consider refining your keywords, use broader terms or removing less important words from the keywords.
-`] });
+ ${actorsText}
+
+ If you need more detailed information about any of these Actors, including their input schemas and usage instructions, please use the ${HelperTools.ACTOR_GET_DETAILS} tool with the specific Actor name.
+ If the search did not return relevant results, consider refining your keywords, use broader terms or removing less important words from the keywords.
+ `];
+
+        const structuredContent = {
+            actors: structuredActorCards,
+            query: parsed.keywords,
+            count: actorCards.length,
+        };
+
+        return buildMCPResponse({ texts, structuredContent });
     },
 } as const;