@salesforce/pwa-kit-mcp 0.3.0-preview.2 → 0.3.0-preview.4

package/CHANGELOG.md

@@ -1,4 +1,4 @@
-## v0.3.0-preview.0 (Sep 19, 2025)
+## v0.3.0-preview.4 (Sep 23, 2025)
 - Added telemetry for MCP tools. [#3327](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3327)
 
 ## v0.2.0 (Sep 4, 2025)

package/LICENSE

@@ -0,0 +1,14 @@
+BSD 3-Clause License
+
+Copyright (c) 2023 Salesforce, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of Salesforce.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/dist/CHANGELOG.md

@@ -0,0 +1,16 @@
+## v0.3.0-preview.4 (Sep 23, 2025)
+- Added telemetry for MCP tools. [#3327](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3327)
+
+## v0.2.0 (Sep 4, 2025)
+- Normalize tool names; Add introduction section for PWA Kit MCP and resize the images on README. [#3239](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3239)
+
+## v0.1.1 (Aug 11, 2025)
+- Add missing `shelljs` dependency. [#3053](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3053)
+
+## v0.1.0 (Jun 26, 2025)
+- Clean up readme [#2954](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2954)
+- Add `create_app_guidelines` MCP tool  [#2663](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2663)
+- Add `create_new_sample_component` MCP tool. [#2651](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2651)
+- Add `create_app_guidelines` MCP tool. [#2599](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2599)
+- Add `run_site_test` MCP tool [#2989](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2989) [#2645](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2645) [#3003](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3003)
+- Add `create_sample_storefront_page` MCP tool [#2899](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2899) [#3014](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/3014)

package/dist/LICENSE

@@ -0,0 +1,14 @@
+BSD 3-Clause License
+
+Copyright (c) 2023 Salesforce, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of Salesforce.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/dist/README.md

@@ -0,0 +1,154 @@
+# 🚀 PWA Kit MCP Server
+
+An MCP server that enhances the entire development lifecycle of PWA Kit storefront apps — from project creation and management to AI-assisted coding, testing, and implementation of best practices — all within your IDE.
+
+## 🔍 What is MCP?
+
+**Model Context Protocol (MCP)** is an open protocol that enables secure, structured communication between host applications (like [Cursor IDE](https://www.cursor.so/) or other AI development tools) and external tools or data sources.
+
+It allows AI agents to query context-aware services like this server to help developers build better software, faster.
+
+
+👉 **[Read more at modelcontextprotocol.io](https://modelcontextprotocol.io/)**
+
+
+## What is PWA-Kit-MCP?
+
+PWA-Kit-MCP is a local STDIO MCP Server that communicates via STDIO and operates in conjunction with a running local process, making it a fully locally installed MCP server. It provides an initial suite of MCP tools intended to standardize and optimize the developer workflow for PWA Kit storefront development. These tools facilitate project creation, supply development guidelines, enable the generation of new components and pages, and support site validation through performance and accessibility testing.
+
+_NOTE: Cursor provides multiple LLMs for your use. These PWA Kit MCP tools were tested with the Claude 4 Sonnet LLM_
+
+## 🧰 Features
+
+The PWA Kit MCP Server offers the following intelligent tools tailored to Salesforce Commerce Cloud PWA development:
+
+* **`create_storefront_app`**:
+  Guides agents and developers through creating a new PWA Kit project with `@salesforce/pwa-kit-create-app`.
+
+* **`create_sample_component`**:
+  Walks developers through a brief Q\&A to scaffold a component using the commerce data model, layout, and structure.
+
+* **`create_sample_page`**:
+  Interactive tool to generate a new PWA storefront page with custom routing and components.
+
+* **`development_guidelines`**:
+  Provides best practices and guidance for building PWA Kit storefronts.
+
+* **`run_site_test`**:
+  Runs performance and accessibility audits on a provided site URL.
+  *Example: `https://pwa-kit.mobify-storefront.com`*
+
+
+## ▶️ Running the MCP Server
+
+### 🖥️ From Cursor IDE
+
+1. Open **Cursor**.
+
+2. Navigate to **Settings > Cursor Settings...**
+<img src="https://raw.githubusercontent.com/SalesforceCommerceCloud/pwa-kit/refs/heads/develop/packages/pwa-kit-mcp/docs/images/cursor-settings.png" alt="Cursor Settings Screenshot" width="50%" />
+
+3. Go to **Tools & Integrations > MCP Tools > New MCP Server**
+<img src="https://raw.githubusercontent.com/SalesforceCommerceCloud/pwa-kit/refs/heads/develop/packages/pwa-kit-mcp/docs/images/cursor-mcp-tools.png" alt="Cursor MCP Tools Screenshot" width="50%" />
+
+4. Update your `mcp.json` like this (edit the placeholders as needed):
+```json
+{
+  "mcpServers": {
+    "pwa-kit": {
+      "command": "npx",
+      "args": ["-y", "@salesforce/pwa-kit-mcp"],
+      "env": {
+        "PWA_STOREFRONT_APP_PATH": "{{path-to-app-directory}}"
+      }
+    }
+  }
+}
+```
+_NOTE: Replace `{{path-to-app-directory}}` with the absolute path to your generated project's `app` subfolder. For example: `"/Users/username/mcp-server-folder/mystorefront/app"`._
+
+## 📊 Telemetry
+
+The server collects minimal, anonymous usage data to improve reliability and the developer experience.
+
+- **What's included**:
+  - Server lifecycle events: started, stopped, errors (`SERVER_STATUS`).
+  - Tool usage: tool name, run time, success/error (`TOOL_CALLED`).
+- **What’s not included**:
+  - No source code, file contents, prompts, or secrets are collected by default.
+- **How to disable/opt out**:
+  - Add `--no-telemetry` to your `args`.
+
+**Beta:** Telemetry for the PWA Kit MCP server is in beta and subject to change. Event names, payloads, and destinations may change without notice; the feature may be modified or removed.
+
+These are the available flags that you can pass to the `args` option. 
+
+| Flag Name | Description | Required? |Notes |
+| -----------------| -------| ------- | ----- |
+| `--no-telemetry` | Boolean flag to disable telemetry, the automatic collection of data for monitoring and analysis. | No | Telemetry is enabled by default, so specify this flag to disable it.  |
+| `"-y", "@salesforce/mcp"` | Tells `npx` to automatically install the `@salesforce/mcp` package instead of asking permission. | Yes | Don't change this.
+
+Once saved, Cursor will:
+
+* Launch the MCP server
+* Connect to it as a client
+* Display the available tools in the UI and how you can invoke them
+
+You can return to **MCP Tools** anytime to enable or disable specific tools or servers.
+
+### 🧪 From Other MCP Clients
+
+We currently only support Cursor IDE, but if you wish to try it out with your AI agent enabled IDE, you can manually run the server be following the below steps. **NOTE:** This server communicates via **stdio**, so it is important to ensure your IDE can communicate in this manner.
+
+```bash
+cd {{dir-to-mcp}}
+npm run start
+```
+
+Then send JSON-RPC requests like:
+
+```json
+{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
+{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "create_sample_component", "arguments": {}}}
+```
+
+---
+
+## 👩‍💻 Development
+
+If you are actively developing features for the MCP server and want to get immediate feedback during testing, follow the below steps.
+
+1. Update your Cursor IDE MCP server configuration so that you are referencing the local server. This can be done by opening the "View: Open MCP Settings" 
+from the command pallet and editing your `pwa-kit` entry to look like the entry below.
+```json
+{
+  "mcpServers": {
+    "pwa-kit": {
+      "command": "node",
+      "args": ["{{path-to-app-mono-repo}}/packages/pwa-kit-mcp/dist/server/server.js"],
+      "env": {
+        "PWA_STOREFRONT_APP_PATH": "{{path-to-app-directory}}"
+      }
+    }
+  }
+}
+```
+
+2. Ensure that your server is built and will rebuild whenever changes are made you by running the following command in the `/pwa-kit-mcp` folder:
+```bash
+npm run build:watch
+```
+
+The server logs to `stderr` and communicates using MCP via `stdio`. You can view these logs in the `Output` section (shift + command + U) and filtering
+the output on "MCP Logs".
+
+
+### 🔹 File & Folder Overview
+
+| Location       | Purpose                                                               |
+| -------------- | --------------------------------------------------------------------- |
+| `package.json` | Node.js dependencies and project scripts                              |
+| `mcp.json`     | MCP client configuration (used by Cursor or other IDEs)               |
+| `src/server/`  | Main server entry point (`server.js`)                                 |
+| `src/tools/`   | Contains all MCP tools like `create-storefront-app`, `site-test`, etc. |
+| `src/utils/`   | Shared utility functions                                              |

package/dist/data/CategoryDocument.json

@@ -0,0 +1,239 @@
+{
+    "description": "Document representing a category.",
+    "properties": {
+        "c_alternativeUrl": {
+            "$ref": "https://zzrf-001.dx.commercecloud.salesforce.com/s/-/dw/meta/rest/data/v23_1/documents/markup_text",
+            "description": "Renders an alternative URL in main navigation. Uses Commerce Cloud content url notation. For example: $url('Account-Show')$ or normal URL http://xchange.demandware.com",
+            "x-label": {
+                "default": "Alternative URL"
+            }
+        },
+        "c_catBannerID": {
+            "description": "Used to define the content asset used to populate a grid page banner for a category. This value is applied to all sub-category navigation (cascading) if no specific catBannerID has been defined for  a sub-category.",
+            "x-label": {
+                "default": "Category Banner ID"
+            },
+            "type": "string"
+        },
+        "c_customCSSFile": {
+            "$ref": "https://zzrf-001.dx.commercecloud.salesforce.com/s/-/dw/meta/rest/data/v23_1/documents/media_file",
+            "description": "Use this attribute to apply custom styles for this category.",
+            "x-label": {
+                "default": "Custom CSS File"
+            }
+        },
+        "c_enableCompare": {
+            "description": "Used to define if/when the Compare feature is to be visualized in the storefront based on navigation. If enableCompare = FALSE, no Compare checkboxes will be displayed in the grid view. If enableCompare = TRUE, the category (and its children) will support the Compare feature.",
+            "x-label": {
+                "default": "Enable Compare"
+            },
+            "type": "boolean"
+        },
+        "c_headerMenuBanner": {
+            "$ref": "https://zzrf-001.dx.commercecloud.salesforce.com/s/-/dw/meta/rest/data/v23_1/documents/markup_text",
+            "x-label": {
+                "default": "Header Menu Banner"
+            }
+        },
+        "c_headerMenuOrientation": {
+            "description": "Which way to orient the menu and optional header menu HTML. Vertical will list all in one line. Horizontal will list in columns.",
+            "enum": [
+                "Horizontal",
+                "Vertical"
+            ],
+            "x-enum-labels": [
+                {
+                    "default": "Horizontal"
+                },
+                {
+                    "default": "Vertical"
+                }
+            ],
+            "x-label": {
+                "default": "Header Menu Orientation"
+            },
+            "type": "string"
+        },
+        "c_showInMenu": {
+            "description": "Used to indicate that a category (such as Mens -> Footwear -> Boots) will display in the roll-over navigation. A sub-category only shows if also the parent category is marked as showInMenu. Up to three category levels are shown in roll-over navigation.",
+            "x-label": {
+                "default": "Show in Menu Navigation"
+            },
+            "type": "boolean"
+        },
+        "c_sizeChartID": {
+            "description": "Used to define the content asset ID of the Size Chart that is appropriate for products whose PRIMARY category is the associated category (and its children). Whenever a product detail page (or quick view) is rendered, the Size Chart link is populated based on the value of this attribute for the products primary categorization. If not defined, NO size chart link is displayed.",
+            "x-label": {
+                "default": "Size Chart"
+            },
+            "type": "string"
+        },
+        "c_slotBannerHtml": {
+            "additionalProperties": {
+                "$ref": "https://zzrf-001.dx.commercecloud.salesforce.com/s/-/dw/meta/rest/data/v23_1/documents/markup_text"
+            },
+            "format": "localized",
+            "x-label": {
+                "default": "Slot Banner HTML"
+            },
+            "type": "object"
+        },
+        "c_slotBannerImage": {
+            "$ref": "https://zzrf-001.dx.commercecloud.salesforce.com/s/-/dw/meta/rest/data/v23_1/documents/media_file",
+            "description": "Image used on either the top or bottom slot on the category landing pages.",
+            "x-label": {
+                "default": "Category Landing Slot Image"
+            }
+        },
+        "catalog_id": {
+            "description": "The id of the catalog that contains it.",
+            "x-label": {
+                "default": "ID"
+            },
+            "type": "string"
+        },
+        "categories": {
+            "description": "The array of sub categories for the category.",
+            "items": {
+                "$ref": "https://zzrf-001.dx.commercecloud.salesforce.com/s/-/dw/meta/rest/data/v23_1/documents/category"
+            },
+            "type": "array"
+        },
+        "creation_date": {
+            "description": "Returns the value of attribute 'creationDate'.",
+            "format": "date-time",
+            "x-label": {
+                "default": "Creation Date"
+            },
+            "readOnly": true,
+            "type": "string"
+        },
+        "description": {
+            "additionalProperties": {
+                "type": "string"
+            },
+            "description": "The localized description of the category.",
+            "format": "localized",
+            "x-label": {
+                "default": "Description"
+            },
+            "type": "object"
+        },
+        "id": {
+            "description": "The id of the category.",
+            "x-label": {
+                "default": "ID"
+            },
+            "maxLength": 256,
+            "minLength": 1,
+            "type": "string"
+        },
+        "image": {
+            "description": "The name of the category image. The URL to the image is computed.",
+            "x-label": {
+                "default": "Standard Image"
+            },
+            "maxLength": 256,
+            "minLength": 1,
+            "type": "string"
+        },
+        "last_modified": {
+            "description": "Returns the value of attribute 'lastModified'.",
+            "format": "date-time",
+            "x-label": {
+                "default": "Last Modified"
+            },
+            "readOnly": true,
+            "type": "string"
+        },
+        "link": {
+            "description": "The URL to get the category. This is a computed attribute and cannot be modified.",
+            "type": "string"
+        },
+        "name": {
+            "additionalProperties": {
+                "type": "string"
+            },
+            "description": "The localized name of the category.",
+            "format": "localized",
+            "x-label": {
+                "default": "Name"
+            },
+            "type": "object"
+        },
+        "online": {
+            "description": "The online status of the category determines if it is visible in the storefront. Defaults to false if not specified on create.",
+            "x-label": {
+                "default": "Online"
+            },
+            "type": "boolean"
+        },
+        "page_description": {
+            "additionalProperties": {
+                "type": "string"
+            },
+            "description": "The localized page description of the category.",
+            "format": "localized",
+            "x-label": {
+                "default": "Page Description"
+            },
+            "type": "object"
+        },
+        "page_keywords": {
+            "additionalProperties": {
+                "type": "string"
+            },
+            "description": "The localized page keywords for the category.",
+            "format": "localized",
+            "x-label": {
+                "default": "Page Keywords"
+            },
+            "type": "object"
+        },
+        "page_title": {
+            "additionalProperties": {
+                "type": "string"
+            },
+            "description": "The localized page title of the category.",
+            "format": "localized",
+            "x-label": {
+                "default": "Page Title"
+            },
+            "type": "object"
+        },
+        "parent_category_id": {
+            "description": "The id of the parent category. Defaults to root if not specified on create.",
+            "maxLength": 256,
+            "minLength": 1,
+            "type": "string"
+        },
+        "paths": {
+            "description": "The paths that contains catalog and category information requested by non-standard expand request",
+            "items": {
+                "$ref": "https://zzrf-001.dx.commercecloud.salesforce.com/s/-/dw/meta/rest/data/v23_1/documents/path_record"
+            },
+            "type": "array"
+        },
+        "position": {
+            "description": "The position of the category determines the display order in the storefront.",
+            "format": "double",
+            "type": "number"
+        },
+        "sorting_rules": {
+            "description": "The sorting rules that are attached to the category requested by non-standard expand request",
+            "items": {
+                "$ref": "https://zzrf-001.dx.commercecloud.salesforce.com/s/-/dw/meta/rest/data/v23_1/documents/sorting_rule"
+            },
+            "type": "array"
+        },
+        "thumbnail": {
+            "description": "The name of the category thumbnail. The URL to the thumbnail is computed.",
+            "x-label": {
+                "default": "Thumbnail Image"
+            },
+            "maxLength": 256,
+            "minLength": 1,
+            "type": "string"
+        }
+    }
+}