feat(widgets): redesign actor search and actor detail (#430)

- add Actor widgets for search and detail

Search:
<img width="890" height="848" alt="image"
src="https://github.com/user-attachments/assets/dc6b7216-be7d-4a67-a8e5-88d8e76c36de"
/>

Mobile search:
<img width="492" height="549" alt="Screenshot 2026-02-12 at 11 46 03"
src="https://github.com/user-attachments/assets/c5bd5b84-3c1a-429e-b669-db76c44888cd"
/>

Detail:
<img width="819" height="756" alt="image"
src="https://github.com/user-attachments/assets/0dbfdfe5-617b-4f78-8f38-73642bb45e75"
/>

Fullscreen detail:
<img width="1618" height="1005" alt="image"
src="https://github.com/user-attachments/assets/ea06b8bc-7161-4e77-b73f-d9386826840d"
/>

Mobile detail:
<img width="417" height="909" alt="image"
src="https://github.com/user-attachments/assets/a7fe7f21-ecd3-42cf-b366-2d3d97e27850"
/>

Author: jmikitova

package-lock.json

@@ -68,7 +68,7 @@ EXAMPLES:
 
         if (apifyMcpServer.options.uiMode === 'openai') {
             const { structuredContent: processedStructuredContent, actorUrl } = processActorDetailsForResponse(details);
-            const widgetStructuredContent = {
+            const structuredContent = {
                 actorInfo: details.actorCardStructured,
                 inputSchema: details.inputSchema,
                 actorDetails: processedStructuredContent.actorDetails,
@@ -85,7 +85,7 @@ An interactive widget has been rendered with detailed Actor information.
             const widgetConfig = getWidgetConfig(WIDGET_URIS.SEARCH_ACTORS);
             return buildMCPResponse({
                 texts,
-                structuredContent: widgetStructuredContent,
+                structuredContent,
                 _meta: {
                     ...widgetConfig?.meta,
                     'openai/widgetDescription': `Actor details for ${parsed.actor} from Apify Store`,

src/tools/fetch-actor-details.ts

@@ -1,31 +1,15 @@
 import type { ActorStoreList } from 'apify-client';
 import { z } from 'zod';
 
-import { ApifyClient } from '../apify-client.js';
 import { HelperTools } from '../const.js';
 import { getWidgetConfig, WIDGET_URIS } from '../resources/widgets.js';
-import type { ActorPricingModel, ExtendedActorStoreList, InternalToolArgs, ToolEntry, ToolInputSchema } from '../types.js';
-import { formatActorForWidget, formatActorToActorCard, formatActorToStructuredCard } from '../utils/actor-card.js';
+import type { ActorPricingModel, InternalToolArgs, ToolEntry, ToolInputSchema } from '../types.js';
+import { formatActorForWidget, formatActorToActorCard, formatActorToStructuredCard, type WidgetActor } from '../utils/actor-card.js';
 import { searchAndFilterActors } from '../utils/actor-search.js';
 import { compileSchema } from '../utils/ajv.js';
 import { buildMCPResponse } from '../utils/mcp.js';
 import { actorSearchOutputSchema } from './structured-output-schemas.js';
 
-export async function searchActorsByKeywords(
-    search: string,
-    apifyToken: string,
-    limit: number | undefined = undefined,
-    offset: number | undefined = undefined,
-    allowsAgenticUsers: boolean | undefined = undefined,
-): Promise<ExtendedActorStoreList[]> {
-    const client = new ApifyClient({ token: apifyToken });
-    const storeClient = client.store();
-    if (allowsAgenticUsers !== undefined) storeClient.params = { ...storeClient.params, allowsAgenticUsers };
-
-    const results = await storeClient.list({ search, limit, offset });
-    return results.items;
-}
-
 export const searchActorsArgsSchema = z.object({
     limit: z.number()
         .int()
@@ -172,7 +156,7 @@ You can also try using more specific or alternative keywords related to your sea
             count: number;
             instructions?: string;
             // Widget format actors (not validated by schema, but available for widget UI)
-            widgetActors?: ReturnType<typeof formatActorForWidget>[];
+            widgetActors?: WidgetActor[];
         } = {
             actors: structuredActorCards,
             query: parsed.keywords,
@@ -184,17 +168,19 @@ You can also try using more specific or alternative keywords related to your sea
         // Add widget format actors when widget mode is enabled
         if (apifyMcpServer.options.uiMode === 'openai') {
             structuredContent.widgetActors = actors.map(formatActorForWidget);
-        }
 
-        // When widget mode is enabled, return minimal text with widget metadata
-        // When widget mode is disabled, return full text response without widget metadata
-        if (apifyMcpServer.options.uiMode === 'openai') {
+            const actorCards = actors.map((actor) => formatActorToActorCard(actor));
+            const actorsText = actorCards.join('\n\n');
             const texts = [`
  # Search results:
  - **Search query:** ${parsed.keywords}
  - **Number of Actors found:** ${actors.length}
 
-An interactive widget has been rendered with the search results.
+An interactive widget has been rendered with the search results. The user can already see the list of Actors visually in the widget, so do NOT print or summarize the Actor list in your response.
+
+ # Actors:
+
+ ${actorsText}
 `];
 
             const widgetConfig = getWidgetConfig(WIDGET_URIS.SEARCH_ACTORS);

src/tools/store_collection.ts

@@ -111,7 +111,13 @@ export const actorInfoSchema = {
         },
         pricing: pricingSchema,
         stats: statsSchema,
-        rating: { type: 'number', description: 'Actor rating' },
+        rating: {
+            type: 'object' as const, // Literal type required for MCP SDK type compatibility
+            properties: {
+                average: { type: 'number', description: 'Average rating' },
+                count: { type: 'number', description: 'Number of ratings' },
+            },
+        },
         modifiedAt: { type: 'string', description: 'Last modification date' },
         isDeprecated: { type: 'boolean', description: 'Whether the Actor is deprecated' },
     },

src/tools/structured-output-schemas.ts

@@ -3,7 +3,15 @@ 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 { Actor, ActorDefaultRunOptions, ActorDefinition, ActorStoreList, PricingInfo } from 'apify-client';
+import type {
+    Actor as ActorOutdated,
+    ActorDefaultRunOptions,
+    ActorDefinition,
+    ActorRunPricingInfo,
+    ActorStats,
+    ActorStoreList as ActorStoreListOutdated,
+    PricePerEventActorPricingInfo as PricePerEventActorPricingInfoOutdated,
+} from 'apify-client';
 import type z from 'zod';
 
 import type { ACTOR_PRICING_MODEL, TELEMETRY_ENV, TOOL_STATUS } from './const.js';
@@ -59,17 +67,17 @@ export type ActorDefinitionWithDesc = Omit<ActorDefinition, 'input'> & {
  */
 export type ActorDefinitionPruned = Pick<ActorDefinitionWithDesc,
     'id' | 'actorFullName' | 'buildTag' | 'readme' | 'readmeSummary' | 'input' | 'description' | 'defaultRunOptions'> & {
-        webServerMcpPath?: string; // Optional, used for Actorized MCP server tools
-        pictureUrl?: string; // Optional, URL to the Actor's icon/picture
-    };
+    webServerMcpPath?: string; // Optional, used for Actorized MCP server tools
+    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;
+    info: ActorOutdated;
 };
 
 /**
@@ -198,27 +206,28 @@ export type PricingTier = 'FREE' | 'BRONZE' | 'SILVER' | 'GOLD' | 'PLATINUM' | '
  */
 export type ActorChargeEvent = {
     eventTitle: string;
-    eventDescription: string;
+    eventDescription?: string;
     /** Flat price per event in USD (if not tiered) */
     eventPriceUsd?: number;
     /** Tiered pricing per event, by tier name (FREE, BRONZE, etc.) */
     eventTieredPricingUsd?: Partial<Record<PricingTier, TieredEventPrice>>;
 };
 
-/**
- * Pricing per event for an Actor, supporting both flat and tiered pricing.
- */
-export type PricingPerEvent = {
-    actorChargeEvents: Record<string, ActorChargeEvent>;
-};
+export type TieredPricing = {
+    [tier: string]: {
+        tieredPricePerUnitUsd: number;
+    };
+}
 
-export type ExtendedPricingInfo = PricingInfo & {
-    pricePerUnitUsd?: number;
-    trialMinutes?: number;
-    unitName?: string; // Name of the unit for the pricing model
-    pricingPerEvent: PricingPerEvent;
-    tieredPricing?: Partial<Record<PricingTier, { tieredPricePerUnitUsd: number }>>;
-};
+type PricePerEventActorPricingInfo = PricePerEventActorPricingInfoOutdated & {
+    pricingPerEvent: {
+        actorChargeEvents: Record<string, ActorChargeEvent>;
+    };
+}
+
+export type PricingInfo = ActorRunPricingInfo & {
+    tieredPricing?: TieredPricing;
+} | PricePerEventActorPricingInfo;
 
 export type ToolCategory = keyof typeof toolCategories;
 /**
@@ -234,8 +243,8 @@ export type Input = {
      */
     actors?: string[] | string;
     /**
-    * @deprecated Use `enableAddingActors` instead.
-    */
+     * @deprecated Use `enableAddingActors` instead.
+     */
     enableActorAutoLoading?: boolean | string;
     enableAddingActors?: boolean | string;
     maxActorMemoryBytes?: number;
@@ -265,13 +274,48 @@ 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
     definition: ActorDefinitionPruned;
-    actor: Actor;
+    actor: ActorOutdated;
 };
 
-export type ExtendedActorStoreList = ActorStoreList & {
-    categories?: string[];
-    bookmarkCount?: number;
+export type ActorStoreList = ActorStoreListOutdated & {
+    actorReviewCount?: number;
     actorReviewRating?: number;
+    badge?: string | null;
+    bookmarkCount?: number;
+    categories?: string[];
+    currentPricingInfo: ActorRunPricingInfo;
+    isWhiteListedForAgenticPayments?: boolean;
+    notice?: string | null;
+    userFullName?: string;
+    stats: ActorStats & {
+        actorReviewCount?: number;
+        actorReviewRating?: number;
+        bookmarkCount?: number;
+        publicActorRunStats30Days?: Partial<Record<string, number>> & {
+            SUCCEEDED?: number;
+            TOTAL?: number;
+        };
+    };
+};
+
+export type Actor = ActorOutdated & {
+    actorPermissionLevel?: string;
+    hasNoDataset?: boolean;
+    isCritical?: boolean;
+    isGeneric?: boolean;
+    isSourceCodeHidden?: boolean;
+    pictureUrl?: string;
+    standbyUrl?: string | null;
+    stats: ActorStats & {
+        publicActorRunStats30Days?: Partial<Record<string, number>> & {
+            SUCCEEDED?: number;
+            TOTAL?: number;
+        };
+        actorReviewCount?: number;
+        actorReviewRating?: number;
+        bookmarkCount?: number;
+        lastRunStartedAt?: string | Date | null;
+    };
 };
 
 export type ActorDefinitionStorage = {
@@ -454,6 +498,7 @@ export type StructuredActorCard = {
     title?: string;
     url: string;
     fullName: string;
+    pictureUrl?: string;
     developer: {
         username: string;
         isOfficialApify: boolean;
@@ -468,7 +513,10 @@ export type StructuredActorCard = {
         successRate?: number;
         bookmarks?: number;
     };
-    rating?: number;
+    rating?: {
+        average: number;
+        count: number;
+    };
     modifiedAt?: string;
     isDeprecated: boolean;
 }