sfcc-dev-mcp 1.0.9-2 → 1.0.11

package/.github/copilot-instructions.md

@@ -62,6 +62,7 @@ sfcc-dev-mcp/
 │   │   │   └── system-objects-client.ts # System object definitions
 │   │   ├── log-client.ts         # SFCC log analysis client
 │   │   ├── docs-client.ts        # SFCC documentation client
+│   │   ├── sfra-client.ts        # SFRA documentation client
 │   │   ├── ocapi-client.ts       # Main OCAPI client coordinator
 │   │   └── best-practices-client.ts # Best practices guide client
 │   ├── config/                   # Configuration management
@@ -80,12 +81,19 @@ sfcc-dev-mcp/
 ├── docs/                         # SFCC documentation and guides
 │   ├── best-practices/           # Development best practice guides
 │   │   ├── cartridge_creation.md
+│   │   ├── isml_templates.md     
 │   │   ├── ocapi_hooks.md
 │   │   ├── scapi_hooks.md
 │   │   ├── sfra_controllers.md
 │   │   ├── scapi_custom_endpoint.md
 │   │   ├── performance.md
 │   │   └── security.md
+│   ├── sfra/                    # SFRA documentation
+│   │   ├── server.md
+│   │   ├── request.md
+│   │   ├── response.md
+│   │   ├── querystring.md
+│   │   └── render.md
 │   ├── dw_catalog/              # SFCC Catalog API documentation
 │   ├── dw_customer/             # SFCC Customer API documentation
 │   ├── dw_order/                # SFCC Order API documentation
@@ -118,8 +126,9 @@ sfcc-dev-mcp/
 ##### **Service Clients** (`clients/`)
 - **DocsClient** (`docs-client.ts`): Processes SFCC documentation and provides search capabilities across all namespaces
 - **LogClient** (`log-client.ts`): Connects to SFCC instances for real-time log analysis and monitoring
+- **SFRAClient** (`sfra-client.ts`): Provides comprehensive SFRA (Storefront Reference Architecture) documentation access including Server, Request, Response, QueryString, and render module documentation with method and property details
 - **OCAPIClient** (`ocapi-client.ts`): Main OCAPI coordinator that orchestrates specialized clients and provides unified interface
-- **BestPracticesClient** (`best-practices-client.ts`): Serves curated development guides, security recommendations, and hook references
+- **BestPracticesClient** (`best-practices-client.ts`): Serves curated development guides including cartridge creation, ISML templates with security and performance guidelines, OCAPI/SCAPI hooks, SFRA controllers, custom endpoints, security recommendations, and performance optimization strategies with hook reference tables
 
 #### **Configuration Management** (`config/`)
 - **Configuration Factory** (`configuration-factory.ts`): Creates configurations for different modes
@@ -134,7 +143,7 @@ sfcc-dev-mcp/
 
 #### **Tool Categories**
 
-1. **SFCC Documentation Tools** (7 tools)
+1. **SFCC Documentation Tools** (5 tools)
    - Class information and method documentation
    - API search and discovery
    - Complete SFCC namespace coverage
@@ -144,15 +153,21 @@ sfcc-dev-mcp/
    - Security and performance recommendations
    - Hook reference tables and examples
 
-3. **Log Analysis Tools** (6 tools)
+3. **SFRA Documentation Tools** (3 tools)
+   - SFRA class and module documentation
+   - Server, Request, Response, QueryString, and render module details
+   - Complete documentation with properties and methods included
+
+4. **Log Analysis Tools** (6 tools)
    - Real-time error monitoring
    - Log search and pattern matching
    - System health summarization
 
-4. **System Object Tools** (6 tools)
+5. **System Object Tools** (6 tools)
    - Custom attribute discovery
    - Site preference management
    - System object schema exploration
+   - Custom object attribute definitions search
 
 ### 🚀 Operating Modes
 

package/.github/workflows/publish.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '20'
           registry-url: 'https://registry.npmjs.org'
 
       - name: Configure Git

package/README.md

@@ -44,8 +44,9 @@ To use this MCP server with Claude Desktop or other MCP clients, add the followi
 
 | Tool Category | Documentation-Only Mode | Full Mode |
 |---------------|------------------------|-----------|
-| **SFCC Documentation** (7 tools) | ✅ Available | ✅ Available |
+| **SFCC Documentation** (5 tools) | ✅ Available | ✅ Available |
 | **Best Practices Guides** (4 tools) | ✅ Available | ✅ Available |
+| **SFRA Documentation** (3 tools) | ✅ Available | ✅ Available |
 | **Log Analysis** (6 tools) | ❌ Requires credentials | ✅ Available |
 | **System Object Definitions** (6 tools) | ❌ Requires OAuth | ✅ Available with OAuth |
 
@@ -53,43 +54,219 @@ To use this MCP server with Claude Desktop or other MCP clients, add the followi
 
 ## 🤖 AI Assistant Integration
 
-For optimal AI assistance when working with SFCC projects, copy the [`sfcc-ai-instructions.md`](./sfcc-ai-instructions.md) file to your SFCC project directory and rename it to `copilot-instructions.md`, `claude.md`, or similar. This file provides comprehensive guidance to AI assistants on:
+For optimal AI assistance when working with SFCC projects, this repository includes specialized instruction files for different AI interfaces in the `ai-instructions/` directory.
 
-- **When to use MCP tools** vs. relying on general AI knowledge
-- **Specific tool recommendations** for common SFCC development tasks
-- **Workflow patterns** for debugging, implementation, and best practices
-- **Error reduction** by encouraging use of current, verified SFCC information
+### Available AI Interface Instructions
 
-This significantly improves AI assistance accuracy and reduces hallucination when working on SFCC development tasks.
+| AI Interface | Location | Description |
+|--------------|----------|-------------|
+| **GitHub Copilot** | `ai-instructions/github-copilot/copilot-instructions.md` | Optimized for inline code suggestions and completions |
+| **Claude Desktop** | `ai-instructions/claude-desktop/claude_custom_instructions.md` | Leverages multi-turn conversations and MCP integration |
+| **Cursor** | `ai-instructions/cursor/.cursor/rules/` | Modern rule-based system for real-time development |
 
----
+### Quick Setup for AI Interfaces
 
-An MCP (Model Context Protocol) server that provides comprehensive access to Salesforce B2C Commerce Cloud development features. This allows AI agents to assist with SFCC development tasks including log analysis, debugging, monitoring, and **SFCC documentation querying**.
+Copy the appropriate instruction file to your SFCC project directory and follow the interface-specific setup instructions below.
+
+## 📦 Installation & Setup
+
+### Option 1: Using npx (Recommended - No Installation Required)
+
+The easiest way to use this MCP server is with npx, which automatically handles installation and updates:
+
+```bash
+# Test the server (Documentation-only mode)
+npx sfcc-dev-mcp
+
+# Use with custom dw.json file
+npx sfcc-dev-mcp --dw-json /path/to/your/dw.json
+```
+
+### Option 2: Global Installation
+
+Install the package globally for use across multiple projects:
+
+```bash
+# Install globally
+npm install -g sfcc-dev-mcp
+
+# Run from anywhere
+sfcc-dev-mcp --dw-json /path/to/your/dw.json
+```
+
+### Option 3: Local Development Installation
+
+For development or local modifications:
+
+```bash
+# Clone the repository
+git clone https://github.com/your-username/sfcc-dev-mcp.git
+cd sfcc-dev-mcp
+
+# Install dependencies
+npm install
+
+# Build the TypeScript code
+npm run build
+
+# Run locally
+npm start -- --dw-json /path/to/your/dw.json
+```
+
+## 🎯 AI Interface Setup Guides
+
+### GitHub Copilot Setup
+
+1. **Copy the instruction file** to your SFCC project root:
+   ```bash
+   cp ai-instructions/github-copilot/copilot-instructions.md your-sfcc-project/.github/copilot-instructions.md
+   ```
+
+2. **Configure the MCP server** (if using MCP-compatible tools):
+   ```json
+   {
+     "mcpServers": {
+       "sfcc-dev": {
+         "command": "npx",
+         "args": ["sfcc-dev-mcp", "--dw-json", "/path/to/your/dw.json"]
+       }
+     }
+   }
+   ```
+
+3. **Features enabled:**
+   - Inline code suggestions with SFCC context
+   - Auto-completion for SFCC APIs and patterns
+   - Template generation for controllers, hooks, and components
+   - Real-time error detection and fixes
+
+### Claude Desktop Setup
+
+1. **Copy the instruction file** to your SFCC project:
+   ```bash
+   cp ai-instructions/claude-desktop/claude_custom_instructions.md your-sfcc-project/claude-instructions.md
+   ```
+
+2. **Configure Claude Desktop MCP integration**:
+   
+   **Location of config file:**
+   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+   **Documentation-Only Mode** (No SFCC credentials needed):
+   ```json
+   {
+     "mcpServers": {
+       "sfcc-dev": {
+         "command": "npx",
+         "args": ["sfcc-dev-mcp"]
+       }
+     }
+   }
+   ```
+
+   **Full Mode** (With SFCC credentials for log analysis and system objects):
+   ```json
+   {
+     "mcpServers": {
+       "sfcc-dev": {
+         "command": "npx",
+         "args": ["sfcc-dev-mcp", "--dw-json", "/path/to/your/dw.json"]
+       }
+     }
+   }
+   ```
+
+3. **Create your dw.json file** for Full Mode:
+   ```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"
+   }
+   ```
+
+4. **Features enabled:**
+   - Real-time SFCC documentation access
+   - Multi-turn debugging conversations
+   - Architecture review and planning
+   - Complete log analysis and system object exploration
+
+### Cursor Setup
+
+1. **Copy the modern rules structure** to your SFCC project:
+   ```bash
+   cp -r ai-instructions/cursor/.cursor your-sfcc-project/
+   ```
+
+2. **Configure MCP server** (if using MCP-compatible extensions):
+   ```json
+   {
+     "mcpServers": {
+       "sfcc-dev": {
+         "command": "npx",
+         "args": ["sfcc-dev-mcp", "--dw-json", "/path/to/your/dw.json"]
+       }
+     }
+   }
+   ```
+
+3. **Available Cursor Rules:**
+   - `sfcc-development.mdc` - Core SFCC patterns (always applied)
+   - `sfra-controllers.mdc` - Controller development (auto-attached)
+   - `hooks-development.mdc` - Hook implementation (auto-attached)
+   - `debugging-workflows.mdc` - Debugging guidance (manual: `@debugging-workflows`)
+   - `system-objects.mdc` - Data model patterns (auto-attached)
+   - `security-patterns.mdc` - Security best practices (manual: `@security-patterns`)
+   - `testing-patterns.mdc` - Testing templates (auto-attached)
+   - `performance-optimization.mdc` - Performance guidance (manual: `@performance-optimization`)
+
+4. **Features enabled:**
+   - Context-aware code completion
+   - Real-time validation against SFCC APIs
+   - File-aware refactoring across cartridge structures
+   - Security-first development patterns
+
+### Operating Modes Comparison
+
+| Mode | GitHub Copilot | Claude Desktop | Cursor |
+|------|----------------|----------------|--------|
+| **Documentation Access** | ✅ Via MCP | ✅ Native MCP | ✅ Via MCP |
+| **Code Completion** | ✅ Inline | ❌ N/A | ✅ Real-time |
+| **Multi-turn Conversations** | ❌ Limited | ✅ Full | ✅ Limited |
+| **File-aware Development** | ✅ Good | ❌ N/A | ✅ Excellent |
+| **Real-time Validation** | ✅ Good | ❌ N/A | ✅ Excellent |
+| **Log Analysis** | ✅ Via MCP | ✅ Native MCP | ✅ Via MCP |
 
 ## Features
 
 ### SFCC Best Practices Guides
-- **Get Available Guides**: List all available SFCC best practice guides covering OCAPI hooks, SCAPI hooks, SFRA controllers, and custom SCAPI endpoints
-- **Get Complete Guide**: Retrieve comprehensive best practice guides with structured content for specific SFCC development areas
-- **Search Best Practices**: Search across all best practice guides for specific terms, concepts, or patterns
+- **Get Available Guides**: List all available SFCC best practice guides covering cartridge creation, ISML templates, OCAPI hooks, SCAPI hooks, SFRA controllers, and custom SCAPI endpoints
+- **Get Complete Guide**: Retrieve comprehensive best practice guides with structured content for specific SFCC development areas including the new ISML Templates guide with security, performance, and maintainability guidelines
+- **Search Best Practices**: Search across all best practice guides for specific terms, concepts, or patterns including ISML-specific topics like encoding, XSS prevention, and template architecture
 - **Get Hook Reference**: Access detailed hook reference tables for OCAPI and SCAPI hooks with endpoints and extension points
 
 ### SFCC Documentation Querying
 - **Get Class Information**: Retrieve detailed information about any SFCC class including properties, methods, and descriptions
 - **Search Classes**: Find SFCC classes by name with partial matching
-- **Get Class Methods**: List all methods for a specific SFCC class with signatures
-- **Get Class Properties**: List all properties for a specific SFCC class with types and modifiers
 - **Search Methods**: Find methods across all SFCC classes by name
 - **List All Classes**: Get a complete list of available SFCC classes
 - **Get Raw Documentation**: Access the complete Markdown documentation for any class
 
+### SFRA Documentation Access
+- **Get Available SFRA Documents**: List all available SFRA (Storefront Reference Architecture) documentation including Server, Request, Response, QueryString, and render module
+- **Get SFRA Document**: Retrieve complete SFRA class or module documentation with detailed information about properties, methods, and usage examples
+- **Search SFRA Documentation**: Search across all SFRA documentation for specific terms, concepts, or functionality related to routing, middleware, request handling, or response management
+
 ### SFCC System Object Definitions
 - **Get All System Objects**: Retrieve a complete list of all system object definitions with metadata including attribute counts
 - **Get System Object Definition**: Get detailed information about a specific system object (Product, Customer, Order, etc.) including all attributes
-- **Get System Object Attribute Definitions**: Get comprehensive attribute definitions for a specific system object type with detailed information about all attributes including custom attributes, their types, constraints, and metadata. This provides more detailed attribute information than the basic system object definition.
-- **Search System Object Attribute Definitions**: Search for specific attribute definitions within a system object type using complex queries. Supports text search on id/display_name/description, filtering by properties like mandatory/searchable/system, and sorting. Essential for finding custom attributes or attributes with specific characteristics.
+- **Search System Object Attribute Definitions**: Search for specific attribute definitions within a system object type using complex queries. Supports text search on id/display_name/description, filtering by properties like mandatory/searchable/system, and sorting. Essential for finding custom attributes or attributes with specific characteristics. To get all attributes for an object, use a match_all_query.
 - **Search Site Preferences**: Search site preferences across sites in the specified preference group and instance. Essential for discovering custom site preferences, understanding preference configurations, or when working with site-specific settings. Supports complex queries with text search, filtering, and sorting.
 - **Search System Object Attribute Groups**: Search attribute groups for a specific system object type. Essential for discovering site preference groups (use "SitePreferences" as objectType) needed for the site preferences search API. Supports complex queries with text search, filtering, and sorting on group properties.
+- **Search Custom Object Attribute Definitions**: Search for specific attribute definitions within a custom object type using complex queries. Use this for custom objects (user-defined data structures) rather than system objects. Supports text search on id/display_name/description, filtering by properties like mandatory/searchable/system, and sorting. Essential for finding custom attributes or attributes with specific characteristics in custom object definitions.
 
 *Note: System object definition tools require OAuth credentials (clientId and clientSecret) and are useful for discovering custom attributes and site preferences added to standard SFCC objects.*
 
@@ -155,6 +332,12 @@ The server expects the following structure relative to the working directory:
 │   ├── ocapi_hooks.md
 │   ├── scapi_hooks.md
 │   └── ...
+├── sfra/
+│   ├── server.md
+│   ├── request.md
+│   ├── response.md
+│   ├── querystring.md
+│   └── render.md
 ├── dw_catalog/
 ├── dw_order/
 └── ... (other SFCC class documentation folders)
@@ -202,7 +385,7 @@ export SFCC_SITE_ID="RefArch"
 
 ### Business Manager Setup for System Object Definition Tools
 
-To use the system object definition tools (`get_system_object_definitions`, `get_system_object_definition`, `get_system_object_attribute_definitions`, `search_system_object_attribute_definitions`, `search_site_preferences`, `search_system_object_attribute_groups`), you need to configure Data API access in Business Manager:
+To use the system object definition tools (`get_system_object_definitions`, `get_system_object_definition`, `search_system_object_attribute_definitions`, `search_site_preferences`, `search_system_object_attribute_groups`, `search_custom_object_attribute_definitions`), you need to configure Data API access in Business Manager:
 
 #### Step 1: Create API Client in Account Manager
 
@@ -247,15 +430,15 @@ To use the system object definition tools (`get_system_object_definitions`, `get
           "write_attributes": "(**)"
         },
         {
-          "resource_id": "/system_object_definitions/*/attribute_definitions",
+          "resource_id": "/system_object_definition_search",
           "methods": [
-            "get"
+            "post"
           ],
           "read_attributes": "(**)",
           "write_attributes": "(**)"
         },
         {
-          "resource_id": "/system_object_definition_search",
+          "resource_id": "/system_object_definitions/*/attribute_definition_search",
           "methods": [
             "post"
           ],
@@ -263,7 +446,7 @@ To use the system object definition tools (`get_system_object_definitions`, `get
           "write_attributes": "(**)"
         },
         {
-          "resource_id": "/system_object_definitions/*/attribute_definition_search",
+          "resource_id": "/system_object_definitions/*/attribute_group_search",
           "methods": [
             "post"
           ],
@@ -271,7 +454,7 @@ To use the system object definition tools (`get_system_object_definitions`, `get
           "write_attributes": "(**)"
         },
         {
-          "resource_id": "/system_object_definitions/*/attribute_group_search",
+          "resource_id": "/custom_object_definitions/*/attribute_definition_search",
           "methods": [
             "post"
           ],
@@ -539,30 +722,16 @@ You can configure the MCP client to use npx, which automatically handles package
    }
    ```
 
-3. **`get_sfcc_class_methods`** - Get all methods for a class
-   ```json
-   {
-     "className": "dw.catalog.Product"
-   }
-   ```
-
-4. **`get_sfcc_class_properties`** - Get all properties for a class
-   ```json
-   {
-     "className": "dw.catalog.Catalog"
-   }
-   ```
-
-5. **`search_sfcc_methods`** - Find methods across all classes
+3. **`search_sfcc_methods`** - Find methods across all classes
    ```json
    {
      "methodName": "getPrice"
    }
    ```
 
-6. **`list_sfcc_classes`** - List all available SFCC classes
+4. **`list_sfcc_classes`** - List all available SFCC classes
 
-7. **`get_sfcc_class_documentation`** - Get raw documentation
+5. **`get_sfcc_class_documentation`** - Get raw documentation
    ```json
    {
      "className": "dw.catalog.Product"
@@ -597,33 +766,45 @@ You can configure the MCP client to use npx, which automatically handles package
    }
    ```
 
-### SFCC System Object Definition Tools
+### SFCC SFRA Documentation Tools
 
-1. **`get_system_object_definitions`** - Get all system object definitions
+1. **`get_available_sfra_documents`** - List all available SFRA documents
+   ```json
+   {}
+   ```
+
+2. **`get_sfra_document`** - Get complete SFRA class or module documentation
    ```json
    {
-     "count": 50,
-     "select": "(**)"
+     "documentName": "server"
    }
    ```
 
-2. **`get_system_object_definition`** - Get specific system object definition
+3. **`search_sfra_documentation`** - Search across all SFRA documentation
    ```json
    {
-     "objectType": "Product"
+     "query": "middleware"
    }
    ```
 
-3. **`get_system_object_attribute_definitions`** - Get attribute definitions for an object type
+### SFCC System Object Definition Tools
+
+1. **`get_system_object_definitions`** - Get all system object definitions
    ```json
    {
-     "objectType": "Product",
-     "count": 100,
+     "count": 50,
      "select": "(**)"
    }
    ```
 
-4. **`search_system_object_attribute_definitions`** - Search attribute definitions
+2. **`get_system_object_definition`** - Get specific system object definition
+   ```json
+   {
+     "objectType": "Product"
+   }
+   ```
+
+3. **`search_system_object_attribute_definitions`** - Search attribute definitions
    ```json
    {
      "objectType": "Product",
@@ -639,7 +820,7 @@ You can configure the MCP client to use npx, which automatically handles package
    }
    ```
 
-5. **`search_site_preferences`** - Search site preferences
+4. **`search_site_preferences`** - Search site preferences
    ```json
    {
      "groupId": "MyPreferenceGroup",
@@ -660,7 +841,7 @@ You can configure the MCP client to use npx, which automatically handles package
    }
    ```
 
-6. **`search_system_object_attribute_groups`** - Search attribute groups
+5. **`search_system_object_attribute_groups`** - Search attribute groups
    ```json
    {
      "objectType": "SitePreferences",
@@ -674,6 +855,22 @@ You can configure the MCP client to use npx, which automatically handles package
    }
    ```
 
+6. **`search_custom_object_attribute_definitions`** - Search attribute definitions within a custom object type
+   ```json
+   {
+     "objectType": "custom_object_type",
+     "searchRequest": {
+       "query": {
+         "text_query": {
+           "fields": ["id", "display_name"],
+           "search_phrase": "custom_attribute"
+         }
+       },
+       "select": "(**)"
+     }
+   }
+   ```
+
 ### Log Analysis Tools
 
 1. **`get_latest_errors`** - Get recent error messages
@@ -770,6 +967,138 @@ npm run build
 npm test
 ```
 
+## Troubleshooting and Debugging
+
+### MCP Server Logs
+
+The server automatically writes all logs to files to avoid interfering with the JSON-RPC protocol and ensure consistent debugging capabilities. This prevents JSON parsing errors and provides reliable log access for troubleshooting.
+
+#### Log File Locations by Operating System
+
+**macOS:**
+```
+/tmp/sfcc-mcp-logs/
+├── sfcc-mcp-info.log      # General information and startup messages
+├── sfcc-mcp-warn.log      # Warning messages and deprecation notices
+├── sfcc-mcp-error.log     # Error messages and stack traces
+└── sfcc-mcp-debug.log     # Detailed debug information (when --debug is enabled)
+```
+
+**Windows:**
+```
+%TEMP%\sfcc-mcp-logs\
+├── sfcc-mcp-info.log      # General information and startup messages
+├── sfcc-mcp-warn.log      # Warning messages and deprecation notices
+├── sfcc-mcp-error.log     # Error messages and stack traces
+└── sfcc-mcp-debug.log     # Detailed debug information (when --debug is enabled)
+```
+
+**Linux:**
+```
+/tmp/sfcc-mcp-logs/
+├── sfcc-mcp-info.log      # General information and startup messages
+├── sfcc-mcp-warn.log      # Warning messages and deprecation notices
+├── sfcc-mcp-error.log     # Error messages and stack traces
+└── sfcc-mcp-debug.log     # Detailed debug information (when --debug is enabled)
+```
+
+#### Viewing Logs in Real-Time
+
+**macOS/Linux:**
+```bash
+# View all logs in real-time
+tail -f /tmp/sfcc-mcp-logs/*.log
+
+# View specific log levels
+tail -f /tmp/sfcc-mcp-logs/sfcc-mcp-error.log    # Errors only
+tail -f /tmp/sfcc-mcp-logs/sfcc-mcp-debug.log    # Debug info (if enabled)
+```
+
+**Windows (PowerShell):**
+```powershell
+# View error logs in real-time
+Get-Content "$env:TEMP\sfcc-mcp-logs\sfcc-mcp-error.log" -Wait
+
+# View all logs
+Get-ChildItem "$env:TEMP\sfcc-mcp-logs" | ForEach-Object { Get-Content $_.FullName -Wait }
+```
+
+#### Common Issues and Solutions
+
+**JSON Parsing Errors:**
+- **Issue**: `Expected ',' or ']' after array element in JSON at position X`
+- **Cause**: Previous versions logged to console, interfering with MCP protocol
+- **Solution**: Update to latest version - logs now go to files automatically
+
+**Log Files Not Created:**
+- **Issue**: No log files in the expected directory
+- **Cause**: Server running has permissions issue
+- **Solution**: Check that you're running via MCP client (not directly with `node`) or verify write permissions to temp directory
+
+**Missing Debug Information:**
+- **Issue**: Debug log file empty or missing detailed information
+- **Cause**: Debug mode not enabled
+- **Solution**: Add `--debug true` to your MCP client configuration:
+  ```json
+  {
+    "mcpServers": {
+      "sfcc-dev": {
+        "command": "npx",
+        "args": ["sfcc-dev-mcp", "--dw-json", "/path/to/dw.json", "--debug", "true"]
+      }
+    }
+  }
+  ```
+
+**Connection Issues:**
+- **Issue**: Server appears to start but tools don't work
+- **Cause**: Various configuration or network issues
+- **Solution**: Check error logs for specific error messages and verify SFCC credentials
+
+#### Debug Mode
+
+Enable debug mode for detailed troubleshooting information:
+
+```json
+{
+  "mcpServers": {
+    "sfcc-dev": {
+      "command": "npx",
+      "args": ["sfcc-dev-mcp", "--dw-json", "/path/to/dw.json", "--debug", "true"]
+    }
+  }
+}
+```
+
+Debug mode provides:
+- Method entry and exit tracking
+- Performance timing information
+- Full request/response details
+- Configuration loading details
+- Client initialization status
+
+#### Log Cleanup
+
+Log files accumulate over time. You can safely delete old log files:
+
+**macOS/Linux:**
+```bash
+# Remove all log files
+rm /tmp/sfcc-mcp-logs/*.log
+
+# Remove logs older than 7 days
+find /tmp/sfcc-mcp-logs -name "*.log" -mtime +7 -delete
+```
+
+**Windows:**
+```powershell
+# Remove all log files
+Remove-Item "$env:TEMP\sfcc-mcp-logs\*.log"
+
+# Remove logs older than 7 days
+Get-ChildItem "$env:TEMP\sfcc-mcp-logs" -Filter "*.log" | Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-7) } | Remove-Item
+```
+
 ### Documentation Generation
 
 The SFCC documentation is automatically converted from the official SFCC documentation using the included scraping script.