@10up/block-renderer-mcp-server

Model Context Protocol (MCP) server for AI assistant integration. Enables AI assistants like Claude to render and validate WordPress blocks.

Installation

npm install @10up/block-renderer-mcp-server
# or
pnpm add @10up/block-renderer-mcp-server

Overview

This package provides an MCP server that exposes:

1. Tools - Actions AI can perform (render, validate, generate prompt)
2. Resources - Data AI can read (blocks, tokens, patterns, preferences)

Works with:

• Claude Desktop
• Cursor IDE
• Any MCP-compatible client

Usage

Start Server Programmatically

import { runMcpServer } from '@10up/block-renderer-mcp-server';

await runMcpServer({
  theme: parsedTheme,
  patterns: patternRegistry,
  preferences: userPreferences,
  wpContentPath: '/path/to/wp-content',
  themeName: 'my-theme'
});

Create Server Without Running

import { createMcpServer } from '@10up/block-renderer-mcp-server';

const server = createMcpServer({
  theme: parsedTheme,
  patterns: patternRegistry,
});

// Connect to custom transport
server.connect(myTransport);

Server Configuration

interface McpServerConfig {
  /** Block catalog (auto-generated if theme provided) */
  catalog?: BlockCatalog;
  /** Parsed theme with tokens */
  theme?: ParsedTheme;
  /** Pattern registry */
  patterns?: PatternRegistry;
  /** User preferences */
  preferences?: BlockPreferencesConfig;
  /** Path to wp-content for third-party block scanning */
  wpContentPath?: string;
  /** Theme name for block scanning */
  themeName?: string;
}

CLI Usage

# Using workspace config from a specific directory
npx @10up/block-renderer-mcp-server --config /path/to/project

# Using workspace config from current directory
npx @10up/block-renderer-mcp-server

# With theme (bypasses workspace config)
npx @10up/block-renderer-mcp-server --theme /path/to/theme

# Disable file watching
npx @10up/block-renderer-mcp-server --config /path/to/project --no-watch

CLI Options

| Option | Description | |--------|-------------| | -c, --config <path> | Path to workspace directory containing .block-renderer/config.json | | -t, --theme <path> | Path to WordPress theme directory | | -p, --preferences <path> | Path to preferences file | | -i, --ignite | Enable Ignite WP mode (fluid tokens, typography presets) | | -P, --pretty | Format rendered block markup with indentation | | --no-watch | Disable file watching for auto-refresh | | -h, --help | Show help message |

Workspace Configuration

Instead of passing CLI arguments, you can configure the MCP server via a config file in your project root. This is the recommended approach for per-project setups.

Config File Location

Create .block-renderer/config.json in your project directory:

{
  "themePath": "./wp-content/themes/my-theme",
  "ignite": true,
  "prettyPrint": true,
  "preferencesPath": "./block-preferences.json"
}

Config Options

| Option | Type | Description | |--------|------|-------------| | themePath | string | Required. Path to WordPress theme directory (relative to project root) | | patternsDir | string | Path to patterns directory (relative to project root, defaults to themePath/patterns) | | ignite | boolean | Enable Ignite WP mode for fluid tokens and typography presets | | prettyPrint | boolean | Format rendered block markup with indentation | | preferencesPath | string | Path to preferences file (relative to project root) |

Path Resolution

All paths in the config file are resolved relative to the project root (the directory containing .block-renderer/), not relative to the config file itself.

For example, with this structure:

my-project/                          # Project root
├── .block-renderer/
│   └── config.json                  # themePath: "./wp-content/themes/my-theme"
└── wp-content/
    └── themes/
        └── my-theme/

The themePath of ./wp-content/themes/my-theme resolves to /path/to/my-project/wp-content/themes/my-theme.

Config Priority

CLI arguments take precedence over config file settings:

1. CLI only: Uses CLI arguments
2. Config file only: Uses config file
3. Both: CLI arguments override config file values

Auto-Refresh (File Watching)

The MCP server automatically watches for file changes and reloads data when:

| File Pattern | Refreshes | |--------------|-----------| | theme.json | Theme tokens, colors, typography, spacing | | styles/*.json | Style variations, section styles | | patterns/*.php | Pattern registry | | **/block.json | Block catalog (theme + plugins) | | block-preferences.json | User preferences |

Changes are debounced (300ms) to batch rapid file saves. After refresh, MCP clients are notified via resourceListChanged notification.

Disabling File Watching

Use --no-watch flag to disable:

npx @10up/block-renderer-mcp-server --no-watch

Client Configuration

Recommended: Per-Project Configuration

The recommended approach is to use per-project MCP configs. This allows each project to have its own block-renderer configuration without hardcoding paths in global config files.

Setup Steps

1. Create workspace config in your project root:

your-project/
├── .block-renderer/
│   └── config.json      # Theme path and options
├── .cursor/
│   └── mcp.json         # MCP server definition (for Cursor)
├── .claude/
│   └── settings.json    # MCP server definition (for Claude Code)
└── wp-content/
    └── themes/
        └── your-theme/

2. Create .block-renderer/config.json with your theme settings:

{
  "themePath": "./wp-content/themes/your-theme",
  "ignite": true,
  "prettyPrint": true
}

3. Create the MCP client config for your IDE (see below).

When the MCP server starts, it reads .block-renderer/config.json from the current working directory (your project root) and resolves all paths relative to that directory.

Cursor IDE (Per-Project)

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "block-renderer": {
      "command": "npx",
      "args": ["@10up/block-renderer-mcp-server"]
    }
  }
}

When you open the project folder in Cursor, the MCP server starts with that folder as the working directory and automatically finds .block-renderer/config.json.

Claude Code (Per-Project)

Create .claude/settings.json in your project root:

{
  "mcpServers": {
    "block-renderer": {
      "command": "npx",
      "args": ["@10up/block-renderer-mcp-server"]
    }
  }
}

Claude Desktop

Claude Desktop requires a global config. Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "block-renderer": {
      "command": "npx",
      "args": [
        "@10up/block-renderer-mcp-server",
        "--config",
        "/absolute/path/to/your/project"
      ]
    }
  }
}

Note: Claude Desktop doesn't support per-project configs, so you must use --config with an absolute path. For multi-project setups, you may need to update this path when switching projects.

Global Config (Not Recommended)

You can add the MCP server to your global Cursor config at ~/.cursor/mcp.json, but this requires hardcoding the project path:

{
  "mcpServers": {
    "block-renderer": {
      "command": "npx",
      "args": [
        "@10up/block-renderer-mcp-server",
        "--config",
        "/absolute/path/to/project"
      ]
    }
  }
}

This approach is not recommended because:

• The path only works for one project
• You must update it when switching between projects
• Per-project configs are more portable and don't require absolute paths

Available Tools

render_blocks

Convert JSON block tree to WordPress markup.

Input:

{
  "blockTree": {
    "root": "para-1",
    "elements": {
      "para-1": {
        "key": "para-1",
        "type": "core/paragraph",
        "props": { "content": "Hello world" }
      }
    }
  }
}

Output:

<!-- wp:paragraph -->
<p>Hello world</p>
<!-- /wp:paragraph -->

validate_tree

Validate block structure and return errors.

Input:

{
  "blockTree": {
    "root": "para-1",
    "elements": {
      "para-1": {
        "key": "para-1",
        "type": "core/paragraph",
        "props": {
          "content": "Hello",
          "style": { "color": { "background": "var:preset|color|invalid" } }
        }
      }
    }
  }
}

Output (valid):

Block tree is valid.

Output (invalid):

Validation errors:
- Unknown color token: invalid

generate_prompt

Generate AI system prompt with current configuration.

Input:

{
  "compact": true
}

Output:

# WordPress Block Generation

You are generating WordPress blocks using a JSON format...

refresh_catalog

Manually reload blocks, patterns, and theme tokens from disk. Usually not needed as files are watched automatically, but useful as a fallback when changes aren't detected.

Input:

{
  "what": ["blocks", "patterns", "tokens", "preferences"]
}

Or refresh everything:

{
  "what": ["all"]
}

Output:

Refreshed: blocks, patterns, tokens, preferences
Counts: blocks: 45, thirdPartyBlocks: 5, patterns: 12, colors: 8

Note: This tool is only available when the server is started with workspace configuration (either via config file or CLI). In legacy mode (no configuration), this tool returns an error.

Available Resources

blocks://catalog

List of available WordPress blocks with their attributes and constraints.

URI: blocks://catalog
MIME: text/markdown

Returns documentation of all registered blocks including:
- Block name and title
- Available attributes with types
- Nesting constraints (parent, ancestor, allowedBlocks)
- Whether block is dynamic

tokens://colors

Color presets from the configured theme.

URI: tokens://colors
MIME: text/markdown

Returns:
- Color name and slug
- Hex value
- CSS variable reference (var:preset|color|{slug})

tokens://typography

Typography presets from the theme.

URI: tokens://typography
MIME: text/markdown

Returns:
- Font sizes with slugs and values
- Font families with CSS font stacks

patterns://list

Available block patterns from the theme.

URI: patterns://list
MIME: text/markdown

Returns:
- Pattern slug and title
- Categories
- Description

preferences://current

Current user preferences configuration.

URI: preferences://current
MIME: application/json

Returns the loaded preferences object.

Third-Party Block Support

When wpContentPath and themeName are provided, the server automatically scans and registers third-party blocks from:

• wp-content/plugins/*/
• wp-content/mu-plugins/*/
• wp-content/client-mu-plugins/*/
• wp-content/themes/{themeName}/blocks/

This enables AI to generate markup for custom blocks like tenup/tabs, acf/custom-block, etc.

Complete Exports

Functions

| Function | Description | |----------|-------------| | createMcpServer(config) | Create MCP server instance | | runMcpServer(config) | Run server with stdio transport | | loadMcpConfig(cliArgs, cwd) | Load and merge workspace config with CLI args | | loadWorkspaceConfigFromFile(cwd) | Load raw workspace config from file | | mergeConfigs(fileConfig, cliArgs, cwd) | Merge file config with CLI args | | resolveConfig(rawConfig, configDir) | Resolve relative paths to absolute | | hasWorkspaceConfig(cwd) | Check if workspace config exists | | createFileWatcher(manager, config) | Create file watcher for auto-refresh |

Classes

| Class | Description | |-------|-------------| | CatalogManager | Manages catalog state with refresh capabilities | | FileWatcher | Watches files and triggers catalog refresh |

Types

| Type | Description | |------|-------------| | McpServerConfig | Server configuration options | | CreateMcpServerResult | Result from createMcpServer | | RunMcpServerResult | Result from runMcpServer | | RawWorkspaceConfig | Raw config as stored in file | | ResolvedMcpConfig | Resolved config with absolute paths | | CliArgs | CLI argument interface | | RefreshResult | Result of a refresh operation | | WatchConfig | File watcher configuration |

License

MIT