@W-21048944 Support Plugins and docs update (#253)

yhsieh1 · web-flow · commit 1147ea300b8f · 2026-03-12T17:14:22.000-04:00
diff --git a/.changeset/mcp-dirname-change.md b/.changeset/mcp-dirname-change.md
@@ -0,0 +1,5 @@
+---
+'@salesforce/b2c-dx-mcp': patch
+---
+
+Changed oclif dirname from `b2c-dx-mcp` to `b2c` so the MCP server shares the same plugin directory as the CLI, enabling plugin discovery and unified plugin management.
diff --git a/.changeset/mcp-docs-improvements.md b/.changeset/mcp-docs-improvements.md
@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-dx-mcp': patch
+'@salesforce/b2c-dx-docs': patch
+---
+
+Improved MCP documentation: added `@latest` to all examples to prevent Windows caching issues, standardized server name to `b2c-dx-mcp`, updated GitHub Copilot examples to use correct `servers` format with `type: stdio`, clarified MRT configuration options (`mrtProject`, `mrtEnvironment`, `mrtApiKey` in dw.json vs `api_key` in ~/.mobify), changed "Claude Desktop" to "Claude Code" throughout, simplified authentication sections, and improved flag documentation consistency across tool pages.
diff --git a/docs/mcp/configuration.md b/docs/mcp/configuration.md
@@ -10,9 +10,11 @@ The B2C DX MCP Server uses the same configuration system as the B2C CLI. For MCP
 
 Credentials are resolved in the following priority order (same as the CLI):
 
-1. **Flags** (highest priority)
-2. **Environment variables**
-3. **Config files** (lowest priority)
+1. **Flags** (highest priority) - e.g., `--server`, `--api-key`, `--project`
+2. **Environment variables** - Set in MCP client's `env` object
+3. **Config files** (lowest priority) - `dw.json` (project-level) and `~/.mobify` (user-level for MRT API key)
+
+**Note:** For MRT API key specifically, `dw.json` (`mrtApiKey` field) takes precedence over `~/.mobify` when both are present.
 
 ## Credential Sources
 
@@ -38,23 +40,23 @@ Create a [`dw.json`](../guide/configuration#configuration-file) file in your pro
 }
 ```
 
-The server automatically loads this file when using project-level installation (recommended). With user-level Cursor configuration, ensure `--project-directory` points to your project.
+The server automatically loads this file when using project-level configuration (recommended). With user-level Cursor configuration, ensure `--project-directory "${workspaceFolder}"` is included in the args array. Claude Code and GitHub Copilot automatically detect the project location.
 
 **Required fields per toolset:**
 
 | Toolset | Required Fields |
 |---------|----------------|
 | **SCAPI** | `short-code`, `tenant-id`, `client-id`, `client-secret` |
 | **CARTRIDGES** | `hostname`, `username`, `password` (or OAuth: `hostname`, `client-id`, `client-secret`) |
-| **MRT** | `project`, MRT API key (from `~/.mobify` or `--api-key`) |
+| **MRT** | `mrtProject` (from `dw.json` `mrtProject` field or `--project` flag), MRT API key (from `dw.json` `mrtApiKey`, `~/.mobify` `api_key`, or `--api-key` flag) |
 | **PWAV3** | None (project directory auto-detected with project-level installation) |
 | **STOREFRONTNEXT** | None (project directory auto-detected with project-level installation) |
 
 **Note:** Some tools require specific scopes. See [Configuring Scopes](../guide/authentication#configuring-scopes) in the Authentication Setup guide and individual tool pages for scope requirements.
 
 #### MRT Credentials (`~/.mobify`)
 
-MRT API keys are loaded from [`~/.mobify`](../guide/configuration#mrt-api-key) using the same format and resolution order as the CLI.
+MRT tools require an API key for authentication. MRT API keys are stored in a separate [`~/.mobify`](../guide/configuration#mrt-api-key) file in your home directory.
 
 Create the `~/.mobify` file manually:
 
@@ -64,18 +66,26 @@ Create the `~/.mobify` file manually:
 }
 ```
 
-For complete setup instructions, see the [Authentication Guide](../guide/authentication#managed-runtime-api-key).
+**File locations:**
+- Default: `~/.mobify`
+- With `--cloud-origin`: `~/.mobify--{hostname}` (e.g., `~/.mobify--custom.example.com` for `--cloud-origin https://custom.example.com`)
+
+**Note:** The `dw.json` file can include `mrtProject`, `mrtEnvironment`, and `mrtApiKey` for project-level MRT configuration. Alternatively, the API key can be stored in `~/.mobify` (user-level, shared across projects). If both are present, `dw.json` takes precedence. Environment variables and flags can override these values (see [Configuration Priority](#configuration-priority)).
+
+For complete setup instructions, including how to get your API key, see the [Authentication Guide](../guide/authentication#managed-runtime-api-key).
 
 ### Option 2: Environment Variables
 
 Set environment variables in the `env` object of your MCP client configuration. The MCP server supports the same environment variables as the CLI. See the [CLI Configuration guide](../guide/configuration#environment-variables) for the complete list of supported variables.
 
+> **Note:** Examples below use `mcpServers` (Cursor format). For GitHub Copilot/VS Code, use `servers` instead and add `"type": "stdio"` (see [Installation](./installation#github-copilot)).
+
 ```json
 {
   "mcpServers": {
-    "b2c-dx": {
+    "b2c-dx-mcp": {
       "command": "npx",
-      "args": ["-y", "@salesforce/b2c-dx-mcp", "--allow-non-ga-tools"],
+      "args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--allow-non-ga-tools"],
       "env": {
         "SFCC_SERVER": "xxx.demandware.net",
         "SFCC_CLIENT_ID": "...",
@@ -96,11 +106,11 @@ Pass credentials directly as command-line flags:
 ```json
 {
   "mcpServers": {
-    "b2c-dx": {
+    "b2c-dx-mcp": {
       "command": "npx",
       "args": [
         "-y",
-        "@salesforce/b2c-dx-mcp",
+        "@salesforce/b2c-dx-mcp@latest",
         "--server",
         "xxx.demandware.net",
         "--username",
@@ -135,11 +145,11 @@ Override auto-discovery by specifying toolsets explicitly:
 ```json
 {
   "mcpServers": {
-    "b2c-dx": {
+    "b2c-dx-mcp": {
       "command": "npx",
       "args": [
         "-y",
-        "@salesforce/b2c-dx-mcp",
+        "@salesforce/b2c-dx-mcp@latest",
         "--toolsets",
         "CARTRIDGES,MRT",
         "--allow-non-ga-tools"
diff --git a/docs/mcp/index.md b/docs/mcp/index.md
@@ -28,16 +28,16 @@ The MCP server automatically detects your project type and enables relevant tool
 
 ```bash [Project Scope (Recommended)]
 cd /path/to/your/project
-claude mcp add --transport stdio --scope project b2c-dx -- npx -y @salesforce/b2c-dx-mcp --allow-non-ga-tools
+claude mcp add --transport stdio --scope project b2c-dx-mcp -- npx -y @salesforce/b2c-dx-mcp@latest --allow-non-ga-tools
 ```
 
 ```bash [User Scope]
-claude mcp add --transport stdio --scope user b2c-dx -- npx -y @salesforce/b2c-dx-mcp --allow-non-ga-tools
+claude mcp add --transport stdio --scope user b2c-dx-mcp -- npx -y @salesforce/b2c-dx-mcp@latest --allow-non-ga-tools
 ```
 
 :::
 
-**Cursor:** [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=b2c-dx&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzYWxlc2ZvcmNlL2IyYy1keC1tY3AiLCItLXByb2plY3QtZGlyZWN0b3J5IiwiJHt3b3Jrc3BhY2VGb2xkZXJ9IiwiLS1hbGxvdy1ub24tZ2EtdG9vbHMiXX0=)
+**Cursor:** [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=b2c-dx-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzYWxlc2ZvcmNlL2IyYy1keC1tY3BAbGF0ZXN0IiwiLS1wcm9qZWN0LWRpcmVjdG9yeSIsIiR7d29ya3NwYWNlRm9sZGVyfSIsIi0tYWxsb3ctbm9uLWdhLXRvb2xzIl19)
 
 See the [Installation Guide](./installation) for detailed setup instructions for Claude Code, Cursor, GitHub Copilot, and other MCP clients.
 
@@ -130,6 +130,12 @@ AI assistants automatically decide which MCP tools to use based on your prompts.
 
 See the [Toolsets & Tools Reference](./toolsets) for more prompting examples for each toolset.
 
+## Plugins
+
+The MCP server uses the B2C CLI under the hood, so CLI plugins automatically extend MCP functionality. Plugins can add new commands, provide custom configuration sources, integrate with external systems, and more.
+
+See the [CLI Plugin documentation](../guide/extending) for details on creating plugins and [Third-Party Plugins](../guide/third-party-plugins) for available community plugins.
+
 ## Next Steps
 
 - [Installation Guide](./installation) - Set up Claude Code, Cursor, GitHub Copilot, or other MCP clients
diff --git a/docs/mcp/installation.md b/docs/mcp/installation.md
@@ -53,11 +53,11 @@ Claude Code supports MCP servers via CLI installation:
 
 ```bash [Project Scope (Recommended)]
 cd /path/to/your/project
-claude mcp add --transport stdio --scope project b2c-dx -- npx -y @salesforce/b2c-dx-mcp --allow-non-ga-tools
+claude mcp add --transport stdio --scope project b2c-dx-mcp -- npx -y @salesforce/b2c-dx-mcp@latest --allow-non-ga-tools
 ```
 
 ```bash [User Scope]
-claude mcp add --transport stdio --scope user b2c-dx -- npx -y @salesforce/b2c-dx-mcp --allow-non-ga-tools
+claude mcp add --transport stdio --scope user b2c-dx-mcp -- npx -y @salesforce/b2c-dx-mcp@latest --allow-non-ga-tools
 ```
 
 :::
@@ -78,9 +78,9 @@ Project-level configuration automatically detects your project location and can
 ```json
 {
   "mcpServers": {
-    "b2c-dx": {
+    "b2c-dx-mcp": {
       "command": "npx",
-      "args": ["-y", "@salesforce/b2c-dx-mcp", "--allow-non-ga-tools"]
+      "args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--allow-non-ga-tools"]
     }
   }
 }
@@ -94,27 +94,47 @@ With project-level configuration, the server automatically detects your project
 
 Alternatively, use the "Add to Cursor" link to add to user-level configuration:
 
-[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=b2c-dx&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzYWxlc2ZvcmNlL2IyYy1keC1tY3AiLCItLXByb2plY3QtZGlyZWN0b3J5IiwiJHt3b3Jrc3BhY2VGb2xkZXJ9IiwiLS1hbGxvdy1ub24tZ2EtdG9vbHMiXX0=)
+[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=b2c-dx-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzYWxlc2ZvcmNlL2IyYy1keC1tY3BAbGF0ZXN0IiwiLS1wcm9qZWN0LWRpcmVjdG9yeSIsIiR7d29ya3NwYWNlRm9sZGVyfSIsIi0tYWxsb3ctbm9uLWdhLXRvb2xzIl19)
 
-**Note:** The install link adds to user-level configuration (`~/.cursor/mcp.json`) with `--project-directory "${workspaceFolder}"`. The `${workspaceFolder}` variable automatically expands to your current workspace, so no manual updates are needed when switching projects.
+**Manual Configuration (Windows or if link doesn't work):**
+
+1. Open or create `~/.cursor/mcp.json` (on Windows: `C:\Users\<your-username>\.cursor\mcp.json`)
+2. Add the following configuration:
+
+```json
+{
+  "mcpServers": {
+    "b2c-dx-mcp": {
+      "command": "npx",
+      "args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--project-directory", "${workspaceFolder}", "--allow-non-ga-tools"]
+    }
+  }
+}
+```
+
+> **Note:** Cursor uses `"mcpServers"` as the top-level key. For GitHub Copilot/VS Code, use `"servers"` instead (see [GitHub Copilot](#github-copilot) section). The `${workspaceFolder}` variable automatically expands to your current workspace, so no manual updates are needed when switching projects.
 
 ## GitHub Copilot
 
 GitHub Copilot supports MCP servers via configuration in your workspace. See the [GitHub Copilot MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_configure-the-mcpjson-file) for setup instructions.
 
-Copilot supports project-level configuration. Create the MCP config file in your workspace:
+Copilot supports project-level configuration. Create the MCP config file in your workspace (`.vscode/mcp.json`):
 
 ```json
 {
-  "mcpServers": {
-    "b2c-dx": {
+  "servers": {
+    "b2c-dx-mcp": {
+      "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@salesforce/b2c-dx-mcp", "--allow-non-ga-tools"]
+      "args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--allow-non-ga-tools"]
     }
-  }
+  },
+  "inputs": []
 }
 ```
 
+> **Note:** GitHub Copilot/VS Code uses `"servers"` (not `"mcpServers"`) and requires `"type": "stdio"` for stdio-based servers. The `"inputs"` array is optional but included for consistency with VS Code's format.
+
 With project-level configuration, the server automatically detects your project location.
 
 ## Troubleshooting
@@ -124,6 +144,31 @@ With project-level configuration, the server automatically detects your project
 - Verify Node.js version: `node --version` (must be 22.0.0+)
 - Check that `npx` is available and working
 
+### "Could not determine executable to run" Error (Windows)
+
+This error occurs when npx uses a cached broken version (`0.0.1`) instead of the latest version. npx's cache-first behavior can reuse an older cached version even when newer versions are available.
+
+**Solution:**
+
+1. **Update your MCP configuration** to use `@latest`:
+   ```json
+   {
+     "mcpServers": {
+       "b2c-dx-mcp": {
+         "command": "npx",
+         "args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--allow-non-ga-tools"]
+       }
+     }
+   }
+   ```
+
+2. **Clear the npx cache** if the issue persists:
+   ```bash
+   npm cache clean --force
+   ```
+
+**Prevention:** Always use `@latest` in your MCP configuration to ensure npx fetches the latest version from the registry instead of using cached versions.
+
 ### Tools Not Available
 
 - Ensure `--allow-non-ga-tools` flag is included (required for preview tools)
diff --git a/docs/mcp/tools/cartridge-deploy.md b/docs/mcp/tools/cartridge-deploy.md
@@ -20,17 +20,15 @@ This tool is useful for deploying custom code cartridges for SFRA or other B2C C
 
 ## Authentication
 
-Supports two authentication methods:
+Requires WebDAV access credentials. Supports two authentication methods:
 
-- **Basic Authentication (WebDAV)** - Uses `username` and `password` from `dw.json` or environment variables
-- **OAuth** - Uses `client-id` and `client-secret` from `dw.json` or environment variables
+**Required:**
+- **Basic Auth (recommended)** - `hostname`, `username`, and `password` (WebDAV access key). Provides better performance for WebDAV operations.
+- **OAuth** - `hostname`, `client-id`, and `client-secret`. Requires WebDAV Client Permissions configured.
 
-See [Configuration](../configuration) for complete credential setup details.
+**Configuration priority:** Flags → Environment variables → `dw.json` config file
 
-**Configuration Priority:**
-1. Flags (`--server`, `--username`, `--password`, `--client-id`, `--client-secret`)
-2. Environment variables (`SFCC_SERVER`, `SFCC_USERNAME`, `SFCC_PASSWORD`, `SFCC_CLIENT_ID`, `SFCC_CLIENT_SECRET`)
-3. `dw.json` config file (auto-discovered or via `--config` flag)
+See [Configuration](../configuration) for complete credential setup details including flags and environment variables. See [Authentication Setup](../../guide/authentication#webdav-access) for WebDAV access key and OAuth configuration instructions.
 
 ## Parameters
 
diff --git a/docs/mcp/tools/mrt-bundle-push.md b/docs/mcp/tools/mrt-bundle-push.md
@@ -21,20 +21,21 @@ This tool is shared across the MRT, PWAV3, and STOREFRONTNEXT toolsets.
 
 ## Authentication
 
-Requires Managed Runtime (MRT) credentials. See [MRT Credentials](../configuration#mrt-credentials-mobify) for complete details.
-
-**Configuration priority:**
-1. Flags (`--api-key`, `--project`, `--environment`, `--cloud-origin`)
-2. Environment variables (`MRT_API_KEY`, `MRT_PROJECT`, `MRT_ENVIRONMENT`, `MRT_CLOUD_ORIGIN`)
-3. `~/.mobify` config file (or `~/.mobify--[hostname]` if `--cloud-origin` is set)
+Requires Managed Runtime (MRT) credentials.
 
 **Required:**
-- `project` (via `--project` flag or `MRT_PROJECT` environment variable)
-- `api-key` (via `--api-key` flag, `MRT_API_KEY` environment variable, or `~/.mobify` config file)
+- `project` - MRT project slug
+- `api-key` - MRT API key
+
+**Required when `deploy: true`:**
+- `environment` - Target environment (e.g., staging, production)
 
 **Optional:**
-- `environment` (required only when `deploy: true`; via `--environment` flag or `MRT_ENVIRONMENT` environment variable)
-- `cloud-origin` (for environment-specific `~/.mobify` files; via `--cloud-origin` flag or `MRT_CLOUD_ORIGIN` environment variable)
+- `cloud-origin` - Overrides MRT API endpoint and uses `~/.mobify--{hostname}` instead of `~/.mobify`
+
+**Configuration priority:** Flags → Environment variables → `~/.mobify` config file
+
+See [MRT Credentials](../configuration#mrt-credentials-mobify) for complete setup instructions including flags, environment variables, and the `~/.mobify` file format. See [Authentication Setup](../../guide/authentication#managed-runtime-api-key) for how to get your API key.
 
 ## Parameters
 
diff --git a/packages/b2c-dx-mcp/CONTRIBUTING.md b/packages/b2c-dx-mcp/CONTRIBUTING.md
@@ -33,7 +33,7 @@ For local development or testing, use the development build directly:
 ```json
 {
   "mcpServers": {
-    "b2c-dx": {
+    "b2c-dx-mcp": {
       "command": "node",
       "args": ["/path/to/packages/b2c-dx-mcp/bin/dev.js", "--project-directory", "${workspaceFolder}", "--allow-non-ga-tools"]
     }
@@ -113,7 +113,7 @@ When updating MCP documentation, you may need to create or update the "Add to Cu
 
 The deep link follows this format:
 ```
-cursor://anysphere.cursor-deeplink/mcp/install?name=b2c-dx&config=<base64-encoded-config>
+cursor://anysphere.cursor-deeplink/mcp/install?name=b2c-dx-mcp&config=<base64-encoded-config>
 ```
 
 ### Generating the Base64 Config
@@ -124,27 +124,27 @@ cursor://anysphere.cursor-deeplink/mcp/install?name=b2c-dx&config=<base64-encode
    ```json
    {
      "command": "npx",
-     "args": ["-y", "@salesforce/b2c-dx-mcp", "--project-directory", "${workspaceFolder}", "--allow-non-ga-tools"]
+     "args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--project-directory", "${workspaceFolder}", "--allow-non-ga-tools"]
    }
    ```
 
    The `${workspaceFolder}` variable automatically expands to the current workspace directory in Cursor.
 
 2. **Encode to Base64** using Node.js:
    ```bash
-   node -e "console.log(Buffer.from(JSON.stringify({command: 'npx', args: ['-y', '@salesforce/b2c-dx-mcp', '--project-directory', '\${workspaceFolder}', '--allow-non-ga-tools']})).toString('base64'))"
+   node -e "console.log(Buffer.from(JSON.stringify({command: 'npx', args: ['-y', '@salesforce/b2c-dx-mcp@latest', '--project-directory', '\${workspaceFolder}', '--allow-non-ga-tools']})).toString('base64'))"
    ```
 
 3. **Construct the full link**:
    ```
-   cursor://anysphere.cursor-deeplink/mcp/install?name=b2c-dx&config=<base64-string>
+   cursor://anysphere.cursor-deeplink/mcp/install?name=b2c-dx-mcp&config=<base64-string>
    ```
 
 ### Example
 
 **User-level link (used in documentation):**
 ```markdown
-[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=b2c-dx&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzYWxlc2ZvcmNlL2IyYy1keC1tY3AiLCItLXByb2plY3QtZGlyZWN0b3J5IiwiJHt3b3Jrc3BhY2VGb2xkZXJ9IiwiLS1hbGxvdy1ub24tZ2EtdG9vbHMiXX0=)
+[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=b2c-dx-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzYWxlc2ZvcmNlL2IyYy1keC1tY3AiLCItLXByb2plY3QtZGlyZWN0b3J5IiwiJHt3b3Jrc3BhY2VGb2xkZXJ9IiwiLS1hbGxvdy1ub24tZ2EtdG9vbHMiXX0=)
 ```
 
 ### Where to Update
diff --git a/packages/b2c-dx-mcp/README.md b/packages/b2c-dx-mcp/README.md
diff --git a/packages/b2c-dx-mcp/package.json b/packages/b2c-dx-mcp/package.json
diff --git a/packages/b2c-dx-mcp/src/commands/mcp.ts b/packages/b2c-dx-mcp/src/commands/mcp.ts
diff --git a/packages/b2c-dx-mcp/src/registry.ts b/packages/b2c-dx-mcp/src/registry.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@salesforce/b2c-dx-mcp': patch
 +---
++
 +Changed oclif dirname from `b2c-dx-mcp` to `b2c` so the MCP server shares the same plugin directory as the CLI, enabling plugin discovery and unified plugin management.