@wootsup/yt-builder-mcp 1.1.0 → 1.1.6

package/README.md

@@ -1,6 +1,6 @@
-# @wootsup/yt-builder-mcp — YT Builder MCP for YOOtheme Pro (unofficial)
+# @wootsup/yt-builder-mcp. YT Builder MCP for YOOtheme Pro (unofficial)
 
-> Drive your page builder via MCP. Built for YOOtheme Pro 4.0+ — connect **Claude Desktop**, **Cursor**, **Continue**, **Zed**, **Cline**, or **Roo Code** in one command.
+> 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](https://yootheme.com)). YT Builder MCP is built by WootsUp (getimo
@@ -8,20 +8,22 @@
 > The integration uses YOOtheme Pro's public extension points.
 
 **License:** MIT
-**Status:** Pre-alpha — under active development.
 
 ---
 
 ## Quick start
 
 ```bash
-# 1. Install the WordPress plugin (yt-builder-mcp).
-#    See https://wootsup.com/products/yt-builder-mcp
-
-# 2. Generate a Bearer key in
-#    wp-admin → Tools → "YT Builder MCP" → Bearer Keys → Generate New Key.
+# 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.
+#    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
@@ -34,67 +36,66 @@ npx -y @wootsup/yt-builder-mcp install-skill
 
 The wizard prompts for:
 
-1. Your WordPress site URL.
+1. Your site URL (WordPress or Joomla).
 2. The Bearer key you just generated.
 3. Which AI client(s) to configure (multi-select).
 
-It probes `/wp-json/yt-builder-mcp/v1/health` to confirm the
-plugin is reachable, `/etag` to validate the Bearer key, then writes
-the MCP server entry into each selected client's config file. After
-restart you should see the new tools prefixed with `yootheme_builder_*`.
+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 (6)
+## 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` | |
-| Continue | `~/.continue/config.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
+## Tool surface (gateway model)
 
-The server registers **24 tools total**, but only **11 entries appear
-in `tools/list`** (well under Cursor's ~40-tool cap):
+The server registers **26 domain tools + 1 gateway = 27 reachable** tools,
+of which **20 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
+  `yootheme_builder_health`, `yootheme_builder_diagnose`. The
   "the gateway itself might be broken" escape hatch.
-- **8 essential forwarded tools** (always in `tools/list`): the most-
-  used reads and writes — `pages_list`, `get_etag`, `element_list`,
-  `element_add`, `element_update_settings`, `sources_list`,
-  `element_types_list`, `inspect_multi_items_binding`.
-- **1 gateway tool** (`yootheme_builder_advanced`): exposes the
-  remaining **13 advanced tools** behind a single entry. Call
-  `yootheme_builder_advanced({ tool: "<name>" })` for discovery
-  (returns the schema) or `({ tool, arguments })` to execute.
-- **13 advanced tools** dispatched via the gateway (page_get_layout,
-  page_get_schema, page_save, page_publish, element_get,
-  element_move, element_clone, element_delete,
-  element_get_binding, element_bind_source, element_unbind_source,
-  clean_implode_directives, element_type_get_schema).
-
-Total: **23 domain tools + 1 gateway = 24**. Surface: **11 entries
-in tools/list**. See `skills/yt-builder-mcp/SKILL.md` for the
-full catalog and the 5 canonical workflows.
-
-## Tool catalogue — 23 domain tools
+- **17 essential forwarded tools** (always in `tools/list`): the most-used
+  reads and writes (`pages_list`, `get_etag`, `element_list`, `element_add`,
+  `element_update_settings`, `sources_list`, `element_types_list`,
+  `inspect_multi_items_binding`, and the multi-site `sites_list` / `sites_test`,
+  among others).
+- **1 gateway tool** (`yootheme_builder_advanced`): exposes the remaining
+  **7 advanced tools** behind a single entry. 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`                                                                                                                                                |
-| Pages       |     6 | `pages_list`, `page_get_layout`, `page_get_schema`, `get_etag`, `page_save`, `page_publish`                                                                          |
+| 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     |     4 | `sources_list`, `element_get_binding`, `element_bind_source`, `element_unbind_source`                                                                                |
-| Multi-Items |     2 | `inspect_multi_items_binding`, `clean_implode_directives`                                                                                                            |
-| Inspection  |     2 | `element_types_list`, `element_type_get_schema`                                                                                                                      |
+| 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`                                                                                         |
+| Gateway     |     1 | `advanced`                                                                                                                                                          |
 
-All tool names are prefixed with `yootheme_builder_` at the MCP
-server boundary.
+All tool names are prefixed with `yootheme_builder_` at the MCP server boundary.
 
 ## Subcommands
 
@@ -105,7 +106,7 @@ yt-builder-mcp --version, -v    Print package version.
 yt-builder-mcp --help, -h       Show usage.
 ```
 
-### `install-skill` — bundled agent skill
+### `install-skill` (bundled agent skill)
 
 Copies the bundled `skills/yootheme-builder/` folder into
 `~/.claude/skills/` and appends a marker block to `~/AGENTS.md` so
@@ -121,10 +122,10 @@ The skill ships with the 5 canonical workflows (build hero, bind
 source, clone section, diagnose 401, add custom element) plus a
 23-tool auto-generated catalog appendix.
 
-## DXT bundle — Claude Desktop one-click install
+## 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
+produces a `yt-builder-mcp.dxt` archive, the
 [Desktop Extension](https://github.com/anthropics/dxt) format used
 by Claude Desktop for one-click MCP installs. Build it from a
 source checkout:
@@ -145,8 +146,8 @@ 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 pre-Wave-7 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_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). |
@@ -200,12 +201,12 @@ Supported flags:
 | Flag | Required? | Description |
 |------|-----------|-------------|
 | `--non-interactive` | Yes | Opt-in to non-interactive mode (no prompts). |
-| `--url <wp-url>` | Yes | WordPress base URL; trailing slash is stripped. |
-| `--token <bearer>` | Yes | Bearer key from wp-admin (do not prepend `Bearer `). |
-| `--client <id>` | Yes (≥1) | Client id; repeatable. Valid ids: `claude-desktop`, `cursor`, `zed`, `continue`, `cline`, `roo-code`. |
+| `--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 codes documented in the table below, so CI can branch on the
 exit code to detect whether the install actually succeeded.
 
 ## Exit codes (CLI)
@@ -225,7 +226,7 @@ The CLI returns POSIX-style exit codes for scripting / CI:
 
 ## Documentation
 
-- [SKILL.md (bundled agent skill)](./skills/yt-builder-mcp/SKILL.md) — 5 canonical workflows, gateway model, tool catalog
+- [SKILL.md (bundled agent skill)](./skills/yt-builder-mcp/SKILL.md): 5 canonical workflows, gateway model, tool catalog
 - [REST API Reference](https://github.com/wootsup/yt-builder-mcp/blob/main/docs/rest-api-reference.md)
 - [MCP Tool Reference](https://github.com/wootsup/yt-builder-mcp/blob/main/docs/mcp-tool-reference.md)
 

package/manifest.json

@@ -2,7 +2,7 @@
     "dxt_version": "0.1",
     "name": "@wootsup/yt-builder-mcp",
     "display_name": "YT Builder MCP for YOOtheme Pro (unofficial)",
-    "version": "1.1.0",
+    "version": "1.1.6",
     "description": "Drive your YOOtheme Pro Page Builder programmatically from Claude, Cursor, Codex, Gemini and 5 other MCP-capable AI assistants — read layouts, edit settings, add elements, bind dynamic sources. Works on WordPress and Joomla 5/6. Built for YOOtheme Pro 4.0+. Independent third-party project, not affiliated with YOOtheme GmbH.",
     "long_description": "YT Builder MCP gives AI assistants a typed, scoped, and idempotent surface for your YOOtheme Pro Page Builder, on either WordPress or Joomla 5/6. Tools cover page discovery, layout inspection, element CRUD, source binding, and diagnostics. Bearer auth, optimistic locking via ETag, scope hierarchy (read < write < admin), and structured-error responses keep the agent safe and the workflow correct on first try. 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.",
     "icon": "icon.png",
@@ -47,31 +47,31 @@
         }
     },
     "user_config": {
-        "YTB_MCP_SITES_FILE": {
+        "YTB_MCP_SITE_URL": {
             "type": "string",
-            "title": "Sites registry file (multi-site mode)",
-            "description": "Path to sites.json for multi-site setups (e.g. ~/.config/yt-builder-mcp/sites.json). When set, the legacy YTB_MCP_SITE_URL / YTB_MCP_BEARER_TOKEN fields are ignored. Create via `npx -y @wootsup/yt-builder-mcp add-site`.",
+            "title": "Site URL (connect one site)",
+            "description": "Fill this if you connect a SINGLE site (most people). The address of your YOOtheme site, e.g. https://example.com, or https://example.com/wordpress if WordPress runs in a subfolder. No trailing slash. Leave empty if you use the Sites file below.",
             "required": false
         },
-        "YTB_MCP_SITE_URL": {
+        "YTB_MCP_BEARER_TOKEN": {
             "type": "string",
-            "title": "Site URL",
-            "description": "Base URL of the site (e.g. https://example.com, https://example.com/wordpress for subdir WordPress, https://example.com/joomla for subdir Joomla). Without trailing slash.",
-            "required": false
+            "title": "Bearer token (for that one site)",
+            "description": "Fill this if you connect a SINGLE site. Paste the key you generated in your CMS admin: WordPress under Tools, YT Builder MCP; Joomla under Components, YT Builder MCP, then Generate Key. The 'write' scope is enough. Leave empty if you use the Sites file below.",
+            "required": false,
+            "sensitive": true
         },
         "YTB_MCP_PLATFORM": {
             "type": "string",
-            "title": "Platform (optional)",
-            "description": "CMS platform hint. Allowed values: \"auto\" (default — auto-detect from URL path and, if ambiguous, runtime-probe both platforms' /health endpoints), \"wordpress\", or \"joomla\". Set explicitly only to override auto-detection (e.g. when the host blocks anonymous health probes).",
+            "title": "Platform (one site, optional)",
+            "description": "Leave this on 'auto'. The server detects WordPress or Joomla by itself. Only set 'wordpress' or 'joomla' if your host blocks the automatic check.",
             "required": false,
             "default": "auto"
         },
-        "YTB_MCP_BEARER_TOKEN": {
+        "YTB_MCP_SITES_FILE": {
             "type": "string",
-            "title": "Bearer token",
-            "description": "Bearer token generated in the YT Builder MCP admin UI (WordPress: Tools → YT Builder MCP; Joomla: Components → YT Builder MCP) → Generate Key. Scope: write is sufficient for most agent workflows; admin only for key-management.",
-            "required": false,
-            "sensitive": true
+            "title": "Sites file (connect many sites, advanced)",
+            "description": "Only for managing several sites from one install (agencies). Path to a sites.json, e.g. /Users/you/.config/yt-builder-mcp/sites.json. Create and fill it with: npx -y @wootsup/yt-builder-mcp add-site (do not hand-edit). When set, the three single-site fields above are ignored. Most people leave this empty.",
+            "required": false
         }
     },
     "compatibility": {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@wootsup/yt-builder-mcp",
-    "version": "1.1.0",
+    "version": "1.1.6",
     "type": "module",
     "description": "YT Builder MCP — drive your page builder from Claude, Cursor, Codex, Gemini and 5 other MCP-capable AI assistants. Built for YOOtheme Pro 4.0+. Independent third-party project, not affiliated with YOOtheme GmbH.",
     "license": "MIT",
@@ -66,6 +66,7 @@
         "@modelcontextprotocol/sdk": "^1.27.0",
         "@clack/prompts": "^0.7.0",
         "pino": "^10.3.1",
+        "proper-lockfile": "^4.1.2",
         "zod": "^4.3.6"
     },
     "devDependencies": {
@@ -75,7 +76,6 @@
         "@typescript-eslint/parser": "^8.0.0",
         "@vitest/coverage-v8": "^1.4.0",
         "eslint": "^9.0.0",
-        "proper-lockfile": "^4.1.2",
         "typescript": "^5.4.0",
         "typescript-eslint": "^8.0.0",
         "vitest": "^1.4.0"