@10up/block-renderer-mcp-server

@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/

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

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

1. 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