@salesforce/pwa-kit-mcp 3.12.0-nightly-20250724080225 → 3.12.0-nightly-20250728080226

package/README.md

@@ -14,7 +14,24 @@ 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.
+- `create_app_guidelines`: This tool provides all the information an agent needs to correctly scaffold a new PWA Kit app using the `@salesforce/pwa-kit-create-app` CLI. 
+
+  It returns:
+    - Project creation guidelines for agent behavior
+    - CLI description and available options
+    - Input schemas for presets or templates
+
+    The output enables agents to ask the right questions and use the CLI correctly without ever mixing unsupported options.
+
+    **Example Triggers**
+
+    This tool is automatically used when the user expresses intent to create a project, such as:
+
+    - "Create a new PWA Kit app."
+    - "Start a new storefront using a preset."
+    - "What templates are available for PWA Kit?"
+    - "What PWA-Kit presets are available?"
+    - "Create a PWA-Kit project using the `retail-react-app-demo` preset in the `~/test-project` directory."
 - `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
@@ -34,11 +51,11 @@ npm ci
 
 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%" />
+<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. Click **Tools & Integrations** > **MCP Tools** > **New MCP Server**.
 
-<img src="./docs/images/cursor-mcp-tools.png" alt="Cursor MCP Tools Screenshot" width="50%" />
+<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%" />
 
 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.
 
@@ -71,7 +88,7 @@ You can go back to MCP Tools and choose to enable/disable any MCP Server or tool
 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%" />
+<img src="https://raw.githubusercontent.com/SalesforceCommerceCloud/pwa-kit/refs/heads/develop/packages/pwa-kit-mcp/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.
 
@@ -95,7 +112,7 @@ After you modify the `claude_desktop_config.json` file, Claude will do these act
 - 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%" />
+<img src="https://raw.githubusercontent.com/SalesforceCommerceCloud/pwa-kit/refs/heads/develop/packages/pwa-kit-mcp/docs/images/claude-list-tools.png" alt="Claude MCP Tools Screenshot" width="40%" />
 
 You can also enable/disable any available tools from here.
 
@@ -138,26 +155,51 @@ The server outputs debug information to stderr and handle MCP protocol messages
   - package.json
   - package-lock.json
   - README.md
+  - CHANGELOG.md
   - mcp.json
   - claude_desktop_config.json
+  - babel.config.js
+  - jest.config.js
+  - jest-setup.js
+  - .eslintrc.js
+  - .eslintignore
   /src
     /server
       - server.js
+      - server.test.js
+    /tools
+      - index.js
+      - developer-guideline.js
+      - developer-guideline.test.js
+      - create-app-guideline.js
+      - create-app-guideline.test.js
+      - create-new-component.js
+      - create-new-component.test.js
+      - site-test.js
+      - site-test.test.js
+      - site-test-accessibility.js
+      - site-test-performance.js
     /utils
-      - pwa-developer-guideline-tool.js
+      - index.js
       - utils.js
-    /tests
-      - test-mcp.js
+      - utils.test.js
+    /data
+      - CategoryDocument.json
+      - DocumentList.json
+      - ProductDocument.json
   /docs
     /images
         - claude-config.png
         - claude-list-tools.png
-        - cursor-list-tools.png
-        - cursor-settings.pnb
+        - cursor-mcp-tools.png
+        - cursor-settings.png
     - cursor-integration-guide.md
-  /node_modules
+  /dist
 ```
 
 - Server code is in `src/server/`.
-- Utilities/tools are in `src/utils/`.
+- MCP tools are in `src/tools/`.
+- Utilities are in `src/utils/`.
+- Data files are in `src/data/`.
 - Documentation is in `docs/`.
+- Built distribution files are in `dist/`.

package/docs/cursor-integration-guide.md

@@ -0,0 +1,310 @@
+# How to Programmatically Insert Code Blocks in Cursor
+
+This guide shows different methods to programmatically insert code blocks in files using Cursor.
+
+## Method 1: Using Your MCP Server (Recommended)
+
+### Setup
+1. **Configure the MCP Server in Cursor.**
+   ```json
+   // Add to your Cursor MCP configuration
+   {
+     "mcpServers": {
+       "pwa-kit-mcp": {
+         "command": "node",
+         "args": ["pwa-kit-mcp/server.js"]
+       }
+     }
+   }
+   ```
+
+2. **Restart Cursor** to load the MCP server.
+
+### Using the Tools
+
+#### 1. Analyze Code Structure
+```javascript
+// Ask Cursor/Claude: "Analyze this React code structure"
+// The MCP server will identify:
+// - Import statements
+// - Component definitions
+// - Export statements
+// - Insertion points
+// - Framework detection (React, Next.js)
+// - Styling system detection (Tailwind, CSS)
+```
+
+#### 2. Insert React Components
+```javascript
+// Ask Cursor/Claude: "Insert a ProductCard component with Tailwind styling"
+// The MCP server will:
+// - Analyze the existing code
+// - Generate the appropriate component
+// - Find the best insertion point
+// - Add necessary imports
+// - Insert the component code
+```
+
+#### 3. Create New Component Files
+```javascript
+// Ask Cursor/Claude: "Create a new Button component file"
+// The MCP server will generate a complete component file with:
+// - Proper imports
+// - Component definition
+// - Export statement
+// - Styling (Tailwind or CSS)
+```
+
+## Method 2: Direct File Manipulation
+
+### Using Node.js Scripts
+```javascript
+import fs from 'fs/promises';
+import path from 'path';
+
+async function insertCodeBlock(filePath, codeBlock, insertionPoint = 'end') {
+  try {
+    // Read existing file
+    const content = await fs.readFile(filePath, 'utf-8');
+    const lines = content.split('\n');
+    
+    let insertIndex;
+    
+    switch (insertionPoint) {
+      case 'start':
+        insertIndex = 0;
+        break;
+      case 'end':
+        insertIndex = lines.length;
+        break;
+      case 'after-imports':
+        // Find last import statement
+        insertIndex = findLastImportLine(lines) + 1;
+        break;
+      case 'before-export':
+        // Find export default statement
+        insertIndex = findExportDefaultLine(lines);
+        break;
+      default:
+        insertIndex = lines.length;
+    }
+    
+    // Insert the code block
+    lines.splice(insertIndex, 0, '', codeBlock, '');
+    
+    // Write back to file
+    await fs.writeFile(filePath, lines.join('\n'), 'utf-8');
+    console.log(`✅ Code inserted into ${filePath}`);
+    
+  } catch (error) {
+    console.error('❌ Error inserting code:', error);
+  }
+}
+
+function findLastImportLine(lines) {
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (lines[i].trim().startsWith('import ')) {
+      return i;
+    }
+  }
+  return 0;
+}
+
+function findExportDefaultLine(lines) {
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim().startsWith('export default')) {
+      return i;
+    }
+  }
+  return lines.length;
+}
+
+// Usage
+await insertCodeBlock(
+  './src/App.js',
+  `const NewComponent = () => {
+  return <div>Hello World</div>;
+};`,
+  'after-imports'
+);
+```
+
+### Using the fs module with templates
+```javascript
+import fs from 'fs/promises';
+import { AddComponentTool } from './AddComponentTool.js';
+
+const componentTool = new AddComponentTool();
+
+async function insertReactComponent(filePath, componentType, options) {
+  try {
+    // Read existing file
+    const content = await fs.readFile(filePath, 'utf-8');
+    
+    // Use our MCP tool to insert the component
+    const modifiedCode = componentTool.insertComponent(content, componentType, options);
+    
+    // Write back to file
+    await fs.writeFile(filePath, modifiedCode, 'utf-8');
+    console.log(`✅ ${componentType} component inserted into ${filePath}`);
+    
+  } catch (error) {
+    console.error('❌ Error:', error);
+  }
+}
+
+// Usage
+await insertReactComponent('./src/App.js', 'button', {
+  name: 'SubmitButton',
+  variant: 'primary',
+  styling: 'tailwind'
+});
+```
+
+## Method 3: Using Cursor's AI Commands
+
+### 1. **Natural Language Commands:**
+```
+"Insert a ProductCard component after the imports in App.js"
+"Add a modal component with Tailwind styling to this file"
+"Create a new button component with these specifications: primary variant, medium size"
+```
+
+### 2. **Structured Prompts:**
+```
+Insert a React component with these specifications.
+- Type: ProductCard
+- Name: FeaturedProduct
+- Styling: Tailwind CSS
+- Features: Show price, rating, and add-to-cart button
+- Insert after imports in the current file
+```
+
+### 3. **Code Generation Prompts:**
+```
+Generate and insert a complete React component.
+
+```typescript
+interface ProductCardProps {
+  product: {
+    id: string;
+    name: string;
+    price: number;
+    image: string;
+    rating?: number;
+  };
+  onAddToCart: (product: Product) => void;
+}
+```
+
+Create a ProductCard component using this interface.
+```
+
+## Method 4: VSCode/Cursor Extensions
+
+### Custom Extension for Code Insertion
+```javascript
+// extension.js
+const vscode = require('vscode');
+
+function activate(context) {
+  let disposable = vscode.commands.registerCommand('extension.insertComponent', async () => {
+    const editor = vscode.window.activeTextEditor;
+    if (!editor) return;
+    
+    // Get component type from user
+    const componentType = await vscode.window.showQuickPick([
+      'button', 'card', 'modal', 'product', 'form'
+    ], { placeHolder: 'Select component type' });
+    
+    if (!componentType) return;
+    
+    // Generate component code using your MCP server
+    const componentCode = await generateComponent(componentType);
+    
+    // Find insertion point
+    const insertionPoint = findInsertionPoint(editor.document);
+    
+    // Insert the code
+    editor.edit(editBuilder => {
+      editBuilder.insert(insertionPoint, `\n${componentCode}\n`);
+    });
+  });
+  
+  context.subscriptions.push(disposable);
+}
+
+async function generateComponent(type) {
+  // Call your MCP server or use the AddComponentTool directly
+  const { AddComponentTool } = await import('./AddComponentTool.js');
+  const tool = new AddComponentTool();
+  
+  return tool.createComponentFile(
+    `Custom${type.charAt(0).toUpperCase() + type.slice(1)}`,
+    type,
+    { styling: 'tailwind' }
+  );
+}
+```
+
+## Method 5: Automation Scripts
+
+### Batch Component Generation
+```javascript
+import { AddComponentTool } from './AddComponentTool.js';
+import fs from 'fs/promises';
+import path from 'path';
+
+const componentTool = new AddComponentTool();
+
+const componentsToCreate = [
+  { name: 'ProductCard', type: 'product', options: { styling: 'tailwind' } },
+  { name: 'AddToCartButton', type: 'button', options: { variant: 'primary' } },
+  { name: 'ProductModal', type: 'modal', options: { closeOnOverlay: true } },
+  { name: 'ReviewCard', type: 'card', options: { showHeader: true } }
+];
+
+async function generateComponents() {
+  const componentsDir = './src/components';
+  
+  // Ensure directory exists
+  await fs.mkdir(componentsDir, { recursive: true });
+  
+  for (const comp of componentsToCreate) {
+    const componentCode = componentTool.createComponentFile(
+      comp.name,
+      comp.type,
+      comp.options
+    );
+    
+    const fileName = `${comp.name}.jsx`;
+    const filePath = path.join(componentsDir, fileName);
+    
+    await fs.writeFile(filePath, componentCode, 'utf-8');
+    console.log(`✅ Created ${fileName}`);
+  }
+}
+
+generateComponents().catch(console.error);
+```
+
+## Best Practices
+
+1. **Use the MCP Server**: The MCP server provides intelligent analysis and proper code insertion.
+2. **Validate Syntax**: Always check generated code for syntax errors.
+3. **Preserve Formatting**: Maintain consistent code style and indentation.
+4. **Handle Imports**: Ensure necessary imports are added when inserting components.
+5. **Test Integration**: Verify that inserted components work with existing code.
+
+## Demo Commands
+
+Run the demo to see the MCP server in action:
+```bash
+npm run demo  # or: node demo.js
+```
+
+This demo demonstrates the following:
+- Code structure analysis
+- Component insertion
+- New file creation
+- Real-time code generation 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/pwa-kit-mcp",
-  "version": "3.12.0-nightly-20250724080225",
+  "version": "3.12.0-nightly-20250728080226",
   "private": false,
   "description": "MCP server that helps you build Salesforce Commerce Cloud PWA Kit Composable Storefront",
   "main": "dist/server/server.js",
@@ -8,6 +8,7 @@
     "CHANGELOG.md",
     "LICENSE",
     "dist/**/*.{js,d.ts,json}",
+    "docs/",
     "!dist/CHANGELOG.md",
     "!dist/README.md",
     "!**/*.test.{ts,js}"
@@ -52,9 +53,9 @@
   "devDependencies": {
     "@babel/node": "^7.22.5",
     "@playwright/test": "^1.49.0",
-    "@salesforce/pwa-kit-dev": "3.12.0-nightly-20250724080225",
+    "@salesforce/pwa-kit-dev": "3.12.0-nightly-20250728080226",
     "cross-env": "^5.2.1",
-    "internal-lib-build": "3.12.0-nightly-20250724080225",
+    "internal-lib-build": "3.12.0-nightly-20250728080226",
     "nodemon": "^2.0.22"
   },
   "engines": {
@@ -64,5 +65,5 @@
   "publishConfig": {
     "directory": "dist"
   },
-  "gitHead": "5ee8b1378edaa5edcdfa185a94590d2a1c0f7264"
+  "gitHead": "a52aa781d18baaaf4bc31b405879b1c980cc2f2a"
 }