|
| 1 | +import dedent from 'dedent'; |
| 2 | +import { z } from 'zod'; |
| 3 | + |
| 4 | +import { HelperTools } from '../../const.js'; |
| 5 | +import { getWidgetConfig, WIDGET_URIS } from '../../resources/widgets.js'; |
| 6 | +import type { InternalToolArgs, ToolEntry, ToolInputSchema } from '../../types.js'; |
| 7 | +import { |
| 8 | + buildActorDetailsForWidget, |
| 9 | + buildCardOptions, |
| 10 | + fetchActorDetails, |
| 11 | +} from '../../utils/actor_details.js'; |
| 12 | +import { compileSchema } from '../../utils/ajv.js'; |
| 13 | +import { buildMCPResponse } from '../../utils/mcp.js'; |
| 14 | +import { getUserInfoCached } from '../../utils/userid_cache.js'; |
| 15 | +import { fixActorNameInputAndLog } from '../core/actor_tools_factory.js'; |
| 16 | +import { |
| 17 | + actorDetailsOutputDefaults, |
| 18 | + buildActorNotFoundResponse, |
| 19 | +} from '../core/fetch_actor_details_common.js'; |
| 20 | +import { actorDetailsWidgetOutputSchema } from '../structured_output_schemas.js'; |
| 21 | + |
| 22 | +const widgetConfig = getWidgetConfig(WIDGET_URIS.SEARCH_ACTORS); |
| 23 | + |
| 24 | +/** |
| 25 | + * Widget-only input: `actor` only. `additionalProperties: false` + AJV's |
| 26 | + * `removeAdditional: true` means stray keys like `output` are silently stripped |
| 27 | + * at the server boundary; the `.strict()` Zod parse below is belt-and-braces |
| 28 | + * for any path that bypasses AJV. |
| 29 | + */ |
| 30 | +const fetchActorDetailsWidgetArgsSchema = z.object({ |
| 31 | + actor: z.string() |
| 32 | + .min(1) |
| 33 | + .describe('Actor ID or full name in the format "username/name", e.g., "apify/rag-web-browser".'), |
| 34 | +}).strict(); |
| 35 | + |
| 36 | +const FETCH_ACTOR_DETAILS_WIDGET_DESCRIPTION = dedent` |
| 37 | + Render an interactive UI element (widget) displaying detailed Actor information for the user. |
| 38 | +
|
| 39 | + Use this tool ONLY when the user explicitly wants to see or browse Actor details |
| 40 | + (e.g., "show me apify/rag-web-browser", "tell me about this Actor", "what does apify/web-scraper look like"). |
| 41 | + The response renders as an interactive widget the user can view directly. |
| 42 | +
|
| 43 | + For silent data lookups (e.g., fetching the input schema before calling an Actor, inspecting README |
| 44 | + for decision making), use ${HelperTools.ACTOR_GET_DETAILS} instead — it returns the same data |
| 45 | + without rendering a widget. |
| 46 | +
|
| 47 | + Input: the Actor ID or full name only. Output fields are fixed by the widget contract. |
| 48 | +`; |
| 49 | + |
| 50 | +export const fetchActorDetailsWidgetTool: ToolEntry = Object.freeze({ |
| 51 | + type: 'internal', |
| 52 | + name: HelperTools.ACTOR_GET_DETAILS_WIDGET, |
| 53 | + description: FETCH_ACTOR_DETAILS_WIDGET_DESCRIPTION, |
| 54 | + inputSchema: z.toJSONSchema(fetchActorDetailsWidgetArgsSchema) as ToolInputSchema, |
| 55 | + outputSchema: actorDetailsWidgetOutputSchema, |
| 56 | + ajvValidate: compileSchema(z.toJSONSchema(fetchActorDetailsWidgetArgsSchema)), |
| 57 | + // Tool-level widget meta; only registered in apps mode so stripWidgetMeta is a no-op here. |
| 58 | + _meta: { |
| 59 | + ...widgetConfig?.meta, |
| 60 | + }, |
| 61 | + annotations: { |
| 62 | + title: 'Fetch Actor details (widget)', |
| 63 | + readOnlyHint: true, |
| 64 | + destructiveHint: false, |
| 65 | + idempotentHint: true, |
| 66 | + openWorldHint: false, |
| 67 | + }, |
| 68 | + call: async (toolArgs: InternalToolArgs) => { |
| 69 | + const { apifyToken, apifyClient, mcpSessionId } = toolArgs; |
| 70 | + const parsed = fetchActorDetailsWidgetArgsSchema.parse(toolArgs.args); |
| 71 | + const actorName = fixActorNameInputAndLog(parsed.actor, { mcpSessionId, route: HelperTools.ACTOR_GET_DETAILS_WIDGET }); |
| 72 | + |
| 73 | + const { userPlanTier } = await getUserInfoCached(apifyToken, apifyClient); |
| 74 | + const cardOptions = { ...buildCardOptions(actorDetailsOutputDefaults), userTier: userPlanTier }; |
| 75 | + const details = await fetchActorDetails(apifyClient, actorName, cardOptions); |
| 76 | + if (!details) { |
| 77 | + return buildActorNotFoundResponse(actorName); |
| 78 | + } |
| 79 | + |
| 80 | + const { actorUrl, actorDetails } = buildActorDetailsForWidget(details, userPlanTier); |
| 81 | + const structuredContent = { |
| 82 | + actorDetails: { |
| 83 | + actorInfo: actorDetails.actorInfo, |
| 84 | + actorCard: actorDetails.actorCard, |
| 85 | + readme: actorDetails.readme, |
| 86 | + }, |
| 87 | + }; |
| 88 | + |
| 89 | + const texts = [dedent` |
| 90 | + # Actor information: |
| 91 | + - **Actor:** ${actorName} |
| 92 | + - **URL:** ${actorUrl} |
| 93 | +
|
| 94 | + An interactive widget has been rendered with detailed Actor information. |
| 95 | + `]; |
| 96 | + |
| 97 | + return buildMCPResponse({ |
| 98 | + texts, |
| 99 | + structuredContent, |
| 100 | + // Response-level meta; only returned in apps mode (this handler is apps-only). |
| 101 | + _meta: { |
| 102 | + ...widgetConfig?.meta, |
| 103 | + 'openai/widgetDescription': `Actor details for ${actorName} from Apify Store`, |
| 104 | + }, |
| 105 | + }); |
| 106 | + }, |
| 107 | +} as const); |
0 commit comments