refactor(mcp): use Services.workingDirectory for component discovery

Add workingDirectory property to Services and update page-designer-decorator
tool to use it instead of reading process.env.SFCC_WORKING_DIRECTORY directly.
This ensures component searches start from the correct project directory when
MCP clients spawn servers from the home directory.

- Add workingDirectory to Services (resolved from --working-directory flag/env)
- Update page-designer-decorator to use services.workingDirectory
- Simplify tool description for LLM consumption
- Update tests and documentation accordingly

Author: sf-cboscenco

packages/b2c-dx-mcp/src/commands/mcp.ts

@@ -337,7 +337,8 @@ export default class McpServerCommand extends BaseCommand<typeof McpServerComman
     );
 
     // Create services from already-resolved config (BaseCommand.init() already resolved it)
-    const services = Services.fromResolvedConfig(this.resolvedConfig);
+    // Pass workingDirectory so tools can use it instead of process.cwd() (which may be ~)
+    const services = Services.fromResolvedConfig(this.resolvedConfig, startupFlags.workingDirectory);
 
     // Register toolsets
     await registerToolsets(startupFlags, server, services);

packages/b2c-dx-mcp/src/services.ts

@@ -73,6 +73,8 @@ export interface ServicesOptions {
   b2cInstance?: B2CInstance;
   /** Pre-resolved MRT configuration (auth, project, environment) */
   mrtConfig?: MrtConfig;
+  /** Project working directory for file operations */
+  workingDirectory?: string;
 }
 
 /**
@@ -90,6 +92,7 @@ export interface ServicesOptions {
  * services.b2cInstance;        // B2CInstance | undefined
  * services.mrtConfig.auth;     // AuthStrategy | undefined
  * services.mrtConfig.project;  // string | undefined
+ * services.workingDirectory;   // string (project directory)
  * ```
  */
 export class Services {
@@ -106,24 +109,34 @@ export class Services {
    */
   public readonly mrtConfig: MrtConfig;
 
+  /**
+   * Project working directory for file operations.
+   * Used by tools to ensure they operate on the correct project directory,
+   * especially when MCP clients spawn servers from the home directory.
+   * Defaults to process.cwd() if not provided.
+   */
+  public readonly workingDirectory: string;
+
   public constructor(opts: ServicesOptions = {}) {
     this.b2cInstance = opts.b2cInstance;
     this.mrtConfig = opts.mrtConfig ?? {};
+    this.workingDirectory = opts.workingDirectory ?? process.cwd();
   }
 
   /**
    * Creates a Services instance from an already-resolved configuration.
    *
    * @param config - Already-resolved configuration from BaseCommand.resolvedConfig
+   * @param workingDirectory - Optional working directory (defaults to process.cwd())
    * @returns Services instance with resolved config
    *
    * @example
    * ```typescript
    * // In a command that extends BaseCommand
-   * const services = Services.fromResolvedConfig(this.resolvedConfig);
+   * const services = Services.fromResolvedConfig(this.resolvedConfig, this.flags['working-directory']);
    * ```
    */
-  public static fromResolvedConfig(config: ResolvedB2CConfig): Services {
+  public static fromResolvedConfig(config: ResolvedB2CConfig, workingDirectory?: string): Services {
     // Build MRT config using factory methods
     const mrtConfig: MrtConfig = {
       auth: config.hasMrtConfig() ? config.createMrtAuth() : undefined,
@@ -138,6 +151,7 @@ export class Services {
     return new Services({
       b2cInstance,
       mrtConfig,
+      workingDirectory,
     });
   }
 

packages/b2c-dx-mcp/src/tools/page-designer-decorator/README.md

@@ -90,6 +90,9 @@ The tool automatically searches for components in these locations (in order):
 4. `src/**` (broader search)
 5. Custom paths (if provided via `searchPaths`)
 
+**Working Directory:**
+Component discovery uses the working directory resolved from `--working-directory` flag or `SFCC_WORKING_DIRECTORY` environment variable (via Services). This ensures searches start from the correct project directory, especially when MCP clients spawn servers from the home directory.
+
 **Examples:**
 
 - `"ProductCard"` → finds `src/components/product-tile/ProductCard.tsx`
@@ -101,6 +104,7 @@ The tool automatically searches for components in these locations (in order):
 - Use component name for portability
 - Use path for unusual locations
 - Add `searchPaths` for monorepos or non-standard structures
+- Ensure `--working-directory` flag or `SFCC_WORKING_DIRECTORY` env var is set correctly
 
 ## 🏗️ Architecture
 
@@ -242,7 +246,7 @@ The test suite covers:
 - Interactive mode (all steps: analyze, select_props, configure_attrs, configure_regions, confirm_generation)
 - Error handling (invalid input, invalid step name, missing parameters)
 - Edge cases (no props, only complex props, optional props, union types, already decorated components)
-- Environment variables (SFCC_WORKING_DIRECTORY)
+- Working directory resolution (from --working-directory flag or SFCC_WORKING_DIRECTORY env var via Services)
 
 See [`test/tools/page-designer-decorator/README.md`](../../../test/tools/page-designer-decorator/README.md) for detailed testing instructions.
 

packages/b2c-dx-mcp/src/tools/page-designer-decorator/analyzer.ts

@@ -603,7 +603,7 @@ export function resolveComponent(input: string, workspaceRoot: string, searchPat
         `Full path checked: ${fullPath}\n\n` +
         `Tips:\n` +
         `  1. Use component name instead (e.g., "ProductCard") for automatic discovery\n` +
-        `  2. If components are in a different repo, set: SFCC_WORKING_DIRECTORY=/path/to/storefront-next`,
+        `  2. If components are in a different repo, set --working-directory flag or SFCC_WORKING_DIRECTORY env var`,
     );
   }
 
@@ -630,7 +630,7 @@ export function resolveComponent(input: string, workspaceRoot: string, searchPat
         `  1. Provide full path: component: "src/components/ProductCard.tsx"\n` +
         `  2. Add custom search: searchPaths: ["packages/retail/src"]\n` +
         `  3. Check component name spelling and casing\n` +
-        `  4. If components are in a different repo, set: SFCC_WORKING_DIRECTORY=/path/to/storefront-next`,
+        `  4. If components are in a different repo, set --working-directory flag or SFCC_WORKING_DIRECTORY env var`,
     );
   }
 

packages/b2c-dx-mcp/src/tools/page-designer-decorator/index.ts

@@ -599,59 +599,19 @@ function handleAutoMode(args: PageDesignerDecoratorInput, workspaceRoot: string)
 /**
  * Creates the Page Designer decorator tool for Storefront Next.
  *
- * @param _services - MCP services (not used by this tool)
+ * @param services - MCP services (provides workingDirectory for component search)
  * @returns The configured MCP tool
  */
-export function createPageDesignerDecoratorTool(_services: Services): McpTool {
+export function createPageDesignerDecoratorTool(services: Services): McpTool {
   return {
     name: 'add_page_designer_decorator',
 
-    description: `⚠️ MANDATORY: Add Page Designer decorators to an existing component (Template Literals Version).
-    
-    Analyzes component structure and guides through adding @Component, @AttributeDefinition, and @RegionDefinition decorators.
-    
-    ENVIRONMENT SETUP:
-    Set SFCC_WORKING_DIRECTORY environment variable to the Storefront Next repository path.
-    If not set, uses current working directory.
-    
-    INITIAL CALL - MODE SELECTION:
-    When called with ONLY the 'component' parameter (no autoMode, no conversationContext), the tool will:
-    - Analyze the component (automatically finds it by name)
-    - Present mode selection options to the user
-    - WAIT for user to choose between Auto Mode or Interactive Mode
-    - DO NOT proceed until user selects a mode
-    
-    MODES:
-    
-    **AUTO MODE** (set autoMode: true):
-    - Automatically analyzes component and generates decorators with sensible defaults
-    - Skips all interactive steps
-    - Auto-selects suitable props (excludes complex and UI-only props)
-    - Auto-infers types based on naming patterns
-    - Immediately generates code - no confirmation needed
-    - Best for: Quick setup, standard components, batch processing
-    
-    **INTERACTIVE MODE** (set conversationContext.step: "analyze"):
-    - Multi-step workflow with user confirmation at each stage
-    - Allows fine-tuned control over all settings
-    - MUST ask questions and WAIT for responses
-    - DO NOT generate code until user confirms configuration
-    - Best for: Complex components, custom requirements, learning
-    
-    WORKFLOW STEPS (Interactive Mode):
-    1. analyze: Parse component, identify props, provide recommendations
-    2. select_props: Confirm user's selections and prepare for configuration
-    3. configure_attrs: Set explicit types, names, defaults where needed
-    4. configure_regions: Configure nested content areas (optional)
-    5. confirm_generation: Generate final decorator code
-    
-    INTELLIGENT FEATURES:
-    - Auto-infers types when possible (string, number, boolean)
-    - Suggests explicit types when needed (url, image, enum, markup)
-    - Detects unsuitable props (complex types, UI-only props)
-    - Provides smart defaults based on naming patterns
-    
-    Use conversationContext parameter for multi-turn conversation (interactive mode only).`,
+    description:
+      'Adds Page Designer decorators (@Component, @AttributeDefinition, @RegionDefinition) to React components. ' +
+      'Two modes: autoMode=true for quick setup with defaults, or interactive mode via conversationContext.step. ' +
+      'Component discovery uses workingDirectory from flags/env. ' +
+      'Auto mode: selects suitable props, infers types, generates code immediately. ' +
+      'Interactive mode: multi-step workflow (analyze → select_props → configure_attrs → configure_regions → confirm_generation).',
 
     inputSchema: pageDesignerDecoratorSchema.shape as ZodRawShape,
     toolsets: ['STOREFRONTNEXT'],
@@ -661,10 +621,9 @@ export function createPageDesignerDecoratorTool(_services: Services): McpTool {
       try {
         // Validate and parse input
         const validatedArgs = pageDesignerDecoratorSchema.parse(args) as PageDesignerDecoratorInput;
-        // Workspace resolution:
-        // 1. SFCC_WORKING_DIRECTORY (Storefront Next convention, recommended)
-        // 2. process.cwd() (fallback)
-        const workspaceRoot = process.env.SFCC_WORKING_DIRECTORY || process.cwd();
+        // Use workingDirectory from services to ensure we search in the correct project directory
+        // This prevents searches in the home folder when MCP clients spawn servers from ~
+        const workspaceRoot = services.workingDirectory;
 
         if (validatedArgs.autoMode === undefined && !validatedArgs.conversationContext) {
           const fullPath = resolveComponent(validatedArgs.component, workspaceRoot, validatedArgs.searchPaths);

packages/b2c-dx-mcp/test/tools/page-designer-decorator/index.test.ts

@@ -31,10 +31,11 @@ function getResultText(result: ToolResult): string {
 /**
  * Create a mock services instance for testing.
  *
+ * @param workingDirectory - Optional working directory (defaults to process.cwd())
  * @returns A new Services instance with empty configuration
  */
-function createMockServices(): Services {
-  return new Services({});
+function createMockServices(workingDirectory?: string): Services {
+  return new Services({workingDirectory});
 }
 
 /**
@@ -114,22 +115,20 @@ describe('tools/page-designer-decorator', () => {
   let originalCwd: string;
 
   beforeEach(() => {
-    services = createMockServices();
     // Create a temporary directory for test components
     testDir = path.join(tmpdir(), `b2c-mcp-test-${Date.now()}`);
     mkdirSync(testDir, {recursive: true});
     originalCwd = process.cwd();
     process.chdir(testDir);
-    // Set SFCC_WORKING_DIRECTORY to the test directory
-    process.env.SFCC_WORKING_DIRECTORY = testDir;
+    // Create services with workingDirectory set to test directory
+    services = createMockServices(testDir);
   });
 
   afterEach(() => {
     process.chdir(originalCwd);
     if (existsSync(testDir)) {
       rmSync(testDir, {recursive: true, force: true});
     }
-    delete process.env.SFCC_WORKING_DIRECTORY;
   });
 
   describe('tool metadata', () => {
@@ -186,13 +185,14 @@ describe('tools/page-designer-decorator', () => {
       expect(text).to.include('TestComponent');
     });
 
-    it('should use SFCC_WORKING_DIRECTORY if set', async () => {
-      const tool = createPageDesignerDecoratorTool(services);
+    it('should use workingDirectory from Services', async () => {
       const customDir = path.join(tmpdir(), `b2c-mcp-test-custom-${Date.now()}`);
       mkdirSync(customDir, {recursive: true});
       createTestComponent(customDir, 'CustomComponent');
 
-      process.env.SFCC_WORKING_DIRECTORY = customDir;
+      // Create services with custom workingDirectory
+      const customServices = createMockServices(customDir);
+      const tool = createPageDesignerDecoratorTool(customServices);
 
       const result = await tool.handler({
         component: 'CustomComponent',