@wix/mcp 1.0.0

package/README.md

@@ -0,0 +1,131 @@
+# General Config:
+
+## From npm package:
+
+```
+command: npx:
+args: ["@wix/mcp"]
+```
+
+## Local:
+
+First: clone + install + build
+
+```
+command: npx
+args: ["/Users/absolute/path/to/repo/dir/."]
+```
+
+```
+command: node
+args: ["/Users/absolute/path/to/build/index.js"]
+```
+
+# Optional config arguments:
+
+### choose a tool:
+`--tools=WDS,REST,SDK,WIX_HEADLESS,BUILD_APPS` - specify which standard tools to enable (if not specified, all standard tools are enabled)
+
+### enable experimental tools:
+`--experimental=WIX_API,CLI_COMMAND` - enable specific experimental tools (disabled by default)
+
+### choose a logger:
+`--logger=mcp` - log to MCP server (default)
+`--logger=file` - log to file (in `~/wix-mcp-log.txt`)
+
+Available tool options:
+
+Standard tools (all enabled by default if no --tools specified):
+- `WDS`: Wix Design System Documentation tools (MCP tool: `SearchWixWDSDocumentation`)
+- `REST`: Wix REST API Documentation tools (MCP tool: `SearchWixRESTDocumentation`)
+- `SDK`: Wix SDK Documentation tools (MCP tool: `SearchWixSDKDocumentation`)
+- `BUILD_APPS`: Build Apps Documentation tools (MCP tool: `SearchBuildAppsDocumentation`)
+- `WIX_HEADLESS`: Wix Headless Documentation tools (MCP tool: `SearchWixHeadlessDocumentation`)
+
+Experimental tools (disabled by default):
+- `WIX_API`: Wix API tools for calling APIs on a Wix app (MCP tool: `CallWixAPI`)
+- `CLI_COMMAND`: CLI commands for working with Wix apps (MCP tool: `RunWixCliCommand`)
+
+Note: Experimental tools are in early development and may have limited functionality or breaking changes. These tools are disabled by default and must be explicitly enabled via the --experimental argument, regardless of whether --tools is specified or not.
+
+The tool enum value (e.g. `WDS`) is used in the `--tools` and `--experimental` arguments, while the MCP tool name (e.g. `SearchWixWDSDocumentation`) is what you'll see in the actual tool calls.
+
+# Resource Feature
+
+The resource feature provides access to Wix documentation through the MCP server. It:
+
+1. Fetches documentation indexes from specified Wix portals
+2. Makes documentation articles available as resources through the MCP server
+3. Allows fetching article content using the MCP protocol
+
+Resources are accessible using the `wix-docs://` URI scheme, which maps to the corresponding Wix documentation URLs.
+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
+
+# Cursor
+
+## Cursor MCP docs:
+
+https://docs.cursor.com/context/model-context-protocol
+
+## Config:
+
+## using `~/.cursor/mcp.json`
+
+### with npx:
+
+```
+{
+  "mcpServers": {
+    "IGOR_TOOLS": {
+      "command": "npx",
+      "args": [
+        "@wix/mcp"
+      ]
+    }
+  }
+}
+```
+
+### With npx locally:
+```
+{
+  "mcpServers": {
+    "IGOR_TOOLS": {
+      "command": "npx",
+      "args": [
+        "/Users/absolute/path/to/repo/dir/."
+      ]
+    }
+  }
+}
+```
+
+### with node:
+
+1. clone
+2. build
+
+```
+{
+  "mcpServers": {
+    "IGOR_TOOLS": {
+      "command": "node",
+      "args": [
+        "/Users/absolute/path/to/build/index.js"
+      ]
+    }
+  }
+}
+```
+
+### You can try using bun + index.ts 
+
+# Troubleshooting
+
+- try including full path to node
+- try using bun and index.ts directly
+- make sure build files have permissions for cursor to access
+- log should be written to `~/wix-mcp-log.txt`
+- add .env file with `WIX_COOKIE=` to avoid rate limits on SDK tool use

package/bin.js

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

package/build/cli-tools/cli.js

@@ -0,0 +1,295 @@
+import { z } from 'zod';
+import { getCliAuthTokenForSiteId, getSiteIdFromCliAppConfig, handleWixAPIResponse } from './utils.js';
+import { logger } from '../logger.js';
+import { execa } from 'execa';
+import { mockInteractiveGenerateCommandTool } from '../interactive-command-tools/interactive-command-utils.js';
+export const VALID_CLI_TOOLS = [
+    'WIX_API',
+    'CLI_COMMAND',
+    'CLI_COMMAND_INTERACTIVE_MODE'
+];
+export function addCliTools(server, allowedTools = [
+    'WIX_API',
+    'CLI_COMMAND',
+    'CLI_COMMAND_INTERACTIVE_MODE'
+]) {
+    if (allowedTools.includes('WIX_API')) {
+        server.tool('CallWixAPI', 'Call Wix apis on an app. Use this to create, read, update, and delete data and other Wix entities in your Wix app.', {
+            appPath: z
+                .string()
+                .describe('The dir path to the wix backoffice cli app to call the api on behalf of'), // should we have appPath or siteId here? (appPath encapsulates this more since we can get the siteId from the appPath then perform the call)
+            url: z
+                .string()
+                .describe('The url of the api to call - usually you get this from the Wix REST docs or from the conversation context'),
+            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 ({ method, url, body, appPath }) => {
+            logger.log(`Calling Wix API: ${appPath} ${method} ${url}, body: ${JSON.stringify(body)}`);
+            const siteId = getSiteIdFromCliAppConfig(appPath);
+            logger.log(`Site ID for Wix API call: ${siteId}`);
+            const authorization = getCliAuthTokenForSiteId(siteId);
+            try {
+                const response = await fetch(url, {
+                    method,
+                    headers: {
+                        Authorization: authorization,
+                        ...(body ? { 'Content-Type': 'application/json' } : {})
+                    },
+                    body
+                });
+                const responseData = await handleWixAPIResponse(response);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Wix API call successful: ${JSON.stringify(responseData)}`
+                        }
+                    ]
+                };
+            }
+            catch (error) {
+                logger.error(`Failed to call Wix API: ${error}`);
+                throw new Error(`Failed to call Wix API: ${error}`);
+            }
+        });
+    }
+    if (allowedTools.includes('CLI_COMMAND_INTERACTIVE_MODE')) {
+        server.tool('RunWixCliCommandInteractiveMode', `Executes Wix CLI commands for Wix app development and management.
+    Use this tool to run commands like 'wix app generate' (adds new extensions), 'wix app build' (builds your app), 'wix app preview' (creates shareable preview), 'wix app release' (releases a new version of your app), and more.
+
+    IMPORTANT: Before using this tool, check if the command is mapped in package.json scripts:
+    * Use this tool for npm/yarn scripts that map to Wix CLI commands as well.
+    * Do not use this tool for starting the local development server.
+    
+    Before using this tool, you MUST search the Wix documentation for the command you want to run.
+    
+    DO NOT USE THIS TOOL FOR ANY OTHER PURPOSE. IT IS ONLY FOR WIX CLI COMMANDS.`, {
+            appPath: z
+                .string()
+                .describe('The full path to the Wix CLI app to run the command on'),
+            extensionType: z
+                .enum(['DASHBOARD_PAGE', 'BACKEND_EVENT'])
+                .optional()
+                .describe('The type of extension to generate. You MUST provide this for commands that generate extensions.'),
+            searchedDocs: z
+                .boolean()
+                .describe('Whether you have already searched the Wix documentation for the command you want to run.'),
+            command: z
+                .string()
+                .min(1, 'Command cannot be empty')
+                .max(1000, 'Command is too long')
+                .describe("The Wix CLI command to execute (e.g. 'wix app generate', 'wix app build', 'wix app preview', 'wix app release', etc.), or a npm/yarn script that maps to a Wix CLI command (e.g. 'npm run generate', 'yarn build', etc.).")
+        }, async ({ command, appPath, extensionType }) => {
+            command = command.replace('wix app generate', 'npm run generate');
+            if (command.includes('generate') && !extensionType) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: "Error: You must provide an extension type for the 'generate' command."
+                        }
+                    ],
+                    isError: true
+                };
+            }
+            logger.log(`RunWixCliCommand: command: ${command}, appPath: ${appPath}, extensionType: ${extensionType}`);
+            try {
+                logger.log(`Executing Wix CLI command: ${command}`);
+                const commandParts = command.split(' ');
+                const commandName = commandParts[0];
+                const commandArgs = commandParts.slice(1);
+                // Execute with timeout
+                const subprocess = execa(commandName, commandArgs, {
+                    cwd: appPath,
+                    extendEnv: true,
+                    env: {
+                        ...process.env,
+                        PATH: process.env.PATH,
+                        WIX_CLI_TEST_OVERRIDES: JSON.stringify({
+                            inkDebug: true
+                        })
+                    },
+                    timeout: 5 * 60 * 1000, // 5 minute timeout
+                    maxBuffer: 10 * 1024 * 1024 // 10MB output limit
+                });
+                logger.log(`RunWixCliCommand: pid: ${subprocess.pid}`);
+                if (!subprocess.pid) {
+                    let spawnError;
+                    // make sure spawnError is defined by waiting for the error event
+                    if (!spawnError) {
+                        await new Promise((resolve) => {
+                            subprocess.on('error', (err) => {
+                                spawnError = err;
+                                resolve({ spawnError });
+                            });
+                        });
+                    }
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Failed to start the Wix CLI command process. This usually indicates a problem with the command or the environment. Are you sure Wix CLI is installed globally?\n\nCommand: ${command}\n\n${spawnError}`
+                            }
+                        ]
+                    };
+                }
+                const { stdin, stdout, stderr } = subprocess;
+                if (extensionType) {
+                    const output = await mockInteractiveGenerateCommandTool({
+                        extensionType,
+                        stdin,
+                        stdout
+                    });
+                    logger.log(`RunWixCliCommand: output: ${output}`);
+                    return {
+                        content: [{ type: 'text', text: output }]
+                    };
+                }
+                const stringifyStdout = JSON.stringify(stdout);
+                const stringifyStderr = JSON.stringify(stderr);
+                return {
+                    content: [
+                        { type: 'text', text: stringifyStdout },
+                        ...(stringifyStderr
+                            ? [{ type: 'text', text: `Error: ${stringifyStderr}` }]
+                            : [])
+                    ]
+                };
+            }
+            catch (error) {
+                logger.error(`Error executing Wix CLI command: ${error}`);
+                return {
+                    content: [{ type: 'text', text: `Error: ${error}` }],
+                    isError: true
+                };
+            }
+        });
+    }
+    if (allowedTools.includes('CLI_COMMAND')) {
+        server.tool('RunWixCliCommand', `Executes Wix CLI commands for Wix app development and management.
+    Use this tool to run commands like 'wix app generate' (adds new extensions), 'wix app build' (builds your app), 'wix app preview' (creates shareable preview), 'wix app release' (releases a new version of your app), and more.
+
+    IMPORTANT: Before using this tool, check if the command is mapped in package.json scripts:
+    * Use this tool for npm/yarn scripts that map to Wix CLI commands as well.
+    * Do not use this tool for starting the local development server.
+    
+    Before using this tool, you MUST search the Wix documentation for the command you want to run.
+    
+    DO NOT USE THIS TOOL FOR ANY OTHER PURPOSE. IT IS ONLY FOR WIX CLI COMMANDS.`, {
+            appPath: z
+                .string()
+                .describe('The full path to the Wix CLI app to run the command on'),
+            extensionType: z
+                .enum([
+                'dashboard-page',
+                'dashboard-plugin',
+                'dashboard-menu-plugin',
+                'dashboard-modal',
+                'web-method',
+                'api-route',
+                'event',
+                'service-plugin'
+            ])
+                .optional()
+                .describe('The type of extension to generate. You MUST provide this for commands that generate extensions.'),
+            extensionName: z
+                .string()
+                .optional()
+                .describe('The name of the extension to generate, e.g. My Dashboard Page. You MUST provide this for commands that generate extensions.'),
+            searchedDocs: z
+                .boolean()
+                .describe('Whether you have already searched the Wix documentation for the command you want to run.'),
+            command: z
+                .string()
+                .min(1, 'Command cannot be empty')
+                .max(1000, 'Command is too long')
+                .describe("The Wix CLI command to execute (e.g. 'wix app generate', 'wix app build', 'wix app preview', 'wix app release', etc.), or a script that maps to a Wix CLI command (e.g. 'npm run generate', 'yarn generate', etc.).")
+        }, async ({ command, appPath, extensionType, extensionName }) => {
+            logger.log(`RunWixCliCommand: command: ${command}, appPath: ${appPath}, extensionType: ${extensionType}, extensionName: ${extensionName}`);
+            let commandName = '';
+            let commandArgs = [];
+            if (command.includes('generate')) {
+                if (!extensionType) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: "Error: You must provide an extension type for the 'generate' command."
+                            }
+                        ],
+                        isError: true
+                    };
+                }
+                if (!extensionName) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: "Error: You must provide an extension name for the 'generate' command."
+                            }
+                        ],
+                        isError: true
+                    };
+                }
+                // Format generate command with proper arguments
+                commandName = 'npx';
+                commandArgs = [
+                    'wix',
+                    'app',
+                    'generate',
+                    '-t',
+                    extensionType,
+                    '-n',
+                    extensionName,
+                    '--json'
+                ];
+            }
+            else {
+                const commandParts = command.split(' ');
+                commandName = commandParts[0];
+                commandArgs = commandParts.slice(1);
+            }
+            try {
+                logger.log(`Executing Wix CLI command: ${commandName} ${commandArgs.join(' ')}`);
+                // Execute with timeout
+                const { stdout, stderr, exitCode } = await execa(commandName, commandArgs, {
+                    cwd: appPath,
+                    extendEnv: true,
+                    env: {
+                        ...process.env
+                    },
+                    timeout: 5 * 60 * 1000, // 5 minute timeout
+                    maxBuffer: 10 * 1024 * 1024 // 10MB output limit
+                });
+                if (exitCode !== 0) {
+                    return {
+                        content: [{ type: 'text', text: `Error: ${stderr}` }],
+                        isError: true
+                    };
+                }
+                logger.log(`RunWixCliCommand: stdout: ${stdout}`);
+                logger.log(`RunWixCliCommand: stderr: ${stderr}`);
+                return {
+                    content: [
+                        { type: 'text', text: stdout },
+                        ...(stderr
+                            ? [{ type: 'text', text: `Error: ${stderr}` }]
+                            : [])
+                    ]
+                };
+            }
+            catch (error) {
+                logger.error(`Error executing Wix CLI command: ${error}`);
+                return {
+                    content: [{ type: 'text', text: `Error: ${error}` }],
+                    isError: true
+                };
+            }
+        });
+    }
+}

package/build/cli-tools/utils.js

@@ -0,0 +1,31 @@
+import { readFileSync } from 'fs';
+import { homedir } from 'os';
+import path from 'path';
+export function getCliAuthTokenForSiteId(siteIdOrAccountsFileName) {
+    const authData = JSON.parse(readFileSync(path.join(homedir(), `.wix/auth/${siteIdOrAccountsFileName}.json`), 'utf8'));
+    return authData.accessToken;
+}
+// f"first get the site id - its in the `{backoffice_app_dir}/.wix/app.config.json` file, it has a json object with a siteId field",
+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;
+};