@wix/mcp 1.0.8 → 1.0.10

package/README.md

@@ -1,164 +1,169 @@
-# General Config:
+# Wix MCP
 
-## From npm package:
+## Installation & Usage
 
+### From npm Package
+
+```sh
+npx @wix/mcp
 ```
-command: npx:
-args: ["@wix/mcp"]
+
+### Local Development
+
+1. Clone the repository
+2. Install dependencies
+3. Build the project
+
+Run locally with:
+
+```sh
+npx /Users/absolute/path/to/repo/dir/.
 ```
 
-## Local:
+Or directly with Node:
+
+```sh
+node /Users/absolute/path/to/build/bin-standalone.js
+```
+
+## Configuration Options
+
+### Tool Selection
 
-First: clone + install + build
+Enable specific standard tools (all enabled by default):
 
 ```
-command: npx
-args: ["/Users/absolute/path/to/repo/dir/."]
+--tools=WDS,REST,SDK,WIX_HEADLESS,BUILD_APPS
 ```
 
+### Experimental Tools
+
+Enable experimental tools (disabled by default):
+
 ```
-command: node
-args: ["/Users/absolute/path/to/build/bin.js"]
+--experimental=WIX_API,CLI_COMMAND
 ```
 
-# Optional config arguments:
+### CLI Mode
 
-### 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)
+Specify CLI mode:
 
-### enable experimental tools:
-`--experimental=WIX_API,CLI_COMMAND` - enable specific experimental tools (disabled by default)
+```
+--cli=wix-one
+```
 
-### choose a CLI mode:
-`--cli=wix-one` - specifies to use Wix One CLI mode (if not specified, default CLI mode is used)
+### Logger
 
-### choose a logger:
-`--logger=mcp` - log to MCP server (default)
-`--logger=file` - log to file (in `~/wix-mcp-log.txt`)
+Set logging output:
 
-Available tool options:
+- `--logger=mcp` (default, logs to MCP server)
+- `--logger=file` (logs to `~/wix-mcp-log.txt`)
 
-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`)
+### Tool Reference
 
-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`)
+**Standard Tools:**
+- `WDS`: Wix Design System Documentation (`SearchWixWDSDocumentation`)
+- `REST`: Wix REST API Documentation (`SearchWixRESTDocumentation`)
+- `SDK`: Wix SDK Documentation (`SearchWixSDKDocumentation`)
+- `BUILD_APPS`: Build Apps Documentation (`SearchBuildAppsDocumentation`)
+- `WIX_HEADLESS`: Wix Headless Documentation (`SearchWixHeadlessDocumentation`)
 
-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.
+**Experimental Tools:**
+- `WIX_API`: Wix API tools (`CallWixAPI`)
+- `CLI_COMMAND`: CLI commands for Wix apps (`RunWixCliCommand`)
 
-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.
+> Experimental tools are in early development and may have limited functionality or breaking changes. They must be explicitly enabled with `--experimental`.
 
-# Resource Feature
+## Resources
 
-The resource feature provides access to Wix documentation through the MCP server. It:
+The resource feature provides access to Wix documentation via the MCP server:
 
-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
+- Fetches documentation indexes from specified Wix portals
+- Makes documentation articles available as resources
+- 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
+Resources use the `wix-docs://` URI scheme, which maps to Wix Docs URLs:
 
-pass:
-`--portals=<docs-portal-name>`
-to load all docs from the portal as resources
+- Docs URL: `https://dev.wix.com/docs/...`
+- Resource URI: `wix-docs://...`
 
+To load all docs from a portal:
 
-# Cursor
+```
+--portals=<docs-portal-name>
+```
 
-## Cursor MCP docs:
+## Cursor Integration
 
-https://docs.cursor.com/context/model-context-protocol
+### MCP Docs
 
-## Config:
+See: https://docs.cursor.com/context/model-context-protocol
 
-## using `~/.cursor/mcp.json`
+### Configuration (`~/.cursor/mcp.json`)
 
-### with npx:
+#### Using npm package
 
-```
+```json
 {
   "mcpServers": {
     "wix-local-mcp": {
       "command": "npx",
-      "args": [
-        "-y",
-        "@wix/mcp"
-      ]
+      "args": ["-y", "@wix/mcp"]
     }
   }
 }
 ```
 
-### With npx locally:
-```
+#### Using local build
+
+```json
 {
   "mcpServers": {
     "wix-local-mcp": {
       "command": "npx",
-      "args": [
-        "/Users/absolute/path/to/repo/dir/."
-      ]
+      "args": ["/Users/absolute/path/to/repo/dir/."]
     }
   }
 }
 ```
 
-### with node:
-
-1. clone
-2. build
+#### Using Node
 
-```
+```json
 {
   "mcpServers": {
     "wix-local-mcp": {
       "command": "node",
-      "args": [
-        "/Users/absolute/path/to/build/bin.js"
-      ]
+      "args": ["/Users/absolute/path/to/build/bin-standalone.js"]
     }
   }
 }
 ```
 
-### You can try using bun + index.ts 
+## Troubleshooting
 
-# 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
-- log should be written to `~/wix-mcp-log.txt`
-- add .env file with `WIX_COOKIE=` to avoid rate limits on SDK tool use
+- Check logs from Claude Desktop or Cursor
+- For Node/fnm/nvm errors: ensure the latest Node version is set as default
+- For npx errors: use `-y` and the correct npm registry
+- Try specifying the full path to Node
+- Try using Bun and `index.ts` directly
+- Ensure build files have appropriate permissions
 
-## NVM possible fix:
-```
-  "wix-mcp-remote-prod": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@wix/mcp-remote",
-        "https://mcp.wix.com/sse"
-      ],
-      "env": {
-        "PATH": "<path-to-your-nvm-node-version>/bin"
-      }
-    }
+### NVM Example Fix
+
+```json
+"wix-mcp-remote-prod": {
+  "command": "npx",
+  "args": ["-y", "@wix/mcp-remote", "https://mcp.wix.com/sse"],
+  "env": {
+    "PATH": "<path-to-your-nvm-node-version>/bin"
+  }
+}
 ```
 
-## fnm possible fix:
+### FNM Example Fix
 
-```
+```json
 {
   "mcpServers": {
     "wix-mcp-remote-prod": {
@@ -172,5 +177,4 @@ https://docs.cursor.com/context/model-context-protocol
 }
 ```
 
-
-
+> Node 20 is required to build.

package/build/bin-standalone.js

@@ -5341,16 +5341,15 @@ var require_browser = __commonJS({
   }
 });
 
-// ../../node_modules/supports-color/node_modules/has-flag/index.js
+// ../../node_modules/has-flag/index.js
 var require_has_flag = __commonJS({
-  "../../node_modules/supports-color/node_modules/has-flag/index.js"(exports, module) {
+  "../../node_modules/has-flag/index.js"(exports, module) {
     "use strict";
-    module.exports = (flag, argv) => {
-      argv = argv || process.argv;
+    module.exports = (flag, argv = process.argv) => {
       const prefix = flag.startsWith("-") ? "" : flag.length === 1 ? "-" : "--";
-      const pos = argv.indexOf(prefix + flag);
-      const terminatorPos = argv.indexOf("--");
-      return pos !== -1 && (terminatorPos === -1 ? true : pos < terminatorPos);
+      const position = argv.indexOf(prefix + flag);
+      const terminatorPosition = argv.indexOf("--");
+      return position !== -1 && (terminatorPosition === -1 || position < terminatorPosition);
     };
   }
 });
@@ -5360,16 +5359,23 @@ var require_supports_color = __commonJS({
   "../../node_modules/supports-color/index.js"(exports, module) {
     "use strict";
     var os = __require("os");
+    var tty = __require("tty");
     var hasFlag = require_has_flag();
-    var env = process.env;
+    var { env } = process;
     var forceColor;
-    if (hasFlag("no-color") || hasFlag("no-colors") || hasFlag("color=false")) {
-      forceColor = false;
+    if (hasFlag("no-color") || hasFlag("no-colors") || hasFlag("color=false") || hasFlag("color=never")) {
+      forceColor = 0;
     } else if (hasFlag("color") || hasFlag("colors") || hasFlag("color=true") || hasFlag("color=always")) {
-      forceColor = true;
+      forceColor = 1;
     }
     if ("FORCE_COLOR" in env) {
-      forceColor = env.FORCE_COLOR.length === 0 || parseInt(env.FORCE_COLOR, 10) !== 0;
+      if (env.FORCE_COLOR === "true") {
+        forceColor = 1;
+      } else if (env.FORCE_COLOR === "false") {
+        forceColor = 0;
+      } else {
+        forceColor = env.FORCE_COLOR.length === 0 ? 1 : Math.min(parseInt(env.FORCE_COLOR, 10), 3);
+      }
     }
     function translateLevel(level) {
       if (level === 0) {
@@ -5382,8 +5388,8 @@ var require_supports_color = __commonJS({
         has16m: level >= 3
       };
     }
-    function supportsColor(stream) {
-      if (forceColor === false) {
+    function supportsColor(haveStream, streamIsTTY) {
+      if (forceColor === 0) {
         return 0;
       }
       if (hasFlag("color=16m") || hasFlag("color=full") || hasFlag("color=truecolor")) {
@@ -5392,19 +5398,22 @@ var require_supports_color = __commonJS({
       if (hasFlag("color=256")) {
         return 2;
       }
-      if (stream && !stream.isTTY && forceColor !== true) {
+      if (haveStream && !streamIsTTY && forceColor === void 0) {
         return 0;
       }
-      const min = forceColor ? 1 : 0;
+      const min = forceColor || 0;
+      if (env.TERM === "dumb") {
+        return min;
+      }
       if (process.platform === "win32") {
         const osRelease = os.release().split(".");
-        if (Number(process.versions.node.split(".")[0]) >= 8 && Number(osRelease[0]) >= 10 && Number(osRelease[2]) >= 10586) {
+        if (Number(osRelease[0]) >= 10 && Number(osRelease[2]) >= 10586) {
           return Number(osRelease[2]) >= 14931 ? 3 : 2;
         }
         return 1;
       }
       if ("CI" in env) {
-        if (["TRAVIS", "CIRCLECI", "APPVEYOR", "GITLAB_CI"].some((sign) => sign in env) || env.CI_NAME === "codeship") {
+        if (["TRAVIS", "CIRCLECI", "APPVEYOR", "GITLAB_CI", "GITHUB_ACTIONS", "BUILDKITE"].some((sign) => sign in env) || env.CI_NAME === "codeship") {
           return 1;
         }
         return min;
@@ -5433,19 +5442,16 @@ var require_supports_color = __commonJS({
       if ("COLORTERM" in env) {
         return 1;
       }
-      if (env.TERM === "dumb") {
-        return min;
-      }
       return min;
     }
     function getSupportLevel(stream) {
-      const level = supportsColor(stream);
+      const level = supportsColor(stream, stream && stream.isTTY);
       return translateLevel(level);
     }
     module.exports = {
       supportsColor: getSupportLevel,
-      stdout: getSupportLevel(process.stdout),
-      stderr: getSupportLevel(process.stderr)
+      stdout: translateLevel(supportsColor(true, tty.isatty(1))),
+      stderr: translateLevel(supportsColor(true, tty.isatty(2)))
     };
   }
 });
@@ -15001,6 +15007,27 @@ var runSemanticSearchAndFormat = async ({
 
 // src/docs/docs.ts
 import { captureException } from "@sentry/node";
+
+// src/docs/fetch-article.ts
+async function fetchArticleContentFromDigor(httpClient, articleUrl, mode) {
+  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 { data } = await httpClient.get(url.toString());
+  logger.log(`Fetched resource from docs: ${data.articleContent}`);
+  return data.articleContent;
+}
+async function fetchArticleContent(httpClient, articleUrl, mode) {
+  if (mode === "raw") {
+    const { data: doc } = await httpClient.get(articleUrl);
+    return doc;
+  }
+  return fetchArticleContentFromDigor(httpClient, articleUrl, mode);
+}
+
+// src/docs/docs.ts
 var VALID_DOCS_TOOLS = [
   "WDS",
   "REST",
@@ -15455,15 +15482,44 @@ var addDocsTools = (server2, allowedTools = [
     }
   );
 };
-async function fetchArticleContent(httpClient, articleUrl, mode) {
-  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 { data } = await httpClient.get(url.toString());
-  logger.log(`Fetched resource from docs: ${data.articleContent}`);
-  return data.articleContent;
+
+// src/docs/get-to-know.ts
+var defaultDocUrl = "https://dev.wix.com/docs/picasso/wix-ai-docs/rules/get-to-know-wix-llm-instructions";
+var DESCRIPTION = `\u{1F534} **REQUIRED FIRST STEP for all Wix tasks.** This tool is the primary guide for the Wix ecosystem, offering global setup instructions and current best practices.
+
+**Rule: ALWAYS run this tool successfully BEFORE any other Wix-specific action (e.g., doc searches, API calls, coding). NO EXCEPTIONS.** Failing to do so will likely cause errors.
+
+The information from this tool is foundational and MUST inform all subsequent Wix actions.
+
+**Instructions for user requests:**
+
+1.  **Identify Wix concepts** relevant to the query (refer to ReadMe).
+2.  **Read best practices:** For each concept, if a \`<best-practices>{url}</best-practices>\` document exists in ReadMe, use 'ReadFullDocsArticle' to access it.
+3.  **Search:** If more information is needed, use 'SearchX' tools.`;
+async function addGetToKnowTools(server2, docUrl) {
+  server2.tool("WixREADME", DESCRIPTION, async ({ httpClient }) => {
+    try {
+      const doc = docUrl ? await fetchArticleContent(httpClient, docUrl, "raw") : await fetchArticleContent(httpClient, defaultDocUrl, "article");
+      return {
+        content: [
+          {
+            type: "text",
+            text: doc
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Error fetching the document: ${error.message}`
+          }
+        ]
+      };
+    }
+  });
 }
 
 // src/cli-tools/cli.ts
@@ -16268,7 +16324,11 @@ var addDocsResources = async (server2, portals) => {
 
 // src/bin.ts
 var PUBLIC_TOOLS = [...VALID_DOCS_TOOLS];
-var EXPERIMENTAL_TOOLS = ["WIX_API", "CLI_COMMAND"];
+var EXPERIMENTAL_TOOLS = [
+  "WIX_API",
+  "CLI_COMMAND",
+  "GET_TO_KNOW_WIX"
+];
 var DEFAULT_TOOLS = [...VALID_DOCS_TOOLS];
 var parsedArgs = minimist(process.argv.slice(2));
 function parseExperimentalArg() {
@@ -16342,6 +16402,10 @@ if (cliTools.length > 0) {
   logger.log("Adding cli tools:", cliTools, "isWixOne:", isWixOne);
   addCliTools(server, cliTools, isWixOne);
 }
+if (activeTools.includes("GET_TO_KNOW_WIX")) {
+  const docUrl = parsedArgs["get-to-know-wix-url"];
+  await addGetToKnowTools(server, docUrl);
+}
 try {
   const portals = parsedArgs["portals"]?.split(",") || [];
   if (portals.length > 0) {