From 65b0dbcf5822cafc8aab53b251c308fda5446f38 Mon Sep 17 00:00:00 2001 From: Yuming Hsieh Date: Wed, 25 Mar 2026 15:33:10 -0400 Subject: [PATCH 1/3] @W-20599722 improve mcp docs --- .changeset/mcp-docs-install-config-clarity.md | 5 + docs/guide/index.md | 43 +++- docs/mcp/configuration.md | 234 +++++++++--------- docs/mcp/index.md | 125 ++-------- docs/mcp/installation.md | 50 +++- docs/mcp/tools/mrt-bundle-push.md | 49 +++- docs/mcp/tools/sfnext-configure-theme.md | 22 ++ docs/mcp/toolsets.md | 4 +- 8 files changed, 265 insertions(+), 267 deletions(-) create mode 100644 .changeset/mcp-docs-install-config-clarity.md diff --git a/.changeset/mcp-docs-install-config-clarity.md b/.changeset/mcp-docs-install-config-clarity.md new file mode 100644 index 00000000..6227e8eb --- /dev/null +++ b/.changeset/mcp-docs-install-config-clarity.md @@ -0,0 +1,5 @@ +--- +'@salesforce/b2c-dx-docs': patch +--- + +Clarified MCP documentation for quick install and configuration, including project-root setup steps, environment variable guidance, and MRT/theming tool setup details to reduce onboarding confusion. diff --git a/docs/guide/index.md b/docs/guide/index.md index 0e1875d0..ec38268d 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -33,24 +33,49 @@ See the [CLI Installation Guide](./installation) for more installation options. The B2C DX MCP Server enables AI assistants to help with B2C Commerce development tasks. -**Claude Code:** - ::: code-group -```bash [Project Scope (Recommended)] +```bash [Claude Code] cd /path/to/your/project -claude mcp add --transport stdio --scope project b2c-dx-mcp -- npx -y @salesforce/b2c-dx-mcp@latest --allow-non-ga-tools +claude plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling +claude plugin install b2c-dx-mcp --scope project ``` -```bash [User Scope] -claude mcp add --transport stdio --scope user b2c-dx-mcp -- npx -y @salesforce/b2c-dx-mcp@latest --allow-non-ga-tools +```bash [Cursor] +cd /path/to/your/project +mkdir -p .cursor +cat > .cursor/mcp.json <<'EOF' +{ + "mcpServers": { + "b2c-dx-mcp": { + "command": "npx", + "args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--allow-non-ga-tools"] + } + } +} +EOF ``` -::: +```bash [GitHub Copilot] +cd /path/to/your/project +mkdir -p .vscode +cat > .vscode/mcp.json <<'EOF' +{ + "servers": { + "b2c-dx-mcp": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--allow-non-ga-tools"] + } + }, + "inputs": [] +} +EOF +``` -**Cursor:** [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=b2c-dx-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzYWxlc2ZvcmNlL2IyYy1keC1tY3BAbGF0ZXN0IiwiLS1wcm9qZWN0LWRpcmVjdG9yeSIsIiR7d29ya3NwYWNlRm9sZGVyfSIsIi0tYWxsb3ctbm9uLWdhLXRvb2xzIl19) +::: -See the [MCP Server Installation Guide](/mcp/installation) for detailed setup instructions for Claude Code, Cursor, GitHub Copilot, and other MCP clients. +See the [MCP Server Installation Guide](/mcp/installation) for full setup steps and troubleshooting. ## Next Steps diff --git a/docs/mcp/configuration.md b/docs/mcp/configuration.md index 255be24b..61dc34f5 100644 --- a/docs/mcp/configuration.md +++ b/docs/mcp/configuration.md @@ -4,29 +4,15 @@ description: Configure the B2C DX MCP Server with credentials, flags, environmen # Configuration -The B2C DX MCP Server uses the same configuration system as the B2C CLI. For MCP, environment variables are set in your MCP client's JSON config (`env` object), not as system environment variables. See the [CLI Configuration guide](../guide/configuration) and [Authentication Setup guide](../guide/authentication) for credential formats and setup details. +The MCP server works with a minimal `mcp.json` — credentials and project settings are typically managed in your project's `dw.json` or `.env` file. You can also pass flags and environment variables directly in `mcp.json` if needed. -## Configuration Priority - -Credentials are resolved in the following priority order (same as the CLI): - -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 +See the [CLI Configuration guide](../guide/configuration) and [Authentication Setup guide](../guide/authentication) for credential formats and setup details. -### Option 1: Config Files (Recommended) +## Credentials -Config files are the recommended approach for managing credentials. They keep credentials out of your MCP client configuration and are automatically loaded from your project. +### `dw.json` (Recommended) {#dw-json} -#### B2C Credentials (`dw.json`) - -Create a [`dw.json`](../guide/configuration#configuration-file) file in your project root. The MCP server uses the same format as the CLI. See the [CLI Configuration guide](../guide/configuration#configuration-file) for the complete `dw.json` format, supported fields, and multi-instance configuration. - -**Example minimal configuration:** +Create a [`dw.json`](../guide/configuration#configuration-file) file in your project root. The MCP server uses the same format as the CLI and loads it automatically with project-level installation. ```json { @@ -40,7 +26,9 @@ Create a [`dw.json`](../guide/configuration#configuration-file) file in your pro } ``` -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. +With user-level Cursor configuration, add `--project-directory "${workspaceFolder}"` to the args array so the server can find `dw.json`. Claude Code and GitHub Copilot automatically detect the project location. + +See the [CLI Configuration guide](../guide/configuration#configuration-file) for the complete `dw.json` format, supported fields, and multi-instance configuration. **Required fields per toolset:** @@ -48,99 +36,64 @@ The server automatically loads this file when using project-level configuration |---------|----------------| | **SCAPI** | `short-code`, `tenant-id`, `client-id`, `client-secret` | | **CARTRIDGES** | `hostname`, `username`, `password` (or OAuth: `hostname`, `client-id`, `client-secret`) | -| **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) | +| **MRT** | `mrtProject`, `mrtApiKey` (or `api_key` in `~/.mobify`, or `MRT_API_KEY` env var). `mrtEnvironment` required when deploying. | +| **PWAV3** | None (project directory auto-detected) | +| **STOREFRONTNEXT** | None (project directory auto-detected) | **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 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. +### `.env` File {#env-file} -Create the `~/.mobify` file manually: +As an alternative to `dw.json`, you can place a `.env` file in your project root. The server loads it automatically at startup via Node.js native `process.loadEnvFile()`. -```json -{ - "api_key": "your-mrt-api-key" -} +```bash +SFCC_SERVER=xxx.demandware.net +SFCC_CLIENT_ID=... +SFCC_CLIENT_SECRET=... +SFCC_SHORTCODE=... +SFCC_TENANT_ID=... ``` -**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)). +> **Note:** The `.env` file is loaded from the process working directory. Claude Code and GitHub Copilot set cwd to the project root regardless of scope, so `.env` works in all cases. Cursor user-level config (`~/.cursor/mcp.json`) sets cwd to `~`, so `.env` in the project root **will not be found** — use `dw.json` or system environment variables instead. Cursor project-level config (`.cursor/mcp.json`) works as expected. -For complete setup instructions, including how to get your API key, see the [Authentication Guide](../guide/authentication#managed-runtime-api-key). +See the [Environment Variables Reference](#environment-variables-reference) for the complete list of supported variables. -### Option 2: Environment Variables +### MRT Credentials (`~/.mobify`) {#mrt-credentials} -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)). +MRT tools require an API key. You can include `mrtApiKey`, `mrtProject`, and `mrtEnvironment` in `dw.json` (see [required fields](#dw-json) above), or store the API key in a separate [`~/.mobify`](../guide/configuration#mrt-api-key) file (user-level, shared across projects): ```json { - "mcpServers": { - "b2c-dx-mcp": { - "command": "npx", - "args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--allow-non-ga-tools"], - "env": { - "SFCC_SERVER": "xxx.demandware.net", - "SFCC_CLIENT_ID": "...", - "SFCC_CLIENT_SECRET": "...", - "SFCC_SHORTCODE": "...", - "SFCC_TENANT_ID": "...", - "MRT_API_KEY": "..." - } - } - } + "api_key": "your-mrt-api-key" } ``` -### Option 3: Flags +**`~/.mobify` file locations:** +- Default: `~/.mobify` +- With `--cloud-origin`: `~/.mobify--{hostname}` (e.g., `~/.mobify--custom.example.com`) +- With `--credentials-file` (or `MRT_CREDENTIALS_FILE`): uses the specified path -Pass credentials directly as command-line flags: +If both `dw.json` and `~/.mobify` contain an API key, `dw.json` takes precedence. For complete setup instructions, see the [Authentication Guide](../guide/authentication#managed-runtime-api-key). -```json -{ - "mcpServers": { - "b2c-dx-mcp": { - "command": "npx", - "args": [ - "-y", - "@salesforce/b2c-dx-mcp@latest", - "--server", - "xxx.demandware.net", - "--username", - "...", - "--password", - "...", - "--client-id", - "...", - "--client-secret", - "...", - "--allow-non-ga-tools" - ] - } - } -} -``` +## Configuration Priority + +When the same setting is provided in multiple places, the server resolves values in this order: -> **Note:** Flags and environment variables in your MCP client configuration are less secure than config files (`dw.json`), especially if your MCP client configuration is shared or committed to version control. Use `dw.json` (which can be gitignored) for sensitive credentials. +1. **Flags** (highest) — e.g., `--server`, `--api-key` in the `args` array +2. **Environment variables** — via `.env` file, MCP client `env` object, or system environment +3. **Config files** (lowest) — `dw.json` and `~/.mobify` -See the [CLI Configuration guide](../guide/configuration#cli-flags) for complete flag and environment variable documentation. +In practice, you rarely need flags or env vars in `mcp.json` — `dw.json` and `.env` handle most cases. Flags and the `env` object are available for overrides or CI environments. ## Toolset Selection ### Auto-Discovery (Default) -By default, the server automatically detects your project type and enables relevant toolsets. See [Project Type Detection](./#project-type-detection) for details. +By default, the server automatically detects your project type and enables relevant toolsets. No configuration needed. See [Project Type Detection](./#project-type-detection) for details. ### Manual Selection -Override auto-discovery by specifying toolsets explicitly: +Override auto-discovery with `--toolsets` or `SFCC_TOOLSETS`: ```json { @@ -159,15 +112,9 @@ Override auto-discovery by specifying toolsets explicitly: } ``` -**Available toolsets:** -- `CARTRIDGES` - Cartridge deployment and code version management -- `MRT` - Managed Runtime bundle operations -- `PWAV3` - PWA Kit v3 development tools -- `SCAPI` - Salesforce Commerce API discovery -- `STOREFRONTNEXT` - Storefront Next development tools -- `all` - Enable all toolsets +**Available toolsets:** `CARTRIDGES`, `MRT`, `PWAV3`, `SCAPI`, `STOREFRONTNEXT`, `all` -**Note:** The `SCAPI` toolset is always enabled, even if not explicitly specified. +With auto-discovery, the `SCAPI` toolset is always included. When using `--toolsets` or `--tools`, only the specified toolsets/tools are enabled. ### Individual Tool Selection @@ -183,54 +130,95 @@ Enable specific tools instead of entire toolsets: } ``` -## Logging Configuration +## Logging -### Log Level - -Set logging verbosity: +Set logging verbosity with `--log-level` or `SFCC_LOG_LEVEL`: ```json { - "args": [ - "--log-level", - "debug" - ] + "args": ["--log-level", "debug"] } ``` **Available levels:** `trace`, `debug`, `info`, `warn`, `error`, `silent` -### Debug Mode - -Enable debug logging (equivalent to `--log-level debug`): - -```json -{ - "args": [ - "--debug" - ] -} -``` +The `--debug` flag (or `SFCC_DEBUG`) is a shorthand for `--log-level debug`. ## Telemetry Telemetry is enabled by default and collects anonymous usage data to help improve the developer experience. -### What We Collect +**What we collect:** server lifecycle events, tool usage (which tools and execution time), command metrics, and environment info (platform, Node.js version, package version). + +**What we don't collect:** credentials, business data, tool arguments/results, or file contents. + +To disable, set either variable in your `.env` file or MCP client `env` object: + +| Variable | Description | +|----------|-------------| +| `SFCC_DISABLE_TELEMETRY` | Set to `true` to disable telemetry | +| `SF_DISABLE_TELEMETRY` | Set to `true` to disable telemetry (sf CLI standard) | + +## MCP Server Flags Reference {#mcp-server-flags} + +Flags specific to the MCP server (in addition to the shared CLI flags in the [CLI Configuration guide](../guide/configuration)): + +| Flag | Type | Default | Description | +| ---- | ---- | ------- | ----------- | +| `--toolsets` | string | Auto-detect | Toolsets to enable (comma-separated) | +| `--tools` | string | - | Individual tools to enable (comma-separated) | +| `--allow-non-ga-tools` | boolean | `false` | Enable non-GA (experimental) tools | + +Environment variable equivalents for these flags are listed in [MCP Server Environment Variables](#mcp-server-environment-variables). + +## Environment Variables Reference {#environment-variables-reference} + +These can be set in a `.env` file, the MCP client `env` object, or as system environment variables. + +### MCP Server Environment Variables {#mcp-server-environment-variables} + +MCP-specific environment variables (flag equivalents): + +| Env Variable | Equivalent Flag | Type | Default | Description | +| ------------ | --------------- | ---- | ------- | ----------- | +| `SFCC_TOOLSETS` | `--toolsets` | string | Auto-detect | Toolsets to enable (comma-separated) | +| `SFCC_TOOLS` | `--tools` | string | - | Individual tools to enable (comma-separated) | +| `SFCC_ALLOW_NON_GA_TOOLS` | `--allow-non-ga-tools` | boolean | `false` | Enable non-GA (experimental) tools | + +**B2C instance:** + +| Variable | Description | +|----------|-------------| +| `SFCC_SERVER` | B2C instance hostname | +| `SFCC_CODE_VERSION` | Code version for deployments | +| `SFCC_USERNAME` | Username for Basic auth (WebDAV) | +| `SFCC_PASSWORD` | Password/access key for Basic auth | +| `SFCC_CLIENT_ID` | OAuth client ID (`SFCC_OAUTH_CLIENT_ID` also supported) | +| `SFCC_CLIENT_SECRET` | OAuth client secret (`SFCC_OAUTH_CLIENT_SECRET` also supported) | +| `SFCC_SHORTCODE` | SCAPI short code | +| `SFCC_TENANT_ID` | Organization/tenant ID | + +**MRT:** -- **Server lifecycle events**: When the server starts, stops, or encounters errors -- **Tool usage**: Which tools are called and their execution time (not the arguments or results) -- **Command metrics**: Command duration and success/failure status -- **Environment info**: Platform, architecture, Node.js version, and package version +| Variable | Description | +|----------|-------------| +| `MRT_API_KEY` | MRT API key (`SFCC_MRT_API_KEY` also supported) | +| `MRT_PROJECT` | MRT project slug (`SFCC_MRT_PROJECT` also supported) | +| `MRT_ENVIRONMENT` | Target environment (`SFCC_MRT_ENVIRONMENT` also supported) | +| `MRT_CLOUD_ORIGIN` | MRT API origin URL (`SFCC_MRT_CLOUD_ORIGIN` also supported) | +| `MRT_CREDENTIALS_FILE` | Path to MRT credentials file (overrides `~/.mobify`) | -### What We Don't Collect +**General:** -- **No credentials**: No API keys, passwords, or secrets -- **No business data**: No product data, customer information, or site content -- **No tool arguments**: No input parameters or output results from tool calls -- **No file contents**: No source code, configuration files, or project data +| Variable | Description | +|----------|-------------| +| `SFCC_PROJECT_DIRECTORY` | Project directory (`SFCC_WORKING_DIRECTORY` also supported) | +| `SFCC_CONFIG` | Path to config file | +| `SFCC_INSTANCE` | Instance name from configuration file | +| `SFCC_LOG_LEVEL` | Logging level | +| `SFCC_DEBUG` | Enable debug logging | -To disable telemetry, set `SFCC_DISABLE_TELEMETRY=true` in your MCP client configuration's `env` object. +See the [CLI Configuration guide](../guide/configuration#environment-variables) for the complete list including OAuth and advanced options. ## Next Steps diff --git a/docs/mcp/index.md b/docs/mcp/index.md index c5a62a21..ec32cbfd 100644 --- a/docs/mcp/index.md +++ b/docs/mcp/index.md @@ -8,80 +8,17 @@ The B2C DX MCP Server enables AI assistants (like Claude Code, Cursor, GitHub Co > ⚠️ **Preview Release**: This package is in preview. Tools are functional but require `--allow-non-ga-tools` to enable. Additional tools will be added in future releases. -## Overview - -The MCP server automatically detects your project type and enables relevant tools. It reads configuration from your project's configuration files and provides AI assistants with context-aware tools to help you: - -- Discover and explore Salesforce Commerce APIs -- Deploy code and manage B2C instances -- Build and deploy applications to Managed Runtime -- Get development guidelines and best practices -- Generate components and scaffold new features - ## Quick Start -### Installation - -**Claude Code:** - -::: code-group - -```bash [Project Scope (Recommended)] -cd /path/to/your/project -claude mcp add --transport stdio --scope project b2c-dx-mcp -- npx -y @salesforce/b2c-dx-mcp@latest --allow-non-ga-tools -``` - -```bash [Plugin Marketplace (Alternative)] -claude plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling -claude plugin install b2c-dx-mcp --scope project -``` - -```bash [User Scope] -claude mcp add --transport stdio --scope user b2c-dx-mcp -- npx -y @salesforce/b2c-dx-mcp@latest --allow-non-ga-tools -``` +1. **Install** — set up the MCP server for your client. See the [Installation Guide](./installation) for Claude Code, Cursor, GitHub Copilot, and other clients. -::: +2. **Configure credentials** — create a [`dw.json`](./configuration#dw-json) or [`.env`](./configuration#env-file) file in your project root. No changes to `mcp.json` needed. -**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. - -### Configuration - -The server automatically detects your project type and loads configuration from `dw.json` in your project root. See the [Configuration Guide](./configuration) for details on: - -- Credential management (config files, environment variables, flags) -- Project type detection -- Toolset selection (auto-discovery vs manual) -- Required credentials per toolset +3. **Start using tools** — the server auto-detects your project type and enables relevant [toolsets](./toolsets). For authentication setup instructions, see the [Authentication Setup guide](../guide/authentication) which covers API client creation, WebDAV access, SCAPI authentication, and MRT API keys. -### Available Toolsets - -The server provides five toolsets with specialized tools for different development workflows: - -- [CARTRIDGES](./toolsets#cartridges) - Cartridge deployment and code version management -- [MRT](./toolsets#mrt) - Managed Runtime bundle operations -- [PWAV3](./toolsets#pwav3) - PWA Kit v3 development tools -- [SCAPI](./toolsets#scapi) - Salesforce Commerce API discovery -- [STOREFRONTNEXT](./toolsets#storefrontnext) - Storefront Next development tools - -See the [Toolsets & Tools Reference](./toolsets) for detailed descriptions of each toolset and its tools. - -## Usage - -### Project Directory - -With project-level installation (recommended), the server automatically detects your project location from the MCP config file location. This enables: - -1. **Auto-discovery** - Detects your project type and enables appropriate toolsets. -2. **Configuration loading** - Reads [`dw.json`](../guide/configuration#configuration-file) from your project for credentials. -3. **Scaffolding** - Creates new files in the correct location. - -**Note:** If using user-level configuration on Cursor, add `--project-directory "${workspaceFolder}"` to the args array. Claude Code and GitHub Copilot don't require this flag. - -### Project Type Detection +## Project Type Detection The server analyzes your project directory and enables toolsets based on what it finds: @@ -92,59 +29,29 @@ The server analyzes your project directory and enables toolsets based on what it | **Cartridges** | `.project` file in cartridge directory | CARTRIDGES, SCAPI | | **No project detected** | No B2C markers found | SCAPI (base toolset only) | -The **SCAPI** toolset is always enabled. Hybrid projects (e.g., cartridges + PWA Kit) get combined toolsets. - -### Prompting Tips - -AI assistants automatically decide which MCP tools to use based on your prompts. To get the best results: +With auto-discovery, the **SCAPI** toolset is always included. Hybrid projects (e.g., cartridges + PWA Kit) get combined toolsets. You can also [manually select toolsets](./configuration#toolset-selection). -> ⚠️ **IMPORTANT**: **Explicitly mention "Use the MCP tool"** in your prompts for reliable tool usage. While AI assistants can automatically select MCP tools based on context, explicit instructions ensure the assistant prioritizes MCP tools over general knowledge, especially when multiple approaches are possible. +## Prompting Tips -#### Best Practices +> ⚠️ **Explicitly mention "Use the MCP tool"** in your prompts for reliable tool usage. This ensures the assistant prioritizes MCP tools over general knowledge. -1. **Always explicitly request MCP tool usage**: Start prompts with "Use the MCP tool to..." or include "Use the MCP tool" in your request -2. **Be specific about your goal**: Instead of "help me with Storefront Next", say "Use the MCP tool to show me how to build a product detail page with authentication" -3. **Mention the tool or domain explicitly**: Reference the framework (Storefront Next, PWA Kit), operation (deploy, discover), or domain (SCAPI, cartridges) -4. **Use natural language**: Describe what you want to achieve, not the tool name -5. **Provide context**: Mention your project type, what you're building, or what you need to learn -6. **Ask for guidelines first**: When starting a new project or learning a framework, ask for development guidelines before writing code -7. **Combine related topics**: Ask for multiple related sections in one request (e.g., "Use the MCP tool to show me data fetching and component patterns for Storefront Next") -8. **Specify operations clearly**: For deployment operations, mention the target and what to deploy (for example, "Use the MCP tool to deploy my cartridges to the sandbox instance") +**Examples:** +- "I'm new to Storefront Next. **Use the MCP tool** to show me the critical rules I need to know." +- "**Use the MCP tool** to list all available SCAPI schemas." +- "**Use the MCP tool** to deploy my cartridges to the sandbox instance." +- "**Use the MCP tool** to build and push my Storefront Next bundle to staging." +- "**Use the MCP tool** to convert this Figma design to a Storefront Next component: [Figma URL with node-id]" -#### Example Prompts - -**Storefront Next Development:** -- ✅ "I'm new to Storefront Next. Use the MCP tool to show me the critical rules I need to know." -- ✅ "I need to build a product detail page. Use the MCP tool to show me best practices for data fetching and component patterns." -- ✅ "I want to apply my brand colors to my Storefront Next site. Use the MCP tool to help me." - -**SCAPI Discovery:** -- ✅ "Use the MCP tool to list all available SCAPI schemas." -- ✅ "Use the MCP tool to get the OpenAPI schema for shopper-baskets v1." - -**Cartridge Deployment:** -- ✅ "Use the MCP tool to deploy my cartridges to the sandbox instance." - -**MRT Bundle Operations:** -- ✅ "Use the MCP tool to build and push my Storefront Next bundle to staging." - -**Figma-to-Component:** -- ✅ "Use the MCP tool to convert this Figma design to a Storefront Next component: [Figma URL with node-id]" -- ✅ "Use the MCP tool to create this homepage from the Figma design: [Figma URL with node-id]. Create new components or update existing components using the MCP tool if necessary, then update the home page. The expected result should be that the homepage matches as closely as possible to the provided Figma design." -- ✅ "Use the MCP tool to map Figma design tokens to my theme." - -See the [Toolsets & Tools Reference](./toolsets) for more prompting examples for each toolset. +Other tips: be specific about your goal, mention the framework or domain, use natural language, and ask for guidelines first when learning a new framework. ## 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. +The MCP server uses the B2C CLI under the hood, so CLI plugins automatically extend MCP functionality. See the [CLI Plugin documentation](../guide/extending) for details. ## Next Steps - [Installation Guide](./installation) - Set up Claude Code, Cursor, GitHub Copilot, or other MCP clients -- [Configuration](./configuration) - Configure credentials, flags, and toolset selection +- [Configuration](./configuration) - Configure credentials, environment variables, MCP flags, toolset selection, and logging - [Toolsets & Tools](./toolsets) - Explore available toolsets and tools - [CLI Reference](../cli/) - Learn about the B2C CLI commands - [API Reference](../api/) - Explore the SDK API diff --git a/docs/mcp/installation.md b/docs/mcp/installation.md index 00deb9b4..d9107f9f 100644 --- a/docs/mcp/installation.md +++ b/docs/mcp/installation.md @@ -8,30 +8,39 @@ This guide covers installing and configuring the B2C DX MCP Server for various M ## Prerequisites -- Node.js 22.0.0 or higher +- Node.js 22.0.0 or higher (`npx` is included with Node.js and must be accessible from the MCP client's process environment) - A B2C Commerce project (for project-specific toolsets) - MCP client (Claude Code, Cursor, GitHub Copilot, or compatible client) > **Note:** For Figma-to-component tools, you also need an external Figma MCP server enabled. See [Figma-to-Component Tools Setup](./figma-tools-setup) for details. -The MCP server is installed via `npx`, which downloads and runs the latest version on demand. For project directory and project type detection details, see [MCP Server Overview](./#usage). +The MCP server is installed via `npx`, which downloads and runs the latest version on demand. For project type detection details, see [MCP Server Overview](./#project-type-detection). ## Claude Code -Claude Code supports MCP servers via CLI installation: +### Plugin Marketplace -::: code-group +Install from the Claude Code plugin marketplace: -```bash [Project Scope (Recommended)] +```bash cd /path/to/your/project -claude mcp add --transport stdio --scope project b2c-dx-mcp -- npx -y @salesforce/b2c-dx-mcp@latest --allow-non-ga-tools -``` - -```bash [Plugin Marketplace (Alternative)] claude plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling claude plugin install b2c-dx-mcp --scope project ``` +> **Note:** For plugin marketplace installs, MCP server configuration is managed by the plugin. For credentials and settings, use [`dw.json`](./configuration#dw-json) or [`.env`](./configuration#env-file) in your project root. + +### CLI + +Add the MCP server directly via the Claude Code CLI: + +::: code-group + +```bash [Project Scope] +cd /path/to/your/project +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-mcp -- npx -y @salesforce/b2c-dx-mcp@latest --allow-non-ga-tools ``` @@ -113,6 +122,12 @@ Copilot supports project-level configuration. Create the MCP config file in your With project-level configuration, the server automatically detects your project location. +## After Installation + +With the default `mcp.json`, the server auto-detects your project type and loads credentials from your project's `dw.json` or `.env` file. No additional changes to `mcp.json` are needed. + +See [Configuration](./configuration) for setting up `dw.json`, `.env`, and toolset selection. + ## Troubleshooting ### Server Not Starting @@ -120,6 +135,16 @@ 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 +### `spawn npx ENOENT` Error + +This error means the MCP client cannot find `npx` in its process PATH. This commonly happens when opening Cursor or VS Code from a desktop shortcut, Finder (macOS), or Start Menu (Windows) — the app may not inherit your terminal's PATH where Node.js is installed. + +**Solutions:** + +- **macOS/Linux:** Open Cursor or VS Code from the terminal (`cursor .` or `code .`) so it inherits your shell PATH, or add the Node.js bin directory to your system PATH so it's available in GUI-launched apps. +- **Windows:** Ensure the Node.js installer added `npm`/`npx` to your system PATH (not just user PATH). You may need to restart after installing Node.js. +- **nvm/fnm users:** Version managers set PATH in your shell profile, which GUI apps don't source. Either launch from terminal or create a symlink to the Node.js binary in a system-wide location (e.g., `/usr/local/bin/node`). + ### "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. @@ -153,12 +178,13 @@ This error occurs when npx uses a cached broken version (`0.0.1`) instead of the ### Configuration Not Loading -- Ensure `dw.json` exists in your project root +- Ensure `dw.json` or `.env` exists in your project root - Verify you're using project-level configuration (recommended) -- Check file permissions on `dw.json` +- Check file permissions on `dw.json` or `.env` +- If using user-level Cursor config, ensure `--project-directory "${workspaceFolder}"` is in the args array ## Next Steps -- [Configuration](./configuration) - Configure credentials, flags, and toolset selection +- [Configuration](./configuration) - Configure credentials, environment variables, MCP flags, toolset selection, and logging - [Toolsets & Tools](./toolsets) - Explore available toolsets and tools - [MCP Server Overview](./) - Learn more about the MCP server diff --git a/docs/mcp/tools/mrt-bundle-push.md b/docs/mcp/tools/mrt-bundle-push.md index bfcc3ebf..afa4004a 100644 --- a/docs/mcp/tools/mrt-bundle-push.md +++ b/docs/mcp/tools/mrt-bundle-push.md @@ -19,30 +19,55 @@ The `mrt_bundle_push` tool bundles a pre-built project and uploads it to Managed This tool is shared across the MRT, PWAV3, and STOREFRONTNEXT toolsets. -## Authentication +## Credentials and Setup -Requires Managed Runtime (MRT) credentials. +This tool reads MRT credentials from the same sources as the CLI. -**Required:** -- `project` - MRT project slug -- `api-key` - MRT API key +### What you must configure -**Required when `deploy: true`:** -- `environment` - Target environment (e.g., staging, production) +| Logical value | Required | Flag | Environment variable | `dw.json` field | Other source | +| ------------- | -------- | ---- | -------------------- | --------------- | ------------ | +| MRT project slug | Yes | `--project` | `MRT_PROJECT` | `mrtProject` | - | +| MRT API key | Yes | `--api-key` | `MRT_API_KEY` | `mrtApiKey` | `api_key` in `~/.mobify` | +| MRT environment | Only when `deploy: true` | `--environment` | `MRT_ENVIRONMENT` | `mrtEnvironment` | - | +| MRT cloud origin | No | `--cloud-origin` | `MRT_CLOUD_ORIGIN` | `mrtCloudOrigin` | Uses `~/.mobify--{hostname}` with `--cloud-origin` | -**Optional:** -- `cloud-origin` - Overrides MRT API endpoint and uses `~/.mobify--{hostname}` instead of `~/.mobify` +**When the same value is set in multiple places, resolution order is:** Flags → Environment variables → Config files (`dw.json`, `~/.mobify`) -**Configuration priority:** Flags → Environment variables → `~/.mobify` config file +For normal setup, prefer project-level `dw.json` (and `.env` when needed). Use flags or MCP client `env` for temporary overrides. -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. +See [MRT Credentials](../configuration#mrt-credentials) for complete setup details. See [Authentication Setup](../../guide/authentication#managed-runtime-api-key) for how to get your API key. + +### Setup examples + +**Using `dw.json` (recommended)** - Add MRT fields to your project's `dw.json`. No changes to `mcp.json` are required: + +```json +{ + "mrtProject": "my-project", + "mrtEnvironment": "staging", + "mrtApiKey": "your-api-key" +} +``` + +**Using `.env` file** - Place in your project root: + +```bash +MRT_API_KEY=your-api-key +MRT_PROJECT=my-project +MRT_ENVIRONMENT=staging +``` + +See [Environment Variables Reference](../configuration#environment-variables-reference) for all supported MRT variables (including optional `MRT_CLOUD_ORIGIN`). + +**Using MCP client `env` object or flags** - Best for overrides or CI. See [Configuration](../configuration#environment-variables-reference) for variable names and [Configuration Priority](../configuration#configuration-priority) for resolution order. ## Parameters Defaults for `buildDirectory`, `ssrOnly`, and `ssrShared` are chosen by detected project type (Storefront Next, PWA Kit v3, or generic). Explicit parameters override the project-type defaults. | Parameter | Type | Required | Default | Description | -|-----------|------|----------|---------|-------------| +| --------- | ---- | -------- | ------- | ----------- | | `buildDirectory` | string | No | `build` | Path to build directory containing the built project files. Can be absolute or relative to the project directory. | | `message` | string | No | None | Deployment message to include with the bundle push. Useful for tracking deployments. | | `ssrOnly` | string | No | Varies by project type | Glob patterns for server-only files (SSR), comma-separated or JSON array. These files are only included in the server bundle. | diff --git a/docs/mcp/tools/sfnext-configure-theme.md b/docs/mcp/tools/sfnext-configure-theme.md index be5a124c..a2d57937 100644 --- a/docs/mcp/tools/sfnext-configure-theme.md +++ b/docs/mcp/tools/sfnext-configure-theme.md @@ -22,6 +22,28 @@ The tool guides you through a structured workflow: answer questions about your d - Storefront Next project +## Custom Theming Files + +Add custom theming guidance files by setting the `THEMING_FILES` environment variable. The value is a JSON array of `{key, path}` objects. Paths are resolved relative to the project directory (absolute paths also supported). Custom files are loaded when `sfnext_configure_theme` initializes for the project and are available via the `fileKeys` parameter. + +Use this only when you need project-specific guidance (for example, brand rules or design-system constraints). If the default files are sufficient, you can skip `THEMING_FILES`. + +**In `.env` file (recommended):** + +```bash +THEMING_FILES='[{"key":"brand-guidelines","path":"docs/brand-guidelines.md"}]' +``` + +**In MCP client `env` object:** + +```json +{ + "env": { + "THEMING_FILES": "[{\"key\":\"brand-guidelines\",\"path\":\"docs/brand-guidelines.md\"}]" + } +} +``` + ## Parameters | Parameter | Type | Required | Description | diff --git a/docs/mcp/toolsets.md b/docs/mcp/toolsets.md index 72459cd9..76b301c3 100644 --- a/docs/mcp/toolsets.md +++ b/docs/mcp/toolsets.md @@ -19,7 +19,7 @@ Toolsets are collections of related tools that work together to support specific - [SCAPI](#scapi) - Salesforce Commerce API discovery - [STOREFRONTNEXT](#storefrontnext) - Storefront Next development tools -**Note:** The `SCAPI` toolset is always enabled, even if not explicitly specified. +**Note:** With auto-discovery, the `SCAPI` toolset is always included. When using `--toolsets` or `--tools`, only the specified toolsets/tools are enabled. ## CARTRIDGES @@ -114,6 +114,6 @@ Some tools appear in multiple toolsets (for example, `mrt_bundle_push`, `scapi_s ## Next Steps -- [Configuration](./configuration) - Configure credentials and toolset selection +- [Configuration](./configuration) - Configure credentials, environment variables, MCP flags, toolset selection, and logging - [Installation](./installation) - Set up the MCP server - [MCP Server Overview](./) - Learn more about the MCP server From 66b715d5cbb9999cc9e044b85a93f49f4f83eba5 Mon Sep 17 00:00:00 2001 From: Yuming Hsieh Date: Wed, 25 Mar 2026 16:22:55 -0400 Subject: [PATCH 2/3] update quick start install --- docs/guide/index.md | 61 +++++++++++++++++---------------------- docs/mcp/configuration.md | 2 +- 2 files changed, 27 insertions(+), 36 deletions(-) diff --git a/docs/guide/index.md b/docs/guide/index.md index ec38268d..0e6b4226 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -11,8 +11,6 @@ The B2C Developer Tooling provides command-line and AI-assisted development tool ## Quick CLI Install -::: code-group - ```bash [npm] npm install -g @salesforce/b2c-cli ``` @@ -25,56 +23,49 @@ npx @salesforce/b2c-cli --help brew install SalesforceCommerceCloud/tools/b2c-cli ``` -::: - See the [CLI Installation Guide](./installation) for more installation options. ## Quick MCP Install The B2C DX MCP Server enables AI assistants to help with B2C Commerce development tasks. -::: code-group +### Claude Code (Project Scope) -```bash [Claude Code] -cd /path/to/your/project +1. Open your project root in Claude Code. +2. Install the plugin marketplace entry: + +```bash claude plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling claude plugin install b2c-dx-mcp --scope project ``` -```bash [Cursor] -cd /path/to/your/project -mkdir -p .cursor -cat > .cursor/mcp.json <<'EOF' -{ - "mcpServers": { - "b2c-dx-mcp": { - "command": "npx", - "args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--allow-non-ga-tools"] - } - } +### Cursor (Project Scope) + +1. Open your project root. +2. Create or edit `.cursor/mcp.json`. +3. Add this entry under `mcpServers` (merge with existing config, do not replace the full file): + +```json +"b2c-dx-mcp": { + "command": "npx", + "args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--allow-non-ga-tools"] } -EOF ``` -```bash [GitHub Copilot] -cd /path/to/your/project -mkdir -p .vscode -cat > .vscode/mcp.json <<'EOF' -{ - "servers": { - "b2c-dx-mcp": { - "type": "stdio", - "command": "npx", - "args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--allow-non-ga-tools"] - } - }, - "inputs": [] +### GitHub Copilot (Project Scope) + +1. Open your project root. +2. Create or edit `.vscode/mcp.json`. +3. Add this entry under `servers` (merge with existing config, do not replace the full file): + +```json +"b2c-dx-mcp": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--allow-non-ga-tools"] } -EOF ``` -::: - See the [MCP Server Installation Guide](/mcp/installation) for full setup steps and troubleshooting. ## Next Steps diff --git a/docs/mcp/configuration.md b/docs/mcp/configuration.md index 61dc34f5..11d0f8a6 100644 --- a/docs/mcp/configuration.md +++ b/docs/mcp/configuration.md @@ -4,7 +4,7 @@ description: Configure the B2C DX MCP Server with credentials, flags, environmen # Configuration -The MCP server works with a minimal `mcp.json` — credentials and project settings are typically managed in your project's `dw.json` or `.env` file. You can also pass flags and environment variables directly in `mcp.json` if needed. +The B2C DX MCP Server uses the same configuration system as the B2C CLI. See the [CLI Configuration guide](../guide/configuration) and [Authentication Setup guide](../guide/authentication) for credential formats and setup details. From 398dae3b345aa6c05a5d1c7bcccf70795ac5a696 Mon Sep 17 00:00:00 2001 From: Yuming Hsieh Date: Wed, 25 Mar 2026 16:25:03 -0400 Subject: [PATCH 3/3] revert cli install changes --- docs/guide/index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/guide/index.md b/docs/guide/index.md index 0e6b4226..bb1309ab 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -11,6 +11,8 @@ The B2C Developer Tooling provides command-line and AI-assisted development tool ## Quick CLI Install +::: code-group + ```bash [npm] npm install -g @salesforce/b2c-cli ``` @@ -23,6 +25,8 @@ npx @salesforce/b2c-cli --help brew install SalesforceCommerceCloud/tools/b2c-cli ``` +::: + See the [CLI Installation Guide](./installation) for more installation options. ## Quick MCP Install