@wix/mcp 1.0.0

package/build/docs/docs.js

@@ -0,0 +1,268 @@
+import { z } from 'zod';
+import { runSemanticSearchAndFormat } from './semanticSearch.js';
+import { logger } from '../logger.js';
+import { captureException } from '@sentry/node';
+export const VALID_DOCS_TOOLS = [
+    'WDS',
+    'REST',
+    'SDK',
+    'BUILD_APPS',
+    'WIX_HEADLESS'
+];
+export const addDocsTools = (server, allowedTools = [
+    'WDS',
+    'REST',
+    'SDK',
+    'BUILD_APPS',
+    'WIX_HEADLESS'
+]) => {
+    // WDS Documentation
+    if (allowedTools.includes('WDS')) {
+        server.tool('SearchWixWDSDocumentation', [
+            'Searches the Wix Design System Documentation for components and patterns.',
+            'Use this tool when you need to understand or implement UI components and design patterns in a Wix project.',
+            'Search for specific component names, patterns, or UI requirements.',
+            "If you can't find what you need, try to rephrase your search term or use bigger maxResults value."
+        ].join('\n'), {
+            searchTerm: z
+                .string()
+                .describe('The search term to search for in the Wix Design System Documentation'),
+            maxResults: z
+                .number()
+                .describe('The maximum number of results to return, default is 5, max is 15')
+                .min(1)
+                .max(15)
+                .optional()
+                .default(5)
+        }, async ({ searchTerm, maxResults }, { panorama }) => {
+            try {
+                logger.log(`Searching for ${searchTerm} in Wix WDS`);
+                const result = await runSemanticSearchAndFormat('WDS', {
+                    searchTerm: searchTerm
+                }, Math.max(1, Math.min(maxResults ?? 5, 15)));
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: result
+                        }
+                    ]
+                };
+            }
+            catch (error) {
+                panorama.errorMonitor().reportError(error);
+                captureException(error, {
+                    tags: {
+                        componentId: 'SearchWixWDSDocumentation',
+                        toolName: 'SearchWixWDSDocumentation'
+                    }
+                });
+                logger.error(`Error searching for ${searchTerm} in Wix WDS: ${error}`);
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: 'Error: ' + error.message }]
+                };
+            }
+        });
+    }
+    // REST Documentation
+    if (allowedTools.includes('REST')) {
+        server.tool('SearchWixRESTDocumentation', [
+            'Searches the official Wix REST API documentation.',
+            'Use this tool whenever you need to to interact with the Wix platform via HTTP requests.',
+            "Specify the API endpoint, resource, or action you need information about (e.g., 'get site details endpoint', 'create data collection', 'update product API', 'REST authentication').",
+            "If you can't find what you need, try to rephrase your search term or use bigger maxResults value."
+        ].join('\n'), {
+            searchTerm: z
+                .string()
+                .describe('The search term to search for in the Wix REST API Documentation'),
+            maxResults: z
+                .number()
+                .describe('The maximum number of results to return, default is 5, max is 15')
+                .min(1)
+                .max(15)
+                .optional()
+                .default(5)
+        }, async ({ searchTerm, maxResults }, { panorama }) => {
+            try {
+                logger.log(`Searching for ${searchTerm} in Wix REST API`);
+                const result = await runSemanticSearchAndFormat('REST', {
+                    searchTerm: searchTerm
+                }, Math.max(1, Math.min(maxResults ?? 5, 15)));
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: result
+                        }
+                    ]
+                };
+            }
+            catch (error) {
+                panorama.errorMonitor().reportError(error);
+                captureException(error, {
+                    tags: {
+                        componentId: 'SearchWixRESTDocumentation',
+                        toolName: 'SearchWixRESTDocumentation'
+                    }
+                });
+                logger.error(`Error searching for ${searchTerm} in Wix REST API: ${error}`);
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: 'Error: ' + error.message }]
+                };
+            }
+        });
+    }
+    // SDK Documentation
+    if (allowedTools.includes('SDK')) {
+        server.tool('SearchWixSDKDocumentation', [
+            'Searches the official Wix javascript SDK documentation.',
+            'Use this tool whenever you need to write or modify Wix related SDK code.',
+            "Specify the SDK module, function, or feature you need information about (e.g., 'how to query all items from a data collection?', 'how to use wix-stores-backend', 'authentication methods in the SDK').",
+            "If you can't find what you need, try to rephrase your search term or use bigger maxResults value."
+        ].join('\n'), {
+            searchTerm: z
+                .string()
+                .describe('The search term to search for in the Wix SDK Documentation'),
+            maxResults: z
+                .number()
+                .describe('The maximum number of results to return, default is 5, max is 15')
+                .min(1)
+                .max(15)
+                .optional()
+                .default(5)
+        }, async ({ searchTerm, maxResults }, { panorama }) => {
+            try {
+                logger.log(`Searching for ${searchTerm} in Wix SDK`);
+                panorama
+                    .transaction('SearchWixSDKDocumentation')
+                    .start({ maxResults });
+                const result = await runSemanticSearchAndFormat('SDK', {
+                    searchTerm: searchTerm
+                }, Math.max(1, Math.min(maxResults ?? 5, 15)));
+                panorama
+                    .transaction('SearchWixSDKDocumentation')
+                    .finish({ maxResults });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: result
+                        }
+                    ]
+                };
+            }
+            catch (error) {
+                panorama.errorMonitor().reportError(error);
+                captureException(error, {
+                    tags: {
+                        componentId: 'SearchWixSDKDocumentation',
+                        toolName: 'SearchWixSDKDocumentation'
+                    }
+                });
+                logger.error(`Error searching for ${searchTerm} in Wix SDK: ${error}`);
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: 'Error: ' + error.message }]
+                };
+            }
+        });
+    }
+    // Build Apps Documentation
+    if (allowedTools.includes('BUILD_APPS')) {
+        server.tool('SearchBuildAppsDocumentation', [
+            'Searches the official Build Apps documentation.',
+            'Use this tool when you need to understand or implement Wix CLI applications related code.',
+            'The search term should be a specific Wix CLI command or specific topic related to Wix CLI applications or its ecosystem (e.g. deployment, creating new extensions etc).',
+            "If you can't find what you need, try to rephrase your search term or use bigger maxResults value."
+        ].join('\n'), {
+            searchTerm: z
+                .string()
+                .describe('The search term to search for in the Build Apps Documentation'),
+            maxResults: z
+                .number()
+                .describe('The maximum number of results to return, default is 5, max is 15')
+                .min(1)
+                .max(15)
+                .optional()
+                .default(5)
+        }, async ({ searchTerm, maxResults }, { panorama }) => {
+            try {
+                logger.log(`Searching for ${searchTerm} in Build Apps`);
+                const result = await runSemanticSearchAndFormat('BUILD_APPS', {
+                    searchTerm: `wix cli docs for ${searchTerm}`
+                }, Math.max(1, Math.min(maxResults ?? 5, 15)));
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: result
+                        }
+                    ]
+                };
+            }
+            catch (error) {
+                panorama.errorMonitor().reportError(error);
+                captureException(error, {
+                    tags: {
+                        componentId: 'SearchBuildAppsDocumentation',
+                        toolName: 'SearchBuildAppsDocumentation'
+                    }
+                });
+                logger.error(`Error searching for ${searchTerm} in Build Apps: ${error}`);
+                return {
+                    content: [{ type: 'text', text: 'Error: ' + error.message }]
+                };
+            }
+        });
+    }
+    // Wix Headless Documentation
+    if (allowedTools.includes('WIX_HEADLESS')) {
+        server.tool('SearchWixHeadlessDocumentation', [
+            'Searches the official Wix Headless Documentation.',
+            'Use this tool when you need to understand or implement Headless related code.',
+            'The search term should be a specific Wix Headless topic or feature you need information about.',
+            "If you can't find what you need, try to rephrase your search term or use bigger maxResults value."
+        ].join('\n'), {
+            searchTerm: z
+                .string()
+                .describe('The search term to search for in the Headless Documentation'),
+            maxResults: z
+                .number()
+                .describe('The maximum number of results to return, default is 5, max is 15')
+                .min(1)
+                .max(15)
+                .optional()
+                .default(5)
+        }, async ({ searchTerm, maxResults }, { panorama }) => {
+            try {
+                logger.log(`Searching for ${searchTerm} in Headless`);
+                const result = await runSemanticSearchAndFormat('WIX_HEADLESS', {
+                    searchTerm: searchTerm
+                }, Math.max(1, Math.min(maxResults ?? 5, 15)));
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: result
+                        }
+                    ]
+                };
+            }
+            catch (error) {
+                panorama.errorMonitor().reportError(error);
+                captureException(error, {
+                    tags: {
+                        componentId: 'SearchWixHeadlessDocumentation',
+                        toolName: 'SearchWixHeadlessDocumentation'
+                    }
+                });
+                logger.error(`Error searching for ${searchTerm} in Wix Headless: ${error}`);
+                return {
+                    content: [{ type: 'text', text: 'Error: ' + error.message }]
+                };
+            }
+        });
+    }
+};

package/build/docs/semanticSearch.js

@@ -0,0 +1,86 @@
+import { logger } from '../logger.js';
+const MAX_CONTENT_LENGTH = 10000;
+const runSemanticSearch = async (toolName, toolParams, maxResults = 20, rerank = false) => {
+    const startTime = new Date().getTime();
+    const url = new URL(`https://www.wixapis.com/mcp-docs-search/v1/search?maxResults=${maxResults}&rerank=${rerank}`);
+    if (toolName === 'SDK') {
+        url.searchParams.append('kbName', 'SDK_SCHEMAS_KB_ID');
+        url.searchParams.append('kbName', 'SDK_DOCS_KB_ID');
+    }
+    else if (toolName === 'REST') {
+        url.searchParams.append('kbName', 'REST_METHODS_KB_ID');
+        url.searchParams.append('kbName', 'REST_DOCS_KB_ID');
+    }
+    else if (toolName === 'WDS') {
+        url.searchParams.append('kbName', 'WDS_DOCS_KB_ID');
+    }
+    else if (toolName === 'BUILD_APPS') {
+        url.searchParams.append('kbName', 'BUILD_APPS_KB_ID');
+    }
+    else if (toolName === 'WIX_HEADLESS') {
+        url.searchParams.append('kbName', 'HEADLESS_KB_ID');
+    }
+    for (const [key, value] of Object.entries(toolParams)) {
+        url.searchParams.append(key, value);
+    }
+    logger.log('Running RAG search', url.toString());
+    const response = await fetch(url.toString(), {
+        headers: {
+            'Content-Type': 'application/json',
+            'x-time-budget': '180000',
+            'x-wix-time-budget': '180000',
+            Cookie: process.env.WIX_COOKIE || ''
+        }
+    });
+    if (!response.ok) {
+        logger.error(`Failed to run rag search: ${response.statusText}`);
+        throw new Error(`Failed to run rag search: ${response.statusText}`);
+    }
+    const data = await response.json();
+    const endTime = new Date().getTime();
+    const timeTaskFormatted = (endTime - startTime) / 1000;
+    logger.log('Ran RAG search successfully with params', JSON.stringify(toolParams), timeTaskFormatted, typeof data);
+    return data?.results;
+};
+const getContentFromChunkedContent = (chunkedContent) => {
+    let content = '';
+    for (const chunk of chunkedContent) {
+        if (content.length + chunk.length > MAX_CONTENT_LENGTH) {
+            break;
+        }
+        content += '\n\n---\n\n' + chunk;
+    }
+    return content;
+};
+const formatResultsContent = (resultsFromKbs, maxResults) => {
+    // First, take the results from all KBs and sort them by overallMatchScore
+    const allResults = Object.entries(resultsFromKbs)
+        .map(([, { results }]) => results)
+        .flat();
+    if (allResults.length === 0) {
+        throw new Error('No result from search');
+    }
+    const sortedResults = allResults.sort((a, b) => b.scoresInfo.overallMatchScore - a.scoresInfo.overallMatchScore);
+    // Take the top maxResults results
+    const topResults = sortedResults.slice(0, maxResults);
+    // Concatenate the content of the top results
+    const concatenatedContent = topResults
+        .map((result) => {
+        const content = result.entry.content;
+        const chunkedContent = result.entry.chunkedContent;
+        if (content.length > MAX_CONTENT_LENGTH) {
+            logger.log(`Content is too long, using first chunk`, {
+                contentLength: content.length,
+                chunkedContentLength: chunkedContent.length
+            });
+            return getContentFromChunkedContent(chunkedContent);
+        }
+        return content;
+    })
+        .join('\n\n---\n\n');
+    return concatenatedContent;
+};
+export const runSemanticSearchAndFormat = async (toolName, toolParams, maxResults = 20, rerank = false) => {
+    const results = await runSemanticSearch(toolName, toolParams, maxResults, rerank);
+    return formatResultsContent(results, Math.min(maxResults, 10));
+};

package/build/docs/semanticSearch.test.js

@@ -0,0 +1,289 @@
+import { describe, test, expect, beforeEach, vi, afterAll } from 'vitest';
+import { runSemanticSearchAndFormat } from './semanticSearch.js';
+const sampleSearchResponse = {
+    results: {
+        SDK_DOCS_KB_ID: {
+            results: [
+                {
+                    entry: {
+                        content: 'SDK Documentation content 1'
+                    },
+                    scoresInfo: {
+                        overallMatchScore: 0.95
+                    }
+                },
+                {
+                    entry: {
+                        content: 'SDK Documentation content 2'
+                    },
+                    scoresInfo: {
+                        overallMatchScore: 0.85
+                    }
+                }
+            ]
+        },
+        SDK_SCHEMAS_KB_ID: {
+            results: [
+                {
+                    entry: {
+                        content: 'SDK Schema content 1'
+                    },
+                    scoresInfo: {
+                        overallMatchScore: 0.9
+                    }
+                }
+            ]
+        },
+        BUILD_APPS_KB_ID: {
+            results: [
+                {
+                    entry: {
+                        content: 'Build Apps content 1'
+                    },
+                    scoresInfo: {
+                        overallMatchScore: 0.88
+                    }
+                }
+            ]
+        }
+    }
+};
+const originalProcessEnv = process.env;
+describe('Semantic Search', () => {
+    let fetchMock;
+    global.fetch = vi.fn();
+    beforeEach(() => {
+        vi.clearAllMocks();
+        process.env = { ...originalProcessEnv };
+        fetchMock = global.fetch;
+        fetchMock.mockReset();
+        fetchMock.mockResolvedValue({
+            ok: true,
+            status: 200,
+            statusText: 'OK',
+            json: async () => sampleSearchResponse
+        });
+    });
+    afterAll(() => {
+        process.env = originalProcessEnv;
+    });
+    test('performs SDK semantic search successfully', async () => {
+        const sdkResponse = {
+            results: {
+                SDK_DOCS_KB_ID: {
+                    results: [
+                        {
+                            entry: {
+                                content: 'SDK Documentation content 1'
+                            },
+                            scoresInfo: {
+                                overallMatchScore: 0.95
+                            }
+                        },
+                        {
+                            entry: {
+                                content: 'SDK Documentation content 2'
+                            },
+                            scoresInfo: {
+                                overallMatchScore: 0.85
+                            }
+                        }
+                    ]
+                },
+                SDK_SCHEMAS_KB_ID: {
+                    results: [
+                        {
+                            entry: {
+                                content: 'SDK Schema content 1'
+                            },
+                            scoresInfo: {
+                                overallMatchScore: 0.9
+                            }
+                        }
+                    ]
+                }
+            }
+        };
+        fetchMock.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: async () => sdkResponse
+        });
+        const result = await runSemanticSearchAndFormat('SDK', {
+            searchTerm: 'wix-data query'
+        });
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        const [url] = fetchMock.mock.calls[0];
+        expect(url).toContain('mcp-docs-search/v1/search');
+        expect(url).toContain('maxResults=20');
+        expect(url).toContain('rerank=false');
+        expect(url).toContain('kbName=SDK_SCHEMAS_KB_ID');
+        expect(url).toContain('kbName=SDK_DOCS_KB_ID');
+        expect(url).toContain('searchTerm=wix-data+query');
+        // Results should be sorted by score and limited to 10
+        expect(result).toBe('SDK Documentation content 1\n\n---\n\nSDK Schema content 1\n\n---\n\nSDK Documentation content 2');
+    });
+    test('performs REST semantic search successfully', async () => {
+        const restResponse = {
+            results: {
+                REST_METHODS_KB_ID: {
+                    results: [
+                        {
+                            entry: {
+                                content: 'REST Methods content'
+                            },
+                            scoresInfo: {
+                                overallMatchScore: 0.98
+                            }
+                        }
+                    ]
+                },
+                REST_DOCS_KB_ID: {
+                    results: [
+                        {
+                            entry: {
+                                content: 'REST Documentation content'
+                            },
+                            scoresInfo: {
+                                overallMatchScore: 0.95
+                            }
+                        }
+                    ]
+                }
+            }
+        };
+        fetchMock.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: async () => restResponse
+        });
+        const result = await runSemanticSearchAndFormat('REST', {
+            searchTerm: 'create collection'
+        });
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        const [url] = fetchMock.mock.calls[0];
+        expect(url).toContain('kbName=REST_METHODS_KB_ID');
+        expect(url).toContain('kbName=REST_DOCS_KB_ID');
+        expect(result).toBe('REST Methods content\n\n---\n\nREST Documentation content');
+    });
+    test('performs WDS semantic search successfully', async () => {
+        const wdsResponse = {
+            results: {
+                WDS_DOCS_KB_ID: {
+                    results: [
+                        {
+                            entry: {
+                                content: 'WDS Documentation content'
+                            },
+                            scoresInfo: {
+                                overallMatchScore: 0.95
+                            }
+                        }
+                    ]
+                }
+            }
+        };
+        fetchMock.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: async () => wdsResponse
+        });
+        const result = await runSemanticSearchAndFormat('WDS', { searchTerm: 'Button component' }, 1);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        const [url] = fetchMock.mock.calls[0];
+        expect(url).toContain('kbName=WDS_DOCS_KB_ID');
+        expect(result).toBe('WDS Documentation content');
+    });
+    test('performs BUILD_APPS semantic search successfully', async () => {
+        const buildAppsResponse = {
+            results: {
+                BUILD_APPS_KB_ID: {
+                    results: [
+                        {
+                            entry: {
+                                content: 'Build Apps content 1'
+                            },
+                            scoresInfo: {
+                                overallMatchScore: 0.88
+                            }
+                        }
+                    ]
+                }
+            }
+        };
+        fetchMock.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: async () => buildAppsResponse
+        });
+        const result = await runSemanticSearchAndFormat('BUILD_APPS', { searchTerm: 'deploy app' }, 5);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        const [url] = fetchMock.mock.calls[0];
+        expect(url).toContain('kbName=BUILD_APPS_KB_ID');
+        expect(result).toBe('Build Apps content 1');
+    });
+    test('performs WIX_HEADLESS semantic search successfully', async () => {
+        const wixHeadlessResponse = {
+            results: {
+                WIX_HEADLESS_KB_ID: {
+                    results: [
+                        {
+                            entry: {
+                                content: 'Wix Headless content 1'
+                            },
+                            scoresInfo: {
+                                overallMatchScore: 0.92
+                            }
+                        }
+                    ]
+                }
+            }
+        };
+        fetchMock.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: async () => wixHeadlessResponse
+        });
+        const result = await runSemanticSearchAndFormat('WIX_HEADLESS', {
+            searchTerm: 'query'
+        });
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        const [url] = fetchMock.mock.calls[0];
+        expect(url).toContain('kbName=HEADLESS_KB_ID');
+        expect(result).toBe('Wix Headless content 1');
+    });
+    test('handles API error response', async () => {
+        fetchMock.mockResolvedValueOnce({
+            ok: false,
+            status: 500,
+            statusText: 'Internal Server Error'
+        });
+        await expect(runSemanticSearchAndFormat('SDK', { searchTerm: 'query' })).rejects.toThrow('Failed to run rag search: Internal Server Error');
+    });
+    test('handles empty results', async () => {
+        fetchMock.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: async () => ({ results: {} })
+        });
+        await expect(runSemanticSearchAndFormat('SDK', { searchTerm: 'query' })).rejects.toThrow('No result from search');
+    });
+    test('respects maxResults parameter', async () => {
+        const maxResults = 5;
+        await runSemanticSearchAndFormat('SDK', { searchTerm: 'query' }, maxResults);
+        const [url] = fetchMock.mock.calls[0];
+        expect(url).toContain('maxResults=5');
+    });
+    test('respects rerank parameter', async () => {
+        await runSemanticSearchAndFormat('SDK', { searchTerm: 'query' }, 5, true);
+        const [url] = fetchMock.mock.calls[0];
+        expect(url).toContain('rerank=true');
+    });
+    test('uses WIX_COOKIE when available', async () => {
+        process.env.WIX_COOKIE = 'test-cookie';
+        await runSemanticSearchAndFormat('SDK', { searchTerm: 'query' });
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        const [, options] = fetchMock.mock.calls[0];
+        expect(options.headers.Cookie).toBe('test-cookie');
+    });
+});