Merge branch 'main' into add-mrt-utilities

Author: kieran-sf

.changeset/docs-mcp-preview-update.md

@@ -123,9 +123,14 @@ jobs:
               per_page: 100,
             });
 
+            // Exclude package.json under test/fixtures/ (e.g. e2e workspace-detection fixtures)
+            const isUnderTestFixtures = (filename) =>
+              filename.includes('/test/') && filename.includes('/fixtures/');
             const changedPackageJsonFiles = files
               .map((file) => file.filename)
-              .filter((filename) => filename.endsWith('package.json'));
+              .filter((filename) =>
+                filename.endsWith('package.json') && !isUnderTestFixtures(filename),
+              );
 
             const findings = [];
 
@@ -200,4 +205,4 @@ jobs:
             await addLabel(reviewLabel);
             core.setFailed(
               `Net-new third-party dependencies found: ${allNetNewDeps.join(', ')}. Add \`${approvalLabel}\` after review.`,
-            );
+            );

.changeset/unregister-placeholder-tools.md

@@ -166,3 +166,39 @@ jobs:
             if (context.eventName === 'schedule') {
               github.rest.issues.create(issue);
             }
+
+  mcp-e2e-tests:
+    name: MCP E2E
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.17.1
+      - name: Get pnpm store directory
+        id: pnpm-store
+        shell: bash
+        run: |
+          echo "store_path=$(pnpm store path --silent)" >> $GITHUB_OUTPUT
+      - name: Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.pnpm-store.outputs.store_path }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Build packages
+        run: pnpm -r run build
+      - name: Run MCP E2E tests
+        working-directory: packages/b2c-dx-mcp
+        env:
+          SFCC_DISABLE_TELEMETRY: 'true'
+          NODE_ENV: test
+        run: pnpm run test:e2e:ci

.github/workflows/3pl-guard.yml

@@ -51,6 +51,16 @@ const guideSidebar = [
       {text: 'Storefront Next', link: '/guide/storefront-next'},
     ],
   },
+  {
+    text: 'MCP Server',
+    items: [
+      {text: 'Overview', link: '/mcp/'},
+      {text: 'Installation', link: '/mcp/installation'},
+      {text: 'Configuration', link: '/mcp/configuration'},
+      {text: 'Toolsets & Tools', link: '/mcp/toolsets'},
+      {text: 'Figma Tools Setup', link: '/mcp/figma-tools-setup'},
+    ],
+  },
   {
     text: 'Extending',
     items: [
@@ -83,6 +93,23 @@ const guideSidebar = [
       {text: 'Logging', link: '/cli/logging'},
     ],
   },
+  {
+    text: 'Tools Reference',
+    items: [
+      {text: 'cartridge_deploy', link: '/mcp/tools/cartridge-deploy'},
+      {text: 'mrt_bundle_push', link: '/mcp/tools/mrt-bundle-push'},
+      {text: 'pwakit_development_guidelines', link: '/mcp/tools/pwakit-development-guidelines'},
+      {text: 'scapi_schemas_list', link: '/mcp/tools/scapi-schemas-list'},
+      {text: 'scapi_custom_api_scaffold', link: '/mcp/tools/scapi-custom-api-scaffold'},
+      {text: 'scapi_custom_apis_status', link: '/mcp/tools/scapi-custom-apis-status'},
+      {text: 'storefront_next_development_guidelines', link: '/mcp/tools/storefront-next-development-guidelines'},
+      {text: 'storefront_next_figma_to_component_workflow', link: '/mcp/tools/storefront-next-figma-to-component-workflow'},
+      {text: 'storefront_next_generate_component', link: '/mcp/tools/storefront-next-generate-component'},
+      {text: 'storefront_next_map_tokens_to_theme', link: '/mcp/tools/storefront-next-map-tokens-to-theme'},
+      {text: 'storefront_next_page_designer_decorator', link: '/mcp/tools/storefront-next-page-designer-decorator'},
+      {text: 'storefront_next_site_theming', link: '/mcp/tools/storefront-next-site-theming'},
+    ],
+  },
 ];
 
 // Script to force hard navigation for version switching links
@@ -133,6 +160,7 @@ export default defineConfig({
       {text: 'Guide', link: '/guide/'},
       {text: 'CLI Reference', link: '/cli/'},
       {text: 'API Reference', link: '/api/'},
+      {text: 'MCP Server', link: '/mcp/'},
       {
         text: isDevBuild ? 'Dev' : 'Latest',
         items: getVersionItems(),
@@ -147,6 +175,7 @@ export default defineConfig({
     sidebar: {
       '/guide/': guideSidebar,
       '/cli/': guideSidebar,
+      '/mcp/': guideSidebar,
       '/api/': [
         {
           text: 'API Reference',

.github/workflows/e2e-tests.yml

@@ -1,5 +1,13 @@
 # @salesforce/b2c-dx-docs
 
+## 0.2.1
+
+### Patch Changes
+
+- [#202](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/pull/202) [`917c230`](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/commit/917c230d033b7b12bd0262d221173618f71cd0a7) - MCP docs: preview release wording, sidebar nav, remove placeholder tool references (Thanks [@yhsieh1](https://github.com/yhsieh1)!)
+
+- [#217](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/pull/217) [`eee5dbc`](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/commit/eee5dbc126db7a635389889204a504e25ea132fb) - Add MCP tool reference documentation for pwakit_development_guidelines and storefront_next_development_guidelines; MCP Server sidebar, Tools Reference, and nav updates in config (Thanks [@yhsieh1](https://github.com/yhsieh1)!)
+
 ## 0.2.0
 
 ### Minor Changes

docs/.vitepress/config.mts

@@ -0,0 +1,136 @@
+---
+description: Prerequisites and setup for Figma-to-component tools (workflow orchestrator, generate component, map tokens).
+---
+
+# Figma-to-Component Tools Setup
+
+Prerequisites and setup for using the Figma workflow tools: `storefront_next_figma_to_component_workflow`, `storefront_next_generate_component`, and `storefront_next_map_tokens_to_theme`.
+
+## Overview
+
+The Figma-to-component workflow uses **two MCP servers** that must both be enabled in your MCP client:
+
+1. **b2c-dx-mcp** - Workflow orchestration, component analysis (REUSE/EXTEND/CREATE), and token mapping
+2. **Figma MCP** (external) - Fetches design context, screenshots, and metadata from Figma files
+
+For full end-to-end conversion from Figma design to Storefront Next component, both servers must be configured and enabled.
+
+## B2C DX MCP Configuration
+
+Ensure the b2c-dx-mcp server is configured with:
+
+- **`--project-directory`** - Must point to your Storefront Next project root. Required for:
+  - `storefront_next_map_tokens_to_theme` - Theme file discovery (`app.css`)
+  - `storefront_next_generate_component` - Workspace context
+- **`--allow-non-ga-tools`** - Figma tools are preview; this flag is required to enable them
+- **Storefront Next project** - Must have `app.css` or `src/app.css` for token mapping (or pass `themeFilePath` explicitly)
+
+See [Installation](./installation) for MCP client setup (Cursor, Claude Desktop, etc.).
+
+## Figma MCP Setup
+
+The workflow calls Figma MCP tools to fetch design data. These come from a **separate Figma MCP server** that you must enable in your MCP client.
+
+**Figma MCP tools used by the workflow:**
+
+| Tool | Purpose |
+|------|---------|
+| `get_design_context` | Generates UI code from the design and returns asset URLs |
+| `get_screenshot` | Provides a visual reference image of the design |
+| `get_metadata` | Retrieves node hierarchy, layer types, names, positions, and sizes |
+
+See the [Figma MCP Server Documentation](https://developers.figma.com/docs/figma-mcp-server) for official setup and tool details.
+
+Figma provides two connection options. Check the [Figma MCP catalog](https://www.figma.com/mcp-catalog/) to see which your client supports, then follow the matching installation:
+
+### Desktop MCP (Local)
+
+Runs through the Figma desktop app on your machine. No API token required; uses your Figma app session.
+
+- Requires the Figma desktop application to be installed and running
+- See [Figma MCP - Local Server Installation](https://developers.figma.com/docs/figma-mcp-server/local-server-installation/)
+
+### Remote MCP (Hosted)
+
+Connects directly to Figma's hosted endpoint. Does not require the desktop app but **requires a Figma Personal Access Token**.
+
+- See [Figma MCP - Remote Server Installation](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/)
+
+#### Creating a Figma Personal Access Token
+
+1. Log in to [Figma](https://www.figma.com)
+2. Click your profile icon (top-left) → **Settings**
+3. Go to **Settings → Security → Personal Access Tokens**
+4. Click **Generate New Token** and give it a name (e.g., "MCP")
+5. Select **read-only** access for all scopes
+6. Click **Generate token** and **copy the token immediately** — Figma shows it only once
+
+#### Storing the Token
+
+Store the token in an environment variable (e.g., `FIGMA_API_KEY` or `FIGMA_ACCESS_TOKEN`). Do not hardcode it in configuration files or commit it to version control.
+
+**Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "figma": {
+      "command": "...",
+      "env": {
+        "FIGMA_API_KEY": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+Refer to your Figma MCP provider's documentation for the exact environment variable name and configuration.
+
+## Figma Design File
+
+### File Access
+
+You must have **view access** (or higher) to the Figma file. The file cannot be restricted in a way that blocks API access.
+
+### URL with node-id
+
+The workflow requires a Figma URL that includes the `node-id` query parameter. This identifies the specific frame or component to convert.
+
+**How to get a URL with node-id:**
+
+1. Open the Figma file
+2. Select the frame or component you want to convert
+3. Right-click → **Copy link to selection** (or use the share menu)
+4. The copied URL will include `?node-id=1-2` (or similar)
+
+**Supported URL formats:**
+
+- `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
+- `https://www.figma.com/design/:fileKey/:fileName?node-id=1-2`
+- `https://figma.com/file/:fileKey/:fileName?node-id=1-2`
+
+### No Special Figma Configuration
+
+The basic workflow does not require:
+
+- Figma Dev Mode
+- Code Connect
+- Plugins
+- Special file structure
+
+## Verification
+
+To confirm both servers are working:
+
+1. **b2c-dx-mcp** - List tools in your MCP client; you should see `storefront_next_figma_to_component_workflow`, `storefront_next_generate_component`, and `storefront_next_map_tokens_to_theme`
+2. **Figma MCP** - List tools; you should see `mcp__figma__get_design_context`, `mcp__figma__get_screenshot`, and `mcp__figma__get_metadata` (or similar names per your Figma MCP provider)
+
+If the Figma MCP server is not enabled, the workflow tool will still return instructions and parsed parameters, but the AI assistant will not be able to fetch design data. Inform the user that the Figma MCP server must be enabled for full conversion.
+
+## Related Documentation
+
+- [storefront_next_figma_to_component_workflow](./tools/storefront-next-figma-to-component-workflow) - Workflow orchestrator (call first)
+- [storefront_next_generate_component](./tools/storefront-next-generate-component) - REUSE/EXTEND/CREATE recommendation
+- [storefront_next_map_tokens_to_theme](./tools/storefront-next-map-tokens-to-theme) - Token mapping
+- [STOREFRONTNEXT Toolset](./toolsets#storefrontnext) - Overview of Storefront Next tools
+- [Figma MCP Server Documentation](https://developers.figma.com/docs/figma-mcp-server) - Official Figma MCP setup

docs/CHANGELOG.md

@@ -120,6 +120,7 @@ AI assistants automatically decide which MCP tools to use based on your prompts.
 **Storefront Next Development:**
 - ✅ "I'm new to Storefront Next. Use the MCP tool to show me the critical rules I need to know."
 - ✅ "I need to build a product detail page. Use the MCP tool to show me best practices for data fetching and component patterns."
+- ✅ "I want to apply my brand colors to my Storefront Next site. Use the MCP tool to help me."
 
 **SCAPI Discovery:**
 - ✅ "Use the MCP tool to list all available SCAPI schemas."
@@ -131,6 +132,11 @@ AI assistants automatically decide which MCP tools to use based on your prompts.
 **MRT Bundle Operations:**
 - ✅ "Use the MCP tool to build and push my Storefront Next bundle to staging."
 
+**Figma-to-Component:**
+- ✅ "Use the MCP tool to convert this Figma design to a Storefront Next component: [Figma URL with node-id]"
+- ✅ "Use the MCP tool to create this homepage from the Figma design: [Figma URL with node-id]. Create new components or update existing components using the MCP tool if necessary, then update the home page. The expected result should be that the homepage matches as closely as possible to the provided Figma design."
+- ✅ "Use the MCP tool to map Figma design tokens to my theme."
+
 See the [Toolsets & Tools Reference](./toolsets) for more prompting examples for each toolset.
 
 ## Telemetry

docs/mcp/figma-tools-setup.md

@@ -12,6 +12,8 @@ This guide covers installing and configuring the B2C DX MCP Server for various M
 - A B2C Commerce project (for project-specific toolsets)
 - MCP client (Cursor, Claude Desktop, or compatible client)
 
+**Figma-to-component tools:** If you use the Figma workflow tools (`storefront_next_figma_to_component_workflow`, `storefront_next_generate_component`, `storefront_next_map_tokens_to_theme`), you also need an external Figma MCP server enabled. See [Figma-to-Component Tools Setup](./figma-tools-setup) for prerequisites and configuration.
+
 ## Install via npm (Recommended)
 
 ```json