From 9d5699400385f94f85b434f3b5053c9ef02f3625 Mon Sep 17 00:00:00 2001 From: Yuming Hsieh Date: Tue, 17 Mar 2026 12:20:29 -0400 Subject: [PATCH 1/6] @W-21513849 update tool names and docs --- .changeset/mcp-tool-renames.md | 6 ++ docs/.vitepress/config.mts | 18 ++--- docs/mcp/figma-tools-setup.md | 10 +-- ...guidelines.md => pwakit-get-guidelines.md} | 4 +- ... => scapi-custom-api-generate-scaffold.md} | 10 +-- ...tus.md => scapi-custom-apis-get-status.md} | 4 +- docs/mcp/tools/scapi-schemas-list.md | 23 ++---- ... => sfnext-add-page-designer-decorator.md} | 4 +- ...mponent.md => sfnext-analyze-component.md} | 54 ++++++------- ...e-theming.md => sfnext-configure-theme.md} | 4 +- ...guidelines.md => sfnext-get-guidelines.md} | 6 +- .../mcp/tools/sfnext-match-tokens-to-theme.md | 78 +++++++++++++++++++ ...flow.md => sfnext-start-figma-workflow.md} | 18 ++--- .../storefront-next-map-tokens-to-theme.md | 78 ------------------- docs/mcp/toolsets.md | 30 +++---- packages/b2c-dx-mcp/CONTRIBUTING.md | 2 +- packages/b2c-dx-mcp/README.md | 42 +++++----- .../content/sfnext/page-designer.md | 20 ++--- .../content/sfnext/quick-reference.md | 2 +- .../pwav3/pwa-kit-development-guidelines.ts | 2 +- packages/b2c-dx-mcp/src/tools/scapi/index.ts | 4 +- ... => scapi-custom-api-generate-scaffold.ts} | 12 +-- ...tus.ts => scapi-custom-apis-get-status.ts} | 10 +-- .../src/tools/scapi/scapi-schemas-list.ts | 2 +- .../src/tools/storefrontnext/README.md | 28 +++---- .../figma/figma-to-component/index.ts | 14 ++-- .../figma/generate-component/index.ts | 4 +- .../storefrontnext/figma/map-tokens/index.ts | 4 +- .../src/tools/storefrontnext/index.ts | 12 +-- .../page-designer-decorator/README.md | 8 +- .../page-designer-decorator/index.ts | 2 +- .../templates/decorator-generator.ts | 2 +- .../sfnext-development-guidelines.ts | 2 +- .../storefrontnext/site-theming/README.md | 4 +- .../storefrontnext/site-theming/index.ts | 2 +- packages/b2c-dx-mcp/test/e2e/mcp-e2e.test.ts | 13 ++-- packages/b2c-dx-mcp/test/registry.test.ts | 24 +++--- .../pwa-kit-development-guidelines.test.ts | 2 +- ...capi-custom-api-generate-scaffold.test.ts} | 8 +- ...s => scapi-custom-apis-get-status.test.ts} | 8 +- .../tools/scapi/scapi-schemas-list.test.ts | 2 +- .../test/tools/storefrontnext/figma/README.md | 22 +++--- .../figma/figma-to-component/index.test.ts | 8 +- .../page-designer-decorator/README.md | 6 +- .../page-designer-decorator/index.test.ts | 2 +- .../sfnext-development-guidelines.test.ts | 2 +- .../storefrontnext/site-theming/README.md | 8 +- .../storefrontnext/site-theming/index.test.ts | 2 +- 48 files changed, 312 insertions(+), 320 deletions(-) create mode 100644 .changeset/mcp-tool-renames.md rename docs/mcp/tools/{pwakit-development-guidelines.md => pwakit-get-guidelines.md} (96%) rename docs/mcp/tools/{scapi-custom-api-scaffold.md => scapi-custom-api-generate-scaffold.md} (88%) rename docs/mcp/tools/{scapi-custom-apis-status.md => scapi-custom-apis-get-status.md} (97%) rename docs/mcp/tools/{storefront-next-page-designer-decorator.md => sfnext-add-page-designer-decorator.md} (95%) rename docs/mcp/tools/{storefront-next-generate-component.md => sfnext-analyze-component.md} (52%) rename docs/mcp/tools/{storefront-next-site-theming.md => sfnext-configure-theme.md} (96%) rename docs/mcp/tools/{storefront-next-development-guidelines.md => sfnext-get-guidelines.md} (93%) create mode 100644 docs/mcp/tools/sfnext-match-tokens-to-theme.md rename docs/mcp/tools/{storefront-next-figma-to-component-workflow.md => sfnext-start-figma-workflow.md} (80%) delete mode 100644 docs/mcp/tools/storefront-next-map-tokens-to-theme.md rename packages/b2c-dx-mcp/src/tools/scapi/{scapi-custom-api-scaffold.ts => scapi-custom-api-generate-scaffold.ts} (96%) rename packages/b2c-dx-mcp/src/tools/scapi/{scapi-custom-apis-status.ts => scapi-custom-apis-get-status.ts} (96%) rename packages/b2c-dx-mcp/test/tools/scapi/{scapi-custom-api-scaffold.test.ts => scapi-custom-api-generate-scaffold.test.ts} (97%) rename packages/b2c-dx-mcp/test/tools/scapi/{scapi-custom-apis-status.test.ts => scapi-custom-apis-get-status.test.ts} (97%) diff --git a/.changeset/mcp-tool-renames.md b/.changeset/mcp-tool-renames.md new file mode 100644 index 00000000..6b931e71 --- /dev/null +++ b/.changeset/mcp-tool-renames.md @@ -0,0 +1,6 @@ +--- +'@salesforce/b2c-dx-mcp': minor +'@salesforce/b2c-dx-docs': patch +--- + +Rename MCP tools for clearer, action-oriented naming. scapi_custom_api_scaffold β†’ scapi_custom_api_generate_scaffold. sfnext_map_tokens_to_theme β†’ sfnext_match_tokens_to_theme. diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 80f4afdc..3df0dc84 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -102,16 +102,16 @@ const referenceSidebar = [ 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: 'pwakit_get_guidelines', link: '/mcp/tools/pwakit-get-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'}, + {text: 'scapi_custom_api_generate_scaffold', link: '/mcp/tools/scapi-custom-api-generate-scaffold'}, + {text: 'scapi_custom_apis_get_status', link: '/mcp/tools/scapi-custom-apis-get-status'}, + {text: 'sfnext_get_guidelines', link: '/mcp/tools/sfnext-get-guidelines'}, + {text: 'sfnext_start_figma_workflow', link: '/mcp/tools/sfnext-start-figma-workflow'}, + {text: 'sfnext_analyze_component', link: '/mcp/tools/sfnext-analyze-component'}, + {text: 'sfnext_match_tokens_to_theme', link: '/mcp/tools/sfnext-match-tokens-to-theme'}, + {text: 'sfnext_add_page_designer_decorator', link: '/mcp/tools/sfnext-add-page-designer-decorator'}, + {text: 'sfnext_configure_theme', link: '/mcp/tools/sfnext-configure-theme'}, ], }, ]; diff --git a/docs/mcp/figma-tools-setup.md b/docs/mcp/figma-tools-setup.md index 18ec3db5..e61d0f0f 100644 --- a/docs/mcp/figma-tools-setup.md +++ b/docs/mcp/figma-tools-setup.md @@ -4,7 +4,7 @@ description: Prerequisites and setup for Figma-to-component tools (workflow orch # 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`. +Prerequisites and setup for using the Figma workflow tools: `sfnext_start_figma_workflow`, `sfnext_analyze_component`, and `sfnext_match_tokens_to_theme`. > **Note:** 🚧 This MCP tool is for Storefront Next. Storefront Next is part of a closed pilot and isn't available for general use. @@ -15,7 +15,7 @@ The Figma-to-component workflow requires an **external Figma MCP server** to fet **Prerequisites:** - b2c-dx-mcp configured with `--allow-non-ga-tools` flag (Figma tools are preview) - Storefront Next project -- `app.css` theme file (required for `storefront_next_map_tokens_to_theme` tool; optional path can be provided) +- `app.css` theme file (required for `sfnext_match_tokens_to_theme` tool; optional path can be provided) - External Figma MCP server enabled in your MCP client See [Installation](./installation) for b2c-dx-mcp setup. @@ -49,8 +49,8 @@ If the Figma MCP server is not enabled, the workflow tool will still return inst ## 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 +- [sfnext_start_figma_workflow](./tools/sfnext-start-figma-workflow) - Workflow orchestrator (call first) +- [sfnext_analyze_component](./tools/sfnext-analyze-component) - REUSE/EXTEND/CREATE recommendation +- [sfnext_match_tokens_to_theme](./tools/sfnext-match-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 diff --git a/docs/mcp/tools/pwakit-development-guidelines.md b/docs/mcp/tools/pwakit-get-guidelines.md similarity index 96% rename from docs/mcp/tools/pwakit-development-guidelines.md rename to docs/mcp/tools/pwakit-get-guidelines.md index 914ff643..c97e9505 100644 --- a/docs/mcp/tools/pwakit-development-guidelines.md +++ b/docs/mcp/tools/pwakit-get-guidelines.md @@ -2,13 +2,13 @@ description: Get PWA Kit v3 development guidelines and best practices for React, Chakra UI, and Commerce API. --- -# pwakit_development_guidelines +# pwakit_get_guidelines Returns critical architecture rules, coding standards, and best practices for building PWA Kit v3 applications with React, Chakra UI, and Commerce API. ## Overview -The `pwakit_development_guidelines` tool provides essential development guidance for PWA Kit v3. It: +The `pwakit_get_guidelines` tool provides essential development guidance for PWA Kit v3. It: 1. Returns comprehensive guidelines by default (quick-reference plus key sections). 2. Supports retrieving specific topic sections on demand. diff --git a/docs/mcp/tools/scapi-custom-api-scaffold.md b/docs/mcp/tools/scapi-custom-api-generate-scaffold.md similarity index 88% rename from docs/mcp/tools/scapi-custom-api-scaffold.md rename to docs/mcp/tools/scapi-custom-api-generate-scaffold.md index 943369d0..6395a81b 100644 --- a/docs/mcp/tools/scapi-custom-api-scaffold.md +++ b/docs/mcp/tools/scapi-custom-api-generate-scaffold.md @@ -2,19 +2,19 @@ description: Generate a new custom SCAPI endpoint (OAS 3.0 schema, api.json, script.js) in an existing cartridge. --- -# scapi_custom_api_scaffold +# scapi_custom_api_generate_scaffold Generate a new custom SCAPI endpoint in an existing cartridge. Creates `schema.yaml` (OAS 3.0 contract), `api.json` (endpoint mapping), and `script.js` (implementation) under the cartridge's `rest-apis//` directory. ## Overview -The `scapi_custom_api_scaffold` tool scaffolds a new custom API using the B2C tooling SDK's `custom-api` scaffold. It: +The `scapi_custom_api_generate_scaffold` tool scaffolds a new custom API using the B2C tooling SDK's `custom-api` scaffold. It: - Creates an OpenAPI 3.0 schema, API manifest, and script stub in your project. - Uses the first cartridge found in the project if you don't specify one. - Supports **shopper** (siteId, customer-facing) or **admin** (no siteId) API types. -**No instance or OAuth required** β€” this tool works locally and only writes files into your project. To check registration status after deployment, use [`scapi_custom_apis_status`](./scapi-custom-apis-status). +**No instance or OAuth required** β€” this tool works locally and only writes files into your project. To check registration status after deployment, use [`scapi_custom_apis_get_status`](./scapi-custom-apis-get-status). ## Parameters @@ -78,7 +78,7 @@ Returns the scaffold ID, output directory, and list of created files: 1. **Edit** `schema.yaml` to define paths, request/response schemas, and operation IDs. 2. **Edit** `script.js` to implement the endpoint logic. 3. **Deploy** the cartridge to your instance and **activate** the code version to register the API. -4. **Verify** with [`scapi_custom_apis_status`](./scapi-custom-apis-status) that endpoints show as `active`. +4. **Verify** with [`scapi_custom_apis_get_status`](./scapi-custom-apis-get-status) that endpoints show as `active`. Shopper APIs are available at: `https://{shortCode}.api.commercecloud.salesforce.com/custom/{apiName}/v1/organizations/{organizationId}/...` and require the `siteId` query parameter and ShopperToken authentication. @@ -86,7 +86,7 @@ Shopper APIs are available at: ## Related Tools - Part of the [SCAPI](../toolsets#scapi), [PWAV3](../toolsets#pwav3), and [STOREFRONTNEXT](../toolsets#storefrontnext) toolsets -- [`scapi_custom_apis_status`](./scapi-custom-apis-status) β€” Check custom API endpoint registration status after deployment +- [`scapi_custom_apis_get_status`](./scapi-custom-apis-get-status) β€” Check custom API endpoint registration status after deployment - [`scapi_schemas_list`](./scapi-schemas-list) β€” List or fetch custom API schemas (use `apiFamily: "custom"`) ## See Also diff --git a/docs/mcp/tools/scapi-custom-apis-status.md b/docs/mcp/tools/scapi-custom-apis-get-status.md similarity index 97% rename from docs/mcp/tools/scapi-custom-apis-status.md rename to docs/mcp/tools/scapi-custom-apis-get-status.md index 63a676fa..f286437d 100644 --- a/docs/mcp/tools/scapi-custom-apis-status.md +++ b/docs/mcp/tools/scapi-custom-apis-get-status.md @@ -2,7 +2,7 @@ description: Check the registration status of custom SCAPI endpoints deployed on your B2C Commerce instance. --- -# scapi_custom_apis_status +# scapi_custom_apis_get_status List custom SCAPI endpoint registration status (active/not_registered). Returns one row per endpoint per site with detailed status information. @@ -10,7 +10,7 @@ List custom SCAPI endpoint registration status (active/not_registered). Returns Checks the registration status of custom API endpoints deployed on your B2C Commerce instance. Returns endpoint status (`active` or `not_registered`) with per-site details. -**Note:** This tool queries your live instance. For schema definitions, use [`scapi_schemas_list`](./scapi-schemas-list) with `apiFamily: "custom"`. To create a new custom API, use [`scapi_custom_api_scaffold`](./scapi-custom-api-scaffold). +**Note:** This tool queries your live instance. For schema definitions, use [`scapi_schemas_list`](./scapi-schemas-list) with `apiFamily: "custom"`. To create a new custom API, use [`scapi_custom_api_generate_scaffold`](./scapi-custom-api-generate-scaffold). ## Authentication diff --git a/docs/mcp/tools/scapi-schemas-list.md b/docs/mcp/tools/scapi-schemas-list.md index c9781bcb..e8407dc7 100644 --- a/docs/mcp/tools/scapi-schemas-list.md +++ b/docs/mcp/tools/scapi-schemas-list.md @@ -13,7 +13,7 @@ The `scapi_schemas_list` tool provides two modes of operation. 1. **List (Discovery)**: Browse available schemas without fetching full OpenAPI specs. 2. **Fetch**: Retrieve complete OpenAPI schema for a specific API. -This tool works with both standard SCAPI (Shop, Admin, Shopper APIs) and custom APIs. For endpoint registration status, use [`scapi_custom_apis_status`](./scapi-custom-apis-status) instead. +This tool works with both standard SCAPI (Shop, Admin, Shopper APIs) and custom APIs. For endpoint registration status, use [`scapi_custom_apis_get_status`](./scapi-custom-apis-get-status) instead. ## Authentication @@ -48,12 +48,6 @@ Omit `includeSchemas` or any identifier to browse available schemas: - `availableApiNames` - List of available API names - `availableApiVersions` - List of available API versions -**Example prompts:** -- βœ… "Use the MCP tool to list all available SCAPI schemas." -- βœ… "Use the MCP tool to show me what checkout APIs exist." β†’ `apiFamily: "checkout"` -- βœ… "Use the MCP tool to discover SCAPI product endpoints." β†’ `apiFamily: "product"` -- βœ… "Use the MCP tool to list custom API definitions." β†’ `apiFamily: "custom"` - ### Fetch Mode Set `includeSchemas: true` and provide all three identifiers (`apiFamily`, `apiName`, `apiVersion`) to fetch a complete OpenAPI schema: @@ -62,11 +56,6 @@ Set `includeSchemas: true` and provide all three identifiers (`apiFamily`, `apiN - Full OpenAPI schema specification - Use `expandAll: true` to get the complete schema without collapsing -**Example prompts:** -- βœ… "Use the MCP tool to get the OpenAPI schema for shopper-baskets v1." β†’ `apiFamily: "shopper"`, `apiName: "shopper-baskets"`, `apiVersion: "v1"`, `includeSchemas: true` -- βœ… "Use the MCP tool to show me the full OpenAPI spec for shopper-products v1." β†’ `includeSchemas: true`, `expandAll: true` -- βœ… "Use the MCP tool to show me the loyalty-points custom API schema." β†’ `apiFamily: "custom"`, `apiName: "loyalty-points"`, `apiVersion: "v1"`, `includeSchemas: true` - ## Usage Examples ### Standard SCAPI Discovery @@ -83,6 +72,10 @@ Filter by API family: Use the MCP tool to show me what checkout APIs exist. ``` +``` +Use the MCP tool to discover SCAPI product endpoints. +``` + ### Custom API Discovery List custom API definitions: @@ -154,13 +147,13 @@ Use the MCP tool to show me the full OpenAPI spec for shopper-products v1. - Part of the [SCAPI](../toolsets#scapi), [PWAV3](../toolsets#pwav3), and [STOREFRONTNEXT](../toolsets#storefrontnext) toolsets - Always enabled (base toolset) -- For endpoint registration status, use [`scapi_custom_apis_status`](./scapi-custom-apis-status) +- For endpoint registration status, use [`scapi_custom_apis_get_status`](./scapi-custom-apis-get-status) ## See Also - [SCAPI Toolset](../toolsets#scapi) - Overview of SCAPI discovery tools -- [scapi_custom_apis_status](./scapi-custom-apis-status) - Check custom API endpoint registration status -- [scapi_custom_api_scaffold](./scapi-custom-api-scaffold) - Generate a new custom API in a cartridge +- [scapi_custom_apis_get_status](./scapi-custom-apis-get-status) - Check custom API endpoint registration status +- [scapi_custom_api_generate_scaffold](./scapi-custom-api-generate-scaffold) - Generate a new custom API in a cartridge - [Authentication Setup](../../guide/authentication#scapi-authentication) - Set up SCAPI authentication with required roles and scopes - [Configuration](../configuration) - Configure OAuth credentials - [CLI Reference](../../cli/scapi-schemas) - Equivalent CLI commands: `b2c scapi schemas list` and `b2c scapi schemas get` diff --git a/docs/mcp/tools/storefront-next-page-designer-decorator.md b/docs/mcp/tools/sfnext-add-page-designer-decorator.md similarity index 95% rename from docs/mcp/tools/storefront-next-page-designer-decorator.md rename to docs/mcp/tools/sfnext-add-page-designer-decorator.md index 18ddc699..cd8c18f5 100644 --- a/docs/mcp/tools/storefront-next-page-designer-decorator.md +++ b/docs/mcp/tools/sfnext-add-page-designer-decorator.md @@ -2,7 +2,7 @@ description: Add Page Designer decorators to React components for Storefront Next to make them available in Page Designer. --- -# storefront_next_page_designer_decorator +# sfnext_add_page_designer_decorator Adds Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDefinition`) to React components to make them available in Page Designer for Storefront Next. @@ -10,7 +10,7 @@ Adds Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDef ## Overview -The `storefront_next_page_designer_decorator` tool analyzes React components and generates Page Designer decorators that enable components to be used in Page Designer. It supports two modes: +The `sfnext_add_page_designer_decorator` tool analyzes React components and generates Page Designer decorators that enable components to be used in Page Designer. It supports two modes: 1. **Auto Mode**: Quick setup with sensible defaults-automatically selects suitable props, infers types, and generates decorators immediately. 2. **Interactive Mode**: Multi-step workflow for fine-tuned control over decorator configuration. diff --git a/docs/mcp/tools/storefront-next-generate-component.md b/docs/mcp/tools/sfnext-analyze-component.md similarity index 52% rename from docs/mcp/tools/storefront-next-generate-component.md rename to docs/mcp/tools/sfnext-analyze-component.md index b20d8acd..d0d334fc 100644 --- a/docs/mcp/tools/storefront-next-generate-component.md +++ b/docs/mcp/tools/sfnext-analyze-component.md @@ -1,28 +1,28 @@ --- -description: Analyze Figma design and discovered components to recommend REUSE, EXTEND, or CREATE strategy. +description: Analyze design and discovered components to recommend REUSE, EXTEND, or CREATE strategy. --- -# storefront_next_generate_component +# sfnext_analyze_component -Analyzes Figma design and discovered components to recommend a component generation strategy. Returns a REUSE, EXTEND, or CREATE action with confidence score, key differences, and suggested implementation approach. +Analyzes design and discovered components to recommend a component generation strategy. Returns a REUSE, EXTEND, or CREATE action with confidence score, key differences, and suggested implementation approach. > **Note:** 🚧 This MCP tool is for Storefront Next. Storefront Next is part of a closed pilot and isn't available for general use. ## Overview -The `storefront_next_generate_component` tool compares Figma-generated React code against existing components discovered in the codebase. It analyzes differences across styling, structure, behavior, and props, then recommends the best approach: +The `sfnext_analyze_component` tool compares design React code (e.g., from Figma, design handoff, or other sources) against existing components discovered in the codebase. It analyzes differences across styling, structure, behavior, and props, then recommends the best approach: - **REUSE**: Use existing component with props or minor styling adjustments - **EXTEND**: Extend existing component via props, variant, or composition pattern - **CREATE**: Create a new component (reference existing patterns if applicable) -**Workflow position:** Call this tool **after** retrieving Figma design data and discovering similar components. It is a required step in the Figma-to-component workflow. +**Workflow position:** Call this tool **after** retrieving design data and discovering similar components. It is a required step in the Figma-to-component workflow. This tool is part of the STOREFRONTNEXT toolset. ## Prerequisites -- Figma design data retrieved via Figma MCP tools +- Design React code (from Figma MCP, design handoff, or other sources) - Component discovery performed before calling - Storefront Next project @@ -32,9 +32,9 @@ See [Figma-to-Component Tools Setup](../figma-tools-setup) for complete prerequi | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `figmaMetadata` | string | Yes | JSON string containing Figma design metadata from `mcp__figma__get_metadata`. Can be empty string if metadata was not fetched. | -| `figmaCode` | string | Yes | Generated React code from Figma (from `mcp__figma__get_design_context`). | -| `componentName` | string | Yes | Suggested name for the component extracted from the Figma design. | +| `figmaMetadata` | string | Yes | JSON string containing design metadata (from Figma MCP or empty). Can be empty string if metadata was not fetched. | +| `figmaCode` | string | Yes | React code from design (e.g., from Figma `mcp__figma__get_design_context`, or design handoff). | +| `componentName` | string | Yes | Suggested name for the component extracted from the design. | | `discoveredComponents` | array | Yes | Array of similar components discovered using Glob/Grep/Read. Pass empty array if no similar components found. | | `workspacePath` | string | No | Optional workspace root path. Defaults to the MCP server project directory. | @@ -50,6 +50,23 @@ Each item in `discoveredComponents` must have: | `matchType` | string | One of `'name'`, `'structure'`, `'visual'` | | `code` | string | Full source code of the component | +## Usage Examples + +### With Figma design URL + +``` +I have a Figma design at [URL]. Use the MCP tool to fetch the design code, search the codebase for similar components, then analyze and recommend whether to reuse, extend, or create a component. +``` + +### With design code already fetched + +``` +Use the MCP tool to analyze this design and recommend reuse, extend, or create. Design code: [paste React/JSX from Figma or design handoff]. Search the codebase for similar components first, then call the tool with the discovered components. +``` + +### Agent workflow note + +When the agent searches the codebase and finds no similar components, it should still call the tool with `discoveredComponents: []` to get a CREATE recommendation. The user does not need to specify thisβ€”the agent discovers it during the workflow. ## Output @@ -62,25 +79,10 @@ Returns a formatted recommendation including: - **Suggested Approach**: Implementation guidance - **Next Steps**: Action-specific instructions -## Usage Examples - -### With Discovered Components - -``` -Use the MCP tool to analyze the Figma design and recommend whether to reuse, extend, or create a component. I've discovered PrimaryButton and SecondaryButton as similar components. -``` - -### No Similar Components - -``` -Use the MCP tool to analyze the Figma design. No similar components were found in the codebase. -``` - - ## Related Tools -- [`storefront_next_figma_to_component_workflow`](./storefront-next-figma-to-component-workflow) - Call first to get workflow instructions and Figma parameters -- [`storefront_next_map_tokens_to_theme`](./storefront-next-map-tokens-to-theme) - Map Figma design tokens to theme variables +- [`sfnext_start_figma_workflow`](./sfnext-start-figma-workflow) - Call first to get workflow instructions and Figma parameters +- [`sfnext_match_tokens_to_theme`](./sfnext-match-tokens-to-theme) - Match design tokens to theme variables - Part of the [STOREFRONTNEXT](../toolsets#storefrontnext) toolset - Auto-enabled for Storefront Next projects diff --git a/docs/mcp/tools/storefront-next-site-theming.md b/docs/mcp/tools/sfnext-configure-theme.md similarity index 96% rename from docs/mcp/tools/storefront-next-site-theming.md rename to docs/mcp/tools/sfnext-configure-theme.md index 6c8b6071..be5a124c 100644 --- a/docs/mcp/tools/storefront-next-site-theming.md +++ b/docs/mcp/tools/sfnext-configure-theme.md @@ -2,7 +2,7 @@ description: Get theming guidelines, guided questions, and WCAG color contrast validation for Storefront Next. --- -# storefront_next_site_theming +# sfnext_configure_theme Guides theming changes (colors, fonts, visual styling) for Storefront Next and validates color combinations for WCAG accessibility. @@ -10,7 +10,7 @@ Guides theming changes (colors, fonts, visual styling) for Storefront Next and v ## Overview -The `storefront_next_site_theming` tool provides a structured workflow for applying theming to Storefront Next sites: +The `sfnext_configure_theme` tool provides a structured workflow for applying theming to Storefront Next sites: 1. **Guidelines** - Layout preservation rules, specification compliance, and accessibility requirements 2. **Guided Questions** - Collects user preferences (colors, fonts, mappings) one at a time diff --git a/docs/mcp/tools/storefront-next-development-guidelines.md b/docs/mcp/tools/sfnext-get-guidelines.md similarity index 93% rename from docs/mcp/tools/storefront-next-development-guidelines.md rename to docs/mcp/tools/sfnext-get-guidelines.md index e6c660b2..164d841d 100644 --- a/docs/mcp/tools/storefront-next-development-guidelines.md +++ b/docs/mcp/tools/sfnext-get-guidelines.md @@ -2,7 +2,7 @@ description: Get Storefront Next development guidelines and best practices for React Server Components, data loading, and framework constraints. --- -# storefront_next_development_guidelines +# sfnext_get_guidelines Returns critical architecture rules, coding standards, and best practices for building Storefront Next applications with React Server Components. @@ -10,7 +10,7 @@ Returns critical architecture rules, coding standards, and best practices for bu ## Overview -The `storefront_next_development_guidelines` tool provides essential development guidance for Storefront Next. It: +The `sfnext_get_guidelines` tool provides essential development guidance for Storefront Next. It: 1. Returns comprehensive guidelines by default (quick-reference plus key sections). 2. Supports retrieving specific topic sections on demand. @@ -98,7 +98,7 @@ The returned content includes: - Part of the [STOREFRONTNEXT](../toolsets#storefrontnext) toolset - Auto-enabled for Storefront Next projects -- [`storefront_next_page_designer_decorator`](./storefront-next-page-designer-decorator) - Add Page Designer decorators to components +- [`sfnext_add_page_designer_decorator`](./sfnext-add-page-designer-decorator) - Add Page Designer decorators to components ## See Also diff --git a/docs/mcp/tools/sfnext-match-tokens-to-theme.md b/docs/mcp/tools/sfnext-match-tokens-to-theme.md new file mode 100644 index 00000000..09757bca --- /dev/null +++ b/docs/mcp/tools/sfnext-match-tokens-to-theme.md @@ -0,0 +1,78 @@ +--- +description: Match design tokens to existing theme tokens in app.css with confidence scores and suggestions. +--- + +# sfnext_match_tokens_to_theme + +Matches design tokens (colors, spacing, radius, etc.) to your Storefront Next theme tokens in `app.css`. Helps you identify which design tokens match existing theme variables and suggests new token names for values that don't have matches. + +> **Note:** 🚧 This MCP tool is for Storefront Next. Storefront Next is part of a closed pilot and isn't available for general use. + +## Overview + +The `sfnext_match_tokens_to_theme` tool helps you use theme tokens instead of hardcoded values in your components. After retrieving design tokens (from Figma, design handoff, or other sources), use this tool to match them against your Storefront Next theme. + +The tool reads your `app.css` theme file (or you can specify a custom path) and compares design tokens against your existing theme variables. It returns a report with instructions showing which tokens match, which are similar, and which need new theme variables created. **The tool does not modify files**β€”it provides recommendations and instructions for you to apply. + +This tool is part of the STOREFRONTNEXT toolset. + +## Prerequisites + +- Storefront Next project with `app.css` (or provide `themeFilePath` explicitly) +- Design tokens extracted (from Figma, design system, or other sources) + +See [Figma-to-Component Tools Setup](../figma-tools-setup) for complete prerequisites and configuration. + +## Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `figmaTokens` | array | Yes | Array of design tokens (e.g., from Figma, design system, or style guide). | +| `themeFilePath` | string | No | Optional absolute path to theme CSS file. If not provided, searches for `app.css` in common locations. | + +### Token Schema + +Each token in `figmaTokens` must have: + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Token name (e.g., `"Primary/Blue"`, `"Spacing/Large"`). | +| `value` | string | Yes | Token value (e.g., `"#2563eb"`, `"16px"`, `"0.5rem"`). | +| `type` | string | Yes | One of: `color`, `spacing`, `radius`, `opacity`, `fontSize`, `fontFamily`, `other`. | +| `description` | string | No | Optional description. | + +## Usage Examples + +**Match design tokens to your theme (default app.css):** +``` +Use the MCP tool to match these design tokens to my theme: Primary/Blue #2563eb (color), Spacing/Large 16px (spacing). +``` + +**Match design tokens with custom theme file path:** +``` +Use the MCP tool to match these design tokens to my theme at /path/to/app.css: +- Primary/Blue #2563eb (color) +- Spacing/Large 16px (spacing) +``` + +## Output + +Returns a report (does not modify files) showing: +- Which design tokens match existing theme variables (exact matches) +- Which tokens are similar to existing variables (suggested matches) +- Which tokens need new theme variables created (with suggested names) +- Instructions for using the matched tokens in components and adding new tokens to your theme file + +## Related Tools + +- [`sfnext_start_figma_workflow`](./sfnext-start-figma-workflow) - Workflow orchestrator; call first +- [`sfnext_analyze_component`](./sfnext-analyze-component) - REUSE/EXTEND/CREATE recommendation +- Part of the [STOREFRONTNEXT](../toolsets#storefrontnext) toolset +- Auto-enabled for Storefront Next projects + +## See Also + +- [Figma-to-Component Tools Setup](../figma-tools-setup) - Prerequisites and Figma MCP configuration +- [STOREFRONTNEXT Toolset](../toolsets#storefrontnext) - Overview of Storefront Next development tools +- [Configuration](../configuration) - Configure project directory +- [Storefront Next Guide](../../guide/storefront-next) - Storefront Next development guide diff --git a/docs/mcp/tools/storefront-next-figma-to-component-workflow.md b/docs/mcp/tools/sfnext-start-figma-workflow.md similarity index 80% rename from docs/mcp/tools/storefront-next-figma-to-component-workflow.md rename to docs/mcp/tools/sfnext-start-figma-workflow.md index 51f0d99b..8ff8a7e4 100644 --- a/docs/mcp/tools/storefront-next-figma-to-component-workflow.md +++ b/docs/mcp/tools/sfnext-start-figma-workflow.md @@ -2,7 +2,7 @@ description: Workflow orchestrator for Figma-to-component conversion. Parses your Figma URL and guides you through design-to-component conversion. --- -# storefront_next_figma_to_component_workflow +# sfnext_start_figma_workflow Workflow orchestrator for converting Figma designs to Storefront Next components. Provide a Figma design URL to start the workflow, which extracts design data, analyzes your codebase, and produces component recommendations. @@ -47,15 +47,6 @@ The parser supports these URL formats: The `node-id` parameter accepts hyphen format (`1-2`) or colon format (`1:2`). The parser converts hyphens to colons for Figma MCP compatibility. -## Output - -The workflow returns a guide with extracted Figma parameters (`fileKey`, `nodeId`, and original URL). After the full workflow completes, you receive a component recommendation (REUSE/EXTEND/CREATE) with confidence score and a token mapping summary. - -**Example prompts:** -- βœ… "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 start the Figma-to-component workflow with a custom workflow file at /path/to/custom-workflow.md" - ## Usage Examples ### Basic Workflow Start @@ -78,11 +69,14 @@ Create a homepage from a Figma design, creating or updating components as needed 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. ``` +## Output + +The workflow returns a guide with extracted Figma parameters (`fileKey`, `nodeId`, and original URL). After the full workflow completes, you receive a component recommendation (REUSE/EXTEND/CREATE) with confidence score and a token mapping summary. ## Related Tools -- [`storefront_next_generate_component`](./storefront-next-generate-component) - Analyzes design and discovered components; recommends REUSE/EXTEND/CREATE -- [`storefront_next_map_tokens_to_theme`](./storefront-next-map-tokens-to-theme) - Maps Figma design tokens to theme variables +- [`sfnext_analyze_component`](./sfnext-analyze-component) - Analyzes design and discovered components; recommends REUSE/EXTEND/CREATE +- [`sfnext_match_tokens_to_theme`](./sfnext-match-tokens-to-theme) - Matches design tokens to theme variables - Part of the [STOREFRONTNEXT](../toolsets#storefrontnext) toolset - Auto-enabled for Storefront Next projects diff --git a/docs/mcp/tools/storefront-next-map-tokens-to-theme.md b/docs/mcp/tools/storefront-next-map-tokens-to-theme.md deleted file mode 100644 index 1f83191e..00000000 --- a/docs/mcp/tools/storefront-next-map-tokens-to-theme.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -description: Map Figma design tokens to existing theme tokens in app.css with confidence scores and suggestions. ---- - -# storefront_next_map_tokens_to_theme - -Maps Figma design tokens (colors, spacing, radius, etc.) to your Storefront Next theme tokens in `app.css`. Helps you identify which Figma tokens match existing theme variables and suggests new token names for values that don't have matches. - -> **Note:** 🚧 This MCP tool is for Storefront Next. Storefront Next is part of a closed pilot and isn't available for general use. - -## Overview - -The `storefront_next_map_tokens_to_theme` tool helps you use theme tokens instead of hardcoded values in your components. After retrieving design tokens from Figma, use this tool to map them to your Storefront Next theme. - -The tool reads your `app.css` theme file (or you can specify a custom path) and compares Figma tokens against your existing theme variables. It returns a report with instructions showing which tokens match, which are similar, and which need new theme variables created. **The tool does not modify files**β€”it provides recommendations and instructions for you to apply. - -This tool is part of the STOREFRONTNEXT toolset. - -## Prerequisites - -- Storefront Next project with `app.css` (or provide `themeFilePath` explicitly) -- Figma tokens extracted from design (colors, spacing, radius, etc.) - -See [Figma-to-Component Tools Setup](../figma-tools-setup) for complete prerequisites and configuration. - -## Parameters - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `figmaTokens` | array | Yes | Array of design tokens extracted from Figma. | -| `themeFilePath` | string | No | Optional absolute path to theme CSS file. If not provided, searches for `app.css` in common locations. | - -### Figma Token Schema - -Each token in `figmaTokens` must have: - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `name` | string | Yes | Token name from Figma (e.g., `"Primary/Blue"`, `"Spacing/Large"`). | -| `value` | string | Yes | Token value (e.g., `"#2563eb"`, `"16px"`, `"0.5rem"`). | -| `type` | string | Yes | One of: `color`, `spacing`, `radius`, `opacity`, `fontSize`, `fontFamily`, `other`. | -| `description` | string | No | Optional description from Figma. | - - -## Output - -Returns a report (does not modify files) showing: -- Which Figma tokens match existing theme variables (exact matches) -- Which tokens are similar to existing variables (suggested matches) -- Which tokens need new theme variables created (with suggested names) -- Instructions for using the matched tokens in components and adding new tokens to your theme file - -## Usage Examples - -**Map Figma tokens to your theme:** -``` -Use the MCP tool to map these Figma tokens to my theme: Primary/Blue #2563eb (color), Spacing/Large 16px (spacing). -``` - -**With custom theme file path:** -``` -Use the MCP tool to map Figma design tokens to my theme file at /path/to/app.css. -``` - - -## Related Tools - -- [`storefront_next_figma_to_component_workflow`](./storefront-next-figma-to-component-workflow) - Workflow orchestrator; call first -- [`storefront_next_generate_component`](./storefront-next-generate-component) - REUSE/EXTEND/CREATE recommendation -- Part of the [STOREFRONTNEXT](../toolsets#storefrontnext) toolset -- Auto-enabled for Storefront Next projects - -## See Also - -- [Figma-to-Component Tools Setup](../figma-tools-setup) - Prerequisites and Figma MCP configuration -- [STOREFRONTNEXT Toolset](../toolsets#storefrontnext) - Overview of Storefront Next development tools -- [Configuration](../configuration) - Configure project directory -- [Storefront Next Guide](../../guide/storefront-next) - Storefront Next development guide diff --git a/docs/mcp/toolsets.md b/docs/mcp/toolsets.md index b6df7b17..72459cd9 100644 --- a/docs/mcp/toolsets.md +++ b/docs/mcp/toolsets.md @@ -61,10 +61,10 @@ PWA Kit v3 development tools for building headless storefronts. | Tool | Description | Documentation | |------|-------------|---------------| -| [`pwakit_development_guidelines`](./tools/pwakit-development-guidelines) | Get PWA Kit v3 development guidelines and best practices | [View details](./tools/pwakit-development-guidelines) | +| [`pwakit_get_guidelines`](./tools/pwakit-get-guidelines) | Get PWA Kit v3 development guidelines and best practices | [View details](./tools/pwakit-get-guidelines) | | [`scapi_schemas_list`](./tools/scapi-schemas-list) | List or fetch SCAPI schemas (standard and custom). Use apiFamily: "custom" for custom APIs. | [View details](./tools/scapi-schemas-list) | -| [`scapi_custom_api_scaffold`](./tools/scapi-custom-api-scaffold) | Generate a new custom SCAPI endpoint (schema, api.json, script.js) in an existing cartridge. | [View details](./tools/scapi-custom-api-scaffold) | -| [`scapi_custom_apis_status`](./tools/scapi-custom-apis-status) | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. | [View details](./tools/scapi-custom-apis-status) | +| [`scapi_custom_api_generate_scaffold`](./tools/scapi-custom-api-generate-scaffold) | Generate a new custom SCAPI endpoint (schema, api.json, script.js) in an existing cartridge. | [View details](./tools/scapi-custom-api-generate-scaffold) | +| [`scapi_custom_apis_get_status`](./tools/scapi-custom-apis-get-status) | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. | [View details](./tools/scapi-custom-apis-get-status) | | [`mrt_bundle_push`](./tools/mrt-bundle-push) | Build, push bundle (optionally deploy) | [View details](./tools/mrt-bundle-push) | ## SCAPI @@ -80,8 +80,8 @@ Salesforce Commerce API discovery and exploration. | Tool | Description | Documentation | |------|-------------|---------------| | [`scapi_schemas_list`](./tools/scapi-schemas-list) | List or fetch SCAPI schemas (standard and custom). Use apiFamily: "custom" for custom APIs. | [View details](./tools/scapi-schemas-list) | -| [`scapi_custom_api_scaffold`](./tools/scapi-custom-api-scaffold) | Generate a new custom SCAPI endpoint (schema, api.json, script.js) in an existing cartridge. | [View details](./tools/scapi-custom-api-scaffold) | -| [`scapi_custom_apis_status`](./tools/scapi-custom-apis-status) | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. | [View details](./tools/scapi-custom-apis-status) | +| [`scapi_custom_api_generate_scaffold`](./tools/scapi-custom-api-generate-scaffold) | Generate a new custom SCAPI endpoint (schema, api.json, script.js) in an existing cartridge. | [View details](./tools/scapi-custom-api-generate-scaffold) | +| [`scapi_custom_apis_get_status`](./tools/scapi-custom-apis-get-status) | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. | [View details](./tools/scapi-custom-apis-get-status) | ## STOREFRONTNEXT @@ -95,22 +95,22 @@ Storefront Next development tools for building modern storefronts. | Tool | Description | Documentation | |------|-------------|---------------| -| [`storefront_next_development_guidelines`](./tools/storefront-next-development-guidelines) | Get Storefront Next development guidelines and best practices | [View details](./tools/storefront-next-development-guidelines) | -| [`storefront_next_figma_to_component_workflow`](./tools/storefront-next-figma-to-component-workflow) | Workflow orchestrator for Figma-to-component conversion. Parses Figma URL, returns step-by-step instructions for subsequent tool calls | [View details](./tools/storefront-next-figma-to-component-workflow) | -| [`storefront_next_generate_component`](./tools/storefront-next-generate-component) | Analyze Figma design and discovered components to recommend REUSE, EXTEND, or CREATE strategy | [View details](./tools/storefront-next-generate-component) | -| [`storefront_next_map_tokens_to_theme`](./tools/storefront-next-map-tokens-to-theme) | Map Figma design tokens to existing theme tokens in app.css with confidence scores and suggestions | [View details](./tools/storefront-next-map-tokens-to-theme) | -| [`storefront_next_page_designer_decorator`](./tools/storefront-next-page-designer-decorator) | Add Page Designer decorators to Storefront Next components | [View details](./tools/storefront-next-page-designer-decorator) | -| [`storefront_next_site_theming`](./tools/storefront-next-site-theming) | Get theming guidelines, questions, and WCAG color validation for Storefront Next | [View details](./tools/storefront-next-site-theming) | +| [`sfnext_get_guidelines`](./tools/sfnext-get-guidelines) | Get Storefront Next development guidelines and best practices | [View details](./tools/sfnext-get-guidelines) | +| [`sfnext_start_figma_workflow`](./tools/sfnext-start-figma-workflow) | Workflow orchestrator for Figma-to-component conversion. Parses Figma URL, returns step-by-step instructions for subsequent tool calls | [View details](./tools/sfnext-start-figma-workflow) | +| [`sfnext_analyze_component`](./tools/sfnext-analyze-component) | Analyze design and discovered components to recommend REUSE, EXTEND, or CREATE strategy | [View details](./tools/sfnext-analyze-component) | +| [`sfnext_match_tokens_to_theme`](./tools/sfnext-match-tokens-to-theme) | Map design tokens to existing theme tokens in app.css with confidence scores and suggestions | [View details](./tools/sfnext-match-tokens-to-theme) | +| [`sfnext_add_page_designer_decorator`](./tools/sfnext-add-page-designer-decorator) | Add Page Designer decorators to Storefront Next components | [View details](./tools/sfnext-add-page-designer-decorator) | +| [`sfnext_configure_theme`](./tools/sfnext-configure-theme) | Get theming guidelines, questions, and WCAG color validation for Storefront Next | [View details](./tools/sfnext-configure-theme) | | [`scapi_schemas_list`](./tools/scapi-schemas-list) | List or fetch SCAPI schemas (standard and custom). Use apiFamily: "custom" for custom APIs. | [View details](./tools/scapi-schemas-list) | -| [`scapi_custom_api_scaffold`](./tools/scapi-custom-api-scaffold) | Generate a new custom SCAPI endpoint (schema, api.json, script.js) in an existing cartridge. | [View details](./tools/scapi-custom-api-scaffold) | -| [`scapi_custom_apis_status`](./tools/scapi-custom-apis-status) | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. | [View details](./tools/scapi-custom-apis-status) | +| [`scapi_custom_api_generate_scaffold`](./tools/scapi-custom-api-generate-scaffold) | Generate a new custom SCAPI endpoint (schema, api.json, script.js) in an existing cartridge. | [View details](./tools/scapi-custom-api-generate-scaffold) | +| [`scapi_custom_apis_get_status`](./tools/scapi-custom-apis-get-status) | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. | [View details](./tools/scapi-custom-apis-get-status) | | [`mrt_bundle_push`](./tools/mrt-bundle-push) | Build, push bundle (optionally deploy) | [View details](./tools/mrt-bundle-push) | -**Figma-to-component tools** (`storefront_next_figma_to_component_workflow`, `storefront_next_generate_component`, `storefront_next_map_tokens_to_theme`) require additional setup: an external Figma MCP server and a valid Figma URL with `node-id`. See [Figma-to-Component Tools Setup](./figma-tools-setup) for prerequisites and configuration. +**Figma-to-component tools** (`sfnext_start_figma_workflow`, `sfnext_analyze_component`, `sfnext_match_tokens_to_theme`) require additional setup: an external Figma MCP server and a valid Figma URL with `node-id`. See [Figma-to-Component Tools Setup](./figma-tools-setup) for prerequisites and configuration. ## Tool Deduplication -Some tools appear in multiple toolsets (for example, `mrt_bundle_push`, `scapi_schemas_list`, `scapi_custom_api_scaffold`, `scapi_custom_apis_status`). When using multiple toolsets, tools are automatically deduplicated, so you'll only see each tool once. +Some tools appear in multiple toolsets (for example, `mrt_bundle_push`, `scapi_schemas_list`, `scapi_custom_api_generate_scaffold`, `scapi_custom_apis_get_status`). When using multiple toolsets, tools are automatically deduplicated, so you'll only see each tool once. ## Next Steps diff --git a/packages/b2c-dx-mcp/CONTRIBUTING.md b/packages/b2c-dx-mcp/CONTRIBUTING.md index e7b75064..d35c13df 100644 --- a/packages/b2c-dx-mcp/CONTRIBUTING.md +++ b/packages/b2c-dx-mcp/CONTRIBUTING.md @@ -65,7 +65,7 @@ npx mcp-inspector --cli node bin/dev.js --toolsets all --allow-non-ga-tools --me # Call a specific tool npx mcp-inspector --cli node bin/dev.js --toolsets all --allow-non-ga-tools \ --method tools/call \ - --tool-name storefront_next_page_designer_decorator + --tool-name sfnext_add_page_designer_decorator ``` ### JSON-RPC via stdin diff --git a/packages/b2c-dx-mcp/README.md b/packages/b2c-dx-mcp/README.md index d30a36ea..c57479d2 100644 --- a/packages/b2c-dx-mcp/README.md +++ b/packages/b2c-dx-mcp/README.md @@ -82,9 +82,9 @@ See the [Configuration Guide](https://salesforcecommercecloud.github.io/b2c-deve |---------|-------|------| | CARTRIDGES | `cartridge_deploy` | [toolsets#cartridges](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#cartridges) | | MRT | `mrt_bundle_push` | [toolsets#mrt](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#mrt) | -| SCAPI | `scapi_schemas_list`, `scapi_custom_apis_status`, `scapi_customapi_scaffold` | [toolsets#scapi](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#scapi) | -| STOREFRONTNEXT | `storefront_next_development_guidelines`, `storefront_next_page_designer_decorator`, `storefront_next_site_theming`, `storefront_next_figma_to_component_workflow`, `storefront_next_generate_component`, `storefront_next_map_tokens_to_theme` | [toolsets#storefrontnext](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#storefrontnext) | -| PWAV3 | `pwakit_development_guidelines` + SCAPI tools | [toolsets#pwav3](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#pwav3) | +| SCAPI | `scapi_schemas_list`, `scapi_custom_apis_get_status`, `scapi_custom_api_generate_scaffold` | [toolsets#scapi](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#scapi) | +| STOREFRONTNEXT | `sfnext_get_guidelines`, `sfnext_add_page_designer_decorator`, `sfnext_configure_theme`, `sfnext_start_figma_workflow`, `sfnext_analyze_component`, `sfnext_match_tokens_to_theme` | [toolsets#storefrontnext](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#storefrontnext) | +| PWAV3 | `pwakit_get_guidelines` + SCAPI tools | [toolsets#pwav3](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#pwav3) | ### cartridge_deploy @@ -107,62 +107,62 @@ List or fetch SCAPI schemas (standard and custom). [Details](https://salesforcec - "Use the MCP tool to list all SCAPI schemas." - "Use the MCP tool to get the OpenAPI schema for shopper-baskets v1." -### scapi_custom_apis_status +### scapi_custom_apis_get_status -Get custom API endpoint registration status. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/scapi-custom-apis-status) +Get custom API endpoint registration status. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/scapi-custom-apis-get-status) - "Use the MCP tool to list custom API endpoints on my instance." - "Use the MCP tool to show which custom APIs are active vs not registered." -### scapi_customapi_scaffold +### scapi_custom_api_generate_scaffold -Generate new custom SCAPI endpoint in a cartridge. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/scapi-custom-api-scaffold) +Generate new custom SCAPI endpoint in a cartridge. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/scapi-custom-api-generate-scaffold) - "Use the MCP tool to scaffold a new custom API named my-products." - "Use the MCP tool to create a custom admin API called customer-trips." -### storefront_next_development_guidelines +### sfnext_get_guidelines -Get Storefront Next guidelines and best practices. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/storefront-next-development-guidelines) +Get Storefront Next guidelines and best practices. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-get-guidelines) - "Use the MCP tool to show me critical Storefront Next rules." - "Use the MCP tool to get data-fetching and component patterns." -### storefront_next_page_designer_decorator +### sfnext_add_page_designer_decorator -Add Page Designer decorators to components. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/storefront-next-page-designer-decorator) +Add Page Designer decorators to components. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-add-page-designer-decorator) - "Use the MCP tool to add Page Designer decorators to my component." -### storefront_next_site_theming +### sfnext_configure_theme -Get theming guidelines, questions, and WCAG color validation for Storefront Next. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/storefront-next-site-theming) +Get theming guidelines, questions, and WCAG color validation for Storefront Next. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-configure-theme) - "Use the MCP tool to help me apply my brand colors to my Storefront Next site." - "Use the MCP tool to validate my color combinations for accessibility." -### storefront_next_figma_to_component_workflow +### sfnext_start_figma_workflow -Workflow orchestrator for Figma-to-component conversion. Parses Figma URL, returns step-by-step instructions for subsequent tool calls. Requires external Figma MCP server. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/storefront-next-figma-to-component-workflow) β€” [Figma Setup](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/figma-tools-setup) +Workflow orchestrator for Figma-to-component conversion. Parses Figma URL, returns step-by-step instructions for subsequent tool calls. Requires external Figma MCP server. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-start-figma-workflow) β€” [Figma Setup](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/figma-tools-setup) - "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]" -### storefront_next_generate_component +### sfnext_analyze_component -Analyze Figma design and discovered components to recommend REUSE, EXTEND, or CREATE strategy. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/storefront-next-generate-component) +Analyze design and discovered components to recommend REUSE, EXTEND, or CREATE strategy. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-analyze-component) - "Use the MCP tool to analyze the Figma design and recommend whether to reuse, extend, or create a component." -### storefront_next_map_tokens_to_theme +### sfnext_match_tokens_to_theme -Map Figma design tokens to existing theme tokens in app.css with confidence scores and suggestions. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/storefront-next-map-tokens-to-theme) +Map design tokens to existing theme tokens in app.css with confidence scores and suggestions. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-match-tokens-to-theme) - "Use the MCP tool to map these Figma design tokens to my theme." -### pwakit_development_guidelines +### pwakit_get_guidelines -Get PWA Kit v3 guidelines. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/pwakit-development-guidelines) +Get PWA Kit v3 guidelines. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/pwakit-get-guidelines) - "Use the MCP tool to get PWA Kit development guidelines." diff --git a/packages/b2c-dx-mcp/content/sfnext/page-designer.md b/packages/b2c-dx-mcp/content/sfnext/page-designer.md index 74021bf4..54d267c8 100644 --- a/packages/b2c-dx-mcp/content/sfnext/page-designer.md +++ b/packages/b2c-dx-mcp/content/sfnext/page-designer.md @@ -35,7 +35,7 @@ To add a new content page: define a page type and ID in Commerce Cloud, then in - **Add a metadata class** with `@Component('typeId', { name, description })` and `@AttributeDefinition()` (and optionally `@AttributeDefinition({ type: 'image' })`, `type: 'url'`, etc.) for each prop you want editable in Page Designer. Use `@RegionDefinition([...])` if the component has nested regions (e.g. a grid with slots). - **Implement the React component** so it accepts those props (and strips Page Designer–only props like `component`, `page`, `componentData`, `designMetadata` before spreading to the DOM). If the component needs server data (e.g. products for a carousel), export a `loader({ componentData, context })` and optionally a `fallback` component; the registry calls the loader during `collectComponentDataPromises` and passes resolved data as the `data` prop. -- **Use the MCP tool `storefront_next_page_designer_decorator`** to generate decorators instead of writing them by hand. Example components: `components/hero/index.tsx`, `components/content-card/index.tsx`, `components/product-carousel/index.tsx`. +- **Use the MCP tool `sfnext_add_page_designer_decorator`** to generate decorators instead of writing them by hand. Example components: `components/hero/index.tsx`, `components/content-card/index.tsx`, `components/product-carousel/index.tsx`. ### After changes @@ -50,29 +50,21 @@ To add a new content page: define a page type and ID in Commerce Cloud, then in Use the **B2C DX MCP server** for Page Designer work instead of hand-writing decorators and metadata. Configure the B2C DX MCP server in your IDE (e.g. in MCP settings) so these tools are available. -### 1. `storefront_next_page_designer_decorator` (STOREFRONTNEXT toolset) +### 1. `sfnext_add_page_designer_decorator` (STOREFRONTNEXT toolset) Adds Page Designer decorators to an existing React component so it can be used in Business Manager. The tool analyzes the component, picks suitable props, infers types (e.g. `*Url`/`*Link` β†’ url, `*Image` β†’ image, `is*`/`show*` β†’ boolean), and generates `@Component('typeId', { name, description })`, `@AttributeDefinition()` on a metadata class, and optionally `@RegionDefinition([...])` for nested regions. It skips complex or UI-only props (e.g. className, style, callbacks). - **Auto mode** (fast): Ask in your IDE: *"Add Page Designer support to [ComponentName] with autoMode"*. The tool runs in one turn with no prompts. - **Interactive mode** (control): Ask *"Add Page Designer support to [ComponentName]"* and answer questions about typeId, which props to expose, types, and optional nested regions. -### 2. `storefront_next_generate_page_designer_metadata` (STOREFRONTNEXT toolset) - -Generates Page Designer metadata JSON from decorated components, page types, and aspects. Writes files under the cartridge experience folder (e.g. `cartridges/app_storefrontnext_base/cartridge/experience/`). Use after adding or changing decorators so Business Manager has up-to-date component and page-type definitions. - -- **Full scan**: Run with no file list to process the whole project. -- **Incremental**: Pass specific file paths to regenerate only those components. -- **Dry run**: Use `dryRun: true` to see what would be generated without writing files. - -### 3. `cartridge_deploy` (CARTRIDGES toolset) +### 2. `cartridge_deploy` (CARTRIDGES toolset) Packages the cartridge, uploads it to Commerce Cloud via WebDAV, and unpacks it on the server. Requires Commerce Cloud credentials (e.g. `dw.json` or explicit config). Use after generating metadata so the new/updated metadata is available in Business Manager. ### Typical workflow -1. **`storefront_next_page_designer_decorator`** β€” Add decorators to the component (use autoMode for a quick first pass). -2. **`storefront_next_generate_page_designer_metadata`** β€” Generate metadata JSON so the component and regions appear in Page Designer. +1. **`sfnext_add_page_designer_decorator`** β€” Add decorators to the component (use autoMode for a quick first pass). +2. **Rebuild** β€” The static registry is auto-generated at build time by the staticRegistry Vite plugin. 3. **`cartridge_deploy`** β€” Deploy to Commerce Cloud so merchants can use the component in Business Manager. ## Best Practices @@ -81,6 +73,6 @@ Packages the cartridge, uploads it to Commerce Cloud via WebDAV, and unpacks it 2. **Use registry for components**: Register all Page Designer components with proper `typeId` 3. **Handle design mode**: Adapt UI when `pageDesignerMode` is `'EDIT'` or `'PREVIEW'` 4. **Rebuild after registry changes**: Static registry is generated at build time -5. **Use MCP tools**: Leverage `storefront_next_page_designer_decorator` and `storefront_next_generate_page_designer_metadata` for faster development +5. **Use MCP tools**: Leverage `sfnext_add_page_designer_decorator` for faster development **Reference:** See README.md for complete Page Designer documentation and MCP tool setup. diff --git a/packages/b2c-dx-mcp/content/sfnext/quick-reference.md b/packages/b2c-dx-mcp/content/sfnext/quick-reference.md index d5feb071..2f09def0 100644 --- a/packages/b2c-dx-mcp/content/sfnext/quick-reference.md +++ b/packages/b2c-dx-mcp/content/sfnext/quick-reference.md @@ -196,7 +196,7 @@ import { Card } from '@/components/ui/card'; ## πŸ” Get Detailed Guidelines -Use the `storefront_next_development_guidelines` MCP tool with specific sections: +Use the `sfnext_get_guidelines` MCP tool with specific sections: ```json { diff --git a/packages/b2c-dx-mcp/src/tools/pwav3/pwa-kit-development-guidelines.ts b/packages/b2c-dx-mcp/src/tools/pwav3/pwa-kit-development-guidelines.ts index 67fe7fe7..02bc7b8a 100644 --- a/packages/b2c-dx-mcp/src/tools/pwav3/pwa-kit-development-guidelines.ts +++ b/packages/b2c-dx-mcp/src/tools/pwav3/pwa-kit-development-guidelines.ts @@ -118,7 +118,7 @@ const DEFAULT_SECTIONS: SectionKey[] = ['quick-reference', 'components', 'data-f export function createDeveloperGuidelinesTool(loadServices: () => Promise | Services): McpTool { return createToolAdapter( { - name: 'pwakit_development_guidelines', + name: 'pwakit_get_guidelines', description: 'ESSENTIAL FIRST STEP for PWA Kit v3 development. Returns critical architecture rules, coding standards, and best practices. ' + 'Use this tool FIRST before writing any PWA Kit code to understand non-negotiable patterns for React components, ' + diff --git a/packages/b2c-dx-mcp/src/tools/scapi/index.ts b/packages/b2c-dx-mcp/src/tools/scapi/index.ts index 7e919414..30580d87 100644 --- a/packages/b2c-dx-mcp/src/tools/scapi/index.ts +++ b/packages/b2c-dx-mcp/src/tools/scapi/index.ts @@ -16,8 +16,8 @@ import type {McpTool} from '../../utils/index.js'; import type {Services} from '../../services.js'; import {createScapiSchemasListTool} from './scapi-schemas-list.js'; -import {createScapiCustomApisStatusTool} from './scapi-custom-apis-status.js'; -import {createScaffoldCustomApiTool} from './scapi-custom-api-scaffold.js'; +import {createScapiCustomApisStatusTool} from './scapi-custom-apis-get-status.js'; +import {createScaffoldCustomApiTool} from './scapi-custom-api-generate-scaffold.js'; /** * Creates all tools for the SCAPI toolset. diff --git a/packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-api-scaffold.ts b/packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-api-generate-scaffold.ts similarity index 96% rename from packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-api-scaffold.ts rename to packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-api-generate-scaffold.ts index 50d6f80f..0a9f7e55 100644 --- a/packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-api-scaffold.ts +++ b/packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-api-generate-scaffold.ts @@ -5,12 +5,12 @@ */ /** - * SCAPI Custom API Scaffold tool. + * SCAPI Custom API Generate Scaffold tool. * * Generates a new custom SCAPI endpoint using the SDK's custom-api scaffold * (schema.yaml, api.json, script.js). * - * @module tools/scapi/scapi-custom-api-scaffold + * @module tools/scapi/scapi-custom-api-generate-scaffold */ import {z} from 'zod'; @@ -35,7 +35,7 @@ export interface ScaffoldCustomApiExecuteOverrides { } /** - * Input schema for scapi_custom_api_scaffold tool. + * Input schema for scapi_custom_api_generate_scaffold tool. * Parameters match the custom-api scaffold: apiName, apiType, cartridgeName, etc. */ interface ScaffoldCustomApiInput { @@ -54,7 +54,7 @@ interface ScaffoldCustomApiInput { } /** - * Output schema for scapi_custom_api_scaffold tool. + * Output schema for scapi_custom_api_generate_scaffold tool. */ interface ScaffoldCustomApiOutput { scaffold: string; @@ -190,7 +190,7 @@ export async function executeScaffoldCustomApi( } /** - * Creates the scapi_custom_api_scaffold tool. + * Creates the scapi_custom_api_generate_scaffold tool. * * Uses @salesforce/b2c-tooling-sdk scaffold: registry, resolveScaffoldParameters, * resolveOutputDirectory, generateFromScaffold. cartridgeName must be a cartridge @@ -205,7 +205,7 @@ export function createScaffoldCustomApiTool( ): McpTool { return createToolAdapter( { - name: 'scapi_custom_api_scaffold', + name: 'scapi_custom_api_generate_scaffold', description: `Generate a new custom SCAPI endpoint (OAS 3.0 schema, api.json, script.js) in an existing cartridge. \ Required: apiName (kebab-case). Optional: cartridgeName (defaults to first cartridge found in project), apiType (shopper|admin) default to shopper, \ apiDescription, projectRoot, outputDir.`, diff --git a/packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-apis-status.ts b/packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-apis-get-status.ts similarity index 96% rename from packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-apis-status.ts rename to packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-apis-get-status.ts index 44e8f92f..9bbabeee 100644 --- a/packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-apis-status.ts +++ b/packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-apis-get-status.ts @@ -10,7 +10,7 @@ * Mirrors CLI: b2c scapi custom status. All CLI flags are supported; let the agent decide what to use. * Returns raw endpoints from the API (no roll-up). Remote only. * - * @module tools/scapi/scapi-custom-apis-status + * @module tools/scapi/scapi-custom-apis-get-status */ import {z} from 'zod'; @@ -94,7 +94,7 @@ function buildResponse( } /** - * Input schema for scapi_custom_apis_status tool. + * Input schema for scapi_custom_apis_get_status tool. * Mirrors b2c scapi custom status (--status, --group-by, --columns). * Use columns parameter to request all fields or specific fields. */ @@ -108,7 +108,7 @@ interface CustomListInput { } /** - * Output schema for scapi_custom_apis_status tool. + * Output schema for scapi_custom_apis_get_status tool. */ interface CustomListOutput { /** Raw endpoints (one per site). When groupBy is set, use "groups" instead. */ @@ -123,7 +123,7 @@ interface CustomListOutput { } /** - * Creates the scapi_custom_apis_status tool. + * Creates the scapi_custom_apis_get_status tool. * * Mirrors CLI: b2c scapi custom status. All flags supported; agent chooses what to use. * See: https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/custom-apis.html#b2c-scapi-custom-status @@ -131,7 +131,7 @@ interface CustomListOutput { export function createScapiCustomApisStatusTool(loadServices: () => Promise | Services): McpTool { return createToolAdapter( { - name: 'scapi_custom_apis_status', + name: 'scapi_custom_apis_get_status', description: `List Custom SCAPI endpoint registration status (active/not_registered). Returns one row per endpoint per site. For schemas, use scapi_schemas_list with apiFamily: "custom". Use cases: Check endpoint status, verify deployment, get per-site details. Use status: "active" to filter, groupBy: "site" to group, columns: "field1,field2" for specific fields, or omit columns for defaults. diff --git a/packages/b2c-dx-mcp/src/tools/scapi/scapi-schemas-list.ts b/packages/b2c-dx-mcp/src/tools/scapi/scapi-schemas-list.ts index 4c060969..3dfddad9 100644 --- a/packages/b2c-dx-mcp/src/tools/scapi/scapi-schemas-list.ts +++ b/packages/b2c-dx-mcp/src/tools/scapi/scapi-schemas-list.ts @@ -296,7 +296,7 @@ export function createScapiSchemasListTool(loadServices: () => Promise return createToolAdapter( { name: 'scapi_schemas_list', - description: `List or fetch SCAPI schema metadata and OpenAPI specs for standard SCAPI (Shop/Admin/Shopper) and custom APIs (apiFamily: "custom"). For endpoint registration status, use scapi_custom_apis_status. + description: `List or fetch SCAPI schema metadata and OpenAPI specs for standard SCAPI (Shop/Admin/Shopper) and custom APIs (apiFamily: "custom"). For endpoint registration status, use scapi_custom_apis_get_status. **Modes:** - **List (discovery):** Omit includeSchemas or any identifier. Returns metadata: schemas[], total, availableApiFamilies/Names/Versions. diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/README.md b/packages/b2c-dx-mcp/src/tools/storefrontnext/README.md index 6726789d..d4a290e2 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/README.md +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/README.md @@ -4,7 +4,7 @@ MCP tools for Storefront Next development with React Server Components. ## Tools -### `storefront_next_development_guidelines` +### `sfnext_get_guidelines` **ESSENTIAL FIRST STEP** for Storefront Next development. Returns critical architecture rules, coding standards, and best practices. Use this tool FIRST before writing any Storefront Next code to understand non-negotiable patterns for React Server Components, data loading, and framework constraints. @@ -52,12 +52,12 @@ MCP tools for Storefront Next development with React Server Components. ```json // Default - returns comprehensive guidelines (quick-reference + data-fetching + components + testing) { - "name": "storefront_next_development_guidelines" + "name": "sfnext_get_guidelines" } // Single section { - "name": "storefront_next_development_guidelines", + "name": "sfnext_get_guidelines", "arguments": { "sections": ["data-fetching"] } @@ -65,7 +65,7 @@ MCP tools for Storefront Next development with React Server Components. // Multiple related sections { - "name": "storefront_next_development_guidelines", + "name": "sfnext_get_guidelines", "arguments": { "sections": ["data-fetching", "components", "performance"] } @@ -73,14 +73,14 @@ MCP tools for Storefront Next development with React Server Components. // All sections { - "name": "storefront_next_development_guidelines", + "name": "sfnext_get_guidelines", "arguments": { "sections": ["quick-reference", "data-fetching", "state-management", "auth", "config", "i18n", "components", "styling", "page-designer", "performance", "testing", "extensions", "pitfalls"] } } ``` -### `storefront_next_page_designer_decorator` +### `sfnext_add_page_designer_decorator` Add Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDefinition`) to existing React components for Storefront Next. @@ -108,7 +108,7 @@ Add Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDefi ```json // Auto mode (quick setup) { - "name": "storefront_next_page_designer_decorator", + "name": "sfnext_add_page_designer_decorator", "arguments": { "component": "ProductCard", "autoMode": true @@ -117,7 +117,7 @@ Add Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDefi // Interactive mode (step-by-step) { - "name": "storefront_next_page_designer_decorator", + "name": "sfnext_add_page_designer_decorator", "arguments": { "component": "Hero", "conversationContext": { @@ -127,7 +127,7 @@ Add Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDefi } ``` -### `storefront_next_site_theming` +### `sfnext_configure_theme` **MANDATORY** before implementing any theming changes. Provides theming guidelines, questions, and automatic color contrast validation. Call this tool FIRST when the user requests theming (even if colors/fonts are provided). Never implement without calling it first. @@ -154,7 +154,7 @@ Add Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDefi ```json // First call - get guidelines and questions { - "name": "storefront_next_site_theming", + "name": "sfnext_configure_theme", "arguments": { "conversationContext": { "collectedAnswers": {"colors": [], "fonts": []} @@ -164,7 +164,7 @@ Add Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDefi // Validation call - after constructing colorMapping (colorMapping alone triggers validation) { - "name": "storefront_next_site_theming", + "name": "sfnext_configure_theme", "arguments": { "conversationContext": { "collectedAnswers": { @@ -184,7 +184,7 @@ Add Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDefi ### Architecture -#### `storefront_next_development_guidelines` +#### `sfnext_get_guidelines` The tool loads content from markdown files in the `content/` directory: @@ -217,7 +217,7 @@ Each section markdown file includes: βœ… **Always Current**: Content loaded from markdown files (easy to update) βœ… **Comprehensive Default**: Returns key sections by default for immediate value -#### `storefront_next_page_designer_decorator` +#### `sfnext_add_page_designer_decorator` The tool uses a rule-based architecture with TypeScript template literals for generating Page Designer decorators: @@ -255,7 +255,7 @@ Component discovery uses the project directory resolved from `--project-director **See also**: [Detailed documentation](./page-designer-decorator/README.md) for complete usage guide, architecture details, and examples. -#### `storefront_next_site_theming` +#### `sfnext_configure_theme` The tool loads theming guidance from markdown files in `content/site-theming/` and runs automatic WCAG contrast validation when `colorMapping` is provided: diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/figma-to-component/index.ts b/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/figma-to-component/index.ts index 90e885b2..fcf83eb0 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/figma-to-component/index.ts +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/figma-to-component/index.ts @@ -252,7 +252,7 @@ function formatNextStepsReminder(): string { This tool has provided workflow instructions only. You MUST now execute ALL steps below. -**EXPECTED FINAL OUTPUT:** A recommendation with confidence score from generate_component tool AND a token mapping summary from map_tokens_to_theme tool. +**EXPECTED FINAL OUTPUT:** A recommendation with confidence score from sfnext_analyze_component tool AND a token mapping summary from sfnext_match_tokens_to_theme tool. ### Step 1: Fetch Figma Design Data (Parallel Calls) Call these Figma MCP tools with the parameters above: @@ -268,7 +268,7 @@ Use your tools to find existing components: - Score each match (0-100) based on similarity ### Step 3: Analyze Component Strategy (CRITICAL - DO NOT SKIP) -You MUST call \`generate_component\` tool with: +You MUST call \`sfnext_analyze_component\` tool with: - figmaMetadata (from step 1, or empty string if not fetched) - figmaCode (from step 1) - componentName (extracted from Figma) @@ -277,14 +277,14 @@ You MUST call \`generate_component\` tool with: This tool returns the recommendation with confidence score that MUST be shown to the user. ### Step 4: Map Design Tokens (CRITICAL - DO NOT SKIP) -You MUST call \`map_tokens_to_theme\` tool with tokens extracted from Figma design. +You MUST call \`sfnext_match_tokens_to_theme\` tool with tokens extracted from Figma design. This tool returns the token mapping summary that MUST be shown to the user. ### Step 5: Implement After showing the recommendation and token mapping to the user, wait for approval then implement the code changes. Use the downloaded asset paths from Step 1 for any img src or imageUrl propsβ€”do not use placeholder paths. -**DO NOT STOP until you have called generate_component AND map_tokens_to_theme and shown their outputs to the user.** +**DO NOT STOP until you have called sfnext_analyze_component AND sfnext_match_tokens_to_theme and shown their outputs to the user.** `; } @@ -329,7 +329,7 @@ export function generateWorkflowResponse(figmaUrl: string, workflowFilePath?: st } /** - * Creates the storefront_next_figma_to_component_workflow MCP tool. + * Creates the sfnext_start_figma_workflow MCP tool. * * @param loadServices - Function that loads configuration and returns Services instance * @returns MCP tool for workflow orchestration @@ -337,14 +337,14 @@ export function generateWorkflowResponse(figmaUrl: string, workflowFilePath?: st export function createFigmaToComponentTool(loadServices: () => Promise | Services): McpTool { return createToolAdapter( { - name: 'storefront_next_figma_to_component_workflow', + name: 'sfnext_start_figma_workflow', description: 'WORKFLOW ORCHESTRATOR: Call this tool FIRST when converting Figma designs. ' + 'Parses Figma URL to extract fileKey and nodeId, returns step-by-step workflow instructions ' + 'and parameters for subsequent tool calls. ' + 'CRITICAL: This is only the FIRST step. After calling this tool, you MUST continue executing ' + 'the complete workflow: 1) Call Figma MCP tools, 2) Discover similar components, ' + - '3) Call generate_component tool, 4) Call map_tokens_to_theme tool, ' + + '3) Call sfnext_analyze_component tool, 4) Call sfnext_match_tokens_to_theme tool, ' + '5) Show both outputs to the user then implement the recommended approach.', toolsets: ['STOREFRONTNEXT'], isGA: false, diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/generate-component/index.ts b/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/generate-component/index.ts index 5a00431a..e2e126a5 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/generate-component/index.ts +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/generate-component/index.ts @@ -126,7 +126,7 @@ export function generateComponentRecommendation(input: GenerateComponentInput): } /** - * Creates the storefront_next_generate_component MCP tool. + * Creates the sfnext_analyze_component MCP tool. * * @param loadServices - Function that loads configuration and returns Services instance * @returns MCP tool for component analysis and recommendation @@ -134,7 +134,7 @@ export function generateComponentRecommendation(input: GenerateComponentInput): export function createGenerateComponentTool(loadServices: () => Promise | Services): McpTool { return createToolAdapter( { - name: 'storefront_next_generate_component', + name: 'sfnext_analyze_component', description: 'Analyzes Figma design and discovered components to recommend component generation strategy. ' + 'Workflow: 1) Discover similar components using Glob/Grep/Read tools, ' + diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/map-tokens/index.ts b/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/map-tokens/index.ts index af28f155..33dada57 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/map-tokens/index.ts +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/map-tokens/index.ts @@ -252,7 +252,7 @@ export function mapFigmaTokensToTheme(args: MapTokensToThemeInput, workspaceRoot } /** - * Creates the storefront_next_map_tokens_to_theme MCP tool. + * Creates the sfnext_match_tokens_to_theme MCP tool. * * @param loadServices - Function that loads configuration and returns Services instance * @returns MCP tool for token mapping @@ -260,7 +260,7 @@ export function mapFigmaTokensToTheme(args: MapTokensToThemeInput, workspaceRoot export function createMapTokensToThemeTool(loadServices: () => Promise | Services): McpTool { return createToolAdapter( { - name: 'storefront_next_map_tokens_to_theme', + name: 'sfnext_match_tokens_to_theme', description: 'Maps Figma design tokens to existing StorefrontNext theme tokens in app.css. ' + 'Analyzes Figma design tokens (colors, spacing, radius, etc.) and finds exact matches, ' + diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/index.ts b/packages/b2c-dx-mcp/src/tools/storefrontnext/index.ts index 6cd5a5db..fe0da9c8 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/index.ts +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/index.ts @@ -10,12 +10,12 @@ * This toolset provides MCP tools for Storefront Next development. * * **Implemented Tools:** - * - `storefront_next_development_guidelines` - Get development guidelines and best practices - * - `storefront_next_page_designer_decorator` - Add Page Designer decorators to React components - * - `storefront_next_site_theming` - Get theming guidelines, questions, and validation - * - `storefront_next_figma_to_component_workflow` - Convert Figma to components - * - `storefront_next_generate_component` - Generate new components - * - `storefront_next_map_tokens_to_theme` - Map design tokens + * - `sfnext_get_guidelines` - Get development guidelines and best practices + * - `sfnext_add_page_designer_decorator` - Add Page Designer decorators to React components + * - `sfnext_configure_theme` - Get theming guidelines, questions, and validation + * - `sfnext_start_figma_workflow` - Convert Figma to components + * - `sfnext_analyze_component` - Analyze design and recommend REUSE/EXTEND/CREATE + * - `sfnext_match_tokens_to_theme` - Match design tokens to theme * * Note: mrt_bundle_push is defined in the MRT toolset and appears in STOREFRONTNEXT. * diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/README.md b/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/README.md index e62d5bcb..fddd981a 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/README.md +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/README.md @@ -41,19 +41,19 @@ page-designer-decorator/ ```bash # By component name (automatically finds the file) -storefront_next_page_designer_decorator({ +sfnext_add_page_designer_decorator({ component: "ProductItem", autoMode: true }) # Interactive mode -storefront_next_page_designer_decorator({ +sfnext_add_page_designer_decorator({ component: "ProductTile", conversationContext: { step: "analyze" } }) # With custom search paths (for unusual locations) -storefront_next_page_designer_decorator({ +sfnext_add_page_designer_decorator({ component: "ProductItem", searchPaths: ["packages/retail/src", "app/features"], autoMode: true @@ -64,7 +64,7 @@ storefront_next_page_designer_decorator({ ```bash # If you prefer to specify the exact path -storefront_next_page_designer_decorator({ +sfnext_add_page_designer_decorator({ component: "src/components/ProductItem.tsx", autoMode: true }) diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/index.ts b/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/index.ts index 293d3372..dab0f34e 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/index.ts +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/index.ts @@ -629,7 +629,7 @@ function handleAutoMode(args: PageDesignerDecoratorInput, workspaceRoot: string) */ export function createPageDesignerDecoratorTool(loadServices: () => Promise | Services): McpTool { return { - name: 'storefront_next_page_designer_decorator', + name: 'sfnext_add_page_designer_decorator', description: 'Adds Page Designer decorators (@Component, @AttributeDefinition, @RegionDefinition) to React components. ' + diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/templates/decorator-generator.ts b/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/templates/decorator-generator.ts index ac3b6384..1aca75a5 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/templates/decorator-generator.ts +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/templates/decorator-generator.ts @@ -344,7 +344,7 @@ function generateRegionDefinition(context: MetadataContext): string { * **Generated code must be:** * - Added to the component file (after imports, before component) * - Compiled with TypeScript - * - Used by `generate_page_designer_metadata` tool to create JSON metadata + * - Used by the staticRegistry Vite plugin to generate the component registry * * @param context - Complete metadata context * @returns TypeScript code string ready to paste into component file diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/sfnext-development-guidelines.ts b/packages/b2c-dx-mcp/src/tools/storefrontnext/sfnext-development-guidelines.ts index f553f66d..39382aa3 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/sfnext-development-guidelines.ts +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/sfnext-development-guidelines.ts @@ -106,7 +106,7 @@ const DEFAULT_SECTIONS: SectionKey[] = ['quick-reference', 'data-fetching', 'com export function createDeveloperGuidelinesTool(loadServices: () => Promise | Services): McpTool { return createToolAdapter( { - name: 'storefront_next_development_guidelines', + name: 'sfnext_get_guidelines', description: 'ESSENTIAL FIRST STEP for Storefront Next development. Returns critical architecture rules, coding standards, and best practices. ' + 'Use this tool FIRST before writing any Storefront Next code to understand non-negotiable patterns for React Server Components, ' + diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/site-theming/README.md b/packages/b2c-dx-mcp/src/tools/storefrontnext/site-theming/README.md index 6f746590..4fa92feb 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/site-theming/README.md +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/site-theming/README.md @@ -49,7 +49,7 @@ Content files (in `packages/b2c-dx-mcp/content/site-theming/`): ```json // First call - get guidelines and questions { - "name": "storefront_next_site_theming", + "name": "sfnext_configure_theme", "arguments": { "conversationContext": { "collectedAnswers": {"colors": [], "fonts": []} @@ -59,7 +59,7 @@ Content files (in `packages/b2c-dx-mcp/content/site-theming/`): // Validation call - after constructing colorMapping { - "name": "storefront_next_site_theming", + "name": "sfnext_configure_theme", "arguments": { "conversationContext": { "collectedAnswers": { diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/site-theming/index.ts b/packages/b2c-dx-mcp/src/tools/storefrontnext/site-theming/index.ts index 80ead1a5..77f9574c 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/site-theming/index.ts +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/site-theming/index.ts @@ -44,7 +44,7 @@ export type { export function createSiteThemingTool(loadServices: () => Promise | Services): McpTool { return createToolAdapter( { - name: 'storefront_next_site_theming', + name: 'sfnext_configure_theme', description: '⚠️ MANDATORY: Call this tool FIRST before implementing any theming changes. ' + 'Provides theming guidelines, questions, and automatic validation. ' + diff --git a/packages/b2c-dx-mcp/test/e2e/mcp-e2e.test.ts b/packages/b2c-dx-mcp/test/e2e/mcp-e2e.test.ts index ee642f8d..67a638e1 100644 --- a/packages/b2c-dx-mcp/test/e2e/mcp-e2e.test.ts +++ b/packages/b2c-dx-mcp/test/e2e/mcp-e2e.test.ts @@ -97,12 +97,15 @@ describe('MCP Server E2E', function () { it('filters tools by individual tool name', async () => { const client = new McpE2EClient({ - args: ['--tools', 'scapi_schemas_list,scapi_custom_apis_status', '--allow-non-ga-tools'], + args: ['--tools', 'scapi_schemas_list,scapi_custom_apis_get_status', '--allow-non-ga-tools'], }); await client.start(); const result = (await client.call('tools/list')) as {tools: Array<{name: string}>}; expect(result.tools).to.have.lengthOf(2); - expect(result.tools.map((t) => t.name).sort()).to.deep.equal(['scapi_custom_apis_status', 'scapi_schemas_list']); + expect(result.tools.map((t) => t.name).sort()).to.deep.equal([ + 'scapi_custom_apis_get_status', + 'scapi_schemas_list', + ]); await client.stop(); }); @@ -171,12 +174,12 @@ describe('MCP Server E2E', function () { it('returns proper error for invalid input when required param missing', async () => { const client = new McpE2EClient({ - args: ['--tools', 'storefront_next_page_designer_decorator', '--allow-non-ga-tools'], + args: ['--tools', 'sfnext_add_page_designer_decorator', '--allow-non-ga-tools'], }); await client.start(); try { await client.call('tools/call', { - name: 'storefront_next_page_designer_decorator', + name: 'sfnext_add_page_designer_decorator', arguments: {}, // missing required componentName etc. }); // May throw or return content with error @@ -204,7 +207,7 @@ describe('MCP Server E2E', function () { await client.start(); const result = (await client.call('tools/list')) as {tools: Array<{name: string}>}; const names = result.tools.map((t) => t.name); - expect(names.some((n) => n.includes('storefront_next') || n.includes('scapi'))).to.be.true; + expect(names.some((n) => n.includes('sfnext') || n.includes('scapi'))).to.be.true; await client.stop(); }); diff --git a/packages/b2c-dx-mcp/test/registry.test.ts b/packages/b2c-dx-mcp/test/registry.test.ts index 2d9819f5..ffaa5cf4 100644 --- a/packages/b2c-dx-mcp/test/registry.test.ts +++ b/packages/b2c-dx-mcp/test/registry.test.ts @@ -85,8 +85,8 @@ describe('registry', () => { const toolNames = registry.SCAPI.map((t) => t.name); expect(toolNames).to.include('scapi_schemas_list'); - expect(toolNames).to.include('scapi_custom_apis_status'); - expect(toolNames).to.include('scapi_custom_api_scaffold'); + expect(toolNames).to.include('scapi_custom_apis_get_status'); + expect(toolNames).to.include('scapi_custom_api_generate_scaffold'); }); it('should create STOREFRONTNEXT tools', () => { @@ -97,8 +97,8 @@ describe('registry', () => { expect(registry.STOREFRONTNEXT.length).to.be.greaterThan(0); const toolNames = registry.STOREFRONTNEXT.map((t) => t.name); - expect(toolNames).to.include('storefront_next_development_guidelines'); - expect(toolNames).to.include('storefront_next_page_designer_decorator'); + expect(toolNames).to.include('sfnext_get_guidelines'); + expect(toolNames).to.include('sfnext_add_page_designer_decorator'); // mrt_bundle_push should also appear in STOREFRONTNEXT (multi-toolset) expect(toolNames).to.include('mrt_bundle_push'); }); @@ -170,7 +170,7 @@ describe('registry', () => { expect(server.registeredTools).to.include('cartridge_deploy'); // Should not include tools exclusive to other toolsets - expect(server.registeredTools).to.not.include('scapi_custom_apis_status'); + expect(server.registeredTools).to.not.include('scapi_custom_apis_get_status'); }); it('should register tools from multiple toolsets', async () => { @@ -205,7 +205,7 @@ describe('registry', () => { expect(server.registeredTools).to.include('cartridge_deploy'); expect(server.registeredTools).to.include('mrt_bundle_push'); expect(server.registeredTools).to.include('scapi_schemas_list'); - expect(server.registeredTools).to.include('storefront_next_development_guidelines'); + expect(server.registeredTools).to.include('sfnext_get_guidelines'); }); it('should register individual tools via --tools flag', async () => { @@ -227,7 +227,7 @@ describe('registry', () => { const server = createMockServer(); const flags: StartupFlags = { toolsets: ['CARTRIDGES'], - tools: ['scapi_custom_apis_status'], + tools: ['scapi_custom_apis_get_status'], allowNonGaTools: true, }; @@ -237,7 +237,7 @@ describe('registry', () => { // Should include all CARTRIDGES tools expect(server.registeredTools).to.include('cartridge_deploy'); // Should also include the individual SCAPI tool - expect(server.registeredTools).to.include('scapi_custom_apis_status'); + expect(server.registeredTools).to.include('scapi_custom_apis_get_status'); // Should not include other SCAPI tools not in CARTRIDGES expect(server.registeredTools).to.not.include('scapi_schemas_list'); }); @@ -303,8 +303,8 @@ describe('registry', () => { // Auto-discovery always includes BASE_TOOLSET (SCAPI), even if no project type detected expect(server.registeredTools).to.include('scapi_schemas_list'); - expect(server.registeredTools).to.include('scapi_custom_apis_status'); - expect(server.registeredTools).to.include('scapi_custom_api_scaffold'); + expect(server.registeredTools).to.include('scapi_custom_apis_get_status'); + expect(server.registeredTools).to.include('scapi_custom_api_generate_scaffold'); }); it('should trigger auto-discovery when all individual tools are invalid', async () => { @@ -320,8 +320,8 @@ describe('registry', () => { // Auto-discovery always includes BASE_TOOLSET (SCAPI), even if no project type detected expect(server.registeredTools).to.include('scapi_schemas_list'); - expect(server.registeredTools).to.include('scapi_custom_apis_status'); - expect(server.registeredTools).to.include('scapi_custom_api_scaffold'); + expect(server.registeredTools).to.include('scapi_custom_apis_get_status'); + expect(server.registeredTools).to.include('scapi_custom_api_generate_scaffold'); }); it('should skip non-GA tools when allowNonGaTools is false', async () => { diff --git a/packages/b2c-dx-mcp/test/tools/pwav3/pwa-kit-development-guidelines.test.ts b/packages/b2c-dx-mcp/test/tools/pwav3/pwa-kit-development-guidelines.test.ts index 612f72a9..40387dfc 100644 --- a/packages/b2c-dx-mcp/test/tools/pwav3/pwa-kit-development-guidelines.test.ts +++ b/packages/b2c-dx-mcp/test/tools/pwav3/pwa-kit-development-guidelines.test.ts @@ -39,7 +39,7 @@ describe('tools/pwav3/pwa-kit-development-guidelines', () => { describe('tool metadata', () => { it('should have correct tool name', () => { const tool = createDeveloperGuidelinesTool(() => services); - expect(tool.name).to.equal('pwakit_development_guidelines'); + expect(tool.name).to.equal('pwakit_get_guidelines'); }); it('should have concise, action-oriented description', () => { diff --git a/packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-api-scaffold.test.ts b/packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-api-generate-scaffold.test.ts similarity index 97% rename from packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-api-scaffold.test.ts rename to packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-api-generate-scaffold.test.ts index ffafc156..3be3624e 100644 --- a/packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-api-scaffold.test.ts +++ b/packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-api-generate-scaffold.test.ts @@ -12,7 +12,7 @@ import path from 'node:path'; import { createScaffoldCustomApiTool, executeScaffoldCustomApi, -} from '../../../src/tools/scapi/scapi-custom-api-scaffold.js'; +} from '../../../src/tools/scapi/scapi-custom-api-generate-scaffold.js'; import {Services} from '../../../src/services.js'; import {createMockResolvedConfig} from '../../test-helpers.js'; import type {ToolResult} from '../../../src/utils/types.js'; @@ -48,7 +48,7 @@ interface ScaffoldOutput { error?: string; } -describe('tools/scapi/scapi-custom-api-scaffold', () => { +describe('tools/scapi/scapi-custom-api-generate-scaffold', () => { let services: Services; let tempDir: string; let loadServices: () => Services; @@ -68,11 +68,11 @@ describe('tools/scapi/scapi-custom-api-scaffold', () => { }); describe('createScaffoldCustomApiTool', () => { - it('should create scapi_custom_api_scaffold tool with correct metadata', () => { + it('should create scapi_custom_api_generate_scaffold tool with correct metadata', () => { const tool = createScaffoldCustomApiTool(loadServices); expect(tool).to.exist; - expect(tool.name).to.equal('scapi_custom_api_scaffold'); + expect(tool.name).to.equal('scapi_custom_api_generate_scaffold'); expect(tool.description).to.include('custom SCAPI'); expect(tool.description).to.include('apiName'); expect(tool.inputSchema).to.exist; diff --git a/packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-apis-status.test.ts b/packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-apis-get-status.test.ts similarity index 97% rename from packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-apis-status.test.ts rename to packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-apis-get-status.test.ts index ed314744..2bd1b4a7 100644 --- a/packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-apis-status.test.ts +++ b/packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-apis-get-status.test.ts @@ -7,7 +7,7 @@ import {expect} from 'chai'; import {describe, it, beforeEach, afterEach} from 'mocha'; import {stub, restore, type SinonStub} from 'sinon'; -import {createScapiCustomApisStatusTool} from '../../../src/tools/scapi/scapi-custom-apis-status.js'; +import {createScapiCustomApisStatusTool} from '../../../src/tools/scapi/scapi-custom-apis-get-status.js'; import {Services} from '../../../src/services.js'; import {createMockResolvedConfig} from '../../test-helpers.js'; import type {CustomApisClient, CustomApisComponents} from '@salesforce/b2c-tooling-sdk/clients'; @@ -66,7 +66,7 @@ function createMockClientResponse(endpoints: CustomApiEndpoint[], activeCodeVers }; } -describe('tools/scapi/scapi-custom-apis-status', () => { +describe('tools/scapi/scapi-custom-apis-get-status', () => { let services: Services; let mockGet: SinonStub; @@ -93,11 +93,11 @@ describe('tools/scapi/scapi-custom-apis-status', () => { }); describe('createScapiCustomApisStatusTool', () => { - it('should create scapi_custom_apis_status tool with correct metadata', () => { + it('should create scapi_custom_apis_get_status tool with correct metadata', () => { const tool = createScapiCustomApisStatusTool(() => services); expect(tool).to.exist; - expect(tool.name).to.equal('scapi_custom_apis_status'); + expect(tool.name).to.equal('scapi_custom_apis_get_status'); expect(tool.description).to.include('Custom'); expect(tool.description).to.include('endpoint'); expect(tool.description).to.include('Custom'); diff --git a/packages/b2c-dx-mcp/test/tools/scapi/scapi-schemas-list.test.ts b/packages/b2c-dx-mcp/test/tools/scapi/scapi-schemas-list.test.ts index e82faf81..06ff8bc2 100644 --- a/packages/b2c-dx-mcp/test/tools/scapi/scapi-schemas-list.test.ts +++ b/packages/b2c-dx-mcp/test/tools/scapi/scapi-schemas-list.test.ts @@ -61,7 +61,7 @@ describe('tools/scapi/scapi-schemas-list', () => { expect(tool.description).to.include('SCAPI'); expect(tool.description).to.include('List'); expect(tool.description).to.include('Fetch'); - expect(tool.description).to.include('scapi_custom_apis_status'); + expect(tool.description).to.include('scapi_custom_apis_get_status'); expect(tool.inputSchema).to.exist; expect(tool.handler).to.be.a('function'); expect(tool.toolsets).to.deep.equal(['PWAV3', 'SCAPI', 'STOREFRONTNEXT']); diff --git a/packages/b2c-dx-mcp/test/tools/storefrontnext/figma/README.md b/packages/b2c-dx-mcp/test/tools/storefrontnext/figma/README.md index 39cac7f1..35172f2b 100644 --- a/packages/b2c-dx-mcp/test/tools/storefrontnext/figma/README.md +++ b/packages/b2c-dx-mcp/test/tools/storefrontnext/figma/README.md @@ -42,7 +42,7 @@ mcp-inspector node --conditions development bin/dev.js --toolsets STOREFRONTNEXT Then in the inspector: 1. Click **Connect** -2. Click **List Tools** - you should see `storefront_next_figma_to_component_workflow`, `storefront_next_generate_component`, `storefront_next_map_tokens_to_theme` +2. Click **List Tools** - you should see `sfnext_start_figma_workflow`, `sfnext_analyze_component`, `sfnext_match_tokens_to_theme` 3. Click on each tool to test with sample inputs ### 3. CLI Testing @@ -58,20 +58,20 @@ npx mcp-inspector --cli node bin/run.js --toolsets STOREFRONTNEXT --allow-non-ga # Call figma-to-component workflow npx mcp-inspector --cli node bin/run.js --toolsets STOREFRONTNEXT --allow-non-ga-tools \ --method tools/call \ - --tool-name storefront_next_figma_to_component_workflow \ + --tool-name sfnext_start_figma_workflow \ --args '{"figmaUrl": "https://figma.com/design/abc123/MyDesign?node-id=1-2"}' # Call generate-component npx mcp-inspector --cli node bin/run.js --toolsets STOREFRONTNEXT --allow-non-ga-tools \ --method tools/call \ - --tool-name storefront_next_generate_component \ + --tool-name sfnext_analyze_component \ --args '{"figmaMetadata": "{}", "figmaCode": "
Hello
", "componentName": "TestComponent", "discoveredComponents": []}' # Call map-tokens (requires --project-directory with Storefront Next project containing app.css) npx mcp-inspector --cli node bin/run.js --toolsets STOREFRONTNEXT --allow-non-ga-tools \ --project-directory /path/to/storefront-next \ --method tools/call \ - --tool-name storefront_next_map_tokens_to_theme \ + --tool-name sfnext_match_tokens_to_theme \ --args '{"figmaTokens": [{"name": "Primary", "value": "#2563eb", "type": "color"}]}' ``` @@ -95,7 +95,7 @@ For `map-tokens` and `generate-component`, the tools use the project directory f ### 6. Test Scenarios -#### storefront_next_figma_to_component_workflow +#### sfnext_start_figma_workflow **Valid Figma URL** @@ -128,7 +128,7 @@ Expected: Error message with URL format guidance. Expected: Uses custom workflow content instead of default. -#### storefront_next_generate_component +#### sfnext_analyze_component **Empty discovered components (CREATE)** @@ -164,7 +164,7 @@ Expected: CREATE recommendation with confidence ~95%. Expected: REUSE, EXTEND, or CREATE based on analyzed differences. -#### storefront_next_map_tokens_to_theme +#### sfnext_match_tokens_to_theme **Basic token mapping** @@ -195,7 +195,7 @@ Expected: Uses specified theme file instead of auto-discovery. For a full Figma-to-component conversion, execute in order: -1. **Call `storefront_next_figma_to_component_workflow`** with the Figma URL. Receive fileKey, nodeId, and workflow instructions. +1. **Call `sfnext_start_figma_workflow`** with the Figma URL. Receive fileKey, nodeId, and workflow instructions. 2. **Call Figma MCP tools** (external) with the returned fileKey and nodeId: - `mcp__figma__get_design_context` (REQUIRED) @@ -204,9 +204,9 @@ For a full Figma-to-component conversion, execute in order: 3. **Discover similar components** using Glob/Grep/Read to search the codebase for components similar to the Figma design. -4. **Call `storefront_next_generate_component`** with figmaMetadata, figmaCode, componentName, and discoveredComponents. Receive REUSE/EXTEND/CREATE recommendation. +4. **Call `sfnext_analyze_component`** with figmaMetadata, figmaCode, componentName, and discoveredComponents. Receive REUSE/EXTEND/CREATE recommendation. -5. **Call `storefront_next_map_tokens_to_theme`** with design tokens extracted from Figma. Receive token mapping and suggestions. +5. **Call `sfnext_match_tokens_to_theme`** with design tokens extracted from Figma. Receive token mapping and suggestions. 6. **Implement** the recommended approach and present the component to the developer for review. @@ -214,7 +214,7 @@ For a full Figma-to-component conversion, execute in order: ### Theme File Not Found -If `map_tokens_to_theme` returns "Theme file (app.css) not found": +If `sfnext_match_tokens_to_theme` returns "Theme file (app.css) not found": - Ensure `--project-directory` points to a Storefront Next project root - Verify `app.css` or `src/app.css` exists in that directory diff --git a/packages/b2c-dx-mcp/test/tools/storefrontnext/figma/figma-to-component/index.test.ts b/packages/b2c-dx-mcp/test/tools/storefrontnext/figma/figma-to-component/index.test.ts index d933cc5d..e5f455ea 100644 --- a/packages/b2c-dx-mcp/test/tools/storefrontnext/figma/figma-to-component/index.test.ts +++ b/packages/b2c-dx-mcp/test/tools/storefrontnext/figma/figma-to-component/index.test.ts @@ -126,14 +126,16 @@ describe('Figma To Component Workflow (figma/)', () => { expect(response).to.include('`mcp__figma__get_design_context`'); expect(response).to.include('`mcp__figma__get_screenshot`'); - expect(response).to.include('`generate_component`'); - expect(response).to.include('`map_tokens_to_theme`'); + expect(response).to.include('`sfnext_analyze_component`'); + expect(response).to.include('`sfnext_match_tokens_to_theme`'); }); it('should include the do-not-stop instruction', () => { const response = generateWorkflowResponse('https://figma.com/design/abc123/MyDesign?node-id=1-2'); - expect(response).to.include('DO NOT STOP until you have called generate_component AND map_tokens_to_theme'); + expect(response).to.include( + 'DO NOT STOP until you have called sfnext_analyze_component AND sfnext_match_tokens_to_theme', + ); }); it('should include image export approval instruction (user must confirm before exporting)', () => { diff --git a/packages/b2c-dx-mcp/test/tools/storefrontnext/page-designer-decorator/README.md b/packages/b2c-dx-mcp/test/tools/storefrontnext/page-designer-decorator/README.md index 3a509f4f..cc069890 100644 --- a/packages/b2c-dx-mcp/test/tools/storefrontnext/page-designer-decorator/README.md +++ b/packages/b2c-dx-mcp/test/tools/storefrontnext/page-designer-decorator/README.md @@ -37,7 +37,7 @@ pnpm run inspect:dev Then in the inspector: 1. Click **Connect** -2. Click **List Tools** - you should see `storefront_next_page_designer_decorator` +2. Click **List Tools** - you should see `sfnext_add_page_designer_decorator` 3. Click on the tool to test it with real inputs ### 3. CLI Testing @@ -45,13 +45,13 @@ Then in the inspector: Test via command line: ```bash -# List all tools (should include storefront_next_page_designer_decorator) +# List all tools (should include sfnext_add_page_designer_decorator) npx mcp-inspector --cli node bin/dev.js --toolsets STOREFRONTNEXT --allow-non-ga-tools --method tools/list # Call the tool npx mcp-inspector --cli node bin/dev.js --toolsets STOREFRONTNEXT --allow-non-ga-tools \ --method tools/call \ - --tool-name storefront_next_page_designer_decorator \ + --tool-name sfnext_add_page_designer_decorator \ --args '{"component": "MyComponent"}' ``` diff --git a/packages/b2c-dx-mcp/test/tools/storefrontnext/page-designer-decorator/index.test.ts b/packages/b2c-dx-mcp/test/tools/storefrontnext/page-designer-decorator/index.test.ts index 8e893443..5d19ebec 100644 --- a/packages/b2c-dx-mcp/test/tools/storefrontnext/page-designer-decorator/index.test.ts +++ b/packages/b2c-dx-mcp/test/tools/storefrontnext/page-designer-decorator/index.test.ts @@ -138,7 +138,7 @@ describe('tools/storefrontnext/page-designer-decorator', () => { describe('tool metadata', () => { it('should have correct tool name', () => { const tool = createPageDesignerDecoratorTool(getServices); - expect(tool.name).to.equal('storefront_next_page_designer_decorator'); + expect(tool.name).to.equal('sfnext_add_page_designer_decorator'); }); it('should have comprehensive description', () => { diff --git a/packages/b2c-dx-mcp/test/tools/storefrontnext/sfnext-development-guidelines.test.ts b/packages/b2c-dx-mcp/test/tools/storefrontnext/sfnext-development-guidelines.test.ts index 8d656df6..c5035d99 100644 --- a/packages/b2c-dx-mcp/test/tools/storefrontnext/sfnext-development-guidelines.test.ts +++ b/packages/b2c-dx-mcp/test/tools/storefrontnext/sfnext-development-guidelines.test.ts @@ -39,7 +39,7 @@ describe('tools/storefrontnext/sfnext-development-guidelines', () => { describe('tool metadata', () => { it('should have correct tool name', () => { const tool = createDeveloperGuidelinesTool(() => services); - expect(tool.name).to.equal('storefront_next_development_guidelines'); + expect(tool.name).to.equal('sfnext_get_guidelines'); }); it('should have concise, action-oriented description', () => { diff --git a/packages/b2c-dx-mcp/test/tools/storefrontnext/site-theming/README.md b/packages/b2c-dx-mcp/test/tools/storefrontnext/site-theming/README.md index 4ba44cd7..716b73e9 100644 --- a/packages/b2c-dx-mcp/test/tools/storefrontnext/site-theming/README.md +++ b/packages/b2c-dx-mcp/test/tools/storefrontnext/site-theming/README.md @@ -37,7 +37,7 @@ pnpm run inspect:dev Then in the inspector: 1. Click **Connect** -2. Click **List Tools** - you should see `storefront_next_site_theming` +2. Click **List Tools** - you should see `sfnext_configure_theme` 3. Click on the tool to test it with real inputs ### 3. CLI Testing @@ -45,19 +45,19 @@ Then in the inspector: Test via command line: ```bash -# List all tools (should include storefront_next_site_theming) +# List all tools (should include sfnext_configure_theme) npx mcp-inspector --cli node bin/dev.js --toolsets STOREFRONTNEXT --allow-non-ga-tools --method tools/list # Call the tool - list available files npx mcp-inspector --cli node bin/dev.js --toolsets STOREFRONTNEXT --allow-non-ga-tools \ --method tools/call \ - --tool-name storefront_next_site_theming \ + --tool-name sfnext_configure_theme \ --args '{}' # Call with conversation context - get guidelines and questions npx mcp-inspector --cli node bin/dev.js --toolsets STOREFRONTNEXT --allow-non-ga-tools \ --method tools/call \ - --tool-name storefront_next_site_theming \ + --tool-name sfnext_configure_theme \ --args '{"conversationContext":{"collectedAnswers":{"colors":[],"fonts":[]}}}' ``` diff --git a/packages/b2c-dx-mcp/test/tools/storefrontnext/site-theming/index.test.ts b/packages/b2c-dx-mcp/test/tools/storefrontnext/site-theming/index.test.ts index f27dc947..da0e9e3d 100644 --- a/packages/b2c-dx-mcp/test/tools/storefrontnext/site-theming/index.test.ts +++ b/packages/b2c-dx-mcp/test/tools/storefrontnext/site-theming/index.test.ts @@ -53,7 +53,7 @@ describe('tools/storefrontnext/site-theming', () => { describe('tool metadata', () => { it('should have correct structure', () => { const tool = createSiteThemingTool(createMockLoadServices(services)); - expect(tool).to.have.property('name', 'storefront_next_site_theming'); + expect(tool).to.have.property('name', 'sfnext_configure_theme'); expect(tool.description).to.include('theming guidelines'); expect(tool).to.have.property('inputSchema'); expect(tool).to.have.property('handler'); From c65496323e756327a5bbafeffa99b78fcb8a395d Mon Sep 17 00:00:00 2001 From: Yuming Hsieh Date: Tue, 17 Mar 2026 15:24:47 -0400 Subject: [PATCH 2/6] @W-21513849 update tool names and docs Made-with: Cursor --- .changeset/mcp-tool-renames.md | 6 +++ docs/.vitepress/config.mts | 18 +++---- docs/mcp/figma-tools-setup.md | 10 ++-- ...guidelines.md => pwakit-get-guidelines.md} | 4 +- ... => scapi-custom-api-generate-scaffold.md} | 10 ++-- ...tus.md => scapi-custom-apis-get-status.md} | 4 +- docs/mcp/tools/scapi-schemas-list.md | 23 +++----- ... => sfnext-add-page-designer-decorator.md} | 4 +- ...mponent.md => sfnext-analyze-component.md} | 54 ++++++++++--------- ...e-theming.md => sfnext-configure-theme.md} | 4 +- ...guidelines.md => sfnext-get-guidelines.md} | 6 +-- ...flow.md => sfnext-start-figma-workflow.md} | 18 +++---- docs/mcp/toolsets.md | 30 +++++------ packages/b2c-dx-mcp/CONTRIBUTING.md | 2 +- packages/b2c-dx-mcp/README.md | 42 +++++++-------- .../content/sfnext/page-designer.md | 20 +++---- .../content/sfnext/quick-reference.md | 2 +- .../pwav3/pwa-kit-development-guidelines.ts | 2 +- packages/b2c-dx-mcp/src/tools/scapi/index.ts | 4 +- ... => scapi-custom-api-generate-scaffold.ts} | 12 ++--- ...tus.ts => scapi-custom-apis-get-status.ts} | 10 ++-- .../src/tools/scapi/scapi-schemas-list.ts | 2 +- .../src/tools/storefrontnext/README.md | 28 +++++----- .../figma/figma-to-component/index.ts | 14 ++--- .../figma/generate-component/index.ts | 4 +- .../storefrontnext/figma/map-tokens/index.ts | 4 +- .../src/tools/storefrontnext/index.ts | 12 ++--- .../page-designer-decorator/README.md | 8 +-- .../page-designer-decorator/index.ts | 2 +- .../templates/decorator-generator.ts | 2 +- .../sfnext-development-guidelines.ts | 2 +- .../storefrontnext/site-theming/README.md | 4 +- .../storefrontnext/site-theming/index.ts | 2 +- packages/b2c-dx-mcp/test/e2e/mcp-e2e.test.ts | 13 +++-- packages/b2c-dx-mcp/test/registry.test.ts | 24 ++++----- .../pwa-kit-development-guidelines.test.ts | 2 +- ...capi-custom-api-generate-scaffold.test.ts} | 8 +-- ...s => scapi-custom-apis-get-status.test.ts} | 8 +-- .../tools/scapi/scapi-schemas-list.test.ts | 2 +- .../test/tools/storefrontnext/figma/README.md | 22 ++++---- .../figma/figma-to-component/index.test.ts | 8 +-- .../page-designer-decorator/README.md | 6 +-- .../page-designer-decorator/index.test.ts | 2 +- .../sfnext-development-guidelines.test.ts | 2 +- .../storefrontnext/site-theming/README.md | 8 +-- .../storefrontnext/site-theming/index.test.ts | 2 +- 46 files changed, 234 insertions(+), 242 deletions(-) create mode 100644 .changeset/mcp-tool-renames.md rename docs/mcp/tools/{pwakit-development-guidelines.md => pwakit-get-guidelines.md} (96%) rename docs/mcp/tools/{scapi-custom-api-scaffold.md => scapi-custom-api-generate-scaffold.md} (88%) rename docs/mcp/tools/{scapi-custom-apis-status.md => scapi-custom-apis-get-status.md} (97%) rename docs/mcp/tools/{storefront-next-page-designer-decorator.md => sfnext-add-page-designer-decorator.md} (95%) rename docs/mcp/tools/{storefront-next-generate-component.md => sfnext-analyze-component.md} (52%) rename docs/mcp/tools/{storefront-next-site-theming.md => sfnext-configure-theme.md} (96%) rename docs/mcp/tools/{storefront-next-development-guidelines.md => sfnext-get-guidelines.md} (93%) rename docs/mcp/tools/{storefront-next-figma-to-component-workflow.md => sfnext-start-figma-workflow.md} (80%) rename packages/b2c-dx-mcp/src/tools/scapi/{scapi-custom-api-scaffold.ts => scapi-custom-api-generate-scaffold.ts} (96%) rename packages/b2c-dx-mcp/src/tools/scapi/{scapi-custom-apis-status.ts => scapi-custom-apis-get-status.ts} (96%) rename packages/b2c-dx-mcp/test/tools/scapi/{scapi-custom-api-scaffold.test.ts => scapi-custom-api-generate-scaffold.test.ts} (97%) rename packages/b2c-dx-mcp/test/tools/scapi/{scapi-custom-apis-status.test.ts => scapi-custom-apis-get-status.test.ts} (97%) diff --git a/.changeset/mcp-tool-renames.md b/.changeset/mcp-tool-renames.md new file mode 100644 index 00000000..6b931e71 --- /dev/null +++ b/.changeset/mcp-tool-renames.md @@ -0,0 +1,6 @@ +--- +'@salesforce/b2c-dx-mcp': minor +'@salesforce/b2c-dx-docs': patch +--- + +Rename MCP tools for clearer, action-oriented naming. scapi_custom_api_scaffold β†’ scapi_custom_api_generate_scaffold. sfnext_map_tokens_to_theme β†’ sfnext_match_tokens_to_theme. diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 80f4afdc..3df0dc84 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -102,16 +102,16 @@ const referenceSidebar = [ 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: 'pwakit_get_guidelines', link: '/mcp/tools/pwakit-get-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'}, + {text: 'scapi_custom_api_generate_scaffold', link: '/mcp/tools/scapi-custom-api-generate-scaffold'}, + {text: 'scapi_custom_apis_get_status', link: '/mcp/tools/scapi-custom-apis-get-status'}, + {text: 'sfnext_get_guidelines', link: '/mcp/tools/sfnext-get-guidelines'}, + {text: 'sfnext_start_figma_workflow', link: '/mcp/tools/sfnext-start-figma-workflow'}, + {text: 'sfnext_analyze_component', link: '/mcp/tools/sfnext-analyze-component'}, + {text: 'sfnext_match_tokens_to_theme', link: '/mcp/tools/sfnext-match-tokens-to-theme'}, + {text: 'sfnext_add_page_designer_decorator', link: '/mcp/tools/sfnext-add-page-designer-decorator'}, + {text: 'sfnext_configure_theme', link: '/mcp/tools/sfnext-configure-theme'}, ], }, ]; diff --git a/docs/mcp/figma-tools-setup.md b/docs/mcp/figma-tools-setup.md index 18ec3db5..e61d0f0f 100644 --- a/docs/mcp/figma-tools-setup.md +++ b/docs/mcp/figma-tools-setup.md @@ -4,7 +4,7 @@ description: Prerequisites and setup for Figma-to-component tools (workflow orch # 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`. +Prerequisites and setup for using the Figma workflow tools: `sfnext_start_figma_workflow`, `sfnext_analyze_component`, and `sfnext_match_tokens_to_theme`. > **Note:** 🚧 This MCP tool is for Storefront Next. Storefront Next is part of a closed pilot and isn't available for general use. @@ -15,7 +15,7 @@ The Figma-to-component workflow requires an **external Figma MCP server** to fet **Prerequisites:** - b2c-dx-mcp configured with `--allow-non-ga-tools` flag (Figma tools are preview) - Storefront Next project -- `app.css` theme file (required for `storefront_next_map_tokens_to_theme` tool; optional path can be provided) +- `app.css` theme file (required for `sfnext_match_tokens_to_theme` tool; optional path can be provided) - External Figma MCP server enabled in your MCP client See [Installation](./installation) for b2c-dx-mcp setup. @@ -49,8 +49,8 @@ If the Figma MCP server is not enabled, the workflow tool will still return inst ## 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 +- [sfnext_start_figma_workflow](./tools/sfnext-start-figma-workflow) - Workflow orchestrator (call first) +- [sfnext_analyze_component](./tools/sfnext-analyze-component) - REUSE/EXTEND/CREATE recommendation +- [sfnext_match_tokens_to_theme](./tools/sfnext-match-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 diff --git a/docs/mcp/tools/pwakit-development-guidelines.md b/docs/mcp/tools/pwakit-get-guidelines.md similarity index 96% rename from docs/mcp/tools/pwakit-development-guidelines.md rename to docs/mcp/tools/pwakit-get-guidelines.md index 914ff643..c97e9505 100644 --- a/docs/mcp/tools/pwakit-development-guidelines.md +++ b/docs/mcp/tools/pwakit-get-guidelines.md @@ -2,13 +2,13 @@ description: Get PWA Kit v3 development guidelines and best practices for React, Chakra UI, and Commerce API. --- -# pwakit_development_guidelines +# pwakit_get_guidelines Returns critical architecture rules, coding standards, and best practices for building PWA Kit v3 applications with React, Chakra UI, and Commerce API. ## Overview -The `pwakit_development_guidelines` tool provides essential development guidance for PWA Kit v3. It: +The `pwakit_get_guidelines` tool provides essential development guidance for PWA Kit v3. It: 1. Returns comprehensive guidelines by default (quick-reference plus key sections). 2. Supports retrieving specific topic sections on demand. diff --git a/docs/mcp/tools/scapi-custom-api-scaffold.md b/docs/mcp/tools/scapi-custom-api-generate-scaffold.md similarity index 88% rename from docs/mcp/tools/scapi-custom-api-scaffold.md rename to docs/mcp/tools/scapi-custom-api-generate-scaffold.md index 943369d0..6395a81b 100644 --- a/docs/mcp/tools/scapi-custom-api-scaffold.md +++ b/docs/mcp/tools/scapi-custom-api-generate-scaffold.md @@ -2,19 +2,19 @@ description: Generate a new custom SCAPI endpoint (OAS 3.0 schema, api.json, script.js) in an existing cartridge. --- -# scapi_custom_api_scaffold +# scapi_custom_api_generate_scaffold Generate a new custom SCAPI endpoint in an existing cartridge. Creates `schema.yaml` (OAS 3.0 contract), `api.json` (endpoint mapping), and `script.js` (implementation) under the cartridge's `rest-apis//` directory. ## Overview -The `scapi_custom_api_scaffold` tool scaffolds a new custom API using the B2C tooling SDK's `custom-api` scaffold. It: +The `scapi_custom_api_generate_scaffold` tool scaffolds a new custom API using the B2C tooling SDK's `custom-api` scaffold. It: - Creates an OpenAPI 3.0 schema, API manifest, and script stub in your project. - Uses the first cartridge found in the project if you don't specify one. - Supports **shopper** (siteId, customer-facing) or **admin** (no siteId) API types. -**No instance or OAuth required** β€” this tool works locally and only writes files into your project. To check registration status after deployment, use [`scapi_custom_apis_status`](./scapi-custom-apis-status). +**No instance or OAuth required** β€” this tool works locally and only writes files into your project. To check registration status after deployment, use [`scapi_custom_apis_get_status`](./scapi-custom-apis-get-status). ## Parameters @@ -78,7 +78,7 @@ Returns the scaffold ID, output directory, and list of created files: 1. **Edit** `schema.yaml` to define paths, request/response schemas, and operation IDs. 2. **Edit** `script.js` to implement the endpoint logic. 3. **Deploy** the cartridge to your instance and **activate** the code version to register the API. -4. **Verify** with [`scapi_custom_apis_status`](./scapi-custom-apis-status) that endpoints show as `active`. +4. **Verify** with [`scapi_custom_apis_get_status`](./scapi-custom-apis-get-status) that endpoints show as `active`. Shopper APIs are available at: `https://{shortCode}.api.commercecloud.salesforce.com/custom/{apiName}/v1/organizations/{organizationId}/...` and require the `siteId` query parameter and ShopperToken authentication. @@ -86,7 +86,7 @@ Shopper APIs are available at: ## Related Tools - Part of the [SCAPI](../toolsets#scapi), [PWAV3](../toolsets#pwav3), and [STOREFRONTNEXT](../toolsets#storefrontnext) toolsets -- [`scapi_custom_apis_status`](./scapi-custom-apis-status) β€” Check custom API endpoint registration status after deployment +- [`scapi_custom_apis_get_status`](./scapi-custom-apis-get-status) β€” Check custom API endpoint registration status after deployment - [`scapi_schemas_list`](./scapi-schemas-list) β€” List or fetch custom API schemas (use `apiFamily: "custom"`) ## See Also diff --git a/docs/mcp/tools/scapi-custom-apis-status.md b/docs/mcp/tools/scapi-custom-apis-get-status.md similarity index 97% rename from docs/mcp/tools/scapi-custom-apis-status.md rename to docs/mcp/tools/scapi-custom-apis-get-status.md index 63a676fa..f286437d 100644 --- a/docs/mcp/tools/scapi-custom-apis-status.md +++ b/docs/mcp/tools/scapi-custom-apis-get-status.md @@ -2,7 +2,7 @@ description: Check the registration status of custom SCAPI endpoints deployed on your B2C Commerce instance. --- -# scapi_custom_apis_status +# scapi_custom_apis_get_status List custom SCAPI endpoint registration status (active/not_registered). Returns one row per endpoint per site with detailed status information. @@ -10,7 +10,7 @@ List custom SCAPI endpoint registration status (active/not_registered). Returns Checks the registration status of custom API endpoints deployed on your B2C Commerce instance. Returns endpoint status (`active` or `not_registered`) with per-site details. -**Note:** This tool queries your live instance. For schema definitions, use [`scapi_schemas_list`](./scapi-schemas-list) with `apiFamily: "custom"`. To create a new custom API, use [`scapi_custom_api_scaffold`](./scapi-custom-api-scaffold). +**Note:** This tool queries your live instance. For schema definitions, use [`scapi_schemas_list`](./scapi-schemas-list) with `apiFamily: "custom"`. To create a new custom API, use [`scapi_custom_api_generate_scaffold`](./scapi-custom-api-generate-scaffold). ## Authentication diff --git a/docs/mcp/tools/scapi-schemas-list.md b/docs/mcp/tools/scapi-schemas-list.md index c9781bcb..e8407dc7 100644 --- a/docs/mcp/tools/scapi-schemas-list.md +++ b/docs/mcp/tools/scapi-schemas-list.md @@ -13,7 +13,7 @@ The `scapi_schemas_list` tool provides two modes of operation. 1. **List (Discovery)**: Browse available schemas without fetching full OpenAPI specs. 2. **Fetch**: Retrieve complete OpenAPI schema for a specific API. -This tool works with both standard SCAPI (Shop, Admin, Shopper APIs) and custom APIs. For endpoint registration status, use [`scapi_custom_apis_status`](./scapi-custom-apis-status) instead. +This tool works with both standard SCAPI (Shop, Admin, Shopper APIs) and custom APIs. For endpoint registration status, use [`scapi_custom_apis_get_status`](./scapi-custom-apis-get-status) instead. ## Authentication @@ -48,12 +48,6 @@ Omit `includeSchemas` or any identifier to browse available schemas: - `availableApiNames` - List of available API names - `availableApiVersions` - List of available API versions -**Example prompts:** -- βœ… "Use the MCP tool to list all available SCAPI schemas." -- βœ… "Use the MCP tool to show me what checkout APIs exist." β†’ `apiFamily: "checkout"` -- βœ… "Use the MCP tool to discover SCAPI product endpoints." β†’ `apiFamily: "product"` -- βœ… "Use the MCP tool to list custom API definitions." β†’ `apiFamily: "custom"` - ### Fetch Mode Set `includeSchemas: true` and provide all three identifiers (`apiFamily`, `apiName`, `apiVersion`) to fetch a complete OpenAPI schema: @@ -62,11 +56,6 @@ Set `includeSchemas: true` and provide all three identifiers (`apiFamily`, `apiN - Full OpenAPI schema specification - Use `expandAll: true` to get the complete schema without collapsing -**Example prompts:** -- βœ… "Use the MCP tool to get the OpenAPI schema for shopper-baskets v1." β†’ `apiFamily: "shopper"`, `apiName: "shopper-baskets"`, `apiVersion: "v1"`, `includeSchemas: true` -- βœ… "Use the MCP tool to show me the full OpenAPI spec for shopper-products v1." β†’ `includeSchemas: true`, `expandAll: true` -- βœ… "Use the MCP tool to show me the loyalty-points custom API schema." β†’ `apiFamily: "custom"`, `apiName: "loyalty-points"`, `apiVersion: "v1"`, `includeSchemas: true` - ## Usage Examples ### Standard SCAPI Discovery @@ -83,6 +72,10 @@ Filter by API family: Use the MCP tool to show me what checkout APIs exist. ``` +``` +Use the MCP tool to discover SCAPI product endpoints. +``` + ### Custom API Discovery List custom API definitions: @@ -154,13 +147,13 @@ Use the MCP tool to show me the full OpenAPI spec for shopper-products v1. - Part of the [SCAPI](../toolsets#scapi), [PWAV3](../toolsets#pwav3), and [STOREFRONTNEXT](../toolsets#storefrontnext) toolsets - Always enabled (base toolset) -- For endpoint registration status, use [`scapi_custom_apis_status`](./scapi-custom-apis-status) +- For endpoint registration status, use [`scapi_custom_apis_get_status`](./scapi-custom-apis-get-status) ## See Also - [SCAPI Toolset](../toolsets#scapi) - Overview of SCAPI discovery tools -- [scapi_custom_apis_status](./scapi-custom-apis-status) - Check custom API endpoint registration status -- [scapi_custom_api_scaffold](./scapi-custom-api-scaffold) - Generate a new custom API in a cartridge +- [scapi_custom_apis_get_status](./scapi-custom-apis-get-status) - Check custom API endpoint registration status +- [scapi_custom_api_generate_scaffold](./scapi-custom-api-generate-scaffold) - Generate a new custom API in a cartridge - [Authentication Setup](../../guide/authentication#scapi-authentication) - Set up SCAPI authentication with required roles and scopes - [Configuration](../configuration) - Configure OAuth credentials - [CLI Reference](../../cli/scapi-schemas) - Equivalent CLI commands: `b2c scapi schemas list` and `b2c scapi schemas get` diff --git a/docs/mcp/tools/storefront-next-page-designer-decorator.md b/docs/mcp/tools/sfnext-add-page-designer-decorator.md similarity index 95% rename from docs/mcp/tools/storefront-next-page-designer-decorator.md rename to docs/mcp/tools/sfnext-add-page-designer-decorator.md index 18ddc699..cd8c18f5 100644 --- a/docs/mcp/tools/storefront-next-page-designer-decorator.md +++ b/docs/mcp/tools/sfnext-add-page-designer-decorator.md @@ -2,7 +2,7 @@ description: Add Page Designer decorators to React components for Storefront Next to make them available in Page Designer. --- -# storefront_next_page_designer_decorator +# sfnext_add_page_designer_decorator Adds Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDefinition`) to React components to make them available in Page Designer for Storefront Next. @@ -10,7 +10,7 @@ Adds Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDef ## Overview -The `storefront_next_page_designer_decorator` tool analyzes React components and generates Page Designer decorators that enable components to be used in Page Designer. It supports two modes: +The `sfnext_add_page_designer_decorator` tool analyzes React components and generates Page Designer decorators that enable components to be used in Page Designer. It supports two modes: 1. **Auto Mode**: Quick setup with sensible defaults-automatically selects suitable props, infers types, and generates decorators immediately. 2. **Interactive Mode**: Multi-step workflow for fine-tuned control over decorator configuration. diff --git a/docs/mcp/tools/storefront-next-generate-component.md b/docs/mcp/tools/sfnext-analyze-component.md similarity index 52% rename from docs/mcp/tools/storefront-next-generate-component.md rename to docs/mcp/tools/sfnext-analyze-component.md index b20d8acd..d0d334fc 100644 --- a/docs/mcp/tools/storefront-next-generate-component.md +++ b/docs/mcp/tools/sfnext-analyze-component.md @@ -1,28 +1,28 @@ --- -description: Analyze Figma design and discovered components to recommend REUSE, EXTEND, or CREATE strategy. +description: Analyze design and discovered components to recommend REUSE, EXTEND, or CREATE strategy. --- -# storefront_next_generate_component +# sfnext_analyze_component -Analyzes Figma design and discovered components to recommend a component generation strategy. Returns a REUSE, EXTEND, or CREATE action with confidence score, key differences, and suggested implementation approach. +Analyzes design and discovered components to recommend a component generation strategy. Returns a REUSE, EXTEND, or CREATE action with confidence score, key differences, and suggested implementation approach. > **Note:** 🚧 This MCP tool is for Storefront Next. Storefront Next is part of a closed pilot and isn't available for general use. ## Overview -The `storefront_next_generate_component` tool compares Figma-generated React code against existing components discovered in the codebase. It analyzes differences across styling, structure, behavior, and props, then recommends the best approach: +The `sfnext_analyze_component` tool compares design React code (e.g., from Figma, design handoff, or other sources) against existing components discovered in the codebase. It analyzes differences across styling, structure, behavior, and props, then recommends the best approach: - **REUSE**: Use existing component with props or minor styling adjustments - **EXTEND**: Extend existing component via props, variant, or composition pattern - **CREATE**: Create a new component (reference existing patterns if applicable) -**Workflow position:** Call this tool **after** retrieving Figma design data and discovering similar components. It is a required step in the Figma-to-component workflow. +**Workflow position:** Call this tool **after** retrieving design data and discovering similar components. It is a required step in the Figma-to-component workflow. This tool is part of the STOREFRONTNEXT toolset. ## Prerequisites -- Figma design data retrieved via Figma MCP tools +- Design React code (from Figma MCP, design handoff, or other sources) - Component discovery performed before calling - Storefront Next project @@ -32,9 +32,9 @@ See [Figma-to-Component Tools Setup](../figma-tools-setup) for complete prerequi | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `figmaMetadata` | string | Yes | JSON string containing Figma design metadata from `mcp__figma__get_metadata`. Can be empty string if metadata was not fetched. | -| `figmaCode` | string | Yes | Generated React code from Figma (from `mcp__figma__get_design_context`). | -| `componentName` | string | Yes | Suggested name for the component extracted from the Figma design. | +| `figmaMetadata` | string | Yes | JSON string containing design metadata (from Figma MCP or empty). Can be empty string if metadata was not fetched. | +| `figmaCode` | string | Yes | React code from design (e.g., from Figma `mcp__figma__get_design_context`, or design handoff). | +| `componentName` | string | Yes | Suggested name for the component extracted from the design. | | `discoveredComponents` | array | Yes | Array of similar components discovered using Glob/Grep/Read. Pass empty array if no similar components found. | | `workspacePath` | string | No | Optional workspace root path. Defaults to the MCP server project directory. | @@ -50,6 +50,23 @@ Each item in `discoveredComponents` must have: | `matchType` | string | One of `'name'`, `'structure'`, `'visual'` | | `code` | string | Full source code of the component | +## Usage Examples + +### With Figma design URL + +``` +I have a Figma design at [URL]. Use the MCP tool to fetch the design code, search the codebase for similar components, then analyze and recommend whether to reuse, extend, or create a component. +``` + +### With design code already fetched + +``` +Use the MCP tool to analyze this design and recommend reuse, extend, or create. Design code: [paste React/JSX from Figma or design handoff]. Search the codebase for similar components first, then call the tool with the discovered components. +``` + +### Agent workflow note + +When the agent searches the codebase and finds no similar components, it should still call the tool with `discoveredComponents: []` to get a CREATE recommendation. The user does not need to specify thisβ€”the agent discovers it during the workflow. ## Output @@ -62,25 +79,10 @@ Returns a formatted recommendation including: - **Suggested Approach**: Implementation guidance - **Next Steps**: Action-specific instructions -## Usage Examples - -### With Discovered Components - -``` -Use the MCP tool to analyze the Figma design and recommend whether to reuse, extend, or create a component. I've discovered PrimaryButton and SecondaryButton as similar components. -``` - -### No Similar Components - -``` -Use the MCP tool to analyze the Figma design. No similar components were found in the codebase. -``` - - ## Related Tools -- [`storefront_next_figma_to_component_workflow`](./storefront-next-figma-to-component-workflow) - Call first to get workflow instructions and Figma parameters -- [`storefront_next_map_tokens_to_theme`](./storefront-next-map-tokens-to-theme) - Map Figma design tokens to theme variables +- [`sfnext_start_figma_workflow`](./sfnext-start-figma-workflow) - Call first to get workflow instructions and Figma parameters +- [`sfnext_match_tokens_to_theme`](./sfnext-match-tokens-to-theme) - Match design tokens to theme variables - Part of the [STOREFRONTNEXT](../toolsets#storefrontnext) toolset - Auto-enabled for Storefront Next projects diff --git a/docs/mcp/tools/storefront-next-site-theming.md b/docs/mcp/tools/sfnext-configure-theme.md similarity index 96% rename from docs/mcp/tools/storefront-next-site-theming.md rename to docs/mcp/tools/sfnext-configure-theme.md index 6c8b6071..be5a124c 100644 --- a/docs/mcp/tools/storefront-next-site-theming.md +++ b/docs/mcp/tools/sfnext-configure-theme.md @@ -2,7 +2,7 @@ description: Get theming guidelines, guided questions, and WCAG color contrast validation for Storefront Next. --- -# storefront_next_site_theming +# sfnext_configure_theme Guides theming changes (colors, fonts, visual styling) for Storefront Next and validates color combinations for WCAG accessibility. @@ -10,7 +10,7 @@ Guides theming changes (colors, fonts, visual styling) for Storefront Next and v ## Overview -The `storefront_next_site_theming` tool provides a structured workflow for applying theming to Storefront Next sites: +The `sfnext_configure_theme` tool provides a structured workflow for applying theming to Storefront Next sites: 1. **Guidelines** - Layout preservation rules, specification compliance, and accessibility requirements 2. **Guided Questions** - Collects user preferences (colors, fonts, mappings) one at a time diff --git a/docs/mcp/tools/storefront-next-development-guidelines.md b/docs/mcp/tools/sfnext-get-guidelines.md similarity index 93% rename from docs/mcp/tools/storefront-next-development-guidelines.md rename to docs/mcp/tools/sfnext-get-guidelines.md index e6c660b2..164d841d 100644 --- a/docs/mcp/tools/storefront-next-development-guidelines.md +++ b/docs/mcp/tools/sfnext-get-guidelines.md @@ -2,7 +2,7 @@ description: Get Storefront Next development guidelines and best practices for React Server Components, data loading, and framework constraints. --- -# storefront_next_development_guidelines +# sfnext_get_guidelines Returns critical architecture rules, coding standards, and best practices for building Storefront Next applications with React Server Components. @@ -10,7 +10,7 @@ Returns critical architecture rules, coding standards, and best practices for bu ## Overview -The `storefront_next_development_guidelines` tool provides essential development guidance for Storefront Next. It: +The `sfnext_get_guidelines` tool provides essential development guidance for Storefront Next. It: 1. Returns comprehensive guidelines by default (quick-reference plus key sections). 2. Supports retrieving specific topic sections on demand. @@ -98,7 +98,7 @@ The returned content includes: - Part of the [STOREFRONTNEXT](../toolsets#storefrontnext) toolset - Auto-enabled for Storefront Next projects -- [`storefront_next_page_designer_decorator`](./storefront-next-page-designer-decorator) - Add Page Designer decorators to components +- [`sfnext_add_page_designer_decorator`](./sfnext-add-page-designer-decorator) - Add Page Designer decorators to components ## See Also diff --git a/docs/mcp/tools/storefront-next-figma-to-component-workflow.md b/docs/mcp/tools/sfnext-start-figma-workflow.md similarity index 80% rename from docs/mcp/tools/storefront-next-figma-to-component-workflow.md rename to docs/mcp/tools/sfnext-start-figma-workflow.md index 51f0d99b..8ff8a7e4 100644 --- a/docs/mcp/tools/storefront-next-figma-to-component-workflow.md +++ b/docs/mcp/tools/sfnext-start-figma-workflow.md @@ -2,7 +2,7 @@ description: Workflow orchestrator for Figma-to-component conversion. Parses your Figma URL and guides you through design-to-component conversion. --- -# storefront_next_figma_to_component_workflow +# sfnext_start_figma_workflow Workflow orchestrator for converting Figma designs to Storefront Next components. Provide a Figma design URL to start the workflow, which extracts design data, analyzes your codebase, and produces component recommendations. @@ -47,15 +47,6 @@ The parser supports these URL formats: The `node-id` parameter accepts hyphen format (`1-2`) or colon format (`1:2`). The parser converts hyphens to colons for Figma MCP compatibility. -## Output - -The workflow returns a guide with extracted Figma parameters (`fileKey`, `nodeId`, and original URL). After the full workflow completes, you receive a component recommendation (REUSE/EXTEND/CREATE) with confidence score and a token mapping summary. - -**Example prompts:** -- βœ… "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 start the Figma-to-component workflow with a custom workflow file at /path/to/custom-workflow.md" - ## Usage Examples ### Basic Workflow Start @@ -78,11 +69,14 @@ Create a homepage from a Figma design, creating or updating components as needed 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. ``` +## Output + +The workflow returns a guide with extracted Figma parameters (`fileKey`, `nodeId`, and original URL). After the full workflow completes, you receive a component recommendation (REUSE/EXTEND/CREATE) with confidence score and a token mapping summary. ## Related Tools -- [`storefront_next_generate_component`](./storefront-next-generate-component) - Analyzes design and discovered components; recommends REUSE/EXTEND/CREATE -- [`storefront_next_map_tokens_to_theme`](./storefront-next-map-tokens-to-theme) - Maps Figma design tokens to theme variables +- [`sfnext_analyze_component`](./sfnext-analyze-component) - Analyzes design and discovered components; recommends REUSE/EXTEND/CREATE +- [`sfnext_match_tokens_to_theme`](./sfnext-match-tokens-to-theme) - Matches design tokens to theme variables - Part of the [STOREFRONTNEXT](../toolsets#storefrontnext) toolset - Auto-enabled for Storefront Next projects diff --git a/docs/mcp/toolsets.md b/docs/mcp/toolsets.md index b6df7b17..72459cd9 100644 --- a/docs/mcp/toolsets.md +++ b/docs/mcp/toolsets.md @@ -61,10 +61,10 @@ PWA Kit v3 development tools for building headless storefronts. | Tool | Description | Documentation | |------|-------------|---------------| -| [`pwakit_development_guidelines`](./tools/pwakit-development-guidelines) | Get PWA Kit v3 development guidelines and best practices | [View details](./tools/pwakit-development-guidelines) | +| [`pwakit_get_guidelines`](./tools/pwakit-get-guidelines) | Get PWA Kit v3 development guidelines and best practices | [View details](./tools/pwakit-get-guidelines) | | [`scapi_schemas_list`](./tools/scapi-schemas-list) | List or fetch SCAPI schemas (standard and custom). Use apiFamily: "custom" for custom APIs. | [View details](./tools/scapi-schemas-list) | -| [`scapi_custom_api_scaffold`](./tools/scapi-custom-api-scaffold) | Generate a new custom SCAPI endpoint (schema, api.json, script.js) in an existing cartridge. | [View details](./tools/scapi-custom-api-scaffold) | -| [`scapi_custom_apis_status`](./tools/scapi-custom-apis-status) | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. | [View details](./tools/scapi-custom-apis-status) | +| [`scapi_custom_api_generate_scaffold`](./tools/scapi-custom-api-generate-scaffold) | Generate a new custom SCAPI endpoint (schema, api.json, script.js) in an existing cartridge. | [View details](./tools/scapi-custom-api-generate-scaffold) | +| [`scapi_custom_apis_get_status`](./tools/scapi-custom-apis-get-status) | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. | [View details](./tools/scapi-custom-apis-get-status) | | [`mrt_bundle_push`](./tools/mrt-bundle-push) | Build, push bundle (optionally deploy) | [View details](./tools/mrt-bundle-push) | ## SCAPI @@ -80,8 +80,8 @@ Salesforce Commerce API discovery and exploration. | Tool | Description | Documentation | |------|-------------|---------------| | [`scapi_schemas_list`](./tools/scapi-schemas-list) | List or fetch SCAPI schemas (standard and custom). Use apiFamily: "custom" for custom APIs. | [View details](./tools/scapi-schemas-list) | -| [`scapi_custom_api_scaffold`](./tools/scapi-custom-api-scaffold) | Generate a new custom SCAPI endpoint (schema, api.json, script.js) in an existing cartridge. | [View details](./tools/scapi-custom-api-scaffold) | -| [`scapi_custom_apis_status`](./tools/scapi-custom-apis-status) | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. | [View details](./tools/scapi-custom-apis-status) | +| [`scapi_custom_api_generate_scaffold`](./tools/scapi-custom-api-generate-scaffold) | Generate a new custom SCAPI endpoint (schema, api.json, script.js) in an existing cartridge. | [View details](./tools/scapi-custom-api-generate-scaffold) | +| [`scapi_custom_apis_get_status`](./tools/scapi-custom-apis-get-status) | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. | [View details](./tools/scapi-custom-apis-get-status) | ## STOREFRONTNEXT @@ -95,22 +95,22 @@ Storefront Next development tools for building modern storefronts. | Tool | Description | Documentation | |------|-------------|---------------| -| [`storefront_next_development_guidelines`](./tools/storefront-next-development-guidelines) | Get Storefront Next development guidelines and best practices | [View details](./tools/storefront-next-development-guidelines) | -| [`storefront_next_figma_to_component_workflow`](./tools/storefront-next-figma-to-component-workflow) | Workflow orchestrator for Figma-to-component conversion. Parses Figma URL, returns step-by-step instructions for subsequent tool calls | [View details](./tools/storefront-next-figma-to-component-workflow) | -| [`storefront_next_generate_component`](./tools/storefront-next-generate-component) | Analyze Figma design and discovered components to recommend REUSE, EXTEND, or CREATE strategy | [View details](./tools/storefront-next-generate-component) | -| [`storefront_next_map_tokens_to_theme`](./tools/storefront-next-map-tokens-to-theme) | Map Figma design tokens to existing theme tokens in app.css with confidence scores and suggestions | [View details](./tools/storefront-next-map-tokens-to-theme) | -| [`storefront_next_page_designer_decorator`](./tools/storefront-next-page-designer-decorator) | Add Page Designer decorators to Storefront Next components | [View details](./tools/storefront-next-page-designer-decorator) | -| [`storefront_next_site_theming`](./tools/storefront-next-site-theming) | Get theming guidelines, questions, and WCAG color validation for Storefront Next | [View details](./tools/storefront-next-site-theming) | +| [`sfnext_get_guidelines`](./tools/sfnext-get-guidelines) | Get Storefront Next development guidelines and best practices | [View details](./tools/sfnext-get-guidelines) | +| [`sfnext_start_figma_workflow`](./tools/sfnext-start-figma-workflow) | Workflow orchestrator for Figma-to-component conversion. Parses Figma URL, returns step-by-step instructions for subsequent tool calls | [View details](./tools/sfnext-start-figma-workflow) | +| [`sfnext_analyze_component`](./tools/sfnext-analyze-component) | Analyze design and discovered components to recommend REUSE, EXTEND, or CREATE strategy | [View details](./tools/sfnext-analyze-component) | +| [`sfnext_match_tokens_to_theme`](./tools/sfnext-match-tokens-to-theme) | Map design tokens to existing theme tokens in app.css with confidence scores and suggestions | [View details](./tools/sfnext-match-tokens-to-theme) | +| [`sfnext_add_page_designer_decorator`](./tools/sfnext-add-page-designer-decorator) | Add Page Designer decorators to Storefront Next components | [View details](./tools/sfnext-add-page-designer-decorator) | +| [`sfnext_configure_theme`](./tools/sfnext-configure-theme) | Get theming guidelines, questions, and WCAG color validation for Storefront Next | [View details](./tools/sfnext-configure-theme) | | [`scapi_schemas_list`](./tools/scapi-schemas-list) | List or fetch SCAPI schemas (standard and custom). Use apiFamily: "custom" for custom APIs. | [View details](./tools/scapi-schemas-list) | -| [`scapi_custom_api_scaffold`](./tools/scapi-custom-api-scaffold) | Generate a new custom SCAPI endpoint (schema, api.json, script.js) in an existing cartridge. | [View details](./tools/scapi-custom-api-scaffold) | -| [`scapi_custom_apis_status`](./tools/scapi-custom-apis-status) | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. | [View details](./tools/scapi-custom-apis-status) | +| [`scapi_custom_api_generate_scaffold`](./tools/scapi-custom-api-generate-scaffold) | Generate a new custom SCAPI endpoint (schema, api.json, script.js) in an existing cartridge. | [View details](./tools/scapi-custom-api-generate-scaffold) | +| [`scapi_custom_apis_get_status`](./tools/scapi-custom-apis-get-status) | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. | [View details](./tools/scapi-custom-apis-get-status) | | [`mrt_bundle_push`](./tools/mrt-bundle-push) | Build, push bundle (optionally deploy) | [View details](./tools/mrt-bundle-push) | -**Figma-to-component tools** (`storefront_next_figma_to_component_workflow`, `storefront_next_generate_component`, `storefront_next_map_tokens_to_theme`) require additional setup: an external Figma MCP server and a valid Figma URL with `node-id`. See [Figma-to-Component Tools Setup](./figma-tools-setup) for prerequisites and configuration. +**Figma-to-component tools** (`sfnext_start_figma_workflow`, `sfnext_analyze_component`, `sfnext_match_tokens_to_theme`) require additional setup: an external Figma MCP server and a valid Figma URL with `node-id`. See [Figma-to-Component Tools Setup](./figma-tools-setup) for prerequisites and configuration. ## Tool Deduplication -Some tools appear in multiple toolsets (for example, `mrt_bundle_push`, `scapi_schemas_list`, `scapi_custom_api_scaffold`, `scapi_custom_apis_status`). When using multiple toolsets, tools are automatically deduplicated, so you'll only see each tool once. +Some tools appear in multiple toolsets (for example, `mrt_bundle_push`, `scapi_schemas_list`, `scapi_custom_api_generate_scaffold`, `scapi_custom_apis_get_status`). When using multiple toolsets, tools are automatically deduplicated, so you'll only see each tool once. ## Next Steps diff --git a/packages/b2c-dx-mcp/CONTRIBUTING.md b/packages/b2c-dx-mcp/CONTRIBUTING.md index e7b75064..d35c13df 100644 --- a/packages/b2c-dx-mcp/CONTRIBUTING.md +++ b/packages/b2c-dx-mcp/CONTRIBUTING.md @@ -65,7 +65,7 @@ npx mcp-inspector --cli node bin/dev.js --toolsets all --allow-non-ga-tools --me # Call a specific tool npx mcp-inspector --cli node bin/dev.js --toolsets all --allow-non-ga-tools \ --method tools/call \ - --tool-name storefront_next_page_designer_decorator + --tool-name sfnext_add_page_designer_decorator ``` ### JSON-RPC via stdin diff --git a/packages/b2c-dx-mcp/README.md b/packages/b2c-dx-mcp/README.md index d30a36ea..c57479d2 100644 --- a/packages/b2c-dx-mcp/README.md +++ b/packages/b2c-dx-mcp/README.md @@ -82,9 +82,9 @@ See the [Configuration Guide](https://salesforcecommercecloud.github.io/b2c-deve |---------|-------|------| | CARTRIDGES | `cartridge_deploy` | [toolsets#cartridges](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#cartridges) | | MRT | `mrt_bundle_push` | [toolsets#mrt](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#mrt) | -| SCAPI | `scapi_schemas_list`, `scapi_custom_apis_status`, `scapi_customapi_scaffold` | [toolsets#scapi](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#scapi) | -| STOREFRONTNEXT | `storefront_next_development_guidelines`, `storefront_next_page_designer_decorator`, `storefront_next_site_theming`, `storefront_next_figma_to_component_workflow`, `storefront_next_generate_component`, `storefront_next_map_tokens_to_theme` | [toolsets#storefrontnext](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#storefrontnext) | -| PWAV3 | `pwakit_development_guidelines` + SCAPI tools | [toolsets#pwav3](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#pwav3) | +| SCAPI | `scapi_schemas_list`, `scapi_custom_apis_get_status`, `scapi_custom_api_generate_scaffold` | [toolsets#scapi](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#scapi) | +| STOREFRONTNEXT | `sfnext_get_guidelines`, `sfnext_add_page_designer_decorator`, `sfnext_configure_theme`, `sfnext_start_figma_workflow`, `sfnext_analyze_component`, `sfnext_match_tokens_to_theme` | [toolsets#storefrontnext](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#storefrontnext) | +| PWAV3 | `pwakit_get_guidelines` + SCAPI tools | [toolsets#pwav3](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#pwav3) | ### cartridge_deploy @@ -107,62 +107,62 @@ List or fetch SCAPI schemas (standard and custom). [Details](https://salesforcec - "Use the MCP tool to list all SCAPI schemas." - "Use the MCP tool to get the OpenAPI schema for shopper-baskets v1." -### scapi_custom_apis_status +### scapi_custom_apis_get_status -Get custom API endpoint registration status. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/scapi-custom-apis-status) +Get custom API endpoint registration status. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/scapi-custom-apis-get-status) - "Use the MCP tool to list custom API endpoints on my instance." - "Use the MCP tool to show which custom APIs are active vs not registered." -### scapi_customapi_scaffold +### scapi_custom_api_generate_scaffold -Generate new custom SCAPI endpoint in a cartridge. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/scapi-custom-api-scaffold) +Generate new custom SCAPI endpoint in a cartridge. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/scapi-custom-api-generate-scaffold) - "Use the MCP tool to scaffold a new custom API named my-products." - "Use the MCP tool to create a custom admin API called customer-trips." -### storefront_next_development_guidelines +### sfnext_get_guidelines -Get Storefront Next guidelines and best practices. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/storefront-next-development-guidelines) +Get Storefront Next guidelines and best practices. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-get-guidelines) - "Use the MCP tool to show me critical Storefront Next rules." - "Use the MCP tool to get data-fetching and component patterns." -### storefront_next_page_designer_decorator +### sfnext_add_page_designer_decorator -Add Page Designer decorators to components. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/storefront-next-page-designer-decorator) +Add Page Designer decorators to components. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-add-page-designer-decorator) - "Use the MCP tool to add Page Designer decorators to my component." -### storefront_next_site_theming +### sfnext_configure_theme -Get theming guidelines, questions, and WCAG color validation for Storefront Next. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/storefront-next-site-theming) +Get theming guidelines, questions, and WCAG color validation for Storefront Next. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-configure-theme) - "Use the MCP tool to help me apply my brand colors to my Storefront Next site." - "Use the MCP tool to validate my color combinations for accessibility." -### storefront_next_figma_to_component_workflow +### sfnext_start_figma_workflow -Workflow orchestrator for Figma-to-component conversion. Parses Figma URL, returns step-by-step instructions for subsequent tool calls. Requires external Figma MCP server. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/storefront-next-figma-to-component-workflow) β€” [Figma Setup](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/figma-tools-setup) +Workflow orchestrator for Figma-to-component conversion. Parses Figma URL, returns step-by-step instructions for subsequent tool calls. Requires external Figma MCP server. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-start-figma-workflow) β€” [Figma Setup](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/figma-tools-setup) - "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]" -### storefront_next_generate_component +### sfnext_analyze_component -Analyze Figma design and discovered components to recommend REUSE, EXTEND, or CREATE strategy. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/storefront-next-generate-component) +Analyze design and discovered components to recommend REUSE, EXTEND, or CREATE strategy. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-analyze-component) - "Use the MCP tool to analyze the Figma design and recommend whether to reuse, extend, or create a component." -### storefront_next_map_tokens_to_theme +### sfnext_match_tokens_to_theme -Map Figma design tokens to existing theme tokens in app.css with confidence scores and suggestions. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/storefront-next-map-tokens-to-theme) +Map design tokens to existing theme tokens in app.css with confidence scores and suggestions. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-match-tokens-to-theme) - "Use the MCP tool to map these Figma design tokens to my theme." -### pwakit_development_guidelines +### pwakit_get_guidelines -Get PWA Kit v3 guidelines. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/pwakit-development-guidelines) +Get PWA Kit v3 guidelines. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/pwakit-get-guidelines) - "Use the MCP tool to get PWA Kit development guidelines." diff --git a/packages/b2c-dx-mcp/content/sfnext/page-designer.md b/packages/b2c-dx-mcp/content/sfnext/page-designer.md index 74021bf4..54d267c8 100644 --- a/packages/b2c-dx-mcp/content/sfnext/page-designer.md +++ b/packages/b2c-dx-mcp/content/sfnext/page-designer.md @@ -35,7 +35,7 @@ To add a new content page: define a page type and ID in Commerce Cloud, then in - **Add a metadata class** with `@Component('typeId', { name, description })` and `@AttributeDefinition()` (and optionally `@AttributeDefinition({ type: 'image' })`, `type: 'url'`, etc.) for each prop you want editable in Page Designer. Use `@RegionDefinition([...])` if the component has nested regions (e.g. a grid with slots). - **Implement the React component** so it accepts those props (and strips Page Designer–only props like `component`, `page`, `componentData`, `designMetadata` before spreading to the DOM). If the component needs server data (e.g. products for a carousel), export a `loader({ componentData, context })` and optionally a `fallback` component; the registry calls the loader during `collectComponentDataPromises` and passes resolved data as the `data` prop. -- **Use the MCP tool `storefront_next_page_designer_decorator`** to generate decorators instead of writing them by hand. Example components: `components/hero/index.tsx`, `components/content-card/index.tsx`, `components/product-carousel/index.tsx`. +- **Use the MCP tool `sfnext_add_page_designer_decorator`** to generate decorators instead of writing them by hand. Example components: `components/hero/index.tsx`, `components/content-card/index.tsx`, `components/product-carousel/index.tsx`. ### After changes @@ -50,29 +50,21 @@ To add a new content page: define a page type and ID in Commerce Cloud, then in Use the **B2C DX MCP server** for Page Designer work instead of hand-writing decorators and metadata. Configure the B2C DX MCP server in your IDE (e.g. in MCP settings) so these tools are available. -### 1. `storefront_next_page_designer_decorator` (STOREFRONTNEXT toolset) +### 1. `sfnext_add_page_designer_decorator` (STOREFRONTNEXT toolset) Adds Page Designer decorators to an existing React component so it can be used in Business Manager. The tool analyzes the component, picks suitable props, infers types (e.g. `*Url`/`*Link` β†’ url, `*Image` β†’ image, `is*`/`show*` β†’ boolean), and generates `@Component('typeId', { name, description })`, `@AttributeDefinition()` on a metadata class, and optionally `@RegionDefinition([...])` for nested regions. It skips complex or UI-only props (e.g. className, style, callbacks). - **Auto mode** (fast): Ask in your IDE: *"Add Page Designer support to [ComponentName] with autoMode"*. The tool runs in one turn with no prompts. - **Interactive mode** (control): Ask *"Add Page Designer support to [ComponentName]"* and answer questions about typeId, which props to expose, types, and optional nested regions. -### 2. `storefront_next_generate_page_designer_metadata` (STOREFRONTNEXT toolset) - -Generates Page Designer metadata JSON from decorated components, page types, and aspects. Writes files under the cartridge experience folder (e.g. `cartridges/app_storefrontnext_base/cartridge/experience/`). Use after adding or changing decorators so Business Manager has up-to-date component and page-type definitions. - -- **Full scan**: Run with no file list to process the whole project. -- **Incremental**: Pass specific file paths to regenerate only those components. -- **Dry run**: Use `dryRun: true` to see what would be generated without writing files. - -### 3. `cartridge_deploy` (CARTRIDGES toolset) +### 2. `cartridge_deploy` (CARTRIDGES toolset) Packages the cartridge, uploads it to Commerce Cloud via WebDAV, and unpacks it on the server. Requires Commerce Cloud credentials (e.g. `dw.json` or explicit config). Use after generating metadata so the new/updated metadata is available in Business Manager. ### Typical workflow -1. **`storefront_next_page_designer_decorator`** β€” Add decorators to the component (use autoMode for a quick first pass). -2. **`storefront_next_generate_page_designer_metadata`** β€” Generate metadata JSON so the component and regions appear in Page Designer. +1. **`sfnext_add_page_designer_decorator`** β€” Add decorators to the component (use autoMode for a quick first pass). +2. **Rebuild** β€” The static registry is auto-generated at build time by the staticRegistry Vite plugin. 3. **`cartridge_deploy`** β€” Deploy to Commerce Cloud so merchants can use the component in Business Manager. ## Best Practices @@ -81,6 +73,6 @@ Packages the cartridge, uploads it to Commerce Cloud via WebDAV, and unpacks it 2. **Use registry for components**: Register all Page Designer components with proper `typeId` 3. **Handle design mode**: Adapt UI when `pageDesignerMode` is `'EDIT'` or `'PREVIEW'` 4. **Rebuild after registry changes**: Static registry is generated at build time -5. **Use MCP tools**: Leverage `storefront_next_page_designer_decorator` and `storefront_next_generate_page_designer_metadata` for faster development +5. **Use MCP tools**: Leverage `sfnext_add_page_designer_decorator` for faster development **Reference:** See README.md for complete Page Designer documentation and MCP tool setup. diff --git a/packages/b2c-dx-mcp/content/sfnext/quick-reference.md b/packages/b2c-dx-mcp/content/sfnext/quick-reference.md index d5feb071..2f09def0 100644 --- a/packages/b2c-dx-mcp/content/sfnext/quick-reference.md +++ b/packages/b2c-dx-mcp/content/sfnext/quick-reference.md @@ -196,7 +196,7 @@ import { Card } from '@/components/ui/card'; ## πŸ” Get Detailed Guidelines -Use the `storefront_next_development_guidelines` MCP tool with specific sections: +Use the `sfnext_get_guidelines` MCP tool with specific sections: ```json { diff --git a/packages/b2c-dx-mcp/src/tools/pwav3/pwa-kit-development-guidelines.ts b/packages/b2c-dx-mcp/src/tools/pwav3/pwa-kit-development-guidelines.ts index 67fe7fe7..02bc7b8a 100644 --- a/packages/b2c-dx-mcp/src/tools/pwav3/pwa-kit-development-guidelines.ts +++ b/packages/b2c-dx-mcp/src/tools/pwav3/pwa-kit-development-guidelines.ts @@ -118,7 +118,7 @@ const DEFAULT_SECTIONS: SectionKey[] = ['quick-reference', 'components', 'data-f export function createDeveloperGuidelinesTool(loadServices: () => Promise | Services): McpTool { return createToolAdapter( { - name: 'pwakit_development_guidelines', + name: 'pwakit_get_guidelines', description: 'ESSENTIAL FIRST STEP for PWA Kit v3 development. Returns critical architecture rules, coding standards, and best practices. ' + 'Use this tool FIRST before writing any PWA Kit code to understand non-negotiable patterns for React components, ' + diff --git a/packages/b2c-dx-mcp/src/tools/scapi/index.ts b/packages/b2c-dx-mcp/src/tools/scapi/index.ts index 7e919414..30580d87 100644 --- a/packages/b2c-dx-mcp/src/tools/scapi/index.ts +++ b/packages/b2c-dx-mcp/src/tools/scapi/index.ts @@ -16,8 +16,8 @@ import type {McpTool} from '../../utils/index.js'; import type {Services} from '../../services.js'; import {createScapiSchemasListTool} from './scapi-schemas-list.js'; -import {createScapiCustomApisStatusTool} from './scapi-custom-apis-status.js'; -import {createScaffoldCustomApiTool} from './scapi-custom-api-scaffold.js'; +import {createScapiCustomApisStatusTool} from './scapi-custom-apis-get-status.js'; +import {createScaffoldCustomApiTool} from './scapi-custom-api-generate-scaffold.js'; /** * Creates all tools for the SCAPI toolset. diff --git a/packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-api-scaffold.ts b/packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-api-generate-scaffold.ts similarity index 96% rename from packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-api-scaffold.ts rename to packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-api-generate-scaffold.ts index 50d6f80f..0a9f7e55 100644 --- a/packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-api-scaffold.ts +++ b/packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-api-generate-scaffold.ts @@ -5,12 +5,12 @@ */ /** - * SCAPI Custom API Scaffold tool. + * SCAPI Custom API Generate Scaffold tool. * * Generates a new custom SCAPI endpoint using the SDK's custom-api scaffold * (schema.yaml, api.json, script.js). * - * @module tools/scapi/scapi-custom-api-scaffold + * @module tools/scapi/scapi-custom-api-generate-scaffold */ import {z} from 'zod'; @@ -35,7 +35,7 @@ export interface ScaffoldCustomApiExecuteOverrides { } /** - * Input schema for scapi_custom_api_scaffold tool. + * Input schema for scapi_custom_api_generate_scaffold tool. * Parameters match the custom-api scaffold: apiName, apiType, cartridgeName, etc. */ interface ScaffoldCustomApiInput { @@ -54,7 +54,7 @@ interface ScaffoldCustomApiInput { } /** - * Output schema for scapi_custom_api_scaffold tool. + * Output schema for scapi_custom_api_generate_scaffold tool. */ interface ScaffoldCustomApiOutput { scaffold: string; @@ -190,7 +190,7 @@ export async function executeScaffoldCustomApi( } /** - * Creates the scapi_custom_api_scaffold tool. + * Creates the scapi_custom_api_generate_scaffold tool. * * Uses @salesforce/b2c-tooling-sdk scaffold: registry, resolveScaffoldParameters, * resolveOutputDirectory, generateFromScaffold. cartridgeName must be a cartridge @@ -205,7 +205,7 @@ export function createScaffoldCustomApiTool( ): McpTool { return createToolAdapter( { - name: 'scapi_custom_api_scaffold', + name: 'scapi_custom_api_generate_scaffold', description: `Generate a new custom SCAPI endpoint (OAS 3.0 schema, api.json, script.js) in an existing cartridge. \ Required: apiName (kebab-case). Optional: cartridgeName (defaults to first cartridge found in project), apiType (shopper|admin) default to shopper, \ apiDescription, projectRoot, outputDir.`, diff --git a/packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-apis-status.ts b/packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-apis-get-status.ts similarity index 96% rename from packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-apis-status.ts rename to packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-apis-get-status.ts index 44e8f92f..9bbabeee 100644 --- a/packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-apis-status.ts +++ b/packages/b2c-dx-mcp/src/tools/scapi/scapi-custom-apis-get-status.ts @@ -10,7 +10,7 @@ * Mirrors CLI: b2c scapi custom status. All CLI flags are supported; let the agent decide what to use. * Returns raw endpoints from the API (no roll-up). Remote only. * - * @module tools/scapi/scapi-custom-apis-status + * @module tools/scapi/scapi-custom-apis-get-status */ import {z} from 'zod'; @@ -94,7 +94,7 @@ function buildResponse( } /** - * Input schema for scapi_custom_apis_status tool. + * Input schema for scapi_custom_apis_get_status tool. * Mirrors b2c scapi custom status (--status, --group-by, --columns). * Use columns parameter to request all fields or specific fields. */ @@ -108,7 +108,7 @@ interface CustomListInput { } /** - * Output schema for scapi_custom_apis_status tool. + * Output schema for scapi_custom_apis_get_status tool. */ interface CustomListOutput { /** Raw endpoints (one per site). When groupBy is set, use "groups" instead. */ @@ -123,7 +123,7 @@ interface CustomListOutput { } /** - * Creates the scapi_custom_apis_status tool. + * Creates the scapi_custom_apis_get_status tool. * * Mirrors CLI: b2c scapi custom status. All flags supported; agent chooses what to use. * See: https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/custom-apis.html#b2c-scapi-custom-status @@ -131,7 +131,7 @@ interface CustomListOutput { export function createScapiCustomApisStatusTool(loadServices: () => Promise | Services): McpTool { return createToolAdapter( { - name: 'scapi_custom_apis_status', + name: 'scapi_custom_apis_get_status', description: `List Custom SCAPI endpoint registration status (active/not_registered). Returns one row per endpoint per site. For schemas, use scapi_schemas_list with apiFamily: "custom". Use cases: Check endpoint status, verify deployment, get per-site details. Use status: "active" to filter, groupBy: "site" to group, columns: "field1,field2" for specific fields, or omit columns for defaults. diff --git a/packages/b2c-dx-mcp/src/tools/scapi/scapi-schemas-list.ts b/packages/b2c-dx-mcp/src/tools/scapi/scapi-schemas-list.ts index 4c060969..3dfddad9 100644 --- a/packages/b2c-dx-mcp/src/tools/scapi/scapi-schemas-list.ts +++ b/packages/b2c-dx-mcp/src/tools/scapi/scapi-schemas-list.ts @@ -296,7 +296,7 @@ export function createScapiSchemasListTool(loadServices: () => Promise return createToolAdapter( { name: 'scapi_schemas_list', - description: `List or fetch SCAPI schema metadata and OpenAPI specs for standard SCAPI (Shop/Admin/Shopper) and custom APIs (apiFamily: "custom"). For endpoint registration status, use scapi_custom_apis_status. + description: `List or fetch SCAPI schema metadata and OpenAPI specs for standard SCAPI (Shop/Admin/Shopper) and custom APIs (apiFamily: "custom"). For endpoint registration status, use scapi_custom_apis_get_status. **Modes:** - **List (discovery):** Omit includeSchemas or any identifier. Returns metadata: schemas[], total, availableApiFamilies/Names/Versions. diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/README.md b/packages/b2c-dx-mcp/src/tools/storefrontnext/README.md index 6726789d..d4a290e2 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/README.md +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/README.md @@ -4,7 +4,7 @@ MCP tools for Storefront Next development with React Server Components. ## Tools -### `storefront_next_development_guidelines` +### `sfnext_get_guidelines` **ESSENTIAL FIRST STEP** for Storefront Next development. Returns critical architecture rules, coding standards, and best practices. Use this tool FIRST before writing any Storefront Next code to understand non-negotiable patterns for React Server Components, data loading, and framework constraints. @@ -52,12 +52,12 @@ MCP tools for Storefront Next development with React Server Components. ```json // Default - returns comprehensive guidelines (quick-reference + data-fetching + components + testing) { - "name": "storefront_next_development_guidelines" + "name": "sfnext_get_guidelines" } // Single section { - "name": "storefront_next_development_guidelines", + "name": "sfnext_get_guidelines", "arguments": { "sections": ["data-fetching"] } @@ -65,7 +65,7 @@ MCP tools for Storefront Next development with React Server Components. // Multiple related sections { - "name": "storefront_next_development_guidelines", + "name": "sfnext_get_guidelines", "arguments": { "sections": ["data-fetching", "components", "performance"] } @@ -73,14 +73,14 @@ MCP tools for Storefront Next development with React Server Components. // All sections { - "name": "storefront_next_development_guidelines", + "name": "sfnext_get_guidelines", "arguments": { "sections": ["quick-reference", "data-fetching", "state-management", "auth", "config", "i18n", "components", "styling", "page-designer", "performance", "testing", "extensions", "pitfalls"] } } ``` -### `storefront_next_page_designer_decorator` +### `sfnext_add_page_designer_decorator` Add Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDefinition`) to existing React components for Storefront Next. @@ -108,7 +108,7 @@ Add Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDefi ```json // Auto mode (quick setup) { - "name": "storefront_next_page_designer_decorator", + "name": "sfnext_add_page_designer_decorator", "arguments": { "component": "ProductCard", "autoMode": true @@ -117,7 +117,7 @@ Add Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDefi // Interactive mode (step-by-step) { - "name": "storefront_next_page_designer_decorator", + "name": "sfnext_add_page_designer_decorator", "arguments": { "component": "Hero", "conversationContext": { @@ -127,7 +127,7 @@ Add Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDefi } ``` -### `storefront_next_site_theming` +### `sfnext_configure_theme` **MANDATORY** before implementing any theming changes. Provides theming guidelines, questions, and automatic color contrast validation. Call this tool FIRST when the user requests theming (even if colors/fonts are provided). Never implement without calling it first. @@ -154,7 +154,7 @@ Add Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDefi ```json // First call - get guidelines and questions { - "name": "storefront_next_site_theming", + "name": "sfnext_configure_theme", "arguments": { "conversationContext": { "collectedAnswers": {"colors": [], "fonts": []} @@ -164,7 +164,7 @@ Add Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDefi // Validation call - after constructing colorMapping (colorMapping alone triggers validation) { - "name": "storefront_next_site_theming", + "name": "sfnext_configure_theme", "arguments": { "conversationContext": { "collectedAnswers": { @@ -184,7 +184,7 @@ Add Page Designer decorators (`@Component`, `@AttributeDefinition`, `@RegionDefi ### Architecture -#### `storefront_next_development_guidelines` +#### `sfnext_get_guidelines` The tool loads content from markdown files in the `content/` directory: @@ -217,7 +217,7 @@ Each section markdown file includes: βœ… **Always Current**: Content loaded from markdown files (easy to update) βœ… **Comprehensive Default**: Returns key sections by default for immediate value -#### `storefront_next_page_designer_decorator` +#### `sfnext_add_page_designer_decorator` The tool uses a rule-based architecture with TypeScript template literals for generating Page Designer decorators: @@ -255,7 +255,7 @@ Component discovery uses the project directory resolved from `--project-director **See also**: [Detailed documentation](./page-designer-decorator/README.md) for complete usage guide, architecture details, and examples. -#### `storefront_next_site_theming` +#### `sfnext_configure_theme` The tool loads theming guidance from markdown files in `content/site-theming/` and runs automatic WCAG contrast validation when `colorMapping` is provided: diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/figma-to-component/index.ts b/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/figma-to-component/index.ts index 90e885b2..fcf83eb0 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/figma-to-component/index.ts +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/figma-to-component/index.ts @@ -252,7 +252,7 @@ function formatNextStepsReminder(): string { This tool has provided workflow instructions only. You MUST now execute ALL steps below. -**EXPECTED FINAL OUTPUT:** A recommendation with confidence score from generate_component tool AND a token mapping summary from map_tokens_to_theme tool. +**EXPECTED FINAL OUTPUT:** A recommendation with confidence score from sfnext_analyze_component tool AND a token mapping summary from sfnext_match_tokens_to_theme tool. ### Step 1: Fetch Figma Design Data (Parallel Calls) Call these Figma MCP tools with the parameters above: @@ -268,7 +268,7 @@ Use your tools to find existing components: - Score each match (0-100) based on similarity ### Step 3: Analyze Component Strategy (CRITICAL - DO NOT SKIP) -You MUST call \`generate_component\` tool with: +You MUST call \`sfnext_analyze_component\` tool with: - figmaMetadata (from step 1, or empty string if not fetched) - figmaCode (from step 1) - componentName (extracted from Figma) @@ -277,14 +277,14 @@ You MUST call \`generate_component\` tool with: This tool returns the recommendation with confidence score that MUST be shown to the user. ### Step 4: Map Design Tokens (CRITICAL - DO NOT SKIP) -You MUST call \`map_tokens_to_theme\` tool with tokens extracted from Figma design. +You MUST call \`sfnext_match_tokens_to_theme\` tool with tokens extracted from Figma design. This tool returns the token mapping summary that MUST be shown to the user. ### Step 5: Implement After showing the recommendation and token mapping to the user, wait for approval then implement the code changes. Use the downloaded asset paths from Step 1 for any img src or imageUrl propsβ€”do not use placeholder paths. -**DO NOT STOP until you have called generate_component AND map_tokens_to_theme and shown their outputs to the user.** +**DO NOT STOP until you have called sfnext_analyze_component AND sfnext_match_tokens_to_theme and shown their outputs to the user.** `; } @@ -329,7 +329,7 @@ export function generateWorkflowResponse(figmaUrl: string, workflowFilePath?: st } /** - * Creates the storefront_next_figma_to_component_workflow MCP tool. + * Creates the sfnext_start_figma_workflow MCP tool. * * @param loadServices - Function that loads configuration and returns Services instance * @returns MCP tool for workflow orchestration @@ -337,14 +337,14 @@ export function generateWorkflowResponse(figmaUrl: string, workflowFilePath?: st export function createFigmaToComponentTool(loadServices: () => Promise | Services): McpTool { return createToolAdapter( { - name: 'storefront_next_figma_to_component_workflow', + name: 'sfnext_start_figma_workflow', description: 'WORKFLOW ORCHESTRATOR: Call this tool FIRST when converting Figma designs. ' + 'Parses Figma URL to extract fileKey and nodeId, returns step-by-step workflow instructions ' + 'and parameters for subsequent tool calls. ' + 'CRITICAL: This is only the FIRST step. After calling this tool, you MUST continue executing ' + 'the complete workflow: 1) Call Figma MCP tools, 2) Discover similar components, ' + - '3) Call generate_component tool, 4) Call map_tokens_to_theme tool, ' + + '3) Call sfnext_analyze_component tool, 4) Call sfnext_match_tokens_to_theme tool, ' + '5) Show both outputs to the user then implement the recommended approach.', toolsets: ['STOREFRONTNEXT'], isGA: false, diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/generate-component/index.ts b/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/generate-component/index.ts index 5a00431a..e2e126a5 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/generate-component/index.ts +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/generate-component/index.ts @@ -126,7 +126,7 @@ export function generateComponentRecommendation(input: GenerateComponentInput): } /** - * Creates the storefront_next_generate_component MCP tool. + * Creates the sfnext_analyze_component MCP tool. * * @param loadServices - Function that loads configuration and returns Services instance * @returns MCP tool for component analysis and recommendation @@ -134,7 +134,7 @@ export function generateComponentRecommendation(input: GenerateComponentInput): export function createGenerateComponentTool(loadServices: () => Promise | Services): McpTool { return createToolAdapter( { - name: 'storefront_next_generate_component', + name: 'sfnext_analyze_component', description: 'Analyzes Figma design and discovered components to recommend component generation strategy. ' + 'Workflow: 1) Discover similar components using Glob/Grep/Read tools, ' + diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/map-tokens/index.ts b/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/map-tokens/index.ts index af28f155..33dada57 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/map-tokens/index.ts +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/figma/map-tokens/index.ts @@ -252,7 +252,7 @@ export function mapFigmaTokensToTheme(args: MapTokensToThemeInput, workspaceRoot } /** - * Creates the storefront_next_map_tokens_to_theme MCP tool. + * Creates the sfnext_match_tokens_to_theme MCP tool. * * @param loadServices - Function that loads configuration and returns Services instance * @returns MCP tool for token mapping @@ -260,7 +260,7 @@ export function mapFigmaTokensToTheme(args: MapTokensToThemeInput, workspaceRoot export function createMapTokensToThemeTool(loadServices: () => Promise | Services): McpTool { return createToolAdapter( { - name: 'storefront_next_map_tokens_to_theme', + name: 'sfnext_match_tokens_to_theme', description: 'Maps Figma design tokens to existing StorefrontNext theme tokens in app.css. ' + 'Analyzes Figma design tokens (colors, spacing, radius, etc.) and finds exact matches, ' + diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/index.ts b/packages/b2c-dx-mcp/src/tools/storefrontnext/index.ts index 6cd5a5db..fe0da9c8 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/index.ts +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/index.ts @@ -10,12 +10,12 @@ * This toolset provides MCP tools for Storefront Next development. * * **Implemented Tools:** - * - `storefront_next_development_guidelines` - Get development guidelines and best practices - * - `storefront_next_page_designer_decorator` - Add Page Designer decorators to React components - * - `storefront_next_site_theming` - Get theming guidelines, questions, and validation - * - `storefront_next_figma_to_component_workflow` - Convert Figma to components - * - `storefront_next_generate_component` - Generate new components - * - `storefront_next_map_tokens_to_theme` - Map design tokens + * - `sfnext_get_guidelines` - Get development guidelines and best practices + * - `sfnext_add_page_designer_decorator` - Add Page Designer decorators to React components + * - `sfnext_configure_theme` - Get theming guidelines, questions, and validation + * - `sfnext_start_figma_workflow` - Convert Figma to components + * - `sfnext_analyze_component` - Analyze design and recommend REUSE/EXTEND/CREATE + * - `sfnext_match_tokens_to_theme` - Match design tokens to theme * * Note: mrt_bundle_push is defined in the MRT toolset and appears in STOREFRONTNEXT. * diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/README.md b/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/README.md index e62d5bcb..fddd981a 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/README.md +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/README.md @@ -41,19 +41,19 @@ page-designer-decorator/ ```bash # By component name (automatically finds the file) -storefront_next_page_designer_decorator({ +sfnext_add_page_designer_decorator({ component: "ProductItem", autoMode: true }) # Interactive mode -storefront_next_page_designer_decorator({ +sfnext_add_page_designer_decorator({ component: "ProductTile", conversationContext: { step: "analyze" } }) # With custom search paths (for unusual locations) -storefront_next_page_designer_decorator({ +sfnext_add_page_designer_decorator({ component: "ProductItem", searchPaths: ["packages/retail/src", "app/features"], autoMode: true @@ -64,7 +64,7 @@ storefront_next_page_designer_decorator({ ```bash # If you prefer to specify the exact path -storefront_next_page_designer_decorator({ +sfnext_add_page_designer_decorator({ component: "src/components/ProductItem.tsx", autoMode: true }) diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/index.ts b/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/index.ts index 293d3372..dab0f34e 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/index.ts +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/index.ts @@ -629,7 +629,7 @@ function handleAutoMode(args: PageDesignerDecoratorInput, workspaceRoot: string) */ export function createPageDesignerDecoratorTool(loadServices: () => Promise | Services): McpTool { return { - name: 'storefront_next_page_designer_decorator', + name: 'sfnext_add_page_designer_decorator', description: 'Adds Page Designer decorators (@Component, @AttributeDefinition, @RegionDefinition) to React components. ' + diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/templates/decorator-generator.ts b/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/templates/decorator-generator.ts index ac3b6384..1aca75a5 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/templates/decorator-generator.ts +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/templates/decorator-generator.ts @@ -344,7 +344,7 @@ function generateRegionDefinition(context: MetadataContext): string { * **Generated code must be:** * - Added to the component file (after imports, before component) * - Compiled with TypeScript - * - Used by `generate_page_designer_metadata` tool to create JSON metadata + * - Used by the staticRegistry Vite plugin to generate the component registry * * @param context - Complete metadata context * @returns TypeScript code string ready to paste into component file diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/sfnext-development-guidelines.ts b/packages/b2c-dx-mcp/src/tools/storefrontnext/sfnext-development-guidelines.ts index f553f66d..39382aa3 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/sfnext-development-guidelines.ts +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/sfnext-development-guidelines.ts @@ -106,7 +106,7 @@ const DEFAULT_SECTIONS: SectionKey[] = ['quick-reference', 'data-fetching', 'com export function createDeveloperGuidelinesTool(loadServices: () => Promise | Services): McpTool { return createToolAdapter( { - name: 'storefront_next_development_guidelines', + name: 'sfnext_get_guidelines', description: 'ESSENTIAL FIRST STEP for Storefront Next development. Returns critical architecture rules, coding standards, and best practices. ' + 'Use this tool FIRST before writing any Storefront Next code to understand non-negotiable patterns for React Server Components, ' + diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/site-theming/README.md b/packages/b2c-dx-mcp/src/tools/storefrontnext/site-theming/README.md index 6f746590..4fa92feb 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/site-theming/README.md +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/site-theming/README.md @@ -49,7 +49,7 @@ Content files (in `packages/b2c-dx-mcp/content/site-theming/`): ```json // First call - get guidelines and questions { - "name": "storefront_next_site_theming", + "name": "sfnext_configure_theme", "arguments": { "conversationContext": { "collectedAnswers": {"colors": [], "fonts": []} @@ -59,7 +59,7 @@ Content files (in `packages/b2c-dx-mcp/content/site-theming/`): // Validation call - after constructing colorMapping { - "name": "storefront_next_site_theming", + "name": "sfnext_configure_theme", "arguments": { "conversationContext": { "collectedAnswers": { diff --git a/packages/b2c-dx-mcp/src/tools/storefrontnext/site-theming/index.ts b/packages/b2c-dx-mcp/src/tools/storefrontnext/site-theming/index.ts index 80ead1a5..77f9574c 100644 --- a/packages/b2c-dx-mcp/src/tools/storefrontnext/site-theming/index.ts +++ b/packages/b2c-dx-mcp/src/tools/storefrontnext/site-theming/index.ts @@ -44,7 +44,7 @@ export type { export function createSiteThemingTool(loadServices: () => Promise | Services): McpTool { return createToolAdapter( { - name: 'storefront_next_site_theming', + name: 'sfnext_configure_theme', description: '⚠️ MANDATORY: Call this tool FIRST before implementing any theming changes. ' + 'Provides theming guidelines, questions, and automatic validation. ' + diff --git a/packages/b2c-dx-mcp/test/e2e/mcp-e2e.test.ts b/packages/b2c-dx-mcp/test/e2e/mcp-e2e.test.ts index ee642f8d..67a638e1 100644 --- a/packages/b2c-dx-mcp/test/e2e/mcp-e2e.test.ts +++ b/packages/b2c-dx-mcp/test/e2e/mcp-e2e.test.ts @@ -97,12 +97,15 @@ describe('MCP Server E2E', function () { it('filters tools by individual tool name', async () => { const client = new McpE2EClient({ - args: ['--tools', 'scapi_schemas_list,scapi_custom_apis_status', '--allow-non-ga-tools'], + args: ['--tools', 'scapi_schemas_list,scapi_custom_apis_get_status', '--allow-non-ga-tools'], }); await client.start(); const result = (await client.call('tools/list')) as {tools: Array<{name: string}>}; expect(result.tools).to.have.lengthOf(2); - expect(result.tools.map((t) => t.name).sort()).to.deep.equal(['scapi_custom_apis_status', 'scapi_schemas_list']); + expect(result.tools.map((t) => t.name).sort()).to.deep.equal([ + 'scapi_custom_apis_get_status', + 'scapi_schemas_list', + ]); await client.stop(); }); @@ -171,12 +174,12 @@ describe('MCP Server E2E', function () { it('returns proper error for invalid input when required param missing', async () => { const client = new McpE2EClient({ - args: ['--tools', 'storefront_next_page_designer_decorator', '--allow-non-ga-tools'], + args: ['--tools', 'sfnext_add_page_designer_decorator', '--allow-non-ga-tools'], }); await client.start(); try { await client.call('tools/call', { - name: 'storefront_next_page_designer_decorator', + name: 'sfnext_add_page_designer_decorator', arguments: {}, // missing required componentName etc. }); // May throw or return content with error @@ -204,7 +207,7 @@ describe('MCP Server E2E', function () { await client.start(); const result = (await client.call('tools/list')) as {tools: Array<{name: string}>}; const names = result.tools.map((t) => t.name); - expect(names.some((n) => n.includes('storefront_next') || n.includes('scapi'))).to.be.true; + expect(names.some((n) => n.includes('sfnext') || n.includes('scapi'))).to.be.true; await client.stop(); }); diff --git a/packages/b2c-dx-mcp/test/registry.test.ts b/packages/b2c-dx-mcp/test/registry.test.ts index 2d9819f5..ffaa5cf4 100644 --- a/packages/b2c-dx-mcp/test/registry.test.ts +++ b/packages/b2c-dx-mcp/test/registry.test.ts @@ -85,8 +85,8 @@ describe('registry', () => { const toolNames = registry.SCAPI.map((t) => t.name); expect(toolNames).to.include('scapi_schemas_list'); - expect(toolNames).to.include('scapi_custom_apis_status'); - expect(toolNames).to.include('scapi_custom_api_scaffold'); + expect(toolNames).to.include('scapi_custom_apis_get_status'); + expect(toolNames).to.include('scapi_custom_api_generate_scaffold'); }); it('should create STOREFRONTNEXT tools', () => { @@ -97,8 +97,8 @@ describe('registry', () => { expect(registry.STOREFRONTNEXT.length).to.be.greaterThan(0); const toolNames = registry.STOREFRONTNEXT.map((t) => t.name); - expect(toolNames).to.include('storefront_next_development_guidelines'); - expect(toolNames).to.include('storefront_next_page_designer_decorator'); + expect(toolNames).to.include('sfnext_get_guidelines'); + expect(toolNames).to.include('sfnext_add_page_designer_decorator'); // mrt_bundle_push should also appear in STOREFRONTNEXT (multi-toolset) expect(toolNames).to.include('mrt_bundle_push'); }); @@ -170,7 +170,7 @@ describe('registry', () => { expect(server.registeredTools).to.include('cartridge_deploy'); // Should not include tools exclusive to other toolsets - expect(server.registeredTools).to.not.include('scapi_custom_apis_status'); + expect(server.registeredTools).to.not.include('scapi_custom_apis_get_status'); }); it('should register tools from multiple toolsets', async () => { @@ -205,7 +205,7 @@ describe('registry', () => { expect(server.registeredTools).to.include('cartridge_deploy'); expect(server.registeredTools).to.include('mrt_bundle_push'); expect(server.registeredTools).to.include('scapi_schemas_list'); - expect(server.registeredTools).to.include('storefront_next_development_guidelines'); + expect(server.registeredTools).to.include('sfnext_get_guidelines'); }); it('should register individual tools via --tools flag', async () => { @@ -227,7 +227,7 @@ describe('registry', () => { const server = createMockServer(); const flags: StartupFlags = { toolsets: ['CARTRIDGES'], - tools: ['scapi_custom_apis_status'], + tools: ['scapi_custom_apis_get_status'], allowNonGaTools: true, }; @@ -237,7 +237,7 @@ describe('registry', () => { // Should include all CARTRIDGES tools expect(server.registeredTools).to.include('cartridge_deploy'); // Should also include the individual SCAPI tool - expect(server.registeredTools).to.include('scapi_custom_apis_status'); + expect(server.registeredTools).to.include('scapi_custom_apis_get_status'); // Should not include other SCAPI tools not in CARTRIDGES expect(server.registeredTools).to.not.include('scapi_schemas_list'); }); @@ -303,8 +303,8 @@ describe('registry', () => { // Auto-discovery always includes BASE_TOOLSET (SCAPI), even if no project type detected expect(server.registeredTools).to.include('scapi_schemas_list'); - expect(server.registeredTools).to.include('scapi_custom_apis_status'); - expect(server.registeredTools).to.include('scapi_custom_api_scaffold'); + expect(server.registeredTools).to.include('scapi_custom_apis_get_status'); + expect(server.registeredTools).to.include('scapi_custom_api_generate_scaffold'); }); it('should trigger auto-discovery when all individual tools are invalid', async () => { @@ -320,8 +320,8 @@ describe('registry', () => { // Auto-discovery always includes BASE_TOOLSET (SCAPI), even if no project type detected expect(server.registeredTools).to.include('scapi_schemas_list'); - expect(server.registeredTools).to.include('scapi_custom_apis_status'); - expect(server.registeredTools).to.include('scapi_custom_api_scaffold'); + expect(server.registeredTools).to.include('scapi_custom_apis_get_status'); + expect(server.registeredTools).to.include('scapi_custom_api_generate_scaffold'); }); it('should skip non-GA tools when allowNonGaTools is false', async () => { diff --git a/packages/b2c-dx-mcp/test/tools/pwav3/pwa-kit-development-guidelines.test.ts b/packages/b2c-dx-mcp/test/tools/pwav3/pwa-kit-development-guidelines.test.ts index 612f72a9..40387dfc 100644 --- a/packages/b2c-dx-mcp/test/tools/pwav3/pwa-kit-development-guidelines.test.ts +++ b/packages/b2c-dx-mcp/test/tools/pwav3/pwa-kit-development-guidelines.test.ts @@ -39,7 +39,7 @@ describe('tools/pwav3/pwa-kit-development-guidelines', () => { describe('tool metadata', () => { it('should have correct tool name', () => { const tool = createDeveloperGuidelinesTool(() => services); - expect(tool.name).to.equal('pwakit_development_guidelines'); + expect(tool.name).to.equal('pwakit_get_guidelines'); }); it('should have concise, action-oriented description', () => { diff --git a/packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-api-scaffold.test.ts b/packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-api-generate-scaffold.test.ts similarity index 97% rename from packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-api-scaffold.test.ts rename to packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-api-generate-scaffold.test.ts index ffafc156..3be3624e 100644 --- a/packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-api-scaffold.test.ts +++ b/packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-api-generate-scaffold.test.ts @@ -12,7 +12,7 @@ import path from 'node:path'; import { createScaffoldCustomApiTool, executeScaffoldCustomApi, -} from '../../../src/tools/scapi/scapi-custom-api-scaffold.js'; +} from '../../../src/tools/scapi/scapi-custom-api-generate-scaffold.js'; import {Services} from '../../../src/services.js'; import {createMockResolvedConfig} from '../../test-helpers.js'; import type {ToolResult} from '../../../src/utils/types.js'; @@ -48,7 +48,7 @@ interface ScaffoldOutput { error?: string; } -describe('tools/scapi/scapi-custom-api-scaffold', () => { +describe('tools/scapi/scapi-custom-api-generate-scaffold', () => { let services: Services; let tempDir: string; let loadServices: () => Services; @@ -68,11 +68,11 @@ describe('tools/scapi/scapi-custom-api-scaffold', () => { }); describe('createScaffoldCustomApiTool', () => { - it('should create scapi_custom_api_scaffold tool with correct metadata', () => { + it('should create scapi_custom_api_generate_scaffold tool with correct metadata', () => { const tool = createScaffoldCustomApiTool(loadServices); expect(tool).to.exist; - expect(tool.name).to.equal('scapi_custom_api_scaffold'); + expect(tool.name).to.equal('scapi_custom_api_generate_scaffold'); expect(tool.description).to.include('custom SCAPI'); expect(tool.description).to.include('apiName'); expect(tool.inputSchema).to.exist; diff --git a/packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-apis-status.test.ts b/packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-apis-get-status.test.ts similarity index 97% rename from packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-apis-status.test.ts rename to packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-apis-get-status.test.ts index ed314744..2bd1b4a7 100644 --- a/packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-apis-status.test.ts +++ b/packages/b2c-dx-mcp/test/tools/scapi/scapi-custom-apis-get-status.test.ts @@ -7,7 +7,7 @@ import {expect} from 'chai'; import {describe, it, beforeEach, afterEach} from 'mocha'; import {stub, restore, type SinonStub} from 'sinon'; -import {createScapiCustomApisStatusTool} from '../../../src/tools/scapi/scapi-custom-apis-status.js'; +import {createScapiCustomApisStatusTool} from '../../../src/tools/scapi/scapi-custom-apis-get-status.js'; import {Services} from '../../../src/services.js'; import {createMockResolvedConfig} from '../../test-helpers.js'; import type {CustomApisClient, CustomApisComponents} from '@salesforce/b2c-tooling-sdk/clients'; @@ -66,7 +66,7 @@ function createMockClientResponse(endpoints: CustomApiEndpoint[], activeCodeVers }; } -describe('tools/scapi/scapi-custom-apis-status', () => { +describe('tools/scapi/scapi-custom-apis-get-status', () => { let services: Services; let mockGet: SinonStub; @@ -93,11 +93,11 @@ describe('tools/scapi/scapi-custom-apis-status', () => { }); describe('createScapiCustomApisStatusTool', () => { - it('should create scapi_custom_apis_status tool with correct metadata', () => { + it('should create scapi_custom_apis_get_status tool with correct metadata', () => { const tool = createScapiCustomApisStatusTool(() => services); expect(tool).to.exist; - expect(tool.name).to.equal('scapi_custom_apis_status'); + expect(tool.name).to.equal('scapi_custom_apis_get_status'); expect(tool.description).to.include('Custom'); expect(tool.description).to.include('endpoint'); expect(tool.description).to.include('Custom'); diff --git a/packages/b2c-dx-mcp/test/tools/scapi/scapi-schemas-list.test.ts b/packages/b2c-dx-mcp/test/tools/scapi/scapi-schemas-list.test.ts index e82faf81..06ff8bc2 100644 --- a/packages/b2c-dx-mcp/test/tools/scapi/scapi-schemas-list.test.ts +++ b/packages/b2c-dx-mcp/test/tools/scapi/scapi-schemas-list.test.ts @@ -61,7 +61,7 @@ describe('tools/scapi/scapi-schemas-list', () => { expect(tool.description).to.include('SCAPI'); expect(tool.description).to.include('List'); expect(tool.description).to.include('Fetch'); - expect(tool.description).to.include('scapi_custom_apis_status'); + expect(tool.description).to.include('scapi_custom_apis_get_status'); expect(tool.inputSchema).to.exist; expect(tool.handler).to.be.a('function'); expect(tool.toolsets).to.deep.equal(['PWAV3', 'SCAPI', 'STOREFRONTNEXT']); diff --git a/packages/b2c-dx-mcp/test/tools/storefrontnext/figma/README.md b/packages/b2c-dx-mcp/test/tools/storefrontnext/figma/README.md index 39cac7f1..35172f2b 100644 --- a/packages/b2c-dx-mcp/test/tools/storefrontnext/figma/README.md +++ b/packages/b2c-dx-mcp/test/tools/storefrontnext/figma/README.md @@ -42,7 +42,7 @@ mcp-inspector node --conditions development bin/dev.js --toolsets STOREFRONTNEXT Then in the inspector: 1. Click **Connect** -2. Click **List Tools** - you should see `storefront_next_figma_to_component_workflow`, `storefront_next_generate_component`, `storefront_next_map_tokens_to_theme` +2. Click **List Tools** - you should see `sfnext_start_figma_workflow`, `sfnext_analyze_component`, `sfnext_match_tokens_to_theme` 3. Click on each tool to test with sample inputs ### 3. CLI Testing @@ -58,20 +58,20 @@ npx mcp-inspector --cli node bin/run.js --toolsets STOREFRONTNEXT --allow-non-ga # Call figma-to-component workflow npx mcp-inspector --cli node bin/run.js --toolsets STOREFRONTNEXT --allow-non-ga-tools \ --method tools/call \ - --tool-name storefront_next_figma_to_component_workflow \ + --tool-name sfnext_start_figma_workflow \ --args '{"figmaUrl": "https://figma.com/design/abc123/MyDesign?node-id=1-2"}' # Call generate-component npx mcp-inspector --cli node bin/run.js --toolsets STOREFRONTNEXT --allow-non-ga-tools \ --method tools/call \ - --tool-name storefront_next_generate_component \ + --tool-name sfnext_analyze_component \ --args '{"figmaMetadata": "{}", "figmaCode": "
Hello
", "componentName": "TestComponent", "discoveredComponents": []}' # Call map-tokens (requires --project-directory with Storefront Next project containing app.css) npx mcp-inspector --cli node bin/run.js --toolsets STOREFRONTNEXT --allow-non-ga-tools \ --project-directory /path/to/storefront-next \ --method tools/call \ - --tool-name storefront_next_map_tokens_to_theme \ + --tool-name sfnext_match_tokens_to_theme \ --args '{"figmaTokens": [{"name": "Primary", "value": "#2563eb", "type": "color"}]}' ``` @@ -95,7 +95,7 @@ For `map-tokens` and `generate-component`, the tools use the project directory f ### 6. Test Scenarios -#### storefront_next_figma_to_component_workflow +#### sfnext_start_figma_workflow **Valid Figma URL** @@ -128,7 +128,7 @@ Expected: Error message with URL format guidance. Expected: Uses custom workflow content instead of default. -#### storefront_next_generate_component +#### sfnext_analyze_component **Empty discovered components (CREATE)** @@ -164,7 +164,7 @@ Expected: CREATE recommendation with confidence ~95%. Expected: REUSE, EXTEND, or CREATE based on analyzed differences. -#### storefront_next_map_tokens_to_theme +#### sfnext_match_tokens_to_theme **Basic token mapping** @@ -195,7 +195,7 @@ Expected: Uses specified theme file instead of auto-discovery. For a full Figma-to-component conversion, execute in order: -1. **Call `storefront_next_figma_to_component_workflow`** with the Figma URL. Receive fileKey, nodeId, and workflow instructions. +1. **Call `sfnext_start_figma_workflow`** with the Figma URL. Receive fileKey, nodeId, and workflow instructions. 2. **Call Figma MCP tools** (external) with the returned fileKey and nodeId: - `mcp__figma__get_design_context` (REQUIRED) @@ -204,9 +204,9 @@ For a full Figma-to-component conversion, execute in order: 3. **Discover similar components** using Glob/Grep/Read to search the codebase for components similar to the Figma design. -4. **Call `storefront_next_generate_component`** with figmaMetadata, figmaCode, componentName, and discoveredComponents. Receive REUSE/EXTEND/CREATE recommendation. +4. **Call `sfnext_analyze_component`** with figmaMetadata, figmaCode, componentName, and discoveredComponents. Receive REUSE/EXTEND/CREATE recommendation. -5. **Call `storefront_next_map_tokens_to_theme`** with design tokens extracted from Figma. Receive token mapping and suggestions. +5. **Call `sfnext_match_tokens_to_theme`** with design tokens extracted from Figma. Receive token mapping and suggestions. 6. **Implement** the recommended approach and present the component to the developer for review. @@ -214,7 +214,7 @@ For a full Figma-to-component conversion, execute in order: ### Theme File Not Found -If `map_tokens_to_theme` returns "Theme file (app.css) not found": +If `sfnext_match_tokens_to_theme` returns "Theme file (app.css) not found": - Ensure `--project-directory` points to a Storefront Next project root - Verify `app.css` or `src/app.css` exists in that directory diff --git a/packages/b2c-dx-mcp/test/tools/storefrontnext/figma/figma-to-component/index.test.ts b/packages/b2c-dx-mcp/test/tools/storefrontnext/figma/figma-to-component/index.test.ts index d933cc5d..e5f455ea 100644 --- a/packages/b2c-dx-mcp/test/tools/storefrontnext/figma/figma-to-component/index.test.ts +++ b/packages/b2c-dx-mcp/test/tools/storefrontnext/figma/figma-to-component/index.test.ts @@ -126,14 +126,16 @@ describe('Figma To Component Workflow (figma/)', () => { expect(response).to.include('`mcp__figma__get_design_context`'); expect(response).to.include('`mcp__figma__get_screenshot`'); - expect(response).to.include('`generate_component`'); - expect(response).to.include('`map_tokens_to_theme`'); + expect(response).to.include('`sfnext_analyze_component`'); + expect(response).to.include('`sfnext_match_tokens_to_theme`'); }); it('should include the do-not-stop instruction', () => { const response = generateWorkflowResponse('https://figma.com/design/abc123/MyDesign?node-id=1-2'); - expect(response).to.include('DO NOT STOP until you have called generate_component AND map_tokens_to_theme'); + expect(response).to.include( + 'DO NOT STOP until you have called sfnext_analyze_component AND sfnext_match_tokens_to_theme', + ); }); it('should include image export approval instruction (user must confirm before exporting)', () => { diff --git a/packages/b2c-dx-mcp/test/tools/storefrontnext/page-designer-decorator/README.md b/packages/b2c-dx-mcp/test/tools/storefrontnext/page-designer-decorator/README.md index 3a509f4f..cc069890 100644 --- a/packages/b2c-dx-mcp/test/tools/storefrontnext/page-designer-decorator/README.md +++ b/packages/b2c-dx-mcp/test/tools/storefrontnext/page-designer-decorator/README.md @@ -37,7 +37,7 @@ pnpm run inspect:dev Then in the inspector: 1. Click **Connect** -2. Click **List Tools** - you should see `storefront_next_page_designer_decorator` +2. Click **List Tools** - you should see `sfnext_add_page_designer_decorator` 3. Click on the tool to test it with real inputs ### 3. CLI Testing @@ -45,13 +45,13 @@ Then in the inspector: Test via command line: ```bash -# List all tools (should include storefront_next_page_designer_decorator) +# List all tools (should include sfnext_add_page_designer_decorator) npx mcp-inspector --cli node bin/dev.js --toolsets STOREFRONTNEXT --allow-non-ga-tools --method tools/list # Call the tool npx mcp-inspector --cli node bin/dev.js --toolsets STOREFRONTNEXT --allow-non-ga-tools \ --method tools/call \ - --tool-name storefront_next_page_designer_decorator \ + --tool-name sfnext_add_page_designer_decorator \ --args '{"component": "MyComponent"}' ``` diff --git a/packages/b2c-dx-mcp/test/tools/storefrontnext/page-designer-decorator/index.test.ts b/packages/b2c-dx-mcp/test/tools/storefrontnext/page-designer-decorator/index.test.ts index 8e893443..5d19ebec 100644 --- a/packages/b2c-dx-mcp/test/tools/storefrontnext/page-designer-decorator/index.test.ts +++ b/packages/b2c-dx-mcp/test/tools/storefrontnext/page-designer-decorator/index.test.ts @@ -138,7 +138,7 @@ describe('tools/storefrontnext/page-designer-decorator', () => { describe('tool metadata', () => { it('should have correct tool name', () => { const tool = createPageDesignerDecoratorTool(getServices); - expect(tool.name).to.equal('storefront_next_page_designer_decorator'); + expect(tool.name).to.equal('sfnext_add_page_designer_decorator'); }); it('should have comprehensive description', () => { diff --git a/packages/b2c-dx-mcp/test/tools/storefrontnext/sfnext-development-guidelines.test.ts b/packages/b2c-dx-mcp/test/tools/storefrontnext/sfnext-development-guidelines.test.ts index 8d656df6..c5035d99 100644 --- a/packages/b2c-dx-mcp/test/tools/storefrontnext/sfnext-development-guidelines.test.ts +++ b/packages/b2c-dx-mcp/test/tools/storefrontnext/sfnext-development-guidelines.test.ts @@ -39,7 +39,7 @@ describe('tools/storefrontnext/sfnext-development-guidelines', () => { describe('tool metadata', () => { it('should have correct tool name', () => { const tool = createDeveloperGuidelinesTool(() => services); - expect(tool.name).to.equal('storefront_next_development_guidelines'); + expect(tool.name).to.equal('sfnext_get_guidelines'); }); it('should have concise, action-oriented description', () => { diff --git a/packages/b2c-dx-mcp/test/tools/storefrontnext/site-theming/README.md b/packages/b2c-dx-mcp/test/tools/storefrontnext/site-theming/README.md index 4ba44cd7..716b73e9 100644 --- a/packages/b2c-dx-mcp/test/tools/storefrontnext/site-theming/README.md +++ b/packages/b2c-dx-mcp/test/tools/storefrontnext/site-theming/README.md @@ -37,7 +37,7 @@ pnpm run inspect:dev Then in the inspector: 1. Click **Connect** -2. Click **List Tools** - you should see `storefront_next_site_theming` +2. Click **List Tools** - you should see `sfnext_configure_theme` 3. Click on the tool to test it with real inputs ### 3. CLI Testing @@ -45,19 +45,19 @@ Then in the inspector: Test via command line: ```bash -# List all tools (should include storefront_next_site_theming) +# List all tools (should include sfnext_configure_theme) npx mcp-inspector --cli node bin/dev.js --toolsets STOREFRONTNEXT --allow-non-ga-tools --method tools/list # Call the tool - list available files npx mcp-inspector --cli node bin/dev.js --toolsets STOREFRONTNEXT --allow-non-ga-tools \ --method tools/call \ - --tool-name storefront_next_site_theming \ + --tool-name sfnext_configure_theme \ --args '{}' # Call with conversation context - get guidelines and questions npx mcp-inspector --cli node bin/dev.js --toolsets STOREFRONTNEXT --allow-non-ga-tools \ --method tools/call \ - --tool-name storefront_next_site_theming \ + --tool-name sfnext_configure_theme \ --args '{"conversationContext":{"collectedAnswers":{"colors":[],"fonts":[]}}}' ``` diff --git a/packages/b2c-dx-mcp/test/tools/storefrontnext/site-theming/index.test.ts b/packages/b2c-dx-mcp/test/tools/storefrontnext/site-theming/index.test.ts index f27dc947..da0e9e3d 100644 --- a/packages/b2c-dx-mcp/test/tools/storefrontnext/site-theming/index.test.ts +++ b/packages/b2c-dx-mcp/test/tools/storefrontnext/site-theming/index.test.ts @@ -53,7 +53,7 @@ describe('tools/storefrontnext/site-theming', () => { describe('tool metadata', () => { it('should have correct structure', () => { const tool = createSiteThemingTool(createMockLoadServices(services)); - expect(tool).to.have.property('name', 'storefront_next_site_theming'); + expect(tool).to.have.property('name', 'sfnext_configure_theme'); expect(tool.description).to.include('theming guidelines'); expect(tool).to.have.property('inputSchema'); expect(tool).to.have.property('handler'); From 12f7fa79e435d90f48b446b135cadffef9047300 Mon Sep 17 00:00:00 2001 From: Yuming Hsieh Date: Tue, 17 Mar 2026 15:25:25 -0400 Subject: [PATCH 3/6] Rename storefront-next-map-tokens-to-theme to sfnext-match-tokens-to-theme Made-with: Cursor --- ...ext-map-tokens-to-theme.md => sfnext-match-tokens-to-theme.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/mcp/tools/{storefront-next-map-tokens-to-theme.md => sfnext-match-tokens-to-theme.md} (100%) diff --git a/docs/mcp/tools/storefront-next-map-tokens-to-theme.md b/docs/mcp/tools/sfnext-match-tokens-to-theme.md similarity index 100% rename from docs/mcp/tools/storefront-next-map-tokens-to-theme.md rename to docs/mcp/tools/sfnext-match-tokens-to-theme.md From 4f758957940208a14997c73064994a6b25cb8b24 Mon Sep 17 00:00:00 2001 From: Yuming Hsieh Date: Tue, 17 Mar 2026 15:25:32 -0400 Subject: [PATCH 4/6] Update sfnext-match-tokens-to-theme content (match vs map, design tokens) Made-with: Cursor --- .../mcp/tools/sfnext-match-tokens-to-theme.md | 50 +++++++++---------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/mcp/tools/sfnext-match-tokens-to-theme.md b/docs/mcp/tools/sfnext-match-tokens-to-theme.md index 1f83191e..09757bca 100644 --- a/docs/mcp/tools/sfnext-match-tokens-to-theme.md +++ b/docs/mcp/tools/sfnext-match-tokens-to-theme.md @@ -1,25 +1,25 @@ --- -description: Map Figma design tokens to existing theme tokens in app.css with confidence scores and suggestions. +description: Match design tokens to existing theme tokens in app.css with confidence scores and suggestions. --- -# storefront_next_map_tokens_to_theme +# sfnext_match_tokens_to_theme -Maps Figma design tokens (colors, spacing, radius, etc.) to your Storefront Next theme tokens in `app.css`. Helps you identify which Figma tokens match existing theme variables and suggests new token names for values that don't have matches. +Matches design tokens (colors, spacing, radius, etc.) to your Storefront Next theme tokens in `app.css`. Helps you identify which design tokens match existing theme variables and suggests new token names for values that don't have matches. > **Note:** 🚧 This MCP tool is for Storefront Next. Storefront Next is part of a closed pilot and isn't available for general use. ## Overview -The `storefront_next_map_tokens_to_theme` tool helps you use theme tokens instead of hardcoded values in your components. After retrieving design tokens from Figma, use this tool to map them to your Storefront Next theme. +The `sfnext_match_tokens_to_theme` tool helps you use theme tokens instead of hardcoded values in your components. After retrieving design tokens (from Figma, design handoff, or other sources), use this tool to match them against your Storefront Next theme. -The tool reads your `app.css` theme file (or you can specify a custom path) and compares Figma tokens against your existing theme variables. It returns a report with instructions showing which tokens match, which are similar, and which need new theme variables created. **The tool does not modify files**β€”it provides recommendations and instructions for you to apply. +The tool reads your `app.css` theme file (or you can specify a custom path) and compares design tokens against your existing theme variables. It returns a report with instructions showing which tokens match, which are similar, and which need new theme variables created. **The tool does not modify files**β€”it provides recommendations and instructions for you to apply. This tool is part of the STOREFRONTNEXT toolset. ## Prerequisites - Storefront Next project with `app.css` (or provide `themeFilePath` explicitly) -- Figma tokens extracted from design (colors, spacing, radius, etc.) +- Design tokens extracted (from Figma, design system, or other sources) See [Figma-to-Component Tools Setup](../figma-tools-setup) for complete prerequisites and configuration. @@ -27,46 +27,46 @@ See [Figma-to-Component Tools Setup](../figma-tools-setup) for complete prerequi | Parameter | Type | Required | Description | |-----------|------|----------|-------------| -| `figmaTokens` | array | Yes | Array of design tokens extracted from Figma. | +| `figmaTokens` | array | Yes | Array of design tokens (e.g., from Figma, design system, or style guide). | | `themeFilePath` | string | No | Optional absolute path to theme CSS file. If not provided, searches for `app.css` in common locations. | -### Figma Token Schema +### Token Schema Each token in `figmaTokens` must have: | Field | Type | Required | Description | |-------|------|----------|-------------| -| `name` | string | Yes | Token name from Figma (e.g., `"Primary/Blue"`, `"Spacing/Large"`). | +| `name` | string | Yes | Token name (e.g., `"Primary/Blue"`, `"Spacing/Large"`). | | `value` | string | Yes | Token value (e.g., `"#2563eb"`, `"16px"`, `"0.5rem"`). | | `type` | string | Yes | One of: `color`, `spacing`, `radius`, `opacity`, `fontSize`, `fontFamily`, `other`. | -| `description` | string | No | Optional description from Figma. | - - -## Output - -Returns a report (does not modify files) showing: -- Which Figma tokens match existing theme variables (exact matches) -- Which tokens are similar to existing variables (suggested matches) -- Which tokens need new theme variables created (with suggested names) -- Instructions for using the matched tokens in components and adding new tokens to your theme file +| `description` | string | No | Optional description. | ## Usage Examples -**Map Figma tokens to your theme:** +**Match design tokens to your theme (default app.css):** ``` -Use the MCP tool to map these Figma tokens to my theme: Primary/Blue #2563eb (color), Spacing/Large 16px (spacing). +Use the MCP tool to match these design tokens to my theme: Primary/Blue #2563eb (color), Spacing/Large 16px (spacing). ``` -**With custom theme file path:** +**Match design tokens with custom theme file path:** ``` -Use the MCP tool to map Figma design tokens to my theme file at /path/to/app.css. +Use the MCP tool to match these design tokens to my theme at /path/to/app.css: +- Primary/Blue #2563eb (color) +- Spacing/Large 16px (spacing) ``` +## Output + +Returns a report (does not modify files) showing: +- Which design tokens match existing theme variables (exact matches) +- Which tokens are similar to existing variables (suggested matches) +- Which tokens need new theme variables created (with suggested names) +- Instructions for using the matched tokens in components and adding new tokens to your theme file ## Related Tools -- [`storefront_next_figma_to_component_workflow`](./storefront-next-figma-to-component-workflow) - Workflow orchestrator; call first -- [`storefront_next_generate_component`](./storefront-next-generate-component) - REUSE/EXTEND/CREATE recommendation +- [`sfnext_start_figma_workflow`](./sfnext-start-figma-workflow) - Workflow orchestrator; call first +- [`sfnext_analyze_component`](./sfnext-analyze-component) - REUSE/EXTEND/CREATE recommendation - Part of the [STOREFRONTNEXT](../toolsets#storefrontnext) toolset - Auto-enabled for Storefront Next projects From b410a28e97508734ea4fb4949c5fbcdc4f41db32 Mon Sep 17 00:00:00 2001 From: Yuming Hsieh Date: Tue, 17 Mar 2026 15:40:55 -0400 Subject: [PATCH 5/6] update instruction --- packages/b2c-dx-mcp/content/sfnext/page-designer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/b2c-dx-mcp/content/sfnext/page-designer.md b/packages/b2c-dx-mcp/content/sfnext/page-designer.md index 54d267c8..29a7b72c 100644 --- a/packages/b2c-dx-mcp/content/sfnext/page-designer.md +++ b/packages/b2c-dx-mcp/content/sfnext/page-designer.md @@ -59,7 +59,7 @@ Adds Page Designer decorators to an existing React component so it can be used i ### 2. `cartridge_deploy` (CARTRIDGES toolset) -Packages the cartridge, uploads it to Commerce Cloud via WebDAV, and unpacks it on the server. Requires Commerce Cloud credentials (e.g. `dw.json` or explicit config). Use after generating metadata so the new/updated metadata is available in Business Manager. +Packages the cartridge, uploads it to Commerce Cloud via WebDAV, and unpacks it on the server. **Run `pnpm generate:cartridge` or `pnpm build` before `cartridge_deploy`.** Requires Commerce Cloud credentials (e.g. `dw.json` or explicit config). Use after generating metadata so the new/updated metadata is available in Business Manager. ### Typical workflow From 8f1b206807e97593cd918cd6b47041e993a69a27 Mon Sep 17 00:00:00 2001 From: Yuming Hsieh Date: Tue, 17 Mar 2026 15:44:54 -0400 Subject: [PATCH 6/6] Improve sfnext-match-tokens-to-theme rename detection (restore Figma refs for >50% similarity) Made-with: Cursor --- docs/mcp/tools/sfnext-match-tokens-to-theme.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/mcp/tools/sfnext-match-tokens-to-theme.md b/docs/mcp/tools/sfnext-match-tokens-to-theme.md index 09757bca..d95b424c 100644 --- a/docs/mcp/tools/sfnext-match-tokens-to-theme.md +++ b/docs/mcp/tools/sfnext-match-tokens-to-theme.md @@ -1,10 +1,10 @@ --- -description: Match design tokens to existing theme tokens in app.css with confidence scores and suggestions. +description: Match Figma design tokens to existing theme tokens in app.css with confidence scores and suggestions. --- # sfnext_match_tokens_to_theme -Matches design tokens (colors, spacing, radius, etc.) to your Storefront Next theme tokens in `app.css`. Helps you identify which design tokens match existing theme variables and suggests new token names for values that don't have matches. +Matches Figma design tokens (colors, spacing, radius, etc.) to your Storefront Next theme tokens in `app.css`. Helps you identify which design tokens match existing theme variables and suggests new token names for values that don't have matches. > **Note:** 🚧 This MCP tool is for Storefront Next. Storefront Next is part of a closed pilot and isn't available for general use. @@ -12,7 +12,7 @@ Matches design tokens (colors, spacing, radius, etc.) to your Storefront Next th The `sfnext_match_tokens_to_theme` tool helps you use theme tokens instead of hardcoded values in your components. After retrieving design tokens (from Figma, design handoff, or other sources), use this tool to match them against your Storefront Next theme. -The tool reads your `app.css` theme file (or you can specify a custom path) and compares design tokens against your existing theme variables. It returns a report with instructions showing which tokens match, which are similar, and which need new theme variables created. **The tool does not modify files**β€”it provides recommendations and instructions for you to apply. +The tool reads your `app.css` theme file (or you can specify a custom path) and compares Figma design tokens against your existing theme variables. It returns a report with instructions showing which tokens match, which are similar, and which need new theme variables created. **The tool does not modify files**β€”it provides recommendations and instructions for you to apply. This tool is part of the STOREFRONTNEXT toolset. @@ -30,16 +30,16 @@ See [Figma-to-Component Tools Setup](../figma-tools-setup) for complete prerequi | `figmaTokens` | array | Yes | Array of design tokens (e.g., from Figma, design system, or style guide). | | `themeFilePath` | string | No | Optional absolute path to theme CSS file. If not provided, searches for `app.css` in common locations. | -### Token Schema +### Figma Token Schema Each token in `figmaTokens` must have: | Field | Type | Required | Description | |-------|------|----------|-------------| -| `name` | string | Yes | Token name (e.g., `"Primary/Blue"`, `"Spacing/Large"`). | +| `name` | string | Yes | Token name from Figma (e.g., `"Primary/Blue"`, `"Spacing/Large"`). | | `value` | string | Yes | Token value (e.g., `"#2563eb"`, `"16px"`, `"0.5rem"`). | | `type` | string | Yes | One of: `color`, `spacing`, `radius`, `opacity`, `fontSize`, `fontFamily`, `other`. | -| `description` | string | No | Optional description. | +| `description` | string | No | Optional description from Figma. | ## Usage Examples @@ -58,7 +58,7 @@ Use the MCP tool to match these design tokens to my theme at /path/to/app.css: ## Output Returns a report (does not modify files) showing: -- Which design tokens match existing theme variables (exact matches) +- Which Figma design tokens match existing theme variables (exact matches) - Which tokens are similar to existing variables (suggested matches) - Which tokens need new theme variables created (with suggested names) - Instructions for using the matched tokens in components and adding new tokens to your theme file