shopware-catalog-generator

Shopware Catalog Generator

Generate AI-powered demo catalogs for Shopware. Creates SalesChannels with category trees, products, descriptions, images, reviews, variants, CMS pages, cross-selling, demo customers, promotions, and themed storefronts (AI-generated brand colors, logo, favicon).

Architecture details: See CONCEPTS.md for diagrams and in-depth explanations.

Quick Start

bun install
bun run build

Create a .env file:

# AI Provider — pick one:
AI_PROVIDER=github-models               # Free with GitHub Copilot
AI_API_KEY=ghp_your_github_token        # github.com/settings/tokens
# AI_PROVIDER=pollinations              # Alternative: enter.pollinations.ai
# AI_API_KEY=sk_your_pollinations_key

# Shopware connection (required to sync data)
SW_ENV_URL=http://localhost:8000
SW_CLIENT_ID=your-access-key-id      # Settings → System → Integrations
SW_CLIENT_SECRET=your-secret-key     # Settings → System → Integrations

The SW_CLIENT_ID and SW_CLIENT_SECRET authenticate against the Shopware Admin API. Create an integration in your Shopware Admin under Settings → System → Integrations, then copy the Access key ID and Secret access key into your .env.

Generate a full catalog:

bun run generate --name=music --description="Musical instruments and accessories for musicians of all levels"

This creates a SalesChannel named "music" with 3 top-level categories, ~90 products, AI-generated descriptions, properties, and optional images.

Catalog Templates

Pre-generated, ready-to-use catalogs are available at shopware-catalog-templates. Currently included: music, garden, and beauty.

When you run generate, the CLI automatically checks if a matching template exists. If found, it skips AI generation entirely and uploads the template directly:

# Uses a pre-generated template (instant, no AI needed)
bun run generate --name=music

# Force AI generation even if a template exists
bun run generate --name=music --no-template

Templates require git access via SSH keys or credential helper.

Maintaining the Templates Repository

When regenerating all templates, squash the history to keep the repo size small. A maintenance script is included for this:

bash scripts/reset-templates-history.sh /path/to/shopware-catalog-templates

This creates a fresh single commit, cleans up all stale refs, and repackages the objects to the minimum possible size. Afterwards, a force-push is required.

AI Providers & Performance

Provider	API Key	Text	Images	Best For
github-models	PAT	Free	Free (Pollinations)	Free with GitHub Copilot
pollinations	sk_*	Parallel	Parallel (with key)	Fast, no rate limits
pollinations	pk_*	Sequential	Free (pollen preserved)	Free tier
openai	sk-...	Parallel	Paid (gpt-image-1)	Production, high volume

Free Setup (GitHub Copilot)

If you have a GitHub Copilot subscription, you can generate catalogs entirely for free — text via GitHub Models, images via Pollinations free tier:

AI_PROVIDER=github-models
AI_API_KEY=ghp_your_github_token

No IMAGE_PROVIDER or IMAGE_API_KEY needed. Images are automatically generated via Pollinations free tier.

Create a personal access token at github.com/settings/tokens (no extra scopes needed beyond Copilot access).

Other Providers

# Pollinations with secret key - parallel processing, no rate limits
AI_PROVIDER=pollinations
AI_API_KEY=sk_your_pollinations_secret_key

# Pollinations with publishable key - pollen preserved for text, images are free
AI_PROVIDER=pollinations
AI_API_KEY=pk_your_pollinations_key

# OpenAI (full parallel processing, paid images)
AI_PROVIDER=openai
AI_API_KEY=sk-your-openai-key

Get a Pollinations API key at enter.pollinations.ai

Optional settings:

AI_MODEL=gpt-6-luna          # OpenAI default (reasoning disabled)
IMAGE_PROVIDER=none          # Disable images
IMAGE_MODEL=gpt-image-1-mini # OpenAI default; optional: gpt-image-2.5-flare
IMAGE_QUALITY=low            # OpenAI only: low (fastest), medium, high, auto

OpenAI uses GPT-6 Luna without reasoning for cost-efficient catalog text. In our small live benchmark, it cost about 93% less than GPT-4.1 but took about twice as long. Set AI_MODEL=gpt-4.1-2025-04-14 to retain the previous, faster model. Explicit model overrides are preserved.

Images stay on GPT Image 1 Mini / low. Flare produced sharper detail in the sample, but its estimated cost was about 54% higher and its speed advantage was small. Opt in with IMAGE_MODEL=gpt-image-2.5-flare; existing image sizes and WebP caching work unchanged. Pollinations image models remain flux, turbo, and klein.

Expected Times (90 products)

These are historical estimates, not measurements of the new Luna text default. Actual times depend on model, account limits, and generated content.

Text generation only (blueprint hydration):

Provider	Processing	Time
OpenAI	Parallel (5x)	~5 min
Pollinations (sk_*)	Parallel (5x)	~5 min
GitHub Models	Limited (2x)	~10 min
Pollinations (pk_*)	Sequential	~13 min

Full generation with images (~270 images at 3 views per product):

Provider	Image Model	Quality	Time
OpenAI	gpt-image-1-mini	low	~8-12 min
OpenAI	gpt-image-1-mini	medium	~12-18 min
OpenAI	gpt-image-1.5	medium	~20-25 min
Pollinations	flux (default)	-	~15-20 min
Pollinations	turbo (fast)	-	~10-15 min
Any (images: none)	-	-	~5-13 min

Image generation is the primary time factor. Use IMAGE_PROVIDER=none to skip images for faster testing.

Shopware Connection

SW_ENV_URL=http://localhost:8000
SW_CLIENT_ID=your-access-key-id
SW_CLIENT_SECRET=your-secret-key

To create integration credentials:

1. Open Shopware Admin → Settings → System → Integrations
2. Click Add integration
3. Copy the Access key ID → SW_CLIENT_ID
4. Copy the Secret access key → SW_CLIENT_SECRET

Domains & Languages

Every generated SalesChannel automatically gets two domains:

Domain	Language	Currency
{name}.localhost:8000	English	USD
{name}-de.localhost:8000	German	EUR

The German domain is only created if de-DE language and its snippet set are installed in Shopware. If not, a warning is logged and only the English domain is created.

To install German: Settings → Shop → Languages → Add language → German.

CLI Usage

For the complete reference with all flags and options, see CLI Reference.

Generate

bun run generate --name=music --description="Musical instruments and accessories for musicians of all levels"

Blueprint Workflow

For more control, run the 3-phase pipeline separately. See CONCEPTS.md for details.

# Optional: crawl a real store to guide AI generation (no AI calls, instant)
bun run blueprint inspire --name=music --url=https://some-music-shop.com

bun run blueprint create --name=music --description="Musical instruments and accessories"
bun run blueprint hydrate --name=music   # uses inspiration.json automatically if present
bun run generate --name=music

blueprint inspire extracts categories, example products, brand colors, and a description from a real store's static HTML. The data is saved as inspiration.json and automatically picked up by blueprint hydrate to orient AI generation. No API keys needed — uses cheerio + sharp.

Results depend on the site's structure. Sites with bot protection (Cloudflare, etc.) or full SPA rendering may yield partial or no data. A failed crawl never blocks generation.

Post-Processors

Run specific post-processors after upload:

bun run process --name=music --only=images,reviews

Cleanup

bun run cleanup -- --salesChannel="music"                    # Products + categories
bun run cleanup -- --salesChannel="music" --full --delete    # Everything

Cache Management

bun run cache:list                    # Show cached SalesChannels
bun run cache:clear -- music          # Move to trash
bun run cache:restore -- --all        # Restore from trash

Post-Processors

Post-processors run after upload for resource-intensive tasks (images, reviews, CMS pages, etc.).

Processor	Description	Dependencies
cms-home	Homepage layout with product listing	none
cms-text	Text elements demo page	none
cms-images	Image elements demo page	none
cms-video	Video elements demo page	none
cms-text-images	Text & Images demo page	none
cms-commerce	Commerce elements demo page	images
cms-form	Form elements demo page	none
cms-footer-pages	Shared footer and legal pages	none
cross-selling	Category-based cross-selling via product streams	none
customers	Demo customer accounts with B2B group	none
images	Upload pre-generated product/category images	none
manufacturers	Fictional manufacturer creation	none
promotions	Tiered pricing and promotion codes	none
reviews	Product reviews (0-10 per product)	none
theme	Child theme with brand colors, logo, favicon	none
variants	Variant product creation	manufacturers
digital-product	Digital product (Gift Card)	none
cms-testing	Testing category hierarchy	cms-*, digital-product

Processors run in parallel when possible, respecting dependency order. See CONCEPTS.md for the execution diagram.

Server Mode

Run as an HTTP service with background processing:

bun run server

Method	Endpoint	Description
POST	/generate	Start generation (returns process ID)
GET	/status/:id	Poll process status, progress, and logs
GET	/health	Health check and active process count

# Minimal: name and description are derived from the inspiration URL
curl -X POST http://localhost:3000/generate \
  -H "Content-Type: application/json" \
  -d '{
    "envPath": "http://localhost:8000",
    "shopwareUser": "admin",
    "shopwarePassword": "shopware",
    "inspirationUrl": "https://some-music-shop.com"
  }'

When inspirationUrl is provided, the server crawls the URL before creating the blueprint — so the extracted brandDescription and brand colors are used to orient AI generation. The salesChannel name is derived from the URL hostname if not explicitly set. See CLI Reference for all request fields.

MCP Server (AI Assistant Integration)

This project includes an MCP server for AI assistant integration in Cursor IDE. All CLI commands are exposed as auto-discoverable tools.

Setup

The MCP config at .cursor/mcp.json uses /bin/sh to resolve $HOME dynamically:

{
    "mcpServers": {
        "catalog-generator": {
            "command": "/bin/sh",
            "args": ["-c", "\"$HOME/.bun/bin/bun\" run src/mcp/index.ts"]
        }
    }
}

If your bun is installed elsewhere, adjust the path accordingly.

Testing

bun run test:mcp      # Automated MCP CLI checks (no credentials or external services)
bun run mcp:dev       # Interactive terminal testing
bun run mcp:inspect   # Web UI inspector

test:mcp launches the installed @wong2/mcp-cli against the real Bun MCP server. It checks tool calls, blueprint creation, cache listing, argument validation, and schema defaults using a temporary cache that is removed afterward. Use Node.js 24 for the CLI, matching CI. To use it interactively, run bunx --no-install mcp-cli bun run src/mcp/index.ts and select list_processors for a read-only check.

Contributing

Development

bun run dev           # Watch mode
bun run lint          # Lint + typecheck (oxlint + tsc)
bun run format        # Format code (oxfmt)
bun run build         # Build (lint + format + bundle)

Testing

bun test              # Run all tests
bun test --watch      # Watch mode
bun test --coverage   # With coverage report

E2E Testing

./test-e2e.sh                                                         # Full: create → hydrate → upload → verify
./test-e2e.sh --name=stabilo --description="Writing instruments" \
              --url=https://www.stabilo.com/com                        # With inspiration crawl
./test-e2e.sh --reuse=music                                           # Reuse existing blueprint
./test-e2e.sh --reuse=music --skip-hydrate                            # Skip AI, just upload
./test-e2e.sh --cleanup=music                                         # Cleanup only
bun run test:verify --name=music                                      # Verify Shopware data

Extending

See AGENTS.md for developer documentation on adding post-processors, AI providers, CMS fixtures, and CLI commands.

License

This project is licensed under the GNU Affero General Public License v3.0 or later.