feat: use markdown every time for all json data

MichalKalita · MichalKalita · commit 4dbd41da206a · 2025-09-22T20:15:36.000+02:00
diff --git a/src/tools/actor.ts b/src/tools/actor.ts
@@ -22,6 +22,7 @@ import { ensureOutputWithinCharLimit, getActorDefinitionStorageFieldNames, getAc
 import { fetchActorDetails } from '../utils/actor-details.js';
 import { buildActorResponseContent } from '../utils/actor-response.js';
 import { ajv } from '../utils/ajv.js';
+import { jsonSchemaToMarkdown } from '../utils/json-schema-to-markdown.js';
 import { buildMCPResponse } from '../utils/mcp.js';
 import type { ProgressTracker } from '../utils/progress.js';
 import type { JsonSchemaProperty } from '../utils/schema-generation.js';
@@ -388,7 +389,7 @@ The step parameter enforces this workflow - you cannot call an Actor without fir
                             client = await connectMCPClient(mcpServerUrl, apifyToken);
                             const toolsResponse = await client.listTools();
 
-                            const toolsInfo = toolsResponse.tools.map((tool) => `**${tool.name}**\n${tool.description || 'No description'}\nInput Schema: ${JSON.stringify(tool.inputSchema, null, 2)}`,
+                            const toolsInfo = toolsResponse.tools.map((tool) => `**${tool.name}**\n${tool.description || 'No description'}\n\n${jsonSchemaToMarkdown(tool.inputSchema)}`,
                             ).join('\n\n');
 
                             return buildMCPResponse([`This is an MCP Server Actor with the following tools:\n\n${toolsInfo}\n\nTo call a tool, use step="call" with actor name format: "${baseActorName}:{toolName}"`]);
@@ -402,7 +403,7 @@ The step parameter enforces this workflow - you cannot call an Actor without fir
                             return buildMCPResponse([`Actor information for '${baseActorName}' was not found. Please check the Actor ID or name and ensure the Actor exists.`]);
                         }
                         const content = [
-                            { type: 'text', text: `**Input Schema:**\n${JSON.stringify(details.inputSchema, null, 0)}` },
+                            { type: 'text', text: jsonSchemaToMarkdown(details.inputSchema) },
                         ];
                         /**
                          * Add Skyfire instructions also in the info step since clients are most likely truncating the long tool description of the call-actor.
@@ -478,7 +479,7 @@ The step parameter enforces this workflow - you cannot call an Actor without fir
                     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)}`,
+                            jsonSchemaToMarkdown(actor.tool.inputSchema),
                         ]);
                     }
                 }
diff --git a/src/tools/build.ts b/src/tools/build.ts
@@ -13,6 +13,7 @@ import type {
     ToolEntry,
 } from '../types.js';
 import { ajv } from '../utils/ajv.js';
+import { jsonSchemaToMarkdown } from '../utils/json-schema-to-markdown.js';
 import { filterSchemaProperties, shortenProperties } from './utils.js';
 
 /**
@@ -131,7 +132,7 @@ export const actorDefinitionTool: ToolEntry = {
                 const properties = filterSchemaProperties(v.input.properties as { [key: string]: ISchemaProperties });
                 v.input.properties = shortenProperties(properties);
             }
-            return { content: [{ type: 'text', text: JSON.stringify(v) }] };
+            return { content: [{ type: 'text', text: jsonSchemaToMarkdown(v.input) }] };
         },
     } as InternalTool,
 };
diff --git a/src/tools/dataset.ts b/src/tools/dataset.ts
@@ -6,6 +6,8 @@ import { HelperTools } from '../const.js';
 import type { InternalTool, ToolEntry } from '../types.js';
 import { ajv } from '../utils/ajv.js';
 import { parseCommaSeparatedList } from '../utils/generic.js';
+import { jsonSchemaToMarkdown } from '../utils/json-schema-to-markdown.js';
+import { jsonToMarkdown } from '../utils/json-to-markdown.js';
 import { generateSchemaFromItems } from '../utils/schema-generation.js';
 
 const getDatasetArgs = z.object({
@@ -61,7 +63,7 @@ export const getDataset: ToolEntry = {
             if (!v) {
                 return { content: [{ type: 'text', text: `Dataset '${parsed.datasetId}' not found.` }] };
             }
-            return { content: [{ type: 'text', text: JSON.stringify(v) }] };
+            return { content: [{ type: 'text', text: jsonToMarkdown(v) }] };
         },
     } as InternalTool,
 };
@@ -108,7 +110,7 @@ export const getDatasetItems: ToolEntry = {
             if (!v) {
                 return { content: [{ type: 'text', text: `Dataset '${parsed.datasetId}' not found.` }] };
             }
-            return { content: [{ type: 'text', text: JSON.stringify(v) }] };
+            return { content: [{ type: 'text', text: jsonToMarkdown(v) }] };
         },
     } as InternalTool,
 };
@@ -176,7 +178,7 @@ export const getDatasetSchema: ToolEntry = {
             return {
                 content: [{
                     type: 'text',
-                    text: JSON.stringify(schema),
+                    text: jsonSchemaToMarkdown(schema),
                 }],
             };
         },
diff --git a/src/tools/dataset_collection.ts b/src/tools/dataset_collection.ts
@@ -5,6 +5,7 @@ import { ApifyClient } from '../apify-client.js';
 import { HelperTools } from '../const.js';
 import type { InternalTool, ToolEntry } from '../types.js';
 import { ajv } from '../utils/ajv.js';
+import { jsonToMarkdown } from '../utils/json-to-markdown.js';
 
 const getUserDatasetsListArgs = z.object({
     offset: z.number()
@@ -48,7 +49,7 @@ export const getUserDatasetsList: ToolEntry = {
                 desc: parsed.desc,
                 unnamed: parsed.unnamed,
             });
-            return { content: [{ type: 'text', text: JSON.stringify(datasets) }] };
+            return { content: [{ type: 'text', text: jsonToMarkdown(datasets) }] };
         },
     } as InternalTool,
 };
diff --git a/src/tools/fetch-actor-details.ts b/src/tools/fetch-actor-details.ts
@@ -6,7 +6,7 @@ import { HelperTools } from '../const.js';
 import type { InternalTool, ToolEntry } from '../types.js';
 import { fetchActorDetails } from '../utils/actor-details.js';
 import { ajv } from '../utils/ajv.js';
-import { inputSchemaToMarkdown } from '../utils/input-schema-to-markdown.js';
+import { jsonSchemaToMarkdown } from '../utils/json-schema-to-markdown.js';
 
 const fetchActorDetailsToolArgsSchema = z.object({
     actor: z.string()
@@ -43,7 +43,7 @@ export const fetchActorDetailsTool: ToolEntry = {
                 content: [
                     { type: 'text', text: `**Actor card**:\n${details.actorCard}` },
                     { type: 'text', text: `**README:**\n${details.readme}` },
-                    { type: 'text', text: inputSchemaToMarkdown(details.inputSchema) },
+                    { type: 'text', text: jsonSchemaToMarkdown(details.inputSchema) },
                 ],
             };
         },
diff --git a/src/tools/get-actor-output.ts b/src/tools/get-actor-output.ts
@@ -6,6 +6,7 @@ import { HelperTools, SKYFIRE_TOOL_INSTRUCTIONS, TOOL_MAX_OUTPUT_CHARS } from '.
 import type { InternalTool, ToolEntry } from '../types.js';
 import { ajv } from '../utils/ajv.js';
 import { getValuesByDotKeys, parseCommaSeparatedList } from '../utils/generic.js';
+import { jsonToMarkdown } from '../utils/json-to-markdown.js';
 
 /**
  * Zod schema for get-actor-output tool arguments
@@ -134,7 +135,7 @@ Note: This tool is automatically included if the Apify MCP Server is configured
                 .map((item) => cleanEmptyProperties(item))
                 .filter((item) => item !== undefined);
 
-            let outputText = JSON.stringify(cleanedItems);
+            let outputText = jsonToMarkdown(cleanedItems);
             let truncated = false;
             if (outputText.length > TOOL_MAX_OUTPUT_CHARS) {
                 outputText = outputText.slice(0, TOOL_MAX_OUTPUT_CHARS);
diff --git a/src/tools/key_value_store.ts b/src/tools/key_value_store.ts
@@ -5,6 +5,7 @@ import { ApifyClient } from '../apify-client.js';
 import { HelperTools } from '../const.js';
 import type { InternalTool, ToolEntry } from '../types.js';
 import { ajv } from '../utils/ajv.js';
+import { jsonToMarkdown } from '../utils/json-to-markdown.js';
 
 const getKeyValueStoreArgs = z.object({
     storeId: z.string()
@@ -30,7 +31,7 @@ export const getKeyValueStore: ToolEntry = {
             const parsed = getKeyValueStoreArgs.parse(args);
             const client = new ApifyClient({ token: apifyToken });
             const store = await client.keyValueStore(parsed.storeId).get();
-            return { content: [{ type: 'text', text: JSON.stringify(store) }] };
+            return { content: [{ type: 'text', text: jsonToMarkdown(store) }] };
         },
     } as InternalTool,
 };
@@ -70,7 +71,7 @@ export const getKeyValueStoreKeys: ToolEntry = {
                 exclusiveStartKey: parsed.exclusiveStartKey,
                 limit: parsed.limit,
             });
-            return { content: [{ type: 'text', text: JSON.stringify(keys) }] };
+            return { content: [{ type: 'text', text: jsonToMarkdown(keys) }] };
         },
     } as InternalTool,
 };
@@ -104,7 +105,7 @@ export const getKeyValueStoreRecord: ToolEntry = {
             const parsed = getKeyValueStoreRecordArgs.parse(args);
             const client = new ApifyClient({ token: apifyToken });
             const record = await client.keyValueStore(parsed.storeId).getRecord(parsed.recordKey);
-            return { content: [{ type: 'text', text: JSON.stringify(record) }] };
+            return { content: [{ type: 'text', text: jsonToMarkdown(record) }] };
         },
     } as InternalTool,
 };
diff --git a/src/tools/key_value_store_collection.ts b/src/tools/key_value_store_collection.ts
@@ -5,6 +5,7 @@ import { ApifyClient } from '../apify-client.js';
 import { HelperTools } from '../const.js';
 import type { InternalTool, ToolEntry } from '../types.js';
 import { ajv } from '../utils/ajv.js';
+import { jsonToMarkdown } from '../utils/json-to-markdown.js';
 
 const getUserKeyValueStoresListArgs = z.object({
     offset: z.number()
@@ -48,7 +49,7 @@ export const getUserKeyValueStoresList: ToolEntry = {
                 desc: parsed.desc,
                 unnamed: parsed.unnamed,
             });
-            return { content: [{ type: 'text', text: JSON.stringify(stores) }] };
+            return { content: [{ type: 'text', text: jsonToMarkdown(stores) }] };
         },
     } as InternalTool,
 };
diff --git a/src/tools/run.ts b/src/tools/run.ts
@@ -5,6 +5,7 @@ import { ApifyClient } from '../apify-client.js';
 import { HelperTools } from '../const.js';
 import type { InternalTool, ToolEntry } from '../types.js';
 import { ajv } from '../utils/ajv.js';
+import { jsonToMarkdown } from '../utils/json-to-markdown.js';
 
 const getActorRunArgs = z.object({
     runId: z.string()
@@ -40,7 +41,7 @@ export const getActorRun: ToolEntry = {
             if (!v) {
                 return { content: [{ type: 'text', text: `Run with ID '${parsed.runId}' not found.` }] };
             }
-            return { content: [{ type: 'text', text: JSON.stringify(v) }] };
+            return { content: [{ type: 'text', text: jsonToMarkdown(v) }] };
         },
     } as InternalTool,
 };
@@ -96,7 +97,7 @@ export const abortActorRun: ToolEntry = {
             const parsed = abortRunArgs.parse(args);
             const client = new ApifyClient({ token: apifyToken });
             const v = await client.run(parsed.runId).abort({ gracefully: parsed.gracefully });
-            return { content: [{ type: 'text', text: JSON.stringify(v) }] };
+            return { content: [{ type: 'text', text: jsonToMarkdown(v) }] };
         },
     } as InternalTool,
 };
diff --git a/src/tools/run_collection.ts b/src/tools/run_collection.ts
@@ -5,6 +5,7 @@ import { ApifyClient } from '../apify-client.js';
 import { HelperTools } from '../const.js';
 import type { InternalTool, ToolEntry } from '../types.js';
 import { ajv } from '../utils/ajv.js';
+import { jsonToMarkdown } from '../utils/json-to-markdown.js';
 
 const getUserRunsListArgs = z.object({
     offset: z.number()
@@ -40,7 +41,7 @@ export const getUserRunsList: ToolEntry = {
             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.stringify(runs) }] };
+            return { content: [{ type: 'text', text: jsonToMarkdown(runs) }] };
         },
     } as InternalTool,
 };
diff --git a/src/utils/actor-response.ts b/src/utils/actor-response.ts
@@ -1,4 +1,5 @@
 import type { CallActorGetDatasetResult } from '../tools/actor.js';
+import { jsonSchemaToMarkdown } from './json-schema-to-markdown.js';
 
 /**
  * Builds the response content for Actor tool calls.
@@ -37,9 +38,8 @@ Results summary:
 
 Actor output data schema:
 * You can use this schema to understand the structure of the output data and, for example, retrieve specific fields based on your current task.
-\`\`\`json
-${JSON.stringify(displaySchema, null, 2)}
-\`\`\`
+
+${jsonSchemaToMarkdown(displaySchema)}
 
 Above this text block is a preview of the Actor output containing ${result.previewItems.length} item(s).${itemCount !== result.previewItems.length ? ` You have access only to a limited preview of the Actor output. Do not present this as the full output, as you have only ${result.previewItems.length} item(s) available instead of the full ${itemCount} item(s). Be aware of this and inform users about the currently loaded count and the total available output items count.` : ''}
 
diff --git a/src/utils/json-schema-to-markdown.ts b/src/utils/json-schema-to-markdown.ts
@@ -52,7 +52,7 @@ function formatProperty(key: string, value: any, requiredFields: Set<string>, le
     return result;
 }
 
-export function inputSchemaToMarkdown(inputSchema: IActorInputSchema) {
+export function jsonSchemaToMarkdown(inputSchema: IActorInputSchema) {
     const requiredFields = new Set(inputSchema.required || []);
 
     let markdown = '# JSON Schema';
diff --git a/tests/unit/json-schema-to-markdown.test.ts b/tests/unit/json-schema-to-markdown.test.ts
@@ -1,9 +1,9 @@
 /* eslint-disable max-len */
 import { describe, expect, it } from 'vitest';
 
-import { inputSchemaToMarkdown } from '../../src/utils/input-schema-to-markdown.js';
+import { jsonSchemaToMarkdown } from '../../src/utils/json-schema-to-markdown.js';
 
-describe('inputSchemaToMarkdown', () => {
+describe('jsonSchemaToMarkdown', () => {
     it('should format schema for Actor apify/facebook-posts-scraper', () => {
         const schema = { title: 'Input schema for the empty project actor.',
             description: "This scraper will get post and page details from Facebook pages of your choice. To try it out, just paste a Facebook Page URL and click ▷ Start. If you need any guidance, just <a href='https://blog.apify.com/scrape-facebook-posts-data/' target='_blank' rel='noopener'>follow this tutorial</a>.",
@@ -41,7 +41,7 @@ describe('inputSchemaToMarkdown', () => {
             },
             required: ['startUrls'] };
 
-        const result = inputSchemaToMarkdown(schema);
+        const result = jsonSchemaToMarkdown(schema);
         expect(result).toMatchInlineSnapshot(`
           "# JSON Schema
 
@@ -174,7 +174,7 @@ describe('inputSchemaToMarkdown', () => {
             },
         };
 
-        const result = inputSchemaToMarkdown(schema);
+        const result = jsonSchemaToMarkdown(schema);
         expect(result).toMatchInlineSnapshot(`
           "# JSON Schema
 
@@ -276,7 +276,7 @@ describe('inputSchemaToMarkdown', () => {
             },
         };
 
-        const result = inputSchemaToMarkdown(schema);
+        const result = jsonSchemaToMarkdown(schema);
         expect(result).toMatchInlineSnapshot(`
           "# JSON Schema
 
