Skip to content

@W-20599722 improve mcp docs #287

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yhsieh1 merged 3 commits into from
Mar 25, 2026
Merged

@W-20599722 improve mcp docs #287

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
65b0dbc
@W-20599722 improve mcp docs
yhsieh1 Mar 25, 2026
66b715d
update quick start install
yhsieh1 Mar 25, 2026
398dae3
revert cli install changes
yhsieh1 Mar 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/mcp-docs-install-config-clarity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
40 changes: 30 additions & 10 deletions docs/guide/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,24 +33,44 @@ 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:**
### Claude Code (Project Scope)

::: code-group
1. Open your project root in Claude Code.
2. Install the plugin marketplace entry:

```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
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
### 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"]
}
```

:::
### 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):

**Cursor:** [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=b2c-dx-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzYWxlc2ZvcmNlL2IyYy1keC1tY3BAbGF0ZXN0IiwiLS1wcm9qZWN0LWRpcmVjdG9yeSIsIiR7d29ya3NwYWNlRm9sZGVyfSIsIi0tYWxsb3ctbm9uLWdhLXRvb2xzIl19)
```json
"b2c-dx-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@salesforce/b2c-dx-mcp@latest", "--allow-non-ga-tools"]
}
```

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

Expand Down
234 changes: 111 additions & 123 deletions docs/mcp/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 B2C DX MCP Server uses the same configuration system as the B2C CLI.

## 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
{
Expand All @@ -40,107 +26,74 @@ 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:**

| Toolset | Required Fields |
|---------|----------------|
| **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
{
Expand All @@ -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

Expand All @@ -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

Expand Down
Loading
Loading