io.github.taurgis/sfcc-dev-mcp

Install

Config snippet generator goes here (5 client tabs)

README

# SFCC Development MCP Server

[![npm version](https://badge.fury.io/js/sfcc-dev-mcp.svg)](https://badge.fury.io/js/sfcc-dev-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

## ✨ Key Features

- **🔍 Complete SFCC Documentation Access** - Search and explore all SFCC API classes and methods
- **🏗️ SFRA Documentation** - Enhanced access to Storefront Reference Architecture documentation
- **🧱 ISML Template Reference** - Complete ISML element documentation with examples and usage guidance
- **📊 Log Analysis Tools** - Real-time error monitoring, debugging, and job log analysis for SFCC instances
- **⚙️ System Object Definitions** - Explore custom attributes and site preferences
- **🧪 Script Debugger** - Execute and inspect script-debugger endpoints in credentialed mode
- **🚀 Cartridge Generation** - Automated cartridge structure creation with workspace-bound path safety (writes stay inside workspace roots, or current working directory fallback when roots are unavailable; home-directory fallback is blocked)
- **🧩 Agent Skill Bootstrap** - Install or merge AGENTS.md and bundled skills into the current project or a temp directory for AI assistants
- **✅ Tool Argument Validation** - Runtime schema validation enforces required fields, type checks, enum constraints, integer/numeric bounds, and strict unknown-key checks for object schemas (top-level and nested) before handler execution
- **⏱️ MCP Progress + Cancellation** - Tool calls honor request cancellation signals and emit out-of-band `notifications/progress` updates when clients provide a `progressToken`

## 🚀 Quick Start

### Option 1: Documentation-Only Mode (No SFCC credentials needed)
```json
{
  "mcpServers": {
    "sfcc-dev": {
      "command": "npx",
      "args": ["sfcc-dev-mcp"]
    }
  }
}
```

### Option 2: Full Mode (With SFCC credentials for log and job analysis)  
```json
{
  "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. You can use either auth mode (or both):
- Basic auth: `username` + `password`
- OAuth: `client-id` + `client-secret`
```json
{
  "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"
}
```

At least one complete credential pair is required when `hostname` is set.
If credentials are provided, `hostname` is also required.

### Option 3: Auto-Discovery (Recommended for VS Code users)
Simply open a VS Code workspace that contains a `dw.json` file - the server will automatically discover and use it:
```json
{
  "mcpServers": {
    "sfcc-dev": {
      "command": "npx",
      "args": ["sfcc-dev-mcp"]
    }
  }
}
```

## 🔧 Configuration Discovery Priority

The server discovers SFCC credentials in this order (highest priority first):

| Priority | Source | Description |
|----------|--------|-------------|
| **1** | `--dw-json` CLI parameter | Explicit path to dw.json file |
| **2** | Environment variables | `SFCC_HOSTNAME`, `SFCC_USERNAME`, `SFCC_PASSWORD`, `SFCC_CLIENT_ID`, `SFCC_CLIENT_SECRET` |
| **3** | MCP workspace roots | Automatically discovers dw.json in your VS Code workspace folder(s), and refreshes when the client sends `notifications/roots/list_changed` |

> **Note**: The server no longer searches the current working directory by default, as MCP servers often start with `cwd` set to the user's home directory. The MCP workspace roots mechanism provides reliable project context.

## 🎯 Operating Modes

| Mode | Tools Available | SFCC Credentials Required |
|------|----------------|---------------------------|
| **Documentation-Only** | 18 tools | ❌ No |
| **Full Mode** | 40 tools | ✅ Yes |

### Documentation-Only Mode
Perfect for learning and development, no SFCC instance required:
- Complete SFCC API documentation (5 tools)
- SFRA documentation (5 tools)
- ISML template documentation (5 tools)
- Cartridge generation (1 tool, writes constrained to workspace roots/cwd)
- Agent instruction bootstrap (2 tools) to copy/merge AGENTS.md and skills, or disable future prompts

### Full Mode  
Complete development experience with live SFCC instance access:
- All documentation-only features (18 tools)
- Real-time log analysis and job logs (13 tools)
- System object definitions (6 tools)
- Code version management (2 tools)
- Script debugger operations (1 tool)

## 🏗️ Architecture Overview

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

### Core Layers
- **Tool Schemas** (`src/core/tool-schemas/`): Modular