1.6.1 • Published 21h agoCLI

@wootsup/yt-builder-mcp

Licence

MIT

Version

1.6.1

Deps

Size

2.0 MB

Vulns

Weekly

666

Stars

Summary Dependency Versions

@wootsup/yt-builder-mcp. YT Builder MCP for YOOtheme Pro (unofficial)

Drive your page builder via MCP. Built for YOOtheme Pro 4.0+ on WordPress and Joomla 5/6. Connect Claude Desktop, Claude Code, Cursor, Zed, Continue, Cline, Roo Code, Codex CLI, or Gemini CLI in one command.

Independent third-party project. YOOtheme is a registered trademark of YOOtheme GmbH (yootheme.com). YT Builder MCP is built by WootsUp (getimo productions) and is not affiliated with, endorsed by, or sponsored by YOOtheme. The integration uses YOOtheme Pro's public extension points.

License: MIT

Quick start

# 1. Install the host plugin for your CMS.
#    WordPress: yt-builder-mcp-*.zip plugin.
#    Joomla 5/6: pkg_ytbmcp-*.zip package (three sub-extensions in one go).
#    See https://github.com/wootsup/yt-builder-mcp/releases

# 2. Generate a Bearer key.
#    WordPress: wp-admin → Tools → "YT Builder MCP" → Bearer Keys.
#    Joomla:    Administrator → Components → "YT Builder MCP" → Bearer Keys.
#    Key format: ytb_(live|test)_<payloadB64Url>.<sigB64Url>
#    The key is shown ONCE. Copy it now; it cannot be recovered later.

# 3. Run the wizard to configure your AI client(s):
npx -y @wootsup/yt-builder-mcp setup

# 4. (Optional) Install the bundled agent skill:
npx -y @wootsup/yt-builder-mcp install-skill

# 5. Restart your AI client.

The wizard prompts for:

Your site URL (WordPress or Joomla).
The Bearer key you just generated.
Which AI client(s) to configure (multi-select).

It probes the host plugin's /health endpoint (/wp-json/yt-builder-mcp/v1/health on WordPress, /api/index.php/v1/yt-builder-mcp/health on Joomla) to confirm the plugin is reachable, then /etag to validate the Bearer key. After restart you should see the new tools prefixed with yootheme_builder_*.

Supported AI clients

The wizard auto-detects and configures the following clients:

Client	Config path	Notes
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)	DXT bundle also supported (see below)
Claude Code	`~/.claude.json`
Cursor	`~/.cursor/mcp.json`
Zed	`~/.config/zed/settings.json`
Continue	`~/.continue/config.json`
Cline	`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`	VS Code extension
Roo Code	same VS Code globalStorage path under `rooveterinaryinc.roo-cline`	VS Code extension
Codex CLI	`~/.codex/config.toml`
Gemini CLI	`~/.gemini/settings.json`

Tool surface (gateway model)

The server registers 31 domain tools + 1 gateway = 32 reachable tools, of which 27 are advertised in tools/list (well under Cursor's ~40-tool cap):

2 direct top-level tools (always in tools/list): yootheme_builder_health, yootheme_builder_diagnose. The "the gateway itself might be broken" escape hatch.
24 essential forwarded tools (always in tools/list): the most-used reads and writes (pages_list, pages_create, pages_delete, page_dynamize, get_etag, element_list, element_add, element_update_settings, sources_list, element_types_list, inspect_multi_items_binding, the multi-site sites_list / sites_test / use_site, and the bind→save→publish chain element_bind_source / page_save / page_publish, among others).
1 gateway tool (yootheme_builder_advanced): exposes the remaining 5 advanced tools behind a single entry (page_get_schema, element_get_binding, element_unbind_source, clean_implode_directives, inspect_sublayout). Call yootheme_builder_advanced({ tool: "<name>" }) for discovery (returns the schema) or ({ tool, arguments }) to execute.

See skills/yt-builder-mcp/SKILL.md for the full catalog and canonical workflows, and docs/TOOL-CATALOG.md for an auto-generated reference.

Tool catalogue

Domain	Count	Tools
Health	2	`health`, `diagnose`
Sites	2	`sites_list`, `sites_test`
Pages	7	`pages_list`, `page_get_layout`, `page_get_schema`, `template_summary`, `get_etag`, `page_save`, `page_publish`
Elements	7	`element_list`, `element_get`, `element_add`, `element_update_settings`, `element_move`, `element_clone`, `element_delete`
Sources	5	`sources_list`, `element_get_binding`, `element_bind_source`, `element_unbind_source`, `inspect_multi_items_binding`
Inspection	3	`element_types_list`, `element_type_get_schema`, `clean_implode_directives`
Sublayout	1	`inspect_sublayout` (F154 — fragment subtree + render-time inner-grid gate; advanced/gateway-routed)
Gateway	1	`advanced`

All tool names are prefixed with yootheme_builder_ at the MCP server boundary.

Subcommands

yt-builder-mcp setup            Interactive first-run wizard (default).
yt-builder-mcp install-skill    Install the bundled agent skill.
yt-builder-mcp --version, -v    Print package version.
yt-builder-mcp --help, -h       Show usage.

`install-skill` (bundled agent skill)

Copies the bundled skills/yootheme-builder/ folder into ~/.claude/skills/ and appends a marker block to ~/AGENTS.md so other AI clients pick it up automatically.

~/.claude/skills/ is the universal marker path recognised by Claude Desktop and (per the same convention as @wootsup/apimapper-mcp) other AI clients that follow the ~/AGENTS.md discovery protocol. The single location keeps the skill discoverable across every supported client without per-client write logic.

The skill ships with the 5 canonical workflows (build hero, bind source, clone section, diagnose 401, add custom element) plus a 26-tool auto-generated catalog appendix.

DXT bundle (Claude Desktop one-click install)

The repo includes a manifest.json and scripts/build-dxt.js that produces a yt-builder-mcp.dxt archive, the Desktop Extension format used by Claude Desktop for one-click MCP installs. Build it from a source checkout:

npm run build:dxt
# → ./yt-builder-mcp.dxt

Drop the .dxt file onto Claude Desktop's Extensions screen to install. The bundle includes the compiled dist/, the bundled skill, and manifest.json.

Environment variables

When launched by an AI client (or directly):

Variable	Required?	Purpose
`YTB_MCP_SITE_URL`	Yes	Host CMS base URL (e.g. `https://example.com`). Works for BOTH WordPress and Joomla. Trailing slash is stripped.
`YTB_MCP_WP_URL`	No (deprecated)	Legacy alias for `YTB_MCP_SITE_URL`. Still honoured for older WordPress-only configurations. A non-fatal deprecation notice is written to stderr when this is used without `YTB_MCP_SITE_URL`.
`YTB_MCP_BEARER_TOKEN`	Yes	Bearer key from wp-admin (WordPress: Tools → "YT Builder MCP") or Administrator → Components → "YT Builder MCP" (Joomla). Format-checked client-side: must match `ytb_(live\|test)_<payload>.<sig>`. Do not prepend `Bearer` . The MCP server adds it.
`YTB_MCP_PLATFORM`	No	Explicit platform hint: `wordpress` or `joomla`. Set to `joomla` when `YTB_MCP_SITE_URL` is an origin-only Joomla URL (no `/api/index.php/` in the path). Defaults to URL-shape auto-detection.
`YTB_MCP_TIMEOUT_MS`	No	REST timeout (default 15000).
`YTB_MCP_TEST_MODE`	No	`1` skips the stdio loop (smoke tests).

Manual MCP config (no wizard)

For users who don't want to run the wizard, paste this into your AI client's MCP config file:

{
  "mcpServers": {
    "yt-builder-mcp": {
      "command": "npx",
      "args": ["-y", "@wootsup/yt-builder-mcp"],
      "env": {
        "YTB_MCP_SITE_URL": "https://example.com",
        "YTB_MCP_BEARER_TOKEN": "ytb_live_…"
      }
    }
  }
}

For a Joomla install at an origin-only URL, also set the platform hint:

"env": {
  "YTB_MCP_SITE_URL": "https://example.com/joomla",
  "YTB_MCP_BEARER_TOKEN": "ytb_live_…",
  "YTB_MCP_PLATFORM": "joomla"
}

Non-interactive CI usage

For scripted / CI installs, pass the answers as flags and add --non-interactive to skip every prompt. Missing required flags exit with code 2 and a clear error to stderr:

npx -y @wootsup/yt-builder-mcp setup \
  --non-interactive \
  --client cursor --client claude-desktop \
  --url https://dev.wootsup.com/wordpress \
  --token "$YTB_TOKEN"

Supported flags:

Flag	Required?	Description
`--non-interactive`	Yes	Opt-in to non-interactive mode (no prompts).
`--url <site-url>`	Yes	Site base URL (WordPress or Joomla). Trailing slash is stripped.
`--token <bearer>`	Yes	Bearer key from the host plugin's admin UI (do not prepend `Bearer` ).
`--client <id>`	Yes (≥1)	Client id; repeatable. Valid ids: `claude-desktop`, `claude-code`, `cursor`, `zed`, `continue`, `cline`, `roo-code`, `codex-cli`, `gemini-cli`.

The wizard still runs its plugin-health + auth probes and uses the exit codes documented in the table below, so CI can branch on the exit code to detect whether the install actually succeeded.

Exit codes (CLI)

The CLI returns POSIX-style exit codes for scripting / CI:

Code	Meaning
0	Success
1	Invalid input / unknown subcommand
2	Health probe failed and user declined to continue (or install-skill failure)
3	Auth probe failed and user declined to continue
4	Write failed; configs rolled back
5	Handshake failed; configs rolled back
99	Unhandled fatal in dispatcher
130	User cancelled (SIGINT)

Documentation

SKILL.md (bundled agent skill): 5 canonical workflows, gateway model, tool catalog
REST API Reference
MCP Tool Reference

Repository

https://github.com/wootsup/yt-builder-mcp

Keywords

mcp model-context-protocol yootheme yootheme-pro wordpress claude claude-code cursor codex-cli gemini-cli page-builder ai-assistant wootsup