This is page 1 of 61. Use http://codebase.md/taurgis/sfcc-dev-mcp?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .DS_Store
├── .github
│ ├── dependabot.yml
│ ├── instructions
│ │ ├── mcp-node-tests.instructions.md
│ │ └── mcp-yml-tests.instructions.md
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.yml
│ │ ├── config.yml
│ │ ├── documentation.yml
│ │ ├── feature_request.yml
│ │ └── question.yml
│ ├── PULL_REQUEST_TEMPLATE
│ │ ├── bug_fix.md
│ │ ├── documentation.md
│ │ └── new_tool.md
│ ├── pull_request_template.md
│ └── workflows
│ ├── ci.yml
│ ├── deploy-pages.yml
│ ├── publish.yml
│ └── update-docs.yml
├── .gitignore
├── .husky
│ └── pre-commit
├── aegis.config.docs-only.json
├── aegis.config.json
├── aegis.config.with-dw.json
├── AGENTS.md
├── ai-instructions
│ ├── claude-desktop
│ │ └── claude_custom_instructions.md
│ ├── cursor
│ │ └── .cursor
│ │ └── rules
│ │ ├── debugging-workflows.mdc
│ │ ├── hooks-development.mdc
│ │ ├── isml-templates.mdc
│ │ ├── job-framework.mdc
│ │ ├── performance-optimization.mdc
│ │ ├── scapi-endpoints.mdc
│ │ ├── security-patterns.mdc
│ │ ├── sfcc-development.mdc
│ │ ├── sfra-controllers.mdc
│ │ ├── sfra-models.mdc
│ │ ├── system-objects.mdc
│ │ └── testing-patterns.mdc
│ └── github-copilot
│ └── copilot-instructions.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── docs
│ ├── best-practices
│ │ ├── cartridge_creation.md
│ │ ├── isml_templates.md
│ │ ├── job_framework.md
│ │ ├── localserviceregistry.md
│ │ ├── ocapi_hooks.md
│ │ ├── performance.md
│ │ ├── scapi_custom_endpoint.md
│ │ ├── scapi_hooks.md
│ │ ├── security.md
│ │ ├── sfra_client_side_js.md
│ │ ├── sfra_controllers.md
│ │ ├── sfra_models.md
│ │ └── sfra_scss.md
│ ├── dw_campaign
│ │ ├── ABTest.md
│ │ ├── ABTestMgr.md
│ │ ├── ABTestSegment.md
│ │ ├── AmountDiscount.md
│ │ ├── ApproachingDiscount.md
│ │ ├── BonusChoiceDiscount.md
│ │ ├── BonusDiscount.md
│ │ ├── Campaign.md
│ │ ├── CampaignMgr.md
│ │ ├── CampaignStatusCodes.md
│ │ ├── Coupon.md
│ │ ├── CouponMgr.md
│ │ ├── CouponRedemption.md
│ │ ├── CouponStatusCodes.md
│ │ ├── Discount.md
│ │ ├── DiscountPlan.md
│ │ ├── FixedPriceDiscount.md
│ │ ├── FixedPriceShippingDiscount.md
│ │ ├── FreeDiscount.md
│ │ ├── FreeShippingDiscount.md
│ │ ├── PercentageDiscount.md
│ │ ├── PercentageOptionDiscount.md
│ │ ├── PriceBookPriceDiscount.md
│ │ ├── Promotion.md
│ │ ├── PromotionMgr.md
│ │ ├── PromotionPlan.md
│ │ ├── SlotContent.md
│ │ ├── SourceCodeGroup.md
│ │ ├── SourceCodeInfo.md
│ │ ├── SourceCodeStatusCodes.md
│ │ └── TotalFixedPriceDiscount.md
│ ├── dw_catalog
│ │ ├── Catalog.md
│ │ ├── CatalogMgr.md
│ │ ├── Category.md
│ │ ├── CategoryAssignment.md
│ │ ├── CategoryLink.md
│ │ ├── PriceBook.md
│ │ ├── PriceBookMgr.md
│ │ ├── Product.md
│ │ ├── ProductActiveData.md
│ │ ├── ProductAttributeModel.md
│ │ ├── ProductAvailabilityLevels.md
│ │ ├── ProductAvailabilityModel.md
│ │ ├── ProductInventoryList.md
│ │ ├── ProductInventoryMgr.md
│ │ ├── ProductInventoryRecord.md
│ │ ├── ProductLink.md
│ │ ├── ProductMgr.md
│ │ ├── ProductOption.md
│ │ ├── ProductOptionModel.md
│ │ ├── ProductOptionValue.md
│ │ ├── ProductPriceInfo.md
│ │ ├── ProductPriceModel.md
│ │ ├── ProductPriceTable.md
│ │ ├── ProductSearchHit.md
│ │ ├── ProductSearchModel.md
│ │ ├── ProductSearchRefinementDefinition.md
│ │ ├── ProductSearchRefinements.md
│ │ ├── ProductSearchRefinementValue.md
│ │ ├── ProductVariationAttribute.md
│ │ ├── ProductVariationAttributeValue.md
│ │ ├── ProductVariationModel.md
│ │ ├── Recommendation.md
│ │ ├── SearchModel.md
│ │ ├── SearchRefinementDefinition.md
│ │ ├── SearchRefinements.md
│ │ ├── SearchRefinementValue.md
│ │ ├── SortingOption.md
│ │ ├── SortingRule.md
│ │ ├── Store.md
│ │ ├── StoreGroup.md
│ │ ├── StoreInventoryFilter.md
│ │ ├── StoreInventoryFilterValue.md
│ │ ├── StoreMgr.md
│ │ ├── Variant.md
│ │ └── VariationGroup.md
│ ├── dw_content
│ │ ├── Content.md
│ │ ├── ContentMgr.md
│ │ ├── ContentSearchModel.md
│ │ ├── ContentSearchRefinementDefinition.md
│ │ ├── ContentSearchRefinements.md
│ │ ├── ContentSearchRefinementValue.md
│ │ ├── Folder.md
│ │ ├── Library.md
│ │ ├── MarkupText.md
│ │ └── MediaFile.md
│ ├── dw_crypto
│ │ ├── CertificateRef.md
│ │ ├── CertificateUtils.md
│ │ ├── Cipher.md
│ │ ├── Encoding.md
│ │ ├── JWE.md
│ │ ├── JWEHeader.md
│ │ ├── JWS.md
│ │ ├── JWSHeader.md
│ │ ├── KeyRef.md
│ │ ├── Mac.md
│ │ ├── MessageDigest.md
│ │ ├── SecureRandom.md
│ │ ├── Signature.md
│ │ ├── WeakCipher.md
│ │ ├── WeakMac.md
│ │ ├── WeakMessageDigest.md
│ │ ├── WeakSignature.md
│ │ └── X509Certificate.md
│ ├── dw_customer
│ │ ├── AddressBook.md
│ │ ├── AgentUserMgr.md
│ │ ├── AgentUserStatusCodes.md
│ │ ├── AuthenticationStatus.md
│ │ ├── Credentials.md
│ │ ├── Customer.md
│ │ ├── CustomerActiveData.md
│ │ ├── CustomerAddress.md
│ │ ├── CustomerCDPData.md
│ │ ├── CustomerContextMgr.md
│ │ ├── CustomerGroup.md
│ │ ├── CustomerList.md
│ │ ├── CustomerMgr.md
│ │ ├── CustomerPasswordConstraints.md
│ │ ├── CustomerPaymentInstrument.md
│ │ ├── CustomerStatusCodes.md
│ │ ├── EncryptedObject.md
│ │ ├── ExternalProfile.md
│ │ ├── OrderHistory.md
│ │ ├── ProductList.md
│ │ ├── ProductListItem.md
│ │ ├── ProductListItemPurchase.md
│ │ ├── ProductListMgr.md
│ │ ├── ProductListRegistrant.md
│ │ ├── Profile.md
│ │ └── Wallet.md
│ ├── dw_extensions.applepay
│ │ ├── ApplePayHookResult.md
│ │ └── ApplePayHooks.md
│ ├── dw_extensions.facebook
│ │ ├── FacebookFeedHooks.md
│ │ └── FacebookProduct.md
│ ├── dw_extensions.paymentrequest
│ │ ├── PaymentRequestHookResult.md
│ │ └── PaymentRequestHooks.md
│ ├── dw_extensions.payments
│ │ ├── SalesforceBancontactPaymentDetails.md
│ │ ├── SalesforceCardPaymentDetails.md
│ │ ├── SalesforceEpsPaymentDetails.md
│ │ ├── SalesforceIdealPaymentDetails.md
│ │ ├── SalesforceKlarnaPaymentDetails.md
│ │ ├── SalesforcePaymentDetails.md
│ │ ├── SalesforcePaymentIntent.md
│ │ ├── SalesforcePaymentMethod.md
│ │ ├── SalesforcePaymentRequest.md
│ │ ├── SalesforcePaymentsHooks.md
│ │ ├── SalesforcePaymentsMgr.md
│ │ ├── SalesforcePaymentsSiteConfiguration.md
│ │ ├── SalesforcePayPalOrder.md
│ │ ├── SalesforcePayPalOrderAddress.md
│ │ ├── SalesforcePayPalOrderPayer.md
│ │ ├── SalesforcePayPalPaymentDetails.md
│ │ ├── SalesforceSepaDebitPaymentDetails.md
│ │ └── SalesforceVenmoPaymentDetails.md
│ ├── dw_extensions.pinterest
│ │ ├── PinterestAvailability.md
│ │ ├── PinterestFeedHooks.md
│ │ ├── PinterestOrder.md
│ │ ├── PinterestOrderHooks.md
│ │ └── PinterestProduct.md
│ ├── dw_io
│ │ ├── CSVStreamReader.md
│ │ ├── CSVStreamWriter.md
│ │ ├── File.md
│ │ ├── FileReader.md
│ │ ├── FileWriter.md
│ │ ├── InputStream.md
│ │ ├── OutputStream.md
│ │ ├── PrintWriter.md
│ │ ├── RandomAccessFileReader.md
│ │ ├── Reader.md
│ │ ├── StringWriter.md
│ │ ├── Writer.md
│ │ ├── XMLIndentingStreamWriter.md
│ │ ├── XMLStreamConstants.md
│ │ ├── XMLStreamReader.md
│ │ └── XMLStreamWriter.md
│ ├── dw_job
│ │ ├── JobExecution.md
│ │ └── JobStepExecution.md
│ ├── dw_net
│ │ ├── FTPClient.md
│ │ ├── FTPFileInfo.md
│ │ ├── HTTPClient.md
│ │ ├── HTTPRequestPart.md
│ │ ├── Mail.md
│ │ ├── SFTPClient.md
│ │ ├── SFTPFileInfo.md
│ │ ├── WebDAVClient.md
│ │ └── WebDAVFileInfo.md
│ ├── dw_object
│ │ ├── ActiveData.md
│ │ ├── CustomAttributes.md
│ │ ├── CustomObject.md
│ │ ├── CustomObjectMgr.md
│ │ ├── Extensible.md
│ │ ├── ExtensibleObject.md
│ │ ├── Note.md
│ │ ├── ObjectAttributeDefinition.md
│ │ ├── ObjectAttributeGroup.md
│ │ ├── ObjectAttributeValueDefinition.md
│ │ ├── ObjectTypeDefinition.md
│ │ ├── PersistentObject.md
│ │ ├── SimpleExtensible.md
│ │ └── SystemObjectMgr.md
│ ├── dw_order
│ │ ├── AbstractItem.md
│ │ ├── AbstractItemCtnr.md
│ │ ├── Appeasement.md
│ │ ├── AppeasementItem.md
│ │ ├── Basket.md
│ │ ├── BasketMgr.md
│ │ ├── BonusDiscountLineItem.md
│ │ ├── CouponLineItem.md
│ │ ├── CreateAgentBasketLimitExceededException.md
│ │ ├── CreateBasketFromOrderException.md
│ │ ├── CreateCouponLineItemException.md
│ │ ├── CreateOrderException.md
│ │ ├── CreateTemporaryBasketLimitExceededException.md
│ │ ├── GiftCertificate.md
│ │ ├── GiftCertificateLineItem.md
│ │ ├── GiftCertificateMgr.md
│ │ ├── GiftCertificateStatusCodes.md
│ │ ├── Invoice.md
│ │ ├── InvoiceItem.md
│ │ ├── LineItem.md
│ │ ├── LineItemCtnr.md
│ │ ├── Order.md
│ │ ├── OrderAddress.md
│ │ ├── OrderItem.md
│ │ ├── OrderMgr.md
│ │ ├── OrderPaymentInstrument.md
│ │ ├── OrderProcessStatusCodes.md
│ │ ├── PaymentCard.md
│ │ ├── PaymentInstrument.md
│ │ ├── PaymentMethod.md
│ │ ├── PaymentMgr.md
│ │ ├── PaymentProcessor.md
│ │ ├── PaymentStatusCodes.md
│ │ ├── PaymentTransaction.md
│ │ ├── PriceAdjustment.md
│ │ ├── PriceAdjustmentLimitTypes.md
│ │ ├── ProductLineItem.md
│ │ ├── ProductShippingCost.md
│ │ ├── ProductShippingLineItem.md
│ │ ├── ProductShippingModel.md
│ │ ├── Return.md
│ │ ├── ReturnCase.md
│ │ ├── ReturnCaseItem.md
│ │ ├── ReturnItem.md
│ │ ├── Shipment.md
│ │ ├── ShipmentShippingCost.md
│ │ ├── ShipmentShippingModel.md
│ │ ├── ShippingLineItem.md
│ │ ├── ShippingLocation.md
│ │ ├── ShippingMethod.md
│ │ ├── ShippingMgr.md
│ │ ├── ShippingOrder.md
│ │ ├── ShippingOrderItem.md
│ │ ├── SumItem.md
│ │ ├── TaxGroup.md
│ │ ├── TaxItem.md
│ │ ├── TaxMgr.md
│ │ ├── TrackingInfo.md
│ │ └── TrackingRef.md
│ ├── dw_order.hooks
│ │ ├── CalculateHooks.md
│ │ ├── OrderHooks.md
│ │ ├── PaymentHooks.md
│ │ ├── ReturnHooks.md
│ │ └── ShippingOrderHooks.md
│ ├── dw_rpc
│ │ ├── SOAPUtil.md
│ │ ├── Stub.md
│ │ └── WebReference.md
│ ├── dw_suggest
│ │ ├── BrandSuggestions.md
│ │ ├── CategorySuggestions.md
│ │ ├── ContentSuggestions.md
│ │ ├── CustomSuggestions.md
│ │ ├── ProductSuggestions.md
│ │ ├── SearchPhraseSuggestions.md
│ │ ├── SuggestedCategory.md
│ │ ├── SuggestedContent.md
│ │ ├── SuggestedPhrase.md
│ │ ├── SuggestedProduct.md
│ │ ├── SuggestedTerm.md
│ │ ├── SuggestedTerms.md
│ │ ├── Suggestions.md
│ │ └── SuggestModel.md
│ ├── dw_svc
│ │ ├── FTPService.md
│ │ ├── FTPServiceDefinition.md
│ │ ├── HTTPFormService.md
│ │ ├── HTTPFormServiceDefinition.md
│ │ ├── HTTPService.md
│ │ ├── HTTPServiceDefinition.md
│ │ ├── LocalServiceRegistry.md
│ │ ├── Result.md
│ │ ├── Service.md
│ │ ├── ServiceCallback.md
│ │ ├── ServiceConfig.md
│ │ ├── ServiceCredential.md
│ │ ├── ServiceDefinition.md
│ │ ├── ServiceProfile.md
│ │ ├── ServiceRegistry.md
│ │ ├── SOAPService.md
│ │ └── SOAPServiceDefinition.md
│ ├── dw_system
│ │ ├── AgentUserStatusCodes.md
│ │ ├── Cache.md
│ │ ├── CacheMgr.md
│ │ ├── HookMgr.md
│ │ ├── InternalObject.md
│ │ ├── JobProcessMonitor.md
│ │ ├── Log.md
│ │ ├── Logger.md
│ │ ├── LogNDC.md
│ │ ├── OrganizationPreferences.md
│ │ ├── Pipeline.md
│ │ ├── PipelineDictionary.md
│ │ ├── RemoteInclude.md
│ │ ├── Request.md
│ │ ├── RequestHooks.md
│ │ ├── Response.md
│ │ ├── RESTErrorResponse.md
│ │ ├── RESTResponseMgr.md
│ │ ├── RESTSuccessResponse.md
│ │ ├── SearchStatus.md
│ │ ├── Session.md
│ │ ├── Site.md
│ │ ├── SitePreferences.md
│ │ ├── Status.md
│ │ ├── StatusItem.md
│ │ ├── System.md
│ │ └── Transaction.md
│ ├── dw_util
│ │ ├── ArrayList.md
│ │ ├── Assert.md
│ │ ├── BigInteger.md
│ │ ├── Bytes.md
│ │ ├── Calendar.md
│ │ ├── Collection.md
│ │ ├── Currency.md
│ │ ├── DateUtils.md
│ │ ├── Decimal.md
│ │ ├── FilteringCollection.md
│ │ ├── Geolocation.md
│ │ ├── HashMap.md
│ │ ├── HashSet.md
│ │ ├── Iterator.md
│ │ ├── LinkedHashMap.md
│ │ ├── LinkedHashSet.md
│ │ ├── List.md
│ │ ├── Locale.md
│ │ ├── Map.md
│ │ ├── MapEntry.md
│ │ ├── MappingKey.md
│ │ ├── MappingMgr.md
│ │ ├── PropertyComparator.md
│ │ ├── SecureEncoder.md
│ │ ├── SecureFilter.md
│ │ ├── SeekableIterator.md
│ │ ├── Set.md
│ │ ├── SortedMap.md
│ │ ├── SortedSet.md
│ │ ├── StringUtils.md
│ │ ├── Template.md
│ │ └── UUIDUtils.md
│ ├── dw_value
│ │ ├── EnumValue.md
│ │ ├── MimeEncodedText.md
│ │ ├── Money.md
│ │ └── Quantity.md
│ ├── dw_web
│ │ ├── ClickStream.md
│ │ ├── ClickStreamEntry.md
│ │ ├── Cookie.md
│ │ ├── Cookies.md
│ │ ├── CSRFProtection.md
│ │ ├── Form.md
│ │ ├── FormAction.md
│ │ ├── FormElement.md
│ │ ├── FormElementValidationResult.md
│ │ ├── FormField.md
│ │ ├── FormFieldOption.md
│ │ ├── FormFieldOptions.md
│ │ ├── FormGroup.md
│ │ ├── FormList.md
│ │ ├── FormListItem.md
│ │ ├── Forms.md
│ │ ├── HttpParameter.md
│ │ ├── HttpParameterMap.md
│ │ ├── LoopIterator.md
│ │ ├── PageMetaData.md
│ │ ├── PageMetaTag.md
│ │ ├── PagingModel.md
│ │ ├── Resource.md
│ │ ├── URL.md
│ │ ├── URLAction.md
│ │ ├── URLParameter.md
│ │ ├── URLRedirect.md
│ │ ├── URLRedirectMgr.md
│ │ └── URLUtils.md
│ ├── sfra
│ │ ├── account.md
│ │ ├── address.md
│ │ ├── billing.md
│ │ ├── cart.md
│ │ ├── categories.md
│ │ ├── content.md
│ │ ├── locale.md
│ │ ├── order.md
│ │ ├── payment.md
│ │ ├── price-default.md
│ │ ├── price-range.md
│ │ ├── price-tiered.md
│ │ ├── product-bundle.md
│ │ ├── product-full.md
│ │ ├── product-line-items.md
│ │ ├── product-search.md
│ │ ├── product-tile.md
│ │ ├── querystring.md
│ │ ├── render.md
│ │ ├── request.md
│ │ ├── response.md
│ │ ├── server.md
│ │ ├── shipping.md
│ │ ├── store.md
│ │ ├── stores.md
│ │ └── totals.md
│ └── TopLevel
│ ├── APIException.md
│ ├── arguments.md
│ ├── Array.md
│ ├── ArrayBuffer.md
│ ├── BigInt.md
│ ├── Boolean.md
│ ├── ConversionError.md
│ ├── DataView.md
│ ├── Date.md
│ ├── Error.md
│ ├── ES6Iterator.md
│ ├── EvalError.md
│ ├── Fault.md
│ ├── Float32Array.md
│ ├── Float64Array.md
│ ├── Function.md
│ ├── Generator.md
│ ├── global.md
│ ├── Int16Array.md
│ ├── Int32Array.md
│ ├── Int8Array.md
│ ├── InternalError.md
│ ├── IOError.md
│ ├── Iterable.md
│ ├── Iterator.md
│ ├── JSON.md
│ ├── Map.md
│ ├── Math.md
│ ├── Module.md
│ ├── Namespace.md
│ ├── Number.md
│ ├── Object.md
│ ├── QName.md
│ ├── RangeError.md
│ ├── ReferenceError.md
│ ├── RegExp.md
│ ├── Set.md
│ ├── StopIteration.md
│ ├── String.md
│ ├── Symbol.md
│ ├── SyntaxError.md
│ ├── SystemError.md
│ ├── TypeError.md
│ ├── Uint16Array.md
│ ├── Uint32Array.md
│ ├── Uint8Array.md
│ ├── Uint8ClampedArray.md
│ ├── URIError.md
│ ├── WeakMap.md
│ ├── WeakSet.md
│ ├── XML.md
│ ├── XMLList.md
│ └── XMLStreamError.md
├── docs-site
│ ├── .gitignore
│ ├── App.tsx
│ ├── components
│ │ ├── Badge.tsx
│ │ ├── BreadcrumbSchema.tsx
│ │ ├── CodeBlock.tsx
│ │ ├── Collapsible.tsx
│ │ ├── ConfigBuilder.tsx
│ │ ├── ConfigHero.tsx
│ │ ├── ConfigModeTabs.tsx
│ │ ├── icons.tsx
│ │ ├── Layout.tsx
│ │ ├── LightCodeContainer.tsx
│ │ ├── NewcomerCTA.tsx
│ │ ├── NextStepsStrip.tsx
│ │ ├── OnThisPage.tsx
│ │ ├── Search.tsx
│ │ ├── SEO.tsx
│ │ ├── Sidebar.tsx
│ │ ├── StructuredData.tsx
│ │ ├── ToolCard.tsx
│ │ ├── ToolFilters.tsx
│ │ ├── Typography.tsx
│ │ └── VersionBadge.tsx
│ ├── constants.tsx
│ ├── index.html
│ ├── main.tsx
│ ├── metadata.json
│ ├── package-lock.json
│ ├── package.json
│ ├── pages
│ │ ├── AIInterfacesPage.tsx
│ │ ├── ConfigurationPage.tsx
│ │ ├── DevelopmentPage.tsx
│ │ ├── ExamplesPage.tsx
│ │ ├── FeaturesPage.tsx
│ │ ├── HomePage.tsx
│ │ ├── SecurityPage.tsx
│ │ ├── ToolsPage.tsx
│ │ └── TroubleshootingPage.tsx
│ ├── postcss.config.js
│ ├── public
│ │ ├── .well-known
│ │ │ └── security.txt
│ │ ├── 404.html
│ │ ├── android-chrome-192x192.png
│ │ ├── android-chrome-512x512.png
│ │ ├── apple-touch-icon.png
│ │ ├── explain-product-pricing-methods-no-mcp.png
│ │ ├── explain-product-pricing-methods.png
│ │ ├── favicon-16x16.png
│ │ ├── favicon-32x32.png
│ │ ├── favicon.ico
│ │ ├── llms.txt
│ │ ├── robots.txt
│ │ ├── site.webmanifest
│ │ └── sitemap.xml
│ ├── README.md
│ ├── scripts
│ │ ├── generate-search-index.js
│ │ ├── generate-sitemap.js
│ │ └── search-dev.js
│ ├── src
│ │ └── styles
│ │ ├── input.css
│ │ └── prism-theme.css
│ ├── tailwind.config.js
│ ├── tsconfig.json
│ ├── types.ts
│ ├── utils
│ │ ├── search.ts
│ │ └── toolsData.ts
│ └── vite.config.ts
├── eslint.config.js
├── jest.config.js
├── LICENSE
├── package-lock.json
├── package.json
├── README.md
├── scripts
│ └── convert-docs.js
├── SECURITY.md
├── server.json
├── src
│ ├── clients
│ │ ├── base
│ │ │ ├── http-client.ts
│ │ │ ├── oauth-token.ts
│ │ │ └── ocapi-auth-client.ts
│ │ ├── best-practices-client.ts
│ │ ├── cartridge-generation-client.ts
│ │ ├── docs
│ │ │ ├── class-content-parser.ts
│ │ │ ├── class-name-resolver.ts
│ │ │ ├── documentation-scanner.ts
│ │ │ ├── index.ts
│ │ │ └── referenced-types-extractor.ts
│ │ ├── docs-client.ts
│ │ ├── log-client.ts
│ │ ├── logs
│ │ │ ├── index.ts
│ │ │ ├── log-analyzer.ts
│ │ │ ├── log-client.ts
│ │ │ ├── log-constants.ts
│ │ │ ├── log-file-discovery.ts
│ │ │ ├── log-file-reader.ts
│ │ │ ├── log-formatter.ts
│ │ │ ├── log-processor.ts
│ │ │ ├── log-types.ts
│ │ │ └── webdav-client-manager.ts
│ │ ├── ocapi
│ │ │ ├── code-versions-client.ts
│ │ │ ├── site-preferences-client.ts
│ │ │ └── system-objects-client.ts
│ │ ├── ocapi-client.ts
│ │ └── sfra-client.ts
│ ├── config
│ │ ├── configuration-factory.ts
│ │ └── dw-json-loader.ts
│ ├── core
│ │ ├── handlers
│ │ │ ├── abstract-log-tool-handler.ts
│ │ │ ├── base-handler.ts
│ │ │ ├── best-practices-handler.ts
│ │ │ ├── cartridge-handler.ts
│ │ │ ├── client-factory.ts
│ │ │ ├── code-version-handler.ts
│ │ │ ├── docs-handler.ts
│ │ │ ├── job-log-handler.ts
│ │ │ ├── job-log-tool-config.ts
│ │ │ ├── log-handler.ts
│ │ │ ├── log-tool-config.ts
│ │ │ ├── sfra-handler.ts
│ │ │ ├── system-object-handler.ts
│ │ │ └── validation-helpers.ts
│ │ ├── server.ts
│ │ └── tool-definitions.ts
│ ├── index.ts
│ ├── main.ts
│ ├── services
│ │ ├── file-system-service.ts
│ │ ├── index.ts
│ │ └── path-service.ts
│ ├── tool-configs
│ │ ├── best-practices-tool-config.ts
│ │ ├── cartridge-tool-config.ts
│ │ ├── code-version-tool-config.ts
│ │ ├── docs-tool-config.ts
│ │ ├── job-log-tool-config.ts
│ │ ├── log-tool-config.ts
│ │ ├── sfra-tool-config.ts
│ │ └── system-object-tool-config.ts
│ ├── types
│ │ └── types.ts
│ └── utils
│ ├── cache.ts
│ ├── job-log-tool-config.ts
│ ├── job-log-utils.ts
│ ├── log-cache.ts
│ ├── log-tool-config.ts
│ ├── log-tool-constants.ts
│ ├── log-tool-utils.ts
│ ├── logger.ts
│ ├── ocapi-url-builder.ts
│ ├── path-resolver.ts
│ ├── query-builder.ts
│ ├── utils.ts
│ └── validator.ts
├── tests
│ ├── __mocks__
│ │ ├── docs-client.ts
│ │ ├── src
│ │ │ └── clients
│ │ │ └── base
│ │ │ └── http-client.js
│ │ └── webdav.js
│ ├── base-handler.test.ts
│ ├── base-http-client.test.ts
│ ├── best-practices-handler.test.ts
│ ├── cache.test.ts
│ ├── cartridge-handler.test.ts
│ ├── class-content-parser.test.ts
│ ├── class-name-resolver.test.ts
│ ├── client-factory.test.ts
│ ├── code-version-handler.test.ts
│ ├── code-versions-client.test.ts
│ ├── config.test.ts
│ ├── configuration-factory.test.ts
│ ├── docs-handler.test.ts
│ ├── documentation-scanner.test.ts
│ ├── file-system-service.test.ts
│ ├── job-log-handler.test.ts
│ ├── job-log-utils.test.ts
│ ├── log-client.test.ts
│ ├── log-handler.test.ts
│ ├── log-processor.test.ts
│ ├── logger.test.ts
│ ├── mcp
│ │ ├── AGENTS.md
│ │ ├── node
│ │ │ ├── activate-code-version-advanced.full-mode.programmatic.test.js
│ │ │ ├── code-versions.full-mode.programmatic.test.js
│ │ │ ├── generate-cartridge-structure.docs-only.programmatic.test.js
│ │ │ ├── get-available-best-practice-guides.docs-only.programmatic.test.js
│ │ │ ├── get-available-sfra-documents.programmatic.test.js
│ │ │ ├── get-best-practice-guide.docs-only.programmatic.test.js
│ │ │ ├── get-hook-reference.docs-only.programmatic.test.js
│ │ │ ├── get-job-execution-summary.full-mode.programmatic.test.js
│ │ │ ├── get-job-log-entries.full-mode.programmatic.test.js
│ │ │ ├── get-latest-debug.full-mode.programmatic.test.js
│ │ │ ├── get-latest-error.full-mode.programmatic.test.js
│ │ │ ├── get-latest-info.full-mode.programmatic.test.js
│ │ │ ├── get-latest-job-log-files.full-mode.programmatic.test.js
│ │ │ ├── get-latest-warn.full-mode.programmatic.test.js
│ │ │ ├── get-log-file-contents.full-mode.programmatic.test.js
│ │ │ ├── get-sfcc-class-documentation.docs-only.programmatic.test.js
│ │ │ ├── get-sfcc-class-info.docs-only.programmatic.test.js
│ │ │ ├── get-sfra-categories.docs-only.programmatic.test.js
│ │ │ ├── get-sfra-document.programmatic.test.js
│ │ │ ├── get-sfra-documents-by-category.docs-only.programmatic.test.js
│ │ │ ├── get-system-object-definition.full-mode.programmatic.test.js
│ │ │ ├── get-system-object-definitions.docs-only.programmatic.test.js
│ │ │ ├── get-system-object-definitions.full-mode.programmatic.test.js
│ │ │ ├── list-log-files.full-mode.programmatic.test.js
│ │ │ ├── list-sfcc-classes.docs-only.programmatic.test.js
│ │ │ ├── search-best-practices.docs-only.programmatic.test.js
│ │ │ ├── search-custom-object-attribute-definitions.full-mode.programmatic.test.js
│ │ │ ├── search-job-logs-by-name.full-mode.programmatic.test.js
│ │ │ ├── search-job-logs.full-mode.programmatic.test.js
│ │ │ ├── search-logs.full-mode.programmatic.test.js
│ │ │ ├── search-sfcc-classes.docs-only.programmatic.test.js
│ │ │ ├── search-sfcc-methods.docs-only.programmatic.test.js
│ │ │ ├── search-sfra-documentation.docs-only.programmatic.test.js
│ │ │ ├── search-site-preferences.full-mode.programmatic.test.js
│ │ │ ├── search-system-object-attribute-definitions.full-mode.programmatic.test.js
│ │ │ ├── search-system-object-attribute-groups.full-mode.programmatic.test.js
│ │ │ ├── summarize-logs.full-mode.programmatic.test.js
│ │ │ ├── tools.docs-only.programmatic.test.js
│ │ │ └── tools.full-mode.programmatic.test.js
│ │ ├── README.md
│ │ ├── test-fixtures
│ │ │ └── dw.json
│ │ └── yaml
│ │ ├── activate-code-version.docs-only.test.mcp.yml
│ │ ├── activate-code-version.full-mode.test.mcp.yml
│ │ ├── get_latest_error.test.mcp.yml
│ │ ├── get-available-best-practice-guides.docs-only.test.mcp.yml
│ │ ├── get-available-best-practice-guides.full-mode.test.mcp.yml
│ │ ├── get-available-sfra-documents.docs-only.test.mcp.yml
│ │ ├── get-available-sfra-documents.full-mode.test.mcp.yml
│ │ ├── get-best-practice-guide.docs-only.test.mcp.yml
│ │ ├── get-best-practice-guide.full-mode.test.mcp.yml
│ │ ├── get-code-versions.docs-only.test.mcp.yml
│ │ ├── get-code-versions.full-mode.test.mcp.yml
│ │ ├── get-hook-reference.docs-only.test.mcp.yml
│ │ ├── get-hook-reference.full-mode.test.mcp.yml
│ │ ├── get-job-execution-summary.full-mode.test.mcp.yml
│ │ ├── get-job-log-entries.full-mode.test.mcp.yml
│ │ ├── get-latest-debug.full-mode.test.mcp.yml
│ │ ├── get-latest-error.full-mode.test.mcp.yml
│ │ ├── get-latest-info.full-mode.test.mcp.yml
│ │ ├── get-latest-job-log-files.full-mode.test.mcp.yml
│ │ ├── get-latest-warn.full-mode.test.mcp.yml
│ │ ├── get-log-file-contents.full-mode.test.mcp.yml
│ │ ├── get-sfcc-class-documentation.docs-only.test.mcp.yml
│ │ ├── get-sfcc-class-documentation.full-mode.test.mcp.yml
│ │ ├── get-sfcc-class-info.docs-only.test.mcp.yml
│ │ ├── get-sfcc-class-info.full-mode.test.mcp.yml
│ │ ├── get-sfra-categories.docs-only.test.mcp.yml
│ │ ├── get-sfra-categories.full-mode.test.mcp.yml
│ │ ├── get-sfra-document.docs-only.test.mcp.yml
│ │ ├── get-sfra-document.full-mode.test.mcp.yml
│ │ ├── get-sfra-documents-by-category.docs-only.test.mcp.yml
│ │ ├── get-sfra-documents-by-category.full-mode.test.mcp.yml
│ │ ├── get-system-object-definition.docs-only.test.mcp.yml
│ │ ├── get-system-object-definition.full-mode.test.mcp.yml
│ │ ├── get-system-object-definitions.docs-only.test.mcp.yml
│ │ ├── get-system-object-definitions.full-mode.test.mcp.yml
│ │ ├── list-log-files.full-mode.test.mcp.yml
│ │ ├── list-sfcc-classes.docs-only.test.mcp.yml
│ │ ├── list-sfcc-classes.full-mode.test.mcp.yml
│ │ ├── search-best-practices.docs-only.test.mcp.yml
│ │ ├── search-best-practices.full-mode.test.mcp.yml
│ │ ├── search-custom-object-attribute-definitions.docs-only.test.mcp.yml
│ │ ├── search-custom-object-attribute-definitions.test.mcp.yml
│ │ ├── search-job-logs-by-name.full-mode.test.mcp.yml
│ │ ├── search-job-logs.full-mode.test.mcp.yml
│ │ ├── search-logs.full-mode.test.mcp.yml
│ │ ├── search-sfcc-classes.docs-only.test.mcp.yml
│ │ ├── search-sfcc-classes.full-mode.test.mcp.yml
│ │ ├── search-sfcc-methods.docs-only.test.mcp.yml
│ │ ├── search-sfcc-methods.full-mode.test.mcp.yml
│ │ ├── search-sfra-documentation.docs-only.test.mcp.yml
│ │ ├── search-sfra-documentation.full-mode.test.mcp.yml
│ │ ├── search-site-preferences.docs-only.test.mcp.yml
│ │ ├── search-site-preferences.full-mode.test.mcp.yml
│ │ ├── search-system-object-attribute-definitions.docs-only.test.mcp.yml
│ │ ├── search-system-object-attribute-definitions.full-mode.test.mcp.yml
│ │ ├── search-system-object-attribute-groups.docs-only.test.mcp.yml
│ │ ├── search-system-object-attribute-groups.full-mode.test.mcp.yml
│ │ ├── summarize-logs.full-mode.test.mcp.yml
│ │ ├── tools.docs-only.test.mcp.yml
│ │ └── tools.full-mode.test.mcp.yml
│ ├── oauth-token.test.ts
│ ├── ocapi-auth-client.test.ts
│ ├── ocapi-client.test.ts
│ ├── path-service.test.ts
│ ├── query-builder.test.ts
│ ├── referenced-types-extractor.test.ts
│ ├── servers
│ │ ├── sfcc-mock-server
│ │ │ ├── mock-data
│ │ │ │ └── ocapi
│ │ │ │ ├── code-versions.json
│ │ │ │ ├── custom-object-attributes-customapi.json
│ │ │ │ ├── custom-object-attributes-globalsettings.json
│ │ │ │ ├── custom-object-attributes-versionhistory.json
│ │ │ │ ├── site-preferences-ccv.json
│ │ │ │ ├── site-preferences-fastforward.json
│ │ │ │ ├── site-preferences-sfra.json
│ │ │ │ ├── site-preferences-storefront.json
│ │ │ │ ├── site-preferences-system.json
│ │ │ │ ├── system-object-attribute-groups-campaign.json
│ │ │ │ ├── system-object-attribute-groups-category.json
│ │ │ │ ├── system-object-attribute-groups-order.json
│ │ │ │ ├── system-object-attribute-groups-product.json
│ │ │ │ ├── system-object-attribute-groups-sitepreferences.json
│ │ │ │ ├── system-object-attributes-customeraddress.json
│ │ │ │ ├── system-object-attributes-product-expanded.json
│ │ │ │ ├── system-object-attributes-product.json
│ │ │ │ ├── system-object-definition-category.json
│ │ │ │ ├── system-object-definition-customer.json
│ │ │ │ ├── system-object-definition-customeraddress.json
│ │ │ │ ├── system-object-definition-order.json
│ │ │ │ ├── system-object-definition-product.json
│ │ │ │ ├── system-object-definitions-old.json
│ │ │ │ └── system-object-definitions.json
│ │ │ ├── package-lock.json
│ │ │ ├── package.json
│ │ │ ├── README.md
│ │ │ ├── scripts
│ │ │ │ └── setup-logs.js
│ │ │ ├── server.js
│ │ │ └── src
│ │ │ ├── app.js
│ │ │ ├── config
│ │ │ │ └── server-config.js
│ │ │ ├── middleware
│ │ │ │ ├── auth.js
│ │ │ │ ├── cors.js
│ │ │ │ └── logging.js
│ │ │ ├── routes
│ │ │ │ ├── ocapi
│ │ │ │ │ ├── code-versions-handler.js
│ │ │ │ │ ├── oauth-handler.js
│ │ │ │ │ ├── ocapi-error-utils.js
│ │ │ │ │ ├── ocapi-utils.js
│ │ │ │ │ ├── site-preferences-handler.js
│ │ │ │ │ └── system-objects-handler.js
│ │ │ │ ├── ocapi.js
│ │ │ │ └── webdav.js
│ │ │ └── utils
│ │ │ ├── mock-data-loader.js
│ │ │ └── webdav-xml.js
│ │ └── sfcc-mock-server-manager.ts
│ ├── sfcc-mock-server.test.ts
│ ├── site-preferences-client.test.ts
│ ├── system-objects-client.test.ts
│ ├── utils.test.ts
│ ├── validation-helpers.test.ts
│ └── validator.test.ts
├── tsconfig.json
└── tsconfig.test.json
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | /node_modules/
2 | /dist/
3 | /.idea/
4 | /docs-site-old/.bundle
5 | /docs-site-old/_site
6 | /docs-site-old/vendor
7 | tests/servers/sfcc-mock-server/mock-data/logs/
8 | tests/servers/webdav/node_modules/
9 | tests/servers/ocapi/node_modules/
10 | tests/servers/sfcc-mock-server/node_modules/
11 |
12 | tmp/
13 |
```
--------------------------------------------------------------------------------
/docs-site/.gitignore:
--------------------------------------------------------------------------------
```
1 | # Logs
2 | logs
3 | *.log
4 | npm-debug.log*
5 | yarn-debug.log*
6 | yarn-error.log*
7 | pnpm-debug.log*
8 | lerna-debug.log*
9 |
10 | node_modules
11 | dist
12 | dist-ssr
13 | *.local
14 |
15 | # Generated CSS files
16 | /public/index.css
17 |
18 | # Auto-generated search index
19 | /src/generated-search-index.ts
20 |
21 | # Editor directories and files
22 | .vscode/*
23 | !.vscode/extensions.json
24 | .idea
25 | .DS_Store
26 | *.suo
27 | *.ntvs*
28 | *.njsproj
29 | *.sln
30 | *.sw?
31 |
```
--------------------------------------------------------------------------------
/docs-site/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # SFCC Development MCP Server Documentation Site
2 |
3 | A modern React-based documentation site for the SFCC Development MCP Server built with Vite and TailwindCSS.
4 |
5 | ## Features
6 |
7 | - **React 19** with TypeScript
8 | - **Vite** for fast development and building
9 | - **TailwindCSS** for styling (locally configured)
10 | - **React Router** with Hash routing for GitHub Pages compatibility
11 | - **Responsive design** with mobile-first approach
12 |
13 | ## Development
14 |
15 | ### Prerequisites
16 |
17 | - Node.js 18+
18 | - npm
19 |
20 | ### Setup
21 |
22 | 1. Install dependencies:
23 | ```bash
24 | npm install
25 | ```
26 |
27 | 2. Start development server:
28 | ```bash
29 | npm run dev
30 | ```
31 |
32 | The site will be available at `http://localhost:5173/`
33 |
34 | ### Building for Production
35 |
36 | ```bash
37 | npm run build
38 | ```
39 |
40 | This will:
41 | 1. Generate optimized TailwindCSS from used classes
42 | 2. Build the React application with Vite
43 | 3. Output production files to `dist/`
44 |
45 | ### TailwindCSS Configuration
46 |
47 | TailwindCSS is configured locally with:
48 |
49 | - **Config**: `tailwind.config.js`
50 | - **PostCSS**: `postcss.config.js`
51 | - **Input CSS**: `src/styles/input.css`
52 | - **Output CSS**: `public/index.css` (generated)
53 |
54 | ### Available Scripts
55 |
56 | - `npm run dev` - Start development server with CSS generation
57 | - `npm run build` - Build for production (includes CSS generation)
58 | - `npm run preview` - Preview production build
59 | - `npm run build:css` - Generate TailwindCSS once
60 | - `npm run build:css:watch` - Generate TailwindCSS in watch mode
61 |
62 | ### File Structure
63 |
64 | ```
65 | docs-site-v2/
66 | ├── public/
67 | │ └── index.css # Generated TailwindCSS (gitignored)
68 | ├── src/
69 | │ └── styles/
70 | │ └── input.css # TailwindCSS source
71 | ├── components/ # React components
72 | ├── pages/ # Page components
73 | ├── index.html # Main HTML template
74 | ├── index.tsx # React application entry
75 | ├── tailwind.config.js # TailwindCSS configuration
76 | ├── postcss.config.js # PostCSS configuration
77 | ├── vite.config.ts # Vite configuration
78 | └── package.json # Dependencies and scripts
79 | ```
80 |
81 | ## Deployment
82 |
83 | ### GitHub Pages
84 |
85 | The site is automatically deployed to GitHub Pages when changes are pushed to the `main` branch in the `docs-site-v2/` directory.
86 |
87 | **Deployment Process:**
88 | 1. GitHub Actions workflow triggers on push to `main`
89 | 2. Node.js 18 environment is set up
90 | 3. Dependencies are installed with `npm ci`
91 | 4. Site is built with `NODE_ENV=production npm run build`
92 | 5. Generated `dist/` folder is deployed to GitHub Pages
93 |
94 | **Configuration:**
95 | - Base path: `/` (configured for subdomain deployment)
96 | - Build artifacts: `dist/` directory
97 | - Workflow: `.github/workflows/deploy-docs.yml`
98 |
99 | ### Manual Deployment
100 |
101 | For other static hosting services, use:
102 |
103 | ```bash
104 | npm run build
105 | ```
106 |
107 | The `dist/` folder contains all files needed for deployment to any static hosting service.
108 |
109 | ## Notes
110 |
111 | - The generated CSS file (`public/index.css`) is excluded from version control
112 | - TailwindCSS is configured to only include classes actually used in the project
113 | - CSS is automatically generated before development and build processes
114 |
```
--------------------------------------------------------------------------------
/tests/servers/sfcc-mock-server/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # SFCC Mock Server
2 |
3 | A unified mock server combining WebDAV and OCAPI functionality for SFCC (Salesforce B2C Commerce Cloud) development testing. This server provides a single endpoint for both log file access (WebDAV) and OCAPI API simulation, eliminating the need to run multiple servers during development.
4 |
5 | ## Features
6 |
7 | - 🔄 **Unified Architecture**: Single server handling both WebDAV and OCAPI requests
8 | - 📁 **WebDAV Support**: Mock log file access with PROPFIND and range request support
9 | - 🔐 **OCAPI Simulation**: OAuth authentication and system object/site preferences APIs
10 | - 🚀 **Express.js Based**: Modern, maintainable architecture with modular design
11 | - ⚙️ **Configurable**: Enable/disable features, custom ports, development mode
12 | - 🔧 **Developer Friendly**: Comprehensive logging and error handling
13 |
14 | ## Quick Start
15 |
16 | ```bash
17 | # Install dependencies
18 | npm install
19 |
20 | # Start server in development mode
21 | npm run dev
22 |
23 | # Start server on custom port
24 | npm run start:port
25 |
26 | # Start with custom configuration
27 | npm run start:custom
28 | ```
29 |
30 | ## Usage
31 |
32 | ### Basic Usage
33 |
34 | ```bash
35 | # Start with default settings (port 3000)
36 | node server.js
37 |
38 | # Development mode with verbose logging
39 | node server.js --dev
40 |
41 | # Custom port and host
42 | node server.js --port 4000 --host 0.0.0.0
43 |
44 | # Enable only WebDAV (disable OCAPI)
45 | node server.js --no-ocapi
46 |
47 | # Enable only OCAPI (disable WebDAV)
48 | node server.js --no-webdav
49 | ```
50 |
51 | ### Command Line Options
52 |
53 | | Option | Description | Default |
54 | |--------|-------------|---------|
55 | | `--port <number>` | Server port | 3000 |
56 | | `--host <string>` | Server host | localhost |
57 | | `--dev` | Enable development mode | false |
58 | | `--no-webdav` | Disable WebDAV functionality | enabled |
59 | | `--no-ocapi` | Disable OCAPI functionality | enabled |
60 | | `--no-cors` | Disable CORS headers | enabled |
61 | | `--mock-data <path>` | Custom mock data directory | ./mock-data |
62 | | `--help` | Show help message | - |
63 |
64 | ## Endpoints
65 |
66 | ### Health & Info
67 |
68 | - `GET /health` - Server health check
69 | - `GET /info` - Server information and configuration
70 |
71 | ### WebDAV Endpoints
72 |
73 | - `PROPFIND|GET /on/demandware.servlet/webdav/Sites/Logs/` - SFCC WebDAV path
74 | - `PROPFIND|GET /Logs/` - Direct logs access
75 | - `GET /Logs/jobs/` - Job logs directory
76 |
77 | ### OCAPI Endpoints
78 |
79 | - `POST /dw/oauth2/access_token` - OAuth token endpoint
80 | - `GET /s/-/dw/data/v23_2/system_object_definitions` - System objects
81 | - `POST /s/-/dw/data/v23_2/system_object_definition_search` - Search system objects
82 | - `GET /s/-/dw/data/v23_2/code_versions` - Code versions
83 | - `POST /s/-/dw/data/v23_2/code_versions/:id/activate` - Activate code version
84 |
85 | ## Authentication
86 |
87 | ### OCAPI OAuth Credentials
88 |
89 | For testing OCAPI endpoints, use these credentials:
90 |
91 | - **Client ID**: `test-client-id`
92 | - **Client Secret**: `test-client-secret`
93 | - **Grant Type**: `client_credentials`
94 |
95 | ### Example OAuth Request
96 |
97 | ```bash
98 | curl -X POST http://localhost:3000/dw/oauth2/access_token \\
99 | -H "Authorization: Basic $(echo -n 'test-client-id:test-client-secret' | base64)" \\
100 | -H "Content-Type: application/x-www-form-urlencoded" \\
101 | -d "grant_type=client_credentials"
102 | ```
103 |
104 | ## Mock Data
105 |
106 | ### Directory Structure
107 |
108 | ```
109 | mock-data/
110 | ├── logs/ # WebDAV log files
111 | │ ├── error-blade-*.log # Error logs
112 | │ ├── warn-blade-*.log # Warning logs
113 | │ ├── info-blade-*.log # Info logs
114 | │ ├── debug-blade-*.log # Debug logs
115 | │ └── jobs/ # Job logs
116 | │ └── JobName/
117 | │ └── Job-*.log
118 | └── ocapi/ # OCAPI mock responses
119 | ├── system-object-definitions.json
120 | ├── code-versions.json
121 | └── [other-mock-files].json
122 | ```
123 |
124 | ### Customizing Mock Data
125 |
126 | 1. Edit JSON files in `mock-data/ocapi/` for OCAPI responses
127 | 2. Add log files to `mock-data/logs/` for WebDAV content
128 | 3. Use `--mock-data <path>` to specify custom data directory
129 |
130 | ## Development
131 |
132 | ### Architecture
133 |
134 | The server follows modular architecture principles:
135 |
136 | ```
137 | src/
138 | ├── config/ # Configuration management
139 | ├── middleware/ # Express middleware (auth, CORS, logging)
140 | ├── routes/ # Route handlers (webdav, ocapi)
141 | └── utils/ # Utility functions (data loading, XML generation)
142 | ```
143 |
144 | ### Key Classes
145 |
146 | - **ServerConfig**: Configuration management and validation
147 | - **SFCCMockApp**: Express application setup and routing
148 | - **WebDAVRouteHandler**: WebDAV request handling with PROPFIND support
149 | - **OCAPIRouteHandler**: OCAPI endpoint simulation with authentication
150 | - **AuthenticationManager**: OAuth token generation and validation
151 |
152 | ### Adding New Features
153 |
154 | 1. **New OCAPI Endpoints**: Add routes in `src/routes/ocapi.js`
155 | 2. **WebDAV Extensions**: Modify `src/routes/webdav.js`
156 | 3. **Middleware**: Add to `src/middleware/`
157 | 4. **Mock Data**: Add JSON files to `mock-data/ocapi/`
158 |
159 | ## Testing
160 |
161 | The server is designed to work with the SFCC Development MCP Server test suite:
162 |
163 | ```bash
164 | # Run with the unified server for testing
165 | node server.js --dev --port 3000
166 |
167 | # Test WebDAV functionality
168 | curl -X PROPFIND http://localhost:3000/Logs/
169 |
170 | # Test OCAPI functionality
171 | curl -X POST http://localhost:3000/dw/oauth2/access_token \\
172 | -H "Authorization: Basic $(echo -n 'test-client-id:test-client-secret' | base64)" \\
173 | -d "grant_type=client_credentials"
174 | ```
175 |
176 | ## Troubleshooting
177 |
178 | ### Common Issues
179 |
180 | 1. **Port already in use**: Use `--port <different-port>`
181 | 2. **Missing mock data**: Ensure `mock-data/` directory exists with proper structure
182 | 3. **CORS errors**: Enable CORS with `--cors` (enabled by default)
183 | 4. **Authentication failing**: Verify OAuth credentials match test values
184 |
185 | ### Debug Mode
186 |
187 | Enable development mode for detailed logging:
188 |
189 | ```bash
190 | node server.js --dev
191 | ```
192 |
193 | This will show:
194 | - All incoming requests with headers and body
195 | - All outgoing responses with status codes
196 | - File system operations and path mappings
197 | - Authentication token generation and validation
198 |
199 | ## Contributing
200 |
201 | 1. Follow the modular architecture patterns
202 | 2. Add tests for new functionality
203 | 3. Update documentation for new endpoints or features
204 | 4. Ensure backward compatibility with existing tests
205 |
206 | ## License
207 |
208 | MIT License - See LICENSE file for details
```
--------------------------------------------------------------------------------
/tests/mcp/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Testing Documentation
2 |
3 | This document describes the MCP (Model Context Protocol) tests for the SFCC Development MCP Server.
4 |
5 | ## Overview
6 |
7 | The project includes comprehensive MCP tests using both **YAML** and **Node.js** approaches with the [mcp-aegis](https://aegis.rhino-inquisitor.com/) testing library. The tests verify both **documentation-only mode** and **full mode with credentials**.
8 |
9 | ## Test Structure
10 |
11 | ```
12 | tests/mcp/
13 | ├── AGENTS.md # AI agent guide for MCP testing
14 | ├── yaml/
15 | │ ├── AGENTS.md # YAML-specific agent guide
16 | │ ├── docs-only.test.mcp.yml # Documentation-only mode YAML tests
17 | │ └── full-mode.test.mcp.yml # Full mode YAML tests
18 | ├── node/
19 | │ ├── AGENTS.md # Node.js-specific agent guide
20 | │ ├── docs-only.programmatic.test.js # Documentation-only mode Node.js tests
21 | │ └── full-mode.programmatic.test.js # Full mode Node.js tests
22 | └── test-fixtures/
23 | └── dw.json # Test SFCC credentials configuration
24 | ```
25 |
26 | ## Configuration Files
27 |
28 | ### Documentation-Only Mode
29 | - **File**: `aegis.config.docs-only.json`
30 | - **Command**: `node dist/index.js` (no credentials)
31 | - **Tools**: 15 tools (documentation, best practices, SFRA, cartridge generation)
32 |
33 | ### Full Mode with Credentials
34 | - **File**: `aegis.config.with-dw.json`
35 | - **Command**: `node dist/index.js --dw-json ./tests/mcp/test-fixtures/dw.json`
36 | - **Tools**: 36 tools (includes log analysis, system objects, job logs, code versions)
37 |
38 | ## Available Test Commands
39 |
40 | ### YAML Testing
41 | ```bash
42 | # Documentation-only mode
43 | npm run test:mcp:yaml
44 |
45 | # Full mode with credentials (requires valid SFCC instance)
46 | npm run test:mcp:yaml:full
47 |
48 | # Manual execution with specific config
49 | aegis 'tests/mcp/yaml/*.test.mcp.yml' --config './aegis.config.docs-only.json'
50 | ```
51 |
52 | ### Node.js Programmatic Testing
53 | ```bash
54 | # All programmatic tests
55 | npm run test:mcp:node
56 |
57 | # Manual execution
58 | node --test 'tests/mcp/node/*.programmatic.test.js'
59 | ```
60 |
61 | ### Combined Testing
62 | ```bash
63 | # All MCP tests
64 | npm run test:mcp:all
65 |
66 | # All project tests (Jest + MCP)
67 | npm run test:all
68 |
69 | # CI-friendly format with JSON output
70 | npm run test:mcp:ci
71 | ```
72 |
73 | ## Test Categories
74 |
75 | ### 1. Protocol Compliance Tests
76 | - **Tools list validation**: Ensures tools are properly registered
77 | - **JSON-RPC 2.0 compliance**: Validates request/response format
78 | - **Error handling**: Tests invalid tool calls and missing parameters
79 |
80 | ### 2. Documentation-Only Mode Tests
81 | - **SFCC Documentation Tools** (5 tools): Class info, search, method discovery
82 | - **Best Practices Tools** (4 tools): Guides, search, hook references
83 | - **SFRA Documentation Tools** (5 tools): Documents, search, categories
84 | - **Cartridge Generation Tools** (1 tool): Structure generation
85 | - **Tool Availability**: Verifies log/OCAPI tools are NOT available
86 |
87 | ### 3. Full Mode Tests
88 | - **All Documentation Tools**: Same as documentation-only mode
89 | - **Log Analysis Tools** (8 tools): Error/warn/info/debug logs, search, summarization
90 | - **Job Log Tools** (5 tools): Job log files, entries, search, execution summaries
91 | - **System Object Tools** (6 tools): System objects, attributes, site preferences
92 | - **Code Version Tools** (2 tools): List and activate code versions
93 | - **Authentication Testing**: Graceful handling of connection failures
94 |
95 | ### 4. Performance and Reliability Tests
96 | - **Response Time Validation**: Ensures reasonable performance
97 | - **Concurrent Request Handling**: Tests multiple simultaneous requests
98 | - **Error Recovery**: Validates graceful failure modes
99 | - **Schema Consistency**: Ensures all tools follow MCP standards
100 |
101 | ## Test Patterns Used
102 |
103 | ### YAML Pattern Matching
104 | - **Type validation**: `"match:type:array"`, `"match:type:string"`
105 | - **Content matching**: `"match:contains:expected_text"`
106 | - **Array operations**: `"match:arrayContains:item"`, `"match:arrayLength:15"`
107 | - **Field extraction**: `"match:extractField: "tools.*.name"`
108 | - **Regex patterns**: `"match:regex:[\\s\\S]*pattern[\\s\\S]*"` (multiline safe)
109 | - **Negation**: `"match:not:arrayContains:unwanted_item"`
110 |
111 | ### Node.js Assertions
112 | - **Protocol validation**: JSON-RPC 2.0 compliance checking
113 | - **Tool schema validation**: Input/output schema verification
114 | - **Dynamic testing**: Programmatic test generation and validation
115 | - **Error boundary testing**: Exception handling and meaningful error messages
116 |
117 | ## Running Tests
118 |
119 | ### Prerequisites
120 | ```bash
121 | # Ensure project is built
122 | npm run build
123 |
124 | # Install dependencies (already included)
125 | npm install
126 | ```
127 |
128 | ### Documentation-Only Testing (No Credentials Required)
129 | ```bash
130 | # YAML tests
131 | npm run test:mcp:yaml
132 |
133 | # Programmatic tests
134 | npm run test:mcp:node
135 |
136 | # Both approaches
137 | npm run test:mcp:all
138 | ```
139 |
140 | ### Full Mode Testing (Requires SFCC Instance)
141 | To test full functionality:
142 |
143 | 1. **Update test credentials** in `tests/mcp/test-fixtures/dw.json`:
144 | ```json
145 | {
146 | "version": "1.0.0",
147 | "hostname": "your-instance.sandbox.us01.dx.commercecloud.salesforce.com",
148 | "username": "your-username",
149 | "password": "your-password",
150 | "client-id": "your-client-id",
151 | "client-secret": "your-client-secret",
152 | "code-version": "your-code-version",
153 | "cartridgesPath": "./cartridges"
154 | }
155 | ```
156 |
157 | 2. **Run full mode tests**:
158 | ```bash
159 | npm run test:mcp:yaml:full
160 | ```
161 |
162 | **Note**: Full mode tests expect connection failures with test credentials and verify graceful error handling.
163 |
164 | ## Test Coverage
165 |
166 | ### Tools Tested in Documentation-Only Mode (15 tools)
167 | 1. `get_sfcc_class_info` - SFCC class information
168 | 2. `search_sfcc_classes` - SFCC class search
169 | 3. `search_sfcc_methods` - SFCC method search
170 | 4. `list_sfcc_classes` - Complete SFCC class list
171 | 5. `get_sfcc_class_documentation` - Raw SFCC class documentation
172 | 6. `get_available_best_practice_guides` - Best practices list
173 | 7. `get_best_practice_guide` - Specific best practice guide
174 | 8. `search_best_practices` - Best practices search
175 | 9. `get_hook_reference` - Hook reference tables
176 | 10. `get_available_sfra_documents` - SFRA documents list
177 | 11. `get_sfra_document` - Specific SFRA document
178 | 12. `search_sfra_documentation` - SFRA documentation search
179 | 13. `get_sfra_documents_by_category` - SFRA documents by category
180 | 14. `get_sfra_categories` - SFRA document categories
181 | 15. `generate_cartridge_structure` - Cartridge generation
182 |
183 | ### Additional Tools in Full Mode (+21 tools = 36 total)
184 |
185 | **Log Analysis Tools (8)**:
186 | - `get_latest_error`, `get_latest_warn`, `get_latest_info`, `get_latest_debug`
187 | - `summarize_logs`, `search_logs`, `list_log_files`, `get_log_file_contents`
188 |
189 | **Job Log Tools (5)**:
190 | - `get_latest_job_log_files`, `search_job_logs_by_name`, `get_job_log_entries`
191 | - `search_job_logs`, `get_job_execution_summary`
192 |
193 | **System Object Tools (6)**:
194 | - `get_system_object_definitions`, `get_system_object_definition`
195 | - `search_system_object_attribute_definitions`, `search_site_preferences`
196 | - `search_system_object_attribute_groups`, `search_custom_object_attribute_definitions`
197 |
198 | **Code Version Tools (2)**:
199 | - `get_code_versions`, `activate_code_version`
200 |
201 | ## Debugging Tests
202 |
203 | ### Enable Verbose Output
204 | ```bash
205 | # YAML tests with debugging
206 | aegis 'tests/mcp/yaml/*.test.mcp.yml' --config './aegis.config.docs-only.json' --verbose --debug
207 |
208 | # Check server logs
209 | npm run dev -- --debug true
210 | ```
211 |
212 | ### Common Issues
213 | - **Build Required**: Always run `npm run build` before testing
214 | - **Tool Count Mismatches**: Verify tool counts with `npx aegis query`
215 | - **Connection Failures**: Expected in full mode with test credentials
216 | - **Path Issues**: Use absolute paths in aegis config files
217 |
218 | ## Contributing
219 |
220 | When adding new tools or modifying existing ones:
221 |
222 | 1. **Update test files** to include new tools
223 | 2. **Verify tool counts** using `npx aegis query`
224 | 3. **Test both modes** to ensure proper tool availability
225 | 4. **Update documentation** with new tool descriptions
226 | 5. **Run full test suite** before committing
227 |
228 | ## Resources
229 |
230 | - **[MCP Aegis Documentation](https://aegis.rhino-inquisitor.com/)**: Complete testing framework guide
231 | - **[YAML Testing Guide](./yaml/AGENTS.md)**: Declarative testing patterns
232 | - **[Node.js Testing Guide](./node/AGENTS.md)**: Programmatic testing patterns
233 | - **[MCP Protocol Specification](https://modelcontextprotocol.io/)**: Protocol standards
234 |
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # SFCC Development MCP Server
2 |
3 | [](https://badge.fury.io/js/sfcc-dev-mcp)
4 | [](https://opensource.org/licenses/MIT)
5 |
6 | An AI-powered Model Context Protocol (MCP) server that provides comprehensive access to Salesforce B2C Commerce Cloud development tools, documentation, and best practices.
7 |
8 | ## ✨ Key Features
9 |
10 | - **🔍 Complete SFCC Documentation Access** - Search and explore all SFCC API classes and methods
11 | - **📚 Best Practices Guides** - Curated development guidelines for cartridges, hooks, controllers, client-side JavaScript, and more
12 | - **🏗️ SFRA Documentation** - Enhanced access to Storefront Reference Architecture documentation
13 | - **📊 Log Analysis Tools** - Real-time error monitoring, debugging, and job log analysis for SFCC instances
14 | - **⚙️ System Object Definitions** - Explore custom attributes and site preferences
15 | - **🚀 Cartridge Generation** - Automated cartridge structure creation
16 |
17 | ## 🚀 Quick Start
18 |
19 | ### Option 1: Documentation-Only Mode (No SFCC credentials needed)
20 | ```json
21 | {
22 | "mcpServers": {
23 | "sfcc-dev": {
24 | "command": "npx",
25 | "args": ["sfcc-dev-mcp"]
26 | }
27 | }
28 | }
29 | ```
30 |
31 | ### Option 2: Full Mode (With SFCC credentials for log and job analysis)
32 | ```json
33 | {
34 | "mcpServers": {
35 | "sfcc-dev": {
36 | "command": "npx",
37 | "args": ["sfcc-dev-mcp", "--dw-json", "/path/to/your/dw.json"]
38 | }
39 | }
40 | }
41 | ```
42 |
43 | Create a `dw.json` file with your SFCC credentials:
44 | ```json
45 | {
46 | "hostname": "your-instance.sandbox.us01.dx.commercecloud.salesforce.com",
47 | "username": "your-username",
48 | "password": "your-password",
49 | "client-id": "your-client-id",
50 | "client-secret": "your-client-secret"
51 | }
52 | ```
53 |
54 | ## 🎯 Operating Modes
55 |
56 | | Mode | Tools Available | SFCC Credentials Required |
57 | |------|----------------|---------------------------|
58 | | **Documentation-Only** | 15 tools | ❌ No |
59 | | **Full Mode** | 36 tools | ✅ Yes |
60 |
61 | ### Documentation-Only Mode
62 | Perfect for learning and development - no SFCC instance required:
63 | - Complete SFCC API documentation (5 tools)
64 | - Best practices guides (4 tools) – cartridges, client-side JavaScript, controllers, hooks, security/performance
65 | - SFRA documentation (5 tools)
66 | - Cartridge generation (1 tool)
67 |
68 | ### Full Mode
69 | Complete development experience with live SFCC instance access:
70 | - All documentation-only features (15 tools)
71 | - Real-time log analysis (13 tools)
72 | - System object definitions (6 tools)
73 | - Code version management (2 tools)
74 |
75 | ## � Architecture Overview
76 |
77 | This server is built around a **capability-gated, modular handler architecture** that cleanly separates tool routing from domain logic:
78 |
79 | ### Core Layers
80 | - **Tool Definitions** (`src/core/tool-definitions.ts`): Declarative schemas grouped by category (documentation, best practices, SFRA, logs, job logs, system objects, cartridge generation, code versions).
81 | - **Handlers** (`src/core/handlers/*.ts`): Each category has a handler extending a common base for timing, structured logging, and error normalization (e.g. `log-handler`, `docs-handler`, `system-object-handler`).
82 | - **Clients** (`src/clients/`): Encapsulate domain operations (OCAPI, SFRA docs, best practices, modular log analysis). Handlers delegate to these so orchestration and computation remain separate.
83 | - **Services** (`src/services/`): Dependency-injected abstractions for filesystem and path operations — improves testability and isolates side effects.
84 | - **Modular Log System** (`src/clients/logs/`): Reader (range/tail optimization), discovery, processor (line → structured entry), analyzer (patterns & health), formatter (human output) for maintainable evolution.
85 | - **Configuration Factory** (`src/config/configuration-factory.ts`): Determines capabilities (`canAccessLogs`, `canAccessOCAPI`) based on provided credentials and filters exposed tools accordingly (principle of least privilege).
86 |
87 | ### Why This Matters
88 | - **Extensibility**: Adding a new tool usually means adding a schema + minimal handler logic (or a new handler if a new domain).
89 | - **Security**: Tools that require credentials are never exposed when capability flags are false.
90 | - **Testability**: Unit tests target clients & modules; integration/MCP tests validate handler routing and response structure.
91 | - **Performance**: Tail log reads + lightweight caching (`cache.ts`, `log-cache.ts`) reduce unnecessary I/O.
92 |
93 | ### Adding a New Tool (High-Level)
94 | 1. Add schema object to the correct exported array in `tool-definitions.ts`.
95 | 2. Implement domain logic in a client/service (avoid bloating handlers).
96 | 3. Extend an existing handler or create a new one if it's a new category.
97 | 4. (Only for a new category) register the new handler inside `registerHandlers()` in `server.ts`.
98 | 5. Discover actual response shape with `npx mcp-aegis query` before writing tests.
99 | 6. Add Jest unit tests + YAML MCP tests (docs vs full mode if credentials required).
100 | 7. Update documentation (Development Guide + README counts if changed).
101 |
102 | > For a deeper internal view, see the Development Guide in the docs site.
103 |
104 | ## �🤖 AI Interface Setup
105 |
106 | Choose your preferred AI assistant:
107 |
108 | | Interface | Best For | Setup Guide |
109 | |-----------|----------|-------------|
110 | | **Claude Desktop** | Multi-turn conversations, debugging | [📖 Setup Guide](https://taurgis.github.io/sfcc-dev-mcp/ai-interfaces#claude-desktop) |
111 | | **GitHub Copilot** | VS Code integration, inline suggestions | [📖 Setup Guide](https://taurgis.github.io/sfcc-dev-mcp/ai-interfaces#github-copilot) |
112 | | **Cursor** | Modern AI-powered editor | [📖 Setup Guide](https://taurgis.github.io/sfcc-dev-mcp/ai-interfaces#cursor) |
113 |
114 | ## 📦 Installation
115 |
116 | ### Using npx (Recommended)
117 | > Tip: Add `-y` (or `--yes`) to suppress the interactive prompt npx shows before downloading a package. This prevents AI clients (Claude Desktop, Copilot, Cursor) from hanging waiting for confirmation.
118 | ```bash
119 | # Test the server
120 | npx -y sfcc-dev-mcp
121 |
122 | # Use with your configuration
123 | npx -y sfcc-dev-mcp --dw-json /path/to/your/dw.json
124 | ```
125 |
126 | ### Global Installation
127 | ```bash
128 | npm install -g sfcc-dev-mcp
129 | sfcc-dev-mcp --dw-json /path/to/your/dw.json
130 | ```
131 |
132 | ## 🐛 Debug Mode & Logging
133 |
134 | ### Enable Debug Logging
135 | ```bash
136 | # Enable debug mode for detailed logging
137 | npx -y sfcc-dev-mcp --debug
138 |
139 | # Or with configuration file
140 | npx -y sfcc-dev-mcp --dw-json /path/to/your/dw.json --debug
141 | ```
142 |
143 | ### Log File Locations
144 |
145 | The server writes logs to your system's temporary directory:
146 |
147 | - **macOS**: `/var/folders/{user-id}/T/sfcc-mcp-logs/`
148 | - **Linux**: `/tmp/sfcc-mcp-logs/`
149 | - **Windows**: `%TEMP%\sfcc-mcp-logs\`
150 |
151 | **Log Files Created:**
152 | - `sfcc-mcp-info.log` - General application logs and startup messages
153 | - `sfcc-mcp-debug.log` - Detailed debug information (only when `--debug` is enabled)
154 | - `sfcc-mcp-error.log` - Error messages and stack traces
155 | - `sfcc-mcp-warn.log` - Warning messages
156 |
157 | ### Finding Your Log Directory
158 | ```javascript
159 | // The exact path varies by system - to find yours:
160 | node -e "console.log(require('os').tmpdir() + '/sfcc-mcp-logs')"
161 |
162 | ## 📖 Documentation
163 |
164 | **📚 [Complete Documentation](https://taurgis.github.io/sfcc-dev-mcp/)** - Comprehensive guides and references
165 |
166 | Quick Links:
167 | - **[Installation Guide](https://taurgis.github.io/sfcc-dev-mcp/installation)** - Detailed installation options
168 | - **[AI Interface Setup](https://taurgis.github.io/sfcc-dev-mcp/ai-interfaces)** - Configure Claude Desktop, GitHub Copilot, or Cursor
169 | - **[Configuration Guide](https://taurgis.github.io/sfcc-dev-mcp/configuration)** - SFCC credentials and Data API setup
170 | - **[Available Tools](https://taurgis.github.io/sfcc-dev-mcp/tools)** - Complete tool reference
171 | - **[Examples](https://taurgis.github.io/sfcc-dev-mcp/examples)** - Real-world usage patterns
172 | - **[Troubleshooting](https://taurgis.github.io/sfcc-dev-mcp/troubleshooting)** - Common issues and solutions
173 |
174 | ## 🛠️ Example AI Interactions
175 |
176 | ```
177 | 🧑💻 "Create a new SFCC controller for product search"
178 | 🤖 Generates complete controller with proper imports, route handling, and SFRA patterns
179 |
180 | 🧑💻 "What's wrong with my checkout flow? Check the logs"
181 | 🤖 Analyzes recent error logs, identifies issues, and suggests fixes
182 |
183 | 🧑💻 "Show me how to implement OCAPI hooks for order validation"
184 | 🤖 Provides best practices guide with complete hook implementation examples
185 | ```
186 |
187 | ## 🔒 Security Notes
188 |
189 | - **Local Development Focus**: Designed for individual developer use on local machines
190 | - **Credential Protection**: dw.json files should never be committed to version control
191 | - **Network Security**: All API calls use HTTPS with proper authentication
192 | - **No Data Storage**: Server doesn't persist any SFCC data locally
193 |
194 | ## 🔮 Future Plans
195 |
196 | We're continuously improving the SFCC Development MCP Server with exciting new features planned:
197 |
198 | ### 🎯 Upcoming Enhancements
199 |
200 | - **🧠 Smarter Log Fetching** - Enhanced log analysis with intelligent filtering, pattern recognition, and contextual error correlation
201 | - **🚀 Deployment Tools** - Integration with SFCC deployment processes and code version management
202 |
203 | ### 🤝 We Welcome Your Contributions!
204 |
205 | Have ideas for new features or improvements? We'd love to hear from you!
206 |
207 | - **💡 Feature Requests**: Open an issue to discuss your ideas
208 | - **🐛 Bug Reports**: Help us improve by reporting any issues you encounter
209 | - **🔧 Pull Requests**: Contribute code, documentation, or examples
210 | - **📚 Documentation**: Help expand our guides and best practices
211 |
212 | Check out our [Contributing Guide](CONTRIBUTING.md) to get started, or browse our [open issues](https://github.com/taurgis/sfcc-dev-mcp/issues) to see where you can help.
213 |
214 | **Your expertise and feedback make this tool better for the entire SFCC community!**
215 |
216 | ## 🤝 Contributing
217 |
218 | We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
219 |
220 | ## 📄 License
221 |
222 | This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
223 |
224 | ---
225 |
226 | **🚀 Ready to supercharge your SFCC development with AI?**
227 |
228 | **[📖 Get Started with the Full Documentation](https://taurgis.github.io/sfcc-dev-mcp/)**
229 |
```
--------------------------------------------------------------------------------
/SECURITY.md:
--------------------------------------------------------------------------------
```markdown
1 | # Security Policy
2 |
3 | ## Supported Versions
4 |
5 | We actively maintain and provide security updates for the following versions:
6 |
7 | | Version | Supported |
8 | | ------- | ------------------ |
9 | | 1.x.x | :white_check_mark: |
10 | | < 1.0 | :x: |
11 |
12 | ## Reporting a Vulnerability
13 |
14 | We take the security of the SFCC Development MCP Server seriously. If you discover a security vulnerability, please follow these steps:
15 |
16 | ### 🔒 Private Disclosure
17 |
18 | **Please do NOT report security vulnerabilities through public GitHub issues.**
19 |
20 | Instead, please report security vulnerabilities by:
21 |
22 | 1. **GitHub Security Advisories**: Use GitHub's private vulnerability reporting feature at [https://github.com/taurgis/sfcc-dev-mcp/security/advisories](https://github.com/taurgis/sfcc-dev-mcp/security/advisories)
23 |
24 | ### 📋 What to Include
25 |
26 | When reporting a vulnerability, please include:
27 |
28 | - **Description**: Clear description of the vulnerability
29 | - **Impact**: Potential impact and attack scenarios
30 | - **Reproduction**: Step-by-step instructions to reproduce the issue
31 | - **Environment**: Version, operating system, and configuration details
32 | - **Evidence**: Screenshots, logs, or proof-of-concept code (if applicable)
33 |
34 | ### ⏰ Response Timeline
35 |
36 | We are committed to addressing security vulnerabilities promptly:
37 |
38 | - **Initial Response**: Within 48 hours of report
39 | - **Acknowledgment**: Within 7 days with initial assessment
40 | - **Resolution**: Security patches released within 30 days for high-severity issues
41 | - **Disclosure**: Coordinated disclosure after patch is available
42 |
43 | ## Security Considerations
44 |
45 | ### 🎯 Scope
46 |
47 | This security policy covers vulnerabilities in:
48 |
49 | - **Core MCP Server**: Authentication, data handling, API access
50 | - **SFCC Integration**: OAuth flows, credential management, data exposure
51 | - **Documentation Access**: Information disclosure, access control
52 | - **Log Analysis**: Sensitive data exposure, injection vulnerabilities
53 | - **Dependencies**: Third-party package vulnerabilities
54 |
55 | ### ⚠️ What We Consider Security Issues
56 |
57 | - **Authentication bypass** in SFCC credential handling
58 | - **Sensitive data exposure** in logs or responses
59 | - **Code injection** through tool parameters
60 | - **Unauthorized access** to SFCC instances
61 | - **Credential leakage** in configuration or cache
62 | - **Path traversal** in file operations
63 | - **Denial of service** through resource exhaustion
64 | - **Dependency vulnerabilities** with exploitable impact
65 |
66 | ### ✅ What We Don't Consider Security Issues
67 |
68 | - **Rate limiting** on local development tools
69 | - **Information disclosure** of public SFCC documentation
70 | - **Resource usage** in normal operation scenarios
71 | - **Configuration errors** by end users
72 | - **Network connectivity** issues
73 | - **Feature requests** or usability improvements
74 |
75 | ## Security Best Practices
76 |
77 | ### 🔐 For Users
78 |
79 | 1. **Credential Protection**:
80 | - Store SFCC credentials securely in `dw.json`
81 | - Use environment variables for sensitive configuration
82 | - Regularly rotate API credentials
83 | - Never commit credentials to version control
84 |
85 | 2. **Network Security**:
86 | - Use HTTPS connections to SFCC instances
87 | - Verify SSL certificates in production
88 | - Restrict network access to development instances
89 |
90 | 3. **Local Security**:
91 | - Keep the MCP server updated
92 | - Review log outputs for sensitive data
93 | - Use proper file permissions on configuration files
94 |
95 | ### 🛡️ For Developers
96 |
97 | 1. **Input Validation**:
98 | - Validate all tool parameters
99 | - Sanitize user inputs before processing
100 | - Use type-safe parameter parsing
101 |
102 | 2. **Data Handling**:
103 | - Minimize sensitive data in logs
104 | - Implement proper error handling
105 | - Use secure HTTP clients with proper timeouts
106 |
107 | 3. **Dependency Management**:
108 | - Regularly update dependencies
109 | - Monitor for security advisories
110 | - Use `npm audit` to check for vulnerabilities
111 |
112 | ## Security Features
113 |
114 | ### 🔒 Built-in Security
115 |
116 | - **OAuth 2.0 Authentication** for SFCC OCAPI access
117 | - **Secure credential storage** with local file protection
118 | - **Input validation** on all tool parameters
119 | - **Rate limiting** on external API calls
120 | - **Secure HTTP clients** with proper error handling
121 | - **Minimal privilege principle** for SFCC permissions
122 |
123 | ### 📊 Security Monitoring
124 |
125 | - **Dependency scanning** via GitHub Dependabot
126 | - **Code quality checks** in CI/CD pipeline
127 | - **Security-focused linting** rules
128 | - **Regular security audits** of dependencies
129 |
130 | ## Responsible Disclosure
131 |
132 | We believe in responsible disclosure and will work with security researchers to:
133 |
134 | 1. **Acknowledge** your contribution
135 | 2. **Keep you informed** of our progress
136 | 3. **Credit you appropriately** (unless you prefer to remain anonymous)
137 | 4. **Coordinate timing** of public disclosure
138 |
139 | ## Contact
140 |
141 | For security-related questions or concerns:
142 |
143 | - **GitHub**: [@taurgis](https://github.com/taurgis)
144 | - **Project**: [sfcc-dev-mcp](https://github.com/taurgis/sfcc-dev-mcp)
145 |
146 | ---
147 |
148 | Thank you for helping keep the SFCC Development MCP Server and its users safe! 🛡️
```
--------------------------------------------------------------------------------
/tests/mcp/AGENTS.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Aegis - AI Agent Guide
2 |
3 | **Target Audience**: AI coding assistants, automated testing agents, and AI-powered development tools
4 |
5 | ## Overview
6 |
7 | # MCP Aegis - AI Agent Guide
8 |
9 | ## 🎯 About This Project
10 |
11 | This project uses **MCP Aegis** for testing Model Context Protocol (MCP) servers.
12 |
13 | **MCP Aegis** is a comprehensive Node.js testing library for Model Context Protocol (MCP) servers. It provides both **declarative YAML-based testing** and **programmatic JavaScript/TypeScript testing** with 35+ verified pattern matching capabilities including exact numeric equality, floating-point tolerance, decimal precision validation, modular arithmetic, and comprehensive date/timestamp validation.
14 |
15 | ## 📁 Dedicated Agent Guides
16 |
17 | This guide has been restructured into focused, dedicated guides for each testing approach:
18 |
19 | ### **[YAML Testing Guide](./yaml/AGENTS.md)**
20 | - **Focus**: Declarative, human-readable test files
21 | - **Best For**: Protocol compliance, basic tool testing, maintainable test suites
22 | - **Audience**: Agents generating `.test.mcp.yml` files
23 | - **Key Features**: 35+ pattern matching types including exact numeric equality, floating-point tolerance, decimal precision validation, modular arithmetic, and date/timestamp validation, CLI debugging, no programming required
24 |
25 | ### **[Programmatic Testing Guide](./node/AGENTS.md)**
26 | - **Focus**: JavaScript/TypeScript API integration
27 | - **Best For**: Complex validation, existing test suites, multi-step workflows
28 | - **Audience**: Agents generating `.programmatic.test.js` files
29 | - **Key Features**: Jest/Mocha integration, dynamic validation, performance testing
30 |
31 | ## Quick Decision Matrix
32 |
33 | | Use Case | YAML Testing | Programmatic Testing |
34 | |----------|--------------|---------------------|
35 | | **Protocol compliance** | ✅ Excellent | ✅ Excellent |
36 | | **Simple tool testing** | ✅ Perfect | ⚠️ Overkill |
37 | | **Pattern matching** | ✅ 29+ built-in types | ⚠️ Manual assertions |
38 | | **Complex validation** | ⚠️ Limited logic | ✅ Full JavaScript |
39 | | **Multi-step workflows** | ❌ Not supported | ✅ Perfect |
40 | | **Existing test suites** | ❌ Separate runner | ✅ Jest/Mocha/Node.js |
41 | | **CI/CD integration** | ✅ JSON output | ✅ Standard test runners |
42 | | **Maintenance** | ✅ Declarative | ⚠️ Code maintenance |
43 |
44 | ## 📚 Additional Resources
45 |
46 | ### Documentation
47 | - **[Complete Documentation](https://aegis.rhino-inquisitor.com/)** - Full guide and reference
48 | - **[Installation](https://aegis.rhino-inquisitor.com/installation.html)** | **[Quick Start](https://aegis.rhino-inquisitor.com/quick-start.html)**
49 | - **[Pattern Matching](https://aegis.rhino-inquisitor.com/pattern-matching.html)** | **[Examples](https://aegis.rhino-inquisitor.com/examples.html)**
50 |
51 | ### MCP Architecture for AI Agents
52 | ```
53 | AI Agent → MCP Client → MCP Server → Tools/Services
54 | ↓
55 | MCP Aegis → Test Validation → Quality Assurance
56 | ```
57 |
58 | **Common Tool Categories**: Data retrieval, content generation, external services, analysis tools, component libraries, knowledge bases
59 |
60 | ## Universal Setup
61 |
62 | Both testing approaches require initial configuration:
63 |
64 | ### 1. Installation
65 | ```bash
66 | npm install -g mcp-aegis
67 | # OR
68 | npm install --save-dev mcp-aegis
69 | # OR use init to auto-install
70 | npx mcp-aegis init
71 | ```
72 |
73 | ### 2. Configuration File (`aegis.config.json`)
74 | ```json
75 | {
76 | "name": "My MCP Server",
77 | "command": "node",
78 | "args": ["./server.js"],
79 | "startupTimeout": 5000,
80 | "env": {
81 | "NODE_ENV": "test"
82 | }
83 | }
84 | ```
85 |
86 | ### 3. Test Execution
87 | ```bash
88 | # YAML Testing
89 | aegis "tests/**/*.test.mcp.yml" --config "aegis.config.json"
90 |
91 | # Programmatic Testing
92 | node --test "tests/**/*.programmatic.test.js"
93 |
94 | # Interactive debugging (NEW): Test individual tools without files
95 | aegis query --config "aegis.config.json" # List tools
96 | aegis query tool_name '{"param": "value"}' --config "config.json" # Test tool
97 | ```
98 |
99 | ## When to Use Each Approach
100 |
101 | ### Choose YAML Testing When:
102 | - Testing basic MCP protocol compliance
103 | - Validating simple tool executions
104 | - Creating maintainable test suites for non-developers
105 | - Using built-in pattern matching is sufficient
106 | - CI/CD needs declarative test definitions
107 |
108 | ### Choose Programmatic Testing When:
109 | - Integration with existing JavaScript/TypeScript test suites
110 | - Complex validation logic required
111 | - Multi-step agent workflows need testing
112 | - Dynamic test case generation needed
113 | - Performance testing and monitoring required
114 |
115 | ### Use Query Command For:
116 | - **Rapid development**: Test tools immediately during development
117 | - **Server validation**: Verify server behavior before writing comprehensive tests
118 | - **Tool discovery**: Explore available tools and understand their signatures
119 | - **Debugging**: Inspect exact responses and error conditions
120 | - **Prototyping**: Quick validation during MCP server development
121 |
122 | ## Integration Examples
123 |
124 | ### GitHub Copilot Integration
125 | Add to `.github/copilot-instructions.md`:
126 | ```markdown
127 | ## MCP Testing Standards
128 | 1. Use MCP Aegis for all MCP server testing
129 | 2. Create both YAML (protocol) and programmatic (complex) tests
130 | 3. Reference dedicated guides:
131 | - YAML: ./AGENTS/yaml/AGENTS.md
132 | - Code: ./AGENTS/node/AGENTS.md
133 | 4. Follow 35+ verified pattern matching types including numeric comparisons
134 | 5. Ensure JSON-RPC 2.0 compliance
135 | ```
136 |
137 | ### NPM Scripts Integration
138 | ```json
139 | {
140 | "scripts": {
141 | "test:mcp:yaml": "aegis 'tests/**/*.test.mcp.yml' --config './aegis.config.json'",
142 | "test:mcp:code": "node --test 'tests/**/*.programmatic.test.js'",
143 | "test:mcp:all": "npm run test:mcp:yaml && npm run test:mcp:code",
144 | "test:mcp:ci": "npm run test:mcp:yaml -- --json && npm run test:mcp:code",
145 | "debug:mcp:tools": "aegis query --config './aegis.config.json'",
146 | "debug:mcp:tool": "aegis query"
147 | }
148 | }
149 | ```
150 |
151 | **Usage examples**:
152 | ```bash
153 | npm run test:mcp:all # Run all tests
154 | npm run debug:mcp:tools # List available tools
155 | npm run debug:mcp:tool read_file '{"path": "test.txt"}' # Test specific tool
156 | ```
157 |
158 | ---
159 |
160 | **For detailed implementation guidance, see the dedicated guides:**
161 | - **[YAML Testing Guide](./yaml/AGENTS.md)** - Pattern matching, CLI options, real examples
162 | - **[Programmatic Testing Guide](./node/AGENTS.md)** - API reference, frameworks, advanced scenarios
163 |
```
--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
```markdown
1 | # Contributing to SFCC Development MCP Server
2 |
3 | Thank you for your interest in contributing to the SFCC Development MCP Server! This project provides MCP tools for Salesforce B2C Commerce Cloud development assistance, including documentation access, best practices guides, log analysis, and system object definitions.
4 |
5 | ## Table of Contents
6 |
7 | - [Getting Started](#getting-started)
8 | - [Development Setup](#development-setup)
9 | - [Project Structure](#project-structure)
10 | - [Contributing Guidelines](#contributing-guidelines)
11 | - [Types of Contributions](#types-of-contributions)
12 | - [Development Workflow](#development-workflow)
13 | - [Testing](#testing)
14 | - [Code Style](#code-style)
15 | - [Documentation](#documentation)
16 | - [Submitting Changes](#submitting-changes)
17 | - [Release Process](#release-process)
18 |
19 | ## Getting Started
20 |
21 | ### Prerequisites
22 |
23 | - Node.js (version 18 or higher)
24 | - npm or yarn
25 | - Git
26 | - SFCC instance access (for testing full mode features)
27 |
28 | ### Fork and Clone
29 |
30 | 1. Fork the repository on GitHub
31 | 2. Clone your fork locally:
32 | ```bash
33 | git clone https://github.com/YOUR_USERNAME/sfcc-dev-mcp.git
34 | cd sfcc-dev-mcp
35 | ```
36 |
37 | ## Development Setup
38 |
39 | 1. Install dependencies:
40 | ```bash
41 | npm install
42 | ```
43 |
44 | 2. Build the project:
45 | ```bash
46 | npm run build
47 | ```
48 |
49 | 3. Run in development mode:
50 | ```bash
51 | npm run dev
52 | ```
53 |
54 | 4. Test with MCP Inspector:
55 | ```bash
56 | npm run inspector
57 | ```
58 |
59 | ### Environment Configuration
60 |
61 | For testing full mode features, create a `dw.json` file in the project root:
62 |
63 | ```json
64 | {
65 | "hostname": "your-instance.sandbox.us01.dx.commercecloud.salesforce.com",
66 | "username": "your-username",
67 | "password": "your-password",
68 | "client-id": "your-client-id",
69 | "client-secret": "your-client-secret"
70 | }
71 | ```
72 |
73 | **Note**: Never commit this file. It's already in `.gitignore`.
74 |
75 | ## Project Structure
76 |
77 | ```
78 | src/
79 | ├── main.ts # Entry point
80 | ├── server.ts # MCP server implementation
81 | ├── tool-definitions.ts # MCP tool definitions
82 | ├── types.ts # TypeScript type definitions
83 | ├── config.ts # Configuration management
84 | ├── best-practices-client.ts # Best practices guide client
85 | ├── docs-client.ts # SFCC documentation client
86 | ├── log-client.ts # SFCC log analysis client
87 | ├── ocapi-client.ts # OCAPI system object client
88 | └── utils.ts # Utility functions
89 |
90 | docs/
91 | ├── best-practices/ # Best practice guides
92 | └── dw_*/ # SFCC API documentation
93 |
94 | tests/ # Test files
95 | scripts/ # Build and utility scripts
96 | ```
97 |
98 | ## Contributing Guidelines
99 |
100 | ### Code of Conduct
101 |
102 | - Be respectful and inclusive
103 | - Focus on constructive feedback
104 | - Help maintain a welcoming environment for all contributors
105 |
106 | ### Before Contributing
107 |
108 | 1. Check existing issues and pull requests
109 | 2. Open an issue to discuss major changes
110 | 3. Ensure your contribution aligns with project goals
111 |
112 | ## Types of Contributions
113 |
114 | ### 1. Bug Fixes
115 |
116 | - Fix bugs in existing functionality
117 | - Improve error handling
118 | - Fix documentation inconsistencies
119 |
120 | ### 2. Feature Enhancements
121 |
122 | - Add new MCP tools
123 | - Improve existing tool functionality
124 | - Enhance SFCC API coverage
125 |
126 | ### 3. Documentation
127 |
128 | - Update best practice guides
129 | - Add new SFCC API documentation
130 | - Improve code comments and README
131 |
132 | ### 4. Testing
133 |
134 | - Add unit tests
135 | - Improve test coverage
136 | - Add integration tests
137 |
138 | ### 5. Performance Improvements
139 |
140 | - Optimize API calls
141 | - Improve caching mechanisms
142 | - Reduce memory usage
143 |
144 | ## Development Workflow
145 |
146 | ### 1. Create a Branch
147 |
148 | ```bash
149 | git checkout -b feature/your-feature-name
150 | # or
151 | git checkout -b fix/your-bug-fix
152 | ```
153 |
154 | ### 2. Make Changes
155 |
156 | - Follow the existing code style
157 | - Add tests for new functionality
158 | - Update documentation as needed
159 |
160 | ### 3. Test Your Changes
161 |
162 | ```bash
163 | # Run tests
164 | npm test
165 |
166 | # Run linting
167 | npm run lint
168 |
169 | # Test with MCP Inspector
170 | npm run inspector
171 | ```
172 |
173 | ### 4. Commit Changes
174 |
175 | ```bash
176 | git add .
177 | git commit -m "feat: add new SFCC tool for product management"
178 | ```
179 |
180 | Use conventional commit messages:
181 | - `feat:` for new features
182 | - `fix:` for bug fixes
183 | - `docs:` for documentation changes
184 | - `test:` for test additions/changes
185 | - `refactor:` for code refactoring
186 | - `chore:` for maintenance tasks
187 |
188 | ## Testing
189 |
190 | ### Running Tests
191 |
192 | ```bash
193 | # Run all tests
194 | npm test
195 |
196 | # Run tests in watch mode
197 | npm run test:watch
198 |
199 | # Run tests with coverage
200 | npm run test:coverage
201 | ```
202 |
203 | ### Writing Tests
204 |
205 | - Place test files in the `tests/` directory
206 | - Use the `.test.ts` suffix
207 | - Follow existing test patterns
208 | - Aim for good test coverage of new functionality
209 |
210 | ### Test Categories
211 |
212 | 1. **Unit Tests**: Test individual functions and classes
213 | 2. **Integration Tests**: Test MCP tool functionality
214 | 3. **Mock Tests**: Use mocks for external SFCC API calls
215 |
216 | ## Code Style
217 |
218 | ### ESLint Configuration
219 |
220 | The project uses ESLint for code style enforcement:
221 |
222 | ```bash
223 | # Check for linting issues
224 | npm run lint
225 |
226 | # Auto-fix linting issues
227 | npm run lint:fix
228 | ```
229 |
230 | ### TypeScript
231 |
232 | - Use TypeScript for all new code
233 | - Provide proper type definitions
234 | - Avoid `any` types when possible
235 | - Use interfaces for object shapes
236 |
237 | ### Formatting
238 |
239 | - Use 2 spaces for indentation
240 | - Use single quotes for strings
241 | - Add trailing commas in objects and arrays
242 | - Follow existing code patterns
243 |
244 | ## Documentation
245 |
246 | ### Best Practice Guides
247 |
248 | When adding or updating guides in `docs/best-practices/`:
249 |
250 | 1. Follow the existing markdown structure
251 | 2. Include practical examples
252 | 3. Reference relevant SFCC APIs
253 | 4. Provide security considerations
254 |
255 | ### API Documentation
256 |
257 | When updating SFCC API docs:
258 |
259 | 1. Use the conversion script: `npm run convert-docs`
260 | 2. Ensure proper markdown formatting
261 | 3. Include complete method signatures
262 | 4. Add usage examples where helpful
263 |
264 | ### Code Comments
265 |
266 | - Comment complex business logic
267 | - Explain non-obvious implementation decisions
268 | - Use JSDoc for public APIs
269 | - Keep comments up to date with code changes
270 |
271 | ## Submitting Changes
272 |
273 | ### Pull Request Process
274 |
275 | 1. Push your branch to your fork
276 | 2. Create a pull request against the main branch
277 | 3. Fill out the pull request template
278 | 4. Link any related issues
279 |
280 | ### Pull Request Guidelines
281 |
282 | - Provide a clear description of changes
283 | - Include the motivation for the change
284 | - List any breaking changes
285 | - Add screenshots for UI changes (if applicable)
286 | - Ensure all tests pass
287 | - Update documentation as needed
288 |
289 | ### Review Process
290 |
291 | - At least one maintainer review is required
292 | - Address any feedback promptly
293 | - Keep the pull request focused and atomic
294 | - Rebase if requested to maintain clean history
295 |
296 | ## Release Process
297 |
298 | ### Versioning
299 |
300 | The project follows [Semantic Versioning](https://semver.org/):
301 |
302 | - **MAJOR**: Breaking changes
303 | - **MINOR**: New features (backward compatible)
304 | - **PATCH**: Bug fixes (backward compatible)
305 |
306 | ### Release Steps
307 |
308 | 1. Update version in `package.json`
309 | 2. Update CHANGELOG.md
310 | 3. Create a release tag
311 | 4. Publish to npm registry
312 |
313 | ## Getting Help
314 |
315 | ### Communication Channels
316 |
317 | - GitHub Issues: For bug reports and feature requests
318 | - GitHub Discussions: For questions and general discussion
319 | - Pull Request Comments: For code review discussions
320 |
321 | ### Documentation Resources
322 |
323 | - [MCP Documentation](https://modelcontextprotocol.io/)
324 | - [SFCC API Documentation](https://documentation.b2c.commercecloud.salesforce.com/)
325 | - [TypeScript Documentation](https://www.typescriptlang.org/docs/)
326 |
327 | ## Recognition
328 |
329 | Contributors will be recognized in:
330 |
331 | - GitHub contributor list
332 | - Release notes for significant contributions
333 | - Special mentions for outstanding contributions
334 |
335 | Thank you for contributing to the SFCC Development MCP Server! Your contributions help make SFCC development more accessible and efficient for the entire community.
336 |
```
--------------------------------------------------------------------------------
/docs/best-practices/security.md:
--------------------------------------------------------------------------------
```markdown
1 | # Salesforce B2C Commerce Cloud: Secure Coding Best Practices
2 |
3 | This document provides a concise guide to security best practices for Salesforce B2C Commerce Cloud development, focusing on SFRA Controllers, OCAPI/SCAPI Hooks, and Custom SCAPI Endpoints.
4 |
5 | -----
6 |
7 | ## Core Security Principles
8 |
9 | - **Shared Responsibility**: Salesforce secures the cloud infrastructure. You, the developer, are responsible for securing the custom code you write *in* the cloud.
10 | - **Defense-in-Depth**: Security is layered. Do not rely on a single control (like a WAF). Your code must be independently secure.
11 | - **OWASP Top 10**: All development should align with OWASP principles to mitigate common web application vulnerabilities.
12 | - **Server-Side Validation**: Always validate and sanitize all user input on the server. Client-side validation is for user experience only and provides no security. Use an allowlist approach.
13 | - **Secrets Management**: Never hardcode secrets (API keys, credentials). Store them in Custom Site Preferences.
14 | - **Secure Cryptography**: Use the `dw.crypto` package for all cryptographic operations. Avoid deprecated `Weak*` classes like `WeakCipher`.
15 | - **HTTP Security Headers**: Configure security headers like `Content-Security-Policy`, `X-Frame-Options`, and `Strict-Transport-Security` in the `httpHeaders.json` file.
16 |
17 | -----
18 |
19 | ## 1\. Securing SFRA Controllers
20 |
21 | Controllers are the entry point for storefront logic. Security here is paramount.
22 |
23 | ### Authentication & Authorization
24 |
25 | Always verify **who** the user is (authentication) and **what** they are allowed to do (authorization). There are
26 | off course anonymous users, but authenticated users must be verified before accessing protected resources such as
27 | the profile, basket, or order history.
28 |
29 | - **Authentication**: Use the `userLoggedIn` middleware to ensure a shopper is logged in.
30 | - **Authorization**: After authenticating, verify the user owns the data they are trying to access or modify (e.g., check if `basket.customerNo` matches `req.currentCustomer.profile.customerNo`).
31 |
32 | ```javascript
33 |
34 | var server = require('server');
35 | var userLoggedIn = require('\*/cartridge/scripts/middleware/userLoggedIn');
36 | var CustomerMgr = require('dw/customer/CustomerMgr');
37 |
38 | // The 'userLoggedIn.validateLoggedIn' middleware handles authentication.
39 | server.post('UpdateProfile', userLoggedIn.validateLoggedIn, function (req, res, next) {
40 | // Authorization MUST be performed inside the controller logic.
41 | var profileForm = server.forms.getForm('profile');
42 | var customer = CustomerMgr.getCustomerByCustomerNumber(
43 | req.currentCustomer.profile.customerNo
44 | );
45 |
46 | // Example Authorization Check: Does the logged-in user own this data?
47 | if (customer.profile.email!== profileForm.email.value) {
48 | res.setStatusCode(403);
49 | res.json({ error: 'Forbidden' });
50 | return next();
51 | }
52 |
53 | //... proceed with business logic...
54 | res.json({ success: true });
55 | next();
56 | });
57 |
58 | module.exports = server.exports();
59 |
60 | ````
61 |
62 | ### Cross-Site Request Forgery (CSRF) Protection
63 |
64 | Use the `csrfProtection` middleware for any state-changing POST request. [12, 13]
65 |
66 | 1. **Generate Token**: Use `csrfProtection.generateToken` when rendering the form page.
67 | 2. **Validate Token**: Use `csrfProtection.validateRequest` when processing the form submission.
68 |
69 | ```isml
70 | <form action="${URLUtils.url('Account-HandleProfileUpdate')}" method="POST">
71 | ...
72 | <input type="hidden" name="${pdict.csrf.tokenName}" value="${pdict.csrf.token}"/>
73 | <button type="submit">Save</button>
74 | </form>
75 | ````
76 |
77 | ```javascript
78 | // In your controller
79 | var csrfProtection = require('*/cartridge/scripts/middleware/csrf');
80 |
81 | // 1. Generate token for the form page
82 | server.get('EditProfile', csrfProtection.generateToken, function(req, res, next) {
83 | //... render page...
84 | });
85 |
86 | // 2. Validate token on form submission
87 | server.post('HandleProfileUpdate', csrfProtection.validateRequest, function(req, res, next) {
88 | // If execution reaches here, the token was valid.
89 | //... process form...
90 | });
91 | ```
92 |
93 | #### CRITICAL: CSRF Middleware Automation
94 |
95 | **❌ COMMON MISTAKE**: Manually adding CSRF tokens to viewData
96 |
97 | ```javascript
98 | // ❌ WRONG - Don't do this!
99 | server.get('ShowForm', csrfProtection.generateToken, function(req, res, next) {
100 | res.render('myForm', {
101 | csrf: {
102 | tokenName: req.csrf.tokenName, // ❌ Redundant
103 | token: req.csrf.token // ❌ Redundant
104 | }
105 | });
106 | });
107 | ```
108 |
109 | **✅ CORRECT APPROACH**: Let middleware handle it automatically
110 |
111 | ```javascript
112 | // ✅ CORRECT - Middleware automatically adds CSRF to pdict
113 | server.get('ShowForm', csrfProtection.generateToken, function(req, res, next) {
114 | res.render('myForm', {
115 | // No need to manually add CSRF - middleware does this
116 | pageTitle: 'My Form',
117 | otherData: 'value'
118 | });
119 | // pdict.csrf.tokenName and pdict.csrf.token are automatically available
120 | });
121 | ```
122 |
123 | ### Remote Include Security (server.middleware.include)
124 |
125 | Remote includes (`<isinclude url="...">`) invoke an entirely NEW request created by the Web Adapter – they DO NOT inherit the authentication context of the parent page. Treat every remote include endpoint as PUBLIC unless you explicitly secure it.
126 |
127 | | Risk Vector | Description | Mitigation |
128 | |-------------|-------------|------------|
129 | | Authentication Bypass | Endpoint renders user‑specific data but no login check runs on include request | Add `userLoggedIn.validateLoggedIn` AFTER `server.middleware.include` |
130 | | Sensitive Data in URL | All params are query string → logged, bookmarkable, cache key | Pass only minimal identifiers; never PII, secrets, tokens |
131 | | Cache Poisoning | Unique per-user params (e.g., session IDs) fragment cache & may expose personalized fragments | Keep URL stable; use surrogate keys / vary headers where needed |
132 | | Excessive Fragment Count | Many includes amplify attack surface & performance risk | Keep < 20 per page; consolidate where feasible |
133 | | Nested Includes Depth Abuse | Recursive fragment chains complicate security review & tracing | Avoid nesting beyond depth 2 |
134 |
135 | #### Mandatory Middleware Order
136 | ```javascript
137 | server.get('AccountWidget',
138 | server.middleware.include, // 1. Gatekeeper – blocks direct access without include flag
139 | userLoggedIn.validateLoggedIn, // 2. Re-establish authenticated context if user data needed
140 | cache.applyShortPromotionSensitiveCache, // 3. Explicit cache policy (or disable)
141 | function (req, res, next) {
142 | // SAFE: now in controlled context
143 | res.render('components/account/widget');
144 | next();
145 | }
146 | );
147 | ```
148 |
149 | NEVER put `userLoggedIn.validateLoggedIn` before `server.middleware.include` – bots probing the route directly would still trigger authentication logic (unnecessary overhead) and you’d miss the explicit architectural contract.
150 |
151 | #### Identifying Remote Include Requests
152 | `req.includeRequest === true` inside the controller. Log defensively:
153 | ```javascript
154 | if (!req.includeRequest) {
155 | // Unexpected direct access attempt
156 | Logger.warn('Blocked direct access to remote include endpoint: {0}', request.httpPath);
157 | res.setStatusCode(404);
158 | return next();
159 | }
160 | ```
161 |
162 | #### What NOT to Expose via Remote Include
163 | - Full order history snippets
164 | - Payment method lists / masked credit cards
165 | - Personally identifying profile composites
166 | - Any fragment whose output differs materially per authenticated user unless properly protected
167 |
168 | #### Logging & Forensics
169 | Use extended request ID format (`baseId-depth-index`) to correlate parent + fragment in logs. Example: `Xa12Bc-0-00` (page), `Xa12Bc-1-02` (third fragment). This enables rapid blast-radius analysis during incident response.
170 |
171 | #### Security Review Checklist
172 | ```text
173 | [ ] server.middleware.include first in chain
174 | [ ] Auth middleware present if user / sensitive data
175 | [ ] No secrets / PII in query params
176 | [ ] Cache TTL appropriate (0 for volatile personal data)
177 | [ ] Fragment count on target pages audited (<20)
178 | [ ] No deep nesting (depth <= 2)
179 | [ ] Logging on unexpected direct access attempts
180 | ```
181 |
182 | If any checklist item fails, remediate before deployment.
183 |
184 | #### How CSRF Middleware Works
185 |
186 | **`csrfProtection.generateToken` automatically:**
187 | - Generates a secure token
188 | - Adds `csrf.tokenName` and `csrf.token` to the response's viewData
189 | - Makes them available in templates as `${pdict.csrf.tokenName}` and `${pdict.csrf.token}`
190 |
191 | **Templates access tokens directly:**
192 | ```isml
193 | <!-- ✅ Tokens available automatically -->
194 | <input type="hidden" name="${pdict.csrf.tokenName}" value="${pdict.csrf.token}"/>
195 | ```
196 |
197 | **`csrfProtection.validateRequest` automatically:**
198 | - Validates the submitted token
199 | - Handles failures (logout/redirect)
200 | - Allows controller to proceed only if valid
201 |
202 | **Key Principle**: Never manually add CSRF data to viewData - the middleware handles this completely. Manually adding CSRF tokens is redundant and can lead to inconsistencies or security issues.
203 |
204 | ### Server-Side Validation & Output Encoding
205 |
206 | - **Validation**: Define validation rules (e.g., `mandatory`, `regexp`, `max-length`) in your form definition XML. SFRA automatically enforces these on the server when the form is processed. [14]
207 | - **Output Encoding**: Always use `encoding="on"` in `<isprint>` tags to prevent XSS. This is the default and should not be turned off without a specific, secure reason. [9]
208 |
209 | <!-- end list -->
210 |
211 | ```xml
212 | <field formid="email"
213 | type="string"
214 | mandatory="true"
215 | max-length="50"
216 | regexp="^[\w.%+-]+@[\w.-]+\.[\w]{2,6}$"
217 | parse-error="error.message.parse.email" />
218 | ```
219 |
220 | ```isml
221 | <div>Your email: <isprint value="${pdict.profileForm.email.value}" encoding="on" /></div>
222 | ```
223 |
224 | -----
225 |
226 | ## 2\. Securing OCAPI/SCAPI Hooks
227 |
228 | Hooks are powerful but dangerous. They run in a privileged context *after* initial gateway authentication but *before* business-level authorization. [15, 16]
229 |
230 | **Primary Rule**: Never trust the request. Always re-validate authorization inside the hook script. Check that the authenticated user owns the object being modified. [16]
231 |
232 | ### Authorization Example (`beforePATCH` hook)
233 |
234 | ```javascript
235 | 'use strict';
236 |
237 | var Status = require('dw/system/Status');
238 | var Logger = require('dw/system/Logger');
239 |
240 | exports.beforePATCH = function (basket, productItem, productItemDocument) {
241 | // The gateway authenticated the client, but we MUST authorize the action.
242 | if (customer.authenticated) {
243 | // CRITICAL AUTHORIZATION CHECK:
244 | if (basket.customerNo!== customer.profile.customerNo) {
245 | Logger.getLogger('Security').warn('Auth failure: Customer {0} tried to modify basket {1}', customer.profile.customerNo, basket.basketNo);
246 | // Return an error to block the operation.
247 | return new Status(Status.ERROR, 'AUTH_ERROR', 'Request could not be processed.');
248 | }
249 | }
250 | //... additional validation on productItemDocument...
251 | return new Status(Status.OK); // Allow operation
252 | };
253 | ```
254 |
255 | ### Hook Best Practices
256 |
257 | - **Performance**: Keep hook logic simple and fast. Avoid making new database calls (e.g., `ProductMgr.getProduct()`). [17, 18, 19]
258 | - **Error Handling**: Wrap logic in `try-catch` blocks. Return generic `dw.system.Status` errors to the client. Log detailed, non-sensitive error information for debugging. [16, 20]
259 |
260 | -----
261 |
262 | ## 3\. Securing Custom SCAPI Endpoints
263 |
264 | Custom SCAPI Endpoints use a "contract-first" security model. The OpenAPI Specification (OAS) 3.0 YAML file is an active, enforceable security policy. [21, 22]
265 |
266 | ### Contract-First Security
267 |
268 | The platform validates requests against the OAS contract at the edge, *before* your script runs. Any request with undefined parameters, headers, or body structures is automatically rejected. [23, 24]
269 |
270 | ### Security Schemes & Scopes
271 |
272 | Define security in the OAS contract using `securitySchemes` and apply them to endpoints. Each endpoint must have exactly one custom scope (prefixed with `c_`). [21, 25]
273 |
274 | - **`ShopperToken`**: For customer-facing APIs. Uses SLAS JWTs. [25]
275 | - **`AmOAuth2`**: For admin/back-office APIs. Uses Account Manager tokens. [25]
276 |
277 | <!-- end list -->
278 |
279 | ```yaml
280 | openapi: 3.0.0
281 | info:
282 | title: Custom Loyalty API
283 | version: "1.0.0"
284 | servers:
285 | - url: https://{shortCode}.api.commercecloud.salesforce.com
286 | paths:
287 | /c_loyalty/v1/organizations/{organizationId}/shoppers/me/points:
288 | get:
289 | summary: Get Loyalty Points for the current Shopper
290 | operationId: getLoyaltyPointsForShopper
291 | # This endpoint requires a ShopperToken with the 'c_loyalty.read' scope.
292 | security:
293 | - ShopperToken: [c_loyalty.read]
294 | responses:
295 | '200':
296 | description: Success.
297 | /c_loyalty/v1/organizations/{organizationId}/customers/{customerId}/points_adjustment:
298 | post:
299 | summary: Adjust Loyalty Points for a specific customer (Admin Only)
300 | operationId: adjustCustomerLoyaltyPoints
301 | # This endpoint requires an Admin token with the 'c_loyalty.write' scope.
302 | security:
303 | - AmOAuth2: [c_loyalty.write]
304 | responses:
305 | '204':
306 | description: Success.
307 |
308 | # Reusable security scheme definitions
309 | components:
310 | securitySchemes:
311 | # Definition for Shopper APIs
312 | ShopperToken:
313 | type: http
314 | scheme: bearer
315 | bearerFormat: JWT
316 | description: "Requires a Shopper Access Token (SLAS) with c_ scopes."
317 |
318 | # Definition for Admin APIs
319 | AmOAuth2:
320 | type: oauth2
321 | description: "Requires an Account Manager token with c_ scopes."
322 | flows:
323 | clientCredentials:
324 | tokenUrl: [https://account.demandware.com/dwsso/oauth2/access_token](https://account.demandware.com/dwsso/oauth2/access_token)
325 | scopes:
326 | c_loyalty.read: "Read shopper loyalty data."
327 | c_loyalty.write: "Modify shopper loyalty data."
328 | ```
329 |
330 | ## 4\. Advanced Secrets Management
331 |
332 | Hardcoding secrets such as API keys, credentials, or encryption keys in source code is a severe vulnerability. The platform provides specific, secure locations for storing different types of secrets:
333 |
334 | - **Service Credentials (`dw.svc.ServiceCredential`)**: The most secure and appropriate method for storing secrets used to authenticate to external services (e.g., payment gateways, tax providers, shipping services). Credentials are created and managed in Business Manager (`Administration > Operations > Services`). In code, they are accessed as a read-only `dw.svc.ServiceCredential` object, and their values are never exposed in logs or to the client. This should be the default choice for any third-party integration credential.
335 |
336 | - **Encrypted Custom Object Attributes**: For storing other types of sensitive data that are not service credentials, create a custom attribute on a system or custom object and set its type to `PASSWORD`. The platform automatically encrypts the value of this attribute at rest.
337 |
338 | - **Custom Site Preferences**: Suitable for storing non-secret configuration values, such as feature toggles, endpoint URLs, or less sensitive identifiers. While a vast improvement over hardcoding, they are not encrypted in the same way as `ServiceCredential` or `PASSWORD` attributes and should not be the first choice for highly sensitive secrets like private keys or primary authentication credentials.
339 |
340 | ## 5. Modern Cryptography with dw.crypto
341 |
342 | All cryptographic operations must be performed using the APIs provided in the dw.crypto package. This package provides access to industry-standard, Salesforce-maintained cryptographic libraries.
343 |
344 | A critical security mandate is to avoid all deprecated Weak* classes, such as WeakCipher, WeakMac, and WeakMessageDigest. These classes use outdated and insecure algorithms that are vulnerable to attack. Some older third-party cartridges may still contain references to them; these cartridges must be updated or replaced.
345 |
346 | All new development must use the modern classes like dw.crypto.Cipher. The following is a secure example of symmetric encryption using AES with a GCM block mode, which provides both confidentiality and authenticity.
347 |
348 | ```javascript
349 | var Cipher = require('dw/crypto/Cipher');
350 | var Encoding = require('dw/crypto/Encoding');
351 | var SecureRandom = require('dw/crypto/SecureRandom');
352 |
353 | // Key must be a securely generated, Base64-encoded 256-bit (32-byte) key.
354 | // It should be stored securely using Service Credentials or an encrypted attribute.
355 | var base64Key = 'YOUR_SECURE_BASE64_ENCODED_KEY_HERE';
356 |
357 | // Plaintext to be encrypted
358 | var plainText = 'This is sensitive data.';
359 |
360 | // 1. Generate a cryptographically secure random Initialization Vector (IV).
361 | // For AES/GCM, a 12-byte (96-bit) IV is recommended.
362 | var ivBytes = new SecureRandom().nextBytes(12);
363 | var ivBase64 = Encoding.toBase64(ivBytes);
364 |
365 | // 2. Encrypt the data using a strong, authenticated encryption algorithm.
366 | var aesGcmCipher = new Cipher();
367 | var encryptedBase64 = aesGcmCipher.encrypt(plainText, base64Key, 'AES/GCM/NoPadding', ivBase64, 0);
368 |
369 | // To decrypt, you need the encrypted data, the key, and the same IV.
370 | // var decryptedText = aesGcmCipher.decrypt(encryptedBase64, base64Key, 'AES/GCM/NoPadding', ivBase64, 0);
371 | ```
372 |
373 | ### Cryptographic Best Practices
374 |
375 | - **Use Strong Algorithms**: Always use AES with GCM mode for symmetric encryption, RSA with OAEP padding for asymmetric encryption, and SHA-256 or higher for hashing.
376 |
377 | - **Generate Secure Random Values**: Use `dw.crypto.SecureRandom` for generating cryptographically secure random numbers, IVs, and salts.
378 |
379 | - **Proper Key Management**: Store encryption keys securely using Service Credentials or encrypted custom object attributes. Never hardcode keys in source code.
380 |
381 | - **Use Authenticated Encryption**: Prefer AES/GCM mode which provides both confidentiality and authenticity, preventing tampering with encrypted data.
382 |
383 | - **Unique IVs**: Always generate a unique, random IV for each encryption operation. Never reuse IVs with the same key.
384 |
385 | - **Avoid Weak Classes**: Never use WeakCipher, WeakMac, WeakMessageDigest, or any other deprecated cryptographic classes.
386 |
```
--------------------------------------------------------------------------------
/AGENTS.md:
--------------------------------------------------------------------------------
```markdown
1 | # AGENTS.md – SFCC Development MCP Server (AI Coding Agent Instructions)
2 |
3 | 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.
4 |
5 | Goals of `AGENTS.md`:
6 | - Give any AI coding agent (Copilot, Cursor, Claude, Gemini, Aider, Factory, Ona, Devin, Zed, etc.) a predictable place to load project instructions
7 | - Separate contributor onboarding (README) from deep operational detail (here)
8 | - Encourage portable, open, plain-Markdown instructions (no proprietary schema)
9 |
10 | Agent Operating Principles (Quick Commit Rules):
11 | 1. Verify reality first (counts, structures) with commands—never guess
12 | 2. Make surgical diffs—no drive‑by formatting or unrelated refactors
13 | 3. Validate after every substantive change (build + lint + relevant tests)
14 | 4. Prefer explicit, readable code & docs over clever abstractions
15 | 5. Surface ambiguity or risky instructions with safer alternatives
16 | 6. Keep `AGENTS.md` ↔ `README.md` in sync where they overlap (update both or neither)
17 | 7. Discover actual tool response formats with `npx aegis query` before writing tests
18 | 8. Treat security (credentials, paths, network) as a first‑class concern—assume local but protect anyway
19 | 9. Defer performance tuning unless a measurable issue exists; avoid premature micro‑optimizations
20 | 10. Fail loud & clear: actionable error messages, user vs system error distinction
21 |
22 |
23 | ## 🤖 Unified Engineering Principles & Persona
24 | 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):
25 |
26 | ### Core Competencies
27 | - MCP protocol compliance & tool schema rigor
28 | - SFCC integration breadth: logs, job logs, OCAPI auth, system objects, site preferences
29 | - Strong TypeScript typing, safe narrowing, interface-driven design
30 | - OAuth + token lifecycle correctness
31 | - Log & job execution analysis (parsing, summarization, health signals)
32 | - Documentation ingestion (scan → parse → resolve → extract types)
33 | - Multi-layer test strategy: Jest (unit) + Aegis YAML (declarative) + Node programmatic (stateful)
34 |
35 | ### Quality & Safety
36 | - Intentional, maintainable code; small reversible changes
37 | - Security first: never leak credentials, avoid accidental network exfiltration, sanitize paths
38 | - Explicit error modeling: distinguish user input errors vs system/internal failures
39 | - Deterministic + cache-aware logic; avoid hidden side effects
40 | - Respect local dev constraints—opt for lightweight operations
41 |
42 | ### Documentation Discipline
43 | - Update BOTH `AGENTS.md` & `README.md` for: tool count changes, new handlers, structural moves, added operating modes, configuration shifts
44 | - Quantify before asserting (grep / awk / find) – no hand-waved counts
45 | - Keep architectural diagrams & tool categories consistent with `src/core/tool-definitions.ts`
46 |
47 | ### Testing Strategy
48 | - Always discover real response shape with `npx aegis query` (success, empty, error variants) before writing tests
49 | - Unit tests: core utilities, parsing, validation, token & client logic
50 | - YAML tests: broad tool surface, schema/shape validation, edge cases
51 | - Programmatic tests: multi-step flows, stderr management, stateful sequences
52 | - Performance assertions: CI‑tolerant (<500ms typical, variation <50×) – functional correctness first
53 |
54 | ### Implementation Workflow
55 | 1. Define or adjust tool schema (if new) in `core/tool-definitions.ts`
56 | 2. Implement / extend handler (or add new) with clear separation of concerns
57 | 3. Add / update clients & services with DI-friendly patterns (`ClientFactory` + interfaces)
58 | 4. Run targeted Aegis discovery (success + edge) to capture real output
59 | 5. Write/adjust tests (unit + YAML/programmatic where appropriate)
60 | 6. Verify counts & update docs (both files) atomically
61 | 7. Run lint + tests; address failures before further edits
62 | 8. Commit with concise, scope-focused message
63 |
64 | ### YAML Test Development (Critical Process)
65 | **MANDATORY for all YAML test modifications**: Before writing or modifying ANY YAML test:
66 |
67 | 1. **Discovery First**: Use `npx aegis query [tool_name] '[params]' --config "[config.json]"` to discover actual response formats
68 | 2. **Test Success & Failure**: Query both successful and failure scenarios to understand all response variations
69 | 3. **Document Findings**: Add comments to YAML tests showing discovery commands and expected formats
70 | 4. **Choose Correct Patterns**: Use patterns that match the actual response structure, not assumptions
71 |
72 | **Common Mistakes to Avoid**:
73 | - Using `arrayLength` on JSON strings instead of actual arrays
74 | - Complex regex patterns instead of simpler `contains` or `regex` patterns
75 | - Assuming response structure without verification
76 | - Writing tests before understanding what the tool actually returns
77 |
78 | **Example Discovery Process**:
79 | ```bash
80 | # Discover actual response
81 | npx aegis query get_available_best_practice_guides '{}' --config "./aegis.config.docs-only.json"
82 | # Response: {"content": [{"type": "text", "text": "[{\"name\":\"guide1\",...}]"}], "isError": false}
83 | # Pattern: text: "match:contains:guide1" (not arrayLength since it's a JSON string)
84 | ```
85 |
86 | ### Performance & Stability
87 | - Optimize only after measuring; instrument where ambiguity exists
88 | - Use caching deliberately; document invalidation triggers
89 | - Keep handler execution time predictable; stream or range-read logs where possible
90 |
91 | ### When In Doubt
92 | - Pause and gather empirical data
93 | - Prefer minimal, additive change over speculative refactor
94 | - Escalate ambiguity via explicit options rather than guessing
95 |
96 | ---
97 |
98 | ## 📋 Project Overview
99 |
100 | 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**.
101 |
102 | ### 🎯 Project Goals
103 |
104 | 1. **Enable AI-Assisted SFCC Development**: Provide AI agents with real-time access to SFCC documentation, logs, and system objects **during local development**
105 | 2. **Reduce Development Time**: Eliminate the need to manually search through documentation or logs **while coding**
106 | 3. **Improve Code Quality**: Provide access to current best practices and development guidelines **for personal projects**
107 | 4. **Enhance Local Debugging**: Offer real-time log analysis and error investigation tools **for developer sandbox instances**
108 | 5. **Support Multiple Use Cases**: Work in both documentation-only and full-credential modes **for different development scenarios**
109 |
110 | ### 🏗️ Project Structure
111 |
112 | ```
113 | sfcc-dev-mcp/
114 | ├── src/ # Core TypeScript source code
115 | │ ├── main.ts # CLI entry point and argument parsing
116 | │ ├── index.ts # Package exports and compatibility
117 | │ ├── core/ # Core MCP server functionality
118 | │ │ ├── server.ts # Main MCP server implementation
119 | │ │ ├── tool-definitions.ts # MCP tool schema definitions
120 | │ │ └── handlers/ # Modular tool handlers
121 | │ │ ├── base-handler.ts # Abstract base handler with common functionality
122 | │ │ ├── client-factory.ts # Centralized client creation with dependency injection
123 | │ │ ├── validation-helpers.ts # Common validation utilities for handlers
124 | │ │ ├── docs-handler.ts # SFCC documentation tool handler
125 | │ │ ├── best-practices-handler.ts # Best practices tool handler
126 | │ │ ├── sfra-handler.ts # SFRA documentation tool handler
127 | │ │ ├── log-handler.ts # Log analysis tool handler
128 | │ │ ├── system-object-handler.ts # System object tool handler
129 | │ │ ├── code-version-handler.ts # Code version tool handler
130 | │ │ └── cartridge-handler.ts # Cartridge generation tool handler
131 | │ ├── clients/ # API clients for different services
132 | │ │ ├── base/ # Base client classes and shared functionality
133 | │ │ │ ├── http-client.ts # Base HTTP client with authentication
134 | │ │ │ ├── ocapi-auth-client.ts # OCAPI OAuth authentication client
135 | │ │ │ └── oauth-token.ts # OAuth token management for OCAPI
136 | │ │ ├── ocapi/ # Specialized OCAPI clients
137 | │ │ │ ├── site-preferences-client.ts # Site preferences management
138 | │ │ │ └── system-objects-client.ts # System object definitions
139 | │ │ ├── logs/ # Modular log analysis system
140 | │ │ │ ├── log-client.ts # Main log client orchestrator
141 | │ │ │ ├── webdav-client-manager.ts # WebDAV setup & authentication
142 | │ │ │ ├── log-file-reader.ts # File reading with range requests
143 | │ │ │ ├── log-file-discovery.ts # File listing & filtering
144 | │ │ │ ├── log-processor.ts # Log parsing & entry processing
145 | │ │ │ ├── log-analyzer.ts # Analysis & summarization
146 | │ │ │ ├── log-formatter.ts # Output formatting
147 | │ │ │ ├── log-constants.ts # Constants & configuration
148 | │ │ │ ├── log-types.ts # TypeScript interfaces
149 | │ │ │ └── index.ts # Module exports
150 | │ │ ├── docs/ # Modular SFCC documentation system
151 | │ │ │ ├── documentation-scanner.ts # Documentation file discovery and class listing
152 | │ │ │ ├── class-content-parser.ts # Markdown parsing and content extraction
153 | │ │ │ ├── class-name-resolver.ts # Class name normalization and resolution
154 | │ │ │ ├── referenced-types-extractor.ts # Type extraction from documentation content
155 | │ │ │ └── index.ts # Module exports
156 | │ │ ├── cartridge-generation-client.ts # Cartridge structure generation client
157 | │ │ ├── log-client.ts # Log client compatibility wrapper
158 | │ │ ├── docs-client.ts # SFCC documentation client orchestrator
159 | │ │ ├── sfra-client.ts # SFRA documentation client
160 | │ │ ├── ocapi-client.ts # Main OCAPI client coordinator
161 | │ │ └── best-practices-client.ts # Best practices guide client
162 | │ ├── services/ # Service layer with clean abstractions
163 | │ │ ├── index.ts # Service exports and type definitions
164 | │ │ ├── file-system-service.ts # File system operations service
165 | │ │ └── path-service.ts # Path manipulation service
166 | │ ├── config/ # Configuration management
167 | │ │ ├── configuration-factory.ts # Config factory for different modes
168 | │ │ └── dw-json-loader.ts # dw.json configuration loader
169 | │ ├── tool-configs/ # Tool configuration definitions
170 | │ │ ├── best-practices-tool-config.ts # Best practices tools configuration
171 | │ │ ├── cartridge-tool-config.ts # Cartridge generation tools configuration
172 | │ │ ├── code-version-tool-config.ts # Code version tools configuration
173 | │ │ ├── docs-tool-config.ts # Documentation tools configuration
174 | │ │ ├── job-log-tool-config.ts # Job log tools configuration
175 | │ │ ├── log-tool-config.ts # Log analysis tools configuration
176 | │ │ ├── sfra-tool-config.ts # SFRA documentation tools configuration
177 | │ │ └── system-object-tool-config.ts # System object tools configuration
178 | │ ├── utils/ # Utility functions and helpers
179 | │ │ ├── cache.ts # Caching layer for API responses
180 | │ │ ├── logger.ts # Structured logging system
181 | │ │ ├── utils.ts # Common utility functions
182 | │ │ ├── validator.ts # Input validation utilities
183 | │ │ ├── query-builder.ts # Query string building utilities
184 | │ │ └── path-resolver.ts # File path resolution utilities
185 | │ └── types/ # TypeScript type definitions
186 | │ └── types.ts # Comprehensive type definitions
187 | ├── docs/ # SFCC documentation and guides
188 | │ ├── best-practices/ # Development best practice guides
189 | │ │ ├── cartridge_creation.md
190 | │ │ ├── isml_templates.md
191 | │ │ ├── job_framework.md
192 | │ │ ├── localserviceregistry.md # LocalServiceRegistry integration patterns
193 | │ │ ├── ocapi_hooks.md
194 | │ │ ├── scapi_hooks.md
195 | │ │ ├── sfra_controllers.md
196 | │ │ ├── sfra_models.md # SFRA models best practices
197 | │ │ ├── sfra_client_side_js.md # SFRA client-side JavaScript patterns
198 | │ │ ├── sfra_scss.md # SFRA SCSS override and theming guidance
199 | │ │ ├── scapi_custom_endpoint.md
200 | │ │ ├── performance.md
201 | │ │ └── security.md
202 | │ ├── sfra/ # SFRA documentation
203 | │ │ ├── server.md
204 | │ │ ├── request.md
205 | │ │ ├── response.md
206 | │ │ ├── querystring.md
207 | │ │ └── render.md
208 | │ ├── dw_catalog/ # SFCC Catalog API documentation
209 | │ ├── dw_customer/ # SFCC Customer API documentation
210 | │ ├── dw_order/ # SFCC Order API documentation
211 | │ ├── dw_system/ # SFCC System API documentation
212 | │ └── [other dw_* namespaces] # Complete SFCC API documentation
213 | ├── docs-site/ # React documentation website
214 | │ ├── App.tsx # Main React application component
215 | │ ├── main.tsx # React application entry point
216 | │ ├── index.html # HTML template with SEO and structured data
217 | │ ├── constants.tsx # Application constants and configuration
218 | │ ├── metadata.json # Site metadata configuration
219 | │ ├── types.ts # TypeScript type definitions
220 | │ ├── package.json # Node.js dependencies and scripts
221 | │ ├── vite.config.ts # Vite build configuration
222 | │ ├── tailwind.config.js # Tailwind CSS configuration
223 | │ ├── postcss.config.js # PostCSS configuration
224 | │ ├── tsconfig.json # TypeScript configuration
225 | │ ├── README.md # Documentation site specific README
226 | │ ├── components/ # Reusable React components
227 | │ │ ├── Badge.tsx # Badge component for status/categories
228 | │ │ ├── CodeBlock.tsx # Syntax highlighted code blocks
229 | │ │ ├── Collapsible.tsx # Collapsible content sections
230 | │ │ ├── ConfigBuilder.tsx # Configuration builder component
231 | │ │ ├── ConfigHero.tsx # Configuration page hero section
232 | │ │ ├── ConfigModeTabs.tsx # Configuration mode tab switcher
233 | │ │ ├── Layout.tsx # Main layout wrapper component
234 | │ │ ├── NewcomerCTA.tsx # Call-to-action for new users
235 | │ │ ├── NextStepsStrip.tsx # Next steps guidance component
236 | │ │ ├── OnThisPage.tsx # Table of contents component
237 | │ │ ├── Search.tsx # Search functionality component
238 | │ │ ├── Sidebar.tsx # Site navigation sidebar
239 | │ │ ├── ToolCard.tsx # Tool display card component
240 | │ │ ├── ToolFilters.tsx # Tool filtering controls
241 | │ │ ├── Typography.tsx # Typography components (H1, H2, etc.)
242 | │ │ ├── VersionBadge.tsx # Version display badge
243 | │ │ └── icons.tsx # Icon components library
244 | │ ├── pages/ # Page components for routing
245 | │ │ ├── HomePage.tsx # Homepage with quick start guide
246 | │ │ ├── AIInterfacesPage.tsx # AI interface setup guides
247 | │ │ ├── ConfigurationPage.tsx # Configuration documentation
248 | │ │ ├── DevelopmentPage.tsx # Development guidelines
249 | │ │ ├── ExamplesPage.tsx # Usage examples
250 | │ │ ├── FeaturesPage.tsx # Feature documentation
251 | │ │ ├── SecurityPage.tsx # Security considerations
252 | │ │ ├── ToolsPage.tsx # Available tools documentation
253 | │ │ └── TroubleshootingPage.tsx # Troubleshooting guide
254 | │ ├── src/ # Source assets and generated files
255 | │ │ ├── generated-search-index.ts # Generated search index
256 | │ │ └── styles/ # CSS and styling files
257 | │ ├── utils/ # Utility functions
258 | │ │ ├── search.ts # Search functionality utilities
259 | │ │ └── toolsData.ts # Tools data management
260 | │ ├── scripts/ # Build and utility scripts
261 | │ │ ├── generate-search-index.js # Search index generation script
262 | │ │ ├── generate-sitemap.js # Sitemap generation script
263 | │ │ └── search-dev.js # Development search utilities
264 | │ ├── public/ # Static assets
265 | │ │ ├── 404.html # Custom 404 error page
266 | │ │ ├── robots.txt # Search engine crawling instructions
267 | │ │ ├── sitemap.xml # Site map for search engines
268 | │ │ ├── llms.txt # LLM-specific instructions
269 | │ │ ├── favicon.ico # Website favicon
270 | │ │ ├── favicon-16x16.png # 16x16 favicon variant
271 | │ │ ├── favicon-32x32.png # 32x32 favicon variant
272 | │ │ ├── apple-touch-icon.png # Apple touch icon
273 | │ │ ├── android-chrome-192x192.png # Android Chrome icon 192x192
274 | │ │ ├── android-chrome-512x512.png # Android Chrome icon 512x512
275 | │ │ ├── site.webmanifest # Web app manifest
276 | │ │ ├── index.css # Global CSS styles
277 | │ │ ├── explain-product-pricing-methods.png # Demo screenshot with MCP
278 | │ │ └── explain-product-pricing-methods-no-mcp.png # Demo screenshot without MCP
279 | │ ├── dist/ # Built website output (Vite build)
280 | │ └── node_modules/ # Node.js dependencies
281 | ├── ai-instructions/ # AI instruction files for different platforms
282 | │ ├── claude-desktop/ # Claude Desktop specific instructions
283 | │ │ └── claude_custom_instructions.md
284 | │ ├── cursor/ # Cursor editor specific instructions
285 | │ └── github-copilot/ # GitHub Copilot specific instructions
286 | │ └── copilot-instructions.md
287 | ├── tests/ # Comprehensive test suite
288 | │ ├── __mocks__/ # Mock implementations for testing
289 | │ │ └── src/ # Source code mocks
290 | │ ├── mcp/ # MCP-specific testing tools
291 | │ │ ├── node/ # Programmatic JavaScript/TypeScript testing
292 | │ │ ├── yaml/ # YAML-based declarative testing
293 | │ │ └── test-fixtures/ # Test fixtures and sample data
294 | │ ├── servers/ # Test server implementations
295 | │ │ └── webdav/ # WebDAV server mocks
296 | │ ├── *.test.ts # Individual test files for components
297 | │ └── [various test files] # Unit and integration tests
298 | ├── scripts/ # Build and documentation scripts
299 | └── package.json # Node.js package configuration
300 | ```
301 |
302 | ### 🔧 Key Components
303 |
304 | #### **MCP Server Core** (`core/server.ts`)
305 | - Implements the Model Context Protocol specification
306 | - Handles tool registration and request routing
307 | - Manages configuration modes (documentation-only vs. full)
308 | - Provides error handling and response formatting
309 | - Orchestrates modular tool handlers for different functionality areas
310 |
311 | #### **Tool Handler Architecture** (`core/handlers/`)
312 | - **BaseToolHandler** (`base-handler.ts`): Abstract base class providing common handler functionality, standardized response formatting, execution timing, and error handling patterns
313 | - **ClientFactory** (`client-factory.ts`): Centralized client creation with dependency injection support for testing and clean architecture
314 | - **ValidationHelpers** (`validation-helpers.ts`): Common validation utilities shared across all handlers
315 | - **DocsToolHandler** (`docs-handler.ts`): Handles SFCC documentation tools including class information, method search, and API discovery
316 | - **BestPracticesToolHandler** (`best-practices-handler.ts`): Manages best practice guides, security recommendations, and hook reference tables
317 | - **SFRAToolHandler** (`sfra-handler.ts`): Processes SFRA documentation requests with dynamic discovery and smart categorization
318 | - **LogToolHandler** (`log-handler.ts`): Handles real-time log analysis, error monitoring, and system health summarization
319 | - **SystemObjectToolHandler** (`system-object-handler.ts`): Manages system object definitions, custom attributes, and site preferences
320 | - **CodeVersionToolHandler** (`code-version-handler.ts`): Handles code version listing, activation, and deployment management
321 | - **CartridgeToolHandler** (`cartridge-handler.ts`): Processes cartridge generation requests with complete project setup using dependency injection
322 |
323 | #### **Client Architecture**
324 |
325 | ##### **Base Client Infrastructure** (`clients/base/`)
326 | - **BaseHttpClient** (`http-client.ts`): Abstract base class providing HTTP operations, authentication handling, and error recovery
327 | - **OCAPIAuthClient** (`ocapi-auth-client.ts`): OCAPI-specific OAuth authentication with token management and automatic renewal
328 | - **TokenManager** (`oauth-token.ts`): Singleton OAuth token manager for SFCC OCAPI authentication with automatic expiration handling
329 |
330 | ##### **Specialized OCAPI Clients** (`clients/ocapi/`)
331 | - **OCAPISitePreferencesClient** (`site-preferences-client.ts`): Manages site preference searches and configuration discovery
332 | - **OCAPISystemObjectsClient** (`system-objects-client.ts`): Provides system object definitions, attribute schemas, and custom object exploration
333 |
334 | ##### **Modular Log Analysis System** (`clients/logs/`)
335 | - **SFCCLogClient** (`log-client.ts`): Main orchestrator that composes specialized log modules for comprehensive log analysis including job logs from deeper folder structures
336 | - **WebDAVClientManager** (`webdav-client-manager.ts`): WebDAV authentication and client setup with OAuth and basic auth support
337 | - **LogFileReader** (`log-file-reader.ts`): File reading with range request optimization (200KB tail reading) and comprehensive fallback mechanisms
338 | - **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
339 | - **LogProcessor** (`log-processor.ts`): Log parsing, entry extraction, data manipulation, pattern processing, and job log processing (handles all log levels in single files)
340 | - **LogAnalyzer** (`log-analyzer.ts`): Advanced analysis including pattern detection, health scoring, trend analysis, and recommendation generation
341 | - **LogFormatter** (`log-formatter.ts`): Output formatting, presentation logic, user-friendly message templates, and job execution summaries
342 | - **LogConstants** (`log-constants.ts`): Centralized constants, configuration values, message templates, and job log patterns
343 | - **LogTypes** (`log-types.ts`): Comprehensive TypeScript interfaces for all log operations including job log types
344 |
345 | ##### **Modular SFCC Documentation System** (`clients/docs/`)
346 | - **DocumentationScanner** (`documentation-scanner.ts`): File discovery and class listing across all SFCC namespaces, scanning Markdown documentation files and building comprehensive class inventories
347 | - **ClassContentParser** (`class-content-parser.ts`): Markdown parsing and content extraction, processing class documentation to extract methods, properties, constants, and inheritance information
348 | - **ClassNameResolver** (`class-name-resolver.ts`): Class name normalization and resolution, handling various naming patterns and ensuring consistent class identification across the documentation system
349 | - **ReferencedTypesExtractor** (`referenced-types-extractor.ts`): Type extraction from documentation content with circular reference protection, identifying SFCC types used in method signatures and class relationships
350 |
351 | ##### **Service Clients** (`clients/`)
352 | - **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
353 | - **LogClient** (`log-client.ts`): Backward compatibility wrapper that re-exports the modular log system
354 | - **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
355 | - **OCAPIClient** (`ocapi-client.ts`): Main OCAPI coordinator that orchestrates specialized clients and provides unified interface
356 | - **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
357 | - **CartridgeGenerationClient** (`cartridge-generation-client.ts`): Generates complete cartridge structures with clean dependency injection for file system and path operations
358 |
359 | #### **Configuration Management** (`config/`)
360 | - **Configuration Factory** (`configuration-factory.ts`): Creates configurations for different modes
361 | - **Config Loader** (`dw-json-loader.ts`): Handles dw.json and environment variable loading
362 |
363 | #### **Service Layer** (`services/`)
364 | - **Service Interfaces** (`index.ts`): Exports clean abstractions for system operations (IFileSystemService, IPathService)
365 | - **FileSystemService** (`file-system-service.ts`): Production implementation of file system operations with Node.js fs module
366 | - **PathService** (`path-service.ts`): Production implementation of path manipulation with Node.js path module
367 | - **Mock Services**: Test implementations providing controlled behavior for unit testing without real file system access
368 |
369 | #### **Utilities** (`utils/`)
370 | - **Caching System** (`cache.ts`): Efficient caching for API responses and documentation
371 | - **Logging** (`logger.ts`): Structured logging with debug capabilities
372 | - **Path Resolution** (`path-resolver.ts`): Secure file path handling
373 | - **Common Utilities** (`utils.ts`): Shared utility functions
374 |
375 | #### **Tool Categories**
376 |
377 | 1. **SFCC Documentation Tools** (5 tools)
378 | - Class information and method documentation
379 | - API search and discovery
380 | - Complete SFCC namespace coverage
381 |
382 | 2. **Best Practices Guides** (4 tools)
383 | - Curated development guidelines
384 | - Security and performance recommendations
385 | - SFRA client-side JavaScript architecture (AJAX, validation, accessibility)
386 | - Hook reference tables and examples
387 |
388 | 3. **Enhanced SFRA Documentation Tools** (5 tools)
389 | - **Dynamic Discovery**: Automatically finds all 26+ SFRA documents including core classes, extensive model documentation
390 | - **Smart Categorization**: Organizes documents into 7 logical categories (core, product, order, customer, pricing, store, other)
391 | - **Advanced Search**: Relevance-scored search across all documents with context highlighting
392 | - **Category Filtering**: Explore documents by functional areas for efficient discovery
393 | - **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)
394 |
395 | 4. **Cartridge Generation Tools** (1 tool)
396 | - Automated cartridge structure creation with direct file generation
397 | - Complete project setup with all necessary configuration files
398 | - Proper directory organization and file structure
399 |
400 | 5. **Log Analysis Tools** (8 tools)
401 | - Real-time error monitoring
402 | - Log search and pattern matching
403 | - System health summarization
404 |
405 | 6. **Job Log Tools** (5 tools)
406 | - Job log analysis and debugging
407 | - Job execution summaries
408 | - Custom job step monitoring
409 |
410 | 7. **System Object Tools** (6 tools)
411 | - Custom attribute discovery
412 | - Site preference management
413 | - System object schema exploration
414 | - Custom object attribute definitions search
415 |
416 | 8. **Code Version Tools** (2 tools)
417 | - Code version listing and management
418 | - Code version activation for deployment fixes
419 |
420 | ### 🚀 Operating Modes
421 |
422 | #### **Documentation-Only Mode**
423 | - No SFCC credentials required
424 | - Access to all documentation and best practices
425 | - Perfect for learning and reference
426 |
427 | #### **Full Mode**
428 | - Requires SFCC instance credentials
429 | - Complete access to logs, job logs, and system objects
430 | - Real-time debugging and monitoring capabilities
431 |
432 | ### 🎯 Development Guidelines (Consolidated Above)
433 | Legacy duplication removed. See Unified Engineering Principles section for the authoritative list.
434 | - Configuration options or operating modes
435 | - Development workflows or best practices
436 | - Tool categories or counts
437 | - Installation or setup procedures
438 |
439 | ### 📝 Documentation Maintenance Requirements
440 |
441 | **Critical**: When making any structural or functional changes to the codebase, you **MUST** update the relevant sections in **BOTH** `AGENTS.md` and `README.md`:
442 |
443 | #### **Always Verify Counts with Command Line Tools:**
444 |
445 | Before updating any documentation with tool counts or quantitative information, **ALWAYS** verify the actual numbers using command line tools:
446 |
447 | ```bash
448 | # Total tool count verification
449 | grep -c "name: '" src/core/tool-definitions.ts
450 |
451 | # Individual section counts
452 | awk '/export const SFCC_DOCUMENTATION_TOOLS/,/^];/' src/core/tool-definitions.ts | grep -c "name: '"
453 | awk '/export const BEST_PRACTICES_TOOLS/,/^];/' src/core/tool-definitions.ts | grep -c "name: '"
454 | awk '/export const SFRA_DOCUMENTATION_TOOLS/,/^];/' src/core/tool-definitions.ts | grep -c "name: '"
455 | awk '/export const LOG_TOOLS/,/^];/' src/core/tool-definitions.ts | grep -c "name: '"
456 | awk '/export const SYSTEM_OBJECT_TOOLS/,/^];/' src/core/tool-definitions.ts | grep -c "name: '"
457 | awk '/export const CARTRIDGE_GENERATION_TOOLS/,/^];/' src/core/tool-definitions.ts | grep -c "name: '"
458 | awk '/export const CODE_VERSION_TOOLS/,/^];/' src/core/tool-definitions.ts | grep -c "name: '"
459 |
460 | # Verify file structure changes
461 | find src -name "*.ts" -type f | wc -l # Count TypeScript files
462 | find docs -name "*.md" -type f | wc -l # Count documentation files
463 | ```
464 |
465 | **Never assume or estimate counts** - always verify with actual command line verification before updating documentation.
466 |
467 | #### **Required Updates For:**
468 | - **File Renames/Moves**: Update project structure diagram and component descriptions in AGENTS.md; update any file references in README.md
469 | - **New Classes/Modules**: Add descriptions to the Key Components section in AGENTS.md; update feature lists in README.md if user-facing
470 | - **Changed Responsibilities**: Modify class/module purpose descriptions in AGENTS.md; update feature descriptions in README.md
471 | - **New Tools**: Update tool categories and counts in **both** files; add tool descriptions to README.md features section
472 | - **Configuration Changes**: Update Operating Modes and Configuration Management sections in AGENTS.md; update configuration examples in README.md
473 | - **New Development Patterns**: Add to Common Development Tasks in AGENTS.md
474 | - **Architecture Changes**: Update Client Architecture and Key Components sections in AGENTS.md
475 | - **Installation/Setup Changes**: Update installation and configuration sections in README.md
476 | - **New Operating Modes**: Update both files with new mode descriptions and requirements
477 | - **Tool Count Changes**: Update the "Available Tools by Mode" table in README.md and tool category counts in copilot-instructions.md
478 |
479 | #### **Documentation Standards:**
480 | - **copilot-instructions.md**: Focus on technical architecture, development guidelines, and internal structure
481 | - **README.md**: Focus on user-facing features, installation, configuration, and usage examples
482 | - Use clear, descriptive language that helps developers understand the codebase
483 | - Include specific file paths and references where relevant
484 | - Maintain consistency with existing documentation style and structure
485 | - Provide context for why changes were made when updating architectural decisions
486 | - Keep tool counts and feature lists accurate and current in both files
487 |
488 | #### **When to Update:**
489 | - **Immediately after** making structural changes (file renames, moves, deletions)
490 | - **Before completing** feature development that adds new capabilities
491 | - **During refactoring** that changes class responsibilities or module purposes
492 | - **After adding** new tools, clients, or major functionality
493 | - **When modifying** configuration systems or authentication flows
494 | - **When changing** installation procedures or setup requirements
495 | - **After updating** tool categories or operating modes
496 |
497 | #### **Specific File Responsibilities:**
498 |
499 | **AGENTS.md Updates:**
500 | - Project structure diagram
501 | - Key Components descriptions
502 | - Tool Categories and counts
503 | - Operating Modes technical details
504 | - Development Guidelines
505 | - Common Development Tasks
506 | - Client Architecture descriptions
507 |
508 | **README.md Updates:**
509 | - Feature lists and descriptions
510 | - Available Tools by Mode table
511 | - Installation and setup instructions
512 | - Configuration examples and options
513 | - Usage examples and quick start guides
514 | - Tool descriptions for end users
515 |
516 | **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.
517 |
518 | ### 🔧 Common Development Tasks (Streamlined)
519 |
520 | - **Adding New Tools**: Define schema in `core/tool-definitions.ts`, implement handler in appropriate handler class in `core/handlers/`, or create new handler extending `BaseToolHandler`
521 | - **Creating New Handlers**: Extend `BaseToolHandler` class, implement `canHandle()` and `handle()` methods, register in `server.ts`
522 | - **Using ClientFactory**: Create clients using `ClientFactory` for centralized creation and dependency injection support
523 | - **Implementing Services**: Create service interfaces in `services/index.ts`, implement production versions, and provide mock implementations for testing
524 | - **Dependency Injection**: Use constructor injection for services, leverage `ClientFactory` for client creation with optional service injection
525 | - **Updating Documentation**: Modify files in `docs/` and run conversion scripts
526 | - **Enhancing Authentication**: Update `clients/base/oauth-token.ts` and client authentication logic
527 | - **Improving Caching**: Enhance `utils/cache.ts` for better performance and data freshness
528 | - **Adding Configuration Options**: Update `config/` modules for new configuration capabilities
529 | - **Adding Tests**: Create comprehensive test coverage in the `tests/` directory with proper service mocking
530 | - **MCP Test Execution**: Use `node --test` for individual MCP programmatic tests, NOT `npm test -- file.js` (which runs Jest)
531 | - **Test Types**: Jest for unit tests (`src/` directory), Node.js test runner for MCP programmatic tests (`tests/mcp/node/`), Aegis for YAML tests (`tests/mcp/yaml/`)
532 | - **Adding Utilities**: Extend `utils/` modules for shared functionality
533 | - **Handler Development**: Follow the modular handler pattern - each handler is responsible for a specific tool category with clear separation of concerns
534 | - **Cartridge Generation**: Use `generate_cartridge_structure` tool for automated cartridge creation with direct file generation
535 | - **Job Log Analysis**: Use job log tools for debugging custom job steps - `get_latest_job_log_files`, `get_job_log_entries`, `search_job_logs`, `search_job_logs_by_name`, `get_job_execution_summary`
536 | - **Modular Log Development**: Work with individual log modules in `clients/logs/` for specific functionality - modify `log-analyzer.ts` for analysis improvements, `log-formatter.ts` for output changes, or `log-file-reader.ts` for reading optimizations
537 | - **Modular Documentation Development**: Work with individual documentation modules in `clients/docs/` for specific functionality - modify `documentation-scanner.ts` for file discovery improvements, `class-content-parser.ts` for parsing enhancements, `class-name-resolver.ts` for name resolution logic, or `referenced-types-extractor.ts` for type extraction algorithms
538 | - **Documentation Verification**: Use verification commands (see Maintenance) before changing numeric counts or structure claims
539 | - **CI-Friendly Performance Testing**: When writing performance tests, use lenient timeouts (500ms+) and variation ratios (50x+) to account for GitHub Actions CI environment variability. Prioritize functional validation over strict timing requirements to prevent flaky failures due to infrastructure differences.
540 |
541 | ### 🔍 Testing & Validation (Consolidated Summary)
542 | Detailed testing guidance lives in:
543 | - `tests/mcp/AGENTS.md` (umbrella & decision matrix)
544 | - `tests/mcp/yaml/AGENTS.md` (YAML discovery-first workflow & pattern catalog)
545 | - `tests/mcp/node/AGENTS.md` (programmatic multi-step, stderr management, performance tolerances)
546 |
547 | Essentials:
548 | - Always discover success + empty/no-result + error responses with `npx aegis query` before writing tests.
549 | - Prefer YAML for broad coverage; use programmatic tests for stateful or multi-step logic.
550 | - Keep performance assertions lenient (<500ms typical; <50× variance) unless you have empirical baselines.
551 |
552 | Cheat Sheet:
553 | ```bash
554 | # List tools
555 | npx aegis query --config ./aegis.config.docs-only.json
556 |
557 | # Discovery examples
558 | npx aegis query search_sfcc_classes 'query:catalog' --config ./aegis.config.docs-only.json
559 | npx aegis query get_sfra_document 'documentName:server' --config ./aegis.config.docs-only.json
560 | npx aegis query get_system_object_definitions '' --config ./aegis.config.with-dw.json
561 |
562 | # Complex dotted parameters
563 | npx aegis query search_system_object_attribute_definitions 'objectType:Product|searchRequest.query.match_all_query:{}' --config ./aegis.config.with-dw.json
564 |
565 | # Test suites
566 | npm run test:mcp:yaml # YAML (docs-only)
567 | npm run test:mcp:yaml:full # YAML (full mode)
568 | npm run test:mcp:node # Programmatic
569 | jest # Unit tests
570 | npm test # Full suite
571 |
572 | # Single programmatic test
573 | node --test tests/mcp/node/get-latest-debug.full-mode.programmatic.test.js
574 | ```
575 |
576 | Troubleshooting Quick Tips:
577 | - Mismatch schema: re-run discovery; update both test + docs.
578 | - Flaky stderr assertions: ensure `client.clearStderr()` in programmatic tests (see node guide).
579 | - Empty arrays vs objects: record actual shape before choosing regex pattern.
580 |
581 | #### **Debugging Tool Responses**
582 |
583 | When developing or debugging tools, use aegis to inspect actual response formats:
584 |
585 | ```bash
586 | # Capture full response structure for test validation (pipe format)
587 | npx aegis query search_sfcc_classes 'query:catalog' --config ./aegis.config.docs-only.json | head -50
588 |
589 | # Traditional method format (still supported)
590 | npx aegis query --config ./aegis.config.docs-only.json --method "tools/call" --params '{"name": "[tool-name]", "arguments": [args]}' | head -50
591 |
592 | # Test error handling (pipe format)
593 | npx aegis query search_sfcc_classes 'query:' --config ./aegis.config.docs-only.json
594 |
595 | # Verify JSON response structure (pipe format)
596 | npx aegis query get_sfcc_class_info 'className:dw.catalog.Product' --config ./aegis.config.docs-only.json | jq '.'
597 | ```
598 |
599 | #### **Development Workflow Integration**
600 |
601 | 1. **Tool Development**: After implementing a new tool, immediately test with aegis before writing unit tests
602 | 2. **Response Validation**: Use aegis to capture actual response structures when writing test assertions
603 | 3. **Error Testing**: Verify error handling behavior with invalid parameters through aegis
604 | 4. **Configuration Testing**: Test both docs-only and full modes to ensure proper tool availability
605 | 5. **Integration Testing**: Validate tool interactions and data flow using aegis before automated tests
606 |
607 | #### **Critical: Response Format Discovery Before Writing Tests**
608 |
609 | **ALWAYS use aegis query to understand actual response formats before writing YAML tests.** This prevents test failures due to incorrect assumptions about response structure.
610 |
611 | ##### **Essential Pre-Test Discovery Process:**
612 |
613 | 1. **Query the tool with sample arguments** to see actual response format:
614 | ```bash
615 | npx aegis query search_sfcc_classes 'query:catalog' --config ./aegis.config.docs-only.json
616 | ```
617 |
618 | 2. **Test edge cases** (empty results, errors) to understand all response variations:
619 | ```bash
620 | npx aegis query search_sfcc_classes 'query:zzznothingfound' --config ./aegis.config.docs-only.json
621 | npx aegis query search_sfcc_classes 'query:' --config ./aegis.config.docs-only.json
622 | ```
623 |
624 | 3. **Document the actual response structure** before writing test expectations:
625 | - Is it a JSON object with metadata fields like `{classes: [], totalCount: 5, searchTerm: "query"}`?
626 | - Or a simple JSON array like `["dw.catalog.Product", "dw.catalog.Catalog"]`?
627 | - Does it return `[]` for no results or `{classes: [], totalCount: 0}`?
628 |
629 | 4. **Use the correct validation patterns** based on actual responses:
630 | ```yaml
631 | # For JSON array responses
632 | text: "match:regex:\\[[\\s\\S]*\\]"
633 |
634 | # For empty array responses
635 | text: "match:regex:^\\[\\s*\\]$"
636 |
637 | # For JSON object responses
638 | text: "match:regex:\\{[\\s\\S]*\\}"
639 |
640 | # For specific content validation
641 | text: "match:contains:dw.catalog.Product"
642 | ```
643 |
644 | ##### **Common Testing Mistakes to Avoid:**
645 |
646 | - **Assuming JSON structure without verification**: Don't expect `{classes: [], totalCount: 5}` if tool returns `["class1", "class2"]`
647 | - **Wrong empty result validation**: Using `match:exact:[]` instead of `match:regex:^\\[\\s*\\]$`
648 | - **Missing edge case testing**: Not testing empty queries, invalid parameters, or no-result scenarios
649 | - **Incorrect pattern syntax**: Using `contains:classes` instead of `match:contains:classes`
650 |
651 | ##### **Response Format Discovery Examples:**
652 |
653 | ```bash
654 | # Discover structure for class search (pipe format)
655 | npx aegis query search_sfcc_classes 'query:catalog' --config ./aegis.config.docs-only.json
656 | # Result: ["dw.catalog.Catalog", "dw.catalog.Product", ...] (simple array)
657 |
658 | # Discover empty result format (pipe format)
659 | npx aegis query search_sfcc_classes 'query:zzznothingfound' --config ./aegis.config.docs-only.json
660 | # Result: [] (empty array)
661 |
662 | # Discover error response format (pipe format)
663 | npx aegis query search_sfcc_classes 'query:' --config ./aegis.config.docs-only.json
664 | # Result: {"content": [{"type": "text", "text": "Error: ..."}], "isError": true}
665 | ```
666 |
667 | **Remember**: The time spent discovering actual response formats with aegis saves hours of debugging failed tests later. Always query first, then write tests based on reality, not assumptions.
668 |
669 | #### **Troubleshooting with Aegis**
670 |
671 | - **Tool Not Found**: Check configuration mode (docs-only vs full) and ensure tool is properly registered
672 | - **Invalid Arguments**: Use aegis to test parameter validation and see exact error messages
673 | - **Response Issues**: Compare aegis output with programmatic test expectations to identify format mismatches
674 | - **Performance Issues**: Use aegis timing information to identify slow tools
675 | - **Authentication Problems**: Test full-mode tools with aegis to validate OCAPI/WebDAV connections
676 |
677 | #### **Best Practices**
678 |
679 | - **CRITICAL: Always discover response formats first** - Use aegis query to understand actual response structure before writing any tests
680 | - **Always test new tools** with aegis before writing automated tests
681 | - **Use aegis output** to write accurate test assertions rather than guessing response formats
682 | - **Test both success and error cases** with aegis during development
683 | - **Verify tool availability** in different configuration modes using aegis
684 | - **Debug programmatic test failures** by comparing with aegis CLI results
685 | - **Test parameter validation** using aegis with various input combinations
686 | - **Document actual response formats** in test file comments for future reference
687 | - **Test edge cases comprehensively** - empty results, invalid inputs, missing parameters
688 | - **Use correct YAML pattern syntax** - always prefix with `match:` for validation patterns
689 |
690 | #### **CI-Friendly Performance Testing Guidelines**
691 |
692 | When writing performance-related tests, especially for GitHub Actions CI environments, follow these critical guidelines:
693 |
694 | - **Use Lenient Timeouts**: Set timeout thresholds of **500ms or higher** instead of strict values (50ms-250ms). CI environments are slower and less predictable than local development machines.
695 | - **Account for Environment Variability**: CI runners experience resource contention, cold starts, network latency, and I/O scheduling delays that can significantly impact timing.
696 | - **Performance Variation Ratios**: For tests comparing min/max performance, use ratios of **50x or higher** instead of strict ratios (15x). CI environments can have extreme variations due to:
697 | - Resource sharing with other processes
698 | - JIT compilation and garbage collection delays
699 | - Network and file system variability
700 | - Container initialization overhead
701 | - **Scaling Calculations**: When calculating expected performance based on result count, use generous base times (100ms+) and scaling factors (2ms+ per item) rather than tight calculations.
702 | - **Focus on Functional Validation**: Prioritize correctness over strict performance requirements. Performance tests should catch major regressions, not minor timing variations.
703 | - **Example CI-Friendly Assertions**:
704 | ```javascript
705 | // ❌ Too strict for CI
706 | assert.ok(duration < 50, `Response time should be under 50ms`);
707 | assert.ok(variationRatio < 15, `Performance variation should be under 15x`);
708 |
709 | // ✅ CI-friendly
710 | assert.ok(duration < 500, `Response time should be under 500ms`);
711 | assert.ok(variationRatio < 50, `Performance variation should be under 50x`);
712 | ```
713 |
714 | **Remember**: The goal is reliable CI builds that catch real issues without flaky failures due to infrastructure timing differences.
715 |
716 | #### **Comprehensive Testing Documentation**
717 |
718 | For comprehensive MCP testing guidance, refer to the specialized AGENTS.md files in the testing directories:
719 |
720 | ##### **YAML-Based Declarative Testing**
721 | The primary testing approach using human-readable YAML files with advanced pattern matching:
722 |
723 | - **30+ Advanced Pattern Matching**: String patterns, numeric comparisons, date validation, array operations, field extraction, cross-field validation, and pattern negation
724 | - **Declarative YAML Testing**: Human-readable test files with sophisticated validation patterns
725 | - **Interactive Tool Testing**: Quick commands for testing tools interactively with the aegis CLI
726 | - **Debugging Workflows**: Step-by-step approaches for troubleshooting test failures and server issues
727 | - **Real-World Examples**: Complete test suites for filesystem servers, multi-tool servers, and API testing scenarios
728 | - **Performance Testing**: Patterns for validating response times and system performance
729 | - **Error Handling Validation**: Comprehensive approaches to testing error scenarios and edge cases
730 |
731 | ##### **Programmatic JavaScript/TypeScript Testing**
732 | For complex testing scenarios requiring programmatic logic and integration with existing test suites:
733 |
734 | - **JavaScript/TypeScript API**: Full programmatic access to MCP server testing capabilities
735 | - **Advanced Workflows**: Multi-step testing, state management, and dynamic validation logic
736 | - **Framework Integration**: Jest, Mocha, and Node.js test runner integration patterns
737 | - **Performance Monitoring**: Built-in metrics collection and performance analysis
738 | - **Buffer Management**: Critical guidance on preventing test interference with proper `clearStderr()` usage
739 | - **Error Recovery Testing**: Comprehensive error handling and resilience validation
740 | - **TypeScript Support**: Full type safety for enterprise testing environments
741 |
742 | **Quick Interactive Testing Commands:**
743 | ```bash
744 | # List all available tools
745 | aegis query --config ./aegis.config.docs-only.json
746 |
747 | # Test specific tool with arguments - Multiple formats supported:
748 |
749 | # Pipe format (recommended for CLI)
750 | aegis query read_file 'path:test.txt' --config ./aegis.config.docs-only.json
751 | aegis query calculator 'operation:add|a:5|b:3' --config ./aegis.config.docs-only.json
752 |
753 | # JSON format (complex structures)
754 | aegis query complex_tool '{"config": {"host": "localhost"}, "data": [1,2,3]}' --config ./aegis.config.docs-only.json
755 |
756 | # Method syntax with pipe format
757 | aegis query --method tools/call --params 'name:read_file|arguments.path:test.txt' --config ./aegis.config.docs-only.json
758 |
759 | # Debug with verbose output
760 | aegis query read_file 'path:test.txt' --config ./aegis.config.docs-only.json --verbose
761 | ```
762 |
763 | **For AI Agents**: Both AGENTS.md files are specifically designed for AI assistants to understand how to create and execute comprehensive test suites for MCP servers. Choose YAML-based testing for declarative scenarios or programmatic testing for complex logic requirements. Both approaches can be directly applied to validate this SFCC Dev MCP server's functionality.
764 |
765 | ### 🧱 Architecture Advantages (Consolidated)
766 | Unified benefits of the directory structure, handler model, dependency injection, modular log system, and modular documentation system:
767 |
768 | | Concern | Key Advantages |
769 | |---------|----------------|
770 | | Directory Structure | Clear ownership, scalable growth, minimal cross-module coupling |
771 | | Handlers | Category isolation, standardized lifecycle (canHandle/handle), centralized error & timing, easy extension |
772 | | Dependency Injection | Swappable services, simplified testing (mock interfaces), boundary clarity, reduced coupling |
773 | | Log Modules | SRP per stage (discover→read→process→analyze→format), range-tail efficiency, extensible analysis & output, backward compatibility wrapper |
774 | | Documentation Modules | Streamlined pipeline (scan→parse→resolve→extract), focused optimizations, circular reference protection, type-safe expansion |
775 |
776 | Cross-cutting wins:
777 | - Strong typing across all layers
778 | - Deterministic testability in isolation
779 | - Backward compatibility through orchestrator wrappers (`log-client.ts`, `docs-client.ts`)
780 | - Predictable extension points (add handler, client, or module without ripple)
781 | - Low-risk refactoring zones due to SRP boundaries
782 |
783 | Result: Faster iteration, safer modifications, and clearer mental model for both humans and AI agents.
784 |
785 |
```
--------------------------------------------------------------------------------
/docs-site/postcss.config.js:
--------------------------------------------------------------------------------
```javascript
1 | export default {
2 | plugins: {
3 | tailwindcss: {},
4 | autoprefixer: {},
5 | },
6 | };
7 |
```
--------------------------------------------------------------------------------
/aegis.config.docs-only.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "sfcc-dev-mcp",
3 | "command": "node",
4 | "args": [
5 | "dist/index.js"
6 | ],
7 | "cwd": "./",
8 | "startupTimeout": 10000
9 | }
```
--------------------------------------------------------------------------------
/aegis.config.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "sfcc-dev-mcp-docs-only",
3 | "command": "node",
4 | "args": [
5 | "dist/index.js"
6 | ],
7 | "cwd": "./",
8 | "startupTimeout": 10000,
9 | "env": {
10 | "NODE_ENV": "test"
11 | }
12 | }
13 |
```
--------------------------------------------------------------------------------
/tests/servers/sfcc-mock-server/mock-data/ocapi/system-object-attribute-groups-campaign.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "_v": "23.2",
3 | "_type": "object_attribute_group_search_result",
4 | "count": 0,
5 | "hits": [],
6 | "query": {
7 | "match_all_query": {
8 | "_type": "match_all_query"
9 | }
10 | },
11 | "start": 0,
12 | "total": 0
13 | }
```
--------------------------------------------------------------------------------
/docs-site/types.ts:
--------------------------------------------------------------------------------
```typescript
1 |
2 | export interface NavItem {
3 | label: string;
4 | path: string;
5 | }
6 |
7 | export interface NavGroup {
8 | title: string;
9 | items: NavItem[];
10 | }
11 |
12 | export interface TocItem {
13 | id: string;
14 | label: string;
15 | level: number;
16 | }
17 |
```
--------------------------------------------------------------------------------
/docs/dw_util/Set.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: dw.util
2 |
3 | # Class Set
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - dw.util.Collection
9 | - dw.util.Set
10 |
11 | ## Description
12 |
13 | Represents a set of objects.
14 |
15 | ## Properties
16 |
17 | ## Constructor Summary
18 |
19 | ## Method Summary
```
--------------------------------------------------------------------------------
/docs/dw_svc/SOAPServiceDefinition.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: dw.svc
2 |
3 | # Class SOAPServiceDefinition
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - dw.svc.ServiceDefinition
9 | - dw.svc.SOAPServiceDefinition
10 |
11 | ## Description
12 |
13 | Represents a SOAP WebService definition.
14 |
15 | ## Constructor Summary
16 |
17 | ## Method Summary
```
--------------------------------------------------------------------------------
/aegis.config.with-dw.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "sfcc-dev-mcp-with-credentials",
3 | "command": "node",
4 | "args": [
5 | "dist/index.js",
6 | "--dw-json",
7 | "./tests/mcp/test-fixtures/dw.json",
8 | "--debug"
9 | ],
10 | "cwd": "./",
11 | "startupTimeout": 10000,
12 | "env": {
13 | "NODE_ENV": "test"
14 | }
15 | }
16 |
```
--------------------------------------------------------------------------------
/tests/mcp/test-fixtures/dw.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "version": "1.0.0",
3 | "hostname": "localhost:3000",
4 | "username": "[email protected]",
5 | "password": "test-password",
6 | "client-id": "test-client-id",
7 | "client-secret": "test-client-secret",
8 | "code-version": "test-version",
9 | "cartridgesPath": "./cartridges"
10 | }
11 |
```
--------------------------------------------------------------------------------
/tests/__mocks__/docs-client.ts:
--------------------------------------------------------------------------------
```typescript
1 | // Mock for SFCCDocumentationClient
2 | export const SFCCDocumentationClient = jest.fn().mockImplementation(() => ({
3 | getClassDetailsExpanded: jest.fn(),
4 | getAvailableClasses: jest.fn(),
5 | searchClasses: jest.fn(),
6 | searchMethods: jest.fn(),
7 | getClassDocumentation: jest.fn(),
8 | }));
9 |
```
--------------------------------------------------------------------------------
/docs/dw_content/ContentSearchRefinementValue.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: dw.content
2 |
3 | # Class ContentSearchRefinementValue
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - dw.catalog.SearchRefinementValue
9 | - dw.content.ContentSearchRefinementValue
10 |
11 | ## Description
12 |
13 | Represents the value of a content search refinement.
14 |
15 | ## Constructor Summary
16 |
17 | ## Method Summary
```
--------------------------------------------------------------------------------
/docs/TopLevel/StopIteration.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: TopLevel
2 |
3 | # Class StopIteration
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - StopIteration
9 |
10 | ## Description
11 |
12 | A special type of exception that is thrown when an Iterator or Generator sequence is exhausted.
13 |
14 | ## Constructor Summary
15 |
16 | StopIteration()
17 |
18 | ## Method Summary
19 |
20 | ## Constructor Detail
```
--------------------------------------------------------------------------------
/docs/dw_campaign/FreeDiscount.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: dw.campaign
2 |
3 | # Class FreeDiscount
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - dw.campaign.Discount
9 | - dw.campaign.FreeDiscount
10 |
11 | ## Description
12 |
13 | Represents a free discount in the discount plan, for example "Free shipping on all orders $25 or more."
14 |
15 | ## Constructor Summary
16 |
17 | ## Method Summary
```
--------------------------------------------------------------------------------
/docs/dw_svc/HTTPFormServiceDefinition.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: dw.svc
2 |
3 | # Class HTTPFormServiceDefinition
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - dw.svc.ServiceDefinition
9 | - dw.svc.HTTPServiceDefinition
10 | - dw.svc.HTTPFormServiceDefinition
11 |
12 | ## Description
13 |
14 | Represents an HTTP Form POST Service Definition.
15 |
16 | ## Constructor Summary
17 |
18 | ## Method Summary
```
--------------------------------------------------------------------------------
/src/services/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Services Index
3 | *
4 | * Re-exports all service interfaces and implementations for easy importing
5 | */
6 |
7 | export {
8 | IFileSystemService,
9 | FileSystemService,
10 | MockFileSystemService,
11 | } from './file-system-service.js';
12 |
13 | export {
14 | IPathService,
15 | PathService,
16 | MockPathService,
17 | } from './path-service.js';
18 |
```
--------------------------------------------------------------------------------
/docs/dw_campaign/FreeShippingDiscount.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: dw.campaign
2 |
3 | # Class FreeShippingDiscount
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - dw.campaign.Discount
9 | - dw.campaign.FreeShippingDiscount
10 |
11 | ## Description
12 |
13 | Represents a free shipping discount in the discount plan, for example "Free shipping on all iPods."
14 |
15 | ## Constructor Summary
16 |
17 | ## Method Summary
```
--------------------------------------------------------------------------------
/tests/__mocks__/webdav.js:
--------------------------------------------------------------------------------
```javascript
1 | // Mock implementation of webdav module
2 | const mockWebdavClient = {
3 | getDirectoryContents: jest.fn(),
4 | getFileContents: jest.fn(),
5 | stat: jest.fn(),
6 | createReadStream: jest.fn(),
7 | };
8 |
9 | const createClient = jest.fn(() => mockWebdavClient);
10 |
11 | module.exports = {
12 | createClient,
13 | __mockWebdavClient: mockWebdavClient,
14 | };
15 |
```
--------------------------------------------------------------------------------
/docs/TopLevel/URIError.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: TopLevel
2 |
3 | # Class URIError
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - TopLevel.Error
9 | - URIError
10 |
11 | ## Description
12 |
13 | Represents a URI error.
14 |
15 | ## Constructor Summary
16 |
17 | URIError() Constructs the error.
18 |
19 | URIError(msg : String) Constructs the error with the specified message.
20 |
21 | ## Method Summary
22 |
23 | ## Constructor Detail
```
--------------------------------------------------------------------------------
/docs/TopLevel/TypeError.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: TopLevel
2 |
3 | # Class TypeError
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - TopLevel.Error
9 | - TypeError
10 |
11 | ## Description
12 |
13 | Represents a type error.
14 |
15 | ## Constructor Summary
16 |
17 | TypeError() Constructs the error.
18 |
19 | TypeError(msg : String) Constructs the error with the specified message.
20 |
21 | ## Method Summary
22 |
23 | ## Constructor Detail
```
--------------------------------------------------------------------------------
/docs/TopLevel/RangeError.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: TopLevel
2 |
3 | # Class RangeError
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - TopLevel.Error
9 | - RangeError
10 |
11 | ## Description
12 |
13 | Represents a range error.
14 |
15 | ## Constructor Summary
16 |
17 | RangeError() Constructs the error.
18 |
19 | RangeError(msg : String) Constructs the error with the specified message.
20 |
21 | ## Method Summary
22 |
23 | ## Constructor Detail
```
--------------------------------------------------------------------------------
/docs/TopLevel/EvalError.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: TopLevel
2 |
3 | # Class EvalError
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - TopLevel.Error
9 | - EvalError
10 |
11 | ## Description
12 |
13 | Represents an evaluation error.
14 |
15 | ## Constructor Summary
16 |
17 | EvalError() Constructs the error.
18 |
19 | EvalError(msg : String) Constructs the error with the specified message.
20 |
21 | ## Method Summary
22 |
23 | ## Constructor Detail
```
--------------------------------------------------------------------------------
/docs/TopLevel/SyntaxError.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: TopLevel
2 |
3 | # Class SyntaxError
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - TopLevel.Error
9 | - SyntaxError
10 |
11 | ## Description
12 |
13 | Represents a syntax error.
14 |
15 | ## Constructor Summary
16 |
17 | SyntaxError() Constructs the error.
18 |
19 | SyntaxError(msg : String) Constructs the error with the specified message.
20 |
21 | ## Method Summary
22 |
23 | ## Constructor Detail
```
--------------------------------------------------------------------------------
/docs-site/public/.well-known/security.txt:
--------------------------------------------------------------------------------
```
1 | Contact: https://github.com/taurgis/sfcc-dev-mcp/issues
2 | Expires: 2026-09-20T00:00:00.000Z
3 | Acknowledgments: https://github.com/taurgis/sfcc-dev-mcp/blob/main/CONTRIBUTING.md
4 | Preferred-Languages: en
5 | Canonical: https://sfcc-mcp-dev.rhino-inquisitor.com/.well-known/security.txt
6 | Policy: https://github.com/taurgis/sfcc-dev-mcp/blob/main/SECURITY.md
```
--------------------------------------------------------------------------------
/docs/TopLevel/InternalError.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: TopLevel
2 |
3 | # Class InternalError
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - TopLevel.Error
9 | - InternalError
10 |
11 | ## Description
12 |
13 | Represents the an internal error.
14 |
15 | ## Constructor Summary
16 |
17 | InternalError() Constructs the error.
18 |
19 | InternalError(msg : String) Constructs the error with the specified message.
20 |
21 | ## Method Summary
22 |
23 | ## Constructor Detail
```
--------------------------------------------------------------------------------
/docs/TopLevel/ReferenceError.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: TopLevel
2 |
3 | # Class ReferenceError
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - TopLevel.Error
9 | - ReferenceError
10 |
11 | ## Description
12 |
13 | Represents a reference error.
14 |
15 | ## Constructor Summary
16 |
17 | ReferenceError() Constructs the error.
18 |
19 | ReferenceError(msg : String) Constructs the error with the specified message.
20 |
21 | ## Method Summary
22 |
23 | ## Constructor Detail
```
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/config.yml:
--------------------------------------------------------------------------------
```yaml
1 | blank_issues_enabled: false
2 | contact_links:
3 | - name: 📖 Documentation
4 | url: https://github.com/taurgis/sfcc-dev-mcp/blob/main/README.md
5 | about: Read the project documentation and setup guide
6 | - name: 🔒 Security Issues
7 | url: https://github.com/taurgis/sfcc-dev-mcp/security/advisories/new
8 | about: Report security vulnerabilities privately
9 |
10 |
```
--------------------------------------------------------------------------------
/docs/TopLevel/ConversionError.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: TopLevel
2 |
3 | # Class ConversionError
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - TopLevel.Error
9 | - ConversionError
10 |
11 | ## Description
12 |
13 | Represents a conversion error.
14 |
15 | ## Constructor Summary
16 |
17 | ConversionError() Constructs the error.
18 |
19 | ConversionError(msg : String) Constructs the error with the specified message.
20 |
21 | ## Method Summary
22 |
23 | ## Constructor Detail
```
--------------------------------------------------------------------------------
/docs/dw_order/CreateOrderException.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: dw.order
2 |
3 | # Class CreateOrderException
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - TopLevel.Error
9 | - TopLevel.APIException
10 | - dw.order.CreateOrderException
11 |
12 | ## Description
13 |
14 | This APIException is thrown by method OrderMgr.createOrder(Basket, String) to indicate no Order could be created from the Basket.
15 |
16 | ## Constructor Summary
17 |
18 | ## Method Summary
```
--------------------------------------------------------------------------------
/docs-site/metadata.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "SFCC Development MCP Server Docs",
3 | "description": "A documentation site for the SFCC Development MCP Server, a comprehensive Model Context Protocol server for Salesforce B2C Commerce Cloud development. The site provides guides for getting started, configuration, tools, and examples for AI-assisted SFCC development.",
4 | "requestFramePermissions": []
5 | }
```
--------------------------------------------------------------------------------
/docs-site/public/404.html:
--------------------------------------------------------------------------------
```html
1 | <!DOCTYPE html>
2 | <html lang="en">
3 | <head>
4 | <meta charset="UTF-8" />
5 | <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6 | <title>SFCC Development MCP Server Docs</title>
7 | <script>
8 | // For hash routing, redirect 404s to the main page
9 | window.location.href = '/';
10 | </script>
11 | </head>
12 | <body>
13 | <p>Redirecting...</p>
14 | </body>
15 | </html>
16 |
```
--------------------------------------------------------------------------------
/docs-site/public/robots.txt:
--------------------------------------------------------------------------------
```
1 | User-agent: *
2 | Allow: /
3 |
4 | # Sitemap
5 | Sitemap: https://sfcc-mcp-dev.rhino-inquisitor.com/sitemap.xml
6 |
7 | # Crawl-delay for respectful crawling
8 | Crawl-delay: 1
9 |
10 | # Allow all common search engines
11 | User-agent: Googlebot
12 | Allow: /
13 |
14 | User-agent: Bingbot
15 | Allow: /
16 |
17 | User-agent: Slurp
18 | Allow: /
19 |
20 | User-agent: DuckDuckBot
21 | Allow: /
22 |
23 | # Block certain paths if needed
24 | # Disallow: /temp/
25 | # Disallow: /private/
```
--------------------------------------------------------------------------------
/docs/TopLevel/arguments.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: TopLevel
2 |
3 | # Class arguments
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - arguments
9 |
10 | ## Description
11 |
12 | The arguments of a function.
13 |
14 | ## Properties
15 |
16 | ### callee
17 |
18 | **Type:** Object
19 |
20 | A reference to the function that is currently executing.
21 |
22 | ### length
23 |
24 | **Type:** Number
25 |
26 | The number of arguments passed to the function.
27 |
28 | ## Constructor Summary
29 |
30 | arguments()
31 |
32 | ## Method Summary
33 |
34 | ## Constructor Detail
```
--------------------------------------------------------------------------------
/docs/dw_system/AgentUserStatusCodes.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: dw.system
2 |
3 | # Class AgentUserStatusCodes
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - dw.customer.AgentUserStatusCodes
9 | - dw.system.AgentUserStatusCodes
10 |
11 | ## Description
12 |
13 | AgentUserStatusCodes contains constants representing status codes that can be used with a Status object to indicate the success or failure of the agent user login process.
14 |
15 | ## Constructor Summary
16 |
17 | AgentUserStatusCodes()
18 |
19 | ## Method Summary
20 |
21 | ## Constructor Detail
```
--------------------------------------------------------------------------------
/docs/dw_svc/HTTPFormService.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: dw.svc
2 |
3 | # Class HTTPFormService
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - dw.svc.Service
9 | - dw.svc.HTTPService
10 | - dw.svc.HTTPFormService
11 |
12 | ## Description
13 |
14 | Represents an HTTP Form POST Service. All arguments passed to the call method will be URL-encoded and set as name/value pairs in the HTTP request body. The HTTP request will be a POST with a content-type of application/x-www-form-urlencoded.
15 |
16 | ## Constructor Summary
17 |
18 | ## Method Summary
```
--------------------------------------------------------------------------------
/src/clients/docs/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | /**
2 | * Documentation Module Exports
3 | *
4 | * Exports for the refactored documentation client modules
5 | */
6 |
7 | export { DocumentationScanner, SFCCClassInfo } from './documentation-scanner.js';
8 | export {
9 | ClassContentParser,
10 | SFCCClassDetails,
11 | SFCCMethod,
12 | SFCCProperty,
13 | SFCCConstant,
14 | } from './class-content-parser.js';
15 | export { ClassNameResolver } from './class-name-resolver.js';
16 | export { ReferencedTypesExtractor } from './referenced-types-extractor.js';
17 |
```
--------------------------------------------------------------------------------
/docs/dw_customer/EncryptedObject.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: dw.customer
2 |
3 | # Class EncryptedObject
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - dw.object.PersistentObject
9 | - dw.object.ExtensibleObject
10 | - dw.customer.EncryptedObject
11 |
12 | ## Description
13 |
14 | Defines a API base class for classes containing encrypted attributes like credit cards. Note: this method handles sensitive financial and card holder data. Pay special attention to PCI DSS v3. requirements 1, 3, 7, and 9.
15 |
16 | ## Constructor Summary
17 |
18 | ## Method Summary
```
--------------------------------------------------------------------------------
/docs-site/main.tsx:
--------------------------------------------------------------------------------
```typescript
1 | import { ViteReactSSG } from 'vite-react-ssg';
2 | import { routes } from './App';
3 | import './src/styles/input.css';
4 |
5 | export const createRoot = ViteReactSSG(
6 | // react-router-dom data routes
7 | { routes },
8 | // function to have custom setups
9 | ({ router, routes, isClient, initialState }) => {
10 | // Custom setup if needed for client-side hydration
11 | if (isClient) {
12 | // Client-side only initialization
13 | console.log('Client-side initialization');
14 | }
15 | },
16 | );
```
--------------------------------------------------------------------------------
/docs/dw_order/CreateAgentBasketLimitExceededException.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: dw.order
2 |
3 | # Class CreateAgentBasketLimitExceededException
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - TopLevel.Error
9 | - TopLevel.APIException
10 | - dw.order.CreateAgentBasketLimitExceededException
11 |
12 | ## Description
13 |
14 | This exception is thrown by BasketMgr.createAgentBasket() to indicate that the open agent basket limit for the current session customer is already reached, and therefore no new agent basket could be created.
15 |
16 | ## Constructor Summary
17 |
18 | ## Method Summary
```
--------------------------------------------------------------------------------
/docs/dw_order/CreateTemporaryBasketLimitExceededException.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: dw.order
2 |
3 | # Class CreateTemporaryBasketLimitExceededException
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - TopLevel.Error
9 | - TopLevel.APIException
10 | - dw.order.CreateTemporaryBasketLimitExceededException
11 |
12 | ## Description
13 |
14 | This exception is thrown by BasketMgr.createTemporaryBasket() to indicate that the open temporary basket limit for the current session customer is already reached, and therefore no new temporary basket could be created.
15 |
16 | ## Constructor Summary
17 |
18 | ## Method Summary
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "compilerOptions": {
3 | "target": "ES2022",
4 | "module": "ESNext",
5 | "moduleResolution": "node",
6 | "outDir": "./dist",
7 | "rootDir": "./src",
8 | "strict": true,
9 | "esModuleInterop": true,
10 | "skipLibCheck": true,
11 | "forceConsistentCasingInFileNames": true,
12 | "allowSyntheticDefaultImports": true,
13 | "resolveJsonModule": true,
14 | "declaration": true,
15 | "declarationMap": true,
16 | "sourceMap": true
17 | },
18 | "include": ["src/**/*"],
19 | "exclude": ["node_modules", "dist"]
20 | }
21 |
```
--------------------------------------------------------------------------------
/docs/dw_util/UUIDUtils.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: dw.util
2 |
3 | # Class UUIDUtils
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - dw.util.UUIDUtils
9 |
10 | ## Description
11 |
12 | Utility methods around generating unique IDs.
13 |
14 | ## Constructor Summary
15 |
16 | ## Method Summary
17 |
18 | ### createUUID
19 |
20 | **Signature:** `static createUUID() : String`
21 |
22 | The method generates a unique id.
23 |
24 | ## Method Detail
25 |
26 | ## Method Details
27 |
28 | ### createUUID
29 |
30 | **Signature:** `static createUUID() : String`
31 |
32 | **Description:** The method generates a unique id.
33 |
34 | **Returns:**
35 |
36 | the generated unique id
37 |
38 | ---
```
--------------------------------------------------------------------------------
/tsconfig.test.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "compilerOptions": {
3 | "target": "ES2022",
4 | "module": "ESNext",
5 | "moduleResolution": "node",
6 | "outDir": "./dist",
7 | "rootDir": "./src",
8 | "strict": true,
9 | "esModuleInterop": true,
10 | "skipLibCheck": true,
11 | "forceConsistentCasingInFileNames": true,
12 | "allowSyntheticDefaultImports": true,
13 | "resolveJsonModule": true,
14 | "declaration": true,
15 | "declarationMap": true,
16 | "sourceMap": true
17 | },
18 | "include": ["tests/**/*"],
19 | "exclude": ["node_modules", "dist"]
20 | }
21 |
```
--------------------------------------------------------------------------------
/docs/dw_order/CreateBasketFromOrderException.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: dw.order
2 |
3 | # Class CreateBasketFromOrderException
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - TopLevel.Error
9 | - TopLevel.APIException
10 | - dw.order.CreateBasketFromOrderException
11 |
12 | ## Description
13 |
14 | This APIException is thrown by method BasketMgr.createBasketFromOrder(Order) to indicate no Basket could be created from the Order.
15 |
16 | ## Properties
17 |
18 | ### errorCode
19 |
20 | **Type:** String (Read Only)
21 |
22 | Indicates reason why BasketMgr.createBasketFromOrder(Order) failed.
23 |
24 | ## Constructor Summary
25 |
26 | ## Method Summary
```
--------------------------------------------------------------------------------
/docs/dw_io/FileReader.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: dw.io
2 |
3 | # Class FileReader
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - dw.io.Reader
9 | - dw.io.FileReader
10 |
11 | ## Description
12 |
13 | File reader class.
14 |
15 | ## Constructor Summary
16 |
17 | FileReader(file : File) Constructs the reader.
18 |
19 | FileReader(file : File, encoding : String) Constructs the reader.
20 |
21 | ## Method Summary
22 |
23 | ### close
24 |
25 | **Signature:** `close() : void`
26 |
27 | Closes the reader.
28 |
29 | ## Constructor Detail
30 |
31 | ## Method Detail
32 |
33 | ## Method Details
34 |
35 | ### close
36 |
37 | **Signature:** `close() : void`
38 |
39 | **Description:** Closes the reader.
40 |
41 | ---
```
--------------------------------------------------------------------------------
/docs/dw_web/URLParameter.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: dw.web
2 |
3 | # Class URLParameter
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - dw.web.URLParameter
9 |
10 | ## Description
11 |
12 | This class represents a key-value-pair for URL parameters.
13 |
14 | ## Constructor Summary
15 |
16 | URLParameter(aName : String, aValue : String) Constructs the parameter using the specified name and value and endocded in the form "name=value".
17 |
18 | URLParameter(aName : String, aValue : String, encodeName : boolean) Constructs the parameter using the specified name and value.
19 |
20 | ## Method Summary
21 |
22 | ## Constructor Detail
```
--------------------------------------------------------------------------------
/docs/dw_util/HashMap.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Package: dw.util
2 |
3 | # Class HashMap
4 |
5 | ## Inheritance Hierarchy
6 |
7 | - Object
8 | - dw.util.Map
9 | - dw.util.HashMap
10 |
11 | ## Description
12 |
13 | Represents a hash map of objects.
14 |
15 | ## Constructor Summary
16 |
17 | HashMap() Constructs a new HashMap.
18 |
19 | ## Method Summary
20 |
21 | ### clone
22 |
23 | **Signature:** `clone() : HashMap`
24 |
25 | Returns a shallow copy of this map.
26 |
27 | ## Constructor Detail
28 |
29 | ## Method Detail
30 |
31 | ## Method Details
32 |
33 | ### clone
34 |
35 | **Signature:** `clone() : HashMap`
36 |
37 | **Description:** Returns a shallow copy of this map.
38 |
39 | **Returns:**
40 |
41 | a shallow copy of this map.
42 |
43 | ---
```