feat(gpt-apps): add tools and widget descriptors (#375)

Author: jakcinmarina

README.md

@@ -243,6 +243,39 @@ As above, this exposes only the specified Actor (`apify/my-actor`) as a tool. No
 >
 > **For production use and stable interfaces, always explicitly specify the `tools` parameter** to ensure your configuration remains consistent across updates.
 
+### UI mode configuration
+
+The `uiMode` parameter enables OpenAI-specific widget rendering in tool responses. When enabled, tools like `search-actors` return interactive widget responses optimized for OpenAI clients.
+
+**Configuring the hosted server:**
+
+Enable UI mode using the `ui` query parameter:
+
+```
+https://mcp.apify.com?ui=openai
+```
+
+You can combine it with other parameters:
+
+```
+https://mcp.apify.com?tools=actors,docs&ui=openai
+```
+
+**Configuring the CLI:**
+
+The CLI can be configured using command-line flags. For example, to enable UI mode:
+
+```bash
+npx @apify/actors-mcp-server --uiMode openai
+```
+
+You can also set it via the `UI_MODE` environment variable:
+
+```bash
+export UI_MODE=openai
+npx @apify/actors-mcp-server
+```
+
 ### Backward compatibility
 
 The v2 configuration preserves backward compatibility with v1 usage. Notes:

eslint.config.mjs

@@ -27,6 +27,7 @@ export default [
             'evals/*.ts', // Top-level evaluation scripts
             'evals/*.md', // Documentation files
             'evals/*.json', // Test case data files
+            'src/web/**', // Web directory has its own TypeScript project and build system
         ],
     },
     // Apply the shared Apify TypeScript ESLint configuration

package.json

@@ -87,12 +87,14 @@
     "lint:fix": "eslint . --fix",
     "check": "npm run type-check && npm run lint:fix",
     "build": "tsc -b src",
+    "postbuild": "mkdir -p dist/web && (cp -r src/web/dist dist/web/ 2>/dev/null || :)",
     "build:watch": "tsc -b src -w",
+    "check:widgets": "tsx scripts/check-widgets.ts",
     "type-check": "tsc --noEmit",
     "test": "npm run test:unit",
     "test:unit": "vitest run tests/unit",
     "test:integration": "npm run build && vitest run tests/integration",
-    "clean": "tsc -b src --clean",
+    "clean": "tsc -b src --clean && rm -rf dist/web",
     "evals:create-dataset": "tsx evals/create-dataset.ts",
     "evals:run": "tsx evals/run-evaluation.ts",
     "evals:workflow": "tsx evals/workflows/run-workflow-evals.ts"

scripts/check-widgets.ts

@@ -0,0 +1,46 @@
+/* eslint-disable no-console */
+/**
+ * Build-time check to ensure widget files exist
+ * This script validates that all registered widgets have corresponding files
+ */
+
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { WIDGET_REGISTRY } from '../src/utils/widgets.js';
+
+const filename = fileURLToPath(import.meta.url);
+const projectRoot = resolve(dirname(filename), '..');
+const webDistPath = resolve(projectRoot, 'src/web/dist');
+
+const missingWidgets: string[] = [];
+const existingWidgets: string[] = [];
+
+for (const config of Object.values(WIDGET_REGISTRY)) {
+    const jsPath = resolve(webDistPath, config.jsFilename);
+    if (existsSync(jsPath)) {
+        existingWidgets.push(config.name);
+    } else {
+        missingWidgets.push(`${config.name} (${config.jsFilename})`);
+    }
+}
+
+if (missingWidgets.length > 0) {
+    console.error('Missing widget files:');
+    for (const widget of missingWidgets) {
+        console.error(`   - ${widget}`);
+    }
+    console.error(`\nExpected location: ${webDistPath}`);
+    console.error('\nPlease build the widgets before building the server.');
+    process.exit(1);
+}
+
+if (existingWidgets.length > 0) {
+    console.log('All widget files found:');
+    for (const widget of existingWidgets) {
+        console.log(`   - ${widget}`);
+    }
+}
+
+process.exit(0);

src/actor/server.ts

@@ -15,7 +15,7 @@ import log from '@apify/log';
 
 import { ApifyClient } from '../apify-client.js';
 import { ActorsMcpServer } from '../mcp/server.js';
-import type { ApifyRequestParams } from '../types.js';
+import type { ApifyRequestParams, UiMode } from '../types.js';
 import { parseBooleanFromString } from '../utils/generic.js';
 import { getHelpMessage, HEADER_READINESS_PROBE, Routes, TransportType } from './const.js';
 import { getActorRunData } from './utils.js';
@@ -90,13 +90,17 @@ export function createExpressApp(
                 ?? parseBooleanFromString(process.env.TELEMETRY_ENABLED)
                 ?? true;
 
+            const uiModeParam = urlParams.get('ui') as UiMode | undefined;
+            const uiMode = uiModeParam ?? process.env.UI_MODE as UiMode | undefined;
+
             const mcpServer = new ActorsMcpServer({
                 taskStore,
                 setupSigintHandler: false,
                 transportType: 'sse',
                 telemetry: {
                     enabled: telemetryEnabled,
                 },
+                uiMode,
             });
             const transport = new SSEServerTransport(Routes.MESSAGE, res);
 
@@ -214,6 +218,9 @@ export function createExpressApp(
                     ?? parseBooleanFromString(process.env.TELEMETRY_ENABLED)
                     ?? true;
 
+                const uiModeParam = urlParams.get('ui') as UiMode | undefined;
+                const uiMode = uiModeParam ?? process.env.UI_MODE as UiMode | undefined;
+
                 const mcpServer = new ActorsMcpServer({
                     taskStore,
                     setupSigintHandler: false,
@@ -222,6 +229,7 @@ export function createExpressApp(
                     telemetry: {
                         enabled: telemetryEnabled,
                     },
+                    uiMode,
                 });
 
                 // Load MCP server tools

src/const.ts

@@ -215,8 +215,11 @@ These tools are called **Actors**. They enable you to extract structured data fr
 
 ### Tool dependencies
 - \`${HelperTools.ACTOR_CALL}\`:
-  - First call with \`step="info"\` or use \`${HelperTools.ACTOR_GET_DETAILS}\` to obtain the Actor’s schema.
+  - 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.
 
 ### Tool disambiguation
 - **${HelperTools.ACTOR_OUTPUT_GET} vs ${HelperTools.DATASET_GET_ITEMS}:**
@@ -227,4 +230,6 @@ These tools are called **Actors**. They enable you to extract structured data fr
   \`${HelperTools.STORE_SEARCH}\` finds robust and reliable Actors for specific websites; ${RAG_WEB_BROWSER} is a general and versatile web scraping tool.
 - **Dedicated Actor tools (e.g. ${RAG_WEB_BROWSER}) vs ${HelperTools.ACTOR_CALL}:**
   Prefer dedicated tools when available; use \`${HelperTools.ACTOR_CALL}\` only when no specialized tool exists in Apify store.
+- **Async parameter for ${HelperTools.ACTOR_CALL} (when step="call"):**
+  \`${HelperTools.ACTOR_CALL}\` supports async execution via the \`async\` boolean parameter when \`step="call"\`. When \`async: false\` or not provided, waits for completion and returns results (default when UI mode is disabled). When \`async: true\`, starts the run and returns immediately with runId (default when UI mode is enabled). Use \`async: true\` when the user wants background/progress/UI. After starting an async run and obtaining runId, do NOT start another run—only poll with \`${HelperTools.ACTOR_RUNS_GET}\` using that runId.
 `;