Skip to content

Supercharge your Salesforce B2C Commerce Cloud development with AI-powered documentation access, real-time log analysis, and intelligent best practices guidance

License

Notifications You must be signed in to change notification settings

taurgis/sfcc-dev-mcp

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

SFCC Development MCP Server

npm version License: MIT

An AI-powered Model Context Protocol (MCP) server that provides comprehensive access to Salesforce B2C Commerce Cloud development tools, documentation, and best practices.

โœจ Key Features

  • ๐Ÿ” Complete SFCC Documentation Access - Search and explore all SFCC API classes and methods
  • ๐Ÿ“š Best Practices Guides - Curated development guidelines for cartridges, hooks, controllers, client-side JavaScript, and more
  • ๐Ÿ—๏ธ SFRA Documentation - Enhanced access to Storefront Reference Architecture documentation
  • ๐Ÿ“Š Log Analysis Tools - Real-time error monitoring, debugging, and job log analysis for SFCC instances
  • โš™๏ธ System Object Definitions - Explore custom attributes and site preferences
  • ๐Ÿš€ Cartridge Generation - Automated cartridge structure creation

๐Ÿš€ Quick Start

Option 1: Documentation-Only Mode (No SFCC credentials needed)

{
  "mcpServers": {
    "sfcc-dev": {
      "command": "npx",
      "args": ["sfcc-dev-mcp"]
    }
  }
}

Option 2: Full Mode (With SFCC credentials for log and job analysis)

{
  "mcpServers": {
    "sfcc-dev": {
      "command": "npx",
      "args": ["sfcc-dev-mcp", "--dw-json", "/path/to/your/dw.json"]
    }
  }
}

Create a dw.json file with your SFCC credentials:

{
  "hostname": "your-instance.sandbox.us01.dx.commercecloud.salesforce.com",
  "username": "your-username",
  "password": "your-password", 
  "client-id": "your-client-id",
  "client-secret": "your-client-secret"
}

๐ŸŽฏ Operating Modes

Mode Tools Available SFCC Credentials Required
Documentation-Only 15 tools โŒ No
Full Mode 36 tools โœ… Yes

Documentation-Only Mode

Perfect for learning and development - no SFCC instance required:

  • Complete SFCC API documentation (5 tools)
  • Best practices guides (4 tools) โ€“ cartridges, client-side JavaScript, controllers, hooks, security/performance
  • SFRA documentation (5 tools)
  • Cartridge generation (1 tool)

Full Mode

Complete development experience with live SFCC instance access:

  • All documentation-only features (15 tools)
  • Real-time log analysis (13 tools)
  • System object definitions (6 tools)
  • Code version management (2 tools)

๏ฟฝ Architecture Overview

This server is built around a capability-gated, modular handler architecture that cleanly separates tool routing from domain logic:

Core Layers

  • Tool Definitions (src/core/tool-definitions.ts): Declarative schemas grouped by category (documentation, best practices, SFRA, logs, job logs, system objects, cartridge generation, code versions).
  • Handlers (src/core/handlers/*.ts): Each category has a handler extending a common base for timing, structured logging, and error normalization (e.g. log-handler, docs-handler, system-object-handler).
  • Clients (src/clients/): Encapsulate domain operations (OCAPI, SFRA docs, best practices, modular log analysis). Handlers delegate to these so orchestration and computation remain separate.
  • Services (src/services/): Dependency-injected abstractions for filesystem and path operations โ€” improves testability and isolates side effects.
  • Modular Log System (src/clients/logs/): Reader (range/tail optimization), discovery, processor (line โ†’ structured entry), analyzer (patterns & health), formatter (human output) for maintainable evolution.
  • Configuration Factory (src/config/configuration-factory.ts): Determines capabilities (canAccessLogs, canAccessOCAPI) based on provided credentials and filters exposed tools accordingly (principle of least privilege).

Why This Matters

  • Extensibility: Adding a new tool usually means adding a schema + minimal handler logic (or a new handler if a new domain).
  • Security: Tools that require credentials are never exposed when capability flags are false.
  • Testability: Unit tests target clients & modules; integration/MCP tests validate handler routing and response structure.
  • Performance: Tail log reads + lightweight caching (cache.ts, log-cache.ts) reduce unnecessary I/O.

Adding a New Tool (High-Level)

  1. Add schema object to the correct exported array in tool-definitions.ts.
  2. Implement domain logic in a client/service (avoid bloating handlers).
  3. Extend an existing handler or create a new one if it's a new category.
  4. (Only for a new category) register the new handler inside registerHandlers() in server.ts.
  5. Discover actual response shape with npx mcp-aegis query before writing tests.
  6. Add Jest unit tests + YAML MCP tests (docs vs full mode if credentials required).
  7. Update documentation (Development Guide + README counts if changed).

For a deeper internal view, see the Development Guide in the docs site.

๏ฟฝ๐Ÿค– AI Interface Setup

Choose your preferred AI assistant:

Interface Best For Setup Guide
Claude Desktop Multi-turn conversations, debugging ๐Ÿ“– Setup Guide
GitHub Copilot VS Code integration, inline suggestions ๐Ÿ“– Setup Guide
Cursor Modern AI-powered editor ๐Ÿ“– Setup Guide

๐Ÿ“ฆ Installation

Using npx (Recommended)

Tip: Add -y (or --yes) to suppress the interactive prompt npx shows before downloading a package. This prevents AI clients (Claude Desktop, Copilot, Cursor) from hanging waiting for confirmation.

# Test the server
npx -y sfcc-dev-mcp

# Use with your configuration
npx -y sfcc-dev-mcp --dw-json /path/to/your/dw.json

Global Installation

npm install -g sfcc-dev-mcp
sfcc-dev-mcp --dw-json /path/to/your/dw.json

๐Ÿ› Debug Mode & Logging

Enable Debug Logging

# Enable debug mode for detailed logging
npx -y sfcc-dev-mcp --debug

# Or with configuration file
npx -y sfcc-dev-mcp --dw-json /path/to/your/dw.json --debug

Log File Locations

The server writes logs to your system's temporary directory:

  • macOS: /var/folders/{user-id}/T/sfcc-mcp-logs/
  • Linux: /tmp/sfcc-mcp-logs/
  • Windows: %TEMP%\sfcc-mcp-logs\

Log Files Created:

  • sfcc-mcp-info.log - General application logs and startup messages
  • sfcc-mcp-debug.log - Detailed debug information (only when --debug is enabled)
  • sfcc-mcp-error.log - Error messages and stack traces
  • sfcc-mcp-warn.log - Warning messages

Finding Your Log Directory

// The exact path varies by system - to find yours:
node -e "console.log(require('os').tmpdir() + '/sfcc-mcp-logs')"

## ๐Ÿ“– Documentation

**๐Ÿ“š [Complete Documentation](https://taurgis.github.io/sfcc-dev-mcp/)** - Comprehensive guides and references

Quick Links:
- **[Installation Guide](https://taurgis.github.io/sfcc-dev-mcp/installation)** - Detailed installation options
- **[AI Interface Setup](https://taurgis.github.io/sfcc-dev-mcp/ai-interfaces)** - Configure Claude Desktop, GitHub Copilot, or Cursor
- **[Configuration Guide](https://taurgis.github.io/sfcc-dev-mcp/configuration)** - SFCC credentials and Data API setup
- **[Available Tools](https://taurgis.github.io/sfcc-dev-mcp/tools)** - Complete tool reference
- **[Examples](https://taurgis.github.io/sfcc-dev-mcp/examples)** - Real-world usage patterns
- **[Troubleshooting](https://taurgis.github.io/sfcc-dev-mcp/troubleshooting)** - Common issues and solutions

## ๐Ÿ› ๏ธ Example AI Interactions

๐Ÿง‘โ€๐Ÿ’ป "Create a new SFCC controller for product search" ๐Ÿค– Generates complete controller with proper imports, route handling, and SFRA patterns

๐Ÿง‘โ€๐Ÿ’ป "What's wrong with my checkout flow? Check the logs"
๐Ÿค– Analyzes recent error logs, identifies issues, and suggests fixes

๐Ÿง‘โ€๐Ÿ’ป "Show me how to implement OCAPI hooks for order validation" ๐Ÿค– Provides best practices guide with complete hook implementation examples


## ๐Ÿ”’ Security Notes

- **Local Development Focus**: Designed for individual developer use on local machines
- **Credential Protection**: dw.json files should never be committed to version control
- **Network Security**: All API calls use HTTPS with proper authentication
- **No Data Storage**: Server doesn't persist any SFCC data locally

## ๐Ÿ”ฎ Future Plans

We're continuously improving the SFCC Development MCP Server with exciting new features planned:

### ๐ŸŽฏ Upcoming Enhancements

- **๐Ÿง  Smarter Log Fetching** - Enhanced log analysis with intelligent filtering, pattern recognition, and contextual error correlation
- **๐Ÿš€ Deployment Tools** - Integration with SFCC deployment processes and code version management

### ๐Ÿค We Welcome Your Contributions!

Have ideas for new features or improvements? We'd love to hear from you! 

- **๐Ÿ’ก Feature Requests**: Open an issue to discuss your ideas
- **๐Ÿ› Bug Reports**: Help us improve by reporting any issues you encounter  
- **๐Ÿ”ง Pull Requests**: Contribute code, documentation, or examples
- **๐Ÿ“š Documentation**: Help expand our guides and best practices

Check out our [Contributing Guide](CONTRIBUTING.md) to get started, or browse our [open issues](https://github.com/taurgis/sfcc-dev-mcp/issues) to see where you can help.

**Your expertise and feedback make this tool better for the entire SFCC community!**

## ๐Ÿค Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## ๐Ÿ“„ License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

**๐Ÿš€ Ready to supercharge your SFCC development with AI?**

**[๐Ÿ“– Get Started with the Full Documentation](https://taurgis.github.io/sfcc-dev-mcp/)**

About

Supercharge your Salesforce B2C Commerce Cloud development with AI-powered documentation access, real-time log analysis, and intelligent best practices guidance

Topics

Resources

License

Contributing

Security policy

Stars

Watchers

Forks

Packages

No packages published

Contributors 3

  •  
  •  
  •