@wix/mcp 1.0.94 → 1.0.96

package/build/dts/docs/mintlify-docs.js

@@ -0,0 +1,391 @@
+import { logger } from '../infra/logger.js';
+/**
+ * Mintlify docs, `mintlify-links` mode (wix-private/docs:
+ * documentation/mintlify-migration/tasks/mcp-pipeline.md).
+ *
+ * The KBs and every backend stay as they are. With `docsSite: 'mintlify-links'`,
+ * the docs tools resolve each dev.wix.com docs link in their output to its page
+ * on the Mintlify site, and ReadFullDocsArticle reads pages from Mintlify's
+ * `.md`. Off unless a caller passes the option.
+ */
+export const MINTLIFY_LINKS_DOCS_SITE = 'mintlify-links';
+/** Stage 2: the same, with search on the Mintlify KBs indexed from the Mintlify site. */
+export const MINTLIFY_DOCS_SITE = 'mintlify';
+export const MINTLIFY_HOST = 'https://wix-internal.mintlify.site';
+const MINTLIFY_HOSTNAMES = new Set([
+    'wix-internal.mintlify.site',
+    'wix-internal.mintlify.app'
+]);
+const DEV_WIX_DOCS = 'https://dev.wix.com/docs';
+// dev.wix.com portal slug -> Mintlify tab base, where the two differ.
+const PORTAL_SLUG_TO_TAB = {
+    rest: 'api-reference',
+    'mintlify-sandbox': 'sandbox'
+};
+const TAB_TO_PORTAL_SLUG = {
+    sandbox: 'mintlify-sandbox'
+};
+// The tabs the Mintlify site serves. A dev.wix.com link into any other portal
+// (sdk, velo, build-apps, ...) has no page there yet.
+const MINTLIFY_TABS = new Set(['api-reference', 'sandbox', 'kb']);
+// The skills registry is served on dev.wix.com/docs/skills and is not part of
+// the docs site, so its links are left alone.
+const NON_DOCS_SLUGS = new Set(['skills', 'kb-only', 'api']);
+const CHECK_TTL_MS = 10 * 60 * 1000;
+// Bounds the page-check cache, so many distinct paths can't grow it without limit.
+export const MAX_CHECK_ENTRIES = 5000;
+const CHECK_TIMEOUT_MS = 5000;
+const MAX_REDIRECTS = 3;
+const CHECK_CONCURRENCY = 8;
+export function isMintlifyDocsSite(docsSite) {
+    return (docsSite === MINTLIFY_LINKS_DOCS_SITE || docsSite === MINTLIFY_DOCS_SITE);
+}
+// docs-search-server document types that read the Mintlify KBs instead of today's.
+const MINTLIFY_DOCUMENT_TYPES = {
+    REST: ['MINTLIFY_REST'], // includes the skills, as REST + SKILLS does today
+    SDK: ['MINTLIFY_SDK']
+};
+/** The Mintlify document types a search tool uses in stage 2, or undefined to search as today. */
+export function mintlifyDocumentTypes(docsSite, toolName) {
+    return docsSite === MINTLIFY_DOCS_SITE
+        ? MINTLIFY_DOCUMENT_TYPES[toolName]
+        : undefined;
+}
+export function isMintlifyUrl(url) {
+    try {
+        return MINTLIFY_HOSTNAMES.has(new URL(url).hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/** The URL prefixes the docs tools accept in Mintlify mode, besides dev.wix.com. */
+export const MINTLIFY_URL_PREFIXES = [...MINTLIFY_HOSTNAMES].map((host) => `https://${host}/`);
+function cleanPath(pathname) {
+    const path = pathname.replace(/\.md$/, '').replace(/\/+$/, '');
+    return path === '' ? '/' : path;
+}
+function flavourOf(url) {
+    return url.searchParams.get('apiView')?.toUpperCase() === 'SDK'
+        ? 'sdk'
+        : 'rest';
+}
+/**
+ * Maps a dev.wix.com docs URL, or a Mintlify URL on any alias host, to its
+ * Mintlify page by rule: drop `/docs`, map the portal slug to its tab, drop
+ * the query, the anchor and `.md`. Returns null for anything else.
+ */
+export function toMintlifyCandidate(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return null;
+    }
+    if (MINTLIFY_HOSTNAMES.has(url.hostname)) {
+        const path = cleanPath(url.pathname);
+        return { url: `${MINTLIFY_HOST}${path}`, path, flavour: flavourOf(url) };
+    }
+    if (url.hostname !== 'dev.wix.com' || !url.pathname.startsWith('/docs/')) {
+        return null;
+    }
+    const segments = cleanPath(url.pathname.slice('/docs'.length))
+        .split('/')
+        .filter(Boolean);
+    if (segments.length === 0 || NON_DOCS_SLUGS.has(segments[0])) {
+        return null;
+    }
+    segments[0] = PORTAL_SLUG_TO_TAB[segments[0]] ?? segments[0];
+    const path = `/${segments.join('/')}`;
+    return { url: `${MINTLIFY_HOST}${path}`, path, flavour: flavourOf(url) };
+}
+/**
+ * Maps a Mintlify URL back to its dev.wix.com docs URL, keeping `?apiView=SDK`.
+ * For the REST portal the paths are the same, so the backends that only know
+ * dev.wix.com (ingvar, the docs menu) can serve it.
+ */
+export function toDevWixUrl(rawUrl) {
+    const url = new URL(rawUrl);
+    const segments = cleanPath(url.pathname).split('/').filter(Boolean);
+    if (segments.length > 0) {
+        segments[0] = TAB_TO_PORTAL_SLUG[segments[0]] ?? segments[0];
+    }
+    const query = flavourOf(url) === 'sdk' ? '?apiView=SDK' : '';
+    return `${DEV_WIX_DOCS}/${segments.join('/')}${query}`;
+}
+const checkCache = new Map();
+/** Caches a page check, dropping expired entries, then the oldest, once full. */
+function rememberCheck(path, result) {
+    const now = Date.now();
+    checkCache.delete(path);
+    if (checkCache.size >= MAX_CHECK_ENTRIES) {
+        for (const [key, entry] of checkCache) {
+            if (entry.expires <= now)
+                checkCache.delete(key);
+        }
+    }
+    while (checkCache.size >= MAX_CHECK_ENTRIES) {
+        const oldest = checkCache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        checkCache.delete(oldest);
+    }
+    checkCache.set(path, { result, expires: now + CHECK_TTL_MS });
+}
+/** For tests. */
+export function mintlifyCheckCacheSize() {
+    return checkCache.size;
+}
+/** For tests. */
+export function clearMintlifyCheckCache() {
+    checkCache.clear();
+}
+async function headOnce(url) {
+    return fetch(url, {
+        method: 'HEAD',
+        redirect: 'manual',
+        signal: AbortSignal.timeout(CHECK_TIMEOUT_MS)
+    });
+}
+/**
+ * Asks the Mintlify site whether a page exists, following its own redirects
+ * (moves, and containers that send you to their first page) without
+ * following them blindly: a page is a 200 at the end of at most 3 hops.
+ */
+export async function checkMintlifyPage(path) {
+    const cached = checkCache.get(path);
+    if (cached && cached.expires > Date.now()) {
+        return cached.result;
+    }
+    if (cached)
+        checkCache.delete(path);
+    let result;
+    try {
+        let current = path;
+        let hops = 0;
+        for (;;) {
+            const response = await headOnce(`${MINTLIFY_HOST}${current}`);
+            if (response.status === 200) {
+                result = {
+                    outcome: hops === 0 ? 'identity' : 'redirect',
+                    path: current
+                };
+                break;
+            }
+            const location = response.headers.get('location');
+            if (response.status >= 300 &&
+                response.status < 400 &&
+                location &&
+                hops < MAX_REDIRECTS) {
+                current = cleanPath(new URL(location, MINTLIFY_HOST).pathname);
+                hops++;
+                continue;
+            }
+            result = { outcome: response.status === 404 ? 'missing' : 'error' };
+            break;
+        }
+    }
+    catch (error) {
+        logger.error(`[mintlify] page check failed for ${path}: ${error}`);
+        result = { outcome: 'error' };
+    }
+    rememberCheck(path, result);
+    return result;
+}
+/**
+ * Resolves one docs link to its Mintlify page. With `verify: false` the
+ * mapping is by rule only, which suits menu links (the menu and the Mintlify
+ * navigation come from the same Portal Service tree).
+ */
+export async function resolveDocsLink(rawUrl, { verify = true } = {}) {
+    const candidate = toMintlifyCandidate(rawUrl);
+    if (!candidate) {
+        return { outcome: 'not-docs', url: rawUrl };
+    }
+    const tab = candidate.path.split('/')[1];
+    if (!MINTLIFY_TABS.has(tab)) {
+        return { outcome: 'other-portal', url: rawUrl };
+    }
+    const query = candidate.flavour === 'sdk' ? '?apiView=SDK' : '';
+    if (!verify) {
+        return { outcome: 'identity', url: `${candidate.url}${query}` };
+    }
+    const check = await checkMintlifyPage(candidate.path);
+    if (check.path) {
+        return {
+            outcome: check.outcome,
+            url: `${MINTLIFY_HOST}${check.path}${query}`
+        };
+    }
+    return { outcome: check.outcome, url: rawUrl };
+}
+// A docs link inside text: markdown targets, bare URLs and "fallback::" forms.
+// Stops at whitespace and markdown/HTML delimiters.
+const DOCS_LINK_PATTERN = /https:\/\/(?:dev\.wix\.com\/docs|wix-internal\.mintlify\.(?:site|app))\/[^\s)\]"'<>`]*/g;
+function trimTrailingPunctuation(url) {
+    return url.replace(/[.,;:!?*]+$/, '');
+}
+// A Mintlify page link inside text, with the same delimiters as DOCS_LINK_PATTERN.
+const MINTLIFY_LINK_PATTERN = /https:\/\/wix-internal\.mintlify\.(?:site|app)\/[^\s)\]"'<>`]*/g;
+/**
+ * Maps every Mintlify page link in `text` back to its dev.wix.com docs URL, keeping
+ * `?apiView=SDK` and the anchor. Run before {@link rewriteDocsLinks} on text whose
+ * Mintlify links came by rule rather than from a checked page (SearchWixAPISpec's
+ * index), so a page the site doesn't have ends up on dev.wix.com, not a dead link.
+ */
+export function toDevWixHostText(text) {
+    return text.replace(MINTLIFY_LINK_PATTERN, (match) => {
+        const link = trimTrailingPunctuation(match);
+        let url;
+        try {
+            url = new URL(link);
+        }
+        catch {
+            return match;
+        }
+        // Only docs pages: other paths on the host (llms.txt, assets) have no
+        // dev.wix.com twin, and rewriteDocsLinks leaves them as they are.
+        if (!MINTLIFY_TABS.has(url.pathname.split('/')[1] ?? ''))
+            return match;
+        return toDevWixUrl(link) + url.hash + match.slice(link.length);
+    });
+}
+async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (next < items.length) {
+            const index = next++;
+            results[index] = await fn(items[index]);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+/**
+ * Rewrites every docs link in `text` to its Mintlify page. Links with no
+ * Mintlify page stay as they are, so the agent can still read them through
+ * today's backends. Logs one coverage line per call.
+ */
+export async function rewriteDocsLinks(text, { verify = true, label = 'text' } = {}) {
+    const found = [
+        ...new Set((text.match(DOCS_LINK_PATTERN) ?? []).map(trimTrailingPunctuation))
+    ];
+    const stats = {
+        links: found.length,
+        byOutcome: {},
+        misses: []
+    };
+    if (found.length === 0) {
+        return { text, stats };
+    }
+    const resolved = await mapWithConcurrency(found, CHECK_CONCURRENCY, (url) => resolveDocsLink(url, { verify }));
+    const replacements = new Map();
+    found.forEach((url, i) => {
+        const { outcome, url: target } = resolved[i];
+        stats.byOutcome[outcome] = (stats.byOutcome[outcome] ?? 0) + 1;
+        if (outcome === 'identity' || outcome === 'redirect') {
+            if (target !== url)
+                replacements.set(url, target);
+        }
+        else if (outcome !== 'not-docs') {
+            stats.misses.push(`${outcome} ${url}`);
+        }
+    });
+    // Rewrite each match in place, so a link never changes through a shorter
+    // link it starts with.
+    const rewritten = text.replace(DOCS_LINK_PATTERN, (match) => {
+        const url = trimTrailingPunctuation(match);
+        const target = replacements.get(url);
+        return target ? target + match.slice(url.length) : match;
+    });
+    logger.log(`[mintlify] ${label}: ${stats.links} links ${JSON.stringify(stats.byOutcome)}` +
+        (stats.misses.length
+            ? ` misses: ${stats.misses.slice(0, 10).join(' | ')}`
+            : ''));
+    return { text: rewritten, stats };
+}
+// The index banner Mintlify puts at the top of every .md page.
+const INDEX_BANNER = /^> ## Documentation Index\n(?:>.*\n)*\n?/;
+// Mintlify inlines the source of every imported snippet component
+// (`export const WixEndpoint = (...) => { ... };`): code, not docs.
+const INLINED_SNIPPET = /^export const \w+ = [\s\S]*?^};\n/gm;
+const REST_TAB = /<Tab title="REST">([\s\S]*?)<\/Tab>/;
+const SDK_TAB = /<Tab title="SDK">([\s\S]*?)<\/Tab>/;
+/**
+ * Light cleanup of a method page's .md: drop inlined snippet source, and keep
+ * only the tab the reader asked for (REST, or SDK for `?apiView=SDK`). A
+ * method page carries both, which roughly doubles its size. Pages without
+ * exactly one REST and one SDK tab are left as they are.
+ */
+export function cleanMintlifyMarkdown(markdown, flavour) {
+    const text = markdown.replace(INLINED_SNIPPET, '');
+    const rest = text.match(REST_TAB);
+    const sdk = text.match(SDK_TAB);
+    if (!rest || !sdk || (text.match(/<Tab title=/g) ?? []).length !== 2) {
+        return text;
+    }
+    const start = text.lastIndexOf('<Tabs>', rest.index);
+    const end = text.indexOf('</Tabs>', sdk.index);
+    if (start === -1 || end === -1) {
+        return text;
+    }
+    const kept = (flavour === 'sdk' ? sdk : rest)[1];
+    const note = flavour === 'sdk'
+        ? '_This is the SDK view. Drop `?apiView=SDK` from the URL for the REST view._'
+        : '_This is the REST view. Add `?apiView=SDK` to the URL for the JavaScript SDK view._';
+    return `${text.slice(0, start)}${note}\n\n${kept.trim()}\n${text.slice(end + '</Tabs>'.length)}`;
+}
+// A docs URL in tool text that the Mintlify site has: API Reference, or a `…` placeholder.
+// Skills URLs (dev.wix.com/docs/skills) are the skills registry and stay.
+const DOCS_URL_IN_TEXT = /https:\/\/dev\.wix\.com\/docs\/(?=api-reference\b|\.\.\.)/g;
+/**
+ * Tool and parameter descriptions with their docs URLs on the Mintlify host. The
+ * model copies the examples' host when it cites a page, so with dev.wix.com in
+ * the descriptions it rewrites Mintlify links back to dev.wix.com.
+ */
+export function toMintlifyHostText(text) {
+    return text.replace(DOCS_URL_IN_TEXT, `${MINTLIFY_HOST}/`);
+}
+// A Markdown link or an href to a path on the same site: `](/…` or `href="/…`.
+const SITE_RELATIVE_LINK = /(\]\(|href=["'])\/(?!\/)/g;
+/**
+ * Mintlify's .md links the site's own pages by path (`[Order Object](/api-reference/…)`).
+ * Make them absolute, so the model doesn't have to guess the host (it picks dev.wix.com).
+ */
+export function absolutizeSiteLinks(markdown) {
+    return markdown.replace(SITE_RELATIVE_LINK, (_, open) => `${open}${MINTLIFY_HOST}/`);
+}
+/**
+ * Reads a page from the Mintlify site as Markdown. Returns null when the site
+ * has no page for the URL, so the caller can fall back to today's backend.
+ */
+export async function readMintlifyMarkdown(rawUrl) {
+    const resolved = await resolveDocsLink(rawUrl);
+    if (resolved.outcome !== 'identity' && resolved.outcome !== 'redirect') {
+        return null;
+    }
+    const pageUrl = new URL(resolved.url);
+    const response = await fetch(`${MINTLIFY_HOST}${pageUrl.pathname}.md`, {
+        headers: { accept: 'text/markdown' },
+        redirect: 'follow',
+        signal: AbortSignal.timeout(15000)
+    });
+    if (response.status === 404) {
+        return null;
+    }
+    if (!response.ok) {
+        throw new Error(`Mintlify returned ${response.status} for ${pageUrl.pathname}.md`);
+    }
+    const flavour = toMintlifyCandidate(rawUrl)?.flavour ?? 'rest';
+    const cleaned = cleanMintlifyMarkdown((await response.text()).replace(INDEX_BANNER, ''), flavour);
+    // The page body still links other pages on dev.wix.com; resolve those too.
+    const { text: rewritten } = await rewriteDocsLinks(cleaned, {
+        label: `read ${pageUrl.pathname}`
+    });
+    const markdown = absolutizeSiteLinks(rewritten);
+    logger.log(`[mintlify] read ${pageUrl.pathname}.md (${markdown.length} chars) for ${rawUrl}`);
+    return { url: `${MINTLIFY_HOST}${pageUrl.pathname}`, markdown };
+}
+//# sourceMappingURL=mintlify-docs.js.map

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

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

package/build/dts/docs/semanticSearch.js

@@ -46,6 +46,9 @@ const runSemanticSearch = async (toolName, toolParams, maxResults = 20, rerank =
     else if (toolName === 'CLI') {
         kbNames.push('CLI_KB_ID');
     }
+    else if (toolName === 'HELP_CENTER') {
+        kbNames.push('HELP_CENTER_KB_ID');
+    }
     logger.log(`[SemanticSearch] Tool: ${toolName}, KBs: [${kbNames.join(', ')}], Query: "${toolParams.searchTerm}"`);
     for (const kbName of kbNames) {
         url.searchParams.append('kbName', kbName);
@@ -70,13 +73,16 @@ 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, extraDocumentTypes) => {
+const runPlatformizedSemanticSearch = async (toolName, searchTerm, maxResults = 20, linesInEachResult, extraDocumentTypes, documentTypesOverride) => {
     const startTime = Date.now();
     // 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;
+    // An override replaces the tool's own types (the Mintlify KBs).
+    const documentTypes = documentTypesOverride?.length
+        ? documentTypesOverride
+        : 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',
@@ -105,9 +111,10 @@ const runPlatformizedSemanticSearch = async (toolName, searchTerm, maxResults =
     }
     return content;
 };
-export const runSemanticSearchAndFormat = async ({ toolName, toolParams, maxResults = DEFAULT_MAX_RESULTS, rerank, linesInEachResult, usePlatformizedSearch = true, extraDocumentTypes }) => {
-    if (usePlatformizedSearch) {
-        return runPlatformizedSemanticSearch(toolName, toolParams.searchTerm, maxResults, linesInEachResult, extraDocumentTypes);
+export const runSemanticSearchAndFormat = async ({ toolName, toolParams, maxResults = DEFAULT_MAX_RESULTS, rerank, linesInEachResult, usePlatformizedSearch = true, extraDocumentTypes, documentTypes }) => {
+    // A document-type override names platformized types; the legacy path can't honor it.
+    if (usePlatformizedSearch || documentTypes?.length) {
+        return runPlatformizedSemanticSearch(toolName, toolParams.searchTerm, maxResults, linesInEachResult, extraDocumentTypes, documentTypes);
     }
     else {
         const results = await runSemanticSearch(toolName, toolParams, maxResults, rerank);

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

@@ -1,11 +1,12 @@
 import { WixMcpServer } from '../wix-mcp-server.js';
+export declare const NO_PERSONAL_DATA = "No personal data: no names, emails, phones, passwords, keys or local paths.";
 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.";
+    readonly userRequest: "A short summary of what the user asked for and the context that led here, in a sentence or two, including whether this is a new site or an edit or new version of a site already on Wix. No personal data: no names, emails, phones, passwords, keys or local paths.";
+    readonly siteDescription: "What the site is: its purpose and who it is for. One or two sentences. No personal data: no names, emails, phones, passwords, keys or local paths.";
+    readonly siteForm: "The form the site exists in right now (HTML/CSS/JS files, a static build, a zip, a framework project, another builder's export, a design created in this conversation, or something else), roughly how many files, and whether it includes images. For a framework project: which framework, whether you have its built static output (for example dist/) or only the source, and whether it needs a server at runtime (SSR, API routes, a backend), or that you don't know. Also where it came from: built in this conversation, the user's own project or repo, another builder (which one), or a Wix skill or template (which one). No personal data: no names, emails, phones, passwords, keys or local paths.";
+    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. No personal data: no names, emails, phones, passwords, keys or local paths.";
+    readonly agentIdentity: "Which agent or product you are, which model if you know it, and the harness you run in. No personal data: no names, emails, phones, passwords, keys or local paths.";
+    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; which Wix identity you act with — the user's login through this MCP, a CLI login, or none; and which Wix skills you have (for example wix-headless-kit or wix-manage), by name and where they come from (installed on disk, a plugin, read online), or none. Name the kind of identity, not the account or its email. No personal data: no names, emails, phones, passwords, keys or local paths.";
 };
 export declare const START_DEPLOY_WEBSITE_PARAMS: Array<keyof typeof START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS>;
 export declare const START_DEPLOY_WEBSITE_TOOL_NAME = "StartDeployWebsite";

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

@@ -1,28 +1,33 @@
 import { z } from 'zod';
 import { defaultToolDescriptions } from '../config/default-config.js';
 import { fetchArticleContent } from './fetch-article.js';
+// Personal data in these fields is also redacted before they are recorded
+// (redact-personal-data.ts); this line keeps it out in the first place.
+export const NO_PERSONAL_DATA = 'No personal data: no names, emails, phones, passwords, keys or local paths.';
 // 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."
+    userRequest: `A short summary of what the user asked for and the context that led here, in a sentence or two, including whether this is a new site or an edit or new version of a site already on Wix. ${NO_PERSONAL_DATA}`,
+    siteDescription: `What the site is: its purpose and who it is for. One or two sentences. ${NO_PERSONAL_DATA}`,
+    siteForm: `The form the site exists in right now (HTML/CSS/JS files, a static build, a zip, a framework project, another builder's export, a design created in this conversation, or something else), roughly how many files, and whether it includes images. For a framework project: which framework, whether you have its built static output (for example dist/) or only the source, and whether it needs a server at runtime (SSR, API routes, a backend), or that you don't know. Also where it came from: built in this conversation, the user's own project or repo, another builder (which one), or a Wix skill or template (which one). ${NO_PERSONAL_DATA}`,
+    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. ${NO_PERSONAL_DATA}`,
+    agentIdentity: `Which agent or product you are, which model if you know it, and the harness you run in. ${NO_PERSONAL_DATA}`,
+    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; which Wix identity you act with — the user's login through this MCP, a CLI login, or none; and which Wix skills you have (for example wix-headless-kit or wix-manage), by name and where they come from (installed on disk, a plugin, read online), or none. Name the kind of identity, not the account or its email. ${NO_PERSONAL_DATA}`
 };
 export const START_DEPLOY_WEBSITE_PARAMS = Object.keys(START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS);
+// Named in SERVER_INSTRUCTIONS (config/default-config.ts): when this tool's name or what it is for changes, update them to match.
 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 WRITE_THE_CODE_LINE = "When the user brought no files, write the site's code yourself, then upload it as the guide shows.";
 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.`,
+        `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. ${WRITE_THE_CODE_LINE}`,
         FALLBACK_LINE,
         '---',
         recipe.trim()
@@ -31,7 +36,7 @@ export function startDeployWebsiteResponse(recipe) {
 // 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.',
+    `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. ${WRITE_THE_CODE_LINE}`,
     FALLBACK_LINE
 ].join('\n\n');
 export function addStartDeployWebsiteTool(server, disableTools = [], toolDescriptions, fetchOptions = {}) {

package/build/dts/docs/start-headless-build.d.ts

@@ -3,17 +3,15 @@ import { type StartDeployWebsiteFetchOptions } from './start-deploy-website.js';
 export declare const START_HEADLESS_BUILD_TOOL_NAME = "StartHeadlessBuild";
 /** Wix's headless guide; identical to https://www.wix.com/headless/skill.md. */
 export declare const HEADLESS_GUIDE_URL = "https://www.wix.com/skills/headless-cold-start/headless-kit.md";
-export declare const START_HEADLESS_BUILD_STARTING_POINTS: readonly ["nothing yet", "a design worked out in this conversation", "an existing Wix Headless site", "a project download link", "a Wix site to move to code"];
-type StartingPoint = (typeof START_HEADLESS_BUILD_STARTING_POINTS)[number];
 export declare const START_HEADLESS_BUILD_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 startingPoint: "What the build starts from: nothing yet; a design worked out in this conversation; an existing Wix Headless site; a project download link (a download.zip from Wix); or a Wix site to move to code.";
-    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.";
+    readonly userRequest: "A short summary of what the user asked for and the context that led here, in a sentence or two, including whether this is a new site or an edit or new version of a site already on Wix. No personal data: no names, emails, phones, passwords, keys or local paths.";
+    readonly siteDescription: "What the site is: its purpose and who it is for. One or two sentences. No personal data: no names, emails, phones, passwords, keys or local paths.";
+    readonly startingPoint: "What the site starts from, in your own words: a new site; an existing Wix Headless site (a site deployed from files is one), with its metaSiteId if you have it; a project download link (a download.zip from Wix); a Wix site moving to code; or something else. No personal data: no names, emails, phones, passwords, keys or local paths.";
+    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. No personal data: no names, emails, phones, passwords, keys or local paths.";
+    readonly agentIdentity: "Which agent or product you are, which model if you know it, and the harness you run in. No personal data: no names, emails, phones, passwords, keys or local paths.";
+    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; which Wix identity you act with — the user's login through this MCP, a CLI login, or none; and which Wix skills you have (for example wix-headless-kit or wix-manage), by name and where they come from (installed on disk, a plugin, read online), or none. Name the kind of identity, not the account or its email. No personal data: no names, emails, phones, passwords, keys or local paths.";
 };
-export declare function startHeadlessBuildResponse(guide: string | undefined, startingPoint: StartingPoint): string;
+/** The same response for every call: the headless guide, inline. */
+export declare function startHeadlessBuildResponse(guide: string | undefined): string;
 export declare function addStartHeadlessBuildTool(server: WixMcpServer, disableTools?: string[], toolDescriptions?: Record<string, string>, fetchOptions?: StartDeployWebsiteFetchOptions): void;
-export {};
 //# sourceMappingURL=start-headless-build.d.ts.map

package/build/dts/docs/start-headless-build.js

@@ -1,41 +1,29 @@
 import { z } from 'zod';
 import { defaultToolDescriptions } from '../config/default-config.js';
 import { fetchArticleContent } from './fetch-article.js';
-import { START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS } from './start-deploy-website.js';
+import { NO_PERSONAL_DATA, START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS } from './start-deploy-website.js';
+// Named in SERVER_INSTRUCTIONS (config/default-config.ts): when this tool's name or what it is for changes, update them to match.
 export const START_HEADLESS_BUILD_TOOL_NAME = 'StartHeadlessBuild';
 /** Wix's headless guide; identical to https://www.wix.com/headless/skill.md. */
 export const HEADLESS_GUIDE_URL = 'https://www.wix.com/skills/headless-cold-start/headless-kit.md';
-export const START_HEADLESS_BUILD_STARTING_POINTS = [
-    'nothing yet',
-    'a design worked out in this conversation',
-    'an existing Wix Headless site',
-    'a project download link',
-    'a Wix site to move to code'
-];
-// Like StartDeployWebsite's, these arguments are read by people via BI; only
-// `startingPoint` changes the response.
+// Like StartDeployWebsite's, these arguments are read by people via BI and do not change the
+// response.
 export const START_HEADLESS_BUILD_PARAM_DESCRIPTIONS = {
     userRequest: START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.userRequest,
     siteDescription: START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.siteDescription,
-    startingPoint: 'What the build starts from: nothing yet; a design worked out in this conversation; an existing Wix Headless site; a project download link (a download.zip from Wix); or a Wix site to move to code.',
+    startingPoint: `What the site starts from, in your own words: a new site; an existing Wix Headless site (a site deployed from files is one), with its metaSiteId if you have it; a project download link (a download.zip from Wix); a Wix site moving to code; or something else. ${NO_PERSONAL_DATA}`,
     siteFunctionality: START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.siteFunctionality,
     agentIdentity: START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.agentIdentity,
     wixAccess: START_DEPLOY_WEBSITE_PARAM_DESCRIPTIONS.wixAccess
 };
-const PREFIX = "The following is Wix's headless guide. Follow it end to end and do the work yourself. If you find the user already has the site's code, call StartDeployWebsite instead.";
-const MOVE_TO_CODE_LINE = 'Moving a Wix site to code starts from the site\'s dashboard (Headless settings, "Go Headless"), which hands the owner a prompt with the project\'s download link. Ask the user for that prompt, then follow the guide with it.';
-export function startHeadlessBuildResponse(guide, startingPoint) {
-    const lines = [];
-    if (startingPoint === 'a Wix site to move to code') {
-        lines.push(MOVE_TO_CODE_LINE);
-    }
+const BUILT_HERE = "The site is built here, in code: don't offer Wix's editor or a template instead.";
+const PREFIX = `The following is Wix's headless guide. Follow it end to end and do the work yourself: you write the site, and the guide creates it, connects its Wix business features, and uploads it. ${BUILT_HERE}`;
+/** The same response for every call: the headless guide, inline. */
+export function startHeadlessBuildResponse(guide) {
     if (guide && guide.trim()) {
-        lines.push(PREFIX, '---', guide.trim());
-    }
-    else {
-        lines.push(`Wix's headless guide could not be loaded here. It is at ${HEADLESS_GUIDE_URL}: read it whole with ReadFullDocsArticle if you have that tool, otherwise fetch it with curl or your web tool, then follow it end to end and do the work yourself. If you find the user already has the site's code, call StartDeployWebsite instead.`);
+        return [PREFIX, '---', guide.trim()].join('\n\n');
     }
-    return lines.join('\n\n');
+    return `Wix's headless guide could not be loaded here. It is at ${HEADLESS_GUIDE_URL}: read it whole with ReadFullDocsArticle if you have that tool, otherwise fetch it with curl or your web tool, then follow it end to end and do the work yourself. ${BUILT_HERE}`;
 }
 export function addStartHeadlessBuildTool(server, disableTools = [], toolDescriptions, fetchOptions = {}) {
     if (disableTools.includes(START_HEADLESS_BUILD_TOOL_NAME)) {
@@ -46,13 +34,11 @@ export function addStartHeadlessBuildTool(server, disableTools = [], toolDescrip
         defaultToolDescriptions[START_HEADLESS_BUILD_TOOL_NAME], {
         userRequest: z.string().min(1).describe(d.userRequest),
         siteDescription: z.string().min(1).describe(d.siteDescription),
-        startingPoint: z
-            .enum(START_HEADLESS_BUILD_STARTING_POINTS)
-            .describe(d.startingPoint),
+        startingPoint: z.string().optional().describe(d.startingPoint),
         siteFunctionality: z.string().min(1).describe(d.siteFunctionality),
         agentIdentity: z.string().min(1).describe(d.agentIdentity),
         wixAccess: z.string().min(1).describe(d.wixAccess)
-    }, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async (args, { httpClient }) => {
+    }, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async (_args, { httpClient }) => {
         // Inline, not a link: chat agents cannot fetch www.wix.com themselves.
         let guide;
         try {
@@ -65,7 +51,7 @@ export function addStartHeadlessBuildTool(server, disableTools = [], toolDescrip
             content: [
                 {
                     type: 'text',
-                    text: startHeadlessBuildResponse(guide, args.startingPoint)
+                    text: startHeadlessBuildResponse(guide)
                 }
             ]
         };