Development guide

This project is a TypeScript MCP server with modular handlers and clients.

Prerequisites

• Node.js 18+
• npm 8+

Local setup

git clone https://github.com/taurgis/sfcc-dev-mcp.git
cd sfcc-dev-mcp
npm install
npm run build
npm test

Run in dev mode

npm run dev -- --debug
npm run dev -- --dw-json /path/to/dw.json --debug false

--debug accepts true/false, 1/0, or yes/no. Invalid values fail fast.

Tests and lint

npm test
npm run test:mcp:yaml
npm run test:mcp:node
npm run lint
npm run validate:server-json
npm run validate:tools-sync
npm run validate:skills-sync

Architecture overview

• src/core: server and tool registration
• src/core/server-tool-catalog.ts: capability-aware tool catalog and availability checks
• src/core/server-tool-call-lifecycle.ts: tools/call orchestration for validation, progress, cancellation, and preflight notices
• src/core/server-workspace-discovery.ts: workspace roots discovery and runtime reconfiguration flow
• src/clients: domain clients for docs, logs, OCAPI, and scaffolding
• src/services: file system and path services
• src/utils: caching, validation, logging, and shared abort/timeout helpers

Project architecture

sfcc-dev-mcp/
├── src/
│   ├── main.ts                    # CLI entry point
│   ├── index.ts                   # Package exports
│   ├── core/                      # Core MCP server & tool definitions
│   │   ├── server.ts              # MCP server (registers handlers, capability gating)
│   │   ├── tool-definitions.ts    # All tool schemas grouped by category
│   │   ├── server-tool-catalog.ts # Capability-aware tool catalog and availability checks
│   │   ├── server-tool-call-lifecycle.ts # tools/call lifecycle orchestration
│   │   ├── server-workspace-discovery.ts # Workspace roots discovery and reconfigure flow
│   │   └── handlers/              # Modular tool handlers
│   │       ├── base-handler.ts
│   │       ├── docs-handler.ts
│   │       ├── isml-handler.ts
│   │       ├── sfra-handler.ts
│   │       ├── log-handler.ts
│   │       ├── job-log-handler.ts
│   │       ├── system-object-handler.ts
│   │       ├── code-version-handler.ts
│   │       ├── cartridge-handler.ts
│   │       ├── agent-instructions-handler.ts
│   │       └── script-debugger-handler.ts
│   ├── clients/                   # API & domain clients (logic, not routing)
│   │   ├── base/                  # Shared HTTP + auth
│   │   ├── logs/                  # Modular log system
│   │   ├── docs/                  # Modular documentation system
│   │   ├── docs-client.ts
│   │   ├── sfra-client.ts
│   │   ├── isml-client.ts
│   │   ├── agent-instructions-client.ts
│   │   ├── cartridge/
│   │   ├── ocapi/
│   │   ├── ocapi-client.ts
│   │   ├── log-client.ts
│   │   ├── script-debugger/
│   ├── services/                 # Dependency injection service layer
│   ├── tool-configs/             # Tool grouping & category configs
│   ├── config/                   # Configuration + dw.json loading
│   ├── utils/                    # Caching, validation, logging, abort helpers
│   └── types/
├── tests/                        # Jest + MCP YAML + programmatic tests
├── docs/                         # SFCC documentation sources
├── docs-site/                    # Legacy React docs
├── docs-site-v2/                 # VitePress docs
├── scripts/                      # Conversion & build scripts
└── ai-instructions/              # AI platform instruction sets + bundled skills

Configuration and capability gating

• configuration-factory.ts: derives capabilities (canAccessLogs, canAccessOCAPI, canAccessWebDAV, isLocalMode).
• dw-json-loader.ts: secure credential ingestion and validation.
• credential-validation.ts: shared auth-pair and hostname validation used by both config paths.
• Capability gating rules:
  • No credentials: docs-only tools (docs, SFRA, ISML, cartridge generation, agent instructions).
  • WebDAV credentials + hostname: runtime logs, job logs, and script debugger.
  • Data API credentials + hostname: system & custom objects, site preferences, code versions.
• Tools requiring unavailable capabilities are hidden from tools/list and rejected at tools/call.

Runtime validation boundary

• src/core/tool-argument-validator.ts validates tool arguments at call time before handler execution.
• Validation includes required fields, scalar/object/array types, enum values, integer/number ranges, string constraints, and regex patterns.
• Shared OCAPI query schemas support text_query, term_query, bool_query, filtered_query, and match_all_query.
• Object schemas with declared properties reject unknown keys by default (top-level and nested), unless additionalProperties: true is explicitly set.
• Validation errors are returned as structured tool errors (INVALID_TOOL_ARGUMENTS) so clients can recover predictably.
• Non-validation execution errors are sanitized before returning tool responses (for example, upstream HTTP response bodies are stripped) to reduce accidental data leakage.

Progress and cancellation

• tools/call handlers receive an abort signal from the MCP SDK and return REQUEST_CANCELLED when the request is aborted.
• When clients provide _meta.progressToken, the server emits best-effort notifications/progress updates through request-scoped notification APIs.

Adding a new tool

1. Define the schema in the correct src/core/tool-schemas/* file.
2. Implement or extend a handler under src/core/handlers.
3. Add domain logic in a client under src/clients.
4. Discover response shapes with npx aegis query before writing tests.
5. Add unit tests and MCP YAML tests.
6. Update AGENTS.md and README.md if tool counts or categories change.

Testing strategy

• Unit tests: npm run test:unit
• Full suite (unit + MCP): npm test
• YAML MCP tests: npm run test:mcp:yaml
• Programmatic MCP tests: npm run test:mcp:node
• Lint: npm run lint

Documentation updates

The VitePress site lives in docs-site-v2/. If you modify structure, update the navigation and related pages.

Release process

npm version patch
git push origin main --tags

Checklist:

• Update README.md and AGENTS.md if tool counts or categories change
• Keep server.json version fields aligned with package.json (version and packages[0].version)
• Run npm run validate:server-json after version bumps and before tagging
• Run npm test and npm run lint:check
• Verify docs build in docs-site-v2

Contributing

• Open an issue for large changes
• Keep changes small and scoped
• Add tests for new tools and update docs if behavior changes

Documentation site

The VitePress site lives in docs-site-v2/.

cd docs-site-v2
npm install
npm run dev