sfcc-dev-mcp 1.0.15 → 1.0.19

package/docs-site-v2/development/index.md

@@ -0,0 +1,151 @@
+---
+title: Development Guide
+description: Build, test, and contribute to SFCC Dev MCP with architecture notes, capability gating, and release workflow details.
+---
+
+# Development guide
+
+This project is a TypeScript MCP server with modular handlers and clients.
+
+## Prerequisites
+
+- Node.js 18+
+- npm 8+
+
+## Local setup
+
+```bash
+git clone https://github.com/taurgis/sfcc-dev-mcp.git
+cd sfcc-dev-mcp
+npm install
+npm run build
+npm test
+```
+
+## Run in dev mode
+
+```bash
+npm run dev -- --debug
+npm run dev -- --dw-json /path/to/dw.json --debug false
+```
+
+## Tests and lint
+
+```bash
+npm test
+npm run test:mcp:yaml
+npm run test:mcp:node
+npm run lint
+```
+
+## Architecture overview
+
+- `src/core`: server and tool registration
+- `src/clients`: domain clients for docs, logs, OCAPI, and scaffolding
+- `src/services`: file system and path services
+- `src/utils`: caching, validation, logging
+
+## Project architecture
+
+```text
+sfcc-dev-mcp/
+├── src/
+│   ├── main.ts                    # CLI entry point
+│   ├── index.ts                   # Package exports
+│   ├── core/                      # Core MCP server & tool definitions
+│   │   ├── server.ts              # MCP server (registers handlers, capability gating)
+│   │   ├── tool-definitions.ts    # All tool schemas grouped by category
+│   │   └── handlers/              # Modular tool handlers
+│   │       ├── base-handler.ts
+│   │       ├── docs-handler.ts
+│   │       ├── isml-handler.ts
+│   │       ├── sfra-handler.ts
+│   │       ├── log-handler.ts
+│   │       ├── job-log-handler.ts
+│   │       ├── system-object-handler.ts
+│   │       ├── code-version-handler.ts
+│   │       ├── cartridge-handler.ts
+│   │       └── agent-instructions-handler.ts
+│   ├── clients/                   # API & domain clients (logic, not routing)
+│   │   ├── base/                  # Shared HTTP + auth
+│   │   ├── logs/                  # Modular log system
+│   │   ├── docs/                  # Modular documentation system
+│   │   ├── docs-client.ts
+│   │   ├── sfra-client.ts
+│   │   ├── isml-client.ts
+│   │   ├── agent-instructions-client.ts
+│   │   ├── cartridge/
+│   │   ├── ocapi/
+│   │   ├── ocapi-client.ts
+│   │   ├── log-client.ts
+│   ├── services/                 # Dependency injection service layer
+│   ├── tool-configs/             # Tool grouping & category configs
+│   ├── config/                   # Configuration + dw.json loading
+│   ├── utils/                    # Caching, validation, logging
+│   └── types/
+├── tests/                        # Jest + MCP YAML + programmatic tests
+├── docs/                         # SFCC documentation sources
+├── docs-site/                    # Legacy React docs
+├── docs-site-v2/                 # VitePress docs
+├── scripts/                      # Conversion & build scripts
+└── ai-instructions/              # AI platform instruction sets + bundled skills
+```
+
+## Configuration and capability gating
+
+- `configuration-factory.ts`: derives capabilities (`canAccessLogs`, `canAccessJobLogs`, `canAccessOCAPI`, `canAccessSitePrefs`).
+- `dw-json-loader.ts`: secure credential ingestion and validation.
+- Capability gating rules:
+	- No credentials: docs-only tools (docs, SFRA, ISML, cartridge generation, agent instructions).
+	- WebDAV credentials: runtime logs + job logs.
+	- Data API credentials: system & custom objects, site preferences, code versions.
+- Tools requiring unavailable capabilities are not registered.
+
+## Adding a new tool
+
+1. Define the schema in the correct `src/core/tool-schemas/*` file.
+2. Implement or extend a handler under `src/core/handlers`.
+3. Add domain logic in a client under `src/clients`.
+4. Discover response shapes with `npx aegis query` before writing tests.
+5. Add unit tests and MCP YAML tests.
+6. Update AGENTS.md and README.md if tool counts or categories change.
+
+## Testing strategy
+
+- Unit tests: `npm test`
+- YAML MCP tests: `npm run test:mcp:yaml`
+- Programmatic MCP tests: `npm run test:mcp:node`
+- Lint: `npm run lint`
+
+## Documentation updates
+
+The VitePress site lives in `docs-site-v2/`. If you modify structure, update the navigation and related pages.
+
+## Release process
+
+```bash
+npm version patch
+git push origin main --tags
+```
+
+Checklist:
+
+- Update README.md and AGENTS.md if tool counts or categories change
+- Run `npm test` and `npm run lint:check`
+- Verify docs build in `docs-site-v2`
+
+## Contributing
+
+- Open an issue for large changes
+- Keep changes small and scoped
+- Add tests for new tools and update docs if behavior changes
+
+## Documentation site
+
+The VitePress site lives in `docs-site-v2/`.
+
+```bash
+cd docs-site-v2
+npm install
+npm run dev
+```

package/docs-site-v2/examples/index.md

@@ -0,0 +1,333 @@
+---
+title: Example Prompts
+description: Use tested SFCC Dev MCP prompt examples for docs lookup, log triage, system object analysis, and cartridge generation.
+---
+
+# Examples
+
+Short, focused prompts that map to common workflows. Each section shows a prompt, the typical tool calls, and the expected outcome.
+
+## Docs mode examples
+
+### Explore an SFCC class quickly
+
+Prompt:
+
+```
+Show me the most important methods on dw.catalog.Product for pricing and variation handling.
+```
+
+Typical tools:
+
+- `search_sfcc_classes`
+- `get_sfcc_class_info`
+
+Expected output:
+
+```markdown
+Focused summary of dw.catalog.Product with pricing, availability, and variation methods.
+```
+
+### Focused class exploration
+
+Prompt:
+
+```
+I need only price and availability related getters on dw.catalog.Product. No other methods.
+```
+
+Typical tools:
+
+- `get_sfcc_class_info` with `search` and `includeProperties=false`
+
+### SFRA lookup
+
+Prompt:
+
+```
+Find SFRA docs for middleware and summarize how to use it in a controller.
+```
+
+Typical tools:
+
+- `search_sfra_documentation`
+- `get_sfra_document`
+
+### Generate a controller from documentation context
+
+Prompt:
+
+```
+Using SFRA patterns, create a Product-Show controller that handles missing products, logs errors, and renders price and availability.
+```
+
+Typical tools:
+
+- `get_sfcc_class_info` (Product and PriceModel)
+- `get_sfra_document` (server)
+
+### Generate a cartridge
+
+Prompt:
+
+```
+Generate a cartridge named int_tracking with controller, hook, and service placeholders.
+```
+
+Typical tools:
+
+- `generate_cartridge_structure`
+
+Expected output:
+
+```text
+int_tracking/
+	cartridge/
+		controllers/
+		scripts/
+		templates/
+```
+
+### Scaffold a feature cartridge (with next steps)
+
+Prompt:
+
+```
+Generate a cartridge structure for a shipment tracking integration using hooks + a service layer and note follow-up tasks.
+```
+
+Typical tools:
+
+- `generate_cartridge_structure`
+- `sync_agent_instructions` (optional guidance)
+
+Expected output:
+
+```markdown
+Generated tree (excerpt):
+
+int_tracking/
+	cartridge/
+		controllers/Tracking.js
+		scripts/hooks/shipment.js
+		scripts/services/TrackingService.js
+		templates/default/tracking/trackingstatus.isml
+		static/default/js/tracking/
+
+Assistant adds next steps:
+1) Configure LocalServiceRegistry service: tracking.api
+2) Implement hooks: updateShippingInfo, exportStatus
+3) Add ISML partial to PDP for shipment ETA
+4) Add logging category: TrackingIntegration
+5) Write integration test harness for mocked API responses
+```
+
+## Full mode examples
+
+### Log triage
+
+Prompt:
+
+```
+Summarize errors from the last day and call out the most common patterns.
+```
+
+Typical tools:
+
+- `summarize_logs`
+- `get_latest_error`
+- `search_logs`
+
+Expected output:
+
+```markdown
+1) summarize_logs → Errors: 0, Warnings: 27 (no error file today)
+2) search_logs (pattern=cookie_hint, level=warn) → repeated offline content asset warnings
+
+Assessment:
+- Warning noise masks future issues; no payment/auth errors detected.
+
+Recommended actions:
+- Restore or remove cookie_hint asset, or gate include by site preference.
+- Re-run summarize_logs after remediation to confirm warning reduction.
+```
+
+### Job log analysis
+
+Prompt:
+
+```
+Analyze the latest ProductFeed job log and summarize failures and slow steps.
+```
+
+Typical tools:
+
+- `search_job_logs_by_name`
+- `get_job_log_entries`
+- `get_job_execution_summary`
+
+Expected output:
+
+```markdown
+Flow:
+1) search_job_logs_by_name → confirm job log filenames
+2) get_job_log_entries (limit 50) → capture recent step activity
+3) get_job_execution_summary → aggregate timings and status
+
+Findings:
+- Duration +18% vs rolling average
+- EXPORT step shows retries (socket timeouts)
+
+Recommendations:
+- Reduce batch size and add exponential backoff with jitter
+- Track step_duration_ms and retry_count metrics
+```
+
+### Script evaluation
+
+Prompt:
+
+```
+Check if product 25518704M exists and return name plus current price.
+```
+
+Typical tools:
+
+- `evaluate_script`
+
+Example script:
+
+```javascript
+(function() {
+	var ProductMgr = require('dw/catalog/ProductMgr');
+	var p = ProductMgr.getProduct('25518704M');
+	if (!p) return 'Not found';
+	return JSON.stringify({ id: p.ID, name: p.name, price: p.getPriceModel().getPrice().value });
+})()
+```
+
+### System object attributes
+
+Prompt:
+
+```
+List custom Product attributes that impact pricing or display and show access examples.
+```
+
+Typical tools:
+
+- `search_system_object_attribute_definitions`
+
+Expected output:
+
+```markdown
+Curated Product attributes (custom only):
+- brandDisplayName (Disp) → p.custom.brandDisplayName
+- shippingClass (Ship) → p.custom.shippingClass
+- careInstructions (Content) → p.custom.careInstructions
+
+Notes:
+- Excluded system attributes unless required for pricing/availability.
+- Provide access snippets for each custom attribute.
+```
+
+### Site preference search
+
+Prompt:
+
+```
+Find checkout site preferences related to tax and shipping.
+```
+
+Typical tools:
+
+- `search_site_preferences`
+
+Expected output:
+
+```markdown
+Group: checkout
+- enableTaxCalculation (boolean)
+- enableShippingMethodSelector (boolean)
+
+Usage:
+Site.current.getCustomPreferenceValue('enableTaxCalculation')
+```
+
+### Custom object attributes
+
+Prompt:
+
+```
+For custom object type Global_String, list searchable attributes and show a script access snippet.
+```
+
+Typical tools:
+
+- `search_custom_object_attribute_definitions`
+
+Expected output:
+
+```markdown
+Custom object type: Global_String
+- searchable: altValueMapping, sourceKey
+
+Script access:
+var CustomObjectMgr = require('dw/object/CustomObjectMgr');
+var co = CustomObjectMgr.getCustomObject('Global_String', key);
+var mapped = co && co.custom.altValueMapping;
+```
+
+### Micro job log triage
+
+Prompt:
+
+```
+Give me a 3-step health read for the nightly InventorySync job and only call tools you truly need.
+```
+
+Typical tools:
+
+- `search_job_logs_by_name`
+- `get_job_log_entries`
+- `get_job_execution_summary`
+
+Expected output:
+
+```markdown
+Outcome: SUCCESS (duration 2m14s, 0 errors, 3 warnings)
+Warnings:
+- 2x External API 429 backoffs (within threshold)
+- 1x Deprecated attribute reference
+
+Next actions (only if persistent):
+1) Track retry ratio vs baseline
+2) Replace deprecated attribute before Q4 freeze
+```
+
+## Prompt patterns
+
+Good prompts are specific about scope and expected output:
+
+- "Only include pricing-related methods."
+- "Use live logs before suggesting fixes."
+- "Provide the final code block only."
+
+Avoid prompts that are too broad:
+
+- "Explain everything about SFCC."
+- "Fix checkout." (no context)
+
+### Prompt refinement example
+
+Weak:
+
+```
+Help with product page.
+```
+
+Improved:
+
+```
+Generate an SFRA controller extension to enrich Product-Show with cached ATS and a badge if sustainabilityRating >= 3. Provide only changed code + the template snippet.
+```

package/docs-site-v2/features/index.md

@@ -0,0 +1,144 @@
+---
+title: Features Overview
+description: Explore SFCC Dev MCP capabilities including documentation tools, logs, system objects, cartridge generation, and AI instruction packs.
+---
+
+# Features
+
+The server provides a focused set of capabilities for local SFCC development. Use docs mode for reference and scaffolding, and full mode when you need live data.
+
+<Collapsible title="Cartridge generation" :open="true">
+
+- Generate a production-ready cartridge or full project scaffold
+- Standard structure: controllers, models, ISML, scripts, configs
+- Direct file creation in the target path
+
+Try asking:
+
+- "Generate a cartridge named int_tracking and show the created directories"
+- "What files does generate_cartridge_structure create in full project mode?"
+
+</Collapsible>
+
+<Collapsible title="Agent skills (instruction packs)">
+
+- Portable skills for SFRA, ISML, security, and performance
+- Install with `sync_agent_instructions`
+- Works with Copilot, Claude, and Cursor instruction systems
+
+Try asking:
+
+- "Install bundled agent instructions into my repo"
+- "List available SFCC skills and suggest one for OCAPI hooks"
+
+</Collapsible>
+
+<Collapsible title="SFCC API documentation">
+
+- Query the full `dw.*` namespace
+- Filter by methods, properties, or search terms
+- Retrieve raw docs or class details
+
+Try asking:
+
+- "What methods does dw.catalog.Product have for pricing?"
+- "Search SFCC classes related to inventory"
+
+</Collapsible>
+
+<Collapsible title="Enhanced SFRA documentation">
+
+- Core classes (server, request, response, querystring, render)
+- Model coverage across product, order, pricing, store, customer
+- Search and category filters
+
+Try asking:
+
+- "Search SFRA docs for middleware examples"
+- "List order-related SFRA documents and summarize each"
+
+</Collapsible>
+
+<Collapsible title="ISML template reference">
+
+- Full ISML element reference with syntax and attributes
+- Category browsing (control-flow, output, includes, scripting, cache)
+- Search across ISML elements
+
+Try asking:
+
+- "Show me how to use isloop with paging"
+- "What ISML elements are available for caching?"
+
+</Collapsible>
+
+<Collapsible title="Log and job log analysis (full mode)">
+
+- Latest error, warn, info, debug logs
+- Pattern search and daily summaries
+- Job log discovery and execution summaries
+
+Try asking:
+
+- "Show the latest 10 error log entries containing 'OCAPI'"
+- "Get the latest job execution summary for ProductFeedJob"
+
+</Collapsible>
+
+<Collapsible title="System and custom objects (full mode)">
+
+- List system object definitions and attribute groups
+- Search attribute definitions with filters
+- Search site preferences by group
+
+Try asking:
+
+- "List custom attributes for Product containing 'brand'"
+- "Search site preferences in the SEO group for description fields"
+
+</Collapsible>
+
+<Collapsible title="Code version management (full mode)">
+
+- List available code versions
+- Activate a version for deployment fixes
+
+Try asking:
+
+- "List code versions and highlight the active one"
+- "Activate code version int_release_2025_09"
+
+</Collapsible>
+
+<Collapsible title="Security and performance">
+
+- Credential handling and least-privilege guidance
+- Log access and path validation safeguards
+- Caching and range reads for efficient log access
+
+</Collapsible>
+
+<Collapsible title="AI integration">
+
+- Stable tool schemas for deterministic responses
+- Category grouping to keep prompts small
+- Skills and instruction packs to enforce patterns
+
+</Collapsible>
+
+## Modes at a glance
+
+| Capability | Docs mode | Full mode |
+| --- | --- | --- |
+| SFCC docs, SFRA docs, ISML docs | Yes | Yes |
+| Cartridge generation | Yes | Yes |
+| Agent instructions | Yes | Yes |
+| Logs and job logs | No | Yes |
+| System objects and site preferences | No | Yes |
+| Code versions | No | Yes |
+| Script debugger | No | Yes |
+
+## Next steps
+
+- Browse the [Tools catalog](/tools/)
+- Try the [Examples](/examples/)

package/docs-site-v2/guide/ai-interfaces.md

@@ -0,0 +1,58 @@
+---
+title: AI Interface Setup
+description: Set up SFCC Dev MCP in Copilot, Claude, and Cursor with docs-only and full-mode configuration examples.
+---
+
+# AI interface setup
+
+Use the same MCP server configuration across clients. The differences are mostly where you place the config file or instruction files.
+
+<Callout title="Auto-discovery" variant="success">
+If you open a workspace that contains a `dw.json` and your client supports MCP `roots/list`, the server discovers it automatically after initialization. Use docs mode first, then add credentials when you need full mode.
+</Callout>
+
+## Environment modes
+
+<ModeTabs />
+
+## Universal MCP configuration
+
+Docs-only mode:
+
+```json
+{
+  "mcpServers": {
+    "sfcc-dev": {
+      "command": "npx",
+      "args": ["sfcc-dev-mcp"]
+    }
+  }
+}
+```
+
+Full mode:
+
+```json
+{
+  "mcpServers": {
+    "sfcc-dev": {
+      "command": "npx",
+      "args": ["sfcc-dev-mcp", "--dw-json", "/path/to/dw.json", "--debug", "false"]
+    }
+  }
+}
+```
+
+## AI assistant setup
+
+<AssistantTabs />
+
+## Instruction files
+
+<InstructionFilesTabs />
+
+## Verification prompts
+
+- "Show methods on dw.catalog.Product for pricing"
+- "Summarize the latest error log entries"
+- "Generate a cartridge named int_example"