Wyatt MCP Server

An MCP (Model Context Protocol) server for accelerating Shopify theme development with the Wyatt theme framework. This server provides AI-powered tools for generating BEM components, Liquid templates, and Shopify sections following Wyatt's actual conventions and patterns.

What This MCP Server Does

This server enables AI assistants (like Claude) to generate Shopify theme code that perfectly matches Wyatt's conventions:

• 🎨 Generates Components: Create BEM-compliant HTML and CSS using Wyatt's @layer components pattern
• 🧩 Creates Liquid Templates: Build product grids, cards, and sections with proper {% liquid %} blocks
• 📝 Follows Real Patterns: Uses actual patterns from the Wyatt repository, not documentation assumptions
• 🔧 Handles Metafields: Includes support for variant.metafields.wyatt.images.value and other Wyatt metafields
• 🌍 Translation Ready: Uses proper t:sections._all.* translation keys
• 📱 Responsive: Generates CSS Grid with proper breakpoints and spacing tokens
• 🛡️ Safe: Validates code, prevents overwrites, and blocks unsafe operations

Scope & Limitations

What it covers:

• Component generation with proper BEM naming
• Section creation with complete schemas and settings
• Product displays (grids, cards, summaries) with Wyatt patterns
• Liquid templating with optimization and best practices
• CSS generation using Wyatt's layer system and design tokens

What it doesn't cover (yet):

• Shopify Admin API integration for metafields
• Theme deployment or CLI operations
• Asset optimization or image processing
• Cart/checkout functionality
• App integrations or third-party services

Quick Deploy

☁️ Deploy to Cloud (Recommended)

Deploy the Wyatt MCP server to the cloud so your entire team can access it without local setup:

• Deploy to Railway - Recommended, $5/month after free tier
• Deploy to Render - Free tier available
• Deploy with Docker - Any cloud provider

See DEPLOYMENT.md for detailed deployment instructions.

🌐 HTTP API Usage (Remote)

Use the deployed server via HTTP API - no local setup required!

Base URL: https://wyatt-mcp-production.up.railway.app

Available Endpoints

# Get server health and info
curl https://wyatt-mcp-production.up.railway.app/health

# List all available tools
curl https://wyatt-mcp-production.up.railway.app/tools

# Execute MCP tools via HTTP
curl -X POST https://wyatt-mcp-production.up.railway.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "createBEMComponent",
    "arguments": {
      "name": "product-card",
      "elements": ["title", "price", "image"],
      "modifiers": ["featured", "sale"]
    }
  }'

Example Tool Executions

Create a BEM Component:

curl -X POST https://wyatt-mcp-production.up.railway.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "createBEMComponent",
    "arguments": {
      "name": "hero-banner",
      "elements": ["title", "subtitle", "cta"],
      "modifiers": ["large", "centered"]
    }
  }'

Generate Wyatt Product Summary:

curl -X POST https://wyatt-mcp-production.up.railway.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "generateWyattProductSummary",
    "arguments": {
      "showSwatches": true,
      "showBadges": true,
      "loading": "lazy"
    }
  }'

Create a Shopify Section:

curl -X POST https://wyatt-mcp-production.up.railway.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "createSection",
    "arguments": {
      "name": "featured-products",
      "displayName": "Featured Products",
      "includeSettings": true
    }
  }'

Features

Foundation Tools ✅

• BEM Component Generation: Create properly structured HTML and CSS using @layer components
• Section Creation: Generate Shopify sections with schemas and settings
• Snippet Creation: Create reusable Liquid snippets
• BEM Validation: Validate HTML for BEM naming compliance
• Theme Structure Validation: Ensure proper Shopify theme directory structure

Liquid Power Tools ✅

• Product Grid Generation: Complete product grids with filters, sorting, and pagination
• Liquid Loop Generation: Optimized loops with filters and pagination using {% liquid %} blocks
• Product Card Generation: Customizable product card components
• Section Schema Generation: Create complex section schemas with translation keys
• Conditional Generation: Build Liquid conditional statements
• Filter Management: Add and chain Liquid filters
• Case Statement Generation: Create Liquid case/switch statements

Wyatt-Specific Tools ✅

• Wyatt Product Summary: Generate product cards with variant metafield support and proper component loading
• Wyatt Product Grid: Generate responsive grids with CSS custom properties and component styles
• Wyatt Section Generator: Create complete sections with translation keys, spacing settings, and background options

Installation & Setup

1. Clone and Build

# Clone the repository
git clone <repository-url> wyatt-mcp
cd wyatt-mcp

# Install dependencies
npm install

# Build the TypeScript files
npm run build

2. Configure Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "wyatt": {
      "command": "npm",
      "args": ["run", "start:mcp"],
      "cwd": "/absolute/path/to/wyatt-mcp"
    }
  }
}

Important:

• Use absolute paths for the args parameter
• Set cwd to your Shopify theme directory if you want files to be saved there
• Restart Claude Desktop after making changes

3. Verify Installation

In Claude Desktop, ask: "What Wyatt MCP tools are available?"

You should see all 15 tools listed:

Foundation Tools (5):

• createBEMComponent, createSection, createSnippet, validateBEM, validateThemeStructure

Liquid Power Tools (7):

• generateProductGrid, generateLiquidLoop, generateProductCard, generateSectionSchema, generateConditional, addLiquidFilters, generateCase

Wyatt-Specific Tools (3):

• generateWyattProductSummary, generateWyattProductGrid, generateWyattSection

Usage

Basic Workflow

1. Generate Components:

   Create a product card component with media, title, and price elements

2. Create Sections:

   Generate a hero banner section with blocks support and full-width option

3. Build Product Displays:

   Create a Wyatt-style product grid with 4 columns and swatches

Working with Files

To save generated code to your theme:

Create a product summary snippet and save it to my theme

The MCP server will:

• Generate the code following Wyatt patterns
• Save files to the correct theme directories (snippets/, sections/, assets/)
• Prevent overwriting existing files (safety check)
• Validate all generated code

Example Commands

"Generate a BEM component for a newsletter signup with email input and button elements"

"Create a Wyatt section for featured products with collection picker and column settings"

"Build a product grid snippet with swatches, badges, and lazy loading"

"Generate a hero banner section with translation keys and background settings"

Available Tools

Foundation Tools

1. createBEMComponent

Generate a BEM component with proper HTML and CSS structure using @layer components.

{
  "name": "product-card",
  "elements": ["image", "title", "price", "badge"],
  "modifiers": ["featured", "sale"],
  "outputPath": "/path/to/theme" // optional
}

2. createSection

Create a complete Shopify section with schema.

{
  "name": "hero-banner",
  "displayName": "Hero Banner",
  "includeSettings": true,
  "blocks": [
    { "type": "slide", "name": "Slide" }
  ],
  "outputPath": "/path/to/theme" // optional
}

3. generateProductGrid

Generate a complete product grid with all features.

{
  "collection": "collection",
  "columns": 4,
  "columnsMobile": 2,
  "showFilters": true,
  "showSort": true,
  "productsPerPage": 24,
  "showPagination": true,
  "showSwatches": true,
  "showBadges": true,
  "createSection": true, // wrap in section
  "outputPath": "/path/to/theme" // optional
}

4. generateLiquidLoop

Create optimized Liquid loops.

{
  "collection": "collection.products",
  "itemName": "product",
  "limit": 12,
  "filters": ["where: 'available'", "sort: 'price'"],
  "content": "{% render 'product-card', product: product %}"
}

5. generateProductCard

Generate a customizable product card.

{
  "showTitle": true,
  "showVendor": false,
  "showPrice": true,
  "showSwatches": true,
  "showBadges": true,
  "imageRatio": "square",
  "createSnippet": true,
  "outputPath": "/path/to/theme"
}

6. validateBEM

Validate HTML for BEM compliance.

{
  "html": "<div class=\"product-card product-card--featured\">...</div>",
  "strict": true
}

Wyatt-Specific Tools

7. generateWyattProductSummary

Generate a Wyatt-style product summary with metafield support and proper component patterns.

{
  "showQuickAdd": false,
  "showSwatches": true,
  "showBadges": true,
  "loading": "lazy",
  "createSnippet": true
}

8. generateWyattProductGrid

Generate a Wyatt-style product grid with responsive CSS Grid and component loading.

{
  "sectionId": "{{ section.id }}",
  "columnsMobile": 2,
  "columnsTablet": 3,
  "columnsDesktop": 4,
  "gap": "var(--spacing-unit-s)",
  "createSnippet": true
}

9. generateWyattSection

Generate a complete Wyatt section with proper patterns, translation keys, and responsive settings.

{
  "name": "hero-banner",
  "displayName": "Hero Banner",
  "hasBlocks": true,
  "fullWidth": false,
  "styles": ["hero.css", "button.css"],
  "marginSettings": true,
  "paddingSettings": true,
  "backgroundSettings": true
}

Safety Features

The MCP server includes several safety mechanisms:

• Production Protection: Blocks direct production deployments
• File Protection: Prevents modification of critical files like checkout.liquid
• Settings Protection: Read-only access to settings_data.json by default
• Metafield Protection: Blocks modification of Shopify system metafields
• File Existence Checks: Prevents overwriting existing files without confirmation
• Syntax Validation: Validates all generated Liquid syntax

Development Workflow

For Wyatt Projects (Recommended)

1. Component Creation

   • Use generateWyattProductSummary for product cards with metafield support
   • Use generateWyattProductGrid for responsive product grids
   • Use generateWyattSection for complete sections with translation keys

2. CSS and HTML

   • Use createBEMComponent to generate HTML/CSS with @layer components
   • Validates BEM naming conventions
   • Automatically creates files in correct directories (assets/, snippets/)

3. Liquid Templates

   • Use generateLiquidLoop for optimized loops with {% liquid %} blocks
   • Use generateConditional for if/elsif/else statements
   • All templates include proper Wyatt patterns and component loading

For General Shopify Development

1. Basic Components

   • Use foundation tools for standard BEM components
   • Use liquid tools for template generation
   • Customize as needed for non-Wyatt projects

2. Validation

   • Use validateBEM to check naming compliance
   • Use validateThemeStructure to verify directory structure

Example Workflows

Building a Wyatt Product Page

1. "Create a Wyatt product summary with swatches and badges, save to my theme"
2. "Generate a responsive product grid with 4 desktop columns and 2 mobile columns"
3. "Create a hero section with blocks support for my product page"
4. "Generate the CSS for a product-card component with media and info elements"

Creating a Collection Page

1. "Build a Wyatt section for featured collections with collection picker setting"
2. "Create a product grid snippet that uses CSS custom properties for spacing"
3. "Generate a collection hero with background image and overlay settings"
4. "Add a liquid loop for filtering products by availability"

Building Components

1. "Create a BEM component for a newsletter signup with email and button elements"
2. "Generate CSS using @layer components for a testimonial card"
3. "Build a responsive navigation component with mobile and desktop modifiers"
4. "Create a section schema with translation keys and spacing settings"

Troubleshooting

Common Issues

"MCP server not found" or tools not available:

1. Check that the path in claude_desktop_config.json is absolute and correct
2. Ensure you've run npm run build after installation
3. Restart Claude Desktop after config changes
4. Check that Node.js is installed and in your PATH

"Permission denied" or file creation errors:

1. Verify the cwd path in your MCP config exists and is writable
2. Check that you're in a valid Shopify theme directory
3. Ensure the theme has the correct directory structure (assets/, sections/, snippets/)

Generated code doesn't match Wyatt patterns:

1. Make sure you're using the Wyatt-specific tools (generateWyattProductSummary, etc.)
2. Check that you're referencing the actual Wyatt repo at /Users/msamimi/syatt/projects/wyatt
3. Report issues if patterns don't match the real Wyatt codebase

TypeScript/Build errors:

# Clean rebuild
rm -rf dist/ node_modules/
npm install
npm run build

Getting Help

1. Check the logs: Look at Claude Desktop's developer console for MCP errors
2. Verify tools: Ask Claude "List all available MCP tools" to confirm the server is connected
3. Test manually: Run node dist/index.js to check for startup errors
4. Report issues: File issues with specific error messages and steps to reproduce

Best Practices

1. Always validate component names before creation
2. Use semantic naming that describes the component's purpose
3. Follow BEM strictly - the tools enforce proper naming
4. Test generated Liquid with the syntax validator
5. Check file existence before creating new files
6. Use modifiers instead of creating similar components
7. Reference the Wyatt repo when in doubt about patterns

Roadmap

Phase 3: API Integration (Planned)

• Shopify Admin API integration for metafields
• Storefront API query generation
• Theme settings synchronization

Phase 4: Advanced Features (Planned)

• AI-powered BEM validation with suggestions
• Unused code detection
• Performance analysis tools
• Schema migration utilities

Contributing

1. Follow Wyatt's conventions for all generated code
2. Add tests for new tools
3. Update documentation with examples
4. Ensure all safety checks are in place

License

MIT