@wix/mcp 1.0.86 → 1.0.88

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"];
@@ -30873,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`
@@ -30973,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.
@@ -31032,18 +31041,56 @@ 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: {
     request<T = unknown>(options: WixRequestOptions): Promise<WixResponse<T>>;
+    // Build a multipart/form-data body from files (defaults to the \`files\`
+    // global). Each file becomes a part named fieldName (default "files") with
+    // its path as the filename. Pass body + contentType to wix.request.
+    multipart(
+      files?: Array<{ path: string; content: string; contentType?: string }>,
+      options?: { fieldName?: string }
+    ): { body: string; contentType: string };
   };
   declare const siteId: string | undefined;
+  // Files from the ExecuteWixAPI \`files\` param (raw content, no escaping).
+  declare const files: Array<{ path: string; content: string }>;
+  \`\`\`
+
+  FILE UPLOADS: pass file bodies via the \`files\` param (not inside \`code\` — no escaping), then build the multipart body with \`wix.multipart()\`:
+  \`\`\`javascript
+  // files param: "=== FILE: index.html ===\\n<!doctype html>...\\n=== FILE: app.js ===\\nconsole.log(1)"
+  async () => {
+    const mp = wix.multipart(); // parts named "files", filename = each path
+    const res = await wix.request({
+      scope: "account",
+      method: "POST",
+      url: "https://www.wixapis.com/.../upload",
+      headers: { "Content-Type": mp.contentType },
+      body: mp.body
+    });
+    return res.data;
+  }
   \`\`\`
 `;
 var EXECUTE_WIX_API_WQL = dedent_default`
@@ -31176,6 +31223,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}
   `,
@@ -31308,7 +31356,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.
@@ -31735,7 +31783,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
 
@@ -32372,7 +32420,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.",
@@ -32696,15 +32747,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;
@@ -45776,12 +45829,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();
@@ -46836,12 +46889,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,
@@ -46873,6 +46945,14 @@ function addExecuteTool(server, options) {
         visitor ? "Whether this code creates, updates, deletes, publishes, imports, uploads, or otherwise mutates site data on the visitor\u2019s behalf. Set this to true for create/update/delete/bulk create/import/upload calls even if the reason is inspection, verification, or response-shape discovery. Read-only GET/query/list/search calls can use false." : "Whether this code creates, updates, deletes, publishes, installs, imports, uploads, or otherwise mutates Wix data or site/account state. Set this to true for create/update/delete/bulk create/import/upload calls even if the reason is inspection, verification, or response-shape discovery. Read-only GET/query/list/search calls can use false."
       ),
       sourceDocUrls: external_exports.array(external_exports.string()).describe(d2.sourceDocUrls),
+      files: external_exports.string().optional().describe(
+        [
+          "Optional bundle of raw file contents for uploads, so file bytes never go through the `code` JavaScript (no escaping, no string-literal/`${}`/backtick pitfalls).",
+          "Format: one or more sections, each a line `=== FILE: <path> ===` on its own, followed by that file's raw text content; `<path>` is the path relative to the site root (e.g. `index.html`, `assets/app.js`). Example: `=== FILE: index.html ===\\n<!doctype html>...\\n=== FILE: assets/app.js ===\\nconsole.log(1)`.",
+          'In `code`, the parsed files are the `files` global (array of `{ path, content }`), and `wix.multipart(files)` returns `{ body, contentType }` for a `multipart/form-data` upload \u2014 e.g. `const mp = wix.multipart(); await wix.request({ scope: "account", method: "POST", url, headers: { "Content-Type": mp.contentType }, body: mp.body });`.',
+          "Text files only; for binary assets pass bytes as a base64 request body instead. A file whose content itself contains a line exactly like the delimiter is not supported."
+        ].join(" ")
+      ),
       // Visitor mode takes an agent-supplied token and pins the site; account/site
       // mode lets the agent pick the site.
       ...visitor ? {
@@ -46887,7 +46967,7 @@ function addExecuteTool(server, options) {
     },
     { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
     async (rawArgs, extra) => {
-      const { code, reason, hasMutations, sourceDocUrls, visitorToken } = rawArgs;
+      const { code, reason, hasMutations, sourceDocUrls, visitorToken, files } = rawArgs;
       const siteId = visitor ? visitor.siteId : rawArgs.siteId;
       logger2.log(
         `[ExecuteWixAPI]${visitor ? " (visitor)" : ""} Executing code (${code.length} chars), siteId=${siteId ?? "none"}, hasMutations=${hasMutations}, sourceDocUrls=${JSON.stringify(sourceDocUrls)}, reason="${reason}"`
@@ -46932,7 +47012,8 @@ function addExecuteTool(server, options) {
             siteToken: visitor ? visitorToken : siteHeaders?.Authorization,
             accountToken: visitor ? visitorToken : accountHeaders?.Authorization,
             accountId: accountHeaders?.["wix-account-id"],
-            siteAuthContext
+            siteAuthContext,
+            ...files ? { files } : {}
           },
           visitor ? visitorToken : accountHeaders?.Authorization ?? siteHeaders?.Authorization,
           codeModeFetch

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,18 +12237,56 @@ 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: {
     request<T = unknown>(options: WixRequestOptions): Promise<WixResponse<T>>;
+    // Build a multipart/form-data body from files (defaults to the \`files\`
+    // global). Each file becomes a part named fieldName (default "files") with
+    // its path as the filename. Pass body + contentType to wix.request.
+    multipart(
+      files?: Array<{ path: string; content: string; contentType?: string }>,
+      options?: { fieldName?: string }
+    ): { body: string; contentType: string };
   };
   declare const siteId: string | undefined;
+  // Files from the ExecuteWixAPI \`files\` param (raw content, no escaping).
+  declare const files: Array<{ path: string; content: string }>;
+  \`\`\`
+
+  FILE UPLOADS: pass file bodies via the \`files\` param (not inside \`code\` — no escaping), then build the multipart body with \`wix.multipart()\`:
+  \`\`\`javascript
+  // files param: "=== FILE: index.html ===\\n<!doctype html>...\\n=== FILE: app.js ===\\nconsole.log(1)"
+  async () => {
+    const mp = wix.multipart(); // parts named "files", filename = each path
+    const res = await wix.request({
+      scope: "account",
+      method: "POST",
+      url: "https://www.wixapis.com/.../upload",
+      headers: { "Content-Type": mp.contentType },
+      body: mp.body
+    });
+    return res.data;
+  }
   \`\`\`
 `;
 var EXECUTE_WIX_API_WQL = dedent_default`
@@ -12380,6 +12419,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 +12552,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 +12979,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
 
@@ -13576,7 +13616,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.",
@@ -13900,15 +13943,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;
@@ -14944,6 +14989,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);
@@ -14967,7 +15020,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"];
@@ -16634,12 +16687,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,
@@ -16671,6 +16743,14 @@ function addExecuteTool(server, options) {
         visitor ? "Whether this code creates, updates, deletes, publishes, imports, uploads, or otherwise mutates site data on the visitor\u2019s behalf. Set this to true for create/update/delete/bulk create/import/upload calls even if the reason is inspection, verification, or response-shape discovery. Read-only GET/query/list/search calls can use false." : "Whether this code creates, updates, deletes, publishes, installs, imports, uploads, or otherwise mutates Wix data or site/account state. Set this to true for create/update/delete/bulk create/import/upload calls even if the reason is inspection, verification, or response-shape discovery. Read-only GET/query/list/search calls can use false."
       ),
       sourceDocUrls: external_exports.array(external_exports.string()).describe(d.sourceDocUrls),
+      files: external_exports.string().optional().describe(
+        [
+          "Optional bundle of raw file contents for uploads, so file bytes never go through the `code` JavaScript (no escaping, no string-literal/`${}`/backtick pitfalls).",
+          "Format: one or more sections, each a line `=== FILE: <path> ===` on its own, followed by that file's raw text content; `<path>` is the path relative to the site root (e.g. `index.html`, `assets/app.js`). Example: `=== FILE: index.html ===\\n<!doctype html>...\\n=== FILE: assets/app.js ===\\nconsole.log(1)`.",
+          'In `code`, the parsed files are the `files` global (array of `{ path, content }`), and `wix.multipart(files)` returns `{ body, contentType }` for a `multipart/form-data` upload \u2014 e.g. `const mp = wix.multipart(); await wix.request({ scope: "account", method: "POST", url, headers: { "Content-Type": mp.contentType }, body: mp.body });`.',
+          "Text files only; for binary assets pass bytes as a base64 request body instead. A file whose content itself contains a line exactly like the delimiter is not supported."
+        ].join(" ")
+      ),
       // Visitor mode takes an agent-supplied token and pins the site; account/site
       // mode lets the agent pick the site.
       ...visitor ? {
@@ -16685,7 +16765,7 @@ function addExecuteTool(server, options) {
     },
     { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
     async (rawArgs, extra) => {
-      const { code, reason, hasMutations, sourceDocUrls, visitorToken } = rawArgs;
+      const { code, reason, hasMutations, sourceDocUrls, visitorToken, files } = rawArgs;
       const siteId = visitor ? visitor.siteId : rawArgs.siteId;
       logger.log(
         `[ExecuteWixAPI]${visitor ? " (visitor)" : ""} Executing code (${code.length} chars), siteId=${siteId ?? "none"}, hasMutations=${hasMutations}, sourceDocUrls=${JSON.stringify(sourceDocUrls)}, reason="${reason}"`
@@ -16730,7 +16810,8 @@ function addExecuteTool(server, options) {
             siteToken: visitor ? visitorToken : siteHeaders?.Authorization,
             accountToken: visitor ? visitorToken : accountHeaders?.Authorization,
             accountId: accountHeaders?.["wix-account-id"],
-            siteAuthContext
+            siteAuthContext,
+            ...files ? { files } : {}
           },
           visitor ? visitorToken : accountHeaders?.Authorization ?? siteHeaders?.Authorization,
           codeModeFetch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/mcp",
-  "version": "1.0.86",
+  "version": "1.0.88",
   "description": "A Model Context Protocol server for Wix AI tools",
   "bin": "./build/bin-standalone.js",
   "dependencies": {
@@ -133,5 +133,5 @@
       ]
     }
   },
-  "falconPackageHash": "bfa0ad2bd45ba9e54844e736741354d379ec2790f92872287c5fc1d2"
+  "falconPackageHash": "ca9fecd4d1efd1afea0d159f209aea15cf9475c2edec6f5a172bd92f"
 }