@wix/mcp 1.0.94 → 1.0.95

package/build/dts/bin.js

@@ -95,7 +95,9 @@ if (docsTools.length > 0 || hasGetToKnowWix) {
     logger.log('Adding docs tools:', docsTools);
     addDocsTools(server, docsTools, {
         getToKnowWixEnabled: hasGetToKnowWix,
-        dynamicContextEnabled: hasDynamicContext
+        dynamicContextEnabled: hasDynamicContext,
+        // Mintlify docs: --docsSite=mintlify-links (or WIX_MCP_DOCS_SITE).
+        docsSite: parsedArgs['docsSite'] ?? process.env.WIX_MCP_DOCS_SITE
     });
 }
 if (activeTools.includes('VELO_README')) {

package/build/dts/code-mode/index.d.ts

@@ -20,8 +20,13 @@ export interface CodeModeOptions {
     };
     disableTools?: string[];
     toolDescriptions?: Record<string, string>;
-    /** Max response size in chars before truncation (default: 24,000, ~6,000 tokens). */
+    /** Max response size in chars before truncation (defaults: ExecuteWixAPI 100,000, SearchWixAPISpec 64,000). */
     maxResponseSize?: number;
+    /**
+     * The connection's docsSite (see ../docs/mintlify-docs.ts). SearchWixAPISpec
+     * passes it on, so a Mintlify mode also finds schemas by Mintlify page URL.
+     */
+    docsSite?: string;
 }
 export declare const EXECUTE_TOOL_NAME = "ExecuteWixAPI";
 export declare function addCodeModeTools(server: WixMcpServer, options: CodeModeOptions): Promise<void>;

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

@@ -1,11 +1,13 @@
 import { z } from 'zod';
 import { AttachmentError, resolveAttachments } from './attachments.js';
+import { fileParamNote } from '../config/file-params.js';
 import { logger } from '../infra/logger.js';
 import { defaultToolDescriptions } from '../config/default-config.js';
 import { truncateResponse } from './truncate-response.js';
 import { MAX_ALLOWED_RESPONSE_CHARS } from '../infra/response-size-limits.js';
 import { validateExecuteCode } from './validation.js';
 import { desc } from '../config/param-descriptions.js';
+import { isMintlifyDocsSite, rewriteDocsLinks, toDevWixHostText } from '../docs/mintlify-docs.js';
 import { rethrowIfUnauthorized } from '../auth/index.js';
 import { WixFetchError } from '../wix-fetch-error.js';
 import { addUploadHeadlessWebsiteFilesTool, UPLOAD_HEADLESS_WEBSITE_FILES_TOOL_NAME } from '../api-call/upload-headless-website-files.js';
@@ -44,13 +46,13 @@ export async function addCodeModeTools(server, options) {
  * lightIndex.
  */
 export function addSearchCodeModeTool(server, options) {
-    const { codeModeBaseUrl, codeModeFetch, authStrategy, disableTools = [], toolDescriptions, maxResponseSize } = options;
+    const { codeModeBaseUrl, codeModeFetch, authStrategy, disableTools = [], toolDescriptions, maxResponseSize, docsSite } = options;
     if (disableTools.includes(SEARCH_TOOL_NAME)) {
         return;
     }
     const description = toolDescriptions?.[SEARCH_TOOL_NAME] ??
         defaultToolDescriptions.SearchWixAPISpec;
-    registerSearchTool(server, codeModeBaseUrl, description, maxResponseSize, authStrategy, codeModeFetch);
+    registerSearchTool(server, codeModeBaseUrl, description, maxResponseSize, authStrategy, codeModeFetch, docsSite);
 }
 export function addExecuteCodeModeTool(server, options) {
     const { codeModeBaseUrl, codeModeFetch, authStrategy, visitor, disableTools = [], toolDescriptions, maxResponseSize } = options;
@@ -67,6 +69,9 @@ export function addExecuteCodeModeTool(server, options) {
     });
 }
 const SEARCH_MAX_RESPONSE_CHARS = 64_000;
+// ExecuteWixAPI's own default, ~25,000 tokens, so a full API listing comes back
+// whole. A session's maxResponseSize still overrides it.
+const EXECUTE_MAX_RESPONSE_CHARS = 100_000;
 /**
  * Search needs no auth of its own; without a header the call is bucketed by the
  * Worker's own IP (see postExecute). Anonymous sessions throw here and stay on
@@ -80,7 +85,7 @@ async function resolveLoopbackAuthorization(authStrategy) {
         return undefined;
     }
 }
-function registerSearchTool(server, codeModeBaseUrl, description, maxResponseSize, authStrategy, codeModeFetch = defaultCodeModeFetch) {
+function registerSearchTool(server, codeModeBaseUrl, description, maxResponseSize, authStrategy, codeModeFetch = defaultCodeModeFetch, docsSite) {
     const searchUrl = `${codeModeBaseUrl}/api/code-mode/search`;
     server.tool(SEARCH_TOOL_NAME, description, {
         code: z
@@ -99,7 +104,8 @@ function registerSearchTool(server, codeModeBaseUrl, description, maxResponseSiz
                     'Content-Type': 'application/json',
                     ...(authorization ? { Authorization: authorization } : {})
                 },
-                body: JSON.stringify({ code })
+                // docsSite only when set: without it the request is as before.
+                body: JSON.stringify(docsSite ? { code, docsSite } : { code })
             });
             if (!resp.ok) {
                 const errorBody = await resp.text();
@@ -126,7 +132,13 @@ function registerSearchTool(server, codeModeBaseUrl, description, maxResponseSiz
                     ]
                 };
             }
-            const text = truncateResponse(data.result, maxResponseSize ?? SEARCH_MAX_RESPONSE_CHARS);
+            // Mintlify docs: the index shows docsUrls on the Mintlify host by rule.
+            // Map them back, then resolve each to its Mintlify page as the docs tools
+            // do, so a page the site doesn't have keeps its dev.wix.com link.
+            const result = isMintlifyDocsSite(docsSite) && data.result !== undefined
+                ? JSON.parse((await rewriteDocsLinks(toDevWixHostText(JSON.stringify(data.result)), { label: 'search SearchWixAPISpec' })).text)
+                : data.result;
+            const text = truncateResponse(result, maxResponseSize ?? SEARCH_MAX_RESPONSE_CHARS);
             return {
                 content: [{ type: 'text', text }]
             };
@@ -167,10 +179,13 @@ async function postExecute(executeUrl, body, authorization, codeModeFetch = defa
     }
     return (await resp.json());
 }
-function executeErrorResult(message) {
+function executeErrorResult(message, failedCalls) {
     return {
         isError: true,
-        content: [{ type: 'text', text: `Execute error: ${message}` }]
+        content: [{ type: 'text', text: `Execute error: ${message}` }],
+        // The failed calls as fields, request ids included. The text carries the
+        // ids too, for clients that don't read structured results.
+        ...(failedCalls?.length ? { structuredContent: { failedCalls } } : {})
     };
 }
 function executeTextResult(message) {
@@ -180,7 +195,7 @@ function executeTextResult(message) {
 }
 function formatExecuteResult(data, maxResponseSize, reportBi) {
     if (data.error) {
-        return executeErrorResult(data.error);
+        return executeErrorResult(data.error, data.failedCalls);
     }
     // Before the slice -- resultTextLength is measured after it and saturates.
     reportBi?.({
@@ -203,7 +218,10 @@ function formatExecuteResult(data, maxResponseSize, reportBi) {
     }
     return {
         content: [
-            { type: 'text', text: truncateResponse(data.result, maxResponseSize) }
+            {
+                type: 'text',
+                text: truncateResponse(data.result, maxResponseSize ?? EXECUTE_MAX_RESPONSE_CHARS)
+            }
         ]
     };
 }
@@ -269,7 +287,8 @@ function addExecuteTool(server, options) {
             mime_type: z.string().optional()
         }))
             .optional()
-            .describe('ChatGPT only. Files attached in the chat or created in your sandbox (any type: a zip of a site, HTML, images, PDFs): pass each file as you have it, its file id or its /mnt/data path, and ChatGPT swaps it for { download_url, file_id, file_name?, mime_type? } before the call reaches Wix. No other client does this swap, so outside ChatGPT a path or file:// URL here fails at once; leave this out and use `files`, or upload from your shell if it reaches the internet. 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.'),
+            .describe(fileParamNote('use `files`, or upload from your shell if it reaches the internet') +
+            ' Any type: a zip of a site, HTML, images, PDFs. 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
@@ -360,6 +379,7 @@ function addExecuteTool(server, options) {
                 sessionId,
                 toolInvocationId,
                 clientName: server.server?.getClientVersion?.()?.name,
+                ...(visitor ? { visitorMode: true } : {}),
                 // A visitor token is a site-scoped bearer token: sent as siteToken
                 // (→ Authorization + wix-site-id) and as accountToken only to satisfy
                 // the runtime's required field. Account/site mode uses strategy tokens.

package/build/dts/code-mode/truncate-response.js

@@ -17,6 +17,10 @@ export function truncateResponse(content, maxChars = DEFAULT_MAX_CHARS) {
     const truncated = text.slice(0, effectiveMax);
     const estimatedTokens = Math.ceil(text.length / CHARS_PER_TOKEN);
     const limitTokens = Math.ceil(effectiveMax / CHARS_PER_TOKEN);
-    return `${truncated}\n\n--- TRUNCATED ---\nResponse was ~${estimatedTokens.toLocaleString()} tokens (limit: ${limitTokens.toLocaleString()}). Refine your code to return less data.`;
+    const cutChars = text.length - effectiveMax;
+    const note = `Response was ~${estimatedTokens.toLocaleString()} tokens (limit: ${limitTokens.toLocaleString()}). Showing the first ${effectiveMax.toLocaleString()} of ${text.length.toLocaleString()} characters; the last ${cutChars.toLocaleString()} were cut. To get the rest, run again and return less per call — only the fields you need, the next page (cursor or offset), or the next slice of a large array — and repeat until you have it all.`;
+    // At the top as well as the end: a client that cuts a long result keeps its
+    // head, so a note only at the end is the first thing lost.
+    return `[TRUNCATED: ${note}]\n\n${truncated}\n\n--- TRUNCATED ---\n${note}`;
 }
 //# sourceMappingURL=truncate-response.js.map

package/build/dts/config/default-config.d.ts

@@ -21,29 +21,48 @@ export interface ModeDefaultConfig {
     skillsPrOverrideEnabled?: boolean;
     graphqlEnabled?: boolean;
 }
+/**
+ * CallWixSiteAPI's advice when the Wix MCP lists no ExecuteWixAPI. True only where the server serves
+ * ExecuteWixAPI (a client with an old or cached tool list); `addApiCallTool` swaps it for
+ * `CALL_WIX_SITE_API_NO_EXECUTE_LINE` where ExecuteWixAPI is off on purpose.
+ */
+export declare const CALL_WIX_SITE_API_RECONNECT_LINE = "If the Wix MCP offers no ExecuteWixAPI at all, your Wix connection is likely an old or cached version: tell the user once to reconnect the Wix connector or restart the client, and use this tool until then.";
+export declare const CALL_WIX_SITE_API_NO_EXECUTE_LINE = "If ExecuteWixAPI isn't in your tool list, use this tool.";
 export declare const SYSTEM_REMINDER_GUIDELINES: string;
 export declare function buildSystemReminder(includeReadme: boolean, includeImageUploadGuidance?: boolean): string;
 export declare const SYSTEM_REMINDER: string;
+/** SearchWixHelpCenter's description and response both carry this: Help Center is for people, the developer docs for the agent's own actions. */
+export declare const HELP_CENTER_IS_FOR_PEOPLE = "The Help Center is written for people doing things by hand in Wix's dashboard and editors. To act on a site yourself, the Wix developer docs come first: find the method with SearchWixRESTDocumentation or BrowseWixRESTDocsMenu.";
+/**
+ * The MCP server's \`instructions\`, sent in its reply to initialize. Clients that show them
+ * (ChatGPT and Codex use the first 512 characters; Claude Code loads them at session start and
+ * cuts at 4,096) get the site-creation routing before any tool definition. Sent only to a session
+ * that has every tool it names (SERVER_INSTRUCTIONS_TOOLS).
+ * Each tool named here carries a comment pointing back to this text. A change to any of them (a
+ * name, what it is for, a new site-creation tool) updates this text and that list with it.
+ */
+export declare const SERVER_INSTRUCTIONS = "Wix: build and manage Wix sites. A new site is written in code and uploaded: StartDeployWebsite returns the upload guide; StartHeadlessBuild returns the headless guide, for a site that needs Wix business features (forms, a store, bookings, a CMS, members, payments). WixSiteBuilder or SearchSiteTemplates only when the user asked for Wix's editor, the Wix Harmony Editor, a template, Wix Studio or the Classic Editor. For anything else, except ListWixSites and UploadImageToWixSite, call WixREADME first.";
+/** The tools SERVER_INSTRUCTIONS names. */
+export declare const SERVER_INSTRUCTIONS_TOOLS: string[];
 export declare const SITE_CREATION_COPY: {
     readonly templatePick: {
         readonly nonWidget: "After the user selects a template, call `CreateSiteFromTemplate`.";
         readonly widget: "The gallery creates the site when the user picks one.";
     };
-    readonly unstatedMethod: {
-        readonly nonWidget: "you MUST ask whether they want to build with AI or start from a template, and create nothing and show nothing until they answer";
-        readonly widget: "you MUST call `WixSiteCreation` and let them choose";
-    };
 };
 /** Rewrites non-widget copy into its widget form; a no-op on text that carries no divergence. */
 export declare const toWidget: (text: string) => string;
 export declare const executeWixApiDescription: string;
-export declare function buildToolDescriptions(includeReadme: boolean, includeImageUploadGuidance?: boolean): Record<string, string>;
+export declare function buildToolDescriptions(includeReadme: boolean, includeImageUploadGuidance?: boolean, { usageGuideOnce }?: {
+    usageGuideOnce?: boolean;
+}): Record<string, string>;
 /**
  * Canonical (README-inclusive) tool descriptions used by the live MCP server and
  * all existing importers.
  */
 export declare const defaultToolDescriptions: Record<string, string>;
 export declare const executeCodeModeToolDescriptions: Record<string, string>;
+export declare const WIX_SKILLS_README_SECTION: string;
 /**
  * Default readme docs - content for WixREADME tool response.
  * Assumes both ExecuteWixAPI and SearchWixAPISpec are available (execute-and-search mode).
@@ -51,6 +70,9 @@ export declare const executeCodeModeToolDescriptions: Record<string, string>;
  * Joined rather than interpolated into one `dedent` — `dedent` reads indentation from the literal
  * parts only, so a multi-line interpolation gets flattened.
  */
+export declare function buildReadmeDocs({ recipesIndex }?: {
+    recipesIndex?: boolean;
+}): ReadmeDocConfig[];
 export declare const defaultReadmeDocs: ReadmeDocConfig[];
 /**
  * Merge base config with overrides
@@ -64,6 +86,14 @@ export declare function mergeConfig(base: ModeDefaultConfig, overrides: Partial<
  * All tools enabled, all descriptions, good readmeDocs
  */
 export declare const defaultConfig: ModeDefaultConfig;
+/**
+ * For a session without WixREADME (mode=code, getToKnowWixEnabled off, WixREADME disabled): the
+ * usage guide WixREADME carries goes back onto every tool, as it was before usageGuideOnce.
+ * Custom tool descriptions are kept.
+ */
+export declare function withUsageGuideOnEveryTool<Config extends {
+    toolDescriptions?: Record<string, string>;
+}>(config: Config): Config;
 /**
  * Delta for clients that declared the MCP-Apps UI extension. Merged over the mode config at
  * request time, since the mode override and the widget variant have to compose.