add page-designer-decorator tool for Storefront Next

[sf-cboscenco]

Summary

🎯 Overview

Successfully integrated a new MCP tool (add_page_designer_decorator) into the B2C DX MCP server. This tool enables developers to add Page Designer decorators (@Component, @AttributeDefinition, @RegionDefinition) to React components for Storefront Next projects.

Testing

How was this tested?
Tests are being provided also performed a manual test against a local StorefrontNext installation.

• Tests pass (pnpm test)
• Code is formatted (pnpm run format)

[patricksullivansf]

Great start. thank you! More detailed review soon. Can you update the description with test instructions and add a changeset.

see #133 for an example.

[sf-cboscenco]

Page Designer Decorator Tool - Manual Test Plan

Tool Name: add_page_designer_decorator
Toolset: STOREFRONTNEXT
Status: Non-GA (requires --allow-non-ga-tools flag)
Date: February 13, 2026

---

📋 Prerequisites

Environment Setup

1. Storefront Next Project

   • Have a local Storefront Next project available
   • Set SFCC_WORKING_DIRECTORY environment variable to project root
   • Example: export SFCC_WORKING_DIRECTORY=~/SFCC-Odyssey

2. MCP Server

   • Build the MCP server: cd packages/b2c-dx-mcp && pnpm run build
   • Start MCP server with non-GA tools enabled
   • Example: npx mcp-inspector --cli node bin/dev.js --toolsets STOREFRONTNEXT --allow-non-ga-tools

3. Test Components

   • Create test components in src/components/ directory
   • Components should have various prop types for comprehensive testing

---

🎯 Test Scenarios

Test Category 1: Component Discovery

TC-1.1: Name-Based Discovery (PascalCase)

Objective: Verify component discovery by name in standard location

Steps:

1. Create component: src/components/ProductCard.tsx with props interface
2. Call tool with: component: "ProductCard"
3. Verify tool finds the component without path

Expected Result:

• Tool successfully finds component
• Mode selection prompt appears
• Component name appears in output

Test Data:

// src/components/ProductCard.tsx
export interface ProductCardProps {
  title: string;
  price: number;
}

export default function ProductCard({title, price}: ProductCardProps) {
  return <div>{title} - ${price}</div>;
}

---

TC-1.2: Name-Based Discovery (Kebab-Case)

Objective: Verify component discovery with kebab-case naming

Steps:

1. Create component: src/components/product-card.tsx
2. Call tool with: component: "product-card"
3. Verify tool finds the component

Expected Result:

• Tool finds component regardless of naming convention
• Works with both PascalCase and kebab-case

---

TC-1.3: Nested Component Discovery

Objective: Verify discovery of components in subdirectories

Steps:

1. Create component: src/components/hero/Hero.tsx
2. Call tool with: component: "Hero"
3. Verify tool finds nested component

Expected Result:

• Tool searches recursively in component directories
• Finds components in subdirectories

---

TC-1.4: Path-Based Input

Objective: Verify backward compatibility with path-based input

Steps:

1. Create component: src/components/TestComponent.tsx
2. Call tool with: component: "src/components/TestComponent.tsx"
3. Verify tool accepts path input

Expected Result:

• Tool accepts both name and path inputs
• Path-based input works correctly

---

TC-1.5: Custom Search Paths

Objective: Verify custom search paths for monorepo structures

Steps:

1. Create component in: packages/retail/src/components/CustomComponent.tsx
2. Call tool with:

   {
     "component": "CustomComponent",
     "searchPaths": ["packages/retail/src"]
   }

3. Verify tool finds component in custom location

Expected Result:

• Tool searches in custom paths
• Finds components outside standard locations

---

TC-1.6: Component Not Found

Objective: Verify error handling for non-existent components

Steps:

1. Call tool with: component: "NonExistentComponent"
2. Verify error message

Expected Result:

• Returns error result (isError: true)
• Error message includes:
  • Component name searched
  • List of searched locations
  • Helpful tips for resolution

---

Test Category 2: Auto Mode

TC-2.1: Basic Auto Mode

Objective: Verify auto mode generates decorators for simple component

Steps:

1. Create component with simple props:

   interface SimpleProps {
     title: string;
     count: number;
   }

2. Call tool with:

   {
     "component": "SimpleComponent",
     "autoMode": true
   }

3. Verify generated decorator code

Expected Result:

• Generates @Component decorator
• Generates @AttributeDefinition decorators for title and count
• Includes proper imports
• Code is ready to copy into component file

---

TC-2.2: Auto Mode - Excludes Complex Props

Objective: Verify auto mode excludes complex types

Steps:

1. Create component with mixed props:

   interface MixedProps {
     title: string;
     onClick: () => void;
     config: { key: string };
   }

2. Call tool with autoMode: true
3. Verify generated decorators

Expected Result:

• Includes title in decorators
• Excludes onClick (function type)
• Excludes config (object type)
• Output explains why complex props were excluded

---

TC-2.3: Auto Mode - Excludes UI-Only Props

Objective: Verify auto mode excludes UI-only props

Steps:

1. Create component with UI props:

   interface UIProps {
     title: string;
     className: string;
     style: React.CSSProperties;
   }

2. Call tool with autoMode: true
3. Verify generated decorators

Expected Result:

• Includes title in decorators
• Excludes className and style
• Output explains UI-only props exclusion

---

TC-2.4: Auto Mode - Type Inference

Objective: Verify automatic type inference for common patterns

Steps:

1. Create component with URL/image props:

   interface MediaProps {
     imageUrl: string;
     ctaUrl: string;
     productId: string;
   }

2. Call tool with autoMode: true
3. Verify type suggestions

Expected Result:

• Suggests type: 'url' for imageUrl and ctaUrl
• Suggests type: 'string' for productId
• Provides human-readable names

---

TC-2.5: Auto Mode - Component Already Decorated

Objective: Verify handling of components with existing decorators

Steps:

1. Create component with existing @Component decorator
2. Call tool with autoMode: true
3. Verify warning message

Expected Result:

• Detects existing decorators
• Returns warning message
• Suggests modifying existing decorators instead

---

TC-2.6: Auto Mode - Custom Component ID

Objective: Verify custom component ID override

Steps:

1. Create component: MyComponent.tsx
2. Call tool with:

   {
     "component": "MyComponent",
     "autoMode": true,
     "componentId": "custom-my-component-id"
   }

3. Verify generated decorator uses custom ID

Expected Result:

• Uses provided componentId instead of auto-generated
• Custom ID appears in @Component decorator

---

Test Category 3: Interactive Mode

TC-3.1: Mode Selection

Objective: Verify mode selection prompt appears

Steps:

1. Create component: TestComponent.tsx
2. Call tool with only: component: "TestComponent"
3. Verify mode selection output

Expected Result:

• Presents mode selection options
• Explains Auto Mode vs Interactive Mode
• Waits for user to choose mode
• Includes component name in output

---

TC-3.2: Interactive Mode - Analyze Step

Objective: Verify analysis step provides component information

Steps:

1. Create component with various prop types
2. Call tool with:

   {
     "component": "TestComponent",
     "conversationContext": {
       "step": "analyze"
     }
   }

3. Verify analysis output

Expected Result:

• Shows component name and file path
• Lists all props with types
• Categorizes props (editable, complex, UI-only)
• Suggests component ID and name
• Provides next steps guidance

---

TC-3.3: Interactive Mode - Select Props Step

Objective: Verify prop selection step

Steps:

1. Call tool with:

   {
     "component": "TestComponent",
     "conversationContext": {
       "step": "select_props",
       "selectedProps": ["title", "description"],
       "componentMetadata": {
         "id": "test-component",
         "name": "Test Component",
         "description": "Test component description"
       }
     }
   }

2. Verify confirmation output

Expected Result:

• Confirms selected props
• Shows component metadata
• Provides next step instructions

---

TC-3.4: Interactive Mode - Select Props (Missing Metadata)

Objective: Verify error when metadata is missing

Steps:

1. Call tool with select_props step but no componentMetadata
2. Verify error handling

Expected Result:

• Returns error (isError: true)
• Error message explains missing metadata requirement
• Provides guidance on required fields

---

TC-3.5: Interactive Mode - Configure Attributes Step

Objective: Verify attribute configuration step

Steps:

1. Call tool with:

   {
     "component": "TestComponent",
     "conversationContext": {
       "step": "configure_attrs",
       "selectedProps": ["imageUrl", "description"]
     }
   }

2. Verify configuration guidance

Expected Result:

• Lists props to configure
• Suggests appropriate types (url, image, etc.)
• Provides configuration examples
• Explains attribute options

---

TC-3.6: Interactive Mode - Configure Regions Step

Objective: Verify region configuration step

Steps:

1. Call tool with:

   {
     "component": "TestComponent",
     "conversationContext": {
       "step": "configure_regions"
     }
   }

2. Verify region configuration guidance

Expected Result:

• Explains region concept
• Provides region configuration examples
• Shows how to enable/disable regions

---

TC-3.7: Interactive Mode - Confirm Generation Step

Objective: Verify final code generation step

Steps:

1. Call tool with complete context:

   {
     "component": "TestComponent",
     "conversationContext": {
       "step": "confirm_generation",
       "selectedProps": ["title"],
       "componentMetadata": {
         "id": "test-component",
         "name": "Test Component",
         "description": "Test description"
       },
       "attributeConfig": {
         "title": {
           "type": "string",
           "name": "Title"
         }
       }
     }
   }

2. Verify generated code

Expected Result:

• Generates complete decorator code
• Includes all imports
• Includes @Component decorator
• Includes @AttributeDefinition decorators
• Provides next steps (adding code, generating cartridge, etc.)

---

TC-3.8: Interactive Mode - Confirm Generation (Missing Metadata)

Objective: Verify error when metadata missing in final step

Steps:

1. Call tool with confirm_generation step but no componentMetadata
2. Verify error handling

Expected Result:

• Returns error
• Explains missing metadata requirement
• Suggests starting from beginning

---

Test Category 4: Error Handling

TC-4.1: Invalid Input Type

Objective: Verify Zod validation catches invalid input

Steps:

1. Call tool with invalid input: component: 123
2. Verify validation error

Expected Result:

• Returns error (isError: true)
• Error message explains invalid input
• Provides guidance on correct input format

---

TC-4.2: Invalid Step Name

Objective: Verify error for invalid conversation step

Steps:

1. Call tool with:

   {
     "component": "TestComponent",
     "conversationContext": {
       "step": "invalid_step"
     }
   }

2. Verify error handling

Expected Result:

• Returns error
• Error message includes unknown step name
• Lists valid step options

---

TC-4.3: Missing Required Parameter

Objective: Verify error when component parameter is missing

Steps:

1. Call tool without component parameter
2. Verify validation error

Expected Result:

• Returns validation error
• Explains missing required parameter
• Provides parameter description

---

Test Category 5: Edge Cases

TC-5.1: Component with No Props

Objective: Verify handling of component with empty props interface

Steps:

1. Create component: EmptyProps.tsx with empty interface
2. Call tool with autoMode: true
3. Verify output

Expected Result:

• Handles gracefully
• Explains no editable props found
• Suggests adding props or using interactive mode

---

TC-5.2: Component with Only Complex Props

Objective: Verify handling when all props are complex

Steps:

1. Create component with only function/object props
2. Call tool with autoMode: true
3. Verify output

Expected Result:

• Explains no suitable props found
• Suggests using interactive mode
• Lists complex props found

---

TC-5.3: Component with Optional Props

Objective: Verify handling of optional props

Steps:

1. Create component with optional props:

   interface OptionalProps {
     title?: string;
     count?: number;
   }

2. Call tool with autoMode: true
3. Verify decorator generation

Expected Result:

• Handles optional props correctly
• Generates appropriate decorators
• Marks props as optional in generated code

---

TC-5.4: Component with Union Types

Objective: Verify handling of union type props

Steps:

1. Create component with union types:

   interface UnionProps {
     status: 'active' | 'inactive';
     value: string | number;
   }

2. Call tool with autoMode: true
3. Verify handling

Expected Result:

• Handles union types appropriately
• May suggest enum type for string unions
• Explains type complexity if needed

---

TC-5.5: Component Name Collision

Objective: Verify handling when multiple components match name

Steps:

1. Create two components with same name in different locations:
   • src/components/Test.tsx
   • app/components/Test.tsx
2. Call tool with: component: "Test"
3. Verify which component is selected

Expected Result:

• Selects component based on search priority
• Prefers shortest path (closest to root)
• Output indicates which file was used

---

Test Category 6: Environment Variables

TC-6.1: SFCC_WORKING_DIRECTORY Set

Objective: Verify tool uses environment variable when set

Steps:

1. Set export SFCC_WORKING_DIRECTORY=/path/to/project
2. Create component in that project
3. Call tool from different directory
4. Verify tool finds component

Expected Result:

• Uses SFCC_WORKING_DIRECTORY for workspace root
• Finds components in specified directory
• Works regardless of current working directory

---

TC-6.2: SFCC_WORKING_DIRECTORY Not Set

Objective: Verify fallback to process.cwd()

Steps:

1. Unset SFCC_WORKING_DIRECTORY
2. Navigate to project root
3. Call tool
4. Verify tool uses current directory

Expected Result:

• Falls back to process.cwd()
• Finds components relative to current directory
• Works when called from project root

---

Test Category 7: Real Storefront Next Project Integration

TC-7.1: Real Component in Storefront Next Project

Objective: Verify tool works with actual components from a real Storefront Next installation

Prerequisites:

• Local Storefront Next project available (e.g., ~/SFCC-Odyssey)
• SFCC_WORKING_DIRECTORY environment variable set to project root
• Existing component in the project (or create a test component)

Steps:

1. Set environment variable: export SFCC_WORKING_DIRECTORY=~/SFCC-Odyssey
2. Navigate to a component in the project (e.g., src/components/ProductCard.tsx)
3. Call tool with: component: "ProductCard" (or actual component name)
4. Run through auto mode workflow
5. Copy generated decorator code into the component file
6. Verify code compiles without errors
7. Run pnpm sfnext generate-cartridge to generate metadata
8. Verify metadata files are created correctly

Expected Result:

• Tool finds component in real project structure
• Generated decorator code is valid TypeScript
• Code compiles successfully
• Cartridge metadata generation succeeds
• No TypeScript errors in IDE

---

TC-7.2: Real Component - Interactive Mode Full Workflow

Objective: Verify complete interactive workflow with real component

Prerequisites:

• Local Storefront Next project available
• SFCC_WORKING_DIRECTORY set to project root
• Real component with multiple props

Steps:

1. Set SFCC_WORKING_DIRECTORY to project root
2. Select a real component from the project
3. Run through all interactive steps:
   • Step 1: Analyze
   • Step 2: Select props
   • Step 3: Configure attributes
   • Step 4: Configure regions (optional)
   • Step 5: Confirm generation
4. Copy generated code to component file
5. Verify compilation and cartridge generation

Expected Result:

• All interactive steps work correctly
• Generated code integrates seamlessly with existing component
• No conflicts with existing code
• Cartridge metadata generated successfully

---

TC-7.3: Real Component - Verify Generated Decorators Work

Objective: Verify generated decorators function correctly in Page Designer

Prerequisites:

• Local Storefront Next project
• Component with generated decorators (from TC-7.1 or TC-7.2)
• Cartridge metadata generated

Steps:

1. Deploy cartridge to Commerce Cloud instance
2. Log into Business Manager
3. Navigate to Page Designer
4. Verify component appears in component library
5. Add component to a page
6. Verify all attributes appear in Page Designer UI
7. Edit attribute values
8. Verify values are saved and displayed correctly

Expected Result:

• Component appears in Page Designer component library
• All attributes are editable in Page Designer UI
• Attribute values persist correctly
• Component renders on page with correct values

---

TC-7.4: Real Component - Monorepo Structure

Objective: Verify tool works with monorepo Storefront Next projects

Prerequisites:

• Storefront Next project in monorepo structure (e.g., packages/template-retail-rsc-app)
• Component in non-standard location

Steps:

1. Set SFCC_WORKING_DIRECTORY to monorepo root
2. Use searchPaths to point to Storefront Next package:

   {
     "component": "MyComponent",
     "searchPaths": ["packages/template-retail-rsc-app/src"]
   }

3. Verify tool finds component
4. Generate decorators
5. Verify code works in monorepo context

Expected Result:

• Tool finds components in monorepo structure
• Generated code uses correct import paths
• Works with monorepo build system

---

TC-7.5: Real Component - Existing Decorators

Objective: Verify tool handles components that already have decorators

Prerequisites:

• Storefront Next project
• Component with existing @Component decorator

Steps:

1. Select component with existing decorators
2. Call tool with autoMode: true
3. Verify warning message
4. Test interactive mode to see if it can modify existing decorators

Expected Result:

• Tool detects existing decorators
• Provides appropriate warning/guidance
• Doesn't duplicate decorators
• Can guide modification if needed

---

📊 Test Execution Checklist

Pre-Test Setup

• Storefront Next project available
• SFCC_WORKING_DIRECTORY environment variable set (if needed)
• MCP server built and running
• Test components created in various locations
• MCP inspector/client connected with --allow-non-ga-tools flag

Test Execution

• Component Discovery tests (TC-1.1 through TC-1.6)
• Auto Mode tests (TC-2.1 through TC-2.6)
• Interactive Mode tests (TC-3.1 through TC-3.8)
• Error Handling tests (TC-4.1 through TC-4.3)
• Edge Cases tests (TC-5.1 through TC-5.5)
• Environment Variable tests (TC-6.1 through TC-6.2)
• Real Storefront Next Project tests (TC-7.1 through TC-7.5) ⭐ REQUIRES LOCAL INSTALLATION

Post-Test Verification

• All test cases executed
• Results documented
• Issues logged (if any)
• Generated decorator code validated
• Decorator code tested in actual Storefront Next project ⭐
• Component verified in Page Designer ⭐
• Cartridge metadata generated and deployed ⭐

---

🐛 Known Issues / Limitations

Current Limitations

• Tool requires --allow-non-ga-tools flag (non-GA status)
• Some complex TypeScript types may not be fully supported
• Very large components (>100 props) may have performance impact

Expected Behavior

• Tool should handle all standard React component patterns
• Error messages should be helpful and actionable
• Generated code should be production-ready

---

📝 Test Results Template

Test Case: TC-X.X
Date: YYYY-MM-DD
Tester: [Name]
Status: ✅ Pass / ❌ Fail / ⚠️ Partial

Steps Executed:
1. [Step]
2. [Step]
3. [Step]

Expected Result:
[Expected outcome]

Actual Result:
[Actual outcome]

Notes:
[Any additional observations]

---

🎯 Success Criteria

All tests pass when:

• ✅ Component discovery works for all naming conventions
• ✅ Auto mode generates correct decorators
• ✅ Interactive mode guides through all steps
• ✅ Error handling provides helpful messages
• ✅ Edge cases handled gracefully
• ✅ Environment variables respected
• ✅ Generated code is valid TypeScript
• ✅ Generated code works in Storefront Next project

---

📚 Additional Resources

• Tool Documentation: packages/b2c-dx-mcp/src/tools/page-designer-decorator/README.md
• Toolset Documentation: packages/b2c-dx-mcp/src/tools/storefrontnext/README.md
• MCP Inspector: npx mcp-inspector --help
• Storefront Next Docs: [Internal documentation]

---

Test Plan Version: 1.0
Last Updated: February 13, 2026

[sf-cboscenco]

Great start. thank you! More detailed review soon. Can you update the description with test instructions and add a changeset.

see #133 for an example.

Testing instructions should be also available in the MCP tool test variant of the Readme.md.

[patricksullivansf]

Not a priority but Im guessing TC- 6.2 (current directory) is of dubious value with cursor where mcp cwd is -

[patricksullivansf]

@clavery need your opinion on this change to dep management please?

[clavery]

Only the ones necessary for the build process should be listed here. If it's not necessary to run the install scripts for our use cases it shouldn't be listed.

[sf-cboscenco]

Not a priority but Im guessing TC- 6.2 (current directory) is of dubious value with cursor where mcp cwd is -

TC-6.2: Current Directory Fallback Behavior

How It Works

When SFCC_WORKING_DIRECTORY is not set, the tool uses:

const workspaceRoot = process.env.SFCC_WORKING_DIRECTORY || process.cwd();

If you start the server from the project directory, process.cwd() will be that directory, so component discovery should work.

Example Scenarios

Scenario 1: Manual Start from Project Directory (Works)

# Navigate to your Storefront Next project
cd /path/to/storefront-next

# Start MCP server manually
node /path/to/b2c-dx-mcp/bin/dev.js --toolsets STOREFRONTNEXT --allow-non-ga-tools

# process.cwd() = /path/to/storefront-next ✅
# Component discovery will search in: /path/to/storefront-next/src/components/

Scenario 2: MCP Client Spawns from Home Directory (Fails)

# Cursor/Claude Desktop spawns server from:
cd ~  # /Users/username/

# Server process starts here
node /path/to/b2c-dx-mcp/bin/dev.js --toolsets STOREFRONTNEXT

# process.cwd() = /Users/username/ ❌
# Component discovery searches in: /Users/username/src/components/ (wrong!)

Scenario 3: Using --working-directory Flag (Recommended)

# Start from anywhere
cd ~

# But explicitly set working directory
node /path/to/b2c-dx-mcp/bin/dev.js \
  --working-directory /path/to/storefront-next \
  --toolsets STOREFRONTNEXT \
  --allow-non-ga-tools

# Tool uses --working-directory flag value ✅
# Component discovery searches in: /path/to/storefront-next/src/components/

Important Caveat

While starting from the project directory works, it's not reliable because:

1. MCP clients (Cursor, Claude Desktop) typically spawn servers from unexpected locations (often ~)
2. You can't control where the client starts the server process
3. The working directory may change if the server is restarted

Best Practice

Always set --working-directory or SFCC_WORKING_DIRECTORY in your MCP client configuration:

// Cursor mcp.json
{
  "mcpServers": {
    "b2c-dx": {
      "command": "node",
      "args": [
        "/path/to/b2c-dx-mcp/bin/dev.js",
        "--working-directory", "${workspaceFolder}",  // ✅ Explicit
        "--toolsets", "STOREFRONTNEXT",
        "--allow-non-ga-tools"
      ]
    }
  }
}

This ensures it works regardless of where the MCP client starts the server process.

Summary

• ✅ Yes, starting from the project directory makes TC-6.2 succeed
• ⚠️ Not reliable in practice because MCP clients control where the server starts
• ✅ Always use --working-directory or SFCC_WORKING_DIRECTORY for reliable behavior
• 🧪 TC-6.2 tests the fallback mechanism, but explicit configuration is recommended

[salesforce-cla]

Thanks for the contribution! It looks like @sf-cboscenco is an internal user so signing the CLA is not required. However, we need to confirm this.

[patricksullivansf]

nits for later follow up:

new lint warnings will impair future developer work

/opt/workspace/dev/b2c-developer-tooling/packages/b2c-dx-mcp/src/tools/page-designer-decorator/index.ts
  369:1  warning  Function 'handleConfirmGenerationStep' has a complexity of 23. Maximum allowed is 20  complexity

/opt/workspace/dev/b2c-developer-tooling/packages/b2c-dx-mcp/test/tools/page-designer-decorator/index.test.ts
  463:54  warning  Too many nested callbacks (5). Maximum allowed is 4  max-nested-callbacks
  484:54  warning  Too many nested callbacks (5). Maximum allowed is 4  max-nested-callbacks
  514:54  warning  Too many nested callbacks (5). Maximum allowed is 4  max-nested-callbacks
  540:54  warning  Too many nested callbacks (5). Maximum allowed is 4  max-nested-callbacks
  561:54  warning  Too many nested callbacks (5). Maximum allowed is 4  max-nested-callbacks
  582:54  warning  Too many nested callbacks (5). Maximum allowed is 4  max-nested-callbacks
  603:54  warning  Too many nested callbacks (5). Maximum allowed is 4  max-nested-callbacks
  623:54  warning  Too many nested callbacks (5). Maximum allowed is 4  max-nested-callbacks
  656:54  warning  Too many nested callbacks (5). Maximum allowed is 4  max-nested-callbacks

code coverage is lower than typical for this package

[patricksullivansf]

Sorry this was such a grind. I noted a few areas for future follow up. Thanks for pushing this through. Hopefully the remainder of the tool ports will be easier going forward.