sfcc-dev-mcp 1.0.16 → 1.0.20

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

@@ -1,151 +0,0 @@
----
-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

@@ -1,333 +0,0 @@
----
-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

@@ -1,144 +0,0 @@
----
-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

@@ -1,58 +0,0 @@
----
-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"