feat: Return markdown from get-actor-details.ts

Author: jirispilka

README.md

@@ -186,12 +186,21 @@ Build the `actor-mcp-server` package:
 npm run build
 ```
 
-## Debugging
+## Start HTTP streamable MCP server
 
-Since MCP servers operate over standard input/output (stdio), debugging can be challenging.
-For the best debugging experience, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
+Run using Apify CLI:
 
-You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:
+```bash
+export APIFY_TOKEN="your-apify-token"
+export APIFY_META_ORIGIN=STANDBY
+apify run -p
+```
+
+Once the server is running, you can use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to debug the server exposed at `http://localhost:3001`.
+
+## Start standard input/output (stdio) MCP server
+
+You can launch the MCP Inspector with this command:
 
 ```bash
 export APIFY_TOKEN="your-apify-token"

src/const.ts

@@ -78,3 +78,5 @@ export const ALGOLIA = {
 };
 
 export const PROGRESS_NOTIFICATION_INTERVAL_MS = 5_000; // 5 seconds
+
+export const APIFY_STORE_URL = 'https://apify.com';

src/tools/get-actor-details.ts

@@ -1,8 +1,9 @@
+import type { Actor, Build } from 'apify-client';
 import { z } from 'zod';
 import zodToJsonSchema from 'zod-to-json-schema';
 
 import { ApifyClient } from '../apify-client.js';
-import { HelperTools } from '../const.js';
+import { APIFY_STORE_URL, HelperTools } from '../const.js';
 import type { ExtendedPricingInfo, IActorInputSchema, InternalTool, ToolEntry } from '../types.js';
 import { ajv } from '../utils/ajv.js';
 import { getCurrentPricingInfo, pricingInfoToString } from '../utils/pricing-info.js';
@@ -14,47 +15,34 @@ const getActorDetailsToolArgsSchema = z.object({
         .describe(`Actor ID or full name in the format "username/name", e.g., "apify/rag-web-browser".`),
 });
 
-interface IGetActorDetailsToolResult {
-    id: string;
-    actorFullName: string;
-
-    isPublic: boolean;
-    isDeprecated: boolean;
-    createdAt: string;
-    modifiedAt: string;
-
-    categories?: string[];
-    description: string;
-    readme: string;
-
-    inputSchema: IActorInputSchema;
-
-    pricingInfo: string; // We convert the pricing info into a string representation
-
-    usageStatistics: {
-        totalUsers: {
-            allTime: number;
-            last7Days: number;
-            last30Days: number;
-            last90Days: number;
-        };
-        failedRunsInLast30Days: number | string; // string for 'unknown' case
-    }
+// Helper function to format categories from uppercase with underscores to proper case
+function formatCategories(categories?: string[]): string[] {
+    if (!categories) return [];
+
+    return categories.map((category) => {
+        const formatted = category
+            .toLowerCase()
+            .split('_')
+            .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(' ');
+        // Special case for MCP server, AI, and SEO tools
+        return formatted.replace('Mcp Server', 'MCP Server').replace('Ai', 'AI').replace('Seo', 'SEO');
+    });
 }
 
 export const getActorDetailsTool: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.ACTOR_GET_DETAILS,
-        description: `Retrieve information about an Actor by its ID or full name.\n`
-            + 'The Actor name is always composed of "username/name", for example, "apify/rag-web-browser".\n'
-            + 'This tool returns information about the Actor, including whether it is public or deprecated, '
-            + 'when it was created or modified, the categories in which the Actor is listed, a description, '
-            + 'a README (the Actor\'s documentation), the input schema, and usage statistics - such as how many users are using it '
-            + 'and the number of failed runs of the Actor.\n'
-            + 'For example, use this tool when a user wants to know more about a specific Actor or wants to use optional '
-            + 'or advanced parameters of the Actor that are not listed in the default Actor tool input schema - '
-            + 'so you know the details and how to pass them.',
+        description: `Retrieve comprehensive details about an Actor using its ID or full name.\n`
+            + `This tool provides the Actor's title, description, URL, documentation (README), input schema, categories, pricing, and usage statistics.\n`
+            + `Specify the Actor name in the format "username/name" (e.g., "apify/rag-web-browser").\n`
+            + `The response is formatted in markdown and should be rendered as-is.\n`
+            + `USAGE:\n`
+            + `- Use when a user requests information about an Actor, such as its details, description, input schema, or documentation.\n`
+            + `EXAMPLES:\n`
+            + `- user_input: How to use apify/rag-web-browser\n`
+            + `- user_input: What is the input schema for apify/rag-web-browser`,
         inputSchema: zodToJsonSchema(getActorDetailsToolArgsSchema),
         ajvValidate: ajv.compile(zodToJsonSchema(getActorDetailsToolArgsSchema)),
         call: async (toolArgs) => {
@@ -63,7 +51,7 @@ export const getActorDetailsTool: ToolEntry = {
             const parsed = getActorDetailsToolArgsSchema.parse(args);
             const client = new ApifyClient({ token: apifyToken });
 
-            const [actorInfo, buildInfo] = await Promise.all([
+            const [actorInfo, buildInfo]: [Actor | undefined, Build | undefined] = await Promise.all([
                 client.actor(parsed.actor).get(),
                 client.actor(parsed.actor).defaultBuild().then(async (build) => build.get()),
             ]);
@@ -83,40 +71,34 @@ export const getActorDetailsTool: ToolEntry = {
 
             const currentPricingInfo = getCurrentPricingInfo(actorInfo.pricingInfos || [], new Date());
 
-            const result: IGetActorDetailsToolResult = {
-                id: actorInfo.id,
-                actorFullName: `${actorInfo.username}/${actorInfo.name}`,
-
-                isPublic: actorInfo.isPublic,
-                isDeprecated: actorInfo.isDeprecated || false,
-                createdAt: actorInfo.createdAt.toISOString(),
-                modifiedAt: actorInfo.modifiedAt.toISOString(),
-
-                categories: actorInfo.categories,
-                description: actorInfo.description || 'No description provided.',
-                readme: buildInfo.actorDefinition.readme || 'No README provided.',
-
-                inputSchema,
-
-                pricingInfo: pricingInfoToString(currentPricingInfo as (ExtendedPricingInfo | null)),
+            // Format categories for display
+            const formattedCategories = formatCategories(actorInfo.categories);
+
+            // Note: In the public API, we are missing maintainedByApify property, so we cannot use it here.
+            // Note: Actor rating is not in public API, we need to add it (actorUtils.getActorReviewRatingNumber(actorId))
+            const actorFullName = `${actorInfo.username}/${actorInfo.name}`;
+            const markdownLines = [
+                `Actor details (always present Actor information in this format, always include URL):\n`,
+                `# [${actorInfo.title}](${APIFY_STORE_URL}/${actorFullName}) (${actorFullName})`,
+                `**Developed by:** ${actorInfo.username} Maintained by ${actorInfo.username === 'apify' ? '(Apify)' : '(community)'}`,
+                `**Description:** ${actorInfo.description || 'No description provided.'}`,
+                `**Categories:** ${formattedCategories.length ? formattedCategories.join(', ') : 'Uncategorized'}`,
+                `**Pricing:** ${pricingInfoToString(currentPricingInfo as (ExtendedPricingInfo | null))}`,
+                `**Stats:** ${actorInfo.stats.totalUsers.toLocaleString()} total users, ${actorInfo.stats.totalUsers30Days.toLocaleString()} monthly users`,
+                `Last modified: ${actorInfo.modifiedAt.toISOString()}`,
+            ];
+            if (actorInfo.isDeprecated) {
+                markdownLines.push('\n>This Actor is deprecated and may not be maintained anymore.');
+            }
+            const actorCard = markdownLines.join('\n');
 
-                usageStatistics: {
-                    totalUsers: {
-                        allTime: actorInfo.stats.totalUsers,
-                        last7Days: actorInfo.stats.totalUsers7Days,
-                        last30Days: actorInfo.stats.totalUsers30Days,
-                        last90Days: actorInfo.stats.totalUsers90Days,
-                    },
-                    failedRunsInLast30Days: (
-                        'publicActorRunStats30Days' in actorInfo.stats && 'FAILED' in (actorInfo.stats.publicActorRunStats30Days as object)
-                    ) ? (actorInfo.stats.publicActorRunStats30Days as { FAILED: number }).FAILED : 'unknown',
-                },
-            };
             return {
-                content: [{
-                    type: 'text',
-                    text: JSON.stringify(result),
-                }],
+                content: [
+                    { type: 'text', text: actorCard },
+                    // LLM properly format Actor card, if README and input schema are separate text blocks
+                    { type: 'text', text: `**README**:\n\n${buildInfo.actorDefinition.readme || 'No README provided.'}` },
+                    { type: 'text', text: `**Input Schema**:\n\n${JSON.stringify(inputSchema, null, 0)}` },
+                ],
             };
         },
     } as InternalTool,