@wix/mcp 1.0.0 → 1.0.1

package/README.md

@@ -18,7 +18,7 @@ args: ["/Users/absolute/path/to/repo/dir/."]
 
 ```
 command: node
-args: ["/Users/absolute/path/to/build/index.js"]
+args: ["/Users/absolute/path/to/build/bin.js"]
 ```
 
 # Optional config arguments:
@@ -63,6 +63,11 @@ It's exactly parallel to the real docs url, for example:
 Docs URL: https://dev.wix.com/docs/picasso/wix-ai-docs/best-practices/sdk-best-practices
 Resource URI: wix-docs://picasso/wix-ai-docs/best-practices/sdk-best-practices
 
+pass:
+`--portals=<docs-portal-name>`
+to load all docs from the portal as resources
+
+
 # Cursor
 
 ## Cursor MCP docs:
@@ -78,9 +83,10 @@ https://docs.cursor.com/context/model-context-protocol
 ```
 {
   "mcpServers": {
-    "IGOR_TOOLS": {
+    "wix-local-mcp": {
       "command": "npx",
       "args": [
+        "-y",
         "@wix/mcp"
       ]
     }
@@ -92,7 +98,7 @@ https://docs.cursor.com/context/model-context-protocol
 ```
 {
   "mcpServers": {
-    "IGOR_TOOLS": {
+    "wix-local-mcp": {
       "command": "npx",
       "args": [
         "/Users/absolute/path/to/repo/dir/."
@@ -110,10 +116,10 @@ https://docs.cursor.com/context/model-context-protocol
 ```
 {
   "mcpServers": {
-    "IGOR_TOOLS": {
+    "wix-local-mcp": {
       "command": "node",
       "args": [
-        "/Users/absolute/path/to/build/index.js"
+        "/Users/absolute/path/to/build/bin.js"
       ]
     }
   }
@@ -123,7 +129,9 @@ https://docs.cursor.com/context/model-context-protocol
 ### You can try using bun + index.ts 
 
 # Troubleshooting
-
+- check the logs from claude desktop / cursor
+- is the error related to node / fnm / nvm ? make sure you have the latest node version as the default on in the path
+- is the error related to npx? make sure you use -y and the correct npm registry
 - try including full path to node
 - try using bun and index.ts directly
 - make sure build files have permissions for cursor to access

package/bin.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import './build/index.js';
+import './build/bin.js';

package/build/api-call/index.d.ts

@@ -0,0 +1,2 @@
+import { WixMcpServer } from '../wix-mcp-server.js';
+export declare function addApiCallTool(server: WixMcpServer, getSiteAccessToken: (siteId: string) => Promise<string>, getAccountAccessToken: () => Promise<string>): void;

package/build/api-call/index.js

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+import { logger } from '../logger.js';
+import { handleWixAPIResponse } from '../tool-utils.js';
+export function addApiCallTool(server, getSiteAccessToken, getAccountAccessToken) {
+    server.tool('CallWixSiteAPI', 'Call Wix apis on a business or site. Use this to create, read, update, and delete data and other Wix entities in your Wix site,' +
+        `You should ALWAYS check the rest docs - "SearchWixRESTDocumentation" for the specific API you want to call, don't just call it without knowing what it does, CHECK THE DOCS`, {
+        siteId: z
+            .string()
+            .describe('The id of the site selected using site selection tool'),
+        url: z
+            .string()
+            .describe('The url of the api to call - ALWAYS get the information from the Wix REST docs or from the conversation context, the URL MUST BE ABSOLUTE URL'),
+        method: z
+            .string()
+            .describe('The HTTP method to use for the API call (e.g. GET, POST, PUT, DELETE)'),
+        body: z
+            .string()
+            .optional()
+            .describe('A string representing of a valid JSON object to describe the body of the request')
+    }, async ({ url, body, method, siteId }) => {
+        logger.log(`Calling Wix Site API: ${siteId} ${url}, body: ${JSON.stringify(body)}`);
+        const authorization = await getSiteAccessToken(siteId);
+        try {
+            const response = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: authorization,
+                    ...(body ? { 'Content-Type': 'application/json' } : {})
+                },
+                body: method === 'GET' ? undefined : body
+            });
+            const responseData = await handleWixAPIResponse(response);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Wix Site API call successful: ${JSON.stringify(responseData)}`
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            logger.error(`Failed to call Wix Site API: ${error}`);
+            throw new Error(`Failed to call Wix Site API: ${error}`);
+        }
+    });
+    server.tool('ListWixSites', 'List Wix sites for the current user', async () => {
+        const sitesRes = await fetch('https://www.wixapis.com/site-list/v2/sites/query', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'application/json, text/plain, */*',
+                Authorization: await getAccountAccessToken()
+            },
+            body: JSON.stringify({
+                query: {
+                    cursorPaging: { limit: 50 }
+                }
+            })
+        });
+        const result = await sitesRes.json().then(({ sites }) => sites?.map(({ id, displayName }) => ({
+            id,
+            name: displayName
+        })) ?? []);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result)
+                },
+                {
+                    type: 'text',
+                    text: 'if there is more than one site returned, the user should pick one from a list, list the sites (only name) for the user and ask them to pick one'
+                }
+            ]
+        };
+    });
+    server.tool('ManageWixSite', `Use account level API in order to create a site, update a site and publish site.
+    ALWAYS use "SearchWixRESTDocumentation" to search for the API you should invoke, NEVER GUESS THE SITE API URL`, {
+        url: z
+            .string()
+            .describe('The url of the api to call - ALWAYS get the information from the Wix REST docs DONT GUESS IT, the URL MUST BE ABSOLUTE URL'),
+        method: z
+            .string()
+            .describe('The HTTP method to use for the API call (e.g. GET, POST, PUT, DELETE)'),
+        body: z
+            .string()
+            .optional()
+            .describe('A string representing of a valid JSON object to describe the body of the request')
+    }, async ({ url, body, method }) => {
+        logger.log(`Calling Wix Account level API: ${url}, body: ${JSON.stringify(body)}`);
+        const authorization = await getAccountAccessToken();
+        try {
+            const response = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: authorization,
+                    ...(body ? { 'Content-Type': 'application/json' } : {})
+                },
+                body: method === 'GET' ? undefined : body
+            });
+            const responseData = await handleWixAPIResponse(response);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Wix Account API call successful: ${JSON.stringify(responseData)}`
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            logger.error(`Failed to call Wix Account API: ${error}`);
+            throw new Error(`Failed to call Wix Account API: ${error}`);
+        }
+    });
+}

package/build/bin.d.ts

@@ -0,0 +1,6 @@
+import './sentry.js';
+declare const PUBLIC_TOOLS: readonly ["WDS", "REST", "SDK", "BUILD_APPS", "WIX_HEADLESS", "BUSINESS_SOLUTIONS"];
+declare const EXPERIMENTAL_TOOLS: readonly ["WIX_API", "CLI_COMMAND"];
+type Tool = (typeof PUBLIC_TOOLS)[number] | (typeof EXPERIMENTAL_TOOLS)[number];
+export declare const DEFAULT_TOOLS: Tool[];
+export {};

package/build/bin.js

@@ -0,0 +1,97 @@
+import './sentry.js';
+import minimist from 'minimist';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { addDocsTools, VALID_DOCS_TOOLS } from './docs/docs.js';
+import { addCliTools, VALID_CLI_TOOLS } from './cli-tools/cli.js';
+import { logger, attachStdErrLogger, attachMcpServerLogger, attachFileLogger } from './logger.js';
+import { WixMcpServer } from './wix-mcp-server.js';
+import { addDocsResources } from './resources/docs.js';
+const PUBLIC_TOOLS = [...VALID_DOCS_TOOLS];
+const EXPERIMENTAL_TOOLS = ['WIX_API', 'CLI_COMMAND'];
+export const DEFAULT_TOOLS = [...VALID_DOCS_TOOLS];
+const parsedArgs = minimist(process.argv.slice(2));
+function parseExperimentalArg() {
+    const experimentalArg = parsedArgs['experimental'];
+    if (!experimentalArg)
+        return [];
+    return experimentalArg
+        .split(',')
+        .map((t) => t.trim())
+        .filter((tool) => EXPERIMENTAL_TOOLS.includes(tool));
+}
+function parseToolsArg() {
+    const toolsArg = parsedArgs['tools'];
+    const experimentalTools = parseExperimentalArg();
+    if (!toolsArg) {
+        // When no tools specified, return both default and experimental tools
+        return [...DEFAULT_TOOLS, ...experimentalTools];
+    }
+    const requestedTools = toolsArg.split(',').map((t) => t.trim());
+    const tools = [
+        // Include valid non-experimental tools
+        ...requestedTools.filter((tool) => PUBLIC_TOOLS.includes(tool)),
+        // Include enabled experimental tools
+        ...experimentalTools
+    ];
+    // Warn about enabled experimental tools
+    tools.forEach((tool) => {
+        if (EXPERIMENTAL_TOOLS.includes(tool)) {
+            logger.log(`Warning: ${tool} is an experimental tool and may have limited functionality or breaking changes`);
+        }
+    });
+    return tools;
+}
+const loggerType = parsedArgs['logger'] || 'mcp';
+if (loggerType === 'file') {
+    attachFileLogger();
+}
+else {
+    // Initially we log to stderr, because MCP server is not connected yet
+    // When the server is connected, we attach the MCP server logger
+    attachStdErrLogger();
+}
+logger.log('--------------------------------');
+logger.log('starting WIX MCP server');
+logger.log('--------------------------------');
+const server = new WixMcpServer({
+    name: 'wix-mcp-server',
+    version: '1.0.0'
+}, {
+    capabilities: {
+        tools: {},
+        prompts: {},
+        logging: {},
+        resources: {}
+    }
+});
+const activeTools = parseToolsArg();
+logger.log('Active tools:', activeTools);
+const docsTools = activeTools.filter((tool) => VALID_DOCS_TOOLS.includes(tool));
+if (docsTools.length > 0) {
+    logger.log('Adding docs tools:', docsTools);
+    addDocsTools(server, docsTools);
+}
+const cliTools = activeTools.filter((tool) => VALID_CLI_TOOLS.includes(tool));
+if (cliTools.length > 0) {
+    logger.log('Adding cli tools:', cliTools);
+    addCliTools(server, cliTools);
+}
+try {
+    const portals = parsedArgs['portals']?.split(',') || [];
+    if (portals.length > 0) {
+        logger.log('Adding docs resources for portals:', portals);
+        await addDocsResources(server, portals);
+    }
+}
+catch (error) {
+    logger.error('Error adding docs resources:', error);
+}
+logger.log('Starting server');
+const transport = new StdioServerTransport();
+logger.log('Connecting to transport');
+await server.connect(transport);
+logger.log('Transport connected');
+if (loggerType === 'mcp') {
+    // From now on, we log to the MCP server
+    attachMcpServerLogger(server);
+}

package/build/cli-tools/cli.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const VALID_CLI_TOOLS: readonly ["WIX_API", "CLI_COMMAND", "CLI_COMMAND_INTERACTIVE_MODE"];
+export type CLITool = (typeof VALID_CLI_TOOLS)[number];
+export declare function addCliTools(server: McpServer, allowedTools?: CLITool[]): void;

package/build/cli-tools/cli.js

@@ -1,8 +1,9 @@
 import { z } from 'zod';
-import { getCliAuthTokenForSiteId, getSiteIdFromCliAppConfig, handleWixAPIResponse } from './utils.js';
+import { getCliAuthTokenForSiteId, getSiteIdFromCliAppConfig } from './utils.js';
 import { logger } from '../logger.js';
 import { execa } from 'execa';
 import { mockInteractiveGenerateCommandTool } from '../interactive-command-tools/interactive-command-utils.js';
+import { handleWixAPIResponse } from '../tool-utils.js';
 export const VALID_CLI_TOOLS = [
     'WIX_API',
     'CLI_COMMAND',

package/build/cli-tools/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function getCliAuthTokenForSiteId(siteIdOrAccountsFileName: string): string;
+export declare function getSiteIdFromCliAppConfig(appPath: string): any;

package/build/cli-tools/utils.js

@@ -10,22 +10,3 @@ export function getSiteIdFromCliAppConfig(appPath) {
     const appConfig = JSON.parse(readFileSync(path.join(appPath, '.wix/app.config.json'), 'utf8'));
     return appConfig.siteId;
 }
-const safeParseJSON = (text) => {
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return text;
-    }
-};
-export const handleWixAPIResponse = async (response) => {
-    const responseText = await response.text();
-    const responseData = safeParseJSON(responseText);
-    if (!response.ok) {
-        const errorDetails = typeof responseData === 'object'
-            ? JSON.stringify(responseData)
-            : responseData;
-        throw new Error(`Failed to call Wix API: ${response.status} ${response.statusText}. ${errorDetails}`);
-    }
-    return responseData;
-};

package/build/docs/docs.d.ts

@@ -0,0 +1,4 @@
+import type { WixMcpServer } from '../wix-mcp-server.js';
+export declare const VALID_DOCS_TOOLS: readonly ["WDS", "REST", "SDK", "BUILD_APPS", "WIX_HEADLESS", "BUSINESS_SOLUTIONS"];
+export type DocsTool = (typeof VALID_DOCS_TOOLS)[number];
+export declare const addDocsTools: (server: WixMcpServer, allowedTools?: DocsTool[]) => void;

package/build/docs/docs.js

@@ -7,14 +7,16 @@ export const VALID_DOCS_TOOLS = [
     'REST',
     'SDK',
     'BUILD_APPS',
-    'WIX_HEADLESS'
+    'WIX_HEADLESS',
+    'BUSINESS_SOLUTIONS'
 ];
 export const addDocsTools = (server, allowedTools = [
     'WDS',
     'REST',
     'SDK',
     'BUILD_APPS',
-    'WIX_HEADLESS'
+    'WIX_HEADLESS',
+    'BUSINESS_SOLUTIONS'
 ]) => {
     // WDS Documentation
     if (allowedTools.includes('WDS')) {
@@ -33,13 +35,17 @@ export const addDocsTools = (server, allowedTools = [
                 .min(1)
                 .max(15)
                 .optional()
-                .default(5)
+                .default(10)
         }, 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)));
+                const result = await runSemanticSearchAndFormat({
+                    toolName: 'WDS',
+                    toolParams: {
+                        searchTerm: searchTerm
+                    },
+                    maxResults: Math.max(1, Math.min(maxResults ?? 5, 15))
+                });
                 return {
                     content: [
                         {
@@ -82,18 +88,27 @@ export const addDocsTools = (server, allowedTools = [
                 .min(1)
                 .max(15)
                 .optional()
-                .default(5)
+                .default(10)
         }, 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)));
+                const result = await runSemanticSearchAndFormat({
+                    toolName: 'REST',
+                    toolParams: {
+                        searchTerm: searchTerm
+                    },
+                    maxResults: Math.max(1, Math.min(maxResults ?? 5, 15)),
+                    linesInEachResult: 15
+                });
                 return {
                     content: [
                         {
                             type: 'text',
                             text: result
+                        },
+                        {
+                            type: 'text',
+                            text: 'Next, you MUST use the ReadFullDocsArticle tool if you want to read the full documentation for a specific article or method.'
                         }
                     ]
                 };
@@ -114,6 +129,58 @@ export const addDocsTools = (server, allowedTools = [
             }
         });
     }
+    if (allowedTools.includes('BUSINESS_SOLUTIONS')) {
+        server.tool('SearchWixSampleFlowsDocumentation', [
+            'Searches the official Wix Business solutions Sample flows documentations.',
+            'This tool provides guidance when there is a need to perform several actions over the Wix platform, and a sample flow is needed',
+            'For example, various ways to setup a new business, or an end to end user of user flow',
+            'Once the information is retrieved you can use Wix REST API docs in order to query the specific APIs you need to use in each step'
+        ].join('\n'), {
+            searchTerm: z
+                .string()
+                .describe('The search term for the required sample flow (e.g. "setup a new business")'),
+            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 Sample Flows`);
+                const result = await runSemanticSearchAndFormat({
+                    toolName: 'BUSINESS_SOLUTIONS',
+                    toolParams: {
+                        searchTerm: 'Sample Flow for: ' + searchTerm
+                    },
+                    maxResults: Math.max(1, Math.min(maxResults ?? 5, 15))
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: result
+                        }
+                    ]
+                };
+            }
+            catch (error) {
+                panorama.errorMonitor().reportError(error);
+                captureException(error, {
+                    tags: {
+                        componentId: 'SearchWixSampleFlowsDocumentation',
+                        toolName: 'SearchWixSampleFlowsDocumentation'
+                    }
+                });
+                logger.error(`Error searching for ${searchTerm} in Wix Sample Flows: ${error}`);
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: 'Error: ' + error.message }]
+                };
+            }
+        });
+    }
     // SDK Documentation
     if (allowedTools.includes('SDK')) {
         server.tool('SearchWixSDKDocumentation', [
@@ -138,9 +205,14 @@ export const addDocsTools = (server, allowedTools = [
                 panorama
                     .transaction('SearchWixSDKDocumentation')
                     .start({ maxResults });
-                const result = await runSemanticSearchAndFormat('SDK', {
-                    searchTerm: searchTerm
-                }, Math.max(1, Math.min(maxResults ?? 5, 15)));
+                const result = await runSemanticSearchAndFormat({
+                    toolName: 'SDK',
+                    toolParams: {
+                        searchTerm: searchTerm
+                    },
+                    maxResults: Math.max(1, Math.min(maxResults ?? 5, 15)),
+                    linesInEachResult: 15
+                });
                 panorama
                     .transaction('SearchWixSDKDocumentation')
                     .finish({ maxResults });
@@ -149,6 +221,10 @@ export const addDocsTools = (server, allowedTools = [
                         {
                             type: 'text',
                             text: result
+                        },
+                        {
+                            type: 'text',
+                            text: 'Next, you MUST use ReadFullDocsArticle tool if you want to read full documentation for a specific article or method.'
                         }
                     ]
                 };
@@ -190,9 +266,13 @@ export const addDocsTools = (server, allowedTools = [
         }, 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)));
+                const result = await runSemanticSearchAndFormat({
+                    toolName: 'BUILD_APPS',
+                    toolParams: {
+                        searchTerm: `wix cli docs for ${searchTerm}`
+                    },
+                    maxResults: Math.max(1, Math.min(maxResults ?? 5, 15))
+                });
                 return {
                     content: [
                         {
@@ -238,9 +318,13 @@ export const addDocsTools = (server, allowedTools = [
         }, 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)));
+                const result = await runSemanticSearchAndFormat({
+                    toolName: 'WIX_HEADLESS',
+                    toolParams: {
+                        searchTerm: searchTerm
+                    },
+                    maxResults: Math.max(1, Math.min(maxResults ?? 5, 15))
+                });
                 return {
                     content: [
                         {
@@ -265,4 +349,91 @@ export const addDocsTools = (server, allowedTools = [
             }
         });
     }
+    server.tool('ReadFullDocsArticle', [
+        'Fetches the full Wix docs article or method article.',
+        'Use this tool when you read a summary of a docs article or method article, you have the docs url and want to read the full article.'
+    ].join('\n'), {
+        articleUrl: z
+            .string()
+            .describe('The URL of the docs article or method article to fetch. Should be something like https://dev.wix.com/docs/.../.../...')
+    }, async ({ articleUrl }) => {
+        try {
+            const articleContent = await fetchArticleContent(articleUrl, 'article');
+            if (!articleContent) {
+                throw new Error('Article content is empty');
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: articleContent
+                    },
+                    {
+                        type: 'text',
+                        text: [
+                            '---',
+                            'Next, if you are dealing with a method - you MUST call ReadFullDocsMethodSchema tool - it will give you the full request schema for the method.'
+                        ].join('\n')
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            logger.error(`Error fetching article content or method schema for ${articleUrl}: ${error}`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Could not fetch article content, you should try completing the task without it.'
+                    }
+                ]
+            };
+        }
+    });
+    server.tool('ReadFullDocsMethodSchema', [
+        'Fetches the full method schema for a given method. Always use it before calling the method.',
+        'This will give you the entire request/response schema with all the fields and their descriptions.'
+    ].join('\n'), {
+        articleUrl: z
+            .string()
+            .describe('The URL of the documentation to fetch. Should be something like https://dev.wix.com/docs/.../.../...')
+    }, async ({ articleUrl }) => {
+        try {
+            const articleContent = await fetchArticleContent(articleUrl, 'methodSchema');
+            if (!articleContent) {
+                throw new Error('Method schema is empty');
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: articleContent
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            logger.error(`Error fetching method schema for ${articleUrl}: ${error}`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Could not fetch method schema, you should try completing the task without it.'
+                    }
+                ]
+            };
+        }
+    });
 };
+async function fetchArticleContent(articleUrl, mode) {
+    // https://dev.wix.com/digor/api/get-article-content?articleUrl=https://dev.wix.com/docs/rest/business-solutions/blog/draft-posts/create-draft-post&schema=true
+    const url = new URL(`https://dev.wix.com/digor/api/get-article-content`);
+    url.searchParams.set('articleUrl', articleUrl);
+    const schema = mode === 'methodSchema' ? 'true' : 'false';
+    url.searchParams.set('schema', schema);
+    logger.log(`Fetching resource from docs ${url.toString()}`);
+    const response = await fetch(url.toString());
+    const data = await response.json();
+    logger.log(`Fetched resource from docs: ${data.articleContent}`);
+    return data.articleContent;
+}

package/build/docs/long-content.d.ts

@@ -0,0 +1 @@
+export declare const LONG_KB_CONTENT = "# Method name:\n\ncrm.contacts.queryContacts(options: QueryContactsOptions)\n\n# Method Link:\n\nhttps://dev.wix.com/docs/sdk/backend-modules/crm/contacts/query-contacts\n\n# Method Description:\n\nCreates a query to retrieve a list of contacts.\n\nThe `queryContacts()` function builds a query to retrieve a list of contacts and returns a `ContactsQueryBuilder` object.\n\nThe returned object contains the query definition, which is typically used to run the query using the `find()` function.\n\nYou can refine the query by chaining `ContactsQueryBuilder` functions onto the query. `ContactsQueryBuilder` functions enable you to sort, filter, and control the results `queryContacts()` returns.\n\n`queryContacts()` runs with these `ContactsQueryBuilder` defaults, which you can override:\n\n- `skip(0)`\n- `limit(50)`\n- `descending(\"_createdDate\")`\n\nThe functions that are chained to `queryContacts()` are applied in the order they are called. For example, if you apply `ascending('info.company')` and then `descending('info.name.last')`, the results are sorted first by the company name, and then, if there are multiple results with the same company, the items are sorted by last name.\n\n\n|PROPERTY\t|SUPPORTED FILTERS & SORTING\t\n|:---:|:---:|\n|`_id`|[`eq()`](/contacts-query-builder/eq),[`ne()`](/contacts-query-builder/ne),[`in()`](/contacts-query-builder/in),[`exists()`](/contacts-query-builder/exists)|\n|`_createdDate`|[`eq()`](/contacts-query-builder/eq),[`ne()`](/contacts-query-builder/ne),[`gt()`](/contacts-query-builder/gt),[`lt()`](/contacts-query-builder/lt),[`ge()`](/contacts-query-builder/ge),[`le()`](/contacts-query-builder/le),[`ascending()`](/contacts-query-builder/ascending),[`descending()`](/contacts-query-builder/descending)|\n|`_updatedDate`|[`eq()`](/contacts-query-builder/eq),[`ne()`](/contacts-query-builder/ne),[`gt()`](/contacts-query-builder/gt),[`lt()`](/contacts-query-builder/lt),[`ge()`](/contacts-query-builder/ge),[`le()`](/contacts-query-builder/le)|\n|`lastActivity.activityDate`|[`eq()`](/contacts-query-builder/eq),[`ne()`](/contacts-query-builder/ne),[`gt()`](/contacts-query-builder/gt),[`lt()`](/contacts-query-builder/lt),[`ge()`](/contacts-query-builder/ge),[`le()`](/contacts-query-builder/le),[`ascending()`](/contacts-query-builder/ascending),[`descending()`](/contacts-query-builder/descending)|\n|`primaryInfo.email`|[`eq()`](/contacts-query-builder/eq),[`ne()`](/contacts-query-builder/ne),[`in()`](/contacts-query-builder/in),[`exists()`](/contacts-query-builder/exists),[`startsWith()`](/contacts-query-builder/starts-with),[`ascending()`](/contacts-query-builder/ascending),[`descending()`](/contacts-query-builder/descending)|\n|`primaryInfo.phone`|[`eq()`](/contacts-query-builder/eq),[`ne()`](/contacts-query-builder/ne),[`in()`](/contacts-query-builder/in),[`exists()`](/contacts-query-builder/exists),[`startsWith()`](/contacts-query-builder/starts-with)|\n|`info.name.first`|[`eq()`](/contacts-query-builder/eq),[`ne()`](/contacts-query-builder/ne),[`in()`](/contacts-query-builder/in),[`exists()`](/contacts-query-builder/exists),[`startsWith()`](/contacts-query-builder/starts-with),[`ascending()`](/contacts-query-builder/ascending),[`descending()`](/contacts-query-builder/descending)|\n|`info.name.last`|[`eq()`](/contacts-query-builder/eq),[`ne()`](/contacts-query-builder/ne),[`in()`](/contacts-query-builder/in),[`exists()`](/contacts-query-builder/exists),[`startsWith()`](/contacts-query-builder/starts-with),[`ascending()`](/contacts-query-builder/ascending),[`descending()`](/contacts-query-builder/descending)|\n|`info.company`|[`eq()`](/contacts-query-builder/eq),[`ne()`](/contacts-query-builder/ne),[`in()`](/contacts-query-builder/in),[`exists()`](/contacts-query-builder/exists),[`startsWith()`](/contacts-query-builder/starts-with),[`ascending()`](/contacts-query-builder/ascending),[`descending()`](/contacts-query-builder/descending)|\n|`info.jobTitle`|[`eq()`](/contacts-query-builder/eq),[`ne()`](/contacts-query-builder/ne),[`in()`](/contacts-query-builder/in),[`exists()`](/contacts-query-builder/exists),[`startsWith()`](/contacts-query-builder/starts-with),[`ascending()`](/contacts-query-builder/ascending),[`descending()`](/contacts-query-builder/descending)|\n|`info.birthdate`|[`eq()`](/contacts-query-builder/eq),[`ne()`](/contacts-query-builder/ne),[`ascending()`](/contacts-query-builder/ascending),[`descending()`](/contacts-query-builder/descending)|\n|`info.locale`|[`eq()`](/contacts-query-builder/eq),[`ne()`](/contacts-query-builder/ne),[`in()`](/contacts-query-builder/in),[`exists()`](/contacts-query-builder/exists)|\n\n# Method Permissions:\n\n- Manage Events\n- Read Contacts\n- Read Members and Contacts - all read permissions\n- Manage Restaurants - all permissions\n- Manage Contacts\n- Set Up Automations\n- Manage Members and Contacts - all permissions\n\n# Method Permissions Scopes IDs:\n\n- SCOPE.EVENTS.MANAGE-EVENTS\n- SCOPE.DC-CONTACTS.READ-CONTACTS\n- SCOPE.DC-CONTACTS-MEGA.READ-MEMBERS-CONTACTS\n- SCOPE.RESTAURANTS.MEGA-SCOPES\n- SCOPE.DC-CONTACTS.MANAGE-CONTACTS\n- SCOPE.CRM.SETUP-AUTOMATIONS\n- SCOPE.DC-CONTACTS-MEGA.MANAGE-MEMBERS-CONTACTS\n\n# Method Schema Summary:\n\n# API Method Summary: `queryContacts`\n\n## Method Signature\n```javascript\ncrm.contacts.queryContacts(options)\n```\n\n## Description\nThe `queryContacts()` method creates a query to retrieve a list of contacts and returns a `ContactsQueryBuilder` object. This object allows for further refinement of the query through chaining methods to sort, filter, and control the results. The default settings for the query are:\n- `skip(0)`\n- `limit(50)`\n- `descending(\"_createdDate\")`\n\n## Parameters\n- **options**: `QueryContactsOptions`\n  - Description: Options for querying contacts.\n\n## Return Type\n- **REFERENCE<ContactsQueryBuilder>**: The method returns a `ContactsQueryBuilder` object that can be used to refine the query further.\n\n## Supported Filters & Sorting\nThe following properties can be used for filtering and sorting, along with their supported functions:\n\n| Property                     | Supported Functions                                                                                      |\n|------------------------------|---------------------------------------------------------------------------------------------------------|\n| `_id`                        | `eq()`, `ne()`, `in()`, `exists()`                                                                      |\n| `_createdDate`              | `eq()`, `ne()`, `gt()`, `lt()`, `ge()`, `le()`, `ascending()`, `descending()`                          |\n| `_updatedDate`              | `eq()`, `ne()`, `gt()`, `lt()`, `ge()`, `le()`                                                          |\n| `lastActivity.activityDate`  | `eq()`, `ne()`, `gt()`, `lt()`, `ge()`, `le()`, `ascending()`, `descending()`                          |\n| `primaryInfo.email`         | `eq()`, `ne()`, `in()`, `exists()`, `startsWith()`, `ascending()`, `descending()`                      |\n| `primaryInfo.phone`         | `eq()`, `ne()`, `in()`, `exists()`, `startsWith()`                                                    |\n| `info.name.first`           | `eq()`, `ne()`, `in()`, `exists()`, `startsWith()`, `ascending()`, `descending()`                      |\n| `info.name.last`            | `eq()`, `ne()`, `in()`, `exists()`, `startsWith()`, `ascending()`, `descending()`                      |\n| `info.company`              | `eq()`, `ne()`, `in()`, `exists()`, `startsWith()`, `ascending()`, `descending()`                      |\n| `info.jobTitle`             | `eq()`, `ne()`, `in()`, `exists()`, `startsWith()`, `ascending()`, `descending()`                      |\n| `info.birthdate`            | `eq()`, `ne()`, `ascending()`, `descending()`                                                           |\n| `info.locale`               | `eq()`, `ne()`, `in()`, `exists()`                                                                      |\n\n## Enum Properties\nThe following properties have limited allowed values (enums):\n\n- **lastActivity.activityType**: \n  - Valid values: `ARENA_NEW_LEAD`, `BOOKINGS_APPOINTMENT`, `CASHIER_BUTTON_PURCHASE`, `CONTACT_CREATED`, `CONTACT_MERGED`, `ECOM_CART_ABANDON`, `ECOM_CHECKOUT_BUYER`, `ECOM_PURCHASE`, `EVENTS_RSVP`, `FORM_SUBMITTED`, `GENERAL`, `HOTELS_CANCEL`, `HOTELS_CONFIRMATION`, `HOTELS_PURCHASE`, `HOTELS_RESERVATION`, `INBOX_FORM_SUBMITTED`, `INBOX_MESSAGE_FROM_CUSTOMER`, `INBOX_MESSAGE_TO_CUSTOMER`, `INBOX_PAYMENT_REQUEST_PAID`, `INVOICE_OVERDUE`, `INVOICE_PAY`, `MEMBER_LOGIN`, `MEMBER_REGISTER`, `MEMBER_STATUS_CHANGED`, `NEWSLETTER_SUBSCRIPTION_FORM_SUBMITTED`, `NEWSLETTER_SUBSCRIPTION_NOT_SET`, `NEWSLETTER_SUBSCRIPTION_PENDING`, `NEWSLETTER_SUBSCRIPTION_SUBSCRIBE`, `NEWSLETTER_SUBSCRIPTION_UNSUBSCRIBE`, `PHONE_SUBSCRIPTION_NOT_SET`, `PHONE_SUBSCRIPTION_PENDING`, `PHONE_SUBSCRIPTION_SUBSCRIBE`, `PHONE_SUBSCRIPTION_UNSUBSCRIBE`, `PRICE_QUOTE_ACCEPT`, `PRICE_QUOTE_EXPIRE`, `RESTAURANTS_ORDER`, `RESTAURANTS_RESERVATION`, `SHOUTOUT_CLICK`, `SHOUTOUT_OPEN`, `VIDEO_PURCHASE`, `VIDEO_RENT`\n\n- **primaryEmail.deliverabilityStatus**: \n  - Valid values: `BOUNCED`, `INACTIVE`, `NOT_SET`, `SPAM_COMPLAINT`, `VALID`\n\n- **primaryEmail.subscriptionStatus**: \n  - Valid values: `NOT_SET`, `NO_SUBSCRIPTION_STATUS`, `PENDING`, `SUBSCRIBED`, `UNSUBSCRIBED`\n\n- **primaryPhone.subscriptionStatus**: \n  - Valid values: `NOT_SET`, `NO_SUBSCRIPTION_STATUS`\n\n- **info.emails.items[].tag**: \n  - Valid values: `HOME`, `MAIN`, `UNTAGGED`, `WORK`\n\n- **info.phones.items[].tag**: \n  - Valid values: `FAX`, `HOME`, `MAIN`, `MOBILE`, `UNTAGGED`, `WORK`\n\n- **items[].info.addresses.items[].tag**: \n  - Valid values: `BILLING`, `HOME`, `SHIPPING`, `UNTAGGED`, `WORK`\n\n**Note**: Ensure to use the correct enum values when filtering or sorting based on these properties. \n\n## Possible Errors\nThe following errors may occur when using this method:\n- **400 INVALID_ARGUMENT**: Various application codes indicating unsupported filter value types, unsupported filter values, unsupported filter operators, unsupported filter fields, malformed filters, illegal limits, or unsupported sort fields.\n\n# Method Code Examples:\n\n## queryContacts\n\n```javascript\nimport { contacts } from '@wix/crm';\n\nasync function queryContacts() {\n  const { items } = await contacts.queryContacts().find();\n};\n```\n\n\n\n## default\n\n```javascript\ntry {\n      const { items } = await contacts.queryContacts().find();\n      return items;\n    } catch (error) {\n      console.error(error);\n      throw error;\n   }\n````";