SFCC Development MCP Server

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)

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

Create a dw.json file with your SFCC credentials:

🎯 Operating Modes

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:

📦 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.

Global Installation

🐛 Debug Mode & Logging

Enable Debug Logging

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

🧑‍💻 "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