fix: update actor definition handling to include full metadata and improve MCP server identification (#372)

MQ37 · jirispilka · web-flow · commit 37ab8cb7fae2 · 2025-12-22T12:07:56.000+01:00
* fix: update actor definition handling to include full metadata and improve MCP server identification

* Update src/tools/actor.ts

Co-authored-by: Jiří Spilka &lt;jiri.spilka@apify.com&gt;

* Update src/tools/build.ts

Co-authored-by: Jiří Spilka &lt;jiri.spilka@apify.com&gt;

* Update src/utils/actor.ts

Co-authored-by: Jiří Spilka &lt;jiri.spilka@apify.com&gt;

* fix: improve comment clarity for null filtering in getActorsAsTools function

---------

Co-authored-by: Jiří Spilka &lt;jiri.spilka@apify.com&gt;
diff --git a/src/state.ts b/src/state.ts
@@ -8,10 +8,10 @@ import {
     MCP_SERVER_CACHE_MAX_SIZE,
     MCP_SERVER_CACHE_TTL_SECS,
 } from './const.js';
-import type { ActorDefinitionPruned, ApifyDocsSearchResult } from './types.js';
+import type { ActorDefinitionWithInfo, ApifyDocsSearchResult } from './types.js';
 import { TTLLRUCache } from './utils/ttl-lru.js';
 
-export const actorDefinitionPrunedCache = new TTLLRUCache<ActorDefinitionPruned>(ACTOR_CACHE_MAX_SIZE, ACTOR_CACHE_TTL_SECS);
+export const actorDefinitionPrunedCache = new TTLLRUCache<ActorDefinitionWithInfo>(ACTOR_CACHE_MAX_SIZE, ACTOR_CACHE_TTL_SECS);
 export const searchApifyDocsCache = new TTLLRUCache<ApifyDocsSearchResult[]>(APIFY_DOCS_CACHE_MAX_SIZE, APIFY_DOCS_CACHE_TTL_SECS);
 /** Stores processed Markdown content */
 export const fetchApifyDocsCache = new TTLLRUCache<string>(APIFY_DOCS_CACHE_MAX_SIZE, APIFY_DOCS_CACHE_TTL_SECS);
diff --git a/src/tools/actor.ts b/src/tools/actor.ts
@@ -28,7 +28,7 @@ import type { ProgressTracker } from '../utils/progress.js';
 import type { JsonSchemaProperty } from '../utils/schema-generation.js';
 import { generateSchemaFromItems } from '../utils/schema-generation.js';
 import { getActorDefinition } from './build.js';
-import { actorNameToToolName, buildActorInputSchema, fixedAjvCompile } from './utils.js';
+import { actorNameToToolName, buildActorInputSchema, fixedAjvCompile, isActorInfoMcpServer } from './utils.js';
 
 // Define a named return type for callActorGetDataset
 export type CallActorGetDatasetResult = {
@@ -150,7 +150,7 @@ export async function callActorGetDataset(
  * 4. Properties are shortened using shortenProperties()
  * 5. Enums are added to descriptions with examples using addEnumsToDescriptionsWithExamples()
  *
- * @param {ActorInfo[]} actorsInfo - An array of ActorInfo objects with webServerMcpPath and actorDefinitionPruned.
+ * @param {ActorInfo[]} actorsInfo - An array of ActorInfo objects with webServerMcpPath, definition, and Actor.
  * @returns {Promise<ToolEntry[]>} - A promise that resolves to an array of MCP tools.
  */
 export async function getNormalActorsAsTools(
@@ -159,22 +159,22 @@ export async function getNormalActorsAsTools(
     const tools: ToolEntry[] = [];
 
     for (const actorInfo of actorsInfo) {
-        const { actorDefinitionPruned } = actorInfo;
+        const { definition } = actorInfo;
 
-        if (!actorDefinitionPruned) continue;
+        if (!definition) continue;
 
-        const isRag = actorDefinitionPruned.actorFullName === RAG_WEB_BROWSER;
-        const { inputSchema } = buildActorInputSchema(actorDefinitionPruned.actorFullName, actorDefinitionPruned.input, isRag);
+        const isRag = definition.actorFullName === RAG_WEB_BROWSER;
+        const { inputSchema } = buildActorInputSchema(definition.actorFullName, definition.input, isRag);
 
-        let description = `This tool calls the Actor "${actorDefinitionPruned.actorFullName}" and retrieves its output results.
+        let description = `This tool calls the Actor "${definition.actorFullName}" and retrieves its output results.
 Use this tool instead of the "${HelperTools.ACTOR_CALL}" if user requests this specific Actor.
-Actor description: ${actorDefinitionPruned.description}`;
+Actor description: ${definition.description}`;
         if (isRag) {
             description += RAG_WEB_BROWSER_ADDITIONAL_DESC;
         }
 
         const memoryMbytes = Math.min(
-            actorDefinitionPruned.defaultRunOptions?.memoryMbytes || ACTOR_MAX_MEMORY_MBYTES,
+            definition.defaultRunOptions?.memoryMbytes || ACTOR_MAX_MEMORY_MBYTES,
             ACTOR_MAX_MEMORY_MBYTES,
         );
 
@@ -183,25 +183,25 @@ Actor description: ${actorDefinitionPruned.description}`;
             ajvValidate = fixedAjvCompile(ajv, { ...inputSchema, additionalProperties: true });
         } catch (e) {
             log.error('Failed to compile schema', {
-                actorName: actorDefinitionPruned.actorFullName,
+                actorName: definition.actorFullName,
                 error: e,
             });
             continue;
         }
 
         tools.push({
             type: 'actor',
-            name: actorNameToToolName(actorDefinitionPruned.actorFullName),
-            actorFullName: actorDefinitionPruned.actorFullName,
+            name: actorNameToToolName(definition.actorFullName),
+            actorFullName: definition.actorFullName,
             description,
             inputSchema: inputSchema as ToolInputSchema,
             ajvValidate,
             memoryMbytes,
-            icons: actorDefinitionPruned.pictureUrl
-                ? [{ src: actorDefinitionPruned.pictureUrl, mimeType: 'image/png' }]
+            icons: definition.pictureUrl
+                ? [{ src: definition.pictureUrl, mimeType: 'image/png' }]
                 : undefined,
             annotations: {
-                title: actorDefinitionPruned.actorFullName,
+                title: definition.actorFullName,
                 openWorldHint: true,
             },
             // Allow long running tasks for Actor tools, make it optional for now
@@ -227,21 +227,21 @@ async function getMCPServersAsTools(
 
     // Process all actors in parallel
     const actorToolPromises = actorsInfo.map(async (actorInfo) => {
-        const actorId = actorInfo.actorDefinitionPruned.id;
+        const actorId = actorInfo.definition.id;
         if (!actorInfo.webServerMcpPath) {
             log.warning('Actor does not have a web server MCP path, skipping', {
-                actorFullName: actorInfo.actorDefinitionPruned.actorFullName,
+                actorFullName: actorInfo.definition.actorFullName,
                 actorId,
             });
             return [];
         }
 
         const mcpServerUrl = await getActorMCPServerURL(
-            actorInfo.actorDefinitionPruned.id, // Real ID of the Actor
+            actorInfo.definition.id, // Real ID of the Actor
             actorInfo.webServerMcpPath,
         );
         log.debug('Retrieved MCP server URL for Actor', {
-            actorFullName: actorInfo.actorDefinitionPruned.actorFullName,
+            actorFullName: actorInfo.definition.actorFullName,
             actorId,
             mcpServerUrl,
         });
@@ -256,7 +256,7 @@ async function getMCPServersAsTools(
             return await getMCPServerTools(actorId, client, mcpServerUrl);
         } catch (error) {
             logHttpError(error, 'Failed to connect to MCP server', {
-                actorFullName: actorInfo.actorDefinitionPruned.actorFullName,
+                actorFullName: actorInfo.definition.actorFullName,
                 actorId,
             });
             return [];
@@ -280,26 +280,28 @@ export async function getActorsAsTools(
 
     const actorsInfo: (ActorInfo | null)[] = await Promise.all(
         actorIdsOrNames.map(async (actorIdOrName) => {
-            const actorDefinitionPrunedCached = actorDefinitionPrunedCache.get(actorIdOrName);
-            if (actorDefinitionPrunedCached) {
+            const actorDefinitionWithInfoCached = actorDefinitionPrunedCache.get(actorIdOrName);
+            if (actorDefinitionWithInfoCached) {
                 return {
-                    actorDefinitionPruned: actorDefinitionPrunedCached,
-                    webServerMcpPath: getActorMCPServerPath(actorDefinitionPrunedCached),
+                    definition: actorDefinitionWithInfoCached.definition,
+                    actor: actorDefinitionWithInfoCached.info,
+                    webServerMcpPath: getActorMCPServerPath(actorDefinitionWithInfoCached.definition),
 
                 } as ActorInfo;
             }
 
             try {
-                const actorDefinitionPruned = await getActorDefinition(actorIdOrName, apifyClient);
-                if (!actorDefinitionPruned) {
+                const actorDefinitionWithInfo = await getActorDefinition(actorIdOrName, apifyClient);
+                if (!actorDefinitionWithInfo) {
                     log.softFail('Actor not found or definition is not available', { actorName: actorIdOrName, statusCode: 404 });
                     return null;
                 }
-                // Cache the pruned Actor definition
-                actorDefinitionPrunedCache.set(actorIdOrName, actorDefinitionPruned);
+                // Cache the Actor definition with info
+                actorDefinitionPrunedCache.set(actorIdOrName, actorDefinitionWithInfo);
                 return {
-                    actorDefinitionPruned,
-                    webServerMcpPath: getActorMCPServerPath(actorDefinitionPruned),
+                    definition: actorDefinitionWithInfo.definition,
+                    actor: actorDefinitionWithInfo.info,
+                    webServerMcpPath: getActorMCPServerPath(actorDefinitionWithInfo.definition),
                 } as ActorInfo;
             } catch (error) {
                 logHttpError(error, 'Failed to fetch Actor definition', {
@@ -312,9 +314,14 @@ export async function getActorsAsTools(
 
     const clonedActors = structuredClone(actorsInfo);
 
-    // Filter out nulls and separate Actors with MCP servers and normal Actors
-    const actorMCPServersInfo = clonedActors.filter((actorInfo) => actorInfo && actorInfo.webServerMcpPath) as ActorInfo[];
-    const normalActorsInfo = clonedActors.filter((actorInfo) => actorInfo && !actorInfo.webServerMcpPath) as ActorInfo[];
+    // Filter out nulls - actorInfo can be null if the Actor was not found or an error occurred
+    const nonNullActors = clonedActors.filter((actorInfo): actorInfo is ActorInfo => Boolean(actorInfo));
+
+    // Separate Actors with MCP servers and normal Actors
+    // for MCP servers if mcp path is configured and also if the Actor standby mode is enabled
+    const actorMCPServersInfo = nonNullActors.filter((actorInfo) => isActorInfoMcpServer(actorInfo));
+    // all others
+    const normalActorsInfo = nonNullActors.filter((actorInfo) => !isActorInfoMcpServer(actorInfo));
 
     const [normalTools, mcpServerTools] = await Promise.all([
         getNormalActorsAsTools(normalActorsInfo),
diff --git a/src/tools/build.ts b/src/tools/build.ts
@@ -3,6 +3,7 @@ import { ACTOR_README_MAX_LENGTH } from '../const.js';
 import type {
     ActorDefinitionPruned,
     ActorDefinitionWithDesc,
+    ActorDefinitionWithInfo,
     SchemaProperties,
 } from '../types.js';
 
@@ -13,13 +14,13 @@ import type {
  * @param {string} actorIdOrName - Actor ID or Actor full name.
  * @param {ApifyClient} apifyClient - The Apify client instance.
  * @param {number} limit - Truncate the README to this limit.
- * @returns {Promise<ActorDefinitionWithDesc | null>} - The actor definition with description or null if not found.
+ * @returns {Promise<ActorDefinitionWithInfo | null>} - The Actor definition with info or null if not found.
  */
 export async function getActorDefinition(
     actorIdOrName: string,
     apifyClient: ApifyClient,
     limit: number = ACTOR_README_MAX_LENGTH,
-): Promise<ActorDefinitionPruned | null> {
+): Promise<ActorDefinitionWithInfo | null> {
     const actorClient = apifyClient.actor(actorIdOrName);
     try {
         // Fetch Actor details
@@ -41,7 +42,10 @@ export async function getActorDefinition(
             actorDefinitions.defaultRunOptions = actor.defaultRunOptions;
             // Pass pictureUrl from actor object (untyped property but present in API response)
             (actorDefinitions as Record<string, unknown>).pictureUrl = (actor as unknown as Record<string, unknown>).pictureUrl;
-            return pruneActorDefinition(actorDefinitions);
+            return {
+                definition: pruneActorDefinition(actorDefinitions),
+                info: actor,
+            };
         }
         return null;
     } catch (error) {
diff --git a/src/tools/utils.ts b/src/tools/utils.ts
@@ -2,7 +2,7 @@ import type { ValidateFunction } from 'ajv';
 import type Ajv from 'ajv';
 
 import { ACTOR_ENUM_MAX_LENGTH, ACTOR_MAX_DESCRIPTION_LENGTH, RAG_WEB_BROWSER_WHITELISTED_FIELDS } from '../const.js';
-import type { ActorInputSchema, ActorInputSchemaProperties, SchemaProperties } from '../types.js';
+import type { ActorInfo, ActorInputSchema, ActorInputSchemaProperties, SchemaProperties } from '../types.js';
 import {
     addGlobsProperties,
     addKeyValueProperties,
@@ -12,6 +12,13 @@ import {
     addResourcePickerProperties as addArrayResourcePickerProperties,
 } from '../utils/apify-properties.js';
 
+/*
+ * Checks if the given ActorInfo represents an MCP server Actor.
+ */
+export function isActorInfoMcpServer(actorInfo: ActorInfo): boolean {
+    return !!((actorInfo.webServerMcpPath && actorInfo.actor.actorStandby?.isEnabled));
+}
+
 export function actorNameToToolName(actorName: string): string {
     return actorName
         .replace(/\//g, '-slash-')
diff --git a/src/types.ts b/src/types.ts
@@ -3,7 +3,7 @@ import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import type { InitializeRequest, Notification, Prompt, Request, ToolSchema } from '@modelcontextprotocol/sdk/types.js';
 import type { ValidateFunction } from 'ajv';
-import type { ActorDefaultRunOptions, ActorDefinition, ActorStoreList, PricingInfo } from 'apify-client';
+import type { Actor, ActorDefaultRunOptions, ActorDefinition, ActorStoreList, PricingInfo } from 'apify-client';
 import type z from 'zod';
 
 import type { ACTOR_PRICING_MODEL, TELEMETRY_ENV, TOOL_STATUS } from './const.js';
@@ -62,6 +62,15 @@ export type ActorDefinitionPruned = Pick<ActorDefinitionWithDesc,
         pictureUrl?: string; // Optional, URL to the Actor's icon/picture
     };
 
+/**
+ * Actor definition combined with full actor metadata.
+ * Contains both the pruned definition (for schemas) and complete actor info.
+ */
+export type ActorDefinitionWithInfo = {
+    definition: ActorDefinitionPruned;
+    info: Actor;
+};
+
 /**
  * Base type for all tools in the MCP server.
  * Extends the MCP SDK's Tool schema, which requires inputSchema to have type: "object".
@@ -248,7 +257,8 @@ export type TelemetryEnv = (typeof TELEMETRY_ENV)[keyof typeof TELEMETRY_ENV];
  */
 export type ActorInfo = {
     webServerMcpPath: string | null; // To determined if the Actor is an MCP server
-    actorDefinitionPruned: ActorDefinitionPruned;
+    definition: ActorDefinitionPruned;
+    actor: Actor;
 };
 
 export type ExtendedActorStoreList = ActorStoreList & {
diff --git a/src/utils/actor.ts b/src/utils/actor.ts
@@ -21,10 +21,11 @@ export async function getActorMcpUrlCached(
     }
 
     try {
-        const actorDefinitionPruned = await getActorDefinition(actorIdOrName, apifyClient);
-        const mcpPath = actorDefinitionPruned && getActorMCPServerPath(actorDefinitionPruned);
-        if (actorDefinitionPruned && mcpPath) {
-            const url = await getActorMCPServerURL(actorDefinitionPruned.id, mcpPath);
+        const actorDefinitionWithInfo = await getActorDefinition(actorIdOrName, apifyClient);
+        const definition = actorDefinitionWithInfo?.definition;
+        const mcpPath = definition && getActorMCPServerPath(definition);
+        if (mcpPath) {
+            const url = await getActorMCPServerURL(definition.id, mcpPath);
             mcpServerCache.set(actorIdOrName, url);
             return url;
         }
