@wix/mcp 1.0.85 → 1.0.87

package/build/dts/toolkit.js

@@ -319,7 +319,7 @@ export function createWixToolkit(options) {
                     additionalFields = formatToolResultAdditionalFields(cbResult, {
                         returnedRows: toolBiParams.returnedRows,
                         originalLength: toolBiParams.originalLength
-                    });
+                    }, { name: clientName });
                 }
                 // Panorama: finish or report error
                 if (!isDevEnvironment) {

package/build/dts/wix-mcp-server.js

@@ -183,6 +183,9 @@ export class WixMcpServer extends McpServer {
                     additionalFields = formatToolResultAdditionalFields(cbResult, {
                         returnedRows: toolBiParams.returnedRows,
                         originalLength: toolBiParams.originalLength
+                    }, {
+                        name: this.getClientName?.() || this.server.getClientVersion()?.name,
+                        userAgent: this.getUserAgent?.()
                     });
                 }
                 if (toolSucceeded && !isDevEnvironment) {

package/build/esm/index.js

@@ -27117,6 +27117,14 @@ var EMPTY_COMPLETION_RESULT = {
 
 // src/tool-utils.ts
 var REST_METHOD_CONTRACT_RETRY_HINT = "Before retrying, make sure you have everything needed for a correct call: the right endpoint URL, HTTP method, request body shape, and response shape. Use the SearchWixRESTDocumentation tool or BrowseWixRESTDocsMenu tool to find the correct method or relevant related articles, the ReadFullDocsArticle tool to read the method description and all code examples, and the SearchWixAPISpec tool for precise field names and schema details.";
+var SINGLE_OPERATOR_PER_FIELD_HINT = 'WQL takes one operator per field object. Split the conditions into separate expressions under the matching logical operator \u2014 `{"$and": [{"field": {"$gte": ...}}, {"field": {"$lte": ...}}]}` \u2014 and retry without re-searching the docs.';
+var FIELD_CAPABILITIES_HINT = "This endpoint declares its filterable and sortable fields with their operators. Read the map with SearchWixAPISpec (`queryMethodData.queryFieldsCapabilitiesMap`, or `searchMethodData.searchFieldsCapabilitiesMap` on search methods) and use only what it lists; otherwise fetch a bounded page and filter or sort the results yourself.";
+var getRetryHint = (errorDetails) => {
+  if (!/Filter contains unsupported operator/i.test(errorDetails)) {
+    return REST_METHOD_CONTRACT_RETRY_HINT;
+  }
+  return /"operator":"\{/.test(errorDetails) ? SINGLE_OPERATOR_PER_FIELD_HINT : FIELD_CAPABILITIES_HINT;
+};
 var DEFAULT_OPENAI_SECURITY_SCHEMES = [
   { type: "oauth2", scopes: ["offline_access"] }
 ];
@@ -27143,7 +27151,7 @@ var buildErrorMessage = ({
   ].filter((str) => !!str).join("\n");
   return `${baseMessage}
 
-${REST_METHOD_CONTRACT_RETRY_HINT}`;
+${getRetryHint(String(errorDetails))}`;
 };
 var handleWixAPIResponse = async (response) => {
   const requestId = response.headers?.["x-wix-request-id"];
@@ -29740,7 +29748,25 @@ function extractText(result) {
   return result.content.filter((content) => content.type === "text" && content.text != null).map((content) => content.text).join("\n");
 }
 var TOOL_RESULT_PREVIEW_MAX_CHARS = 4e3;
-function formatToolResultAdditionalFields(result, extras) {
+var CODEX_OUTPUT_BUDGET_BYTES = 4e4;
+function getCodexTruncation(resultText, client) {
+  const isCodex = [client?.name, client?.userAgent].some(
+    (identity) => identity?.toLowerCase().includes("codex")
+  );
+  if (!isCodex) {
+    return void 0;
+  }
+  const resultBytes = new TextEncoder().encode(resultText).length;
+  if (resultBytes <= CODEX_OUTPUT_BUDGET_BYTES) {
+    return void 0;
+  }
+  return {
+    resultBytes,
+    budgetBytes: CODEX_OUTPUT_BUDGET_BYTES,
+    truncatedBytes: resultBytes - CODEX_OUTPUT_BUDGET_BYTES
+  };
+}
+function formatToolResultAdditionalFields(result, extras, client) {
   const resultText = extractText(result);
   const contentTypes = [
     ...new Set(
@@ -29757,6 +29783,7 @@ function formatToolResultAdditionalFields(result, extras) {
     resultTextLength: resultText.length,
     resultPreviewTruncated: resultText.length > TOOL_RESULT_PREVIEW_MAX_CHARS,
     resultContentTypes: contentTypes,
+    codexTruncation: getCodexTruncation(resultText, client),
     ...extras
   });
 }
@@ -29938,10 +29965,17 @@ var WixMcpServer = class extends McpServer {
         if (!toolSucceeded) {
           errorBody = extractText(cbResult);
         } else {
-          additionalFields = formatToolResultAdditionalFields(cbResult, {
-            returnedRows: toolBiParams.returnedRows,
-            originalLength: toolBiParams.originalLength
-          });
+          additionalFields = formatToolResultAdditionalFields(
+            cbResult,
+            {
+              returnedRows: toolBiParams.returnedRows,
+              originalLength: toolBiParams.originalLength
+            },
+            {
+              name: this.getClientName?.() || this.server.getClientVersion()?.name,
+              userAgent: this.getUserAgent?.()
+            }
+          );
         }
         if (toolSucceeded && !isDevEnvironment) {
           panorama.transaction(toolName).finish({ toolInvocationId });
@@ -30847,6 +30881,7 @@ function rethrowIfUnauthorized(error2) {
 
 // src/config/api-request-rules.ts
 var ARRAY_QUERY_PARAMS_RULE = "Repeat array query params once per value: `?fieldsets=URL&fieldsets=RICH_CONTENT`. Do NOT comma-join values (`fieldsets=URL,RICH_CONTENT`), do NOT leave a trailing comma, and do NOT use a value the method schema does not list, even if a sibling method accepts it (draft posts have no `SEO` fieldset).";
+var WQL_FILTER_RULE = "Query and search filters are written in WQL: each field takes a single operator, so combine conditions with the logical operators \u2014 `$and` and `$or` take an array of expressions, `$not` takes one, and they can nest.";
 
 // src/config/default-config.ts
 var AGENT_GOAL = dedent_default`
@@ -30947,7 +30982,7 @@ var SITE_CREATION_COPY = {
 var SITE_GUIDANCE = dedent_default`
   A new-site request has two things to settle: what the site is for, and how to build it. The how is AI generation vs. starting from a template, so naming templates, a template id or Wix Studio (Wix Studio is also the template side) already settles it.
 
-  One case skips all of this: the user ALREADY HAS the finished site as files — hand-written HTML/CSS/JS, a zip, or the export of an AI builder. There is nothing to build, so don't offer AI or templates and don't call any site-creation tool. Send them to https://www.wix.com/headless/drop?utm_campaign=mcp — they drag the files in and get a live Wix-hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
+  One case skips all of this: the user ALREADY HAS the finished site as files — hand-written HTML/CSS/JS, a zip, or the export of an AI builder. There is nothing to build, so don't offer AI or templates and don't call any site-creation tool. For a full agentic flow, read the recipe first and publish the files yourself: https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md — it walks you through creating the site and uploading the files end to end. If you can't follow it, or it doesn't apply (you can't reach the file bytes, or something fails), fall back to sending the user to https://www.wix.com/headless/drop?utm_campaign=mcp — they drag the files in and get a live Wix-hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
 
   Settle what the site is for first: its purpose, topic, business type, audience, or main visitor action. Naming a method is not a description of the site, and neither is the business or industry on its own.
   If you can't tell yet, ask the preferred question below and nothing else — one question, no creation-method question in the same reply, and no internal tool names.
@@ -31006,12 +31041,25 @@ var ACCOUNT_SITE_EXECUTE_SCOPE = dedent_default`
     siteId?: string;
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
     url: string;
+    // Plain object → JSON. A string is sent verbatim (set your own Content-Type,
+    // e.g. multipart/form-data). A Uint8Array/ArrayBuffer is sent as raw bytes
+    // for binary uploads (set your own Content-Type).
     body?: unknown;
     headers?: Record<string, string>;
+    // "base64" returns the response body as a base64 string (data), with
+    // encoding: "base64" on the result — use it for binary downloads (zip,
+    // image, pdf); decoding those as text corrupts them. Binary content types
+    // are returned as base64 automatically even without this. Decode, edit and
+    // re-upload binary WITHIN this script and return only a small summary. If you
+    // must return the bytes, return the wix.request response object itself (so
+    // encoding: "base64" is preserved and it isn't truncated); a bare base64
+    // string you return is treated as plain text and may be truncated.
+    responseType?: "base64";
   }
   interface WixResponse<T = unknown> {
     status: number;
     data: T;
+    encoding?: "base64";
     json(): Promise<T>;
   }
   declare const wix: {
@@ -31150,6 +31198,7 @@ function buildToolDescriptions(includeReadme, includeImageUploadGuidance = true)
     ReadFullDocsArticle: dedent_default`
     Fetches the full Wix docs article or method article with code examples for using the method.
     Docs articles looks like this: https://dev.wix.com/docs/... and they can either be general docs articles or method articles.
+    Take the URL from the user's message or an earlier tool result. To reach an article you have no URL for, search or browse the docs first.
     For REST docs, use the URL as-is. For SDK docs, the URL SHOULD include ?apiView=SDK.
     ${reminder}
   `,
@@ -31282,7 +31331,7 @@ function buildToolDescriptions(includeReadme, includeImageUploadGuidance = true)
   `,
     "import-claude-design-from-url": dedent_default`
     Import a design created in Claude's design tool into Wix. Takes the signed claudeusercontent.com URL Claude Design produces for its self-contained HTML bundle (all images, fonts, and styles inlined); any other host is rejected. Creates a live Wix-hosted site and returns its URL.
-    NOT for site files the user provides themselves (their own HTML/CSS/JS, a zip, another builder's export) — for those, don't call this tool: send the user to https://www.wix.com/headless/drop?utm_campaign=mcp, where they upload the files and get a live hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
+    NOT for site files the user provides themselves (their own HTML/CSS/JS, a zip, another builder's export) — for those, don't call this tool. For a full agentic flow, read the recipe and publish the files yourself: https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md — it covers creating the site and uploading the files end to end. If you can't follow it, or it doesn't apply, fall back to sending the user to https://www.wix.com/headless/drop?utm_campaign=mcp, where they upload the files and get a live hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
   `,
     RunWixCliCommand: dedent_default`
     Executes Wix CLI commands for Wix app development and management.
@@ -31709,7 +31758,7 @@ function buildToolDescriptions(includeReadme, includeImageUploadGuidance = true)
     CreateWixBusinessGuide: dedent_default`
     Provides comprehensive documentation for creating a new Wix business (site, app, etc.).
     Call this ONLY when the user explicitly asks for a headless site, a Wix Classic Editor site, or manual/advanced account/API-based site creation — these don't need the site's purpose first. For normal site-creation ${SITE_CREATION_COPY.normalCreationRoute.nonWidget}; for a specific template id, call \`CreateSiteFromTemplate\`.
-    Exception, even when the user says "headless": if they ALREADY HAVE the finished site as files (their own HTML/CSS/JS, a zip, an AI-builder export) and want those files hosted, don't call this tool — send them to https://www.wix.com/headless/drop?utm_campaign=mcp to upload the files and get a live hosted site (give that URL exactly, keeping the utm_campaign=mcp parameter). This guide's CLI flow is for BUILDING a headless frontend, not for hosting ready-made files.
+    Exception, even when the user says "headless": if they ALREADY HAVE the finished site as files (their own HTML/CSS/JS, a zip, an AI-builder export) and want those files hosted, don't call this tool. For a full agentic flow, read the recipe and publish the files yourself: https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md — it covers creating the site and uploading the files end to end. If you can't follow it, or it doesn't apply, fall back to sending the user to https://www.wix.com/headless/drop?utm_campaign=mcp to upload the files and get a live hosted site (give that URL exactly, keeping the utm_campaign=mcp parameter). This guide's CLI flow is for BUILDING a headless frontend, not for hosting ready-made files.
 
     ## What This Tool Contains
 
@@ -31996,6 +32045,22 @@ function renderApps(apps, knownApps) {
   }
   return lines.join("\n");
 }
+function sanitizeCustomAppName(raw) {
+  return raw.replace(/[\x00-\x1f\x7f]/g, " ").replace(/[`*_[\]|<>]/g, "").replace(/\s+/g, " ").trim().slice(0, 60);
+}
+function renderCustomAppsWithSkillsTools(apps) {
+  const relevant = apps.filter((a2) => a2.appId && (a2.hasSkills || a2.hasTools)).sort(
+    (a2, b2) => (a2.appName ?? a2.appId ?? "").localeCompare(b2.appName ?? b2.appId ?? "")
+  );
+  if (!relevant.length) return "";
+  const lines = [];
+  for (const app of relevant) {
+    const sanitizedName = app.appName ? sanitizeCustomAppName(app.appName) : "";
+    const name = sanitizedName || app.appId;
+    lines.push(`- \`${name}\` (ID: \`${app.appId}\`)`);
+  }
+  return lines.join("\n");
+}
 function renderProperties(props) {
   const sections = [];
   const regionalFormat = [];
@@ -32058,6 +32123,15 @@ function renderSite(site, index, knownApps) {
     lines.push("");
     lines.push(appsContent);
   }
+  const customAppsWithSkillsToolsContent = renderCustomAppsWithSkillsTools(
+    site.customApps ?? []
+  );
+  if (customAppsWithSkillsToolsContent) {
+    lines.push("");
+    lines.push("### Custom Apps with skills and tools");
+    lines.push("");
+    lines.push(customAppsWithSkillsToolsContent);
+  }
   lines.push("");
   lines.push("---");
   lines.push("");
@@ -32321,7 +32395,10 @@ var paramDescriptions = {
       ARRAY_QUERY_PARAMS_RULE
     ].join("\n"),
     method: "The HTTP method to use for the API call (e.g. GET, POST, PUT, DELETE)",
-    body: 'The request body as a JSON object or array with all the required fields and values, including nested objects. Pass the actual value (object or array), NOT a JSON string. YOU MUST NEVER MAKE UP A BODY - the body should be based on the conversation context, i.e from the user prompt OR got into the conversation context by the "ReadFullDocsArticle" tool OR by the "SearchWixAPISpec" tool OR by the "ReadFullDocsMethodSchema" tool - i.e based on the API docs, a relevant recipe you read (preferably), a code example you found in the docs, a schema you read etc.. YOU MUST NEVER ASSUME YOU KNOW WHAT THE BODY SCHEMA IS WITHOUT CONCRETE EXAMPLES OR SCHEMA DEFINITIONS FROM THE CONVERSATION CONTEXT. Prefer reading relevant recipes if you have them in context for understand the body schema for API calls.',
+    body: [
+      'The request body as a JSON object or array with all the required fields and values, including nested objects. Pass the actual value (object or array), NOT a JSON string. YOU MUST NEVER MAKE UP A BODY - the body should be based on the conversation context, i.e from the user prompt OR got into the conversation context by the "ReadFullDocsArticle" tool OR by the "SearchWixAPISpec" tool OR by the "ReadFullDocsMethodSchema" tool - i.e based on the API docs, a relevant recipe you read (preferably), a code example you found in the docs, a schema you read etc.. YOU MUST NEVER ASSUME YOU KNOW WHAT THE BODY SCHEMA IS WITHOUT CONCRETE EXAMPLES OR SCHEMA DEFINITIONS FROM THE CONVERSATION CONTEXT. Prefer reading relevant recipes if you have them in context for understand the body schema for API calls.',
+      WQL_FILTER_RULE
+    ].join("\n"),
     reason: "One sentence explaining the original user request and why you are calling this API to complete it.",
     sourceDocUrl: [
       "The URL of the documentation or recipe where you found this API endpoint.",
@@ -32645,15 +32722,17 @@ Failed to fetch content: ${errorMsg}`
       const baseContentsPromise = Promise.all(
         baseDocsWithoutRecipes.map(fetchDoc)
       );
-      const skillsContentPromise = getSkillsByPortal(httpClient6, {
+      const skillsContentPromise = skillsTags?.length ? getSkillsByPortal(httpClient6, {
         portalId: REST_PORTAL_ID,
         ...repo && { repo },
         ...commitHash && { commitHash },
-        ...skillsTags && skillsTags.length > 0 && { tags: skillsTags }
+        tags: skillsTags
       }).catch((err) => {
         console.error("[WixREADME] Failed to fetch skills by portal:", err);
         return null;
-      });
+      }) : fetchDoc({ action: "include", url: RECIPES_INDEX_URL }).then(
+        (doc) => doc?.text ?? null
+      );
       const filter = {};
       if (siteId) filter.siteId = siteId;
       else if (siteName) filter.siteName = siteName;
@@ -32860,7 +32939,9 @@ function getErrorMessage(error2) {
 }
 function shouldTryMenuFallbackForDocsRead(error2, articleUrl) {
   const message = getErrorMessage(error2);
-  if (!message.includes("404") || !articleUrl.includes("/api-reference/")) {
+  const { pathname } = new URL(articleUrl);
+  const isMenuFallbackUrl = articleUrl.includes("/api-reference/") || pathname.startsWith("/docs/velo");
+  if (!message.includes("404") || !isMenuFallbackUrl) {
     return false;
   }
   return !["This resource is deprecated", "No schema found"].some(
@@ -33513,7 +33594,7 @@ var addDocsTools = (server, allowedTools = [
                   content: [
                     {
                       type: "text",
-                      text: `Note: "${articleUrl}" is a documentation category, not an article. Showing its menu contents below. For category URLs, use BrowseWixRESTDocsMenu directly next time.
+                      text: `Note: "${articleUrl}" is not an article. Showing the closest documentation menu below; read the article you need from its links. For category URLs, use BrowseWixRESTDocsMenu directly next time.
 
 ${text}`
                     }
@@ -33605,7 +33686,7 @@ ${text}`
                   content: [
                     {
                       type: "text",
-                      text: `Note: "${articleUrl}" is a documentation category, not an article. Showing its menu contents below. For category URLs, use BrowseWixRESTDocsMenu directly next time.
+                      text: `Note: "${articleUrl}" is not an article. Showing the closest documentation menu below; read the article you need from its links. For category URLs, use BrowseWixRESTDocsMenu directly next time.
 
 ${text}`
                     }
@@ -45723,12 +45804,12 @@ function addImportClaudeDesignTool(server, authStrategy, options) {
         designUrl = new URL(args.url);
       } catch {
         return errorResult(
-          "Invalid design URL \u2014 this tool only accepts the claudeusercontent.com URL produced by Claude Design. For site files the user provided themselves, do not retry: send the user to https://www.wix.com/headless/drop?utm_campaign=mcp to upload them and get a live hosted site."
+          "Invalid design URL \u2014 this tool only accepts the claudeusercontent.com URL produced by Claude Design. For site files the user provided themselves, do not retry this tool. For a full agentic flow, read the recipe and publish the files yourself: https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md \u2014 it covers creating the site and uploading the files end to end. If you can't follow it, or it doesn't apply, send the user to https://www.wix.com/headless/drop?utm_campaign=mcp to upload them and get a live hosted site."
         );
       }
       if (designUrl.protocol !== "https:" || !designUrl.hostname.endsWith(CLAUDE_USER_CONTENT_HOST_SUFFIX)) {
         return errorResult(
-          "Invalid design URL \u2014 this tool only accepts the claudeusercontent.com URL produced by Claude Design. For site files the user provided themselves, do not retry: send the user to https://www.wix.com/headless/drop?utm_campaign=mcp to upload them and get a live hosted site."
+          "Invalid design URL \u2014 this tool only accepts the claudeusercontent.com URL produced by Claude Design. For site files the user provided themselves, do not retry this tool. For a full agentic flow, read the recipe and publish the files yourself: https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md \u2014 it covers creating the site and uploading the files end to end. If you can't follow it, or it doesn't apply, send the user to https://www.wix.com/headless/drop?utm_campaign=mcp to upload them and get a live hosted site."
         );
       }
       const accountHeaders = await authStrategy.getAccountAuthHeaders();
@@ -46783,12 +46864,31 @@ function formatExecuteResult(data, maxResponseSize, reportBi) {
   reportBi?.({
     originalLength: typeof data.result === "string" ? data.result.length : JSON.stringify(data.result)?.length
   });
+  const base64Text = base64PayloadText(data.result);
+  if (base64Text !== null) {
+    if (base64Text.length <= MAX_ALLOWED_RESPONSE_CHARS) {
+      return { content: [{ type: "text", text: base64Text }] };
+    }
+    const approxKb = Math.ceil(base64Text.length / 1024).toLocaleString();
+    const limitKb = Math.floor(
+      MAX_ALLOWED_RESPONSE_CHARS / 1024
+    ).toLocaleString();
+    return executeErrorResult(
+      `Binary (base64) result is ~${approxKb} KB, too large to return intact (limit ~${limitKb} KB); truncating it would corrupt the base64. Process the bytes inside your ExecuteWixAPI script \u2014 decode, edit, and re-upload in the same call \u2014 and return only a small summary.`
+    );
+  }
   return {
     content: [
       { type: "text", text: truncateResponse(data.result, maxResponseSize) }
     ]
   };
 }
+function base64PayloadText(result) {
+  if (result !== null && typeof result === "object" && result.encoding === "base64" && typeof result.data === "string") {
+    return JSON.stringify(result);
+  }
+  return null;
+}
 function addExecuteTool(server, options) {
   const {
     codeModeBaseUrl,
@@ -47160,10 +47260,14 @@ function createWixToolkit(options) {
         if (!toolSucceeded) {
           errorBody = extractText(cbResult);
         } else {
-          additionalFields = formatToolResultAdditionalFields(cbResult, {
-            returnedRows: toolBiParams.returnedRows,
-            originalLength: toolBiParams.originalLength
-          });
+          additionalFields = formatToolResultAdditionalFields(
+            cbResult,
+            {
+              returnedRows: toolBiParams.returnedRows,
+              originalLength: toolBiParams.originalLength
+            },
+            { name: clientName }
+          );
         }
         if (!isDevEnvironment) {
           if (toolSucceeded) {

package/build/esm/toolkit.js

@@ -12077,6 +12077,7 @@ function rethrowIfUnauthorized(error) {
 
 // src/config/api-request-rules.ts
 var ARRAY_QUERY_PARAMS_RULE = "Repeat array query params once per value: `?fieldsets=URL&fieldsets=RICH_CONTENT`. Do NOT comma-join values (`fieldsets=URL,RICH_CONTENT`), do NOT leave a trailing comma, and do NOT use a value the method schema does not list, even if a sibling method accepts it (draft posts have no `SEO` fieldset).";
+var WQL_FILTER_RULE = "Query and search filters are written in WQL: each field takes a single operator, so combine conditions with the logical operators \u2014 `$and` and `$or` take an array of expressions, `$not` takes one, and they can nest.";
 
 // src/config/default-config.ts
 var AGENT_GOAL = dedent_default`
@@ -12177,7 +12178,7 @@ var SITE_CREATION_COPY = {
 var SITE_GUIDANCE = dedent_default`
   A new-site request has two things to settle: what the site is for, and how to build it. The how is AI generation vs. starting from a template, so naming templates, a template id or Wix Studio (Wix Studio is also the template side) already settles it.
 
-  One case skips all of this: the user ALREADY HAS the finished site as files — hand-written HTML/CSS/JS, a zip, or the export of an AI builder. There is nothing to build, so don't offer AI or templates and don't call any site-creation tool. Send them to https://www.wix.com/headless/drop?utm_campaign=mcp — they drag the files in and get a live Wix-hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
+  One case skips all of this: the user ALREADY HAS the finished site as files — hand-written HTML/CSS/JS, a zip, or the export of an AI builder. There is nothing to build, so don't offer AI or templates and don't call any site-creation tool. For a full agentic flow, read the recipe first and publish the files yourself: https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md — it walks you through creating the site and uploading the files end to end. If you can't follow it, or it doesn't apply (you can't reach the file bytes, or something fails), fall back to sending the user to https://www.wix.com/headless/drop?utm_campaign=mcp — they drag the files in and get a live Wix-hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
 
   Settle what the site is for first: its purpose, topic, business type, audience, or main visitor action. Naming a method is not a description of the site, and neither is the business or industry on its own.
   If you can't tell yet, ask the preferred question below and nothing else — one question, no creation-method question in the same reply, and no internal tool names.
@@ -12236,12 +12237,25 @@ var ACCOUNT_SITE_EXECUTE_SCOPE = dedent_default`
     siteId?: string;
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
     url: string;
+    // Plain object → JSON. A string is sent verbatim (set your own Content-Type,
+    // e.g. multipart/form-data). A Uint8Array/ArrayBuffer is sent as raw bytes
+    // for binary uploads (set your own Content-Type).
     body?: unknown;
     headers?: Record<string, string>;
+    // "base64" returns the response body as a base64 string (data), with
+    // encoding: "base64" on the result — use it for binary downloads (zip,
+    // image, pdf); decoding those as text corrupts them. Binary content types
+    // are returned as base64 automatically even without this. Decode, edit and
+    // re-upload binary WITHIN this script and return only a small summary. If you
+    // must return the bytes, return the wix.request response object itself (so
+    // encoding: "base64" is preserved and it isn't truncated); a bare base64
+    // string you return is treated as plain text and may be truncated.
+    responseType?: "base64";
   }
   interface WixResponse<T = unknown> {
     status: number;
     data: T;
+    encoding?: "base64";
     json(): Promise<T>;
   }
   declare const wix: {
@@ -12380,6 +12394,7 @@ function buildToolDescriptions(includeReadme, includeImageUploadGuidance = true)
     ReadFullDocsArticle: dedent_default`
     Fetches the full Wix docs article or method article with code examples for using the method.
     Docs articles looks like this: https://dev.wix.com/docs/... and they can either be general docs articles or method articles.
+    Take the URL from the user's message or an earlier tool result. To reach an article you have no URL for, search or browse the docs first.
     For REST docs, use the URL as-is. For SDK docs, the URL SHOULD include ?apiView=SDK.
     ${reminder}
   `,
@@ -12512,7 +12527,7 @@ function buildToolDescriptions(includeReadme, includeImageUploadGuidance = true)
   `,
     "import-claude-design-from-url": dedent_default`
     Import a design created in Claude's design tool into Wix. Takes the signed claudeusercontent.com URL Claude Design produces for its self-contained HTML bundle (all images, fonts, and styles inlined); any other host is rejected. Creates a live Wix-hosted site and returns its URL.
-    NOT for site files the user provides themselves (their own HTML/CSS/JS, a zip, another builder's export) — for those, don't call this tool: send the user to https://www.wix.com/headless/drop?utm_campaign=mcp, where they upload the files and get a live hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
+    NOT for site files the user provides themselves (their own HTML/CSS/JS, a zip, another builder's export) — for those, don't call this tool. For a full agentic flow, read the recipe and publish the files yourself: https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md — it covers creating the site and uploading the files end to end. If you can't follow it, or it doesn't apply, fall back to sending the user to https://www.wix.com/headless/drop?utm_campaign=mcp, where they upload the files and get a live hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
   `,
     RunWixCliCommand: dedent_default`
     Executes Wix CLI commands for Wix app development and management.
@@ -12939,7 +12954,7 @@ function buildToolDescriptions(includeReadme, includeImageUploadGuidance = true)
     CreateWixBusinessGuide: dedent_default`
     Provides comprehensive documentation for creating a new Wix business (site, app, etc.).
     Call this ONLY when the user explicitly asks for a headless site, a Wix Classic Editor site, or manual/advanced account/API-based site creation — these don't need the site's purpose first. For normal site-creation ${SITE_CREATION_COPY.normalCreationRoute.nonWidget}; for a specific template id, call \`CreateSiteFromTemplate\`.
-    Exception, even when the user says "headless": if they ALREADY HAVE the finished site as files (their own HTML/CSS/JS, a zip, an AI-builder export) and want those files hosted, don't call this tool — send them to https://www.wix.com/headless/drop?utm_campaign=mcp to upload the files and get a live hosted site (give that URL exactly, keeping the utm_campaign=mcp parameter). This guide's CLI flow is for BUILDING a headless frontend, not for hosting ready-made files.
+    Exception, even when the user says "headless": if they ALREADY HAVE the finished site as files (their own HTML/CSS/JS, a zip, an AI-builder export) and want those files hosted, don't call this tool. For a full agentic flow, read the recipe and publish the files yourself: https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md — it covers creating the site and uploading the files end to end. If you can't follow it, or it doesn't apply, fall back to sending the user to https://www.wix.com/headless/drop?utm_campaign=mcp to upload the files and get a live hosted site (give that URL exactly, keeping the utm_campaign=mcp parameter). This guide's CLI flow is for BUILDING a headless frontend, not for hosting ready-made files.
 
     ## What This Tool Contains
 
@@ -13226,6 +13241,22 @@ function renderApps(apps, knownApps) {
   }
   return lines.join("\n");
 }
+function sanitizeCustomAppName(raw) {
+  return raw.replace(/[\x00-\x1f\x7f]/g, " ").replace(/[`*_[\]|<>]/g, "").replace(/\s+/g, " ").trim().slice(0, 60);
+}
+function renderCustomAppsWithSkillsTools(apps) {
+  const relevant = apps.filter((a) => a.appId && (a.hasSkills || a.hasTools)).sort(
+    (a, b) => (a.appName ?? a.appId ?? "").localeCompare(b.appName ?? b.appId ?? "")
+  );
+  if (!relevant.length) return "";
+  const lines = [];
+  for (const app of relevant) {
+    const sanitizedName = app.appName ? sanitizeCustomAppName(app.appName) : "";
+    const name = sanitizedName || app.appId;
+    lines.push(`- \`${name}\` (ID: \`${app.appId}\`)`);
+  }
+  return lines.join("\n");
+}
 function renderProperties(props) {
   const sections = [];
   const regionalFormat = [];
@@ -13288,6 +13319,15 @@ function renderSite(site, index, knownApps) {
     lines.push("");
     lines.push(appsContent);
   }
+  const customAppsWithSkillsToolsContent = renderCustomAppsWithSkillsTools(
+    site.customApps ?? []
+  );
+  if (customAppsWithSkillsToolsContent) {
+    lines.push("");
+    lines.push("### Custom Apps with skills and tools");
+    lines.push("");
+    lines.push(customAppsWithSkillsToolsContent);
+  }
   lines.push("");
   lines.push("---");
   lines.push("");
@@ -13551,7 +13591,10 @@ var paramDescriptions = {
       ARRAY_QUERY_PARAMS_RULE
     ].join("\n"),
     method: "The HTTP method to use for the API call (e.g. GET, POST, PUT, DELETE)",
-    body: 'The request body as a JSON object or array with all the required fields and values, including nested objects. Pass the actual value (object or array), NOT a JSON string. YOU MUST NEVER MAKE UP A BODY - the body should be based on the conversation context, i.e from the user prompt OR got into the conversation context by the "ReadFullDocsArticle" tool OR by the "SearchWixAPISpec" tool OR by the "ReadFullDocsMethodSchema" tool - i.e based on the API docs, a relevant recipe you read (preferably), a code example you found in the docs, a schema you read etc.. YOU MUST NEVER ASSUME YOU KNOW WHAT THE BODY SCHEMA IS WITHOUT CONCRETE EXAMPLES OR SCHEMA DEFINITIONS FROM THE CONVERSATION CONTEXT. Prefer reading relevant recipes if you have them in context for understand the body schema for API calls.',
+    body: [
+      'The request body as a JSON object or array with all the required fields and values, including nested objects. Pass the actual value (object or array), NOT a JSON string. YOU MUST NEVER MAKE UP A BODY - the body should be based on the conversation context, i.e from the user prompt OR got into the conversation context by the "ReadFullDocsArticle" tool OR by the "SearchWixAPISpec" tool OR by the "ReadFullDocsMethodSchema" tool - i.e based on the API docs, a relevant recipe you read (preferably), a code example you found in the docs, a schema you read etc.. YOU MUST NEVER ASSUME YOU KNOW WHAT THE BODY SCHEMA IS WITHOUT CONCRETE EXAMPLES OR SCHEMA DEFINITIONS FROM THE CONVERSATION CONTEXT. Prefer reading relevant recipes if you have them in context for understand the body schema for API calls.',
+      WQL_FILTER_RULE
+    ].join("\n"),
     reason: "One sentence explaining the original user request and why you are calling this API to complete it.",
     sourceDocUrl: [
       "The URL of the documentation or recipe where you found this API endpoint.",
@@ -13875,15 +13918,17 @@ Failed to fetch content: ${errorMsg}`
       const baseContentsPromise = Promise.all(
         baseDocsWithoutRecipes.map(fetchDoc)
       );
-      const skillsContentPromise = getSkillsByPortal(httpClient, {
+      const skillsContentPromise = skillsTags?.length ? getSkillsByPortal(httpClient, {
         portalId: REST_PORTAL_ID,
         ...repo && { repo },
         ...commitHash && { commitHash },
-        ...skillsTags && skillsTags.length > 0 && { tags: skillsTags }
+        tags: skillsTags
       }).catch((err) => {
         console.error("[WixREADME] Failed to fetch skills by portal:", err);
         return null;
-      });
+      }) : fetchDoc({ action: "include", url: RECIPES_INDEX_URL }).then(
+        (doc) => doc?.text ?? null
+      );
       const filter = {};
       if (siteId) filter.siteId = siteId;
       else if (siteName) filter.siteName = siteName;
@@ -14079,7 +14124,9 @@ function getErrorMessage(error) {
 }
 function shouldTryMenuFallbackForDocsRead(error, articleUrl) {
   const message = getErrorMessage(error);
-  if (!message.includes("404") || !articleUrl.includes("/api-reference/")) {
+  const { pathname } = new URL(articleUrl);
+  const isMenuFallbackUrl = articleUrl.includes("/api-reference/") || pathname.startsWith("/docs/velo");
+  if (!message.includes("404") || !isMenuFallbackUrl) {
     return false;
   }
   return !["This resource is deprecated", "No schema found"].some(
@@ -14732,7 +14779,7 @@ var addDocsTools = (server, allowedTools = [
                   content: [
                     {
                       type: "text",
-                      text: `Note: "${articleUrl}" is a documentation category, not an article. Showing its menu contents below. For category URLs, use BrowseWixRESTDocsMenu directly next time.
+                      text: `Note: "${articleUrl}" is not an article. Showing the closest documentation menu below; read the article you need from its links. For category URLs, use BrowseWixRESTDocsMenu directly next time.
 
 ${text}`
                     }
@@ -14824,7 +14871,7 @@ ${text}`
                   content: [
                     {
                       type: "text",
-                      text: `Note: "${articleUrl}" is a documentation category, not an article. Showing its menu contents below. For category URLs, use BrowseWixRESTDocsMenu directly next time.
+                      text: `Note: "${articleUrl}" is not an article. Showing the closest documentation menu below; read the article you need from its links. For category URLs, use BrowseWixRESTDocsMenu directly next time.
 
 ${text}`
                     }
@@ -14917,6 +14964,14 @@ ${text}`
 
 // src/tool-utils.ts
 var REST_METHOD_CONTRACT_RETRY_HINT = "Before retrying, make sure you have everything needed for a correct call: the right endpoint URL, HTTP method, request body shape, and response shape. Use the SearchWixRESTDocumentation tool or BrowseWixRESTDocsMenu tool to find the correct method or relevant related articles, the ReadFullDocsArticle tool to read the method description and all code examples, and the SearchWixAPISpec tool for precise field names and schema details.";
+var SINGLE_OPERATOR_PER_FIELD_HINT = 'WQL takes one operator per field object. Split the conditions into separate expressions under the matching logical operator \u2014 `{"$and": [{"field": {"$gte": ...}}, {"field": {"$lte": ...}}]}` \u2014 and retry without re-searching the docs.';
+var FIELD_CAPABILITIES_HINT = "This endpoint declares its filterable and sortable fields with their operators. Read the map with SearchWixAPISpec (`queryMethodData.queryFieldsCapabilitiesMap`, or `searchMethodData.searchFieldsCapabilitiesMap` on search methods) and use only what it lists; otherwise fetch a bounded page and filter or sort the results yourself.";
+var getRetryHint = (errorDetails) => {
+  if (!/Filter contains unsupported operator/i.test(errorDetails)) {
+    return REST_METHOD_CONTRACT_RETRY_HINT;
+  }
+  return /"operator":"\{/.test(errorDetails) ? SINGLE_OPERATOR_PER_FIELD_HINT : FIELD_CAPABILITIES_HINT;
+};
 var safeParseJSON = (text) => {
   try {
     return JSON.parse(text);
@@ -14940,7 +14995,7 @@ var buildErrorMessage = ({
   ].filter((str) => !!str).join("\n");
   return `${baseMessage}
 
-${REST_METHOD_CONTRACT_RETRY_HINT}`;
+${getRetryHint(String(errorDetails))}`;
 };
 var handleWixAPIResponse = async (response) => {
   const requestId = response.headers?.["x-wix-request-id"];
@@ -16607,12 +16662,31 @@ function formatExecuteResult(data, maxResponseSize, reportBi) {
   reportBi?.({
     originalLength: typeof data.result === "string" ? data.result.length : JSON.stringify(data.result)?.length
   });
+  const base64Text = base64PayloadText(data.result);
+  if (base64Text !== null) {
+    if (base64Text.length <= MAX_ALLOWED_RESPONSE_CHARS) {
+      return { content: [{ type: "text", text: base64Text }] };
+    }
+    const approxKb = Math.ceil(base64Text.length / 1024).toLocaleString();
+    const limitKb = Math.floor(
+      MAX_ALLOWED_RESPONSE_CHARS / 1024
+    ).toLocaleString();
+    return executeErrorResult(
+      `Binary (base64) result is ~${approxKb} KB, too large to return intact (limit ~${limitKb} KB); truncating it would corrupt the base64. Process the bytes inside your ExecuteWixAPI script \u2014 decode, edit, and re-upload in the same call \u2014 and return only a small summary.`
+    );
+  }
   return {
     content: [
       { type: "text", text: truncateResponse(data.result, maxResponseSize) }
     ]
   };
 }
+function base64PayloadText(result) {
+  if (result !== null && typeof result === "object" && result.encoding === "base64" && typeof result.data === "string") {
+    return JSON.stringify(result);
+  }
+  return null;
+}
 function addExecuteTool(server, options) {
   const {
     codeModeBaseUrl,
@@ -18566,7 +18640,25 @@ function extractText(result) {
   return result.content.filter((content) => content.type === "text" && content.text != null).map((content) => content.text).join("\n");
 }
 var TOOL_RESULT_PREVIEW_MAX_CHARS = 4e3;
-function formatToolResultAdditionalFields(result, extras) {
+var CODEX_OUTPUT_BUDGET_BYTES = 4e4;
+function getCodexTruncation(resultText, client) {
+  const isCodex = [client?.name, client?.userAgent].some(
+    (identity) => identity?.toLowerCase().includes("codex")
+  );
+  if (!isCodex) {
+    return void 0;
+  }
+  const resultBytes = new TextEncoder().encode(resultText).length;
+  if (resultBytes <= CODEX_OUTPUT_BUDGET_BYTES) {
+    return void 0;
+  }
+  return {
+    resultBytes,
+    budgetBytes: CODEX_OUTPUT_BUDGET_BYTES,
+    truncatedBytes: resultBytes - CODEX_OUTPUT_BUDGET_BYTES
+  };
+}
+function formatToolResultAdditionalFields(result, extras, client) {
   const resultText = extractText(result);
   const contentTypes = [
     ...new Set(
@@ -18583,6 +18675,7 @@ function formatToolResultAdditionalFields(result, extras) {
     resultTextLength: resultText.length,
     resultPreviewTruncated: resultText.length > TOOL_RESULT_PREVIEW_MAX_CHARS,
     resultContentTypes: contentTypes,
+    codexTruncation: getCodexTruncation(resultText, client),
     ...extras
   });
 }
@@ -18838,10 +18931,14 @@ function createWixToolkit(options) {
         if (!toolSucceeded) {
           errorBody = extractText(cbResult);
         } else {
-          additionalFields = formatToolResultAdditionalFields(cbResult, {
-            returnedRows: toolBiParams.returnedRows,
-            originalLength: toolBiParams.originalLength
-          });
+          additionalFields = formatToolResultAdditionalFields(
+            cbResult,
+            {
+              returnedRows: toolBiParams.returnedRows,
+              originalLength: toolBiParams.originalLength
+            },
+            { name: clientName }
+          );
         }
         if (!isDevEnvironment) {
           if (toolSucceeded) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/mcp",
-  "version": "1.0.85",
+  "version": "1.0.87",
   "description": "A Model Context Protocol server for Wix AI tools",
   "bin": "./build/bin-standalone.js",
   "dependencies": {
@@ -43,7 +43,7 @@
     "@wix/bi-logger-wix-code-data": "^1.485.0",
     "@wix/common-widget-types": "^1.77.0",
     "@wix/design-system": "^1.256.2",
-    "@wix/dynamic-context-enricher": "0.1.3",
+    "@wix/dynamic-context-enricher": "0.1.4",
     "@wix/http-client": "^2.85.0",
     "@wix/panorama-client-node": "^3.253.0",
     "@wix/standalone-node-bi-logger": "^1.7.24",
@@ -133,5 +133,5 @@
       ]
     }
   },
-  "falconPackageHash": "fa4f66edf0696bfeabc3430c4fc334d1b036704c758c5d5c65aa2b60"
+  "falconPackageHash": "c9087b06450361359889e6ef0ea5562b59ca3f0ea641de700d905ce2"
 }