sfcc-dev-mcp 1.0.21 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.1.0
+
+### Minor Changes
+
+- a0f5fbb: Add script debugger support for credentialed troubleshooting, including dedicated storefront authentication and custom trigger URLs.
+
+  Improve MCP execution and configuration handling with progress notifications, request cancellation, runtime WebDAV capability checks, flexible `dw.json` authentication, strict tool argument validation, and structured timeout-aware tool results.
+
+  Strengthen overall reliability with broader documentation and skill guidance, stronger tests and post-publish validation, and robustness improvements across the server, handlers, and configuration pipeline.
+
 All notable changes to this project will be documented in this file.
 
 The format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
@@ -7,8 +17,10 @@ The format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.
 Release comparison links are provided at the bottom. Earlier patch releases on the same day may represent rapid iterations (e.g. architectural + documentation expansions). Dates are derived from git tag timestamps.
 
 ## [1.0.15] - 2025-10-03
+
 ### Added
-- **SFRA Best Practices Expansion**: 
+
+- **SFRA Best Practices Expansion**:
   - SFRA SCSS best practices guide with theming and override patterns
   - SFRA client-side JavaScript guide covering AJAX flows, validation, and accessibility
 - **OCAPI Select Parameter Support**: Comprehensive support for OCAPI select syntax to control response field selection
@@ -25,6 +37,7 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
 - **Custom Endpoint Caching**: Comprehensive caching strategies documentation for custom SCAPI endpoints with two-tier pattern examples
 
 ### Changed
+
 - **Testing Framework Migration**: Replaced Conductor with Aegis for MCP testing with improved declarative YAML patterns
 - **Documentation Modernization**:
   - Revamped documentation site with improved layout and readability
@@ -41,16 +54,19 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
 - **AI Interface Enhancements**: Improved AI interface and configuration documentation
 
 ### Fixed
+
 - **SSR Hydration**: Fixed SSR hydration mismatch in OnThisPage component
 - **Hash Navigation**: Resolved hash navigation issues after search operations
 
 ### Documentation
+
 - **CSRF Middleware**: Clarified CSRF middleware usage patterns in SFRA
 - **Remote Include Architecture**: Added detailed explanation of remote include patterns for dynamic content
 - **Aegis Testing**: Comprehensive updates to Aegis testing documentation with best practices
 - **Performance Guidance**: Enhanced performance best practices with SCAPI-specific caching strategies
 
 ### Testing
+
 - **Comprehensive Test Coverage**:
   - OCAPI error handling and validation tests
   - Site preferences search tool tests
@@ -64,6 +80,7 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
   - Enhanced test targeting and organization
 
 ### Dependencies
+
 - **GitHub Actions Updates**:
   - `actions/checkout` from 4 to 5
   - `actions/configure-pages` from 4 to 5
@@ -77,16 +94,19 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
   - Updated `ts-jest` in Jest group
 
 ### Notes
+
 - Major testing infrastructure modernization with Aegis framework adoption
 - Significant documentation site improvements with SSG migration and enhanced UX
 - Expanded SFRA best practices coverage for complete development lifecycle
 - Enhanced OCAPI functionality with select parameter support and comprehensive mocking
 
 ## [1.0.14] - 2025-09-16
+
 ### Added
+
 - **SFCC Class Information Filtering**: Enhanced `get_sfcc_class_info` tool with comprehensive filtering capabilities including search parameter, inclusion/exclusion of descriptions, constants, properties, methods, and inheritance hierarchy.
 - **AI Response Comparison Modals**: Interactive modals on documentation site showing side-by-side comparison of AI responses with and without MCP server, including zoom functionality for detailed inspection.
-- **Documentation Site Enhancements**: 
+- **Documentation Site Enhancements**:
   - Examples page with practical usage scenarios and filtering demonstrations
   - Tools page documenting all available MCP tools
   - Features page highlighting key capabilities
@@ -99,6 +119,7 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
 - **Anchor Link Navigation**: Added IDs to documentation headers for direct linking.
 
 ### Changed
+
 - **Project Licensing**: Aligned to MIT License (replaced ISC LICENSE text, updated `package.json` license field).
 - **CI/CD Pipeline**: Enhanced with improved linting and security checks.
 - **Documentation Structure**: Comprehensive reorganization and expansion of documentation site structure.
@@ -107,152 +128,199 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
 - **UI/UX Polish**: Improved padding, layout adjustments, and site navigation structure.
 
 ### Fixed
+
 - **URL Fragment Handling**: Fixed URL-encoded hash fragment handling in documentation site.
 - **Workflow Deployment**: Corrected path issues for page deployment.
 - **Log Tool Validation**: Improved argument validation robustness for log analysis tools.
 
 ### Documentation
+
 - **AI Interface Setup**: Comprehensive guides for Claude Desktop, Cursor, and GitHub Copilot integration.
 - **Security Guidance**: Enhanced security considerations and best practices documentation.
 - **Troubleshooting**: Added comprehensive troubleshooting guide for common setup and usage issues.
 - **Development Workflow**: Detailed development guidelines and contribution instructions.
 
 ### Testing
-- **Enhanced Test Coverage**: 
+
+- **Enhanced Test Coverage**:
   - Comprehensive programmatic tests for SFCC class info filtering in documentation mode
   - Enhanced YAML-based MCP tests for class information tools
   - Job execution summary tests and job log analysis tests
   - Improved test setup reliability and CI stability
 
 ### Notes
+
 - Major documentation site expansion with React/Vite architecture
 - Enhanced developer experience with comprehensive filtering and search capabilities
 - Improved AI assistant integration with detailed setup guides for multiple platforms
 
 ## [1.0.13] - 2025-09-15
+
 ### Added
+
 - `engines` field in `package.json` enforcing Node >=18 and npm >=8.
 - Comprehensive architectural documentation (handler modularization, capability gating, services layer, log subsystem, tool-configs, caching).
 - Initial `CHANGELOG.md` introduction.
 
 ### Changed
+
 - Server reported version synchronized with `package.json`.
 - Development guide: migrated from legacy Jekyll instructions to Vite workflow; updated tool addition workflow for new handler architecture.
 
 ### Fixed
+
 - Removed references to non-existent config files (`config.ts`, `constants.ts`).
 - Corrected debug flag examples (`--debug` vs `--debug true`).
 - Escaping/format fixes in development guide code blocks.
 
 ### Notes
+
 - Pre-1.0.14 license mismatch (ISC vs MIT badge) resolved in 1.0.14.
 
 ## [1.0.12] - 2025-08-19
+
 ### Added
+
 - Code version management tools (listing & activation) with supporting documentation.
 - Cartridge generation enhancements: page layout & styling improvements; prevention of overwriting existing files.
 - Security and OCAPI configuration warnings; highlighted AI instruction files.
 - Additional SFRA model and best practice documentation (ISML decorators, LocalServiceRegistry, Auth examples, BM configuration guide).
 
 ### Changed
+
 - ESLint configuration (global vars, lint fix script), table styling, documentation site theme updates, repository URL in config, branch protection for deploy (restricted to main), improved instance type check.
 - Documentation structure reorganized (multiple passes consolidating guides, theme adjustments, layout evolution and subsequent refinements / reverts).
 
 ### Fixed
+
 - Removal of `resourceState` from activateCodeVersion request.
 
 ### Documentation
+
 - Large expansion of SFRA models, cartridge creation, ISML templates, decorators warnings, URL patterns, customer context, authentication flows, endpoint security guidance.
 
 ### Notes
+
 - Multiple rapid doc iterations (additions, reverts, restyles) before stabilization.
 
 ## [1.0.11] - 2025-08-15
+
 ### Added
+
 - SFCC development rules and SFRA controllers best practices guide.
 - AI interface instruction documentation.
 
 ### Changed
+
 - Refactored rule configurations; enhanced SFCC debugging workflows; streamlined documentation tools; removed improvement roadmap.
 
 ### Fixed
+
 - Log files now sorted by last modification for accurate recency ordering.
 
 ### Testing
+
 - Enhanced log client test coverage.
 
 ### Notes
+
 - Documentation emphasis on rule context explanation and operational clarity.
 
 ## [1.0.10] - 2025-08-15
+
 ### Added
+
 - Custom object attribute search capability.
 - Progressive development guide (subsequently refined) and job framework best practices.
 - Additional documentation: steptypes configuration, ISML templates, SCAPI custom endpoint guide, path parameter & search query usage clarifications, SFRA documentation support expansion.
 
 ### Changed
+
 - Auth examples refactored into appendix; logging improvements and build output cleanliness.
 
 ### Fixed
+
 - Reversal / clarification cycles for job framework status codes and default values (cleanup of earlier docs ambiguities).
 
 ### Notes
+
 - Foundation for expanded SCAPI / SFRA documentation just before rapid rule & controller additions in 1.0.11.
 
 ## [1.0.9-2] - 2025-08-13
+
 ### Changed
+
 - Enhanced release workflow (iteration on same-day release of 1.0.9).
 
 ## [1.0.9] - 2025-08-13
+
 ### Added
+
 - Initial modular handler & directory architecture groundwork: secure config loading, debug log support, documentation-only mode, system object exposure, site preferences & attribute search, OCAPI client integration.
 - CI workflow, caching layer for documentation, expanded class details, path resolver, pre-commit hooks, NPM publishing & Dependabot configuration, issue templates.
 
 ### Changed
+
 - Large-scale codebase reorganization (directory structure, authentication & logging refactors, configuration loading improvements, handler refactors, OAuth token management relocation, package metadata updates, JSON serialization, system object description refinements, server architecture refactor).
 - Log tool naming alignment & tool description clarity improvements.
 
 ### Fixed
+
 - File path security validation enhancements.
 
 ### Documentation
+
 - Extensive expansion: best practices (security, performance, cartridge creation), contributing guidelines, search tool description, quick setup, system object definitions, Copilot instructions, local dev focus clarification.
 
 ### Testing
+
 - Added Jest framework and early test coverage (config factory, OAuth token manager, log client, attribute definitions, best practices client).
 
 ### Notes
+
 - Represents the foundational public baseline preceding rapid feature layering in 1.0.10+.
 
 ## [1.0.8] - 2025-08-13
+
 ### Changed
+
 - Package version alignment & metadata updates; project structure and documentation improvements; Node version CI expansions.
 
 ### Added
+
 - Security & performance best practices guides, contributing guidelines, AI assistant integration guide, deprecation support, attribute definition search, site preferences search.
 
 ### Notes
+
 - Last pre-architecture refactor baseline before major handler and structural reorganization in 1.0.9.
 
 ## [1.0.2] - 2025-08-08
+
 ### Added
+
 - Debug logging capabilities, caching for documentation, expanded class details, initial SFCC MCP server feature set (system object & attribute tools, OCAPI integration, documentation retrieval).
 - Jest testing framework & initial unit tests.
 
 ### Changed
+
 - Centralized logging infrastructure; configuration logging & security tightening; authentication config refactors.
 
 ### Documentation
+
 - Cartridge creation guide, npx usage instructions, API docs, system object definitions resource.
 
 ### Notes
+
 - Early stabilization phase; intermediate patch releases between 1.0.2 and 1.0.8 consolidated here (internal iteration without tags not reconstructed individually).
 
 ## [1.0.0] - 2025-08-08
+
 ### Added
+
 - Initial commit introducing SFCC Dev MCP Server core (base server, tooling scaffolding, initial documentation framework).
 
 ### Notes
+
 - Foundation commit history includes scaffolding, early capability extensions, and initial architectural decisions.
 
 ---
@@ -260,6 +328,7 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
 ---
 
 ### Future
+
 - Add automation for changelog validation in CI (ensure categories & links present).
 - Add script to generate comparison links automatically when tagging.
 - Potential provenance notes for security-impacting changes (e.g., file path validation hardening).
@@ -267,6 +336,7 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
 ---
 
 ### Comparison Links
+
 [1.0.15]: https://github.com/taurgis/sfcc-dev-mcp/compare/v1.0.14...v1.0.15
 [1.0.14]: https://github.com/taurgis/sfcc-dev-mcp/compare/v1.0.13...v1.0.14
 [1.0.13]: https://github.com/taurgis/sfcc-dev-mcp/compare/v1.0.12...v1.0.13
@@ -278,4 +348,3 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
 [1.0.8]: https://github.com/taurgis/sfcc-dev-mcp/compare/v1.0.2...v1.0.8
 [1.0.2]: https://github.com/taurgis/sfcc-dev-mcp/compare/v1.0.0...v1.0.2
 [1.0.0]: https://github.com/taurgis/sfcc-dev-mcp/tree/v1.0.0
-

package/README.md

@@ -3,18 +3,20 @@
 [![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 best practices.
+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
-- **📚 Best Practices Guides** - Curated development guidelines for cartridges, hooks, controllers, client-side JavaScript, and more  
 - **🏗️ SFRA Documentation** - Enhanced access to Storefront Reference Architecture documentation
-- **� ISML Template Reference** - Complete ISML element documentation with examples and best practices
-- **�📊 Log Analysis Tools** - Real-time error monitoring, debugging, and job log analysis for SFCC instances
+- **🧱 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
-- **🚀 Cartridge Generation** - Automated cartridge structure creation
+- **🧪 Script Debugger** - Execute and inspect script-debugger endpoints in credentialed mode, including custom trigger URLs/paths for non-default storefront routes
+- **🚀 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
 
@@ -42,17 +44,25 @@ An AI-powered Model Context Protocol (MCP) server that provides comprehensive ac
 }
 ```
 
-Create a `dw.json` file with your SFCC credentials:
+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`
+- Optional storefront auth (for script debugger trigger on Basic-Auth storefronts): `storefrontUsername` + `storefrontPassword`
 ```json
 {
   "hostname": "your-instance.sandbox.us01.dx.commercecloud.salesforce.com",
   "username": "your-username",
-  "password": "your-password", 
+  "password": "your-password",
+  "storefrontUsername": "your-storefront-basic-user",
+  "storefrontPassword": "your-storefront-basic-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
@@ -74,7 +84,7 @@ The server discovers SFCC credentials in this order (highest priority first):
 |----------|--------|-------------|
 | **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) |
+| **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.
 
@@ -82,36 +92,47 @@ The server discovers SFCC credentials in this order (highest priority first):
 
 | Mode | Tools Available | SFCC Credentials Required |
 |------|----------------|---------------------------|
-| **Documentation-Only** | 21 tools | ❌ No |
-| **Full Mode** | 38 tools | ✅ Yes |
+| **Documentation-Only** | 18 tools | ❌ No |
+| **Full Mode** | 40 tools | ✅ Yes |
 
 ### Documentation-Only Mode
-Perfect for learning and development - no SFCC instance required:
+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)
 - ISML template documentation (5 tools)
-- Cartridge generation (1 tool)
-- Agent instruction bootstrap (1 tool) to copy/merge AGENTS.md and skills
+- 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 (21 tools)
-- Real-time log analysis (13 tools)
+- 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, category-based tool definitions (documentation, best practices, SFRA, ISML, logs, job logs, system objects, cartridge, code versions). Re-exported via `tool-definitions.ts`.
-- **Handlers** (`src/core/handlers/`): Each category has a handler extending a common base for timing, structured logging, and error normalization (e.g. `log-handler`, `docs-handler`, `isml-handler`, `system-object-handler`).
-- **Clients** (`src/clients/`): Encapsulate domain operations (OCAPI, SFRA docs, ISML docs, best practices, modular log analysis, cartridge generation). Handlers delegate to these so orchestration and computation remain separate.
+- **Tool Schemas** (`src/core/tool-schemas/`): Modular, category-based tool definitions (documentation, SFRA, ISML, logs, job logs, system objects, cartridge, code versions, agent instructions, script debugger). Re-exported via `tool-definitions.ts`.
+- **Server Orchestration Modules** (`src/core/server-tool-catalog.ts`, `src/core/server-tool-call-lifecycle.ts`, `src/core/server-workspace-discovery.ts`): Keeps `server.ts` focused by extracting capability-aware tool catalog logic, `tools/call` lifecycle (progress/cancellation/preflight), and workspace roots reconfiguration flow.
+- **Tool Argument Validator** (`src/core/tool-argument-validator.ts`): Enforces runtime argument shape at the MCP boundary for all tools (required fields, primitive/object/array types, enum checks, integer/numeric ranges, string patterns/length, and strict unknown-key checks for object schemas at top-level and nested levels) before tool dispatch.
+- **OCAPI Query Coverage** (`src/core/tool-schemas/shared-schemas.ts`): Shared search schemas include `text_query`, `term_query`, `bool_query`, `filtered_query`, and `match_all_query` so MCP boundary validation aligns with supported OCAPI query patterns.
+- **Handlers** (`src/core/handlers/`): Each category has a handler extending a common base for timing, structured logging, and error normalization, with config-driven wiring via `ConfiguredClientHandler` to reduce repetitive boilerplate (e.g. `log-handler`, `docs-handler`, `isml-handler`, `system-object-handler`).
+- **Clients** (`src/clients/`): Encapsulate domain operations (OCAPI, SFRA docs, ISML docs, modular log analysis, script debugger, cartridge generation, agent-instruction sync). 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).
+- **Shared Credential Validation** (`src/config/credential-validation.ts`): Centralizes auth-pair completeness and hostname-format validation for both `dw.json` loading and runtime configuration creation.
+- **Call-time Capability Guarding** (`src/core/server.ts`): Rejects execution of tools that are unavailable in the current mode, so hidden tools are not callable via direct `tools/call` requests.
+- **Call Lifecycle Signals** (`src/core/server.ts`): `tools/call` handling supports cancellation via request abort signals and emits best-effort progress notifications when the caller provides `_meta.progressToken`.
+- **Tool Error Sanitization** (`src/core/tool-error-response.ts`): Sanitizes upstream execution errors before returning MCP tool responses, reducing accidental leakage of backend payload details.
+- **Runtime WebDAV Verification** (`src/core/server.ts`): For OAuth-only configurations (`client-id`/`client-secret` without `username`/`password`), log/job-log/script-debugger tool exposure is gated by a one-time WebDAV capability probe to avoid false-positive tool availability.
+- **CLI Option Helpers** (`src/config/cli-options.ts`): Centralizes command-line parsing and environment credential detection for predictable startup behavior.
+- **Shared Path Security Policy** (`src/config/path-security-policy.ts`): Reuses allow/block path rules across workspace-root discovery and secure `dw.json` loading.
+- **Shared Abort Utility** (`src/utils/abort-utils.ts`): Centralized timeout and abort-signal composition used by HTTP and debugger clients for consistent cancellation semantics and timer cleanup.
 
 ### Why This Matters
 - **Extensibility**: Adding a new tool usually means adding a schema + minimal handler logic (or a new handler if a new domain).
@@ -137,9 +158,9 @@ Choose your preferred AI assistant:
 
 | Interface | Best For | Setup Guide |
 |-----------|----------|-------------|
-| **Claude Desktop** | Multi-turn conversations, debugging | [📖 Setup Guide](https://taurgis.github.io/sfcc-dev-mcp/ai-interfaces#claude-desktop) |
-| **GitHub Copilot** | VS Code integration, inline suggestions | [📖 Setup Guide](https://taurgis.github.io/sfcc-dev-mcp/ai-interfaces#github-copilot) |
-| **Cursor** | Modern AI-powered editor | [📖 Setup Guide](https://taurgis.github.io/sfcc-dev-mcp/ai-interfaces#cursor) |
+| **Claude Desktop** | Multi-turn conversations, debugging | [📖 Setup Guide](https://sfcc-mcp-dev.rhino-inquisitor.com/guide/ai-interfaces/) |
+| **GitHub Copilot** | VS Code integration, inline suggestions | [📖 Setup Guide](https://sfcc-mcp-dev.rhino-inquisitor.com/guide/ai-interfaces/) |
+| **Cursor** | Modern AI-powered editor | [📖 Setup Guide](https://sfcc-mcp-dev.rhino-inquisitor.com/guide/ai-interfaces/) |
 
 ## 📦 Installation
 
@@ -170,6 +191,8 @@ npx -y sfcc-dev-mcp --debug
 npx -y sfcc-dev-mcp --dw-json /path/to/your/dw.json --debug
 ```
 
+`--debug` accepts `true/false`, `1/0`, or `yes/no`. Invalid values fail fast with a clear error message.
+
 ### Log File Locations
 
 The server writes logs to your system's temporary directory:
@@ -188,20 +211,67 @@ The server writes logs to your system's temporary directory:
 ```javascript
 // The exact path varies by system - to find yours:
 node -e "console.log(require('os').tmpdir() + '/sfcc-mcp-logs')"
+```
+
+## 🧪 Release Flow (Maintainers)
+
+This repository now uses Changesets for npm releases.
+
+When a change should ship in a new `sfcc-dev-mcp` version, add a changeset from the repository root:
+
+```bash
+npm run changeset
+```
+
+Check pending release state against `main` before merging:
+
+```bash
+npm run release:status
+```
+
+The release workflow on `main` creates or updates a release pull request from pending changesets. Merging that release pull request publishes the npm package through npm trusted publishing (GitHub Actions OIDC), waits for npm propagation, reruns MCP tests against the published NPX artifact, and then publishes the same version to the MCP Registry.
+
+`npm run version-packages` also syncs `server.json` with the package version so `validate:server-json` keeps passing in the release PR.
+
+Package publication now uses GitHub Actions OIDC trusted publishing, so no separate npm publish secret is required.
+
+You can run the same validation locally:
+
+```bash
+# Ensure docs-site tool catalog stays in sync with runtime tool definitions
+npm run validate:tools-sync
+
+# Ensure docs-site skills catalog stays in sync with bundled skills
+npm run validate:skills-sync
+
+# Ensure MCP registry metadata stays in sync with package.json
+npm run validate:server-json
+
+# In a separate terminal, start the mock server first for full-mode MCP tests
+npm run test:mock-server:start
+
+# Uses latest published version by default
+npm run test:mcp:published-npx
+
+# Or pin a specific published version
+bash ./scripts/test-published-npx.sh 1.0.21
+```
+
+In GitHub Actions, the publish workflow manages the mock server lifecycle automatically.
 
 ## 📖 Documentation
 
-**📚 [Complete Documentation](https://taurgis.github.io/sfcc-dev-mcp/)** - Comprehensive guides and references
+**📚 [Complete Documentation](https://sfcc-mcp-dev.rhino-inquisitor.com/)** - Comprehensive guides and references
 
 Documentation source lives in `docs-site-v2/` (VitePress). The legacy React site remains in `docs-site/`.
 
 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
+- **[Getting Started](https://sfcc-mcp-dev.rhino-inquisitor.com/guide/)** - Installation and first-run setup
+- **[AI Interface Setup](https://sfcc-mcp-dev.rhino-inquisitor.com/guide/ai-interfaces/)** - Configure Claude Desktop, GitHub Copilot, or Cursor
+- **[Configuration Guide](https://sfcc-mcp-dev.rhino-inquisitor.com/guide/configuration/)** - SFCC credentials and Data API setup
+- **[Available Tools](https://sfcc-mcp-dev.rhino-inquisitor.com/tools/)** - Complete tool reference
+- **[Examples](https://sfcc-mcp-dev.rhino-inquisitor.com/examples/)** - Real-world usage patterns
+- **[Troubleshooting](https://sfcc-mcp-dev.rhino-inquisitor.com/troubleshooting/)** - Common issues and solutions
 
 ## 🛠️ Example AI Interactions
 
@@ -213,7 +283,7 @@ Quick Links:
 🤖 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
+🤖 Retrieves related SFCC classes and methods, then proposes a concrete hook implementation pattern
 ```
 
 ## 🔒 Security Notes
@@ -257,4 +327,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 **🚀 Ready to supercharge your SFCC development with AI?**
 
-**[📖 Get Started with the Full Documentation](https://taurgis.github.io/sfcc-dev-mcp/)**
+**[📖 Get Started with the Full Documentation](https://sfcc-mcp-dev.rhino-inquisitor.com/)**

package/dist/ai-instructions/skills/sfcc-script-evaluation/SKILL.md

@@ -27,6 +27,7 @@ The `evaluate_script` tool allows you to execute arbitrary JavaScript code on an
 | `timeout` | No | `30000` | Maximum execution time in milliseconds |
 | `breakpointFile` | No | Auto-detected | Custom controller path for breakpoint |
 | `breakpointLine` | No | `1,10,20,30,40,50` | Specific line for a single breakpoint; if omitted, strategic lines (1,10,20,30,40,50) are used |
+| `triggerUrl` | No | Auto-detected | Custom storefront URL or path to trigger; site-relative paths are resolved to `https://{hostname}/s/{siteId}/...` |
 
 ## Script Syntax Rules
 

package/dist/clients/agent-instructions-client.d.ts

@@ -52,6 +52,9 @@ export declare class AgentInstructionsClient {
     private resolveWorkspaceRoot;
     private resolveBasePath;
     private resolveSkillsTarget;
+    private getStatusSkillsCandidates;
+    private getDefaultSkillsCandidates;
+    private sanitizePreferredSkillsDir;
     private planAgentMerge;
     private planSkillCopy;
     private applyPlan;

package/dist/clients/agent-instructions-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-instructions-client.d.ts","sourceRoot":"","sources":["../../src/clients/agent-instructions-client.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAC1D,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,eAAe,EAAE,eAAe,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE;QACP,YAAY,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;QAChE,YAAY,EAAE,MAAM,EAAE,CAAC;QACvB,aAAa,EAAE,MAAM,EAAE,CAAC;KACzB,CAAC;IACF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAwB;IAC9D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,CAAC,EAAE,MAAM;IAOnE,SAAS,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAsC7D,gBAAgB,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAiFtE,OAAO,CAAC,oBAAoB;IAY5B,OAAO,CAAC,eAAe;YAmBT,mBAAmB;YAoBnB,cAAc;YAsBd,aAAa;YAqBb,SAAS;YAUT,WAAW;YAoBX,UAAU;YAUV,iBAAiB;YAcjB,mBAAmB;YAUnB,oBAAoB;YASpB,MAAM;YASN,WAAW;CAQ1B"}
+{"version":3,"file":"agent-instructions-client.d.ts","sourceRoot":"","sources":["../../src/clients/agent-instructions-client.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAiBrE,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAC1D,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,eAAe,EAAE,eAAe,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE;QACP,YAAY,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;QAChE,YAAY,EAAE,MAAM,EAAE,CAAC;QACvB,aAAa,EAAE,MAAM,EAAE,CAAC;KACzB,CAAC;IACF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAwB;IAC9D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,CAAC,EAAE,MAAM;IAOnE,SAAS,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAkC7D,gBAAgB,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAiFtE,OAAO,CAAC,oBAAoB;IAY5B,OAAO,CAAC,eAAe;YAmBT,mBAAmB;IAmBjC,OAAO,CAAC,yBAAyB;IAUjC,OAAO,CAAC,0BAA0B;IASlC,OAAO,CAAC,0BAA0B;YAapB,cAAc;YAsBd,aAAa;YAqBb,SAAS;YAUT,WAAW;YAoBX,UAAU;YAUV,iBAAiB;YAcjB,mBAAmB;YAUnB,oBAAoB;YASpB,MAAM;YASN,WAAW;CAQ1B"}