sfcc-dev-mcp 1.0.19 → 1.0.21

package/src/core/tool-schemas/system-object-tools.ts

@@ -1,127 +0,0 @@
-/**
- * System Object Tool Schemas
- */
-
-import { createSearchRequestSchema } from './shared-schemas.js';
-
-export const SYSTEM_OBJECT_TOOLS = [
-  {
-    name: 'get_system_object_definitions',
-    description: 'Get all system object definitions with metadata (not attributes). Use to discover available objects and identify Custom Objects via the _type field.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        start: {
-          type: 'number',
-          description: 'Start index for pagination (default: 0)',
-          default: 0,
-        },
-        count: {
-          type: 'number',
-          description: 'Number of items to return (default: 200)',
-          default: 200,
-        },
-        select: {
-          type: 'string',
-          description: 'OCAPI field selector. Examples: "(**)" for all, "(data.(object_type, display_name))" for specific fields.',
-          default: '(**)',
-        },
-      },
-    },
-  },
-  {
-    name: 'get_system_object_definition',
-    description: 'Get metadata for a specific system object (attribute count, group count, flags). For attribute details, use search_system_object_attribute_definitions. Does not work for Custom Objects.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        objectType: {
-          type: 'string',
-          description: 'System object type, e.g., "Product", "Customer", "Order", "Category".',
-        },
-      },
-      required: ['objectType'],
-    },
-  },
-  {
-    name: 'search_system_object_attribute_definitions',
-    description: 'Search attribute definitions within a system object. Supports text search, filtering by mandatory/searchable/system, and sorting. Use match_all_query to get all attributes.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        objectType: {
-          type: 'string',
-          description: 'System object type, e.g., "Product", "Customer", "Order".',
-        },
-        searchRequest: createSearchRequestSchema('Query to filter attribute definitions'),
-      },
-      required: ['objectType', 'searchRequest'],
-    },
-  },
-  {
-    name: 'search_site_preferences',
-    description: 'Search site preferences by name, description, or type. Use to validate preference names and types when working with Site.getCurrent().getCustomPreferenceValue() or dw.system.Site.current.preferences.custom.*.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        groupId: {
-          type: 'string',
-          description: 'The ID of the preference group to search within',
-        },
-        instanceType: {
-          type: 'string',
-          enum: ['staging', 'development', 'sandbox', 'production'],
-          description: 'The instance type to search preferences for. Since this MCP server is aimed at development and testing, the default is "sandbox".',
-          default: 'sandbox',
-        },
-        searchRequest: createSearchRequestSchema('Query to filter site preferences'),
-        options: {
-          type: 'object',
-          description: 'Additional options for the search',
-          properties: {
-            maskPasswords: {
-              type: 'boolean',
-              description: 'Whether to mask password type preference values (default: true)',
-              default: true,
-            },
-            expand: {
-              type: 'string',
-              description: 'Expand options (use "value" to retrieve value definitions)',
-            },
-          },
-        },
-      },
-      required: ['groupId', 'instanceType', 'searchRequest'],
-    },
-  },
-  {
-    name: 'search_system_object_attribute_groups',
-    description: 'Search attribute groups for a system object. Use "SitePreferences" as objectType to find preference groups needed for the site preferences API.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        objectType: {
-          type: 'string',
-          description: 'System object type, e.g., "Product", "Customer", "SitePreferences".',
-        },
-        searchRequest: createSearchRequestSchema('Query to filter attribute groups'),
-      },
-      required: ['objectType', 'searchRequest'],
-    },
-  },
-  {
-    name: 'search_custom_object_attribute_definitions',
-    description: 'Search attribute definitions within a custom object type (user-defined objects, not system objects). Supports text search, filtering, and sorting.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        objectType: {
-          type: 'string',
-          description: 'Custom object type, e.g., "Global_String", "MyCustomObject".',
-        },
-        searchRequest: createSearchRequestSchema('Query to filter attribute definitions'),
-      },
-      required: ['objectType', 'searchRequest'],
-    },
-  },
-];

package/src/index.ts

@@ -1,20 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * SFCC MCP Server - Entry Point
- *
- * This module serves as the main entry point for the SFCC (Salesforce B2C Commerce Cloud)
- * MCP server. It provides comprehensive development assistance features including log analysis,
- * debugging tools, and more. This file re-exports the main application entry point for
- * backwards compatibility and provides a clean interface for the package.
- */
-
-export { SFCCDevServer } from './core/server.js';
-export { SFCCLogClient } from './clients/log-client.js';
-export { SFCCDocumentationClient } from './clients/docs-client.js';
-export { OCAPIClient } from './clients/ocapi-client.js';
-export { TokenManager } from './clients/base/oauth-token.js';
-export type { SFCCConfig, LogLevel, LogFileInfo, LogSummary, OCAPIConfig, OAuthToken, OAuthTokenResponse } from './types/types.js';
-
-// For direct execution, delegate to main.ts
-import './main.js';

package/src/main.ts

@@ -1,161 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Main entry point for the SFCC Development MCP Server
- *
- * This module handles:
- * - Command-line argument parsing
- * - Configuration discovery (dw.json) from multiple sources
- * - Secure path validation for configuration files
- * - Server initialization and lifecycle management
- *
- * Configuration discovery priority (highest to lowest):
- * 1. Explicit --dw-json command line argument
- * 2. Environment variables (SFCC_HOSTNAME, etc.)
- * 3. MCP workspace roots discovery (after client connection)
- * 4. Current working directory fallback (disabled by default, unreliable)
- *
- * Note: CWD-based discovery is disabled because MCP servers often run
- * with cwd set to the user's home directory, not the project directory.
- * The MCP workspace roots mechanism provides the correct project context.
- */
-
-import { SFCCDevServer } from './core/server.js';
-import { ConfigurationFactory } from './config/configuration-factory.js';
-import { Logger } from './utils/logger.js';
-
-/**
- * Parse command line arguments to extract configuration options
- */
-function parseCommandLineArgs(): { dwJsonPath?: string; debug?: boolean } {
-  const args = process.argv.slice(2);
-  const options: { dwJsonPath?: string; debug?: boolean } = {};
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-
-    if (arg === '--dw-json' && i + 1 < args.length) {
-      options.dwJsonPath = args[i + 1];
-      i++; // Skip the next argument since we consumed it
-    } else if (arg === '--debug' && i + 1 < args.length) {
-      const debugValue = args[i + 1].toLowerCase();
-      options.debug = debugValue === 'true' || debugValue === '1' || debugValue === 'yes';
-      i++; // Skip the next argument since we consumed it
-    } else if (arg === '--debug') {
-      // Allow --debug without a value to default to true
-      options.debug = true;
-    }
-  }
-
-  return options;
-}
-
-/**
- * Check if environment variables provide SFCC credentials
- */
-function hasEnvironmentCredentials(): boolean {
-  const hasBasicAuth = !!(process.env.SFCC_USERNAME && process.env.SFCC_PASSWORD);
-  const hasOAuth = !!(process.env.SFCC_CLIENT_ID && process.env.SFCC_CLIENT_SECRET);
-  return !!(process.env.SFCC_HOSTNAME && (hasBasicAuth || hasOAuth));
-}
-
-/**
- * Main application entry point
- *
- * Configuration discovery priority:
- * 1. CLI --dw-json parameter (explicit, highest priority)
- * 2. Environment variables (SFCC_HOSTNAME, etc.)
- * 3. MCP workspace roots (discovered after client connection - most reliable for project context)
- *
- * Note: CWD-based auto-discovery is intentionally NOT used because MCP servers
- * often start with cwd=/Users/xxx (home directory), not the project directory.
- */
-async function main(): Promise<void> {
-  try {
-    const options = parseCommandLineArgs();
-    const debug = options.debug ?? false;
-
-    // Initialize the global logger with debug setting
-    Logger.initialize('SFCC-MCP-Server', true, debug);
-    const logger = Logger.getInstance();
-
-    logger.log('Starting SFCC Development MCP Server...');
-    logger.log(`[main] Current working directory: ${process.cwd()}`);
-    logger.log(`[main] Command line args: ${JSON.stringify(process.argv.slice(2))}`);
-    if (debug) {
-      logger.log('[main] Debug mode enabled');
-    }
-
-    // Priority 1: Explicit CLI parameter
-    if (options.dwJsonPath) {
-      logger.log(`[main] Using explicit dw.json path from CLI: ${options.dwJsonPath}`);
-    }
-
-    // Priority 2: Environment variables
-    const hasEnvCredentials = hasEnvironmentCredentials();
-    if (hasEnvCredentials) {
-      logger.log('[main] Environment variables provide SFCC credentials');
-    }
-
-    // Determine initial configuration source
-    // - If CLI path provided: use it
-    // - If env vars set: use them
-    // - Otherwise: start in local mode, MCP workspace discovery will upgrade later
-    const dwJsonPath = options.dwJsonPath; // Only use explicit CLI path, not auto-discovery
-
-    // Create configuration using the factory
-    const config = ConfigurationFactory.create({
-      dwJsonPath,
-      // Environment variables as fallback (Priority 2)
-      hostname: process.env.SFCC_HOSTNAME,
-      username: process.env.SFCC_USERNAME,
-      password: process.env.SFCC_PASSWORD,
-      clientId: process.env.SFCC_CLIENT_ID,
-      clientSecret: process.env.SFCC_CLIENT_SECRET,
-    });
-
-    logger.log(`[main] Config created - hostname: "${config.hostname}"`);
-
-    // Log configuration summary (without sensitive data)
-    const capabilities = ConfigurationFactory.getCapabilities(config);
-    logger.log(`[main] Capabilities: ${JSON.stringify(capabilities)}`);
-
-    if (capabilities.isLocalMode) {
-      logger.log('[main] Starting in Local Mode - documentation only');
-      logger.log('[main] MCP workspace roots discovery will attempt to find dw.json after client connects');
-      logger.log('[main] To skip discovery, use --dw-json or set SFCC_* environment variables');
-    } else {
-      const source = options.dwJsonPath ? 'CLI parameter' : 'environment variables';
-      logger.log(`[main] Configuration loaded from ${source}`);
-      logger.log(`[main] Hostname: ${config.hostname}`);
-      logger.log(`[main] Available features: Logs=${capabilities.canAccessLogs}, OCAPI=${capabilities.canAccessOCAPI}, WebDAV=${capabilities.canAccessWebDAV}`);
-    }
-
-    // Create and start the server
-    logger.log('[main] Creating SFCCDevServer...');
-    const server = new SFCCDevServer(config);
-    logger.log('[main] Starting server.run()...');
-    await server.run();
-  } catch (error) {
-    const logger = Logger.getInstance();
-    logger.error('Failed to start SFCC Development MCP Server:', error);
-
-    if (error instanceof Error) {
-      if (error.message.includes('not found')) {
-        logger.log('\nConfiguration Help:');
-        logger.log('1. Open a VS Code workspace with a dw.json file (recommended - auto-discovered)');
-        logger.log('2. Use --dw-json /path/to/dw.json (explicit path)');
-        logger.log('3. Set environment variables: SFCC_HOSTNAME, SFCC_USERNAME, SFCC_PASSWORD');
-      }
-    }
-
-    process.exit(1);
-  }
-}
-
-// Run the main function
-main().catch((error) => {
-  const logger = Logger.getInstance();
-  logger.error('Unhandled error:', error);
-  process.exit(1);
-});

package/src/services/file-system-service.ts

@@ -1,117 +0,0 @@
-/**
- * File System Service Interface and Implementation
- *
- * Provides an abstraction layer over Node.js file system operations
- * to enable easier testing and better dependency injection.
- */
-
-import * as fs from 'fs/promises';
-
-/**
- * Interface for file system operations
- */
-export interface IFileSystemService {
-  /**
-   * Check if a file or directory exists
-   */
-  exists(path: string): Promise<boolean>;
-
-  /**
-   * Create a directory recursively
-   */
-  mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
-
-  /**
-   * Write content to a file
-   */
-  writeFile(path: string, content: string): Promise<void>;
-
-  /**
-   * Read content from a file
-   */
-  readFile(path: string): Promise<string>;
-
-  /**
-   * Check access to a file or directory
-   */
-  access(path: string): Promise<void>;
-}
-
-/**
- * Production implementation of file system service
- */
-export class FileSystemService implements IFileSystemService {
-  async exists(path: string): Promise<boolean> {
-    try {
-      await fs.access(path);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  async mkdir(path: string, options?: { recursive?: boolean }): Promise<void> {
-    await fs.mkdir(path, options);
-  }
-
-  async writeFile(path: string, content: string): Promise<void> {
-    await fs.writeFile(path, content);
-  }
-
-  async readFile(path: string): Promise<string> {
-    return await fs.readFile(path, 'utf-8');
-  }
-
-  async access(path: string): Promise<void> {
-    await fs.access(path);
-  }
-}
-
-/**
- * Mock implementation for testing
- */
-export class MockFileSystemService implements IFileSystemService {
-  private mockFiles: Map<string, string> = new Map();
-  private mockDirectories: Set<string> = new Set();
-
-  // Mock methods for testing setup
-  setMockFile(path: string, content: string): void {
-    this.mockFiles.set(path, content);
-  }
-
-  setMockDirectory(path: string): void {
-    this.mockDirectories.add(path);
-  }
-
-  clearMocks(): void {
-    this.mockFiles.clear();
-    this.mockDirectories.clear();
-  }
-
-  // Service implementation
-  async exists(path: string): Promise<boolean> {
-    return this.mockFiles.has(path) || this.mockDirectories.has(path);
-  }
-
-  async mkdir(path: string, _options?: { recursive?: boolean }): Promise<void> {
-    this.mockDirectories.add(path);
-  }
-
-  async writeFile(path: string, content: string): Promise<void> {
-    this.mockFiles.set(path, content);
-  }
-
-  async readFile(path: string): Promise<string> {
-    const content = this.mockFiles.get(path);
-    if (content === undefined) {
-      throw new Error(`File not found: ${path}`);
-    }
-    return content;
-  }
-
-  async access(path: string): Promise<void> {
-    if (!(await this.exists(path))) {
-      throw new Error(`Path not accessible: ${path}`);
-    }
-  }
-}

package/src/services/index.ts

@@ -1,11 +0,0 @@
-/**
- * Services Index
- *
- * Re-exports all service interfaces and implementations for easy importing
- */
-
-export type { IFileSystemService } from './file-system-service.js';
-export { FileSystemService, MockFileSystemService } from './file-system-service.js';
-
-export type { IPathService } from './path-service.js';
-export { PathService, MockPathService } from './path-service.js';

package/src/services/path-service.ts

@@ -1,124 +0,0 @@
-/**
- * Path Service Interface and Implementation
- *
- * Provides an abstraction layer over Node.js path operations
- * to enable easier testing and better dependency injection.
- */
-
-import * as path from 'path';
-
-/**
- * Interface for path operations
- */
-export interface IPathService {
-  /**
-   * Join path segments
-   */
-  join(...paths: string[]): string;
-
-  /**
-   * Resolve path segments to an absolute path
-   */
-  resolve(...paths: string[]): string;
-
-  /**
-   * Get the directory name of a path
-   */
-  dirname(path: string): string;
-
-  /**
-   * Get the base name of a path
-   */
-  basename(path: string, ext?: string): string;
-
-  /**
-   * Get the extension of a path
-   */
-  extname(path: string): string;
-
-  /**
-   * Normalize a path
-   */
-  normalize(path: string): string;
-
-  /**
-   * Check if path is absolute
-   */
-  isAbsolute(path: string): boolean;
-}
-
-/**
- * Production implementation of path service
- */
-export class PathService implements IPathService {
-  join(...paths: string[]): string {
-    return path.join(...paths);
-  }
-
-  resolve(...paths: string[]): string {
-    return path.resolve(...paths);
-  }
-
-  dirname(filePath: string): string {
-    return path.dirname(filePath);
-  }
-
-  basename(filePath: string, ext?: string): string {
-    return path.basename(filePath, ext);
-  }
-
-  extname(filePath: string): string {
-    return path.extname(filePath);
-  }
-
-  normalize(filePath: string): string {
-    return path.normalize(filePath);
-  }
-
-  isAbsolute(filePath: string): boolean {
-    return path.isAbsolute(filePath);
-  }
-}
-
-/**
- * Mock implementation for testing
- */
-export class MockPathService implements IPathService {
-  // For testing, we can use the real path operations or provide custom behavior
-  join(...paths: string[]): string {
-    return paths.join('/');
-  }
-
-  resolve(...paths: string[]): string {
-    const joined = this.join(...paths);
-    return joined.startsWith('/') ? joined : `/mock/root/${joined}`;
-  }
-
-  dirname(filePath: string): string {
-    const parts = filePath.split('/');
-    return parts.slice(0, -1).join('/') || '/';
-  }
-
-  basename(filePath: string, ext?: string): string {
-    const parts = filePath.split('/');
-    const base = parts[parts.length - 1];
-    if (ext && base.endsWith(ext)) {
-      return base.slice(0, -ext.length);
-    }
-    return base;
-  }
-
-  extname(filePath: string): string {
-    const base = this.basename(filePath);
-    const dotIndex = base.lastIndexOf('.');
-    return dotIndex >= 0 ? base.slice(dotIndex) : '';
-  }
-
-  normalize(filePath: string): string {
-    return filePath.replace(/\/+/g, '/');
-  }
-
-  isAbsolute(filePath: string): boolean {
-    return filePath.startsWith('/');
-  }
-}

package/src/tool-configs/agent-instructions-tool-config.ts

@@ -1,83 +0,0 @@
-import { GenericToolSpec, ToolArguments } from '../core/handlers/base-handler.js';
-import { ValidationHelpers } from '../core/handlers/validation-helpers.js';
-import { AgentInstructionsClient } from '../clients/agent-instructions-client.js';
-import { InstructionAdvisor } from '../core/instruction-advisor.js';
-
-export const AGENT_INSTRUCTION_TOOL_NAMES = [
-  'sync_agent_instructions',
-  'disable_agent_sync',
-] as const;
-
-export type AgentInstructionToolName = typeof AGENT_INSTRUCTION_TOOL_NAMES[number];
-export const AGENT_INSTRUCTION_TOOL_NAMES_SET = new Set<AgentInstructionToolName>(AGENT_INSTRUCTION_TOOL_NAMES);
-
-const DESTINATION_VALUES = ['project', 'user', 'temp'];
-const MERGE_VALUES = ['append', 'replace', 'skip'];
-
-export const AGENT_INSTRUCTION_TOOL_CONFIG: Record<AgentInstructionToolName, GenericToolSpec<ToolArguments, any>> = {
-  sync_agent_instructions: {
-    validate: (args: ToolArguments, toolName: string) => {
-      ValidationHelpers.validateArguments(args, [
-        {
-          field: 'destinationType',
-          required: false,
-          type: 'string',
-          validator: (value: string) => DESTINATION_VALUES.includes(value),
-          errorMessage: 'destinationType must be one of project | user | temp',
-        },
-        {
-          field: 'mergeStrategy',
-          required: false,
-          type: 'string',
-          validator: (value: string) => MERGE_VALUES.includes(value),
-          errorMessage: 'mergeStrategy must be one of append | replace | skip',
-        },
-        { field: 'preferredRoot', required: false, type: 'string' },
-        { field: 'skillsDir', required: false, type: 'string' },
-        { field: 'tempDir', required: false, type: 'string' },
-        { field: 'includeAgents', required: false, type: 'boolean' },
-        { field: 'includeSkills', required: false, type: 'boolean' },
-        { field: 'installMissingOnly', required: false, type: 'boolean' },
-        { field: 'dryRun', required: false, type: 'boolean' },
-      ], toolName);
-    },
-    exec: async (args: ToolArguments, context) => {
-      const client = context.agentInstructionsClient as AgentInstructionsClient;
-      return client.syncInstructions({
-        destinationType: args.destinationType,
-        preferredRoot: args.preferredRoot,
-        skillsDir: args.skillsDir,
-        mergeStrategy: args.mergeStrategy,
-        includeAgents: args.includeAgents,
-        includeSkills: args.includeSkills,
-        installMissingOnly: args.installMissingOnly,
-        dryRun: args.dryRun,
-        tempDir: args.tempDir,
-      });
-    },
-    logMessage: (args: ToolArguments) => `Sync agent instructions (${args.destinationType ?? 'project'})`,
-  },
-  disable_agent_sync: {
-    validate: (args: ToolArguments, toolName: string) => {
-      ValidationHelpers.validateArguments(args, [
-        { field: 'preferredRoot', required: false, type: 'string' },
-      ], toolName);
-    },
-    exec: async (args: ToolArguments, context) => {
-      const client = context.agentInstructionsClient as AgentInstructionsClient;
-      const advisor = context.instructionAdvisor as InstructionAdvisor;
-
-      // Get workspace root from client status
-      const status = await client.getStatus(args.preferredRoot);
-      if (!status.workspaceRoot) {
-        return {
-          success: false,
-          message: 'Cannot disable agent sync: no workspace root found. Provide preferredRoot parameter.',
-        };
-      }
-
-      return advisor.disableAgentSync(status.workspaceRoot);
-    },
-    logMessage: () => 'Disable agent sync suggestions',
-  },
-};

package/src/tool-configs/cartridge-tool-config.ts

@@ -1,41 +0,0 @@
-import { GenericToolSpec, ToolExecutionContext } from '../core/handlers/base-handler.js';
-import { ToolArguments } from '../core/handlers/base-handler.js';
-import { ValidationHelpers, CommonValidations } from '../core/handlers/validation-helpers.js';
-import { CartridgeGenerationClient } from '../clients/cartridge/index.js';
-
-export const CARTRIDGE_TOOL_NAMES = [
-  'generate_cartridge_structure',
-] as const;
-
-export type CartridgeToolName = typeof CARTRIDGE_TOOL_NAMES[number];
-export const CARTRIDGE_TOOL_NAMES_SET = new Set<CartridgeToolName>(CARTRIDGE_TOOL_NAMES);
-
-/**
- * Configuration for cartridge generation tools
- * Maps each tool to its validation, execution, and messaging logic
- */
-export const CARTRIDGE_TOOL_CONFIG: Record<CartridgeToolName, GenericToolSpec<ToolArguments, any>> = {
-  generate_cartridge_structure: {
-    defaults: (args: ToolArguments) => ({
-      ...args,
-      fullProjectSetup: args.fullProjectSetup ?? true,
-    }),
-    validate: (args: ToolArguments, toolName: string) => {
-      ValidationHelpers.validateArguments(args, CommonValidations.requiredField(
-        'cartridgeName',
-        'string',
-        (value: string) => /^[a-zA-Z][a-zA-Z0-9_-]*$/.test(value),
-        'cartridgeName must be a valid identifier (letters, numbers, underscore, hyphen)',
-      ), toolName);
-    },
-    exec: async (args: ToolArguments, context: ToolExecutionContext) => {
-      const client = context.cartridgeClient as CartridgeGenerationClient;
-      return client.generateCartridgeStructure({
-        cartridgeName: args.cartridgeName as string,
-        targetPath: args.targetPath as string | undefined,
-        fullProjectSetup: args.fullProjectSetup as boolean,
-      });
-    },
-    logMessage: (args: ToolArguments) => `Generate cartridge structure for ${args.cartridgeName}`,
-  },
-};