@salesforce/pwa-kit-mcp 0.1.0-preview.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+## v1.0.0-dev.0 (Jun 26, 2025)
+- 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 [#2645](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2645):

package/README.md

@@ -0,0 +1,165 @@
+# PWA Storefront MCP Server
+
+A Model Context Protocol (MCP) server that provides AI coding assistance for developing  PWA-kit-based storefront apps in an IDE.
+
+Install and run this MCP server as a local MCP server or run locally via `npx` (when it's available on `npm` in feature).
+
+## What is MCP?
+
+The Model Context Protocol (MCP) is an open protocol that enables secure connections between host applications, such as Claude Desktop or other AI assistants, and external data sources and tools.
+
+## Features
+
+The PWA Storefront MCP Server provides these features.
+
+- `development_guidelines`: Helps developers understand and follow PWA Storefront developer guidelines and best practices.
+- `create_new_sample_component`: Helps developers create a new sample PWA Storefront component. This feature guides developers through a few simple questions and then generates code for the component based on the commerce data model used, layouts, etc.
+- `create_app_guidelines`: Helps developers generate a new PWA Storefront project.
+- `run_site_test`: Run site performance or accessibility test for a given site URL (e.g. [https://pwa-kit.mobify-storefront.com](https://pwa-kit.mobify-storefront.com))
+
+## Setup
+
+Install dependencies and build under `pwa-kit` root directory:
+
+```bash
+cd {{pwa-kit root directory}}
+npm ci
+```
+
+## Run the MCP Server
+
+### Method 1: Run MCP Server from Cursor
+
+1. Open the Cursor application.
+
+2. In the Cursor Menu on the top menu bar, click **Settings** > **Cursor Settings...**. 
+
+<img src="./docs/images/cursor-settings.png" alt="Cursor Settings Screenshot" width="50%" />
+
+3. Click **Tools & Integrations** > **MCP Tools** > **New MCP Server**.
+
+<img src="./docs/images/cursor-mcp-tools.png" alt="Cursor MCP Tools Screenshot" width="50%" />
+
+The `mcp.json` file opens. Add this definition to your `mcp.json` file and replace {{parent-dir-to-mcp}} and {{path-to-app-directory}} placeholders with correct values.
+
+```json
+{
+  "mcpServers": {
+
+    "pwa-kit-mcp": {
+      "command": "node {{parent-dir-to-mcp}}/pwa-kit-mcp/dist/server/server.js",
+      "transport": "stdio",
+      "args": [],
+      "env": {
+        "PWA_STOREFRONT_APP_PATH": "{{path-to-app-directory}}"
+      }
+    }
+  }
+} 
+```
+
+After you modify the `mcp.json` file, cursor will do these actions.
+
+- Start the MCP server.
+- Connect to the MCP server as a client.
+- List available tools.
+
+You can go back to MCP Tools and choose to enable/disable any MCP Server or tools.
+
+### Method 2: Run MCP Server from Claude
+
+#### Using Claude Desktop
+
+1. In the Claude app menu, on the top menu bar, click **Developer** > **Edit Config**.
+The `claude_desktop_config.json` file opens.
+
+<img src="./docs/images/claude-config.png" alt="Claude MCP Config Screenshot" width="50%" />
+
+2. Add this server definition to your `claude_desktop_config.json` and replace {{path-to-node}}, {{parent-dir-to-mcp}} and {{path-to-app-directory}} placeholders with correct values.
+
+```json
+{
+  "mcpServers": {
+    "pwa-kit-mcp": {
+      "command": "npx",
+      "args": ["-y", "@salesforce/pwa-kit-mcp-server@0.1.0-preview.0"],
+      "env": {
+        "PWA_STOREFRONT_APP_PATH": "{{path-to-app-directory}}"
+      }
+    }
+  }
+}  
+```
+
+After you modify the `claude_desktop_config.json` file, Claude will do these actions.
+
+- Start the MCP server.
+- Connect to the MCP server as a client.
+- List available tools.
+
+<img src="./docs/images/claude-list-tools.png" alt="Claude MCP Tools Screenshot" width="40%" />
+
+You can also enable/disable any available tools from here.
+
+#### Using other MCP clients
+The server runs on stdio, so you can test it with any MCP-compatible client.
+
+### Method 3: Manually start MCP Server
+
+You can also manually start the server from command line and sending JSON-RPC messages:
+
+```bash
+cd {{dir-to-mcp}}
+# Start the server
+npm run start
+
+# Then send JSON-RPC requests to stdin:
+{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
+{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "create_new_component", "arguments": {}}}
+```
+
+## Files
+
+- `server.js` - Main MCP server implementation
+- `mcp.json` - MCP configuration file for clients
+- `package.json` - Node.js dependencies and scripts
+
+## Development
+
+To run the server in development mode:
+```bash
+npm start
+```
+
+The server outputs debug information to stderr and handle MCP protocol messages via stdio.
+
+# Project Structure
+
+```
+/ (root)
+  - package.json
+  - package-lock.json
+  - README.md
+  - mcp.json
+  - claude_desktop_config.json
+  /src
+    /server
+      - server.js
+    /utils
+      - pwa-developer-guideline-tool.js
+      - utils.js
+    /tests
+      - test-mcp.js
+  /docs
+    /images
+        - claude-config.png
+        - claude-list-tools.png
+        - cursor-list-tools.png
+        - cursor-settings.pnb
+    - cursor-integration-guide.md
+  /node_modules
+```
+
+- Server code is in `src/server/`.
+- Utilities/tools are in `src/utils/`.
+- Documentation is in `docs/`.

package/dist/CHANGELOG.md

@@ -0,0 +1,5 @@
+## v1.0.0-dev.0 (Jun 26, 2025)
+- 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 [#2645](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2645):

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"
+        }
+    }
+}