fix: Refactor usage metadata and expose run costs in MCP response (#456)

fix: Refactor MCP response code to centralize usage metadata logic with `buildUsageMeta` function. Fix naming.

Author: jirispilka

src/mcp/server.ts

@@ -70,7 +70,7 @@ import type {
 } from '../types.js';
 import { buildActorResponseContent } from '../utils/actor-response.js';
 import { logHttpError, redactSkyfirePayId } from '../utils/logging.js';
-import { buildMCPResponse } from '../utils/mcp.js';
+import { buildMCPResponse, buildUsageMeta } from '../utils/mcp.js';
 import { createProgressTracker } from '../utils/progress.js';
 import { getServerInstructions } from '../utils/server-instructions.js';
 import { validateSkyfirePayId } from '../utils/skyfire.js';
@@ -878,12 +878,11 @@ Please verify the server URL is correct and accessible, and ensure you have a va
                         }
 
                         const { content, structuredContent } = buildActorResponseContent(tool.actorFullName, callResult);
+                        const _meta = buildUsageMeta(callResult);
                         return {
                             content,
                             structuredContent,
-                            ...(callResult.usageTotalUsd !== undefined && {
-                                _meta: { apifyUsageTotalUsd: callResult.usageTotalUsd, apifyUsageUsd: callResult.usageUsd },
-                            }),
+                            ...(_meta && { _meta }),
                         };
                     } finally {
                         if (progressTracker) {
@@ -1076,12 +1075,11 @@ Please verify the tool name and ensure the tool is properly registered.`;
                     result = {};
                 } else {
                     const { content, structuredContent } = buildActorResponseContent(tool.actorFullName, callResult);
+                    const _meta = buildUsageMeta(callResult);
                     result = {
                         content,
                         structuredContent,
-                        ...(callResult.usageTotalUsd !== undefined && {
-                            _meta: { apifyUsageTotalUsd: callResult.usageTotalUsd, apifyUsageUsd: callResult.usageUsd },
-                        }),
+                        ...(_meta && { _meta }),
                     };
                 }
 

src/tools/actor.ts

@@ -35,7 +35,7 @@ import { ensureOutputWithinCharLimit, getActorDefinitionStorageFieldNames, getAc
 import { buildActorResponseContent } from '../utils/actor-response.js';
 import { ajv, compileSchema } from '../utils/ajv.js';
 import { logHttpError, redactSkyfirePayId } from '../utils/logging.js';
-import { buildMCPResponse } from '../utils/mcp.js';
+import { buildMCPResponse, buildUsageMeta } from '../utils/mcp.js';
 import type { ProgressTracker } from '../utils/progress.js';
 import type { JsonSchemaProperty } from '../utils/schema-generation.js';
 import { generateSchemaFromItems } from '../utils/schema-generation.js';
@@ -697,12 +697,11 @@ Do NOT proactively poll using ${HelperTools.ACTOR_RUNS_GET}. Wait for the widget
 
             const { content, structuredContent } = buildActorResponseContent(actorName, callResult, previewOutput);
 
+            const _meta = buildUsageMeta(callResult);
             return {
                 content,
                 structuredContent,
-                ...(callResult.usageTotalUsd !== undefined && {
-                    _meta: { apifyUsageTotalUsd: callResult.usageTotalUsd, apifyUsageUsd: callResult.usageUsd },
-                }),
+                ...(_meta && { _meta }),
             };
         } catch (error) {
             logHttpError(error, 'Failed to call Actor', { actorName, async: async ?? (apifyMcpServer.options.uiMode === 'openai') });

src/tools/run.ts

@@ -8,7 +8,7 @@ import { getWidgetConfig, WIDGET_URIS } from '../resources/widgets.js';
 import type { InternalToolArgs, ToolEntry, ToolInputSchema } from '../types.js';
 import { compileSchema } from '../utils/ajv.js';
 import { logHttpError } from '../utils/logging.js';
-import { buildMCPResponse } from '../utils/mcp.js';
+import { buildMCPResponse, buildUsageMeta } from '../utils/mcp.js';
 import { generateSchemaFromItems } from '../utils/schema-generation.js';
 import { getActorRunOutputSchema } from './structured-output-schemas.js';
 
@@ -138,15 +138,13 @@ USAGE EXAMPLES:
                     : `Actor run ${parsed.runId} status: ${run.status}. A progress widget has been rendered.`;
 
                 const widgetConfig = getWidgetConfig(WIDGET_URIS.ACTOR_RUN);
+                const usageMeta = buildUsageMeta(run);
                 return buildMCPResponse({
                     texts: [statusText],
                     structuredContent,
                     _meta: {
                         ...widgetConfig?.meta,
-                        ...(run.usageTotalUsd !== undefined && {
-                            apifyUsageTotalUsd: run.usageTotalUsd,
-                            apifyUsageUsd: run.usageUsd,
-                        }),
+                        ...usageMeta,
                     },
                 });
             }
@@ -158,10 +156,7 @@ USAGE EXAMPLES:
             return buildMCPResponse({
                 texts,
                 structuredContent,
-                _meta: run.usageTotalUsd !== undefined ? {
-                    apifyUsageTotalUsd: run.usageTotalUsd,
-                    apifyUsageUsd: run.usageUsd as Record<string, number> | undefined,
-                } : undefined,
+                _meta: buildUsageMeta(run),
             });
         } catch (error) {
             logHttpError(error, 'Failed to get Actor run', { runId: parsed.runId });

src/tools/structured-output-schemas.ts

@@ -223,7 +223,6 @@ export const callActorOutputSchema = {
             description: 'Dataset items from the Actor run (sync mode only, may be truncated due to size limits)',
         },
         instructions: { type: 'string', description: 'Instructions for the LLM on how to process or retrieve additional data' },
-        usageTotalUsd: { type: 'number', description: 'Total cost of the Actor run in USD (sync mode only)' },
     },
     required: ['runId'],
 };
@@ -244,7 +243,6 @@ export const getActorRunOutputSchema = {
             type: 'object' as const,
             description: 'Run statistics (compute units, memory, duration, etc.)',
         },
-        usageTotalUsd: { type: 'number', description: 'Total cost of the Actor run in USD' },
         dataset: {
             type: 'object' as const,
             description: 'Dataset information (only for completed runs with results)',

src/utils/mcp.ts

@@ -1,5 +1,26 @@
 import type { ToolStatus } from '../types.js';
 
+/**
+ * Builds usage metadata for MCP response from a source object containing Apify run costs.
+ * Uses MCP-compliant key names with com.apify/ prefix as per MCP specification.
+ * @param source - Object containing usage cost information
+ * @param source.usageTotalUsd - Total cost in USD (optional)
+ * @param source.usageUsd - Breakdown of costs by resource type (optional)
+ * @returns Usage metadata object or undefined if no usage data is available
+ */
+export function buildUsageMeta(source: {
+    usageTotalUsd?: number;
+    usageUsd?: unknown;
+}): Record<string, unknown> | undefined {
+    const { usageTotalUsd, usageUsd } = source;
+    return usageTotalUsd !== undefined
+        ? {
+            'com.apify/usageTotalUsd': usageTotalUsd,
+            'com.apify/usageUsd': usageUsd,
+        }
+        : undefined;
+}
+
 /**
  * Helper to build a response for MCP from an array of text strings.
  * @param options - Object containing response configuration