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

Tests and lint

npm test
npm run test:mcp:yaml
npm run test:mcp:node
npm run lint

Architecture overview

• src/core: server and tool registration
• src/clients: domain clients for docs, logs, OCAPI, and scaffolding
• src/services: file system and path services
• src/utils: caching, validation, logging

Project architecture

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

Configuration and capability gating

• configuration-factory.ts: derives capabilities (canAccessLogs, canAccessJobLogs, canAccessOCAPI, canAccessSitePrefs).
• dw-json-loader.ts: secure credential ingestion and validation.
• Capability gating rules:
  • No credentials: docs-only tools (docs, SFRA, ISML, cartridge generation, agent instructions).
  • WebDAV credentials: runtime logs + job logs.
  • Data API credentials: system & custom objects, site preferences, code versions.
• Tools requiring unavailable capabilities are not registered.

Adding a new tool

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

Testing strategy

• Unit tests: npm test
• YAML MCP tests: npm run test:mcp:yaml
• Programmatic MCP tests: npm run test:mcp:node
• Lint: npm run lint

Documentation updates

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

Release process

npm version patch
git push origin main --tags

Checklist:

• Update README.md and AGENTS.md if tool counts or categories change
• Run npm test and npm run lint:check
• Verify docs build in docs-site-v2

Contributing

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

Documentation site

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

cd docs-site-v2
npm install
npm run dev