feat(gpt-apps): auto-include get-actor-run for call-actor and uiMode

Author: jakcinmarina

src/const.ts

@@ -218,8 +218,8 @@ These tools are called **Actors**. They enable you to extract structured data fr
   - First call with \`step="info"\` or use \`${HelperTools.ACTOR_GET_DETAILS}\` to obtain the Actor's schema.
   - Then call with \`step="call"\` to execute the Actor.
   - When \`step="call"\`, supports async execution via the \`async\` parameter:
-    - When \`async: false\` or not provided (default when UI mode is disabled): Waits for completion and returns results immediately.
-    - When \`async: true\` (default when UI mode is enabled): Starts the run and returns immediately with runId. Use \`${HelperTools.ACTOR_RUNS_GET}\` to check status and retrieve results.
+  - When \`async: false\` or not provided (default when UI mode is disabled): Waits for completion and returns results immediately.
+  - When \`async: true\` (default when UI mode is enabled): Starts the run and returns immediately with runId. Use \`${HelperTools.ACTOR_RUNS_GET}\` to check status and retrieve results.
 
 ### Tool disambiguation
 - **${HelperTools.ACTOR_OUTPUT_GET} vs ${HelperTools.DATASET_GET_ITEMS}:**

src/mcp/server.ts

@@ -309,7 +309,7 @@ export class ActorsMcpServer {
      * Used primarily for SSE.
      */
     public async loadToolsFromUrl(url: string, apifyClient: ApifyClient) {
-        const tools = await processParamsGetTools(url, apifyClient);
+        const tools = await processParamsGetTools(url, apifyClient, this.options.uiMode);
         if (tools.length > 0) {
             log.debug('Loading tools from query parameters');
             this.upsertTools(tools, false);

src/mcp/utils.ts

@@ -5,7 +5,7 @@ import type { TaskStore } from '@modelcontextprotocol/sdk/experimental/tasks/int
 import type { ApifyClient } from 'apify-client';
 
 import { processInput } from '../input.js';
-import type { Input } from '../types.js';
+import type { Input, UiMode } from '../types.js';
 import { loadToolsFromInput } from '../utils/tools-loader.js';
 import { MAX_TOOL_NAME_LENGTH, SERVER_ID_LENGTH } from './const.js';
 
@@ -41,10 +41,11 @@ export function getProxyMCPServerToolName(url: string, toolName: string): string
  * If URL contains query parameter `actors`, return tools from Actors otherwise return null.
  * @param url The URL to process
  * @param apifyClient The Apify client instance
+ * @param uiMode UI mode from server options
  */
-export async function processParamsGetTools(url: string, apifyClient: ApifyClient) {
+export async function processParamsGetTools(url: string, apifyClient: ApifyClient, uiMode?: UiMode) {
     const input = parseInputParamsFromUrl(url);
-    return await loadToolsFromInput(input, apifyClient);
+    return await loadToolsFromInput(input, apifyClient, uiMode);
 }
 
 export function parseInputParamsFromUrl(url: string): Input {

src/stdio.ts

@@ -188,7 +188,7 @@ async function main() {
 
     const apifyClient = new ApifyClient({ token: apifyToken });
     // Use the shared tools loading logic
-    const tools = await loadToolsFromInput(normalizedInput, apifyClient);
+    const tools = await loadToolsFromInput(normalizedInput, apifyClient, argv.uiMode);
 
     mcpServer.upsertTools(tools);
 

src/tools/actor.ts

@@ -402,6 +402,9 @@ EXAMPLES:
         // Additional props true to allow skyfire-pay-id
         additionalProperties: true,
     }),
+    _meta: {
+        ...getWidgetConfig(WIDGET_URIS.ACTOR_RUN)?.meta,
+    },
     annotations: {
         title: 'Call Actor',
         readOnlyHint: false,

src/tools/fetch-actor-details.ts

@@ -32,6 +32,9 @@ USAGE EXAMPLES:
     inputSchema: z.toJSONSchema(fetchActorDetailsToolArgsSchema) as ToolInputSchema,
     outputSchema: actorDetailsOutputSchema,
     ajvValidate: compileSchema(z.toJSONSchema(fetchActorDetailsToolArgsSchema)),
+    _meta: {
+        ...getWidgetConfig(WIDGET_URIS.SEARCH_ACTORS)?.meta,
+    },
     annotations: {
         title: 'Fetch Actor details',
         readOnlyHint: true,

src/tools/run.ts

@@ -41,6 +41,9 @@ USAGE EXAMPLES:
 - user_input: What is the datasetId for run y2h7sK3Wc?`,
     inputSchema: z.toJSONSchema(getActorRunArgs) as ToolInputSchema,
     ajvValidate: compileSchema(z.toJSONSchema(getActorRunArgs)),
+    _meta: {
+        ...getWidgetConfig(WIDGET_URIS.ACTOR_RUN)?.meta,
+    },
     annotations: {
         title: 'Get Actor run',
         readOnlyHint: true,

src/utils/tools-loader.ts

@@ -13,7 +13,8 @@ import { callActor } from '../tools/actor.js';
 import { getActorOutput } from '../tools/get-actor-output.js';
 import { addTool } from '../tools/helpers.js';
 import { getActorsAsTools, toolCategories, toolCategoriesEnabledByDefault } from '../tools/index.js';
-import type { Input, InternalToolArgs, ToolCategory, ToolEntry } from '../types.js';
+import { getActorRun } from '../tools/run.js';
+import type { Input, InternalToolArgs, ToolCategory, ToolEntry, UiMode } from '../types.js';
 import { getExpectedToolsByCategories } from './tools.js';
 
 // Lazily-computed cache of internal tools by name to avoid circular init issues.
@@ -34,11 +35,13 @@ function getInternalToolByNameMap(): Map<string, ToolEntry> {
  *
  * @param input The processed Input object
  * @param apifyClient The Apify client instance
+ * @param uiMode Optional UI mode.
  * @returns An array of tool entries
  */
 export async function loadToolsFromInput(
     input: Input,
     apifyClient: ApifyClient,
+    uiMode?: UiMode,
 ): Promise<ToolEntry[]> {
     // Helpers for readability
     const normalizeSelectors = (value: Input['tools']): (string | ToolCategory)[] | undefined => {
@@ -139,6 +142,15 @@ export async function loadToolsFromInput(
         result.push(getActorOutput);
     }
 
+    /**
+     * If call-actor tool is present or UI mode is enabled, automatically include get-actor-run
+     * to allow checking run status and retrieving results.
+     */
+    const hasGetActorRun = result.some((entry) => entry.name === HelperTools.ACTOR_RUNS_GET);
+    if (!hasGetActorRun && (hasCallActor || uiMode === 'openai')) {
+        result.push(getActorRun);
+    }
+
     // TEMP: for now we disable this swapping logic as the add-actor tool was misbehaving in some clients
     // Handle client capabilities logic for 'actors' category to swap call-actor for add-actor
     // if client supports dynamic tools.

tests/helpers.ts

@@ -27,7 +27,7 @@ function checkApifyToken(): void {
 }
 
 function appendSearchParams(url: URL, options?: McpClientOptions): void {
-    const { actors, enableAddingActors, tools, telemetry } = options || {};
+    const { actors, enableAddingActors, tools, telemetry, uiMode } = options || {};
     if (actors !== undefined) {
         url.searchParams.append('actors', actors.join(','));
     }
@@ -40,6 +40,9 @@ function appendSearchParams(url: URL, options?: McpClientOptions): void {
     // Append telemetry parameters (default to false for tests when not explicitly set)
     const telemetryEnabled = telemetry?.enabled !== undefined ? telemetry.enabled : false;
     url.searchParams.append('telemetry-enabled', telemetryEnabled.toString());
+    if (uiMode !== undefined) {
+        url.searchParams.append('ui', uiMode);
+    }
 }
 
 export async function createMcpSseClient(

tests/integration/suite.ts

@@ -145,12 +145,14 @@ export function createIntegrationTestsSuite(
         it('should list all default tools and Actors', async () => {
             client = await createClientFn();
             const tools = await client.listTools();
-            expect(tools.tools.length).toEqual(defaultTools.length + defaults.actors.length + 1);
+            expect(tools.tools.length).toEqual(defaultTools.length + defaults.actors.length + 2);
 
             const names = getToolNames(tools);
             expectToolNamesToContain(names, DEFAULT_TOOL_NAMES);
             expectToolNamesToContain(names, DEFAULT_ACTOR_NAMES);
-            expect(names).toContain('get-actor-output');
+            expect(names).toContain(HelperTools.ACTOR_OUTPUT_GET);
+            // get-actor-run should be automatically included when call-actor is present
+            expect(names).toContain(HelperTools.ACTOR_RUNS_GET);
             await client.close();
         });
 
@@ -165,12 +167,14 @@ export function createIntegrationTestsSuite(
             const expectedActors = ['apify-slash-rag-web-browser'];
 
             const expectedTotal = expectedActorsTools.concat(expectedDocsTools, expectedActors);
-            expect(names).toHaveLength(expectedTotal.length + 1);
+            expect(names).toHaveLength(expectedTotal.length + 2);
 
             expectToolNamesToContain(names, expectedActorsTools);
             expectToolNamesToContain(names, expectedDocsTools);
             expectToolNamesToContain(names, expectedActors);
-            expect(names).toContain('get-actor-output');
+            expect(names).toContain(HelperTools.ACTOR_OUTPUT_GET);
+            // get-actor-run should be automatically included when call-actor is present
+            expect(names).toContain(HelperTools.ACTOR_RUNS_GET);
 
             await client.close();
         });
@@ -204,11 +208,13 @@ export function createIntegrationTestsSuite(
         it('should list all default tools and Actors when enableAddingActors is false', async () => {
             client = await createClientFn({ enableAddingActors: false });
             const names = getToolNames(await client.listTools());
-            expect(names.length).toEqual(defaultTools.length + defaults.actors.length + 1);
+            expect(names.length).toEqual(defaultTools.length + defaults.actors.length + 2);
 
             expectToolNamesToContain(names, DEFAULT_TOOL_NAMES);
             expectToolNamesToContain(names, DEFAULT_ACTOR_NAMES);
-            expect(names).toContain('get-actor-output');
+            expect(names).toContain(HelperTools.ACTOR_OUTPUT_GET);
+            // get-actor-run should be automatically included when call-actor is present
+            expect(names).toContain(HelperTools.ACTOR_RUNS_GET);
 
             await client.close();
         });
@@ -412,9 +418,11 @@ export function createIntegrationTestsSuite(
             const selectedToolName = actorNameToToolName(ACTOR_PYTHON_EXAMPLE);
             client = await createClientFn({ enableAddingActors: true, tools: ['actors'] });
             const names = getToolNames(await client.listTools());
-            // Only the actors category, get-actor-output and add-actor should be loaded
-            const numberOfTools = toolCategories.actors.length + 2;
+            // Only the actors category, get-actor-output, get-actor-run, and add-actor should be loaded
+            const numberOfTools = toolCategories.actors.length + 3;
             expect(names).toHaveLength(numberOfTools);
+            // get-actor-run should be automatically included when call-actor is present
+            expect(names).toContain(HelperTools.ACTOR_RUNS_GET);
             // Check that the Actor is not in the tools list
             expect(names).not.toContain(selectedToolName);
 
@@ -1038,11 +1046,13 @@ export function createIntegrationTestsSuite(
             // Test with enableAddingActors = false via env var
             client = await createClientFn({ enableAddingActors: false, useEnv: true });
             const names = getToolNames(await client.listTools());
-            expect(names.length).toEqual(defaultTools.length + defaults.actors.length + 1);
+            expect(names.length).toEqual(defaultTools.length + defaults.actors.length + 2);
 
             expectToolNamesToContain(names, DEFAULT_TOOL_NAMES);
             expectToolNamesToContain(names, DEFAULT_ACTOR_NAMES);
-            expect(names).toContain('get-actor-output');
+            expect(names).toContain(HelperTools.ACTOR_OUTPUT_GET);
+            // get-actor-run should be automatically included when call-actor is present
+            expect(names).toContain(HelperTools.ACTOR_RUNS_GET);
 
             await client.close();
         });
@@ -1493,6 +1503,73 @@ export function createIntegrationTestsSuite(
             expect(searchActorsTool?._meta?.['openai/outputTemplate']).toBeDefined();
             expect(searchActorsTool?._meta?.['openai/widgetAccessible']).toBe(true);
 
+            const fetchActorDetailsToolFromList = tools.tools.find((tool) => tool.name === HelperTools.ACTOR_GET_DETAILS);
+            expect(fetchActorDetailsToolFromList).toBeDefined();
+            expect(fetchActorDetailsToolFromList?._meta).toBeDefined();
+            expect(fetchActorDetailsToolFromList?._meta?.['openai/outputTemplate']).toBeDefined();
+            expect(fetchActorDetailsToolFromList?._meta?.['openai/widgetAccessible']).toBe(true);
+
+            const callActorTool = tools.tools.find((tool) => tool.name === HelperTools.ACTOR_CALL);
+            expect(callActorTool).toBeDefined();
+            expect(callActorTool?._meta).toBeDefined();
+            expect(callActorTool?._meta?.['openai/outputTemplate']).toBeDefined();
+            expect(callActorTool?._meta?.['openai/widgetAccessible']).toBe(true);
+
+            await client.close();
+        });
+
+        it.runIf(options.transport === 'sse' || options.transport === 'streamable-http')('should use uiMode URL parameter when provided', async () => {
+            client = await createClientFn({ uiMode: 'openai' });
+            const tools = await client.listTools();
+            expect(tools.tools.length).toBeGreaterThan(0);
+
+            // Verify that tools have OpenAI metadata when UI mode is enabled via URL parameter
+            const searchActorsTool = tools.tools.find((tool) => tool.name === HelperTools.STORE_SEARCH);
+            expect(searchActorsTool).toBeDefined();
+            expect(searchActorsTool?._meta).toBeDefined();
+            expect(searchActorsTool?._meta?.['openai/outputTemplate']).toBeDefined();
+            expect(searchActorsTool?._meta?.['openai/widgetAccessible']).toBe(true);
+
+            const fetchActorDetailsToolFromList = tools.tools.find((tool) => tool.name === HelperTools.ACTOR_GET_DETAILS);
+            expect(fetchActorDetailsToolFromList).toBeDefined();
+            expect(fetchActorDetailsToolFromList?._meta).toBeDefined();
+            expect(fetchActorDetailsToolFromList?._meta?.['openai/outputTemplate']).toBeDefined();
+            expect(fetchActorDetailsToolFromList?._meta?.['openai/widgetAccessible']).toBe(true);
+
+            const callActorTool = tools.tools.find((tool) => tool.name === HelperTools.ACTOR_CALL);
+            expect(callActorTool).toBeDefined();
+            expect(callActorTool?._meta).toBeDefined();
+            expect(callActorTool?._meta?.['openai/outputTemplate']).toBeDefined();
+            expect(callActorTool?._meta?.['openai/widgetAccessible']).toBe(true);
+
+            await client.close();
+        });
+
+        it('should automatically include get-actor-run when uiMode is enabled', async () => {
+            client = await createClientFn({ uiMode: 'openai' });
+            const tools = await client.listTools();
+            const toolNames = getToolNames(tools);
+
+            // When uiMode is enabled, default tools include call-actor, so get-actor-run should be included
+            expect(toolNames).toContain(HelperTools.ACTOR_CALL);
+            expect(toolNames).toContain(HelperTools.ACTOR_RUNS_GET);
+
+            await client.close();
+        });
+
+        it.runIf(options.transport === 'sse' || options.transport === 'streamable-http')('should include get-actor-run without call-actor', async () => {
+            client = await createClientFn({ uiMode: 'openai', tools: ['docs'] });
+            const tools = await client.listTools();
+            const toolNames = getToolNames(tools);
+
+            // get-actor-run should be included when uiMode is enabled, even if call-actor is not present
+            expect(toolNames).toContain(HelperTools.ACTOR_RUNS_GET);
+            // Docs tools should be present
+            expect(toolNames).toContain(HelperTools.DOCS_SEARCH);
+            expect(toolNames).toContain(HelperTools.DOCS_FETCH);
+            // call-actor should NOT be present since only 'docs' was selected
+            expect(toolNames).not.toContain(HelperTools.ACTOR_CALL);
+
             await client.close();
         });
     });