@wix/mcp 1.0.91 → 1.0.93

package/build/dts/code-mode/attachments.js

@@ -0,0 +1,218 @@
+/**
+ * ChatGPT file attachments for ExecuteWixAPI (`openai/fileParams`).
+ *
+ * ChatGPT resolves a file the user attached — or one the model wrote in its
+ * own sandbox — into `{ download_url, file_id, file_name?, mime_type? }` for a
+ * param the tool lists under `_meta["openai/fileParams"]`. The bytes never go
+ * through the model. We fetch each `download_url` host-side and hand the
+ * runtime ready-made base64 file entries, the same shape the `files` bundle
+ * parses into, so `files`, `wix.multipart()` and `wix.unzip()` are unchanged.
+ *
+ * This is additive: clients without the extension never populate the param
+ * and keep using the `files` bundle (text + base64 sections).
+ */
+// Per call, across all attachments. The base64 (~4/3 of this) is embedded in
+// the generated sandbox module next to the `files` bundle, and both the host
+// Worker and the sandbox isolate hold it alongside the decoded bytes and the
+// multipart body within a 128 MB isolate — 10 MB keeps the whole chain well
+// inside that. A site zip or a handful of images fits.
+export const MAX_ATTACHMENTS_BYTES = 10 * 1024 * 1024;
+// Follow at most this many redirects, revalidating the host at every hop.
+const MAX_REDIRECTS = 4;
+// Hosts ChatGPT hands out in `download_url` (every host seen in
+// UploadImageToWixSite download_urls, 2026-08-01..10-08). Two families:
+// - `<label>.oaiusercontent.com`: an OpenAI-owned domain, so any one-label
+//   subdomain is OpenAI's (observed: sdmntpr<region>, files).
+// - Azure blob accounts behind them, one per OpenAI region.
+//   `blob.core.windows.net` is a shared namespace, so these are exact — a
+//   prefix could be registered by anyone. A new region shows up as an
+//   "is not a ChatGPT file host" error in BI; add it here.
+const OAI_USERCONTENT_HOST = /^[a-z0-9-]+\.oaiusercontent\.com$/;
+const OAI_BLOB_ACCOUNTS = new Set([
+    'australiaeast',
+    'brazilsouth',
+    'cacentral',
+    'centralindia',
+    'centralus',
+    'centralusdr',
+    'denmarkeast',
+    'eastus',
+    'eastus2',
+    'indiasocentral',
+    'italynorth',
+    'japaneast',
+    'koreacentral',
+    'northcentralus',
+    'northeu',
+    'nznorth',
+    'polandcentral',
+    'seasia',
+    'southcentralus',
+    'southeastus3',
+    'ukwest',
+    'westcentralus',
+    'westus',
+    'westus2',
+    'westus3'
+].map((region) => `oaisdmntpr${region}.blob.core.windows.net`));
+export function isAllowedAttachmentHost(hostname) {
+    const h = hostname.toLowerCase();
+    return OAI_USERCONTENT_HOST.test(h) || OAI_BLOB_ACCOUNTS.has(h);
+}
+/** https, default port, allowed host — applied to the first URL and every redirect. */
+function checkAttachmentUrl(url) {
+    if (url.protocol !== 'https:')
+        return 'is not an https URL';
+    if (url.port)
+        return 'uses a non-default port';
+    if (!isAllowedAttachmentHost(url.hostname)) {
+        return `host "${url.hostname}" is not a ChatGPT file host`;
+    }
+    return undefined;
+}
+export class AttachmentError extends Error {
+}
+/** Path inside the upload: the file name, else the URL's last segment, else the id. */
+function attachmentPath(a, url) {
+    let fromUrl = '';
+    try {
+        fromUrl = decodeURIComponent(url.pathname.split('/').filter(Boolean).pop() ?? '');
+    }
+    catch {
+        fromUrl = '';
+    }
+    const raw = (a.file_name?.trim() || fromUrl || a.file_id).replace(/\\/g, '/');
+    // Relative, no traversal, no empty segments.
+    const segments = raw.split('/').filter((s) => s && s !== '.' && s !== '..');
+    return segments.join('/') || a.file_id;
+}
+function toBase64(bytes) {
+    let binary = '';
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(binary);
+}
+/**
+ * GET with manual redirects: every hop must pass checkAttachmentUrl, so an
+ * allowed host cannot bounce the server to an arbitrary or internal one.
+ */
+async function fetchAllowed(start, fetchImpl, label) {
+    let url = start;
+    for (let hop = 0;; hop++) {
+        const res = await fetchImpl(url.toString(), { redirect: 'manual' });
+        const location = res.headers.get('location');
+        const isRedirect = res.status >= 300 && res.status < 400 && location;
+        if (!isRedirect)
+            return res;
+        await res.body?.cancel().catch(() => undefined);
+        if (hop >= MAX_REDIRECTS) {
+            throw new AttachmentError(`${label}: too many redirects.`);
+        }
+        let next;
+        try {
+            next = new URL(location, url);
+        }
+        catch {
+            throw new AttachmentError(`${label}: redirect to an invalid URL.`);
+        }
+        const problem = checkAttachmentUrl(next);
+        if (problem) {
+            throw new AttachmentError(`${label}: the download redirected to a URL that ${problem}; refused.`);
+        }
+        url = next;
+    }
+}
+/**
+ * Read a body while counting bytes against `budget`; stops reading (and
+ * cancels the stream) as soon as it is exceeded, instead of buffering first.
+ */
+async function readWithin(res, budget, overBudget) {
+    const declared = Number(res.headers.get('content-length') ?? 0);
+    if (declared > budget)
+        throw overBudget();
+    if (!res.body) {
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        if (bytes.byteLength > budget)
+            throw overBudget();
+        return bytes;
+    }
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > budget) {
+            await reader.cancel().catch(() => undefined);
+            throw overBudget();
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) {
+        out.set(c, offset);
+        offset += c.byteLength;
+    }
+    return out;
+}
+/**
+ * Fetch every attachment and return base64 file entries for the runtime.
+ * Throws AttachmentError with an agent-facing message: an unresolved item
+ * (ChatGPT passed a sandbox path or a bare id instead of a URL), a host we
+ * don't trust, a failed download, or more bytes than MAX_ATTACHMENTS_BYTES.
+ */
+export async function resolveAttachments(attachments, fetchImpl = fetch) {
+    if (!Array.isArray(attachments) || attachments.length === 0)
+        return [];
+    const items = [];
+    attachments.forEach((raw, i) => {
+        const a = (typeof raw === 'object' && raw);
+        const downloadUrl = a && typeof a.download_url === 'string' ? a.download_url : '';
+        let url;
+        try {
+            url = /^https?:\/\//i.test(downloadUrl)
+                ? new URL(downloadUrl)
+                : undefined;
+        }
+        catch {
+            url = undefined;
+        }
+        if (!a || !url) {
+            throw new AttachmentError(`attachments[${i}] was not resolved to a download URL (got ${JSON.stringify(typeof raw === 'string' ? raw : ((a && a.download_url) ?? raw))}). The platform did not hydrate this attachment; retry once, and if it still arrives like this put the file in the \`files\` bundle instead (\`=== FILE: <path> base64 ===\` for binary).`);
+        }
+        const problem = checkAttachmentUrl(url);
+        if (problem) {
+            throw new AttachmentError(`attachments[${i}].download_url ${problem}. Only platform-resolved attachments are accepted here; for any other URL fetch it in \`code\` via wix.request or put the bytes in the \`files\` bundle.`);
+        }
+        items.push({ a, url });
+    });
+    let remaining = MAX_ATTACHMENTS_BYTES;
+    const out = [];
+    for (const [i, { a, url }] of items.entries()) {
+        const path = attachmentPath(a, url);
+        const label = `attachments[${i}] (${path})`;
+        let res;
+        try {
+            res = await fetchAllowed(url, fetchImpl, label);
+        }
+        catch (e) {
+            if (e instanceof AttachmentError)
+                throw e;
+            throw new AttachmentError(`${label}: download failed (${e.message}).`);
+        }
+        if (!res.ok) {
+            await res.body?.cancel().catch(() => undefined);
+            throw new AttachmentError(`${label}: download returned HTTP ${res.status}. The download_url may have expired; attach the file again.`);
+        }
+        const bytes = await readWithin(res, remaining, () => new AttachmentError(`${label} pushes the attachments past ${MAX_ATTACHMENTS_BYTES} bytes in total for this call; split the upload across calls.`));
+        remaining -= bytes.byteLength;
+        out.push({ path, content: toBase64(bytes), encoding: 'base64' });
+    }
+    return out;
+}
+//# sourceMappingURL=attachments.js.map

package/build/dts/code-mode/index.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { AttachmentError, resolveAttachments } from './attachments.js';
 import { logger } from '../infra/logger.js';
 import { defaultToolDescriptions } from '../config/default-config.js';
 import { truncateResponse } from './truncate-response.js';
@@ -214,7 +215,7 @@ function addExecuteTool(server, options) {
     const { codeModeBaseUrl, codeModeFetch, authStrategy, visitor, toolDescriptions, maxResponseSize } = options;
     const executeUrl = `${codeModeBaseUrl}/api/code-mode/execute`;
     const d = desc('ExecuteWixAPI');
-    server.tool(EXECUTE_TOOL_NAME, toolDescriptions?.[EXECUTE_TOOL_NAME] ??
+    const registered = server.tool(EXECUTE_TOOL_NAME, toolDescriptions?.[EXECUTE_TOOL_NAME] ??
         defaultToolDescriptions.ExecuteWixAPI, {
         code: z
             .string()
@@ -246,6 +247,19 @@ function addExecuteTool(server, options) {
             'In `code` they are the `files` global (`{ path, content, encoding?: "base64" }[]`); `wix.multipart()` turns them into one binary-safe `multipart/form-data` body: `const mp = wix.multipart(); await wix.request({ scope: "account", method: "POST", url, headers: { "Content-Type": mp.contentType }, body: mp.body });`.',
             'Use base64 entries for small assets (icons, logos, fonts) and for files you downloaded and are re-uploading; large images/video go in by URL (`<img src="https://...">`), not in the bundle. A file containing a line exactly like the delimiter is not supported.'
         ].join(' ')),
+        // ChatGPT file attachments (`openai/fileParams`). Item shape must match
+        // OpenAI's file schema: download_url + file_id required, the rest optional.
+        // Declaring it is what makes the platform hand us a download URL instead
+        // of a sandbox path. Resolved host-side into base64 `files` entries.
+        attachments: z
+            .array(z.object({
+            download_url: z.string(),
+            file_id: z.string(),
+            file_name: z.string().optional(),
+            mime_type: z.string().optional()
+        }))
+            .optional()
+            .describe('Files attached in this chat, or files you created in your own file sandbox (any type: a zip of a site, HTML, images, PDFs). Pass the files themselves and the platform resolves each into { download_url, file_id, file_name?, mime_type? }; the bytes are fetched here and appended to the `files` global as { path, content, encoding: "base64" } entries (path = file_name), so `wix.multipart()` and `wix.unzip()` work on them unchanged. Prefer this over base64 in `files` whenever you have a file handle. Up to 10 MB per call.'),
         // Visitor mode takes an agent-supplied token and pins the site; account/site
         // mode lets the agent pick the site.
         ...(visitor
@@ -264,7 +278,7 @@ function addExecuteTool(server, options) {
     // Partial: duck-typed servers (the toolkit's capturing server, test
     // doubles) build their own extra and may not supply every field.
     extra) => {
-        const { code, reason, hasMutations, sourceDocUrls, visitorToken, files } = rawArgs;
+        const { code, reason, hasMutations, sourceDocUrls, visitorToken, files, attachments } = rawArgs;
         // In visitor mode the site is pinned; otherwise it comes from the param.
         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}"`);
@@ -276,6 +290,18 @@ function addExecuteTool(server, options) {
             logger.log(`[ExecuteWixAPI]${visitor ? ' (visitor)' : ''} Rejected invalid code: ${validation.error}`);
             return executeTextResult(validation.error);
         }
+        // ChatGPT attachments → base64 file entries, fetched host-side from the
+        // platform's download URLs. Before any token work: an unresolved item is
+        // an agent-facing error, not a server failure.
+        let attachmentFiles = [];
+        try {
+            attachmentFiles = await resolveAttachments(attachments);
+        }
+        catch (e) {
+            if (e instanceof AttachmentError)
+                return executeErrorResult(e.message);
+            throw e;
+        }
         // Account/site mode resolves tokens from the strategy (before the try so
         // an UnauthorizedError propagates to wrapToolCallback). Visitor mode has no
         // strategy — these stay undefined and the visitor token is used instead.
@@ -329,7 +355,8 @@ function addExecuteTool(server, options) {
                     : accountHeaders?.Authorization,
                 accountId: accountHeaders?.['wix-account-id'],
                 siteAuthContext,
-                ...(files ? { files } : {})
+                ...(files ? { files } : {}),
+                ...(attachmentFiles.length ? { attachmentFiles } : {})
             }, visitor
                 ? visitorToken
                 : (accountHeaders?.Authorization ?? siteHeaders?.Authorization), codeModeFetch);
@@ -354,5 +381,11 @@ function addExecuteTool(server, options) {
             return executeErrorResult(message);
         }
     });
+    // ChatGPT resolves `attachments` into download URLs only for params listed
+    // here (OpenAI's `openai/fileParams` extension). Other clients ignore it.
+    // Optional-chained: duck-typed servers (tests, the toolkit) return nothing.
+    registered?.update?.({
+        _meta: { ...registered._meta, 'openai/fileParams': ['attachments'] }
+    });
 }
 //# sourceMappingURL=index.js.map

package/build/dts/config/default-config.js

@@ -78,9 +78,11 @@ export const SITE_CREATION_COPY = {
  * `CreateWixBusinessGuide` is exempt: headless/classic/manual don't need the site's purpose.
  */
 const SITE_GUIDANCE = dedent `
-  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.
+  First decide which of two different things is being asked for:
+  - The site is code the user or you control — hand-written HTML/CSS/JS, a static build, a zip, another AI builder's export, or a page or design you made earlier in this conversation — and it should go live on Wix. This is also the route whenever the user wants to keep working on the site here, with you: a Wix Headless site is a regular coded site, so you keep full control of the design and can change and redeploy it from this conversation at any time, and Wix business capabilities can be added to it as a backend when they are needed. Call StartDeployWebsite: it returns the recipe to host those exact files as a Wix Headless site (updates reuse the same site and URL; the drop page is only its fallback). Do not offer AI or templates for this and do not call any site-creation tool.
+  - Wix should create the site — generated with AI from a description, or started from a template — and the user will design and edit it in Wix rather than through you. That is what the site-creation tools do; they never take files you already have.
 
-  One case skips all of this: a finished page or site ALREADY EXISTS, in any form — hand-written HTML/CSS/JS, a static build, a zip, another AI builder's export, or a page you made earlier in this conversation. There is nothing to build, so don't offer AI or templates and don't call any site-creation tool: call StartDeployWebsite, which returns the recipe to publish the files yourself (the drop page is only its fallback).
+  For a new site there are 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.
 
   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.
@@ -180,13 +182,14 @@ const ACCOUNT_SITE_EXECUTE_SCOPE = dedent `
     unzip(input: string | Uint8Array): Promise<Array<{ path: string; bytes: Uint8Array; text(): string }>>;
   };
   declare const siteId: string | undefined;
-  // Files from the ExecuteWixAPI \`files\` param. Text entries have \`content\`;
-  // an entry tagged \`=== FILE: <path> base64 ===\` has encoding:'base64' and
-  // base64 \`content\` (a binary file — image, font).
+  // Files from the ExecuteWixAPI \`files\` param, followed by the resolved
+  // \`attachments\`. Text entries have \`content\`; an entry tagged
+  // \`=== FILE: <path> base64 ===\` — and every attachment, path = its file name —
+  // has encoding:'base64' and base64 \`content\`.
   declare const files: Array<{ path: string; content: string; encoding?: "base64" }>;
   \`\`\`
 
-  FILE UPLOADS: put every file in the \`files\` param (never inline in \`code\`). Text goes raw; a small binary (icon, logo, font) rides as a \`base64\`-tagged entry — large images/video are referenced by URL (\`<img src="https://...">\`), not bundled. \`wix.multipart()\` turns the whole set into one upload body (bytes, so binary is safe):
+  FILE UPLOADS: files never go inline in \`code\`; two params feed the \`files\` global. \`attachments\` takes files attached in the chat or created in your file sandbox, of any type and size up to 10 MB per call (a zip of a whole site, HTML, images, PDFs): pass the files themselves, all in one call, and the platform resolves each into \`{ download_url, file_id, file_name?, mime_type? }\` — the bytes are fetched for you and arrive as base64 entries named by file name. The \`files\` param takes content you have as text here: text goes raw; a small binary (icon, logo, font) rides as a \`base64\`-tagged entry — large images/video are referenced by URL (\`<img src="https://...">\`), not bundled. \`wix.multipart()\` turns the whole set into one upload body (bytes, so binary is safe):
   \`\`\`javascript
   // files param:
   //   === FILE: index.html ===
@@ -201,6 +204,12 @@ const ACCOUNT_SITE_EXECUTE_SCOPE = dedent `
     return res.data;
   }
   \`\`\`
+  A site zip passed through \`attachments\` is one base64 entry; unzip it and upload the entries:
+  \`\`\`javascript
+  // attachments: [site.zip] → files = [{ path: "site.zip", content: "<base64>", encoding: "base64" }]
+  const entries = await wix.unzip(files[0].content); // [{ path, bytes, text() }]
+  const mp = wix.multipart(entries);
+  \`\`\`
   DOWNLOAD + EDIT + RE-UPLOAD: fetch the zip as base64, \`wix.unzip()\` it, edit text via \`entry.text()\`, keep binary as bytes, and hand the entries back to \`wix.multipart()\`:
   \`\`\`javascript
   const r = await wix.request({ scope: "account", method: "GET", responseType: "base64", url: zipUrl });
@@ -402,12 +411,12 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
     NEVER call this tool with a missing, empty, or guessed siteId — ask first instead.
 
     Parameters — provide image input via image and/or imageUrls, OR imageBase64:
-    • image (array): chat file ATTACHMENTS. Each item is an object with download_url and file_id (both required), plus optional file_name and mime_type. Pass ALL attachments in one call.
+    • image (array): chat file ATTACHMENTS — files the user attached, or files you created in your own file sandbox. Each item is an object with download_url and file_id (both required), plus optional file_name and mime_type. Pass ALL attachments in one call.
     • imageUrls (array): plain public image URLs the user pasted or other tools produced (no file_id). Pass ALL URLs in one call. Can be combined with image.
     • imageBase64 (string): base64-encoded image + mimeType. One image at a time. Do NOT combine with image/imageUrls.
 
     Delivering the bytes — this is where uploads most often fail:
-    • NEVER pass a local or sandbox file path (e.g. /mnt/..., /home/user/..., /Users/...) in any field — the server cannot reach your filesystem. Use a public http(s) URL (imageUrls) or the complete base64 (imageBase64).
+    • Pass a file as a file, in image: the platform resolves it into download_url and file_id before it reaches this tool — this includes files you created in your sandbox. This server does not share your filesystem, so a bare path string (e.g. /mnt/..., /home/user/..., /Users/...) is not a file. Without a file to pass, use a public http(s) URL (imageUrls) or the complete base64 (imageBase64).
     • imageBase64 must be the WHOLE file, not truncated. For large images prefer imageUrls, since long base64 is easily cut off and will be rejected as unreadable.
   `,
         SupportAndFeedback: dedent `
@@ -904,14 +913,14 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
         WixSiteBuilder: dedent `
     ${SITE_GUIDANCE}
 
-    Tool for generating a Wix site with AI (creating / building a site in Wix Harmony).
+    Tool for generating a Wix site with AI (creating / building a site in Wix Harmony) from a description. It does not take pages or files you already have — those go to StartDeployWebsite.
 
     Call this ONLY when the user's own words name AI (for example "create a site using AI" or "build it with AI") and the site intent is clear. A description of what the site should do — reservations, online ordering, a store, bookings, menus, a portfolio, and the like — is NOT a request for AI and NOT enough to call this tool; never infer AI from features or industry.
     Never default to this tool: if the user hasn't explicitly named AI, don't call this tool — ${SITE_CREATION_COPY.unstatedMethod.nonWidget}.
 
     For templates or Wix Studio, call \`SearchSiteTemplates\`; for a specific template by \`metaSiteId\` or \`templateId\`, call \`CreateSiteFromTemplate\`; for a headless or classic Wix Editor site, or manual/account-API creation, call \`CreateWixBusinessGuide\`.
 
-    Do NOT suggest HTML code, prompt templates, or alternative approaches — actually build the site through this tool.
+    Do NOT suggest HTML code, prompt templates, or alternative approaches instead of building — actually build the site through this tool. (HTML the user already has is the StartDeployWebsite case, not a reason to build.)
   `,
         SearchSiteTemplates: dedent `
     ${SITE_GUIDANCE}
@@ -955,8 +964,8 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
     Set \`hasMutations: true\` for any document containing a mutation root field.
   `,
         StartDeployWebsite: dedent `
-    The user — or you, earlier in this conversation — ALREADY HAVE a finished page or site, in any form, and it should be live on Wix: HTML/CSS/JS files, a static build (dist/, out/), a zip, another AI builder's export, or a page/design you created in this conversation (export it to HTML first — a finished design IS a finished page). Call this when the user says deploy, host, publish, put online, make it live, get a URL, or upload my site / index.html.
-    Also for updating a site deployed this way (replace its files; same site, same URL) and for implementing a backend on one (stores, bookings, CMS, members) as a Wix Headless project — same site, same URL. Works with or without a Wix login (anonymous deploy with a save link), through the Wix MCP alone or from a shell.
+    The user — or you, earlier in this conversation — ALREADY HAVE a finished page or site, in any form, and it should be live on Wix — or an already-deployed Wix Headless site whose files should be replaced. The site can be HTML/CSS/JS files, a static build (dist/, out/), a zip, another AI builder's export, or a page/design you created in this conversation (export it to HTML first — a finished design IS a finished page). Call this when the user says deploy, host, publish, put online, make it live, get a URL, update my site, or upload my site / index.html.
+    Updates keep the same site and URL. Also for implementing a backend on such a site as a Wix Headless project — same site, same URL. Works with or without a Wix login (anonymous deploy with a save link), through the Wix MCP alone or from a shell.
     Missing real functionality — a fake checkout, a form that goes nowhere, bookings — is NOT a reason to rebuild the site with a site-creation tool: deploy the page as is, then add the backend afterwards (the recipe covers it).
     Returns the full recipe; follow it and run the flow yourself. The drop page is only the fallback when you can't.
     NOT for: a screenshot, mockup or reference image of a site the user WANTS (nothing exists to deploy yet — that is site creation: WixSiteBuilder / templates); a Claude Design share URL (import-claude-design-from-url); migrating a live site by URL or CSV exports; adding HTML or code into an existing Wix site; uploading images or documents to a site's media (UploadImageToWixSite).

package/build/dts/config/param-descriptions.js

@@ -73,7 +73,7 @@ export const paramDescriptions = {
     },
     SearchWixRESTDocumentation: {
         searchTerm: 'The search term to look up in the Wix REST API Documentation — a natural-language description of the endpoint, resource, or action you need across any Wix domain (Stores, eCommerce, Bookings, CRM, Members, CMS, Events, Blog, Forms, Media, site settings, etc.), e.g. "create a catalog item with inventory", "book a service", "update data collection items". Match the wording to how many entities you will act on: a plural term ("update products") surfaces the resource\'s bulk methods, which a singular term ("update a product") ranks lower or leaves out. Results are ranked by relevance, so describe the goal rather than guessing an exact API name.',
-        maxResults: 'The maximum number of results to return, default is 10, max is 15',
+        maxResults: 'The maximum number of results to return (1–17, default 17). Results mix REST API documentation with matching recipes and skills.',
         reason: 'One sentence describing the original user request and the task you are trying to accomplish with this search.'
     },
     WixBusinessFlowsDocumentation: {
@@ -94,7 +94,7 @@ export const paramDescriptions = {
     },
     SearchWixHeadlessDocumentation: {
         searchTerm: 'The search term to search for in the Headless Documentation',
-        maxResults: 'The maximum number of results to return, default is 10, max is 15'
+        maxResults: 'The maximum number of results to return (1–17, default 17). Results mix Headless documentation with matching recipes and skills.'
     },
     SearchWixVeloDocumentation: {
         searchTerm: 'The search term to search for in the Velo Documentation',
@@ -125,7 +125,7 @@ export const paramDescriptions = {
     },
     UploadImageToWixSite: {
         siteId: 'The ID (UUID) of the Wix site to upload to. REQUIRED. If the user has not clearly specified which site, ASK them which site to upload to (or use ListWixSites to help them pick) BEFORE calling this tool. NEVER call this tool with a missing, empty, placeholder, or guessed siteId — ask first instead.',
-        image: 'Array of file ATTACHMENTS the user uploaded in the chat. Each item requires download_url and file_id, and may optionally include file_name and mime_type — attached files are automatically resolved to these fields by the platform, so just include them here. For plain image URLs the user pasted, use imageUrls instead. ALWAYS pass ALL attachments together in a single call — NEVER call this tool once per image. Do NOT use together with imageBase64.',
+        image: 'Array of file ATTACHMENTS: files the user uploaded in the chat, or files you created in your own file sandbox. Each item requires download_url and file_id, and may optionally include file_name and mime_type — the platform resolves a file passed here into these fields automatically, so just include the files. For plain image URLs the user pasted, use imageUrls instead. ALWAYS pass ALL attachments together in a single call — NEVER call this tool once per image. Do NOT use together with imageBase64.',
         imageUrls: 'Array of publicly accessible image URLs (e.g. links the user pasted or URLs produced by other tools). Use this for plain URLs that are NOT chat attachments — no file_id is needed. ALWAYS pass ALL URLs together in a single call. Can be combined with image; do NOT use together with imageBase64.',
         imageBase64: 'Base64-encoded image data. Use when the client can read a file and encode it as base64. May include a data URL prefix (e.g. "data:image/jpeg;base64,...") or be raw base64. Do NOT use together with image.',
         mimeType: 'MIME type of the image (e.g. "image/jpeg", "image/png", "image/webp"). Required when imageBase64 does not include a data URL prefix.',

package/build/dts/docs/docs.js

@@ -195,9 +195,9 @@ export const addDocsTools = (server, allowedTools = [
                     .number()
                     .describe(d.maxResults)
                     .min(1)
-                    .max(15)
+                    .max(17)
                     .optional()
-                    .default(15),
+                    .default(17),
                 reason: z.string().describe(d.reason)
             };
         })(), { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ searchTerm, maxResults, reason }, { panorama }) => {
@@ -208,9 +208,12 @@ export const addDocsTools = (server, allowedTools = [
                     toolParams: {
                         searchTerm: searchTerm
                     },
-                    maxResults: Math.max(1, Math.min(maxResults ?? 15, 15)),
+                    maxResults: Math.max(1, Math.min(maxResults ?? 17, 17)),
                     linesInEachResult: 30,
-                    usePlatformizedSearch
+                    usePlatformizedSearch,
+                    // Merge recipes/skills into the REST ranking — they live in a
+                    // separate corpus the REST document_type doesn't cover on its own.
+                    extraDocumentTypes: ['SKILLS']
                 });
                 // Only when a result actually carried the marker. Re-deriving it here would also fire on
                 // an article that merely references a query endpoint, with no such endpoint in the results.
@@ -472,9 +475,9 @@ export const addDocsTools = (server, allowedTools = [
                     .number()
                     .describe(d.maxResults)
                     .min(1)
-                    .max(15)
+                    .max(17)
                     .optional()
-                    .default(15)
+                    .default(17)
             };
         })(), { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ searchTerm, maxResults }, { panorama }) => {
             try {
@@ -484,8 +487,11 @@ export const addDocsTools = (server, allowedTools = [
                     toolParams: {
                         searchTerm: searchTerm
                     },
-                    maxResults: Math.max(1, Math.min(maxResults ?? 15, 15)),
-                    usePlatformizedSearch
+                    maxResults: Math.max(1, Math.min(maxResults ?? 17, 17)),
+                    usePlatformizedSearch,
+                    // Merge recipes/skills into the headless ranking — same separate
+                    // corpus the WIX_HEADLESS document_type doesn't cover on its own.
+                    extraDocumentTypes: ['SKILLS']
                 });
                 return {
                     content: [

package/build/dts/docs/semanticSearch.d.ts

@@ -1,11 +1,12 @@
 import type { DocsTool } from './docs.js';
 export declare const DEFAULT_MAX_RESULTS = 15;
-export declare const runSemanticSearchAndFormat: ({ toolName, toolParams, maxResults, rerank, linesInEachResult, usePlatformizedSearch }: {
+export declare const runSemanticSearchAndFormat: ({ toolName, toolParams, maxResults, rerank, linesInEachResult, usePlatformizedSearch, extraDocumentTypes }: {
     toolName: DocsTool;
     toolParams: Record<string, string>;
     maxResults?: number;
     rerank?: boolean;
     linesInEachResult?: number | undefined;
     usePlatformizedSearch?: boolean;
+    extraDocumentTypes?: string[];
 }) => Promise<string>;
 //# sourceMappingURL=semanticSearch.d.ts.map

package/build/dts/docs/semanticSearch.js

@@ -70,9 +70,14 @@ const runSemanticSearch = async (toolName, toolParams, maxResults = 20, rerank =
     logger.log('Ran RAG search successfully with params', JSON.stringify(toolParams), timeTaskFormatted, typeof data);
     return data?.results;
 };
-const runPlatformizedSemanticSearch = async (toolName, searchTerm, maxResults = 20, linesInEachResult) => {
+const runPlatformizedSemanticSearch = async (toolName, searchTerm, maxResults = 20, linesInEachResult, extraDocumentTypes) => {
     const startTime = Date.now();
-    logger.log(`[SemanticSearch/v2] Tool: ${toolName}, Query: "${searchTerm}"`);
+    // When extra types are requested, search them in one combined ranking via the
+    // plural `document_types` field (mutually exclusive with `document_type`).
+    const documentTypes = extraDocumentTypes?.length
+        ? [toolName, ...extraDocumentTypes]
+        : undefined;
+    logger.log(`[SemanticSearch/v2] Tool: ${documentTypes ? documentTypes.join('+') : toolName}, Query: "${searchTerm}"`);
     const response = await fetch('https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdown', {
         method: 'POST',
         headers: {
@@ -81,7 +86,9 @@ const runPlatformizedSemanticSearch = async (toolName, searchTerm, maxResults =
         },
         body: JSON.stringify({
             search_term: searchTerm,
-            document_type: toolName,
+            ...(documentTypes
+                ? { document_types: documentTypes }
+                : { document_type: toolName }),
             maximum_results: maxResults,
             lines_in_each_result: linesInEachResult
         })
@@ -98,9 +105,9 @@ const runPlatformizedSemanticSearch = async (toolName, searchTerm, maxResults =
     }
     return content;
 };
-export const runSemanticSearchAndFormat = async ({ toolName, toolParams, maxResults = DEFAULT_MAX_RESULTS, rerank, linesInEachResult, usePlatformizedSearch = true }) => {
+export const runSemanticSearchAndFormat = async ({ toolName, toolParams, maxResults = DEFAULT_MAX_RESULTS, rerank, linesInEachResult, usePlatformizedSearch = true, extraDocumentTypes }) => {
     if (usePlatformizedSearch) {
-        return runPlatformizedSemanticSearch(toolName, toolParams.searchTerm, maxResults, linesInEachResult);
+        return runPlatformizedSemanticSearch(toolName, toolParams.searchTerm, maxResults, linesInEachResult, extraDocumentTypes);
     }
     else {
         const results = await runSemanticSearch(toolName, toolParams, maxResults, rerank);

package/build/dts/docs/start-deploy-website.d.ts

@@ -1,5 +1,13 @@
 import { WixMcpServer } from '../wix-mcp-server.js';
-export declare const START_DEPLOY_WEBSITE_BRIEF_DESCRIPTION = "A few sentences covering: the user's request (quoted if short); what the site is \u2014 its purpose and who it is for \u2014 and its current form (HTML/CSS/JS files, a static build, a zip, another builder's export, a design created in this conversation), roughly how many files, and whether it includes images; what the site must be able to do for its visitors beyond showing pages, if anything \u2014 selling, bookings or reservations, tickets, menus and orders, rentals, forms, memberships or paid plans, donations, a blog, or anything else the user expects to work \u2014 described in your own words, or a note that it is a plain static site with no such needs; which agent or product you are and the harness you run in.";
+export declare const START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS: {
+    readonly userRequest: "The user's request that led here, quoted if short, otherwise summarized in a sentence.";
+    readonly siteDescription: "What the site is: its purpose and who it is for. One or two sentences.";
+    readonly siteForm: "The form the site exists in right now (HTML/CSS/JS files, a static build, a zip, another builder's export, a design created in this conversation, or something else), roughly how many files, and whether it includes images.";
+    readonly siteFunctionality: "What the site must be able to do for its visitors beyond showing pages, if anything (for example selling, bookings or reservations, tickets, menus and orders, rentals, forms, memberships or paid plans, donations, a blog, or anything else the user expects to work), in your own words. If it is a plain static site with no such needs, say so.";
+    readonly agentIdentity: "Which agent or product you are and the harness you run in.";
+    readonly wixAccess: "How you can reach Wix from where you run: through this MCP only, or also from a shell whose network can reach wixapis.com; whether you can run the Wix CLI (npx @wix/cli) there and whether it is logged in; and which Wix identity you act with — the user's login through this MCP, a CLI login, or none.";
+};
+export declare const START_DEPLOY_WEBSITE_PARAMS: Array<keyof typeof START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS>;
 export declare const START_DEPLOY_WEBSITE_TOOL_NAME = "StartDeployWebsite";
 export declare const START_DEPLOY_WEBSITE_RECIPE_URL = "https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md";
 export declare const DROP_PAGE_URL = "https://www.wix.com/headless/drop?utm_campaign=mcp";

package/build/dts/docs/start-deploy-website.js

@@ -1,9 +1,18 @@
 import { z } from 'zod';
 import { defaultToolDescriptions } from '../config/default-config.js';
 import { fetchArticleContent } from './fetch-article.js';
-// Longer than the one-sentence `reason` on other tools: it is the only record of
-// who deploys what. Read by people via BI; it does not change the response.
-export const START_DEPLOY_WEBSITE_BRIEF_DESCRIPTION = "A few sentences covering: the user's request (quoted if short); what the site is — its purpose and who it is for — and its current form (HTML/CSS/JS files, a static build, a zip, another builder's export, a design created in this conversation), roughly how many files, and whether it includes images; what the site must be able to do for its visitors beyond showing pages, if anything — selling, bookings or reservations, tickets, menus and orders, rentals, forms, memberships or paid plans, donations, a blog, or anything else the user expects to work — described in your own words, or a note that it is a plain static site with no such needs; which agent or product you are and the harness you run in.";
+// These arguments are the only record of who deploys what; they are read by
+// people via BI and do not change the response. One field per question so each
+// can be analyzed on its own.
+export const START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS = {
+    userRequest: "The user's request that led here, quoted if short, otherwise summarized in a sentence.",
+    siteDescription: 'What the site is: its purpose and who it is for. One or two sentences.',
+    siteForm: "The form the site exists in right now (HTML/CSS/JS files, a static build, a zip, another builder's export, a design created in this conversation, or something else), roughly how many files, and whether it includes images.",
+    siteFunctionality: 'What the site must be able to do for its visitors beyond showing pages, if anything (for example selling, bookings or reservations, tickets, menus and orders, rentals, forms, memberships or paid plans, donations, a blog, or anything else the user expects to work), in your own words. If it is a plain static site with no such needs, say so.',
+    agentIdentity: 'Which agent or product you are and the harness you run in.',
+    wixAccess: "How you can reach Wix from where you run: through this MCP only, or also from a shell whose network can reach wixapis.com; whether you can run the Wix CLI (npx @wix/cli) there and whether it is logged in; and which Wix identity you act with — the user's login through this MCP, a CLI login, or none."
+};
+export const START_DEPLOY_WEBSITE_PARAMS = Object.keys(START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS);
 export const START_DEPLOY_WEBSITE_TOOL_NAME = 'StartDeployWebsite';
 export const START_DEPLOY_WEBSITE_RECIPE_URL = 'https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md';
 export const DROP_PAGE_URL = 'https://www.wix.com/headless/drop?utm_campaign=mcp';
@@ -31,7 +40,30 @@ export function addStartDeployWebsiteTool(server, disableTools = [], toolDescrip
     }
     server.tool(START_DEPLOY_WEBSITE_TOOL_NAME, toolDescriptions?.[START_DEPLOY_WEBSITE_TOOL_NAME] ??
         defaultToolDescriptions[START_DEPLOY_WEBSITE_TOOL_NAME], {
-        brief: z.string().min(1).describe(START_DEPLOY_WEBSITE_BRIEF_DESCRIPTION)
+        userRequest: z
+            .string()
+            .min(1)
+            .describe(START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.userRequest),
+        siteDescription: z
+            .string()
+            .min(1)
+            .describe(START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.siteDescription),
+        siteForm: z
+            .string()
+            .min(1)
+            .describe(START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.siteForm),
+        siteFunctionality: z
+            .string()
+            .min(1)
+            .describe(START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.siteFunctionality),
+        agentIdentity: z
+            .string()
+            .min(1)
+            .describe(START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.agentIdentity),
+        wixAccess: z
+            .string()
+            .min(1)
+            .describe(START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.wixAccess)
     }, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async (_args, { httpClient }) => {
         let text = START_DEPLOY_WEBSITE_POINTER_RESPONSE;
         try {