SFCC Development MCP Server

# AGENTS.md – SFCC Development MCP Server (AI Coding Agent Instructions) This file provides authoritative, agent-focused operational guidelines. It complements `README.md` by documenting build/test workflows, architectural conventions, and maintenance rules that would clutter a human-facing introduction. Goals of `AGENTS.md`: - Give any AI coding agent (Copilot, Cursor, Claude, Gemini, Aider, Factory, Ona, Devin, Zed, etc.) a predictable place to load project instructions - Separate contributor onboarding (README) from deep operational detail (here) - Encourage portable, open, plain-Markdown instructions (no proprietary schema) Agent Operating Principles (Quick Commit Rules): 1. Verify reality first (counts, structures) with commands—never guess 2. Make surgical diffs—no drive‑by formatting or unrelated refactors 3. Validate after every substantive change (build + lint + relevant tests) 4. Prefer explicit, readable code & docs over clever abstractions 5. Surface ambiguity or risky instructions with safer alternatives 6. Keep `AGENTS.md` ↔ `README.md` in sync where they overlap (update both or neither) 7. Discover actual tool response formats with `npx aegis query` before writing tests 8. Treat security (credentials, paths, network) as a first‑class concern—assume local but protect anyway 9. Defer performance tuning unless a measurable issue exists; avoid premature micro‑optimizations 10. Fail loud & clear: actionable error messages, user vs system error distinction ## 🤖 Unified Engineering Principles & Persona Operate as a senior TypeScript / Node.js engineer with deep MCP + SFCC (OCAPI, SCAPI, WebDAV, logs, system objects, preferences) domain knowledge. Apply the following unified principles (consolidates former Persona, Professional Standards, Development Approach, and Development Guidelines): ### Core Competencies - MCP protocol compliance & tool schema rigor - SFCC integration breadth: logs, job logs, OCAPI auth, system objects, site preferences - Strong TypeScript typing, safe narrowing, interface-driven design - OAuth + token lifecycle correctness - Log & job execution analysis (parsing, summarization, health signals) - Documentation ingestion (scan → parse → resolve → extract types) - Multi-layer test strategy: Jest (unit) + Aegis YAML (declarative) + Node programmatic (stateful) ### Quality & Safety - Intentional, maintainable code; small reversible changes - Security first: never leak credentials, avoid accidental network exfiltration, sanitize paths - Explicit error modeling: distinguish user input errors vs system/internal failures - Deterministic + cache-aware logic; avoid hidden side effects - Respect local dev constraints—opt for lightweight operations ### Documentation Discipline - Update BOTH `AGENTS.md` & `README.md` for: tool count changes, new handlers, structural moves, added operating modes, configuration shifts - Quantify before asserting (grep / awk / find) – no hand-waved counts - Keep architectural diagrams & tool categories consistent with `src/core/tool-definitions.ts` ### Testing Strategy - Always discover response shapes with `npx aegis query` before writing tests (see `.github/skills/mcp-yaml-testing/` for detailed workflow) - Unit tests (Jest): core utilities, parsing, validation, token & client logic - YAML tests (Aegis): broad tool surface, schema validation (see `.github/skills/mcp-yaml-testing/`) - Programmatic tests (Node): multi-step flows, stateful sequences (see `.github/skills/mcp-programmatic-testing/`) - Performance assertions: CI‑tolerant (<500ms typical) – correctness first ### Implementation Workflow 1. Define or adjust tool schema (if new) in `core/tool-definitions.ts` 2. Implement / extend handler (or add new) with clear separation of concerns 3. Add / update clients & services with DI-friendly patterns (`ClientFactory` + interfaces) 4. Run targeted Aegis discovery (success + edge) to capture real output 5. Write/adjust tests (unit + YAML/programmatic where appropriate) 6. Verify counts & update docs (both files) atomically 7. Run lint + tests; address failures before further edits 8. Commit with concise, scope-focused message ### Performance & Stability - Optimize only after measuring; instrument where ambiguity exists - Use caching deliberately; document invalidation triggers - Keep handler execution time predictable; stream or range-read logs where possible ### When In Doubt - Pause and gather empirical data - Prefer minimal, additive change over speculative refactor - Escalate ambiguity via explicit options rather than guessing --- ## 📋 Project Overview The **SFCC Development MCP Server** is a **local development** Model Context Protocol server that provides AI agents with comprehensive access to Salesforce B2C Commerce Cloud development tools and resources. This project bridges the gap between AI assistants and SFCC development workflows **for individual developers working on their local machines**. ### 🎯 Project Goals 1. **Enable AI-Assisted SFCC Development**: Provide AI agents with real-time access to SFCC documentation, logs, and system objects **during local development** 2. **Reduce Development Time**: Eliminate the need to manually search through documentation or logs **while coding** 3. **Improve Code Quality**: Provide access to current best practices and development guidelines **for personal projects** 4. **Enhance Local Debugging**: Offer real-time log analysis and error investigation tools **for developer sandbox instances** 5. **Support Multiple Use Cases**: Work in both documentation-only and full-credential modes **for different development scenarios** ### 🏗️ Project Structure ``` sfcc-dev-mcp/ ├── src/ # Core TypeScript source code │ ├── main.ts # CLI entry point and argument parsing │ ├── index.ts # Package exports and compatibility │ ├── core/ # Core MCP server functionality │ │ ├── server.ts # Main MCP server implementation │ │ ├── tool-definitions.ts # Re-exports tool schemas from modular files │ │ ├── tool-schemas/ # Modular tool schema definitions │ │ │ ├── index.ts # Aggregates and re-exports all tool schemas │ │ │ ├── shared-schemas.ts # Reusable schema components (query, pagination, etc.) │ │ │ ├── documentation-tools.ts # SFCC documentation tools (5 tools) │ │ │ ├── best-practices-tools.ts # Best practices tools (4 tools) │ │ │ ├── sfra-tools.ts # SFRA documentation tools (5 tools) │ │ │ ├── isml-tools.ts # ISML documentation tools (5 tools) │ │ │ ├── log-tools.ts # Log + Job log tools (8 + 5 tools) │ │ │ ├── system-object-tools.ts # System object tools (6 tools) │ │ │ ├── cartridge-tools.ts # Cartridge generation tools (1 tool) │ │ │ └── code-version-tools.ts # Code version tools (2 tools) │ │ └── handlers/ # Modular tool handlers │ │ ├── base-handler.ts # Abstract base handler with common functionality │ │ ├── abstract-client-handler.ts # Abstract handler for client-based tools │ │ ├── simple-client-handler.ts # Simple handler for single-client tools │ │ ├── client-factory.ts # Centralized client creation with dependency injection │ │ ├── validation-helpers.ts # Common validation utilities for handlers │ │ ├── docs-handler.ts # SFCC documentation tool handler │ │ ├── best-practices-handler.ts # Best practices tool handler │ │ ├── sfra-handler.ts # SFRA documentation tool handler │ │ ├── isml-handler.ts # ISML documentation tool handler │ │ ├── log-handler.ts # Log analysis tool handler │ │ ├── job-log-handler.ts # Job log analysis tool handler │ │ ├── system-object-handler.ts # System object tool handler │ │ ├── code-version-handler.ts # Code version tool handler │ │ └── cartridge-handler.ts # Cartridge generation tool handler │ ├── clients/ # API clients for different services │ │ ├── base/ # Base client classes and shared functionality │ │ │ ├── http-client.ts # Base HTTP client with authentication │ │ │ ├── ocapi-auth-client.ts # OCAPI OAuth authentication client │ │ │ └── oauth-token.ts # OAuth token management for OCAPI │ │ ├── ocapi/ # Specialized OCAPI clients │ │ │ ├── site-preferences-client.ts # Site preferences management │ │ │ └── system-objects-client.ts # System object definitions │ │ ├── logs/ # Modular log analysis system │ │ │ ├── log-client.ts # Main log client orchestrator │ │ │ ├── webdav-client-manager.ts # WebDAV setup & authentication │ │ │ ├── log-file-reader.ts # File reading with range requests │ │ │ ├── log-file-discovery.ts # File listing & filtering │ │ │ ├── log-processor.ts # Log parsing & entry processing │ │ │ ├── log-analyzer.ts # Analysis & summarization │ │ │ ├── log-formatter.ts # Output formatting │ │ │ ├── log-constants.ts # Constants & configuration │ │ │ ├── log-types.ts # TypeScript interfaces │ │ │ └── index.ts # Module exports │ │ ├── docs/ # Modular SFCC documentation system │ │ │ ├── documentation-scanner.ts # Documentation file discovery and class listing │ │ │ ├── class-content-parser.ts # Markdown parsing and content extraction │ │ │ ├── class-name-resolver.ts # Class name normalization and resolution │ │ │ ├── referenced-types-extractor.ts # Type extraction from documentation content │ │ │ └── index.ts # Module exports │ │ ├── cartridge/ # Cartridge generation system │ │ │ ├── cartridge-generation-client.ts # Main cartridge structure generator │ │ │ ├── cartridge-structure.ts # Directory structure definitions │ │ │ ├── cartridge-templates.ts # File content templates │ │ │ └── index.ts # Module exports │ │ ├── log-client.ts # Log client compatibility wrapper │ │ ├── docs-client.ts # SFCC documentation client orchestrator │ │ ├── sfra-client.ts # SFRA documentation client │ │ ├── isml-client.ts # ISML element documentation client │ │ ├── ocapi-client.ts # Main OCAPI client coordinator │ │ └── best-practices-client.ts # Best practices guide client │ ├── services/ # Service layer with clean abstractions │ │ ├── index.ts # Service exports and type definitions │ │ ├── file-system-service.ts # File system operations service │ │ └── path-service.ts # Path manipulation service │ ├── config/ # Configuration management │ │ ├── configuration-factory.ts # Config factory for different modes │ │ └── dw-json-loader.ts # dw.json configuration loader │ ├── constants/ # Application constants │ │ ├── index.ts # Constants exports │ │ └── best-practices-guides.ts # Best practices guide definitions │ ├── tool-configs/ # Tool configuration definitions │ │ ├── best-practices-tool-config.ts # Best practices tools configuration │ │ ├── cartridge-tool-config.ts # Cartridge generation tools configuration │ │ ├── code-version-tool-config.ts # Code version tools configuration │ │ ├── docs-tool-config.ts # Documentation tools configuration │ │ ├── job-log-tool-config.ts # Job log tools configuration │ │ ├── log-tool-config.ts # Log analysis tools configuration │ │ ├── sfra-tool-config.ts # SFRA documentation tools configuration │ │ └── system-object-tool-config.ts # System object tools configuration │ ├── utils/ # Utility functions and helpers │ │ ├── cache.ts # Caching layer for API responses │ │ ├── logger.ts # Structured logging system │ │ ├── utils.ts # Common utility functions │ │ ├── validator.ts # Input validation utilities │ │ ├── query-builder.ts # Query string building utilities │ │ └── path-resolver.ts # File path resolution utilities │ └── types/ # TypeScript type definitions │ └── types.ts # Comprehensive type definitions ├── docs/ # SFCC documentation and guides │ ├── best-practices/ # Development best practice guides │ │ ├── cartridge_creation.md │ │ ├── isml_templates.md │ │ ├── job_framework.md │ │ ├── localserviceregistry.md # LocalServiceRegistry integration patterns │ │ ├── ocapi_hooks.md │ │ ├── scapi_hooks.md │ │ ├── sfra_controllers.md │ │ ├── sfra_models.md # SFRA models best practices │ │ ├── sfra_client_side_js.md # SFRA client-side JavaScript patterns │ │ ├── sfra_scss.md # SFRA SCSS override and theming guidance │ │ ├── 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 │ ├── dw_system/ # SFCC System API documentation │ └── [other dw_* namespaces] # Complete SFCC API documentation ├── docs-site/ # React documentation website │ ├── App.tsx # Main React application component │ ├── main.tsx # React application entry point │ ├── index.html # HTML template with SEO and structured data │ ├── constants.tsx # Application constants and configuration │ ├── metadata.json # Site metadata configuration │ ├── types.ts # TypeScript type definitions │ ├── package.json # Node.js dependencies and scripts │ ├── vite.config.ts # Vite build configuration │ ├── tailwind.config.js # Tailwind CSS configuration │ ├── postcss.config.js # PostCSS configuration │ ├── tsconfig.json # TypeScript configuration │ ├── README.md # Documentation site specific README │ ├── components/ # Reusable React components │ │ ├── Badge.tsx # Badge component for status/categories │ │ ├── CodeBlock.tsx # Syntax highlighted code blocks │ │ ├── Collapsible.tsx # Collapsible content sections │ │ ├── ConfigBuilder.tsx # Configuration builder component │ │ ├── ConfigHero.tsx # Configuration page hero section │ │ ├── ConfigModeTabs.tsx # Configuration mode tab switcher │ │ ├── Layout.tsx # Main layout wrapper component │ │ ├── NewcomerCTA.tsx # Call-to-action for new users │ │ ├── NextStepsStrip.tsx # Next steps guidance component │ │ ├── OnThisPage.tsx # Table of contents component │ │ ├── Search.tsx # Search functionality component │ │ ├── Sidebar.tsx # Site navigation sidebar │ │ ├── ToolCard.tsx # Tool display card component │ │ ├── ToolFilters.tsx # Tool filtering controls │ │ ├── Typography.tsx # Typography components (H1, H2, etc.) │ │ ├── VersionBadge.tsx # Version display badge │ │ └── icons.tsx # Icon components library │ ├── pages/ # Page components for routing │ │ ├── HomePage.tsx # Homepage with quick start guide │ │ ├── AIInterfacesPage.tsx # AI interface setup guides │ │ ├── ConfigurationPage.tsx # Configuration documentation │ │ ├── DevelopmentPage.tsx # Development guidelines │ │ ├── ExamplesPage.tsx # Usage examples │ │ ├── FeaturesPage.tsx # Feature documentation │ │ ├── SecurityPage.tsx # Security considerations │ │ ├── ToolsPage.tsx # Available tools documentation │ │ └── TroubleshootingPage.tsx # Troubleshooting guide │ ├── src/ # Source assets and generated files │ │ ├── generated-search-index.ts # Generated search index │ │ └── styles/ # CSS and styling files │ ├── utils/ # Utility functions │ │ ├── search.ts # Search functionality utilities │ │ └── toolsData.ts # Tools data management │ ├── scripts/ # Build and utility scripts │ │ ├── generate-search-index.js # Search index generation script │ │ ├── generate-sitemap.js # Sitemap generation script │ │ └── search-dev.js # Development search utilities │ ├── public/ # Static assets │ │ ├── 404.html # Custom 404 error page │ │ ├── robots.txt # Search engine crawling instructions │ │ ├── sitemap.xml # Site map for search engines │ │ ├── llms.txt # LLM-specific instructions │ │ ├── favicon.ico # Website favicon │ │ ├── favicon-16x16.png # 16x16 favicon variant │ │ ├── favicon-32x32.png # 32x32 favicon variant │ │ ├── apple-touch-icon.png # Apple touch icon │ │ ├── android-chrome-192x192.png # Android Chrome icon 192x192 │ │ ├── android-chrome-512x512.png # Android Chrome icon 512x512 │ │ ├── site.webmanifest # Web app manifest │ │ ├── index.css # Global CSS styles │ │ ├── explain-product-pricing-methods.png # Demo screenshot with MCP │ │ └── explain-product-pricing-methods-no-mcp.png # Demo screenshot without MCP │ ├── dist/ # Built website output (Vite build) │ └── node_modules/ # Node.js dependencies ├── docs-site-v2/ # VitePress documentation website │ ├── .vitepress/ # VitePress config and theme │ ├── guide/ # Getting started and configuration │ ├── features/ # Feature overview │ ├── tools/ # Tools catalog │ ├── examples/ # Prompt examples │ ├── script-debugger/ # Script debugger guide │ ├── skills/ # Agent skills guide │ ├── security/ # Security and privacy notes │ ├── development/ # Development guide │ ├── troubleshooting/ # Troubleshooting guide │ ├── public/ # Static assets │ └── package.json # VitePress scripts and dependencies ├── ai-instructions/ # AI instruction files for different platforms │ ├── claude-desktop/ # Claude Desktop specific instructions │ │ └── claude_custom_instructions.md │ ├── cursor/ # Cursor editor specific instructions │ └── github-copilot/ # GitHub Copilot specific instructions │ └── copilot-instructions.md ├── tests/ # Comprehensive test suite │ ├── __mocks__/ # Mock implementations for testing │ │ └── src/ # Source code mocks │ ├── mcp/ # MCP-specific testing tools │ │ ├── node/ # Programmatic JavaScript/TypeScript testing │ │ ├── yaml/ # YAML-based declarative testing │ │ └── test-fixtures/ # Test fixtures and sample data │ ├── servers/ # Test server implementations │ │ └── webdav/ # WebDAV server mocks │ ├── *.test.ts # Individual test files for components │ └── [various test files] # Unit and integration tests ├── scripts/ # Build and documentation scripts └── package.json # Node.js package configuration ``` ### 🔧 Key Components #### **MCP Server Core** (`core/server.ts`) - Implements the Model Context Protocol specification - Handles tool registration and request routing - Manages configuration modes (documentation-only vs. full) - Provides error handling and response formatting - Orchestrates modular tool handlers for different functionality areas - Issues a one-time advisory when AGENTS.md/skills are missing, pointing clients to the installer tool #### **Tool Handler Architecture** (`core/handlers/`) - **BaseToolHandler** (`base-handler.ts`): Abstract base class providing common handler functionality, standardized response formatting, execution timing, and error handling patterns - **AbstractClientHandler** (`abstract-client-handler.ts`): Abstract handler for tools that require client instantiation - **SimpleClientHandler** (`simple-client-handler.ts`): Simplified handler for single-client tools with less boilerplate - **ClientFactory** (`client-factory.ts`): Centralized client creation with dependency injection support for testing and clean architecture - **ValidationHelpers** (`validation-helpers.ts`): Common validation utilities shared across all handlers - **DocsToolHandler** (`docs-handler.ts`): Handles SFCC documentation tools including class information, method search, and API discovery - **BestPracticesToolHandler** (`best-practices-handler.ts`): Manages best practice guides, security recommendations, and hook reference tables - **SFRAToolHandler** (`sfra-handler.ts`): Processes SFRA documentation requests with dynamic discovery and smart categorization - **ISMLToolHandler** (`isml-handler.ts`): Handles ISML element documentation, search, and category browsing - **LogToolHandler** (`log-handler.ts`): Handles real-time log analysis, error monitoring, and system health summarization - **JobLogToolHandler** (`job-log-handler.ts`): Handles job log analysis, debugging, and execution summaries - **SystemObjectToolHandler** (`system-object-handler.ts`): Manages system object definitions, custom attributes, and site preferences - **CodeVersionToolHandler** (`code-version-handler.ts`): Handles code version listing, activation, and deployment management - **CartridgeToolHandler** (`cartridge-handler.ts`): Processes cartridge generation requests with complete project setup using dependency injection - **AgentInstructionsToolHandler** (`agent-instructions-handler.ts`): Installs or merges bundled AGENTS.md and skills into workspaces, user home, or temp directories #### **Client Architecture** ##### **Base Client Infrastructure** (`clients/base/`) - **BaseHttpClient** (`http-client.ts`): Abstract base class providing HTTP operations, authentication handling, and error recovery - **OCAPIAuthClient** (`ocapi-auth-client.ts`): OCAPI-specific OAuth authentication with token management and automatic renewal - **TokenManager** (`oauth-token.ts`): Singleton OAuth token manager for SFCC OCAPI authentication with automatic expiration handling ##### **Specialized OCAPI Clients** (`clients/ocapi/`) - **OCAPISitePreferencesClient** (`site-preferences-client.ts`): Manages site preference searches and configuration discovery - **OCAPISystemObjectsClient** (`system-objects-client.ts`): Provides system object definitions, attribute schemas, and custom object exploration ##### **Modular Log Analysis System** (`clients/logs/`) - **SFCCLogClient** (`log-client.ts`): Main orchestrator that composes specialized log modules for comprehensive log analysis including job logs from deeper folder structures - **WebDAVClientManager** (`webdav-client-manager.ts`): WebDAV authentication and client setup with OAuth and basic auth support - **LogFileReader** (`log-file-reader.ts`): File reading with range request optimization (200KB tail reading) and comprehensive fallback mechanisms - **LogFileDiscovery** (`log-file-discovery.ts`): File listing, filtering by date/level, metadata operations, chronological sorting, and job log discovery from `/Logs/jobs/[job name ID]/` folder structure - **LogProcessor** (`log-processor.ts`): Log parsing, entry extraction, data manipulation, pattern processing, and job log processing (handles all log levels in single files) - **LogAnalyzer** (`log-analyzer.ts`): Advanced analysis including pattern detection, health scoring, trend analysis, and recommendation generation - **LogFormatter** (`log-formatter.ts`): Output formatting, presentation logic, user-friendly message templates, and job execution summaries - **LogConstants** (`log-constants.ts`): Centralized constants, configuration values, message templates, and job log patterns - **LogTypes** (`log-types.ts`): Comprehensive TypeScript interfaces for all log operations including job log types ##### **Modular SFCC Documentation System** (`clients/docs/`) - **DocumentationScanner** (`documentation-scanner.ts`): File discovery and class listing across all SFCC namespaces, scanning Markdown documentation files and building comprehensive class inventories - **ClassContentParser** (`class-content-parser.ts`): Markdown parsing and content extraction, processing class documentation to extract methods, properties, constants, and inheritance information - **ClassNameResolver** (`class-name-resolver.ts`): Class name normalization and resolution, handling various naming patterns and ensuring consistent class identification across the documentation system - **ReferencedTypesExtractor** (`referenced-types-extractor.ts`): Type extraction from documentation content with circular reference protection, identifying SFCC types used in method signatures and class relationships ##### **Service Clients** (`clients/`) - **DocsClient** (`docs-client.ts`): Main orchestrator for SFCC documentation processing that coordinates specialized modules for documentation scanning, content parsing, class name resolution, and type extraction across all namespaces - **LogClient** (`log-client.ts`): Backward compatibility wrapper that re-exports the modular log system - **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 - **ISMLClient** (`isml-client.ts`): Provides ISML element documentation, category-based browsing, and search functionality for template development - **OCAPIClient** (`ocapi-client.ts`): Main OCAPI coordinator that orchestrates specialized clients and provides unified interface - **BestPracticesClient** (`best-practices-client.ts`): Serves curated development guides including cartridge creation, ISML templates with security and performance guidelines, job framework development, LocalServiceRegistry service integrations with OAuth patterns and reusable module design, OCAPI/SCAPI hooks, SFRA controllers, SFRA models with JSON object layer design and architecture patterns, SFRA client-side JavaScript architecture (AJAX flows, validation, accessibility), custom endpoints, security recommendations, and performance optimization strategies with hook reference tables - **AgentInstructionsClient** (`agent-instructions-client.ts`): Plans and installs bundled AI assets (AGENTS.md + skills) into workspaces, user home, or temp directories with merge strategies and missing-only copy support ##### **Cartridge Generation** (`clients/cartridge/`) - **CartridgeGenerationClient** (`cartridge-generation-client.ts`): Generates complete cartridge structures with clean dependency injection for file system and path operations - **CartridgeStructure** (`cartridge-structure.ts`): Defines standard SFCC cartridge directory structure - **CartridgeTemplates** (`cartridge-templates.ts`): Contains file templates for controllers, models, scripts, and configurations #### **Configuration Management** (`config/`) - **Configuration Factory** (`configuration-factory.ts`): Creates configurations for different modes - **Config Loader** (`dw-json-loader.ts`): Handles dw.json and environment variable loading #### **Service Layer** (`services/`) - **Service Interfaces** (`index.ts`): Exports clean abstractions for system operations (IFileSystemService, IPathService) - **FileSystemService** (`file-system-service.ts`): Production implementation of file system operations with Node.js fs module - **PathService** (`path-service.ts`): Production implementation of path manipulation with Node.js path module - **Mock Services**: Test implementations providing controlled behavior for unit testing without real file system access #### **Utilities** (`utils/`) - **Caching System** (`cache.ts`): Efficient caching for API responses and documentation - **Logging** (`logger.ts`): Structured logging with debug capabilities - **Path Resolution** (`path-resolver.ts`): Secure file path handling - **Common Utilities** (`utils.ts`): Shared utility functions #### **Tool Categories** 1. **SFCC Documentation Tools** (5 tools) - Class information and method documentation - API search and discovery - Complete SFCC namespace coverage 2. **Best Practices Guides** (4 tools) - Curated development guidelines - Security and performance recommendations - SFRA client-side JavaScript architecture (AJAX, validation, accessibility) - Hook reference tables and examples 3. **Enhanced SFRA Documentation Tools** (5 tools) - **Dynamic Discovery**: Automatically finds all 26+ SFRA documents including core classes, extensive model documentation - **Smart Categorization**: Organizes documents into 7 logical categories (core, product, order, customer, pricing, store, other) - **Advanced Search**: Relevance-scored search across all documents with context highlighting - **Category Filtering**: Explore documents by functional areas for efficient discovery - **Complete Coverage**: Core SFRA classes (Server, Request, Response, QueryString, render) plus comprehensive model documentation (account, cart, products, pricing, billing, shipping, store, customer management, totals, categories, content, locale, addresses, and more) 4. **ISML Documentation Tools** (5 tools) - Complete ISML element reference and documentation - Control flow elements (isif, isloop, isnext, etc.) - Output formatting (isprint) and includes (isinclude, iscomponent, isslot) - Scripting elements (isscript, isset) and caching (iscache) - Category-based browsing and advanced search capabilities 5. **Cartridge Generation Tools** (1 tool) - Automated cartridge structure creation with direct file generation - Complete project setup with all necessary configuration files - Proper directory organization and file structure 6. **Log Analysis Tools** (8 tools) - Real-time error monitoring - Log search and pattern matching - System health summarization 7. **Job Log Tools** (5 tools) - Job log analysis and debugging - Job execution summaries - Custom job step monitoring 8. **System Object Tools** (6 tools) - Custom attribute discovery - Site preference management - System object schema exploration - Custom object attribute definitions search 9. **Code Version Tools** (2 tools) - Code version listing and management - Code version activation for deployment fixes 10. **Agent Instruction Tools** (1 tool) - Copy or merge AGENTS.md and bundled skills into the current workspace, user home, or a temp directory - Supports dry-run planning, append/replace/skip strategies, and missing-only installs ### 🚀 Operating Modes #### **Configuration Discovery Priority** The server discovers SFCC credentials in this order (highest to lowest priority): 1. **CLI parameter** (`--dw-json /path/to/dw.json`) - Explicit, highest priority 2. **Environment variables** (`SFCC_HOSTNAME`, `SFCC_USERNAME`, `SFCC_PASSWORD`, `SFCC_CLIENT_ID`, `SFCC_CLIENT_SECRET`) 3. **MCP workspace roots discovery** - Automatically finds `dw.json` in VS Code workspace folders after client connection > **Note**: CWD-based auto-discovery is intentionally disabled because MCP servers often start with `cwd` set to the user's home directory, not the project directory. The MCP workspace roots mechanism provides reliable project context. #### **Documentation-Only Mode** - No SFCC credentials required - Access to all documentation and best practices - Perfect for learning and reference #### **Full Mode** - Requires SFCC instance credentials - Complete access to logs, job logs, and system objects - Real-time debugging and monitoring capabilities ### 🎯 Development Guidelines See Unified Engineering Principles section above for the authoritative guidelines covering: - Configuration options and operating modes - Development workflows and best practices - Tool categories and counts - Installation and setup procedures ### 📝 Documentation Maintenance Requirements **Critical**: When making any structural or functional changes to the codebase, you **MUST** update the relevant sections in **BOTH** `AGENTS.md` and `README.md`: #### **Always Verify Counts with Command Line Tools:** Before updating any documentation with tool counts or quantitative information, **ALWAYS** verify the actual numbers using command line tools: ```bash # Total tool count verification (38 tools across all categories) grep -c "name: '" src/core/tool-schemas/*.ts | grep -v ":0" | awk -F: '{sum+=$2} END {print "Total tools:", sum}' # Individual category counts (from modular schema files) echo "Documentation tools:" && grep -c "name: '" src/core/tool-schemas/documentation-tools.ts echo "Best practices tools:" && grep -c "name: '" src/core/tool-schemas/best-practices-tools.ts echo "SFRA tools:" && grep -c "name: '" src/core/tool-schemas/sfra-tools.ts echo "ISML tools:" && grep -c "name: '" src/core/tool-schemas/isml-tools.ts echo "Log + Job log tools:" && grep -c "name: '" src/core/tool-schemas/log-tools.ts echo "System object tools:" && grep -c "name: '" src/core/tool-schemas/system-object-tools.ts echo "Cartridge tools:" && grep -c "name: '" src/core/tool-schemas/cartridge-tools.ts echo "Code version tools:" && grep -c "name: '" src/core/tool-schemas/code-version-tools.ts # Verify file structure changes find src -name "*.ts" -type f | wc -l # Count TypeScript files find docs -name "*.md" -type f | wc -l # Count documentation files ``` **Never assume or estimate counts** - always verify with actual command line verification before updating documentation. #### **Required Updates For:** - **File Renames/Moves**: Update project structure diagram and component descriptions in AGENTS.md; update any file references in README.md - **New Classes/Modules**: Add descriptions to the Key Components section in AGENTS.md; update feature lists in README.md if user-facing - **Changed Responsibilities**: Modify class/module purpose descriptions in AGENTS.md; update feature descriptions in README.md - **New Tools**: Update tool categories and counts in **both** files; add tool descriptions to README.md features section - **Configuration Changes**: Update Operating Modes and Configuration Management sections in AGENTS.md; update configuration examples in README.md - **New Development Patterns**: Add to Common Development Tasks in AGENTS.md - **Architecture Changes**: Update Client Architecture and Key Components sections in AGENTS.md - **Installation/Setup Changes**: Update installation and configuration sections in README.md - **New Operating Modes**: Update both files with new mode descriptions and requirements - **Tool Count Changes**: Update the "Available Tools by Mode" table in README.md and tool category counts in copilot-instructions.md #### **Documentation Standards:** - **copilot-instructions.md**: Focus on technical architecture, development guidelines, and internal structure - **README.md**: Focus on user-facing features, installation, configuration, and usage examples - Use clear, descriptive language that helps developers understand the codebase - Include specific file paths and references where relevant - Maintain consistency with existing documentation style and structure - Provide context for why changes were made when updating architectural decisions - Keep tool counts and feature lists accurate and current in both files #### **When to Update:** - **Immediately after** making structural changes (file renames, moves, deletions) - **Before completing** feature development that adds new capabilities - **During refactoring** that changes class responsibilities or module purposes - **After adding** new tools, clients, or major functionality - **When modifying** configuration systems or authentication flows - **When changing** installation procedures or setup requirements - **After updating** tool categories or operating modes #### **Specific File Responsibilities:** **AGENTS.md Updates:** - Project structure diagram - Key Components descriptions - Tool Categories and counts - Operating Modes technical details - Development Guidelines - Common Development Tasks - Client Architecture descriptions **README.md Updates:** - Feature lists and descriptions - Available Tools by Mode table - Installation and setup instructions - Configuration examples and options - Usage examples and quick start guides - Tool descriptions for end users **Remember**: These documentation files serve as the primary source of truth for understanding the project. `AGENTS.md` guides development practices and architecture, while `README.md` serves users and contributors. Keeping both current ensures consistent understanding across all stakeholders and maintains professional project standards. ### 🔧 Common Development Tasks **Code Development:** - **Adding New Tools**: Define schema in `core/tool-schemas/[category]-tools.ts`, add to `index.ts`, implement in `core/handlers/` - **Creating New Handlers**: Extend `BaseToolHandler`, implement `canHandle()` and `handle()`, register in `server.ts` - **Using ClientFactory**: Create clients with `ClientFactory` for centralized creation and DI support - **Implementing Services**: Create interfaces in `services/index.ts`, implement production + mock versions **Testing** (see `.github/skills/` for detailed guides): - **YAML Tests**: Use `mcp-yaml-testing` skill for declarative test creation - **Programmatic Tests**: Use `mcp-programmatic-testing` skill for complex workflows - **Unit Tests**: Jest for `tests/` directory; MCP tests use `node --test` **SFCC-Specific Tasks** (see `.github/skills/` for detailed guides): - **Cartridge Generation**: Use `sfcc-cartridge-generation` skill for scaffolding - **Log Debugging**: Use `sfcc-log-debugging` skill for error investigation **Modular Development:** - **Log Modules**: Modify `clients/logs/` files for log functionality changes - **Doc Modules**: Modify `clients/docs/` files for documentation parsing changes - **Documentation**: Use verification commands before updating counts ### 🔍 Testing & Validation **Skills Available**: For detailed testing workflows, use these Agent Skills (in `.github/skills/`): - `mcp-yaml-testing` - YAML test creation, patterns, discovery workflow - `mcp-programmatic-testing` - JavaScript tests, buffer management, multi-step workflows **Test Type Decision Matrix**: | Scenario | Recommended | Reason | |----------|-------------|--------| | Basic tool validation | YAML | Simple, declarative, CI-friendly | | Schema/shape testing | YAML | Pattern matching built-in | | Multi-step workflows | Programmatic | State management needed | | Complex business logic | Programmatic | Code execution required | **Essential Commands**: ```bash # Discovery (ALWAYS run before writing tests) npx aegis query [tool_name] '[params]' --config ./aegis.config.docs-only.json # Test execution npm run test:mcp:yaml # YAML tests (docs-only) npm run test:mcp:yaml:full # YAML tests (full mode) npm run test:mcp:node # Programmatic tests npm test # Full suite (Jest + MCP) ``` **Critical Rules**: 1. Always discover response formats with `aegis query` before writing tests 2. Use `client.clearAllBuffers()` in programmatic test `beforeEach()` hooks 3. Never use `Promise.all()` with MCP requests (causes buffer conflicts) 4. Use CI-friendly timeouts (500ms+) for performance assertions ### 🧱 Architecture Advantages (Consolidated) Unified benefits of the directory structure, handler model, dependency injection, modular log system, and modular documentation system: | Concern | Key Advantages | |---------|----------------| | Directory Structure | Clear ownership, scalable growth, minimal cross-module coupling | | Handlers | Category isolation, standardized lifecycle (canHandle/handle), centralized error & timing, easy extension | | Dependency Injection | Swappable services, simplified testing (mock interfaces), boundary clarity, reduced coupling | | Log Modules | SRP per stage (discover→read→process→analyze→format), range-tail efficiency, extensible analysis & output, backward compatibility wrapper | | Documentation Modules | Streamlined pipeline (scan→parse→resolve→extract), focused optimizations, circular reference protection, type-safe expansion | Cross-cutting wins: - Strong typing across all layers - Deterministic testability in isolation - Backward compatibility through orchestrator wrappers (`log-client.ts`, `docs-client.ts`) - Predictable extension points (add handler, client, or module without ripple) - Low-risk refactoring zones due to SRP boundaries Result: Faster iteration, safer modifications, and clearer mental model for both humans and AI agents.