@convertcom/mcp-server 0.0.1-beta.17 → 0.0.1-beta.18

package/README.md

@@ -20,7 +20,7 @@ MCP (Model Context Protocol) is an open standard that allows AI models to intera
 **Key Benefits:**
 - 🔌 **Zero-config integration** – Works with Claude Desktop, Cursor, and any MCP-compatible client
 - 🔍 **Full API access** – Comprehensive coverage of Convert's [REST API v2](https://api.convert.com/doc/v2/)
-- 📚 **Built-in knowledge** – 9,738 indexed chunks across 1,157 Convert documentation URLs
+- 📚 **Built-in knowledge** – 7,992 indexed chunks across 1,245 Convert documentation URLs
 - 🛡️ **Configurable permissions** – Three access levels from reporting-only to full read/write
 - 🧩 **Namespaced tools** – Clean interface with 15 generated API namespaces plus one computed `operator` namespace
 - 🧠 **MCP prompts** – 20 curated Convert experience workflows exposed through `prompts/list` and `prompts/get`

package/build/executor.js

@@ -7,6 +7,8 @@ import { precompiledToolValidators } from './generated-tool-validators.js';
 import { BAYESIAN_ONLY_STATS_FIELDS, FREQUENTIST_ONLY_STATS_FIELDS, isPlainObject, isStatsEngineSchemaTool, normalizeSchema, } from './schema-normalizer.js';
 import { isReadOnlyDelegate } from './tool-safety.js';
 import { redactSensitiveValues, scrubDiagnosticText } from './redaction.js';
+import { imageDimensionsFromBase64 } from './image-dimensions.js';
+import { classifyExecutorFailure, failureAttribution, inputFailure, permissionFailure, validationLabels, } from './failure-attribution.js';
 const MAX_API_ERROR_DETAIL_LEN = 2000;
 const MAX_SCHEMA_ERRORS_TO_SHOW = 8;
 const MAX_SCHEMA_ERRORS_TO_ANALYZE = 1000;
@@ -14,11 +16,21 @@ const MAX_STRUCTURED_SCHEMA_ISSUES = 25;
 const MAX_STRUCTURED_SCHEMA_ISSUES_BYTES = 64 * 1024;
 const MAX_ENUM_VALUES_TO_SHOW = 20;
 const MAX_ENUM_VALUE_LENGTH = 80;
-const MEDIA_RESPONSE_TOOLS = new Set([
-    'getexperiencevariationscreenshot',
+// Heatmap images are explicitly requested, but their output must also fit a
+// conservative visual/model budget. These are policy ceilings, not token-cost
+// guarantees. Keep the existing separate screenshot behavior.
+const MAX_HEATMAP_RESPONSE_BYTES = 1024 * 1024;
+const MAX_HEATMAP_DIMENSION = 2048;
+const MAX_HEATMAP_PIXELS = 1024 * 1024;
+const MAX_HEATMAP_FALLBACK_MODEL_BYTES = 64 * 1024;
+const HEATMAP_RESPONSE_TOOLS = new Set([
     'getexperienceheatmapbackground',
     'getexperienceheatmapoverlay',
 ]);
+const MEDIA_RESPONSE_TOOLS = new Set([
+    'getexperiencevariationscreenshot',
+    ...HEATMAP_RESPONSE_TOOLS,
+]);
 const EXPLICIT_CREDENTIAL_RESPONSE_TOOLS = new Set([
     'getapikeyslist',
     'getsdkkeyslist',
@@ -87,6 +99,7 @@ export async function executeValidatedToolByName(toolName, toolArgs, executionCo
 async function executeApiTool(toolName, definition, toolArgs, executionContext, argumentsAlreadyValidated = false) {
     let uploadScreenshotReadbackUrl = null;
     let authContext;
+    let dispatchState = 'not_dispatched';
     // This is an authorization boundary, not input validation. Keep it on the
     // common execution path so the namespace-only validated seam cannot bypass
     // the staff browse restriction.
@@ -95,10 +108,12 @@ async function executeApiTool(toolName, definition, toolArgs, executionContext,
             error: 'ReadOnlyImpersonation',
             tool: toolName,
             message: 'Staff impersonation is browse-only. Remove as_user and operate as yourself for any write or delete action.',
+            failure: permissionFailure('ReadOnlyImpersonation', 'executor'),
         };
         return {
             isError: true,
             content: [{ type: 'text', text: JSON.stringify(payload) }],
+            structuredContent: payload,
         };
     }
     try {
@@ -106,6 +121,7 @@ async function executeApiTool(toolName, definition, toolArgs, executionContext,
         if (!argumentsAlreadyValidated) {
             const validation = validateToolArgs(toolName, definition.inputSchema, argsToValidate);
             if (!validation.ok) {
+                const validationAttribution = validationLabels(validation.errors);
                 return {
                     isError: true,
                     content: [{ type: 'text', text: validation.message }],
@@ -115,6 +131,7 @@ async function executeApiTool(toolName, definition, toolArgs, executionContext,
                         issues: validation.errors,
                         issue_count: validation.totalErrors,
                         issues_truncated: validation.errorsTruncated,
+                        failure: inputFailure('InvalidArguments', 'executor', validationAttribution.rule, validationAttribution.path),
                     },
                 };
             }
@@ -190,6 +207,7 @@ async function executeApiTool(toolName, definition, toolArgs, executionContext,
                     error: 'MissingConvertCredentials',
                     message,
                     hint: executionContext.missingCredentialsHint,
+                    failure: permissionFailure('MissingConvertCredentials', 'executor'),
                 },
             };
         }
@@ -208,12 +226,61 @@ async function executeApiTool(toolName, definition, toolArgs, executionContext,
         if (toolName === 'uploadexperiencevariationscreenshot') {
             uploadScreenshotReadbackUrl = fullUrl;
         }
+        dispatchState = 'unknown';
         const response = await executeApiRequest(config, executionContext);
+        dispatchState = 'dispatched';
         const embeddedError = embeddedApiError(response.data);
         if (embeddedError) {
             throw new ConvertApiTransportError(`API Error: Status ${embeddedError.status}`, embeddedError.status, response.data);
         }
         const media = mediaResponse(toolName, response);
+        if (media && 'problem' in media) {
+            if (!HEATMAP_RESPONSE_TOOLS.has(toolName)) {
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: 'The upstream image response had unsupported base64 encoding or image signature. No image data was returned.' }],
+                    structuredContent: {
+                        error: 'InvalidMediaResponse',
+                        status: 502,
+                        failure: failureAttribution({
+                            category: 'upstream', source: 'executor', stage: 'upstream_response',
+                            dispatchState: 'dispatched', code: 'InvalidMediaResponse', upstreamStatus: response.status,
+                        }),
+                    },
+                };
+            }
+            const oversized = media.problem === 'budget_exceeded';
+            const error = oversized ? 'ImageBudgetExceeded' : 'InvalidMediaResponse';
+            return {
+                isError: true,
+                content: [{ type: 'text', text: oversized
+                            ? 'The requested heatmap image exceeds the MCP visual output budget. No image data was returned. Open the original heatmap in Convert UI for full-resolution inspection.'
+                            : 'The upstream image has an unsupported, malformed, truncated, or animated format. No image data was returned. Open the original heatmap in Convert UI for inspection.' }],
+                structuredContent: {
+                    error,
+                    status: oversized ? 413 : 502,
+                    upstream_status: response.status,
+                    ...(media.mimeType && { mime_type: media.mimeType }),
+                    ...(media.sizeBytes !== undefined && { size_bytes: media.sizeBytes }),
+                    ...(media.width !== undefined && { width: media.width }),
+                    ...(media.height !== undefined && { height: media.height }),
+                    ...(oversized && { limits: {
+                            max_size_bytes: MAX_HEATMAP_RESPONSE_BYTES,
+                            max_dimension: MAX_HEATMAP_DIMENSION,
+                            max_pixels: MAX_HEATMAP_PIXELS,
+                        } }),
+                    next_step: 'Open the original heatmap in Convert UI. MCP does not crop or resize heatmap images.',
+                    failure: failureAttribution({
+                        category: 'upstream',
+                        source: 'executor',
+                        stage: 'upstream_response',
+                        dispatchState: 'dispatched',
+                        code: error,
+                        upstreamStatus: response.status,
+                    }),
+                },
+            };
+        }
         if (media) {
             const metadata = {
                 status: response.status,
@@ -222,7 +289,9 @@ async function executeApiTool(toolName, definition, toolArgs, executionContext,
                         mime_type: media.mimeType,
                         encoding: 'base64',
                         size_bytes: media.sizeBytes,
+                        ...(media.width !== undefined && { width: media.width, height: media.height }),
                     },
+                    ...media.context,
                     binary_omitted_from_structured_content: true,
                 },
             };
@@ -237,6 +306,11 @@ async function executeApiTool(toolName, definition, toolArgs, executionContext,
                 structuredContent: metadata,
             };
         }
+        if (HEATMAP_RESPONSE_TOOLS.has(toolName)) {
+            const fallbackProblem = inspectHeatmapFallback(response.data);
+            if (fallbackProblem)
+                return heatmapFallbackRefusal(fallbackProblem, response.status);
+        }
         let responseText = '';
         const contentType = response.headers['content-type']?.toLowerCase() || '';
         const isJsonResponse = contentType.includes('application/json') && typeof response.data === 'object' && response.data !== null;
@@ -260,11 +334,19 @@ async function executeApiTool(toolName, definition, toolArgs, executionContext,
         else {
             responseText = `(Status: ${response.status} - No body content)`;
         }
+        const textResponse = `API Response (Status: ${response.status}):\n${responseText}`;
+        const structuredResponse = isJsonResponse
+            ? { status: response.status, data: responseData }
+            : { status: response.status };
+        if (HEATMAP_RESPONSE_TOOLS.has(toolName)
+            && new TextEncoder().encode(textResponse).length
+                + new TextEncoder().encode(JSON.stringify(structuredResponse)).length
+                > MAX_HEATMAP_FALLBACK_MODEL_BYTES) {
+            return heatmapFallbackRefusal('too_large', response.status);
+        }
         return {
-            content: [{ type: 'text', text: `API Response (Status: ${response.status}):\n${responseText}` }],
-            structuredContent: isJsonResponse
-                ? { status: response.status, data: responseData }
-                : { status: response.status },
+            content: [{ type: 'text', text: textResponse }],
+            structuredContent: structuredResponse,
         };
     }
     catch (error) {
@@ -302,6 +384,14 @@ async function executeApiTool(toolName, definition, toolArgs, executionContext,
                     code: 'ApprovalRequired',
                     status: 422,
                     approval_required: approvalRequired,
+                    failure: failureAttribution({
+                        category: 'permission',
+                        source: 'executor',
+                        stage: 'upstream_response',
+                        dispatchState: 'dispatched',
+                        code: 'ApprovalRequired',
+                        upstreamStatus: 422,
+                    }),
                 },
             };
         }
@@ -319,6 +409,8 @@ async function executeApiTool(toolName, definition, toolArgs, executionContext,
         else {
             errorMessage = `Unexpected error: ${String(error)}`;
         }
+        errorStatus ??= statusFromUploadError(error);
+        const failure = classifyExecutorFailure(error, errorStatus, dispatchState);
         errorMessage = scrubDiagnosticText(errorMessage);
         console.error(JSON.stringify({
             component: 'executor',
@@ -333,6 +425,7 @@ async function executeApiTool(toolName, definition, toolArgs, executionContext,
             structuredContent: {
                 error: errorMessage,
                 ...(typeof errorStatus === 'number' ? { status: errorStatus } : {}),
+                failure,
             },
         };
     }
@@ -505,24 +598,175 @@ function embeddedApiError(data) {
         || isPlainObject(data.errors);
     return hasErrorSignal ? { status: code } : null;
 }
+function looksLikeEncodedMedia(value, key) {
+    if (/^data:[^,]{1,100};base64,/i.test(value)
+        || /^(?:iVBORw0KGgo|\/9j\/|R0lGOD|UklGR)/.test(value))
+        return true;
+    return Boolean(key && /^(?:image|base64|data_?url|binary|blob)$/i.test(key)
+        && value.length >= 16 && /^[A-Za-z0-9+/_-]+={0,2}$/.test(value));
+}
+// Preflight the non-image heatmap fallback without serializing an unbounded
+// upstream object. The exact combined text + structuredContent size is checked
+// after this traversal, before either copy is returned to a model client.
+function inspectHeatmapFallback(value) {
+    const encoder = new TextEncoder();
+    const seen = new WeakSet();
+    const stack = [{ value }];
+    let bytes = 0;
+    let nodes = 0;
+    while (stack.length > 0) {
+        if (++nodes > 20_000)
+            return 'too_large';
+        const current = stack.pop();
+        const item = current.value;
+        if (typeof item === 'string') {
+            if (item.length > MAX_HEATMAP_FALLBACK_MODEL_BYTES)
+                return 'too_large';
+            if (looksLikeEncodedMedia(item, current.key))
+                return 'encoded_media';
+            bytes += encoder.encode(JSON.stringify(item)).length;
+        }
+        else if (item === null || typeof item === 'number' || typeof item === 'boolean') {
+            bytes += String(item).length;
+        }
+        else if (typeof item === 'undefined') {
+            bytes += 4;
+        }
+        else if (typeof item === 'object') {
+            if (ArrayBuffer.isView(item) || item instanceof ArrayBuffer)
+                return 'encoded_media';
+            if (seen.has(item))
+                return 'too_large';
+            seen.add(item);
+            if (Array.isArray(item)) {
+                if (item.length > 20_000)
+                    return 'too_large';
+                bytes += item.length + 2;
+                for (const entry of item)
+                    stack.push({ value: entry });
+            }
+            else if (isPlainObject(item)) {
+                bytes += 2;
+                for (const key in item) {
+                    if (!Object.hasOwn(item, key))
+                        continue;
+                    if (++nodes > 20_000)
+                        return 'too_large';
+                    if (key.length > MAX_HEATMAP_FALLBACK_MODEL_BYTES)
+                        return 'too_large';
+                    bytes += encoder.encode(JSON.stringify(key)).length + 2;
+                    if (bytes > MAX_HEATMAP_FALLBACK_MODEL_BYTES)
+                        return 'too_large';
+                    stack.push({ value: item[key], key });
+                }
+            }
+            else
+                return 'encoded_media';
+        }
+        else
+            return 'encoded_media';
+        if (bytes > MAX_HEATMAP_FALLBACK_MODEL_BYTES)
+            return 'too_large';
+    }
+    return null;
+}
+function heatmapFallbackRefusal(problem, upstreamStatus) {
+    const oversized = problem === 'too_large';
+    const error = oversized ? 'MediaResponseTooLarge' : 'UnexpectedMediaPayload';
+    const message = oversized
+        ? 'The heatmap response exceeds the MCP structured output budget. No response data was returned.'
+        : 'The heatmap response contains unexpected encoded media. No response data was returned.';
+    return {
+        isError: true,
+        content: [{ type: 'text', text: `${message} Open the original heatmap in Convert UI for inspection.` }],
+        structuredContent: {
+            error,
+            status: oversized ? 413 : 502,
+            upstream_status: upstreamStatus,
+            limit_combined_model_bytes: MAX_HEATMAP_FALLBACK_MODEL_BYTES,
+            next_step: 'Open the original heatmap in Convert UI. MCP does not crop or resize heatmap images.',
+            failure: failureAttribution({
+                category: 'upstream', source: 'executor', stage: 'upstream_response',
+                dispatchState: 'dispatched', code: error, upstreamStatus,
+            }),
+        },
+    };
+}
 function mediaResponse(toolName, response) {
     if (!MEDIA_RESPONSE_TOOLS.has(toolName))
         return null;
-    const candidate = isPlainObject(response.data) && typeof response.data.data === 'string'
+    const payload = isPlainObject(response.data) && isPlainObject(response.data.data)
         ? response.data.data
-        : (typeof response.data === 'string' ? response.data : null);
-    if (!candidate)
+        : null;
+    const heatmapField = toolName === 'getexperienceheatmapbackground'
+        ? 'background'
+        : toolName === 'getexperienceheatmapoverlay' ? 'overlay' : null;
+    const nestedCandidate = payload && heatmapField ? payload[heatmapField] : null;
+    const heatmapCandidate = nestedCandidate == null || typeof nestedCandidate === 'string'
+        ? nestedCandidate
+        : isPlainObject(nestedCandidate)
+            ? ('image' in nestedCandidate
+                ? (typeof nestedCandidate.image === 'string' ? nestedCandidate.image : 'invalid')
+                : ('url' in nestedCandidate ? 'invalid' : null))
+            : Array.isArray(nestedCandidate)
+                ? (nestedCandidate.length === 1 && isPlainObject(nestedCandidate[0]) && typeof nestedCandidate[0].image === 'string'
+                    ? nestedCandidate[0].image
+                    : (nestedCandidate.some((item) => isPlainObject(item) && 'image' in item) ? 'invalid' : null))
+                : 'invalid';
+    if (heatmapCandidate === 'invalid')
+        return { problem: 'invalid' };
+    const candidate = typeof heatmapCandidate === 'string'
+        ? heatmapCandidate
+        : isPlainObject(response.data) && typeof response.data.data === 'string'
+            ? response.data.data
+            : (typeof response.data === 'string' ? response.data : null);
+    if (candidate === null)
         return null;
+    if (!candidate.trim())
+        return { problem: 'invalid' };
+    if (heatmapField && candidate.length > Math.ceil(MAX_HEATMAP_RESPONSE_BYTES * 4 / 3) + 64) {
+        return { problem: 'budget_exceeded' };
+    }
     const parsedDataUrl = parseImageDataUrl(candidate);
     const data = parsedDataUrl?.data ?? candidate.trim();
     const headerMimeType = imageMimeTypeFromHeader(response.headers['content-type']);
-    const mimeType = parsedDataUrl?.mimeType ?? imageMimeTypeFromMagic(data) ?? headerMimeType;
-    if (!mimeType || !isBase64Payload(data))
-        return null;
+    const sizeBytes = base64DecodedSize(data);
+    if (heatmapField && sizeBytes > MAX_HEATMAP_RESPONSE_BYTES) {
+        return { problem: 'budget_exceeded', sizeBytes };
+    }
+    const signatureMimeType = imageMimeTypeFromMagic(data);
+    const mimeType = signatureMimeType;
+    if (!mimeType || !isBase64Payload(data)
+        || (parsedDataUrl && parsedDataUrl.mimeType !== mimeType)
+        || (heatmapField && headerMimeType && headerMimeType !== mimeType))
+        return { problem: 'invalid' };
+    const dimensions = heatmapField ? imageDimensionsFromBase64(data, mimeType) : null;
+    if (heatmapField && !dimensions)
+        return { problem: 'invalid', mimeType, sizeBytes };
+    if (dimensions && (dimensions.width > MAX_HEATMAP_DIMENSION
+        || dimensions.height > MAX_HEATMAP_DIMENSION
+        || dimensions.width * dimensions.height > MAX_HEATMAP_PIXELS)) {
+        return { problem: 'budget_exceeded', mimeType, sizeBytes, ...dimensions };
+    }
+    const heatmapId = payload?.heatmap_id;
+    const safeHeatmapId = typeof heatmapId === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(heatmapId)
+        ? heatmapId
+        : typeof heatmapId === 'number' && Number.isSafeInteger(heatmapId) && heatmapId > 0
+            ? String(heatmapId)
+            : undefined;
+    const context = payload && heatmapField
+        ? {
+            ...(safeHeatmapId && { heatmap_id: safeHeatmapId }),
+            ...((payload.device === 'desktop' || payload.device === 'tablet' || payload.device === 'mobile') && { device: payload.device }),
+            ...((payload.interaction === 'click' || payload.interaction === 'scroll' || payload.interaction === 'move') && { interaction: payload.interaction }),
+        }
+        : undefined;
     return {
         data,
         mimeType,
-        sizeBytes: base64DecodedSize(data),
+        sizeBytes,
+        ...(dimensions && dimensions),
+        context,
     };
 }
 function parseImageDataUrl(value) {
@@ -544,19 +788,29 @@ function imageMimeTypeFromMagic(data) {
         return 'image/jpeg';
     if (data.startsWith('R0lGOD'))
         return 'image/gif';
-    if (data.startsWith('UklGR'))
-        return 'image/webp';
+    if (data.startsWith('UklGR')) {
+        try {
+            const prefix = atob(data.slice(0, 16).replace(/-/g, '+').replace(/_/g, '/'));
+            if (prefix.startsWith('RIFF') && prefix.slice(8, 12) === 'WEBP')
+                return 'image/webp';
+        }
+        catch { /* An invalid base64 prefix is not an image signature. */ }
+    }
     return null;
 }
 function isBase64Payload(value) {
     if (value.length < 8 || value.length % 4 === 1)
         return false;
-    for (let index = 0; index < value.length; index += 1) {
+    const paddingIndex = value.indexOf('=');
+    if (paddingIndex >= 0 && (value.length % 4 !== 0 || !/^={1,2}$/.test(value.slice(paddingIndex))))
+        return false;
+    const payloadEnd = paddingIndex >= 0 ? paddingIndex : value.length;
+    for (let index = 0; index < payloadEnd; index += 1) {
         const code = value.charCodeAt(index);
         const isAlphaNumeric = (code >= 48 && code <= 57)
             || (code >= 65 && code <= 90)
             || (code >= 97 && code <= 122);
-        if (!isAlphaNumeric && code !== 43 && code !== 47 && code !== 95 && code !== 45 && code !== 61) {
+        if (!isAlphaNumeric && code !== 43 && code !== 47 && code !== 95 && code !== 45) {
             return false;
         }
     }