Skip to content

README.md

Latest commit

 

History

History
412 lines (301 loc) · 16.9 KB

README.md

File metadata and controls

412 lines (301 loc) · 16.9 KB

Salesforce Commerce Cloud B2C MCP Server

MCP (Model Context Protocol) server for Salesforce B2C Commerce Cloud developer experience tools.

⚠️ Active Development: This package is under active development. All tools are currently placeholder implementations that return mock responses. Tool implementations will be added incrementally.

Overview

This MCP server enables AI assistants to help with B2C Commerce development tasks. It provides toolsets for SCAPI, CARTRIDGES, MRT, PWAV3, and STOREFRONTNEXT development.

The server automatically detects your project type and enables relevant tools. See Available Toolsets and Tools for details.

Usage

Working Directory and Auto-Discovery

The most important flag is --working-directory (or env var SFCC_WORKING_DIRECTORY). It tells the server where your project is located, enabling:

  1. Auto-discovery - Detects your project type and enables appropriate toolsets
  2. Configuration loading - Reads dw.json from your project for credentials
  3. Scaffolding - Creates new files in the correct location

Important: MCP clients like Cursor and Claude Desktop spawn servers from the home directory (~), not your project. Always set --working-directory.

Cursor (supports ${workspaceFolder}):

{
  "mcpServers": {
    "b2c-dx": {
      "command": "node",
      "args": ["/path/to/packages/b2c-dx-mcp/bin/dev.js", "--working-directory", "${workspaceFolder}", "--allow-non-ga-tools"]
    }
  }
}

Claude Desktop (use explicit path):

{
  "mcpServers": {
    "b2c-dx": {
      "command": "node",
      "args": ["/path/to/packages/b2c-dx-mcp/bin/dev.js", "--working-directory", "/path/to/your/project", "--allow-non-ga-tools"]
    }
  }
}

Project Type Detection

The server analyzes your working directory and enables toolsets based on what it finds:

Project Type Detection Toolsets Enabled
PWA Kit v3 @salesforce/pwa-kit-*, @salesforce/retail-react-app, or ccExtensibility in package.json PWAV3, MRT, SCAPI
Storefront Next @salesforce/storefront-next-* in package.json STOREFRONTNEXT, MRT, SCAPI
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.

Manual Toolset Selection

Override auto-discovery by specifying toolsets explicitly:

"args": ["--working-directory", "${workspaceFolder}", "--toolsets", "CARTRIDGES,MRT", "--allow-non-ga-tools"]

Prompting Tips and Examples

AI assistants (like Cursor, Claude Desktop) automatically decide which MCP tools to use based on your prompts. To get the best results, use clear, specific prompts that describe what you want to accomplish.

⚠️ IMPORTANT: Explicitly mention "Use the MCP tool" in your prompts for reliable tool usage. While AI assistants (like Cursor's Composer) 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. This is particularly important for getting project-specific, up-to-date information rather than generic responses.

Best Practices

  1. Always explicitly request MCP tool usage (see warning above): 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

Examples by Tool Category

Storefront Next Development Guidelines

The storefront_next_development_guidelines tool provides critical architecture rules and best practices. Use this tool first when starting new Storefront Next development or when you need architecture guidance.

Good prompts:

  • ✅ "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 need to build a checkout form with authentication and validation. Use the MCP tool to show me how to handle form submissions, authentication, and internationalized error messages."
  • ✅ "Use the MCP tool to show me the data fetching patterns for Storefront Next."
  • ✅ "Show me all available Storefront Next development guidelines."

Available sections:

  • quick-reference - Critical rules and architecture principles (default)
  • data-fetching - Data loading patterns with loaders
  • state-management - Client-side state management
  • auth - Authentication and session management
  • components - Component patterns and best practices
  • styling - Tailwind CSS 4, Shadcn/ui, styling guidelines
  • page-designer - Page Designer integration
  • performance - Performance optimization
  • testing - Testing strategies
  • i18n - Internationalization patterns
  • config - Configuration management
  • extensions - Extension development
  • pitfalls - Common pitfalls
PWA Kit Development

Good prompts:

  • ✅ "I'm starting a new PWA Kit project. Use the MCP tool to get the development guidelines."
  • ✅ "Use the MCP tool to create a new product listing page component in my PWA Kit project."
  • ✅ "Use the MCP tool to recommend React hooks for fetching product data in PWA Kit."
  • ✅ "Use the MCP tool to explore the SCAPI Shop API endpoints available for my PWA Kit storefront."
SCAPI Discovery

Good prompts:

  • ✅ "Use the MCP tool to discover what SCAPI endpoints are available for product data."
  • ✅ "Use the MCP tool to discover custom SCAPI APIs in my B2C instance."
  • ✅ "Use the MCP tool to show me all available SCAPI endpoints and their capabilities."
  • ✅ "Use the MCP tool to scaffold a new custom SCAPI API for order management."
Cartridge Deployment

Good prompts:

  • ✅ "Use the MCP tool to deploy my cartridges to the sandbox instance."
  • ✅ "Use the MCP tool to deploy only the app_storefront_base cartridge to production."
  • ✅ "Use the MCP tool to deploy cartridges from the ./cartridges directory and reload the code version."
MRT Bundle Operations

Good prompts:

  • ✅ "Use the MCP tool to build and push my Storefront Next bundle to staging."
  • ✅ "Use the MCP tool to push the bundle from ./build directory to Managed Runtime."
  • ✅ "Use the MCP tool to deploy my PWA Kit bundle to production with a deployment message."

Tips for Better Results

  • Start with guidelines: When learning a new framework, ask for development guidelines first using "Use the MCP tool to get..."
  • Combine related topics: Ask for multiple related sections (e.g., "data fetching and components") in one request
  • Provide project context: Mention your project type (Storefront Next, PWA Kit, cartridges) for better tool selection
  • Specify operations clearly: For deployment operations, mention the target (sandbox, staging, production) and what to deploy

Configuration

Credentials can be provided via config files (recommended), environment variables, or flags. Priority: Flags > Env vars > Config files.

Toolset Required Credentials
SCAPI hostname + client-id + client-secret
CARTRIDGES hostname + username + password (or OAuth)
MRT api-key + project (optionally environment)
PWAV3 --working-directory only (+ MRT config for deployments)
STOREFRONTNEXT --working-directory only (+ MRT/CARTRIDGES config for those tools)

Option 1: Config files (recommended)

B2C credentials — dw.json in your project root:

{ "hostname": "xxx.demandware.net", "username": "...", "password": "...", "client-id": "...", "client-secret": "..." }

MRT credentials — ~/.mobify (create manually or via B2C CLI):

{ "api_key": "..." }

Option 2: Environment variables

"env": { "SFCC_SERVER": "xxx.demandware.net", "SFCC_USERNAME": "...", "SFCC_PASSWORD": "...", "SFCC_MRT_API_KEY": "..." }

Option 3: Flags

"args": ["--server", "xxx.demandware.net", "--username", "...", "--password", "...", "--api-key", "..."]

See Flag Reference for all available flags and env vars.

  • username/password = B2C username + WebDAV access key
  • client-id/client-secret = API client credentials from Account Manager

Flag Reference

Click to expand flag reference

Core Flags

Flag Env Variable Description
--working-directory SFCC_WORKING_DIRECTORY Project directory (enables auto-discovery and config loading)
--toolsets — Comma-separated toolsets to enable
--tools — Comma-separated individual tools to enable
--allow-non-ga-tools — Enable experimental (non-GA) tools
--config — Explicit path to dw.json (advanced)
--log-level — Logging verbosity (trace, debug, info, warn, error, silent)
--debug — Enable debug logging

B2C Instance Flags

Flag Env Variable Description
--server SFCC_SERVER B2C instance hostname
--username SFCC_USERNAME Username for Basic auth (WebDAV)
--password SFCC_PASSWORD Password/access key for Basic auth
--client-id SFCC_CLIENT_ID OAuth client ID
--client-secret SFCC_CLIENT_SECRET OAuth client secret
--code-version SFCC_CODE_VERSION Code version for deployments

MRT Flags

Flag Env Variable Description
--api-key SFCC_MRT_API_KEY MRT API key
--project SFCC_MRT_PROJECT MRT project slug
--environment SFCC_MRT_ENVIRONMENT MRT environment (staging, production)
--cloud-origin SFCC_MRT_CLOUD_ORIGIN MRT cloud origin URL

Available Toolsets and Tools

Use --toolsets all to enable all toolsets, or select specific ones with --toolsets CARTRIDGES,MRT.

Note: All tools are currently placeholder implementations. Use --allow-non-ga-tools flag to enable them.

CARTRIDGES

Cartridge development, deployment, and code version management.

  • Status: 🚧 Placeholder
Tool Description
cartridge_deploy Deploy cartridges to a B2C Commerce instance

MRT

Managed Runtime operations for PWA Kit and Storefront Next deployments.

  • Status: 🚧 Placeholder
Tool Description
mrt_bundle_push Build, push bundle (optionally deploy)

PWAV3

PWA Kit v3 development tools for building headless storefronts.

  • Status: 🚧 Placeholder
Tool Description
pwakit_create_storefront Create a new PWA Kit storefront project
pwakit_create_page Create a new page component in PWA Kit project
pwakit_create_component Create a new React component in PWA Kit project
pwakit_get_dev_guidelines Get PWA Kit development guidelines and best practices
pwakit_recommend_hooks Recommend appropriate React hooks for PWA Kit use cases
pwakit_run_site_test Run site tests for PWA Kit project
pwakit_install_agent_rules Install AI agent rules for PWA Kit development
pwakit_explore_scapi_shop_api Explore SCAPI Shop API endpoints and capabilities
scapi_discovery Discover available SCAPI endpoints and capabilities
scapi_custom_api_discovery Discover custom SCAPI API endpoints
mrt_bundle_push Build, push bundle (optionally deploy)

SCAPI

Salesforce Commerce API discovery and exploration.

  • Status: 🚧 Placeholder
Tool Description
scapi_discovery Discover available SCAPI endpoints and capabilities
scapi_customapi_scaffold Scaffold a new custom SCAPI API
scapi_custom_api_discovery Discover custom SCAPI API endpoints

STOREFRONTNEXT

Storefront Next development tools for building modern storefronts.

  • Status: 🚧 Placeholder
Tool Description
storefront_next_development_guidelines Get Storefront Next development guidelines and best practices
storefront_next_site_theming Configure and manage site theming for Storefront Next
storefront_next_figma_to_component_workflow Convert Figma designs to Storefront Next components
storefront_next_generate_component Generate a new Storefront Next component
storefront_next_map_tokens_to_theme Map design tokens to Storefront Next theme configuration
storefront_next_design_decorator Apply design decorators to Storefront Next components
storefront_next_generate_page_designer_metadata Generate Page Designer metadata for Storefront Next components
scapi_discovery Discover available SCAPI endpoints and capabilities
scapi_custom_api_discovery Discover custom SCAPI API endpoints
mrt_bundle_push Build, push bundle (optionally deploy)

Note: Some tools appear in multiple toolsets (e.g., mrt_bundle_push, scapi_discovery). When using multiple toolsets, tools are automatically deduplicated.

Development

Quick Start

# Install dependencies (from monorepo root)
pnpm install

# Navigate to the package directory
cd packages/b2c-dx-mcp

# Launch MCP Inspector for development (no build needed, uses TypeScript directly)
pnpm run inspect:dev

# Launch MCP Inspector with production build (runs build first)
pnpm run inspect

# Build the package
pnpm run build

# Run tests (includes linting)
pnpm run test

# Format code
pnpm run format

# Run linter only
pnpm run lint

# Clean build artifacts
pnpm run clean

Working Directory

Commands should be run from the packages/b2c-dx-mcp directory:

cd packages/b2c-dx-mcp

Or use pnpm's filter flag from the monorepo root:

pnpm --filter @salesforce/b2c-dx-mcp run <script>

Testing the MCP Server Locally

1. MCP Inspector

Use MCP Inspector to browse tools and test them in a web UI:

pnpm run inspect:dev

This runs TypeScript directly (no build needed). Open the localhost URL shown in the terminal, click Connect, then List Tools to see available tools.

For CLI-based testing:

# List all tools
npx mcp-inspector --cli node bin/dev.js --toolsets all --allow-non-ga-tools --method tools/list

# Call a specific tool
npx mcp-inspector --cli node bin/dev.js --toolsets all --allow-non-ga-tools \
  --method tools/call \
  --tool-name storefront_next_design_decorator

2. IDE Integration

Configure your IDE to use the local MCP server. Add this to your IDE's MCP configuration:

{
  "mcpServers": {
    "b2c-dx-local": {
      "command": "node",
      "args": [
        "/full/path/to/packages/b2c-dx-mcp/bin/dev.js",
        "--toolsets", "all",
        "--allow-non-ga-tools"
      ]
    }
  }
}

Note: Make sure the script is executable: chmod +x /full/path/to/packages/b2c-dx-mcp/bin/dev.js

The script's shebang (#!/usr/bin/env -S node --conditions development) handles Node.js setup automatically.

Note: Restart the MCP server in your IDE to pick up code changes.

3. JSON-RPC via stdin

Send raw MCP protocol messages:

# List all tools (--allow-non-ga-tools required for placeholder tools)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node bin/dev.js --toolsets all --allow-non-ga-tools

# Call a specific tool
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"cartridge_deploy","arguments":{}}}' | node bin/dev.js --toolsets all --allow-non-ga-tools

License

Apache-2.0