@wootsup/yt-builder-mcp 1.1.6 → 1.2.0

package/dist/gateway/capturing-server.js

@@ -0,0 +1,103 @@
+/**
+ * CapturingServer — registration interceptor wrapping a real McpServer.
+ *
+ * Tool routing (Wave G.1 / Design-Doc §3.1.1):
+ *   - L3 direct (yootheme_builder_health, yootheme_builder_diagnose):
+ *     skipped — no forward, no capture. These tools must already be
+ *     registered directly on the real server BEFORE the CapturingServer
+ *     wraps it, so the SDK never sees a duplicate name.
+ *   - L1 essential (ESSENTIAL_TOOLS): forwarded to the real server as a
+ *     first-class MCP tool reachable from `tools/list`.
+ *   - L2 advanced (everything else): captured into the in-process
+ *     advanced registry, reachable through the single
+ *     `yootheme_builder_advanced` gateway tool.
+ *
+ * This is a typed wrapper, NOT a JS Proxy — TypeScript stays strict.
+ *
+ * Typing approach (mirrors the reference apimapper-mcp implementation):
+ *   `ToolRegistrar` is the McpServer subsurface modules consume:
+ *   `registerTool` + `registerResource`. `registerTool` is a hand-written
+ *   generic mirroring the SDK signature EXCEPT its return type is `void`
+ *   — captured tools have no live `RegisteredTool`, and no module reads
+ *   the return value. A real `McpServer` is still assignable to
+ *   `ToolRegistrar` (return-type bivariance for `void`), so every
+ *   call-site accepts both shapes cast-free.
+ *
+ * Casts in this file (each documented + justified inline):
+ *   1. forwarded-essential — erases the handler's `InputArgs` generic to
+ *      the SDK default when `config` is the erased `CapturedToolConfig`.
+ *   2. registry storage — erases the generic handler to the homogeneous
+ *      `CapturedToolHandler` shape so one Map type fits all entries.
+ *   3. `registerResource` field — the SDK declares two overloads; a
+ *      single spread-arg arrow cannot re-express the pair.
+ *
+ * @license MIT
+ */
+import { isDirectTopLevel, isEssential } from './essentials.js';
+/**
+ * Wraps a real McpServer. Forwards L1 essentials (and all resources) to it,
+ * captures L2 non-essentials into an in-process registry, and silently
+ * skips L3 direct top-level names that must already be on the real server.
+ */
+export class CapturingServer {
+    realServer;
+    advancedRegistry = new Map();
+    constructor(realServer) {
+        this.realServer = realServer;
+    }
+    /**
+     * Routes a tool registration by name. Returns `void`: captured tools
+     * have no `RegisteredTool` and no `registerXTools` module reads the
+     * return value.
+     *
+     * Routing order matters: the L3-direct check is FIRST so a caller
+     * cannot accidentally re-route a direct-registered name through the
+     * gateway just by re-naming a future tool builder.
+     */
+    registerTool(name, config, handler) {
+        // L3 — direct top-level: already on the real server, do nothing.
+        // Returning early here prevents the SDK from raising a duplicate-name
+        // error when an L3 tool's builder is accidentally re-included in the
+        // forwarded tool list.
+        if (isDirectTopLevel(name)) {
+            return;
+        }
+        if (isEssential(name)) {
+            // L1 — forward to the real server.
+            //
+            // Cast: the SDK pairs `config.inputSchema` and the handler through
+            // one `InputArgs` generic. Here `config` is the erased
+            // `CapturedToolConfig`, so the SDK cannot re-infer that link; the
+            // handler is asserted to the SDK's default `ToolCallback` to satisfy
+            // the call. The runtime values are exactly what the SDK expects —
+            // only the static generic linkage is erased.
+            this.realServer.registerTool(name, config, handler);
+            return;
+        }
+        // L2 — capture into the advanced registry.
+        //
+        // Erase the generic handler to the captured-handler shape for
+        // homogeneous Map storage. The gateway validates `arguments` against
+        // the tool's Zod schema before invoking it, so the (args, extra)
+        // runtime contract holds.
+        this.advancedRegistry.set(name, {
+            config,
+            handler: handler,
+        });
+    }
+    /**
+     * Resources are always forwarded — they are not part of the tool cap.
+     *
+     * Cast: the SDK declares `registerResource` as two overloads; a single
+     * spread `(...args: RegisterResourceArgs)` arrow cannot re-express that
+     * overload pair, so the field is asserted to the SDK's exact member
+     * type. The spread forwards every argument verbatim, so the runtime
+     * contract is unchanged.
+     */
+    registerResource = ((...args) => this.realServer.registerResource(...args));
+    /** The captured non-essential tools, keyed by tool name. */
+    getAdvancedRegistry() {
+        return this.advancedRegistry;
+    }
+}
+//# sourceMappingURL=capturing-server.js.map

package/dist/gateway/capturing-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capturing-server.js","sourceRoot":"","sources":["../../src/gateway/capturing-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAMH,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA8DhE;;;;GAIG;AACH,MAAM,OAAO,eAAe;IACP,UAAU,CAAY;IACtB,gBAAgB,GAAG,IAAI,GAAG,EAA6B,CAAC;IAEzE,YAAY,UAAqB;QAC7B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IACjC,CAAC;IAED;;;;;;;;OAQG;IACH,YAAY,CACR,IAAY,EACZ,MAA0B,EAC1B,OAAgC;QAEhC,iEAAiE;QACjE,sEAAsE;QACtE,qEAAqE;QACrE,uBAAuB;QACvB,IAAI,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,OAAO;QACX,CAAC;QAED,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,mCAAmC;YACnC,EAAE;YACF,mEAAmE;YACnE,uDAAuD;YACvD,kEAAkE;YAClE,qEAAqE;YACrE,kEAAkE;YAClE,6CAA6C;YAC7C,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAuB,CAAC,CAAC;YACpE,OAAO;QACX,CAAC;QAED,2CAA2C;QAC3C,EAAE;QACF,8DAA8D;QAC9D,qEAAqE;QACrE,iEAAiE;QACjE,0BAA0B;QAC1B,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,EAAE;YAC5B,MAAM;YACN,OAAO,EAAE,OAAyC;SACrD,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;;OAQG;IACH,gBAAgB,GAAkC,CAAC,CAAC,GAAG,IAA0B,EAAE,EAAE,CACjF,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC,CAAkC,CAAC;IAEhF,4DAA4D;IAC5D,mBAAmB;QACf,OAAO,IAAI,CAAC,gBAAgB,CAAC;IACjC,CAAC;CACJ"}

package/dist/gateway/essentials.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Gateway-Hub — single source of truth for the YT Builder MCP
+ * 3-lane registration surface.
+ *
+ * Lanes (Wave G.1 / Design-Doc §3.1.1):
+ *   L1 — ESSENTIAL_TOOLS         forwarded by the CapturingServer as
+ *                                 first-class MCP tools in `tools/list`.
+ *   L2 — (advanced)              every NON-essential, NON-direct tool is
+ *                                 captured by the CapturingServer and
+ *                                 reachable through the single
+ *                                 `yootheme_builder_advanced` gateway tool.
+ *   L3 — DIRECT_TOP_LEVEL_TOOLS  registered directly on the real McpServer
+ *                                 BEFORE the CapturingServer wraps it.
+ *                                 The CapturingServer skips these names
+ *                                 entirely (no forward, no capture) so the
+ *                                 SDK never sees a duplicate registration.
+ *
+ * Why this split: Cursor caps MCP servers at ~40 tools. This adapter
+ * declares 30 callable tools (22 domain L1/L3 + 7 advanced L2 + 1 gateway).
+ * The 3-lane shape keeps `tools/list` at 20 (L1) + 2 (L3) + 1 (gateway) =
+ * 23 entries, well under the cap, while every tool stays fully reachable
+ * (advanced tools through `yootheme_builder_advanced`).
+ *
+ * Health + diagnose live in L3 because they MUST be the first thing an
+ * LLM-host calls when something is broken; routing them through a gateway
+ * would create a chicken-and-egg loop (the LLM would have to discover
+ * the gateway before it can diagnose why the gateway is unreachable).
+ *
+ * @license MIT
+ */
+/**
+ * L1 — Tools kept as first-class entries in `tools/list`.
+ * Forwarded by the CapturingServer to the real McpServer.
+ */
+export declare const ESSENTIAL_TOOLS: readonly ["yootheme_builder_pages_list", "yootheme_builder_get_etag", "yootheme_builder_element_list", "yootheme_builder_element_add", "yootheme_builder_element_update_settings", "yootheme_builder_sources_list", "yootheme_builder_element_types_list", "yootheme_builder_inspect_multi_items_binding", "yootheme_builder_element_get", "yootheme_builder_element_delete", "yootheme_builder_element_clone", "yootheme_builder_element_move", "yootheme_builder_page_get_layout", "yootheme_builder_template_summary", "yootheme_builder_element_type_get_schema", "yootheme_builder_sites_list", "yootheme_builder_sites_test", "yootheme_builder_use_site", "yootheme_builder_pages_create", "yootheme_builder_pages_delete"];
+/**
+ * L3 — Tools registered DIRECTLY on the real McpServer, BEFORE the
+ * CapturingServer wraps it. The CapturingServer treats these names as a
+ * no-op (no forward, no capture) so the SDK never sees a duplicate
+ * registration. Use this lane only for tools that must be reachable
+ * even if the gateway itself fails — currently health + diagnose.
+ */
+export declare const DIRECT_TOP_LEVEL_TOOLS: readonly ["yootheme_builder_health", "yootheme_builder_diagnose"];
+export type EssentialTool = (typeof ESSENTIAL_TOOLS)[number];
+export type DirectTopLevelTool = (typeof DIRECT_TOP_LEVEL_TOOLS)[number];
+/** True if `name` is in the L1 forwarded essentials surface. */
+export declare function isEssential(name: string): boolean;
+/** True if `name` is in the L3 direct top-level surface. */
+export declare function isDirectTopLevel(name: string): boolean;
+//# sourceMappingURL=essentials.d.ts.map

package/dist/gateway/essentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"essentials.d.ts","sourceRoot":"","sources":["../../src/gateway/essentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;GAGG;AACH,eAAO,MAAM,eAAe,osBAqDlB,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,mEAGzB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7D,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD"}

package/dist/gateway/essentials.js

@@ -0,0 +1,108 @@
+/**
+ * Gateway-Hub — single source of truth for the YT Builder MCP
+ * 3-lane registration surface.
+ *
+ * Lanes (Wave G.1 / Design-Doc §3.1.1):
+ *   L1 — ESSENTIAL_TOOLS         forwarded by the CapturingServer as
+ *                                 first-class MCP tools in `tools/list`.
+ *   L2 — (advanced)              every NON-essential, NON-direct tool is
+ *                                 captured by the CapturingServer and
+ *                                 reachable through the single
+ *                                 `yootheme_builder_advanced` gateway tool.
+ *   L3 — DIRECT_TOP_LEVEL_TOOLS  registered directly on the real McpServer
+ *                                 BEFORE the CapturingServer wraps it.
+ *                                 The CapturingServer skips these names
+ *                                 entirely (no forward, no capture) so the
+ *                                 SDK never sees a duplicate registration.
+ *
+ * Why this split: Cursor caps MCP servers at ~40 tools. This adapter
+ * declares 30 callable tools (22 domain L1/L3 + 7 advanced L2 + 1 gateway).
+ * The 3-lane shape keeps `tools/list` at 20 (L1) + 2 (L3) + 1 (gateway) =
+ * 23 entries, well under the cap, while every tool stays fully reachable
+ * (advanced tools through `yootheme_builder_advanced`).
+ *
+ * Health + diagnose live in L3 because they MUST be the first thing an
+ * LLM-host calls when something is broken; routing them through a gateway
+ * would create a chicken-and-egg loop (the LLM would have to discover
+ * the gateway before it can diagnose why the gateway is unreachable).
+ *
+ * @license MIT
+ */
+/**
+ * L1 — Tools kept as first-class entries in `tools/list`.
+ * Forwarded by the CapturingServer to the real McpServer.
+ */
+export const ESSENTIAL_TOOLS = [
+    'yootheme_builder_pages_list',
+    'yootheme_builder_get_etag',
+    'yootheme_builder_element_list',
+    'yootheme_builder_element_add',
+    'yootheme_builder_element_update_settings',
+    'yootheme_builder_sources_list',
+    'yootheme_builder_element_types_list',
+    // Multi-Items inspector — L1 discovery tool. Surfaces when a
+    // binding lives on the wrong (container) level and which `*_item`
+    // child should carry it. Frequent first-call when diagnosing
+    // Grid/Slider/Switcher rendering issues.
+    'yootheme_builder_inspect_multi_items_binding',
+    // F-16 hot-path promotions (Maria-Audit v2 re-confirmed) — the 5
+    // most-used read/mutate operations skip the advanced-router
+    // discovery roundtrip. Cursor cap is ~40; with the W7 sites_list +
+    // sites_test additions (plus later C4 + config-harmonization) we sit
+    // at 20 L1 + 2 L3 + 1 gateway = 23, comfortable below the limit.
+    'yootheme_builder_element_get',
+    'yootheme_builder_element_delete',
+    'yootheme_builder_element_clone',
+    'yootheme_builder_element_move',
+    'yootheme_builder_page_get_layout',
+    // T9 (Audit-v3 B.5) — token-efficient template overview. L1 because
+    // it's the recommended first call when orienting in a large template.
+    'yootheme_builder_template_summary',
+    // 1.0.1 — element_type_get_schema promoted L2 → L1. Live-testing
+    // 1.0.0 in Claude Desktop showed tool_search couldn't surface it
+    // through the advanced gateway, yet it is the canonical prop-key
+    // discovery tool an agent needs BEFORE every element_add or
+    // element_update_settings. Hot-path for any write workflow.
+    'yootheme_builder_element_type_get_schema',
+    // W7 (Multi-Site) — sites_list + sites_test must be L1 so an agent
+    // that just connected to a fresh MCP server can answer "which sites
+    // am I configured against?" without first discovering the gateway.
+    // Both are platform-agnostic (sites_list reads the registry only,
+    // sites_test probes /health + /etag for ONE site). L1 surface 15 → 17.
+    'yootheme_builder_sites_list',
+    'yootheme_builder_sites_test',
+    // Phase 3 (config harmonization) — use_site is the runtime active-
+    // site SWITCH (mirrors api-mapper's apimapper_use_profile). It must
+    // be L1 so an agent can discover + call it directly the same way it
+    // reaches sites_list, instead of routing through the advanced
+    // gateway. L1 surface 19 → 20.
+    'yootheme_builder_use_site',
+    // C4 (v1.2) — pages_create + pages_delete are first-class customer-
+    // facing page-level mutations (POST /pages, DELETE /pages/{id}).
+    // Both must be discoverable directly in tools/list, not behind the
+    // advanced-gateway router — they're high-frequency mutations agents
+    // reach for whenever the user says "create a new page" or "delete
+    // this page". L1 surface 17 → 19.
+    'yootheme_builder_pages_create',
+    'yootheme_builder_pages_delete',
+];
+/**
+ * L3 — Tools registered DIRECTLY on the real McpServer, BEFORE the
+ * CapturingServer wraps it. The CapturingServer treats these names as a
+ * no-op (no forward, no capture) so the SDK never sees a duplicate
+ * registration. Use this lane only for tools that must be reachable
+ * even if the gateway itself fails — currently health + diagnose.
+ */
+export const DIRECT_TOP_LEVEL_TOOLS = [
+    'yootheme_builder_health',
+    'yootheme_builder_diagnose',
+];
+/** True if `name` is in the L1 forwarded essentials surface. */
+export function isEssential(name) {
+    return ESSENTIAL_TOOLS.includes(name);
+}
+/** True if `name` is in the L3 direct top-level surface. */
+export function isDirectTopLevel(name) {
+    return DIRECT_TOP_LEVEL_TOOLS.includes(name);
+}
+//# sourceMappingURL=essentials.js.map

package/dist/gateway/essentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"essentials.js","sourceRoot":"","sources":["../../src/gateway/essentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC3B,6BAA6B;IAC7B,2BAA2B;IAC3B,+BAA+B;IAC/B,8BAA8B;IAC9B,0CAA0C;IAC1C,+BAA+B;IAC/B,qCAAqC;IACrC,6DAA6D;IAC7D,kEAAkE;IAClE,6DAA6D;IAC7D,yCAAyC;IACzC,8CAA8C;IAC9C,iEAAiE;IACjE,4DAA4D;IAC5D,mEAAmE;IACnE,qEAAqE;IACrE,iEAAiE;IACjE,8BAA8B;IAC9B,iCAAiC;IACjC,gCAAgC;IAChC,+BAA+B;IAC/B,kCAAkC;IAClC,oEAAoE;IACpE,sEAAsE;IACtE,mCAAmC;IACnC,iEAAiE;IACjE,iEAAiE;IACjE,iEAAiE;IACjE,4DAA4D;IAC5D,4DAA4D;IAC5D,0CAA0C;IAC1C,mEAAmE;IACnE,oEAAoE;IACpE,mEAAmE;IACnE,kEAAkE;IAClE,uEAAuE;IACvE,6BAA6B;IAC7B,6BAA6B;IAC7B,mEAAmE;IACnE,oEAAoE;IACpE,oEAAoE;IACpE,8DAA8D;IAC9D,+BAA+B;IAC/B,2BAA2B;IAC3B,oEAAoE;IACpE,iEAAiE;IACjE,mEAAmE;IACnE,oEAAoE;IACpE,kEAAkE;IAClE,kCAAkC;IAClC,+BAA+B;IAC/B,+BAA+B;CACzB,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IAClC,yBAAyB;IACzB,2BAA2B;CACrB,CAAC;AAKX,gEAAgE;AAChE,MAAM,UAAU,WAAW,CAAC,IAAY;IACpC,OAAQ,eAAqC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACjE,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,gBAAgB,CAAC,IAAY;IACzC,OAAQ,sBAA4C,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACxE,CAAC"}

package/dist/gateway/test-support.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Gateway test helpers — Wave G.1.
+ *
+ * After the gateway lands, tests that previously looked tools up from
+ * `McpServer._registeredTools` no longer find advanced tools (they're
+ * captured in the advanced registry, not on the real server). These
+ * helpers expose a unified view across all three lanes:
+ *
+ *   - L1 essentials   → real server's `_registeredTools`
+ *   - L2 advanced     → CapturingServer's `getAdvancedRegistry()`
+ *   - L3 + gateway    → real server's `_registeredTools`
+ *
+ * Test-only: never imported by any runtime path.
+ *
+ * @license MIT
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { CapturingServer } from './capturing-server.js';
+/** A tool entry as seen by tests: handler + the registered config. */
+export interface CollectedTool {
+    handler: (args: Record<string, unknown>, extra?: unknown) => CallToolResult | Promise<CallToolResult>;
+    title?: string;
+    description?: string;
+    inputSchema?: unknown;
+    annotations?: Record<string, unknown>;
+}
+/**
+ * Returns every tool — essentials + gateway on the real McpServer plus
+ * the advanced tools captured by the CapturingServer — keyed by tool
+ * name. The CapturingServer must have been used to register the L1/L2
+ * tools, and `registerAdvancedTool` must have run, before this is called.
+ *
+ * Production size = 30:
+ *   20 L1 essentials (real server) + 7 L2 advanced (registry)
+ *   + 2 L3 direct (real server) + 1 gateway (real server) = 30.
+ */
+export declare function collectAllRegisteredTools(server: McpServer, capturing: CapturingServer): Record<string, CollectedTool>;
+/** By-name lookup over a `collectAllRegisteredTools` map. */
+export declare function findTool(tools: Record<string, CollectedTool>, name: string): CollectedTool | undefined;
+//# sourceMappingURL=test-support.d.ts.map

package/dist/gateway/test-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-support.d.ts","sourceRoot":"","sources":["../../src/gateway/test-support.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,CACL,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,CAAC,EAAE,OAAO,KACd,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACrC,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,eAAe,GAC3B,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAuC/B;AAED,6DAA6D;AAC7D,wBAAgB,QAAQ,CACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,EACpC,IAAI,EAAE,MAAM,GACb,aAAa,GAAG,SAAS,CAE3B"}

package/dist/gateway/test-support.js

@@ -0,0 +1,60 @@
+/**
+ * Gateway test helpers — Wave G.1.
+ *
+ * After the gateway lands, tests that previously looked tools up from
+ * `McpServer._registeredTools` no longer find advanced tools (they're
+ * captured in the advanced registry, not on the real server). These
+ * helpers expose a unified view across all three lanes:
+ *
+ *   - L1 essentials   → real server's `_registeredTools`
+ *   - L2 advanced     → CapturingServer's `getAdvancedRegistry()`
+ *   - L3 + gateway    → real server's `_registeredTools`
+ *
+ * Test-only: never imported by any runtime path.
+ *
+ * @license MIT
+ */
+/**
+ * Returns every tool — essentials + gateway on the real McpServer plus
+ * the advanced tools captured by the CapturingServer — keyed by tool
+ * name. The CapturingServer must have been used to register the L1/L2
+ * tools, and `registerAdvancedTool` must have run, before this is called.
+ *
+ * Production size = 30:
+ *   20 L1 essentials (real server) + 7 L2 advanced (registry)
+ *   + 2 L3 direct (real server) + 1 gateway (real server) = 30.
+ */
+export function collectAllRegisteredTools(server, capturing) {
+    const result = {};
+    // The SDK changed the internal field name from `handler` to `callback`
+    // over its 1.x lifetime; accept either to keep the helper resilient.
+    const real = server;
+    for (const [name, tool] of Object.entries(real._registeredTools)) {
+        const callback = 'callback' in tool && typeof tool.callback === 'function'
+            ? tool.callback
+            : tool.handler;
+        result[name] = {
+            handler: callback,
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: tool.annotations,
+        };
+    }
+    for (const [name, entry] of capturing.getAdvancedRegistry()) {
+        const cfg = entry.config;
+        result[name] = {
+            handler: entry.handler,
+            title: cfg.title,
+            description: cfg.description,
+            inputSchema: cfg.inputSchema,
+            annotations: cfg.annotations,
+        };
+    }
+    return result;
+}
+/** By-name lookup over a `collectAllRegisteredTools` map. */
+export function findTool(tools, name) {
+    return tools[name];
+}
+//# sourceMappingURL=test-support.js.map

package/dist/gateway/test-support.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-support.js","sourceRoot":"","sources":["../../src/gateway/test-support.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAmCH;;;;;;;;;GASG;AACH,MAAM,UAAU,yBAAyB,CACrC,MAAiB,EACjB,SAA0B;IAE1B,MAAM,MAAM,GAAkC,EAAE,CAAC;IAEjD,uEAAuE;IACvE,qEAAqE;IACrE,MAAM,IAAI,GAAG,MAEZ,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC/D,MAAM,QAAQ,GACV,UAAU,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,UAAU;YACrD,CAAC,CAAC,IAAI,CAAC,QAAQ;YACf,CAAC,CAAE,IAAiC,CAAC,OAAO,CAAC;QACrD,MAAM,CAAC,IAAI,CAAC,GAAG;YACX,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;SAChC,CAAC;IACN,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,SAAS,CAAC,mBAAmB,EAAE,EAAE,CAAC;QAC1D,MAAM,GAAG,GAAG,KAAK,CAAC,MAKjB,CAAC;QACF,MAAM,CAAC,IAAI,CAAC,GAAG;YACX,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,WAAW,EAAE,GAAG,CAAC,WAAW;SAC/B,CAAC;IACN,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,QAAQ,CACpB,KAAoC,EACpC,IAAY;IAEZ,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * MCP server entrypoint (stdio transport).
+ *
+ * Reads config from environment variables (see `auth.ts`), spins up a
+ * `McpServer` with all tools registered, connects to stdio, and lets
+ * the host (Claude Desktop / Cursor / Zed / …) drive.
+ *
+ * `YTB_MCP_TEST_MODE=1` short-circuits: prints the tool registry and
+ * exits 0. Used by the smoke test and by `release.php` to validate
+ * that the bundled `dist/` is loadable on the target Node version.
+ *
+ * @license MIT
+ */
+export { createServer, SERVER_NAME, SERVER_VERSION } from './server.js';
+export { RestClient, REST_NAMESPACE_PATH, encodeElementPath } from './client.js';
+export { loadConfig, loadRegistry, isTestMode, ENV_SITE_URL, ENV_WP_URL, ENV_BEARER, ENV_SITES_FILE, ENV_PLATFORM, ENV_PROFILE, ENV_TEST_MODE, } from './auth.js';
+export { bootstrapActiveSite } from './sites/bootstrap.js';
+export { ConfigError, RestError, NetworkError } from './errors.js';
+export { buildAllTools } from './tools/index.js';
+export { ClientPool, NoDefaultSiteError, UnknownSiteError } from './sites/client-pool.js';
+export { SiteRegistry } from './sites/registry.js';
+export { synthesiseFromEnv } from './sites/env-bridge.js';
+export { defaultSecretResolver, PlainSecretResolver } from './sites/secret-resolver.js';
+export { ESSENTIAL_TOOLS, DIRECT_TOP_LEVEL_TOOLS, isEssential, isDirectTopLevel, } from './gateway/essentials.js';
+export { CapturingServer, type AdvancedToolEntry, type CapturedToolHandler, type ToolRegistrar, } from './gateway/capturing-server.js';
+export { registerAdvancedTool } from './gateway/advanced-tool.js';
+export { collectAllRegisteredTools, findTool, type CollectedTool, } from './gateway/test-support.js';
+declare function main(): Promise<void>;
+export { main };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAYH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EACH,UAAU,EACV,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,cAAc,EACd,YAAY,EACZ,WAAW,EACX,aAAa,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGjD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACxF,OAAO,EACH,eAAe,EACf,sBAAsB,EACtB,WAAW,EACX,gBAAgB,GACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACH,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,aAAa,GACrB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EACH,yBAAyB,EACzB,QAAQ,EACR,KAAK,aAAa,GACrB,MAAM,2BAA2B,CAAC;AAEnC,iBAAe,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAuEnC;AAkBD,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,119 @@
+/**
+ * MCP server entrypoint (stdio transport).
+ *
+ * Reads config from environment variables (see `auth.ts`), spins up a
+ * `McpServer` with all tools registered, connects to stdio, and lets
+ * the host (Claude Desktop / Cursor / Zed / …) drive.
+ *
+ * `YTB_MCP_TEST_MODE=1` short-circuits: prints the tool registry and
+ * exits 0. Used by the smoke test and by `release.php` to validate
+ * that the bundled `dist/` is loadable on the target Node version.
+ *
+ * @license MIT
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { isTestMode, loadRegistry } from './auth.js';
+import { ConfigError } from './errors.js';
+import { bootstrapActiveSite } from './sites/bootstrap.js';
+import { ClientPool } from './sites/client-pool.js';
+import { SiteRegistry } from './sites/registry.js';
+import { defaultSecretResolver } from './sites/secret-resolver.js';
+import { createServer } from './server.js';
+export { createServer, SERVER_NAME, SERVER_VERSION } from './server.js';
+export { RestClient, REST_NAMESPACE_PATH, encodeElementPath } from './client.js';
+export { loadConfig, loadRegistry, isTestMode, ENV_SITE_URL, ENV_WP_URL, ENV_BEARER, ENV_SITES_FILE, ENV_PLATFORM, ENV_PROFILE, ENV_TEST_MODE, } from './auth.js';
+export { bootstrapActiveSite } from './sites/bootstrap.js';
+export { ConfigError, RestError, NetworkError } from './errors.js';
+export { buildAllTools } from './tools/index.js';
+// W6 — multi-site primitives exported for dist consumers (scripts,
+// embedded uses). The `ClientPool` is the new wiring contract.
+export { ClientPool, NoDefaultSiteError, UnknownSiteError } from './sites/client-pool.js';
+export { SiteRegistry } from './sites/registry.js';
+export { synthesiseFromEnv } from './sites/env-bridge.js';
+export { defaultSecretResolver, PlainSecretResolver } from './sites/secret-resolver.js';
+export { ESSENTIAL_TOOLS, DIRECT_TOP_LEVEL_TOOLS, isEssential, isDirectTopLevel, } from './gateway/essentials.js';
+export { CapturingServer, } from './gateway/capturing-server.js';
+export { registerAdvancedTool } from './gateway/advanced-tool.js';
+export { collectAllRegisteredTools, findTool, } from './gateway/test-support.js';
+async function main() {
+    const testMode = isTestMode();
+    // W10 — multi-site bootstrap is now centralised in
+    // `auth.loadRegistry()`. The canonical resolution order is:
+    //   1. YTB_MCP_SITES_FILE → loadSitesFile + SiteRegistry
+    //   2. env-bridge (YTB_MCP_SITE_URL + YTB_MCP_BEARER_TOKEN)
+    //   3. ConfigError("No sites configured.")
+    //
+    // The single exception lives here: `--test-mode` smoke probes
+    // (release.php, CI tool-list dumps) must boot even when neither
+    // path is configured. We honor loadRegistry first, then trap the
+    // ConfigError in test-mode and synthesise an empty registry so the
+    // tool list still prints. Tools will refuse to run, which is
+    // expected — `--test-mode` never invokes them.
+    let registry;
+    try {
+        registry = await loadRegistry();
+    }
+    catch (e) {
+        // Never crash the transport over a config problem. A DXT host
+        // (Claude Desktop) auto-starts the server the moment the
+        // extension is installed — before any Site URL / Bearer /
+        // sites-file is entered — and also restarts it after every config
+        // edit. Exiting here surfaced a scary "Server disconnected" toast
+        // for two common cases: (1) no config at all (ConfigError), and
+        // (2) a half-finished or malformed sites.json (schema validation,
+        // e.g. a leftover PASTE_… placeholder bearer). Both now boot with
+        // an empty registry: the server connects, advertises its tools,
+        // `sites_list` shows "(no sites)", and any tool needing a site
+        // returns a friendly NoDefaultSiteError at call-time. The real
+        // reason is written to stderr (visible in the host's MCP logs).
+        // In `--test-mode` this also lets the print-tools probe boot with
+        // zero or broken config.
+        const msg = e instanceof Error ? e.message : String(e);
+        const kind = e instanceof ConfigError
+            ? 'starting unconfigured'
+            : 'config problem, starting with no sites';
+        process.stderr.write(`[yt-builder-mcp] ${kind} — ${msg}\n`);
+        registry = new SiteRegistry({
+            schema_version: 1,
+            default_site_id: null,
+            sites: [],
+        });
+    }
+    const secretResolver = defaultSecretResolver();
+    const pool = new ClientPool(registry, secretResolver);
+    // Phase 3 — honour YTB_MCP_PROFILE: seed the pool's active-site
+    // override so a multi-client config (one MCP entry per site, each
+    // with its own profile) boots on the right site without a first
+    // tool call. No-op when unset / "default" / unknown — mirrors
+    // api-mapper's bootstrapActiveProfile. Pure in-memory pointer move.
+    bootstrapActiveSite(pool);
+    const { mcp, tools } = createServer({ pool });
+    if (testMode) {
+        // Print a one-line per tool summary to stderr (stdout is reserved
+        // for the JSON-RPC frame in real runs) and exit cleanly.
+        process.stderr.write(`[yt-builder-mcp] test mode — ${String(tools.length)} tools registered:\n`);
+        for (const tool of tools) {
+            process.stderr.write(`  - ${tool.name}\n`);
+        }
+        process.exit(0);
+    }
+    const transport = new StdioServerTransport();
+    await mcp.connect(transport);
+}
+/**
+ * Auto-run unless explicitly disabled. Tests set `YTB_MCP_NO_AUTORUN=1`
+ * to import the module without firing up the stdio server.
+ *
+ * The bin dispatcher (`bin/yt-builder-mcp.js`) imports
+ * `dist/index.js` dynamically and expects `main()` to take over — so by
+ * default we run on import.
+ */
+if (process.env.YTB_MCP_NO_AUTORUN !== '1') {
+    main().catch((e) => {
+        const message = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`[yt-builder-mcp] fatal: ${message}\n`);
+        process.exit(1);
+    });
+}
+export { main };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/install-skill.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `install-skill` subcommand for `@wootsup/yt-builder-mcp`.
+ *
+ * Copies the bundled `skills/yt-builder-mcp/` directory into the user's
+ * agent-skill folder (typically `~/.claude/skills/`) and appends a marker
+ * block to `~/AGENTS.md` so other AI clients pick it up automatically.
+ *
+ * Idempotent: re-running overwrites existing skill files and skips the
+ * AGENTS.md append when the marker is already present.
+ *
+ * Mirrors the pattern from `@wootsup/mcp install-skill` so users on both
+ * products get the same workflow.
+ *
+ * @license MIT
+ */
+export declare const MARKER_LINE = "<!-- yt-builder-mcp:skill-installed -->";
+export interface InstallSkillOptions {
+    /**
+     * Package root that contains the bundled `skills/` dir. Defaults to
+     * walking up from this file (works in both source and `dist/` layouts).
+     */
+    readonly pkgRoot?: string;
+    /** Target dir where the `yt-builder-mcp/` skill folder will land. */
+    readonly targetSkillsDir?: string;
+    /**
+     * 1.0.1 Wave-R: when `true` (default), the installer removes any
+     * legacy `yootheme-builder/` directory left behind by pre-1.0.1
+     * installs so the user doesn't end up with two side-by-side skill
+     * copies under the same `~/.claude/skills/` root. Set to `false` to
+     * keep the legacy dir.
+     */
+    readonly removeLegacyDir?: boolean;
+    /** Target AGENTS.md file to append the marker to. */
+    readonly targetAgentsFile?: string;
+}
+export interface InstallSkillResult {
+    readonly copied: boolean;
+    readonly markerAlreadyPresent: boolean;
+    readonly skillTargetDir: string;
+    readonly agentsFile: string;
+}
+export declare function installSkill(options?: InstallSkillOptions): Promise<InstallSkillResult>;
+//# sourceMappingURL=install-skill.d.ts.map

package/dist/install-skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-skill.d.ts","sourceRoot":"","sources":["../src/install-skill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAiBH,eAAO,MAAM,WAAW,4CAA4C,CAAC;AAiBrE,MAAM,WAAW,mBAAmB;IAChC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,qDAAqD;IACrD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B;AAwCD,wBAAsB,YAAY,CAC9B,OAAO,GAAE,mBAAwB,GAClC,OAAO,CAAC,kBAAkB,CAAC,CAmD7B"}