Using AI to Create Custom Themes (MCP Server)

Overview

Larapen ships with a Model Context Protocol (MCP) server that lets AI assistants (like Claude, ChatGPT, Cursor, or any MCP-compatible tool) understand and work with the Larapen theme system. Instead of manually reading documentation and studying existing themes, the AI connects directly to your project and gets structured information about theme architecture, file conventions, validation rules, and more.

This means you can describe the theme you want in plain language: and the AI will generate valid, complete theme files that follow every Larapen convention.

Who is this for?

1. Customers who want a unique theme

You don't need to be a developer. Open your AI assistant (Claude Desktop, Cursor, VS Code with Copilot, etc.), make sure the MCP server is configured, and describe what you want:

"I need a dark luxury theme called nightfall with gold accents, elegant serif typography, and a transparent header. I want it to support portfolio and team pages."

The AI will use the MCP tools to understand Larapen's requirements and generate all the necessary files: theme.json, config.php, SCSS, JavaScript, Blade views, and section templates: all correctly structured and following platform conventions.

2. Freelancers and agencies building themes for clients

If you build websites for clients on Larapen, the MCP server dramatically accelerates your workflow:

• Scaffold in seconds: Generate a complete theme skeleton with one prompt instead of manually creating dozens of files.
• Study existing themes: Ask the AI to compare how different themes implement the same view, or show you the exact structure of any theme file.
• Validate before delivery: Run the built-in validation tool to catch missing files, invalid manifests, or broken asset paths before shipping to your client.
• Consistent quality: The AI enforces Larapen conventions automatically: no jQuery, proper Bootstrap integration, correct Vite paths, dark mode support, etc.

Setting up the MCP server

Step 1: Install dependencies

Navigate to the mcp-server/ directory inside your Larapen project and install the PHP dependencies:

cd mcp-server
composer install

Step 2: Configure your AI assistant

Create or edit the .mcp.json file in your Larapen project root directory (not inside mcp-server/):

{
    "mcpServers": {
        "larapen": {
            "command": "php",
            "args": ["mcp-server/server.php"],
            "cwd": "."
        }
    }
}

This tells your MCP-compatible AI assistant how to launch the Larapen server. The exact location depends on your tool:

Step 3: Verify the connection

Open your AI assistant and ask it something like:

"List all installed Larapen themes"

If the MCP server is correctly configured, the AI will call the list_themes tool and return a list of your installed themes with their manifests and file counts. If you see this, everything is working.

What the AI can do with the MCP server

The MCP server exposes 13 tools and 4 resources that the AI uses behind the scenes. You don't need to know the tool names: just describe what you want and the AI will pick the right tools automatically.

Available tools

Available resources (reference data)

Example workflow: Creating a theme from scratch

Here is a typical conversation you might have with your AI assistant:

Describe your vision

You: "I want to create a new Larapen theme called 'nightfall'. It should have a dark luxury feel: deep navy background, gold accents, elegant serif headings (Playfair Display), clean sans-serif body text (Lato). The header should be transparent with a sticky effect on scroll. I want a modern, minimal footer."

The AI researches your project

Behind the scenes, the AI automatically:

1. Reads the theme development guide to understand all requirements
2. Lists existing themes to see what's already installed
3. Studies the default theme's master layout, header, and footer implementation
4. Checks which add-ons are installed (to create matching page templates)
5. Reviews the Vite configuration for proper asset paths

The AI scaffolds your theme

The AI generates all theme files with your specifications applied:

• theme.json: Manifest with your theme name, description, and color settings
• config.php: Settings with your colors (#0a0f1e, #d4a853), fonts, and layout preferences
• assets/scss/theme.scss: Complete SCSS with Bootstrap import, custom properties, dark mode styles, header/footer/section styles
• assets/js/theme.js: Complete JS with header scroll, mobile menu, dark mode toggle, back-to-top, reveal animations
• views/layouts/master.blade.php: Full HTML layout with all required Blade directives
• views/partials/header.blade.php: Transparent header with sticky scroll behavior
• views/partials/footer.blade.php: Minimal dark footer
• All required page templates and section templates

You refine

You: "The hero section looks good, but I want the CTA buttons to have a gold gradient border instead of a solid background. Also, make the testimonials section use a card layout instead of the carousel."

The AI reads the current files and makes targeted changes while keeping everything else consistent.

Validate

You: "Validate my nightfall theme to make sure everything is correct."

The AI runs 10 categories of validation checks and reports any errors or warnings:

{
    "theme": "nightfall",
    "valid": true,
    "summary": "0 errors, 2 warnings, 18 checks passed",
    "errors": [],
    "warnings": [
        "Missing section templates (will fall back to default theme): countdown, before-after",
        "Missing recommended view: views/layouts/auth.blade.php"
    ],
    "passed": [
        "theme.json: Valid manifest structure",
        "config.php: Valid configuration",
        "View exists: views/layouts/master.blade.php",
        "View exists: views/partials/header.blade.php",
        "..."
    ]
}

Build and activate

You: "Build the assets and tell me how to activate the theme."

The AI reminds you to run:

npx vite build

Then go to Appearance → Themes in the admin panel, click "Sync" to discover the new theme, and click "Activate".

How the workflow looks in practice

  You (plain language)              AI Assistant                    MCP Server
  ────────────────────         ────────────────────          ────────────────────

  "Create a dark luxury    ──→  Calls get_theme_              Reads project files
   theme called nightfall"      development_guide,     ←──    and returns structured
                                list_themes,                   theme data
                                list_addons

                           ──→  Calls scaffold_theme    ──→   Creates directories
                                with your specs               and starter files

  "Make the buttons have   ──→  Calls read_theme_file   ──→  Returns file contents
   gold gradient borders"       then edits the SCSS

  "Validate my theme"     ──→   Calls validate_theme    ──→  Runs 10 validation
                                                              checks, returns report

  "Are my assets built?"  ──→   Calls check_theme_      ──→  Checks Vite manifest
                                assets_built                   for theme entries

Validation checks explained

When you ask the AI to validate your theme, it performs these checks:

Tips for best results

• Be specific about your design vision: Mention colors (hex codes), fonts (Google Fonts names), layout style (wide/boxed), header behavior (sticky/transparent), and mood (luxury, playful, corporate, minimal).
• Reference existing themes: Say "similar to the elegant theme but with a darker color palette": the AI will study that theme first.
• Ask for validation early and often: Run validation after scaffolding and again after making changes.
• Iterate in conversation: The AI remembers context, so you can say "make the header taller" or "change the accent color to coral" without repeating everything.
• Always build after changes: Remember to run npx vite build after any SCSS or JS file changes.