👨‍💻 Development Guide

Contributing to the SFCC Development MCP Server project

🚀 Getting Started

Prerequisites

Node.js 18 or higher
npm 8 or higher
Git for version control
TypeScript knowledge recommended

Local Development Setup

bash

# Clone the repository
git clone https://github.com/taurgis/sfcc-dev-mcp.git
cd sfcc-dev-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Start in development mode
npm run dev -- --dw-json /Users/username/sfcc-project/dw.json

🏗️ Project Architecture

Surface: 36+ specialized tools spanning documentation, best practices, SFRA, cartridge generation, runtime logs, job logs, system & custom objects, site preferences, and code versions.

Directory Structure

text

sfcc-dev-mcp/
├── src/
│   ├── main.ts                    # CLI entry point
│   ├── index.ts                   # Package exports
│   ├── core/                      # Core MCP server & tool definitions
│   │   ├── server.ts              # MCP server (registers handlers, capability gating)
│   │   ├── tool-definitions.ts    # All tool schemas grouped by category
│   │   └── handlers/              # Modular tool handlers
│   │       ├── base-handler.ts
│   │       ├── docs-handler.ts
│   │       ├── best-practices-handler.ts
│   │       ├── sfra-handler.ts
│   │       ├── log-handler.ts
│   │       ├── job-log-handler.ts
│   │       ├── system-object-handler.ts
│   │       ├── code-version-handler.ts
│   │       └── cartridge-handler.ts
│   ├── clients/                   # API & domain clients (logic, not routing)
│   │   ├── base/                  # Shared HTTP + auth
│   │   │   ├── http-client.ts
│   │   │   ├── ocapi-auth-client.ts
│   │   │   └── oauth-token.ts
│   │   ├── logs/                  # Modular log system (composition)
│   │   │   ├── log-client.ts          # Orchestrator
│   │   │   ├── webdav-client-manager.ts # WebDAV auth + setup
│   │   │   ├── log-file-reader.ts     # Range / tail reads
│   │   │   ├── log-file-discovery.ts  # Listing & filtering
│   │   │   ├── log-processor.ts       # Parsing & normalization
│   │   │   ├── log-analyzer.ts        # Pattern & health analysis
│   │   │   ├── log-formatter.ts       # Output shaping
│   │   │   ├── log-constants.ts       # Central constants/config
│   │   │   └── log-types.ts           # Type definitions
│   │   ├── docs/                  # Modular documentation system
│   │   │   ├── documentation-scanner.ts
│   │   │   ├── class-content-parser.ts
│   │   │   ├── class-name-resolver.ts
│   │   │   ├── referenced-types-extractor.ts
│   │   │   └── index.ts
│   │   ├── docs-client.ts
│   │   ├── sfra-client.ts
│   │   ├── best-practices-client.ts
│   │   ├── cartridge-generation-client.ts
│   │   ├── ocapi/
│   │   │   ├── site-preferences-client.ts
│   │   │   └── system-objects-client.ts
│   │   ├── ocapi-client.ts
│   │   ├── log-client.ts              # Backwards compat wrapper
│   └── best-practices-client.ts   # (already listed above? keep once)
│   ├── services/                 # Dependency injection service layer
│   │   ├── file-system-service.ts
│   │   ├── path-service.ts
│   │   └── index.ts
│   ├── tool-configs/             # Tool grouping & category configs
│   │   ├── docs-tool-config.ts
│   │   ├── sfra-tool-config.ts
│   │   ├── best-practices-tool-config.ts
│   │   ├── log-tool-config.ts
│   │   ├── job-log-tool-config.ts
│   │   ├── system-object-tool-config.ts
│   │   ├── cartridge-tool-config.ts
│   │   └── code-version-tool-config.ts
│   ├── config/
│   │   ├── configuration-factory.ts   # Mode & capability resolution
│   │   └── dw-json-loader.ts          # Secure dw.json loading
│   ├── utils/
│   │   ├── cache.ts
│   │   ├── logger.ts
│   │   ├── path-resolver.ts
│   │   ├── query-builder.ts
│   │   ├── utils.ts
│   │   ├── validator.ts
│   └── types/
│       └── types.ts
├── tests/                        # Jest + MCP YAML + programmatic tests
│   ├── *.test.ts
│   ├── mcp/yaml/*.mcp.yml        # Declarative tool tests
│   ├── mcp/node/*.programmatic.test.js
│   └── servers/webdav/           # Mock WebDAV server fixtures
├── docs/                         # SFCC & best practices markdown sources
├── docs-site/                    # React + Vite documentation site
├── scripts/                      # Conversion & build scripts
└── ai-instructions/              # AI platform instruction sets

Configuration & Capability Gating (`src/config/`)

configuration-factory.ts: Determines operating mode & derives capabilities (canAccessLogs, canAccessJobLogs, canAccessOCAPI, canAccessSitePrefs).
dw-json-loader.ts: Safe credential ingestion, prevents accidental misuse.
Capability Gating: No credentials → docs & best practice tools only; WebDAV creds → runtime + job logs; Data API creds → system & custom objects, site preferences, code versions.
Least Privilege: Tools requiring unavailable capabilities never registered.

Adding New Tools (Updated Flow)

Define schema in correct category array inside tool-definitions.ts.
Decide placement – extend existing handler or create new handler extending BaseToolHandler.
Implement logic inside a client/service (keep handler thin).
Register handler only if new category (update registerHandlers() in server.ts).
Discover response format: Run with npx aegis query [tool] BEFORE writing tests; capture real JSON shape.
Add tests: Jest unit + YAML (docs & full mode as applicable) + programmatic Node tests if complex.
Update docs: This page + README + copilot instructions when categories/counts change.

Testing Strategy

Programmatic MCP tests must use Node test runner (e.g. node --test tests/mcp/node/your-test.programmatic.test.js) — do NOT invoke via npm test -- file (Jest only).

Unit Tests

bash

# Run all tests
npm test

# Run specific test file
npm test base-http-client.test.ts

# Run with coverage
npm run test:coverage

# Watch mode for development
npm run test:watch

Available Test Scripts

bash

# Core testing scripts from package.json
npm test              # Run all tests with Jest
npm run test:watch    # Run tests in watch mode
npm run test:coverage # Run tests with coverage report

# Linting and code quality
npm run lint          # Check code style
npm run lint:fix      # Auto-fix linting issues
npm run lint:check    # Check with zero warnings

Manual Testing

bash

# Test with real SFCC instance (create your own test-dw.json)
npm run dev -- --dw-json /Users/username/sfcc-project/test-dw.json --debug

# Test documentation-only mode
npm run dev -- --debug

📚 Documentation Updates

Updating SFCC Documentation

1. Add/Update Markdown Files in docs/:

bash

# Add new class documentation
echo "# NewClass\n\nDescription..." > docs/dw_catalog/NewClass.md

2. Run Documentation Conversion:

bash

# Convert and process documentation (requires axios and cheerio)
npm run convert-docs

# Test with limited conversion
npm run convert-docs:test

# Limited conversion (5 files)
npm run convert-docs:limit

3. Test Documentation Tools:

bash

# Test documentation access with your changes
npm run dev -- --debug true
# Then use MCP client to test get_sfcc_class_info with "NewClass"

Updating Documentation Site

The documentation site (docs-site/) is a React + Vite app. Deployment is handled by GitHub Actions after changes are pushed to the default branch.

Edit Content: Modify or add pages/components under docs-site/.

Local Preview:

bash

cd docs-site
npm install
npm run dev  # Opens Vite dev server (default http://localhost:5173)

Build (optional check):

bash

cd docs-site
npm run build  # Generates dist/ with static assets

Push Changes: CI workflow publishes the built site to GitHub Pages.
Search Index / Sitemap: Automatically generated via build scripts (generate:search-index, generate:sitemap).

🎯 Coding Standards

TypeScript Guidelines

typescript

// Use explicit types
interface ToolParams {
  readonly query: string;
  readonly limit?: number;
}

// Use proper error handling
async function riskyOperation(): Promise<Result> {
  try {
    return await performOperation();
  } catch (error) {
    this.logger.error('Operation failed', { error: error.message });
    throw new OperationError('Failed to perform operation', error);
  }
}

// Use meaningful names
const searchProductsByCategory = (categoryId: string) => {
  // Implementation
};

Code Organization

Single Responsibility: Each class/function has one clear purpose
Dependency Injection: Use constructor injection for dependencies
Error Boundaries: Proper error handling at service boundaries
Logging: Comprehensive logging for debugging and monitoring

Git Workflow

bash

# Create feature branch from develop
git checkout develop
git pull origin develop
git checkout -b feature/new-tool-name

# Make atomic commits
git add src/clients/my-client.ts
git commit -m "feat: add my new tool implementation"

git add tests/my-client.test.ts  
git commit -m "test: add unit tests for my new tool"

git add docs-site/tools.md
git commit -m "docs: update tools documentation"

# Push and create PR to develop branch
git push origin feature/new-tool-name

Commit Message Convention:

feat: - New features
fix: - Bug fixes
docs: - Documentation updates
test: - Test additions/modifications
refactor: - Code refactoring
chore: - Build process or auxiliary tool changes

🧪 Testing Best Practices

Test Structure

typescript

describe('FeatureName', () => {
  let client: MyClient;
  let mockHttpClient: jest.Mocked<HttpClient>;
  
  beforeEach(() => {
    mockHttpClient = createMockHttpClient();
    client = new MyClient(mockHttpClient, mockLogger);
  });
  
  describe('methodName', () => {
    it('should handle success case', async () => {
      // Arrange
      const input = { query: 'test' };
      const mockResponse = { data: 'mock response' };
      mockHttpClient.get.mockResolvedValue(mockResponse);
      
      // Act
      const result = await client.methodName(input);
      
      // Assert
      expect(result).toBeDefined();
      expect(mockHttpClient.get).toHaveBeenCalledWith('/expected/path');
    });
    
    it('should handle error case', async () => {
      // Arrange
      const input = { query: 'test' };
      mockHttpClient.get.mockRejectedValue(new Error('Network error'));
      
      // Act & Assert
      await expect(client.methodName(input)).rejects.toThrow('Network error');
    });
  });
});

Mock Strategy

typescript

// Mock external dependencies using Jest
const mockLogger = {
  info: jest.fn(),
  error: jest.fn(),
  debug: jest.fn(),
  warn: jest.fn()
};

// Use factories for complex mocks
const createMockSFCCResponse = (overrides = {}) => ({
  statusCode: 200,
  headers: { 'content-type': 'application/json' },
  data: 'Mock response data',
  ...overrides
});

Testing Coverage Overview

Unit Clients: HTTP/auth, OCAPI subclients, docs, SFRA, best practices, cartridge generation.
Handlers: Each modular handler has focused tests (error shaping, capability filtering).
Log System: Discovery, reader, processor, analyzer, formatter modules.
Job Logs: Parsing & multi-level consolidation logic.
MCP Protocol Tests: YAML declarative + programmatic (Node) in tests/mcp/.
WebDAV Mock: Integration environment for log + job retrieval.

Handler Architecture

BaseToolHandler: Central timing, error normalization, logger integration.
Category Isolation: Each functional domain kept small & cohesive.
Extensibility: New feature area → new handler; minimal churn to existing code.
Testing Benefit: Handlers test orchestration; clients test domain logic.

Services & Dependency Injection

FileSystemService & PathService: Abstract Node APIs for test isolation.
Client Composition: Pass services or mocks explicitly—no hidden globals.
Deterministic Tests: Avoids brittle fs/path mocking at module level.

Log & Job Log Architecture

Reader: Range tail reads minimize bandwidth.
Processor: Normalizes raw lines → structured entries.
Analyzer: Pattern extraction, severity grouping, health scoring.
Formatter: Produces human-oriented summaries for MCP output.
Job Logs: Unified multi-level log files consolidated logically.

Tool Config Modules

Each tool-configs/*.ts file groups logically related tool definitions or export sets, enabling cleaner segregation and future dynamic registration strategies.

Caching & Performance

cache.ts: In-memory response caching (documentation & static lookups).
log-cache.ts: Specialized transient caching for recently tailed segments.
Avoid Premature I/O: Lazy fetch patterns in log discovery & system objects.
Capability Filter: Reduces surface area → fewer accidental expensive calls.

🚀 Release Process

Version Management

bash

# Update version
npm version patch  # 1.0.0 → 1.0.1
npm version minor  # 1.0.0 → 1.1.0  
npm version major  # 1.0.0 → 2.0.0

# Push tags
git push origin main --tags

Release Checklist

1. Update Documentation

README.md tool counts & feature surface (36+ phrasing)
ai-instructions/github-copilot/copilot-instructions.md architecture updates
.github/copilot-instructions.md (sync architecture + counts)
Configuration & Features pages updated if capability surface changed
CHANGELOG.md entry (if present)

2. Testing

All unit tests pass (npm test)
Linting passes (npm run lint:check)
Manual testing with real SFCC instance
Documentation-only mode validation
Build succeeds (npm run build)

3. Build & Package

TypeScript compilation successful
Package size reasonable
Dependencies audit clean (npm audit)

4. Release

GitHub release with changelog
npm publish (automated via .github/workflows/publish.yml)
Documentation deployment (automated)

🤝 Contributing Guidelines

Before Contributing

Check Existing Issues: Search for existing issues or discussions
Discuss Large Changes: Open an issue for significant modifications
Follow Conventions: Adhere to established coding and commit patterns

Pull Request Process

Fork & Branch: Create feature branch from develop
Implement Changes: Follow coding standards and testing requirements
Update Documentation: Ensure documentation reflects changes
Test Thoroughly: All tests must pass (npm test, npm run lint:check)
Submit PR: Provide clear description and link to related issues

Code Review

GitHub Actions: CI pipeline must pass (see .github/workflows/ci.yml)
Code Quality: ESLint and TypeScript checks must pass
Test Coverage: Maintain or improve test coverage
Documentation: Ensure user-facing changes are documented

📊 Performance Considerations

Optimization Guidelines

Caching Strategy: Implement intelligent caching for API responses
Rate Limiting: Respect SFCC API limits and implement backoff
Memory Management: Monitor memory usage, especially for large datasets
Asynchronous Operations: Use proper async/await patterns

Monitoring

typescript

// Performance monitoring example
const startTime = Date.now();
try {
  const result = await performOperation();
  this.metrics.recordSuccess('operation_name', Date.now() - startTime);
  return result;
} catch (error) {
  this.metrics.recordError('operation_name', Date.now() - startTime);
  throw error;
}

🔒 Security Considerations

Credential Handling

No Hardcoding: Never commit credentials to repository
Secure Storage: Use appropriate credential storage mechanisms
Minimal Permissions: Request only necessary permissions
Rotation Support: Design for credential rotation

Input Validation

typescript

// Validate all inputs using proper TypeScript types
import { ToolResponse, ValidationError } from '../types/types.js';

interface ToolParams {
  readonly query: string;
  readonly limit?: number;
}

function validateToolInput(input: unknown): ToolParams {
  if (!input || typeof input !== 'object') {
    throw new ValidationError('Input must be an object');
  }
  
  const { query, limit } = input as any;
  
  if (!query || typeof query !== 'string') {
    throw new ValidationError('Query is required and must be a string');
  }
  
  if (query.length > 1000) {
    throw new ValidationError('Query must be 1000 characters or less');
  }
  
  if (limit !== undefined && (typeof limit !== 'number' || limit < 1 || limit > 100)) {
    throw new ValidationError('Limit must be a number between 1 and 100');
  }
  
  return { query, limit };
}

Next Steps

📝 Contributing Guidelines - Detailed contribution process
🏗️ Issues & Features - Report bugs or request features
💬 Discussions - Community discussions and Q&A
🚀 GitHub Actions - View CI/CD pipeline status

👨‍💻 Development Guide

🚀 Getting Started

Prerequisites

Local Development Setup

🏗️ Project Architecture

Directory Structure

Configuration & Capability Gating (src/config/)

Adding New Tools (Updated Flow)

Testing Strategy

Unit Tests

Available Test Scripts

Manual Testing

📚 Documentation Updates

Updating SFCC Documentation

Updating Documentation Site

🎯 Coding Standards

TypeScript Guidelines

Code Organization

Git Workflow

🧪 Testing Best Practices

Test Structure

Mock Strategy

Testing Coverage Overview

Handler Architecture

Services & Dependency Injection

Log & Job Log Architecture

Tool Config Modules

Caching & Performance

🚀 Release Process

Version Management

Release Checklist

🤝 Contributing Guidelines

Before Contributing

Pull Request Process

Code Review

📊 Performance Considerations

Optimization Guidelines

Monitoring

🔒 Security Considerations

Credential Handling

Input Validation

Next Steps

Configuration & Capability Gating (`src/config/`)