@W-20590941 B2C DX MCP Server Foundation by yhsieh1 · Pull Request #16 · SalesforceCommerceCloud/b2c-developer-tooling

yhsieh1 · 2025-12-23T15:27:25Z

Summary

Added b2c-dx-mcp package to provide an MCP server foundation that exposes B2C Commerce Developer operations as tools for AI assistants.
Allow user to configure tools with the following supported flags:

Flag	Description
`--toolsets`	Comma-separated toolsets to enable (case-insensitive)
`--tools`	Comma-separated individual tools to enable (case-insensitive)
`--allow-non-ga-tools`	Enable experimental (non-GA) tools

Mock pwav3, storefrontnext, scapi, mrt and cartridges tools as placeholder for easy testing and future implementation

Testing

Follow README.md for detailed setup.

Prerequisites

cd packages/b2c-dx-mcp
pnpm install  # ensure dependencies are installed

Note: For development mode (dev.js), no build is required. For production mode (run.js), run pnpm run build first.

Setup

MCP Inspector (Web UI)

Run from packages/b2c-dx-mcp:

pnpm run inspect

Open the localhost URL shown in terminal, click Connect, then List Tools.

Cursor

Create .cursor/mcp.json in your project:

macOS/Linux:

{
  "mcpServers": {
    "b2c-dx-local": {
      "command": "/FULL/PATH/TO/packages/b2c-dx-mcp/bin/dev.js",
      "args": ["--toolsets", "all", "--allow-non-ga-tools"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "b2c-dx-local": {
      "command": "C:\\FULL\\PATH\\TO\\packages\\b2c-dx-mcp\\bin\\dev.cmd",
      "args": ["--toolsets", "all", "--allow-non-ga-tools"]
    }
  }
}

Restart Cursor after saving.

Claude Desktop

macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: Edit %APPDATA%\Claude\claude_desktop_config.json

macOS/Linux:

{
  "mcpServers": {
    "b2c-dx-local": {
      "command": "/FULL/PATH/TO/packages/b2c-dx-mcp/bin/dev.js",
      "args": ["--toolsets", "all", "--allow-non-ga-tools"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "b2c-dx-local": {
      "command": "C:\\FULL\\PATH\\TO\\packages\\b2c-dx-mcp\\bin\\dev.cmd",
      "args": ["--toolsets", "all", "--allow-non-ga-tools"]
    }
  }
}

Restart Claude Desktop after saving.

Test Cases

All tests require --allow-non-ga-tools since all tools are currently non-GA placeholders.

Toolset Selection (`--toolsets`)

#	Args	Expected
1	`--toolsets all`	20 tools
2	`--toolsets CARTRIDGES`	1 tool: cartridge_deploy
3	`--toolsets MRT`	1 tool: mrt_bundle_push
4	`--toolsets PWAV3`	11 tools (pwakit_* + shared tools)
5	`--toolsets SCAPI`	3 tools: scapi_discovery, scapi_customapi_scaffold, scapi_custom_api_discovery
6	`--toolsets STOREFRONTNEXT`	10 tools (sfnext_* + shared tools)
7	`--toolsets CARTRIDGES,MRT`	2 tools (1 + 1)
8	`--toolsets cartridges`	1 tool (case insensitive)

Individual Tool Selection (`--tools`)

#	Args	Expected
9	`--tools cartridge_deploy`	1 tool
10	`--tools cartridge_deploy,mrt_bundle_push`	2 tools
11	`--tools cartridge_deploy,sfnext_design_decorator,mrt_bundle_push`	3 tools from different toolsets

Combination: Toolsets + Tools

#	Args	Expected
12	`--toolsets CARTRIDGES --tools sfnext_design_decorator`	2 tools (1 + 1 from different toolset)
13	`--toolsets CARTRIDGES,MRT --tools sfnext_design_decorator,scapi_discovery`	4 tools
14	`--toolsets CARTRIDGES --tools cartridge_deploy`	1 tool (no duplication)
15	`--toolsets all --tools cartridge_deploy`	20 tools (adding to "all" has no effect)

Shared Tool Deduplication

#	Args	Expected
16	`--toolsets MRT,PWAV3`	mrt_bundle_push appears once (not duplicated)
17	`--toolsets MRT,PWAV3,STOREFRONTNEXT`	mrt_bundle_push appears once
18	`--toolsets SCAPI,STOREFRONTNEXT`	scapi_discovery appears once

Validation (Warnings)

#	Args	Expected
19	`--toolsets INVALID`	Warning: "Ignoring invalid toolset(s)"
20	`--tools invalid_tool`	Warning: "Ignoring invalid tool name(s)"
21	`--toolsets CARTRIDGES,INVALID`	Warning for INVALID, CARTRIDGES enabled (1 tool)
22	`--tools cartridge_deploy,invalid_tool`	Warning for invalid_tool, cartridge_deploy enabled (1 tool)

GA/Non-GA Filtering

#	Args	Expected
23	`--toolsets all` (without `--allow-non-ga-tools`)	0 tools
24	`--toolsets all --allow-non-ga-tools`	20 tools

Tool Invocation

#	Action	Expected
25	Call any tool (e.g., `cartridge_deploy`)	Returns JSON with status "placeholder"
26	Call tool with argument (e.g., `sfnext_design_decorator` with message)	Returns JSON echoing the input

Expected Tool Counts

Toolset	Count	Tools
CARTRIDGES	1	cartridge_deploy
MRT	1	mrt_bundle_push
PWAV3	11	pwakit_create_storefront, pwakit_create_page, pwakit_create_component, pwakit_get_dev_guidelines, pwakit_recommend_hooks, pwakit_run_site_test, pwakit_install_agent_rules, pwakit_explore_scapi_shop_api, scapi_discovery, scapi_custom_api_discovery, mrt_bundle_push
SCAPI	3	scapi_discovery, scapi_customapi_scaffold, scapi_custom_api_discovery
STOREFRONTNEXT	10	sfnext_development_guidelines, sfnext_site_theming, sfnext_figma_to_component_workflow, sfnext_generate_component, sfnext_map_tokens_to_theme, sfnext_design_decorator, sfnext_generate_page_designer_metadata, scapi_discovery, scapi_custom_api_discovery, mrt_bundle_push
all	20	All tools (deduplicated)

Note: Some tools belong to multiple toolsets (e.g., mrt_bundle_push is in MRT, PWAV3, STOREFRONTNEXT). Total is deduplicated.

Tests pass (pnpm test)
Code is formatted (pnpm run format)

clavery · 2025-12-23T15:35:04Z

packages/b2c-dx-mcp/src/commands/mcp.ts

+ * - `this.parse()` - type-safe flag parsing
+ * - `this.error()` - formatted error output
+ */
+export default class McpServerCommand extends Command {


Lets try to use the BaseCommand in the SDK: cli/base-command.ts. It contains a number of flags and conventions that are globally useful for debugging and configuration. It also includes a reference to the dw.json file path in the --config flag:

description: 'Path to config file (in dw.json format; defaults to ./dw.json)', env: 'SFCC_CONFIG', helpGroup: 'GLOBAL', }),

Additionally we'll be adding more config conventions there.

clavery · 2025-12-23T15:40:37Z

packages/b2c-dx-mcp/src/commands/mcp.ts

+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+
+    // Log startup message to stderr (not stdout, which is for MCP protocol)


Note that the logging provided in the @b2c-tooling-sdk/logger and @b2c-tooling-sdk/logging/* modules log to stderr by default. So they should be compatible with MCP server STDIO transport.

When using the BaseCommand base OCLIF command class this is initialized using the BaseCommand.configureLogging method. The BaseCommand also overrides the this.log and related methods to funnel through the SDK logger.

We should opt to use this logging convention throughout the tooling. See some of the commands in the b2c-cli package

packages/b2c-dx-mcp/bin/dev.js

wei-liu-sf · 2025-12-23T16:40:38Z

packages/b2c-dx-mcp/README.md

+
+## Overview
+
+This package provides an MCP server that exposes B2C Commerce operations as tools for AI assistants. It wraps functionality from `@salesforce/b2c-tooling-sdk` and is built with [oclif](https://oclif.io/) for robust CLI handling with auto-generated help and environment variable support.


I would avoid tightening the MCP strictly with @salesforce/b2c-tooling-sdk. In fact, MCP's functionalities do not fully overlap with b2c-tooling-sdk

Thanks! I will update this.

wei-liu-sf · 2025-12-23T16:42:20Z

packages/b2c-dx-mcp/README.md

+
+## Configuration
+
+The server needs B2C Commerce credentials, provided via **environment variables** or a **`dw.json` file**.


this should be optional right?

yes, its optional. I will update it to be clear

wei-liu-sf · 2025-12-23T16:43:04Z

packages/b2c-dx-mcp/README.md

+
+### Option 2: dw.json File
+
+Create a `dw.json` file (auto-discovered from current directory):


please indicate what is necessary to auth?

wei-liu-sf · 2025-12-23T16:46:22Z

packages/b2c-dx-mcp/README.md

+{
+  "mcpServers": {
+    "b2c-dx": {
+      "command": "npx",


npx already?

This is for the setup after release. We have a section for local setup and development.

We can add it when it's actually available? Since this is open source, it may be confusing for people who actually try it and get failure.

That's a good point. I'll update it. Thanks!

wei-liu-sf · 2025-12-23T16:47:11Z

packages/b2c-dx-mcp/README.md

+
+| Toolset | Description |
+|---------|-------------|
+| `CARTRIDGES` | Code deployment and version management |


should we list tools for each tool set?

You are right. Its listed in "Available Tools" section which maps tools to tool set.

When we increase the number of tools in future, it's harder for customers to go through the long list of available tools to figure out what are in each tool set. Therefore, it's easier to list the tools under the tool set (as opposed to list the toolsets for each tool).

It might be good to have a unique command (or flag (--list-toolsets, --list-tools) for listing toolsets. Instead of relying on documentation alone. (this can be a future thing)

--list-toolsets, --list-tools and --enable-tools might be useful in the future if we want to allow AI IDE to auto discover and enable tools dynamically.
I re-structured README.md so that it reflects current state to avoid user confusion.

clavery · 2025-12-23T18:25:14Z

packages/b2c-dx-mcp/src/commands/mcp.ts

+  static flags = {
+    // Toolset selection flags
+    toolsets: Flags.string({
+      char: "s",


Can you remove the shorthand version of these flags? I suspect we will want to update the McpServerCommand to eventually inherit/mix-in flags that support instances/SCAPI (rather than just reading this from dw.json) and -s is assigned to --server, one of the most important flags.

I don't think it's important we have short-hand flags here

Yes, let me remove short-hand flags. Its not really needed to avoid conflicts.

@clavery Its removed. Please take another look.

clavery

Approved. There's a few things I want to explore in future PRs (I can help with this):

We will likely need a BaseCommand that covers instance, MRT, and API use cases. Right now our base commands do not have a "mixin" command like this but MCP needs it. I want this to live in the SDK for other users as well (i will work on this)
We'll want test coverage checks like the other packages.

yhsieh1 added 3 commits December 22, 2025 17:11

add b2c-dx-mcp server

6bfc23b

Merge main into t/commerce/W-20590941/mcp-server

6ec60bc

update readme and format

838d654

yhsieh1 requested a review from clavery as a code owner December 23, 2025 15:27

yhsieh1 requested review from patricksullivansf, snilakandan13 and wei-liu-sf December 23, 2025 15:27

Merge origin/main into t/commerce/W-20590941/mcp-server

7ebce40

clavery reviewed Dec 23, 2025

View reviewed changes

clavery requested changes Dec 23, 2025

View reviewed changes

use BaseCommand class and update dev.js run.js to use import tsx

1b1e313

wei-liu-sf reviewed Dec 23, 2025

View reviewed changes

yhsieh1 added 2 commits December 23, 2025 11:47

update readme

b527db0

update readme

5154424

yhsieh1 requested review from clavery and wei-liu-sf December 23, 2025 17:11

clavery reviewed Dec 23, 2025

View reviewed changes

yhsieh1 added 4 commits December 23, 2025 14:22

remove short hand and update readme

fff0f12

update readme to clarify tools implementation

0b95e99

clarify readme

6f25242

update local setup readme

c550da5

yhsieh1 requested a review from clavery December 23, 2025 20:03

wei-liu-sf approved these changes Dec 23, 2025

View reviewed changes

clavery approved these changes Dec 23, 2025

View reviewed changes

yhsieh1 merged commit e2392b3 into main Dec 23, 2025
2 checks passed

yhsieh1 deleted the t/commerce/W-20590941/mcp-server branch December 29, 2025 20:19


		## Overview

		This package provides an MCP server that exposes B2C Commerce operations as tools for AI assistants. It wraps functionality from `@salesforce/b2c-tooling-sdk` and is built with [oclif](https://oclif.io/) for robust CLI handling with auto-generated help and environment variable support.


		## Configuration

		The server needs B2C Commerce credentials, provided via environment variables or a `dw.json` file.


		### Option 2: dw.json File

		Create a `dw.json` file (auto-discovered from current directory):

Comments

Conversation

yhsieh1 commented Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Testing

Prerequisites

Setup

MCP Inspector (Web UI)

Cursor

Claude Desktop

Test Cases

Toolset Selection (--toolsets)

Individual Tool Selection (--tools)

Combination: Toolsets + Tools

Shared Tool Deduplication

Validation (Warnings)

GA/Non-GA Filtering

Tool Invocation

Expected Tool Counts

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

clavery Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

clavery left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

yhsieh1 commented Dec 23, 2025 •

edited

Loading

Toolset Selection (`--toolsets`)

Individual Tool Selection (`--tools`)

clavery Dec 23, 2025 •

edited

Loading