@wix/mcp 1.0.89 → 1.0.91

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

@@ -18,7 +18,7 @@ function buildSystemReminderGuidelines(includeReadme, includeImageUploadGuidance
     const exception = includeReadme ? '**Exception:** ' : '';
     const lines = [];
     if (includeReadme) {
-        lines.push('if the WixREADME tool is available to you, YOU MUST USE IT AT THE BEGINNING OF ANY CONVERSATION and then continue with calling the other tools and calling the Wix APIs until the task is completed.', '**Exception — creating a new Wix site/website:** For a normal creation request — and only then — skip WixREADME and the docs search, and route straight to the Wix site-creation tools available to you; their descriptions carry the routing rules. Everything else starts with WixREADME as usual.', "If the user explicitly asks for a headless site, Wix Classic Editor site, or manual account/API-based site creation, call CreateWixBusinessGuide right away — these don't need the site's purpose first.", "Never default to AI or search templates unless the user explicitly requests it. When the user named no creation method - let the user make that choice as the site-creation tools' descriptions direct. Never route normal site creation through ManageWixSite, CallWixSiteAPI, or ExecuteWixAPI.");
+        lines.push('if the WixREADME tool is available to you, YOU MUST USE IT AT THE BEGINNING OF ANY CONVERSATION and then continue with calling the other tools and calling the Wix APIs until the task is completed.', '**Exception — creating a new Wix site/website:** For a normal creation request — and only then — skip WixREADME and the docs search, and route straight to the Wix site-creation tools available to you; their descriptions carry the routing rules. Everything else starts with WixREADME as usual.', "If the user explicitly asks for a headless site, Wix Classic Editor site, or manual account/API-based site creation, call CreateWixBusinessGuide right away — these don't need the site's purpose first.", "If the user — or you, earlier in this conversation — already have a finished page or site in any form (HTML/CSS/JS files, a static build, a zip, another builder's export, a design you can export to HTML) and want it live on Wix, call StartDeployWebsite right away — not a site-creation tool, not the docs.", "Never default to AI or search templates unless the user explicitly requests it. When the user named no creation method - let the user make that choice as the site-creation tools' descriptions direct. Never route normal site creation through ManageWixSite, CallWixSiteAPI, or ExecuteWixAPI.");
     }
     lines.push(`${exception}If the user asks to list, show, or find their Wix sites, ${includeReadme ? 'skip WixREADME and ' : ''}call ListWixSites directly.`);
     if (includeImageUploadGuidance) {
@@ -80,7 +80,7 @@ export const SITE_CREATION_COPY = {
 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.
 
-  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.
+  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).
 
   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.
@@ -338,6 +338,7 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
         ReadFullDocsArticle: dedent `
     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.
+    Also reads Wix skills pages — https://www.wix.com/skills/<skill>, https://dev.wix.com/docs/skills/<skill>, and the files they link (e.g. .../<skill>/references/<file>.md) — exactly as served.
     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}
@@ -345,7 +346,7 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
         ReadFullDocsMethodSchema: dedent `
     Fetches the full method schema for a given method.
     This will give you the entire request/response schema with all the fields and their descriptions.
-    For REST API methods, prefer SearchWixAPISpec when it is available: it can fetch and inspect the exact method schema by docs URL, return the request/response shape, and inspect selected nested component schemas without dumping unrelated fields. Use ReadFullDocsMethodSchema for REST only when SearchWixAPISpec is unavailable or did not provide the needed detail.
+    For REST and SDK API-reference methods, prefer SearchWixAPISpec when it is available: it can fetch and inspect the exact method schema by docs URL, return the request/response shape, the JavaScript SDK call (\`method.sdk\`: package, namespace, method, positional parameters, examples), and inspect selected nested component schemas without dumping unrelated fields. Use ReadFullDocsMethodSchema only when SearchWixAPISpec is unavailable or did not provide the needed detail.
     For REST docs, use the URL as-is. For SDK docs, the URL SHOULD include ?apiView=SDK.
     ${reminder}
   `,
@@ -471,7 +472,7 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
   `,
         'import-claude-design-from-url': dedent `
     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. 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.
+    NOT for a page or site that exists in any other form (the user's own HTML/CSS/JS, a static build, a zip, another builder's export, a page you made in this conversation) — for those call StartDeployWebsite instead; it returns the recipe to publish the files yourself.
   `,
         RunWixCliCommand: dedent `
     Executes Wix CLI commands for Wix app development and management.
@@ -500,6 +501,7 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
   `,
         SearchWixSDKDocumentation: dedent `
     Searches the Wix JavaScript SDK documentation.
+    Next step for an API-reference method it returns: pass its docs URL (with or without \`?apiView=SDK\`) to \`SearchWixAPISpec\`'s \`getResourceSchemaByUrl\` when available, and read \`method.sdk\` for the exact import, call signature, typed parameters, return type, and examples.
   `,
         SearchBuildAppsDocumentation: dedent `
     Searches the Wix Build Apps documentation.
@@ -512,18 +514,18 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
         SearchWixHeadlessDocumentation: dedent `
     Searches the Wix Headless documentation.
   `,
-        // Note: The raw schema also contains sdkData (JS SDK package name, namespace, and
-        // code examples) but it's intentionally omitted from the tool description. Currently
-        // this MCP is focused on REST API calls via ExecuteWixAPI. We may want to expose
-        // sdkData in the future — needs further thought on use cases and presentation.
+        // Note: each method also carries its JavaScript SDK facet (`method.sdk`: package,
+        // namespace, method name, positional signature, parameter schema, JS examples),
+        // merged at spec-sync time from the docs' SDK view. REST fields are unchanged;
+        // `sdk` is simply absent on methods the SDK docs don't list.
         SearchWixAPISpec: dedent `
-    Inspect the Wix REST API spec by writing JavaScript code that runs in a sandboxed read-only environment.
-    **Precondition:** you already have a method \`docsUrl\` — from \`SearchWixRESTDocumentation\`, \`BrowseWixRESTDocsMenu\`, \`ReadFullDocsArticle\`, ${includeReadme ? 'a `WixREADME` recipe, ' : ''}or a prior tool result / the user's message in this conversation. If you don't have one yet, call \`SearchWixRESTDocumentation\` FIRST to discover it; do not use this tool to search for or choose an endpoint.
+    Inspect the Wix REST API spec, and the JavaScript SDK call for each method, by writing JavaScript code that runs in a sandboxed read-only environment.
+    **Precondition:** you already have a method \`docsUrl\` — from \`SearchWixRESTDocumentation\`, \`SearchWixSDKDocumentation\` (its \`?apiView=SDK\` URLs work here as-is), \`BrowseWixRESTDocsMenu\`, \`ReadFullDocsArticle\`, ${includeReadme ? 'a `WixREADME` recipe, ' : ''}or a prior tool result / the user's message in this conversation. If you don't have one yet, call \`SearchWixRESTDocumentation\` (or \`SearchWixSDKDocumentation\` when writing SDK code) FIRST to discover it; do not use this tool to search for or choose an endpoint.
     **Never pass a \`docsUrl\` you produced from memory.** If the exact URL you are about to pass to \`getResourceSchemaByUrl\` did not appear verbatim in an earlier tool result (or the user's message), it is a guess — call \`SearchWixRESTDocumentation\` first and use a URL from its ranked results. A guessed URL that merely looks plausible routinely resolves to the WRONG sibling method (e.g. \`.../products-v3/create-product\` when the task needs \`.../products-v3/create-product-with-inventory\`), sending the whole turn down a dead end. When in doubt, discover — don't guess.
-    **This tool's job is to INSPECT the exact schema of a method you have ALREADY located — its request/response shape, nested types, and enums. It is NOT a discovery tool for choosing which method to use.**
+    **This tool's job is to INSPECT the exact schema of a method you have ALREADY located — its request/response shape, nested types, and enums, and its SDK call (\`method.sdk\`). It is NOT a discovery tool for choosing which method to use.**
     With a method \`docsUrl\` in hand, call \`getResourceSchemaByUrl(methodDocsUrl)\` to get the resource schema, then read the target method from \`schema.methods\` and resolve any nested \`{ $circular: name }\` types via \`schema.components.schemas[name]\`.
     **If you don't already have a \`docsUrl\` in context, your FIRST action MUST be \`SearchWixRESTDocumentation\` (ranked semantic search) — not this tool.** Then pass the resulting \`docsUrl\` to \`getResourceSchemaByUrl\` here. Do NOT discover endpoints by hand-filtering or scanning \`lightIndex\` (e.g. \`lightIndex.filter(...)\` / \`lightIndex.flatMap(...)\` on a substring): it has no relevance ranking, matches only at resource-name granularity, and misses composite or method-level operations whose parent resource is named after a different noun than your intent. \`lightIndex\` is for resolving a \`docsUrl\` you already have, not for finding one.
-    Prefer \`SearchWixAPISpec\` over \`ReadFullDocsMethodSchema\` for REST method schemas when it is available, especially once you already have a docs URL from semantic search, menu browsing, or conversation context.
+    Prefer \`SearchWixAPISpec\` over \`ReadFullDocsMethodSchema\` for REST and SDK method schemas when it is available, especially once you already have a docs URL from semantic search, menu browsing, or conversation context.
 
     Prefer URL-first results:
     - If you have a docs URL or partial docs URL, search \`resource.docsUrl\` and \`method.docsUrl\` first.
@@ -531,7 +533,7 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
     - For API execution, return and use \`method.publicUrl\` when available. It is the preferred executable \`https://www.wixapis.com/...\` URL.
     - Return \`docsUrl\` for relevant resources/methods when the next step needs an article or API call source URL; do not hand off to \`ReadFullDocsMethodSchema\` just to inspect a REST method schema.
     - Use \`resourceId\` only as the internal handle for low-level loaders; prefer URL helpers when you have a docs URL.
-    - \`getResourceSchemaByUrl\` resolves only **API resource/method** docs (e.g. \`.../bookings/services/services-v2/create-service\`). It does NOT work on **skill** pages (\`.../skills/...\`) or **article** pages — those have no schema. For an article, use \`getArticleContentByUrl(docsUrl)\`. Never pass a \`.../skills/...\` URL (skill recipes often cross-link sibling skill pages) — use \`SearchWixRESTDocumentation\` to find the real API method instead. If a lookup misses, don't retry the same URL; rediscover it with \`SearchWixRESTDocumentation\`.
+    - \`getResourceSchemaByUrl\` resolves only **API resource/method** docs (e.g. \`.../bookings/services/services-v2/create-service\`). It does NOT work on **skill** pages (\`.../skills/...\`) or **article** pages — those have no schema. For an article, use \`getArticleContentByUrl(docsUrl)\`. Never pass a \`.../skills/...\` URL (skill recipes often cross-link sibling skill pages) — read the skill page with \`ReadFullDocsArticle\`, and use \`SearchWixRESTDocumentation\` to find the real API method. If a lookup misses, don't retry the same URL; rediscover it with \`SearchWixRESTDocumentation\`.
 
     Your code has access to these globals:
 
@@ -546,6 +548,8 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
       resourceId: string;     // internal handle for getResourceSchema()
       docsUrl: string;        // e.g. "https://dev.wix.com/docs/api-reference/.../<resource>"
       menuPath: string[];     // e.g. ["business-solutions", "<vertical>", "<resource>"]
+      sdkPackage?: string;    // JS SDK npm package shared by the resource's methods, e.g. "@wix/<vertical>"
+      sdkNamespace?: string;  // module exported by that package, e.g. "<resources>" — absent when the methods differ (then each method carries its own)
       methods: Array<{
         operationId: string;  // e.g. "wix.<vertical>.v3.<Api>.<Operation>"
         summary: string;      // human-readable method name
@@ -555,6 +559,9 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
         publicUrl?: string;   // preferred executable URL for ExecuteWixAPI, when available after spec sync
         publicBaseUrl?: string;
         description: string;  // truncated to 200 chars
+        sdk?: string;         // the JS SDK call as the SDK docs show it, e.g. "query<Resources>(query, options)"; absent when the SDK docs don't list the method
+        sdkPackage?: string;  // only when the resource-level value is absent
+        sdkNamespace?: string;
       }>;
     }
     \`\`\`
@@ -583,8 +590,17 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
         legacyExamples: Array<{                    // Curl examples
           content: { title: string; request: string; response: string };
         }>;
+        sdk?: {                                    // JavaScript SDK facet; absent when the SDK docs don't list the method
+          package: string;                         // npm package, e.g. "@wix/<vertical>"  →  import { <namespace> } from "<package>"
+          namespace: string;                       // module exported by the package, e.g. "<resources>"
+          method: string;                          // SDK method name; NOT always the operation name (e.g. Data Items' InsertDataItem is "insert")
+          signature: string[];                     // positional parameter names in call order, e.g. ["query", "options"]
+          requestBody: object | null;              // same envelope as the REST requestBody; its properties ARE the parameters in \`signature\`, each typed
+          responses?: object;                      // only when the SDK returns something other than the REST response (e.g. the created entity instead of a Create<X>Response wrapper)
+          examples: Array<{ title: string; description?: string; code: string }>; // JavaScript examples from the SDK docs
+        };
       }>;
-      components: { schemas: object };
+      components: { schemas: object };               // REST types plus the SDK's own types; \`$circular\` names from either body resolve here, exactly as written (SDK-shaped copies of shared types are keyed "sdk:<TypeName>")
     }
     \`\`\`
 
@@ -646,6 +662,16 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
     - When inspecting a specific method schema (i.e. you have found a single method and are returning its details), always include \`responses: method.responses\` alongside \`requestBody\`. Knowing the response shape up front prevents speculative re-runs of mutations just to see what the API returned.
     - Query/search methods: the declared map is \`method.queryMethodData.queryFieldsCapabilitiesMap\`, or \`method.searchMethodData.searchFieldsCapabilitiesMap\` on search methods. Each entry declares one field's allowed \`operators\` and \`sort\` directions — a closed list, valid for that method alone, so another endpoint's map or a field's presence in the response proves nothing here. Each listed operator is valid on its own — a field takes one — so combine conditions with the logical operators instead: \`$and\` and \`$or\` take an array of expressions, \`$not\` takes one, and they can nest. They are WQL syntax rather than a field capability, so they never appear in the map, and its silence about them is no restriction. An undeclared field or unlisted operator are rejected; some endpoints instead ignore the filter or sort and return the wrong rows. \`sort: []\` means not sortable; no map means nothing is declared, so try what you need and filter in code if it isn't supported.
 
+    JavaScript SDK (writing code with \`@wix/sdk\` and the \`@wix/*\` packages, in Wix Headless, Velo, CLI apps, or any Node/browser project):
+    - Read \`method.sdk\`, not the REST fields. The REST \`requestBody\` is the wire shape; the SDK wraps it differently — fields become positional arguments, and secondary fields move into an \`options\` object — so never derive an SDK call from the REST body. \`sdk.requestBody.properties\` are the parameters, in the order given by \`sdk.signature\`; \`sdk.requestBody.required\` says which are mandatory.
+    - The call is \`<namespace>.<method>(<signature>)\` after \`import { <namespace> } from "<package>"\` (e.g. \`import { services } from "@wix/bookings"\`), or \`wixClient.<namespace>.<method>(...)\` on a client created with \`createClient({ modules: { <namespace> } })\`. \`sdk.method\` is the only reliable method name — it is not always the camelCased operation name.
+    - Return value: \`await\` resolves to \`sdk.responses\` when present, otherwise to the same shape as \`method.responses\`. Resolve \`$circular\` names from either body against \`schema.components.schemas\` exactly as written: an SDK body may point at an SDK-shaped copy of a type, keyed \`"sdk:<TypeName>"\` (e.g. \`sdk:wix.bookings.services.v2.Service\`), which sits in the same dictionary.
+    - Field names differ from REST on entity system fields: the SDK reads and writes \`_id\`, \`_createdDate\`, \`_updatedDate\` where REST has \`id\`, \`createdDate\`, \`updatedDate\`. The SDK-shaped types already use the SDK names — take field names from them, never from the REST body or a REST-keyed type.
+    - Timestamps: where a REST field is a \`date-time\` string, the SDK takes and returns a JavaScript \`Date\` object (the SDK types spell this \`type: "Date"\`).
+    - \`sdk.examples[].code\` are the SDK docs' JavaScript examples; prefer adapting one over composing a call from the schema. Query methods use the same WQL \`filter\`/\`sort\` rules and the same \`queryMethodData\` map as REST.
+    - No \`method.sdk\` means the SDK docs don't list that method: say so and offer the REST call instead of guessing an SDK signature. Where the method is listed, \`lightIndex\` carries the same call compactly as \`method.sdk\` (a string), with the package and namespace on the resource.
+    - For ExecuteWixAPI, keep using \`method.publicUrl\` and the REST \`requestBody\`; the SDK facet is for code the user will run, not for calls made through this MCP.
+
     Examples:
 
     Inspect one method schema by exact docs URL:
@@ -690,6 +716,39 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
     }
     \`\`\`
 
+    Get the JavaScript SDK call for a method — import, signature, typed parameters, return type, and a docs example (the docs URL may come from \`SearchWixSDKDocumentation\`, with or without \`?apiView=SDK\`):
+    \`\`\`javascript
+    async function() {
+      const methodUrl = "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products?apiView=SDK";
+
+      const schema = await getResourceSchemaByUrl(methodUrl);
+      const method = schema.methods.find(method => method.docsUrl === methodUrl.replace(/\\?.*$/, ""));
+      if (!method) return { message: "No exact method URL match", methods: schema.methods.map(m => ({ title: m.summary, docsUrl: m.docsUrl, sdk: m.sdk && m.sdk.method })) };
+      if (!method.sdk) return { message: "The SDK docs do not list this method; use the REST call.", publicUrl: method.publicUrl, requestBody: method.requestBody };
+
+      const { sdk } = method;
+      const types = schema.components.schemas;
+      // Each positional parameter, typed. The parameters body is pre-expanded for a method URL;
+      // any remaining { $circular: name } resolves against types[name].
+      const paramsSchema = sdk.requestBody?.content?.["application/json"]?.schema ?? {};
+      const parameters = sdk.signature.map(name => ({
+        name,
+        required: (paramsSchema.required ?? []).includes(name),
+        schema: paramsSchema.properties?.[name]
+      }));
+
+      return {
+        import: \`import { \${sdk.namespace} } from "\${sdk.package}";\`,
+        call: \`\${sdk.namespace}.\${sdk.method}(\${sdk.signature.join(", ")})\`,
+        parameters,
+        returns: sdk.responses ?? method.responses,
+        // Query methods: the same closed list of filterable/sortable fields applies to the SDK call.
+        queryFieldsCapabilities: method.queryMethodData?.queryFieldsCapabilitiesMap,
+        example: sdk.examples[0]
+      };
+    }
+    \`\`\`
+
     Inspect one resource by resource docs URL:
     \`\`\`javascript
     async function() {
@@ -894,11 +953,18 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
     Compose: put independent reads in one document as several root fields, and use related-entity fields (e.g. \`inventoryItems\`, \`collections\`, \`fulfillments\`) instead of extra round-trips. Select only the fields you need; every object field needs a selection set. Variables: use them for \`JSON\` scalars (filter, sort) and plain scalars (String, Int, ID), declared in the document (e.g. \`query Q($f: JSON) { ... filter: $f ... }\`). Write mutation inputs and any object that contains an enum INLINE as GraphQL literals with enum values unquoted (e.g. \`input: { product: { name: "Mug", productType: PHYSICAL } }\`) — this endpoint fails with 503 when an enum value arrives inside an object-typed variable. For lists page with \`cursorPaging\` or \`paging\` exactly as the input type declares (never the other one), and request \`pageInfo { hasNext total }\`; \`total\` is only populated with offset \`paging\`, so for a cursor-paged list count by walking pages or use a count operation.
     Results: each root field fails independently — \`errors[].path\` names the failing field and \`errors[].extensions.message\` the cause (e.g. PERMISSION_DENIED); \`data\` still holds the fields that succeeded. Mutations return the created/updated entity — read the IDs from it and do not re-query to verify. Large results are truncated: narrow the selection or page size instead of re-running.
     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.
+    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).
   `,
         CreateWixBusinessGuide: dedent `
     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. 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.
+    Exception, even when the user says "headless": if a finished page or site already exists in any form (their own HTML/CSS/JS, a static build, a zip, an AI-builder export, a page you made in this conversation) and they want it hosted, don't call this tool — call StartDeployWebsite, which returns the recipe to publish the files yourself. This guide's CLI flow is for BUILDING a headless frontend, not for hosting ready-made files.
 
     ## What This Tool Contains
 

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

@@ -107,7 +107,8 @@ export const paramDescriptions = {
     },
     ReadFullDocsArticle: {
         articleUrl: 'The URL of the docs article or method article to fetch. Should be something like https://dev.wix.com/docs/.../...' +
-            ' For REST docs, use the URL as-is. For SDK docs, the URL SHOULD include the query param ?apiView=SDK (e.g. https://dev.wix.com/docs/...?apiView=SDK).'
+            ' For REST docs, use the URL as-is. For SDK docs, the URL SHOULD include the query param ?apiView=SDK (e.g. https://dev.wix.com/docs/...?apiView=SDK).' +
+            ' Wix skills pages (https://www.wix.com/skills/..., https://dev.wix.com/docs/skills/...) are read as-is, including their referenced files.'
     },
     ReadFullDocsMethodSchema: {
         articleUrl: 'The URL of the documentation to fetch. Should be something like https://dev.wix.com/docs/.../...' +

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

@@ -19,6 +19,8 @@ export interface ReadmeDocConfig {
 export interface DocsToolsOptions {
     getToKnowWixEnabled?: boolean;
     createWixBusinessGuideEnabled?: boolean;
+    /** StartDeployWebsite (publish ready-made site files) — an account-owner flow; off for visitor servers. */
+    startDeployWebsiteEnabled?: boolean;
     disableTools?: string[];
     /** Custom descriptions for tools, keyed by tool name */
     toolDescriptions?: Record<string, string>;

package/build/dts/docs/docs.js

@@ -2,12 +2,13 @@ import { z } from 'zod';
 import { runSemanticSearchAndFormat } from './semanticSearch.js';
 import { logger } from '../infra/logger.js';
 import { captureException } from '@sentry/node';
-import { fetchArticleContent } from './fetch-article.js';
+import { fetchArticleContent, isSkillsRegistryUrl } from './fetch-article.js';
 import { normalizeMenuContent, summarizeLargeMenu, fetchMenuContent, MENU_CONTENT_THRESHOLD } from './normalize-menu-content.js';
 import { fetchPlatformizedMenu, MenuNotFoundError } from './browse-menu.js';
 import { isQueryOrSearchEndpoint, QUERY_CAPABILITY_MARKER } from './searchFormatting.js';
 import { addGetToKnowTools, addGetSiteContextTool } from './get-to-know.js';
 import { addCreateWixBusinessGuideTools } from './create-site-guide.js';
+import { addStartDeployWebsiteTool } from './start-deploy-website.js';
 import { defaultToolDescriptions } from '../config/default-config.js';
 import { desc } from '../config/param-descriptions.js';
 import dedent from 'dedent';
@@ -67,7 +68,7 @@ export const addDocsTools = (server, allowedTools = [
     'CLI',
     'OVERVIEW'
 ], options = {}) => {
-    const { getToKnowWixEnabled = false, createWixBusinessGuideEnabled = true, disableTools, toolDescriptions, readmeDocs, authStrategy, skillsPortalUrl, skillsRepo, repo, skillsPr, commitHash, skillsTags, dynamicContextEnabled, cliEnabled = false, usePlatformizedSearch = true, usePlatformizedBrowse = true } = options;
+    const { getToKnowWixEnabled = false, createWixBusinessGuideEnabled = true, startDeployWebsiteEnabled = true, disableTools, toolDescriptions, readmeDocs, authStrategy, skillsPortalUrl, skillsRepo, repo, skillsPr, commitHash, skillsTags, dynamicContextEnabled, cliEnabled = false, usePlatformizedSearch = true, usePlatformizedBrowse = true } = options;
     const effectiveRepo = repo ?? skillsRepo;
     const effectiveCommitHash = commitHash ?? skillsPr;
     // Helper to get description (custom or default)
@@ -123,6 +124,15 @@ export const addDocsTools = (server, allowedTools = [
         !disableTools?.includes('CreateWixBusinessGuide')) {
         addCreateWixBusinessGuideTools(server, disableTools || [], toolDescriptions, cliEnabled);
     }
+    // On by default: it is a routing slot, not a docs source — the agent with
+    // ready-made site files must find it next to the site-creation tools.
+    if (startDeployWebsiteEnabled) {
+        addStartDeployWebsiteTool(server, disableTools || [], toolDescriptions, {
+            skillsPortalUrl,
+            repo: effectiveRepo,
+            commitHash: effectiveCommitHash
+        });
+    }
     // WDS Documentation
     if (allowedTools.includes('WDS') &&
         !disableTools?.includes('SearchWixWDSDocumentation')) {
@@ -622,17 +632,20 @@ export const addDocsTools = (server, allowedTools = [
                 articleUrl: z.string().url().describe(d.articleUrl)
             };
         })(), { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ articleUrl }, { httpClient }) => {
-            // URL validation: only allow known docs prefixes
+            // URL validation: known docs prefixes, or a Wix skills registry page
+            // (https://www.wix.com/skills/..., https://dev.wix.com/docs/skills/...).
             const validPrefixes = ['https://dev.wix.com/docs/'];
             if (skillsPortalUrl)
                 validPrefixes.push(skillsPortalUrl);
-            if (!validPrefixes.some((p) => articleUrl.startsWith(p))) {
+            const isSkillsPage = isSkillsRegistryUrl(articleUrl);
+            if (!isSkillsPage &&
+                !validPrefixes.some((p) => articleUrl.startsWith(p))) {
                 return {
                     isError: true,
                     content: [
                         {
                             type: 'text',
-                            text: `Invalid article URL: must start with https://dev.wix.com/docs/. Got: "${articleUrl}"`
+                            text: `Invalid article URL: must start with https://dev.wix.com/docs/, or be a Wix skills page (https://www.wix.com/skills/...). Got: "${articleUrl}"`
                         }
                     ]
                 };
@@ -640,8 +653,9 @@ export const addDocsTools = (server, allowedTools = [
             // Every docs page has a .md twin whose menu pages link children WITH
             // the .md suffix, so agents that navigated the .md tree pass .md URLs
             // here — which 404 in get-article-content. Read the canonical page.
-            // (dev.wix.com only: on the skills portal .md is the real path.)
-            if (articleUrl.startsWith('https://dev.wix.com/docs/')) {
+            // (dev.wix.com docs only: on the skills registry .md is the real path.)
+            if (!isSkillsPage &&
+                articleUrl.startsWith('https://dev.wix.com/docs/')) {
                 articleUrl = articleUrl.replace(/\.md$/, '');
             }
             try {

package/build/dts/docs/fetch-article.d.ts

@@ -35,5 +35,6 @@ export declare function fetchRecipesIndex(): Promise<string>;
  * ```
  */
 export declare function fetchArticle(articleUrl: string): Promise<string>;
+export declare function isSkillsRegistryUrl(url: string): boolean;
 export declare function fetchArticleContent(httpClient: HttpClient, articleUrl: string, mode: 'article' | 'methodSchema' | 'raw', stripHeader?: boolean, skillsPortalUrl?: string, repo?: string, commitHash?: string, fetchMcpWhiteList?: boolean): Promise<string>;
 //# sourceMappingURL=fetch-article.d.ts.map

package/build/dts/docs/fetch-article.js

@@ -50,6 +50,38 @@ export async function fetchArticle(articleUrl) {
 // Internal implementation
 // ---------------------------------------------------------------------------
 const DOCS_URL_PREFIX = 'https://dev.wix.com/docs/';
+/**
+ * The Wix skills registry serves agent skills (SKILL.md and bundled files)
+ * as raw markdown straight from the `wix/skills` repo, on every host the
+ * gateway maps to it. Pages there are not docs articles: the rawdocs
+ * get-article-content API does not know them, and `.md` is a real path, so
+ * they are fetched as-is.
+ */
+const SKILLS_REGISTRY_URL = new RegExp('^https://(?:dev\\.wix\\.com(?:/docs)?|www\\.wix\\.com(?:/velo/reference)?)/skills(?:[/.?#]|$)');
+export function isSkillsRegistryUrl(url) {
+    return SKILLS_REGISTRY_URL.test(url.trim());
+}
+async function fetchSkillsRegistryPage(httpClient, url) {
+    let data;
+    try {
+        ({ data } = await httpClient.get(url, {
+            headers: { accept: 'text/markdown, text/plain;q=0.9, */*;q=0.1' }
+        }));
+    }
+    catch (error) {
+        const { message, status } = getHttpErrorDetails(error);
+        const statusSuffix = status ? ` (status ${status})` : '';
+        throw new Error(`${message}${statusSuffix}`);
+    }
+    if (typeof data !== 'string') {
+        // The manifest endpoint is JSON; anything else is text.
+        return JSON.stringify(data, null, 2);
+    }
+    if (!data.trim()) {
+        throw new Error('Article content is empty');
+    }
+    return data;
+}
 function getResponseErrorMessage(data) {
     if (!data) {
         return undefined;
@@ -152,10 +184,16 @@ export async function fetchArticleContent(httpClient, articleUrl, mode, stripHea
         }
         catch (error) {
             console.warn(`[fetch] Override failed for ${effectiveUrl}, falling back to ${articleUrl}:`, error instanceof Error ? error.message : error);
-            // Fall through to normal fetch
-            content = await fetchArticleContentFromDigor(httpClient, articleUrl, mode, stripHeader);
+            // Fall through to the normal fetch for this URL: the registry for a
+            // skills page (rawdocs cannot serve those), rawdocs otherwise.
+            content = isSkillsRegistryUrl(articleUrl)
+                ? await fetchSkillsRegistryPage(httpClient, articleUrl)
+                : await fetchArticleContentFromDigor(httpClient, articleUrl, mode, stripHeader);
         }
     }
+    else if (isSkillsRegistryUrl(articleUrl)) {
+        content = await fetchSkillsRegistryPage(httpClient, articleUrl);
+    }
     else if (mode === 'raw') {
         let parsedUrl;
         try {

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

@@ -0,0 +1,14 @@
+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_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";
+export declare function startDeployWebsiteResponse(recipe: string): string;
+export declare const START_DEPLOY_WEBSITE_POINTER_RESPONSE: string;
+export interface StartDeployWebsiteFetchOptions {
+    skillsPortalUrl?: string;
+    repo?: string;
+    commitHash?: string;
+}
+export declare function addStartDeployWebsiteTool(server: WixMcpServer, disableTools?: string[], toolDescriptions?: Record<string, string>, fetchOptions?: StartDeployWebsiteFetchOptions): void;
+//# sourceMappingURL=start-deploy-website.d.ts.map

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

@@ -0,0 +1,51 @@
+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.";
+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';
+const FALLBACK_LINE = `Only if you cannot run it (you can't reach the file bytes, or a step fails and you can't fix it): send the user to ${DROP_PAGE_URL} — give that URL exactly as written, keeping the utm_campaign=mcp parameter.`;
+// The tool exists to take the agent's attention at routing time; the work itself
+// is the recipe, so the response IS the recipe — fetched live and returned whole,
+// so the agent never has to decide whether to go read it.
+export function startDeployWebsiteResponse(recipe) {
+    return [
+        `The following is the content of ${START_DEPLOY_WEBSITE_RECIPE_URL}. Follow it end to end and do the publishing yourself — do not hand the user instructions.`,
+        FALLBACK_LINE,
+        '---',
+        recipe.trim()
+    ].join('\n\n');
+}
+// When the recipe can't be fetched, the pointer still routes correctly.
+export const START_DEPLOY_WEBSITE_POINTER_RESPONSE = [
+    `Read and follow this recipe end to end: ${START_DEPLOY_WEBSITE_RECIPE_URL}`,
+    'It covers creating the site and uploading the files (with or without a Wix login), updating a site deployed this way, and implementing a backend on it (stores, bookings, CMS, members) as a Wix Headless project. Do the publishing yourself — do not hand the user instructions.',
+    FALLBACK_LINE
+].join('\n\n');
+export function addStartDeployWebsiteTool(server, disableTools = [], toolDescriptions, fetchOptions = {}) {
+    if (disableTools.includes(START_DEPLOY_WEBSITE_TOOL_NAME)) {
+        return;
+    }
+    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)
+    }, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async (_args, { httpClient }) => {
+        let text = START_DEPLOY_WEBSITE_POINTER_RESPONSE;
+        try {
+            // Same path ReadFullDocsArticle takes for this page: the rawdocs article
+            // API, addressed without the .md suffix, header scaffolding stripped.
+            const recipe = await fetchArticleContent(httpClient, START_DEPLOY_WEBSITE_RECIPE_URL.replace(/\.md$/, ''), 'article', true, fetchOptions.skillsPortalUrl, fetchOptions.repo, fetchOptions.commitHash);
+            if (recipe && recipe.trim()) {
+                text = startDeployWebsiteResponse(recipe);
+            }
+        }
+        catch (error) {
+            console.warn(`[StartDeployWebsite] recipe fetch failed, returning the pointer:`, error instanceof Error ? error.message : error);
+        }
+        return { content: [{ type: 'text', text }] };
+    });
+}
+//# sourceMappingURL=start-deploy-website.js.map

package/build/dts/import-claude-design-tool/index.js

@@ -86,11 +86,11 @@ export function addImportClaudeDesignTool(server, authStrategy, options) {
             designUrl = new URL(args.url);
         }
         catch {
-            return errorResult("Invalid design URL — 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 — 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.");
+            return errorResult("Invalid design URL — this tool only accepts the claudeusercontent.com URL produced by Claude Design. For a page or site that exists in any other form (the user's files, a build, a zip, another builder's export, a page you made), do not retry this tool — call StartDeployWebsite, which returns the recipe to publish the files yourself. If that tool isn't available: read https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md and publish them yourself, or send the user to https://www.wix.com/headless/drop?utm_campaign=mcp.");
         }
         if (designUrl.protocol !== 'https:' ||
             !designUrl.hostname.endsWith(CLAUDE_USER_CONTENT_HOST_SUFFIX)) {
-            return errorResult("Invalid design URL — 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 — 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.");
+            return errorResult("Invalid design URL — this tool only accepts the claudeusercontent.com URL produced by Claude Design. For a page or site that exists in any other form (the user's files, a build, a zip, another builder's export, a page you made), do not retry this tool — call StartDeployWebsite, which returns the recipe to publish the files yourself. If that tool isn't available: read https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md and publish them yourself, or send the user to https://www.wix.com/headless/drop?utm_campaign=mcp.");
         }
         // Resolve the caller's account identity BEFORE the design fetch — the
         // design URL is single-use, so an unauthenticated caller must fail

package/build/dts/toolkit-entry.d.cts

@@ -127,6 +127,8 @@ export interface ReadmeDocConfig {
 export interface DocsToolsOptions {
 	getToKnowWixEnabled?: boolean;
 	createWixBusinessGuideEnabled?: boolean;
+	/** StartDeployWebsite (publish ready-made site files) — an account-owner flow; off for visitor servers. */
+	startDeployWebsiteEnabled?: boolean;
 	disableTools?: string[];
 	/** Custom descriptions for tools, keyed by tool name */
 	toolDescriptions?: Record<string, string>;

package/build/dts/toolkit-entry.d.ts

@@ -127,6 +127,8 @@ export interface ReadmeDocConfig {
 export interface DocsToolsOptions {
 	getToKnowWixEnabled?: boolean;
 	createWixBusinessGuideEnabled?: boolean;
+	/** StartDeployWebsite (publish ready-made site files) — an account-owner flow; off for visitor servers. */
+	startDeployWebsiteEnabled?: boolean;
 	disableTools?: string[];
 	/** Custom descriptions for tools, keyed by tool name */
 	toolDescriptions?: Record<string, string>;