@wootsup/yt-builder-mcp 1.1.6 → 1.1.7

package/dist/gateway/advanced-tool/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `yootheme_builder_advanced` gateway tool — Wave G.1 / Design-Doc §3.1.1.
+ *
+ * Single entry-point to every L2 (non-essential, non-direct) tool. Cursor
+ * caps MCP servers at ~40 tools; routing 12 advanced tools through one
+ * gateway keeps `tools/list` at 10 (7 L1 + 2 L3 + 1 gateway).
+ *
+ * Two modes:
+ *   { tool }              → discovery: returns the target's description,
+ *                           a JSON-schema derived from its Zod inputSchema,
+ *                           and its annotation flags. The target handler
+ *                           is NOT invoked.
+ *   { tool, arguments }   → execution: `arguments` is validated against
+ *                           the target's Zod inputSchema in `.strict()`
+ *                           mode (unknown keys surface as Zod issues), then
+ *                           the target handler is invoked with the parsed
+ *                           args and the same `extra` object — so the
+ *                           target tool's progress, elicitation and
+ *                           AbortSignal keep working.
+ *
+ * Errors are structured ({ error, code, suggestion, details }). The gateway
+ * cannot route to itself: `yootheme_builder_advanced` is never in the
+ * advanced registry (the CapturingServer never sees its name — it's
+ * registered after the CapturingServer hands off).
+ *
+ * Round-2 (R2-A2-CRIT2): split into 5 files under `advanced-tool/`
+ * (this barrel + `domains.ts` + `discovery.ts` + `execute.ts` +
+ * `register.ts`) to keep each file ≤ 100 LoC per Architecture §11.
+ *
+ * @license MIT
+ */
+export { DOMAIN_ORDER, DOMAIN_PREFIX_MAP, TOOL_PREFIX, buildDescription, domainOf, groupByDomain, renderGroupedList, } from './domains.js';
+export { discoveryResult, inputSchemaJson, shapeOf } from './discovery.js';
+export { errorResult, executeAdvancedTool } from './execute.js';
+export { registerAdvancedTool } from './register.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/gateway/advanced-tool/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/gateway/advanced-tool/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,OAAO,EACH,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,QAAQ,EACR,aAAa,EACb,iBAAiB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC"}

package/dist/gateway/advanced-tool/index.js

@@ -0,0 +1,39 @@
+/**
+ * `yootheme_builder_advanced` gateway tool — Wave G.1 / Design-Doc §3.1.1.
+ *
+ * Single entry-point to every L2 (non-essential, non-direct) tool. Cursor
+ * caps MCP servers at ~40 tools; routing 12 advanced tools through one
+ * gateway keeps `tools/list` at 10 (7 L1 + 2 L3 + 1 gateway).
+ *
+ * Two modes:
+ *   { tool }              → discovery: returns the target's description,
+ *                           a JSON-schema derived from its Zod inputSchema,
+ *                           and its annotation flags. The target handler
+ *                           is NOT invoked.
+ *   { tool, arguments }   → execution: `arguments` is validated against
+ *                           the target's Zod inputSchema in `.strict()`
+ *                           mode (unknown keys surface as Zod issues), then
+ *                           the target handler is invoked with the parsed
+ *                           args and the same `extra` object — so the
+ *                           target tool's progress, elicitation and
+ *                           AbortSignal keep working.
+ *
+ * Errors are structured ({ error, code, suggestion, details }). The gateway
+ * cannot route to itself: `yootheme_builder_advanced` is never in the
+ * advanced registry (the CapturingServer never sees its name — it's
+ * registered after the CapturingServer hands off).
+ *
+ * Round-2 (R2-A2-CRIT2): split into 5 files under `advanced-tool/`
+ * (this barrel + `domains.ts` + `discovery.ts` + `execute.ts` +
+ * `register.ts`) to keep each file ≤ 100 LoC per Architecture §11.
+ *
+ * @license MIT
+ */
+// Re-exports — keep the public surface that `advanced-tool.ts` exposed
+// before the split, so downstream importers keep working through the
+// `./advanced-tool.js` backward-compat shim.
+export { DOMAIN_ORDER, DOMAIN_PREFIX_MAP, TOOL_PREFIX, buildDescription, domainOf, groupByDomain, renderGroupedList, } from './domains.js';
+export { discoveryResult, inputSchemaJson, shapeOf } from './discovery.js';
+export { errorResult, executeAdvancedTool } from './execute.js';
+export { registerAdvancedTool } from './register.js';
+//# sourceMappingURL=index.js.map

package/dist/gateway/advanced-tool/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/gateway/advanced-tool/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,uEAAuE;AACvE,qEAAqE;AACrE,6CAA6C;AAC7C,OAAO,EACH,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,QAAQ,EACR,aAAa,EACb,iBAAiB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC"}

package/dist/gateway/advanced-tool/register.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Gateway tool registration — wires `yootheme_builder_advanced` onto the
+ * real McpServer, with discovery-mode + execute-mode dispatch.
+ *
+ * Round-2 (R2-A2-CRIT2) extracted from `gateway/advanced-tool.ts`.
+ *
+ * @license MIT
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AdvancedToolEntry } from '../capturing-server.js';
+/**
+ * Registers `yootheme_builder_advanced` on the real McpServer.
+ *
+ * @param realServer       the McpServer that exposes the gateway tool
+ * @param advancedRegistry the captured non-essential tools (from CapturingServer)
+ */
+export declare function registerAdvancedTool(realServer: McpServer, advancedRegistry: Map<string, AdvancedToolEntry>): void;
+//# sourceMappingURL=register.d.ts.map

package/dist/gateway/advanced-tool/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/gateway/advanced-tool/register.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAmBhE;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAChC,UAAU,EAAE,SAAS,EACrB,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,GACjD,IAAI,CA+CN"}

package/dist/gateway/advanced-tool/register.js

@@ -0,0 +1,69 @@
+/**
+ * Gateway tool registration — wires `yootheme_builder_advanced` onto the
+ * real McpServer, with discovery-mode + execute-mode dispatch.
+ *
+ * Round-2 (R2-A2-CRIT2) extracted from `gateway/advanced-tool.ts`.
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+import { buildDescription, renderGroupedList } from './domains.js';
+import { discoveryResult } from './discovery.js';
+import { errorResult, executeAdvancedTool } from './execute.js';
+/** Builds the gateway tool's Zod inputSchema for a given non-empty enum of advanced names. */
+function gatewayInputSchema(enumValues) {
+    return {
+        tool: z.enum(enumValues).describe('Advanced tool to route to (e.g. "yootheme_builder_page_save"). ' +
+            'Omit `arguments` to discover its schema first.'),
+        arguments: z.record(z.string(), z.unknown()).optional().describe('Arguments for the target tool. Omit for discovery mode ' +
+            "(returns the tool's schema + annotations)."),
+    };
+}
+/**
+ * Registers `yootheme_builder_advanced` on the real McpServer.
+ *
+ * @param realServer       the McpServer that exposes the gateway tool
+ * @param advancedRegistry the captured non-essential tools (from CapturingServer)
+ */
+export function registerAdvancedTool(realServer, advancedRegistry) {
+    const advancedNames = [...advancedRegistry.keys()].sort();
+    // z.enum needs a non-empty tuple. The empty-registry arm is exercised
+    // only by defensive test wiring; production always populates the
+    // registry. Keeping the guard means a zero-tool wiring still yields a
+    // valid (if inert) gateway schema rather than a z.enum crash.
+    const enumValues = advancedNames.length > 0 ? advancedNames : ['__none__'];
+    realServer.registerTool('yootheme_builder_advanced', {
+        title: 'Advanced Tool Gateway',
+        description: buildDescription(advancedNames),
+        inputSchema: gatewayInputSchema(enumValues),
+        // Stream D3 T3: gateway is the only L1 tool that retains
+        // `openWorldHint:true` — its effective behaviour is
+        // dynamic (target tool decided at call-time). Conservative
+        // spec-default marks it destructive because it can route
+        // into delete/unbind handlers; the destination tool's own
+        // confirm-guard still gates the actual mutation.
+        annotations: {
+            title: 'Advanced Tool Gateway',
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (args, extra) => {
+        const entry = advancedRegistry.get(args.tool);
+        if (!entry) {
+            return errorResult({
+                message: `Unknown advanced tool: "${args.tool}".`,
+                code: 'unknown_tool',
+                suggestion: 'Pick one of the valid advanced tool names below, or call ' +
+                    'yootheme_builder_health to verify connectivity.\n\n' +
+                    `Valid advanced tools by domain:\n${renderGroupedList(advancedNames)}`,
+                details: { valid_tools_by_domain: renderGroupedList(advancedNames) },
+            });
+        }
+        if (args.arguments === undefined)
+            return discoveryResult(args.tool, entry);
+        return executeAdvancedTool(args.tool, entry, args.arguments, extra);
+    });
+}
+//# sourceMappingURL=register.js.map

package/dist/gateway/advanced-tool/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../../src/gateway/advanced-tool/register.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEhE,8FAA8F;AAC9F,SAAS,kBAAkB,CAAC,UAAiC;IACzD,OAAO;QACH,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,QAAQ,CAC7B,iEAAiE;YAC7D,gDAAgD,CACvD;QACD,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAC5D,yDAAyD;YACrD,4CAA4C,CACnD;KACJ,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAChC,UAAqB,EACrB,gBAAgD;IAEhD,MAAM,aAAa,GAAG,CAAC,GAAG,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAE1D,sEAAsE;IACtE,iEAAiE;IACjE,sEAAsE;IACtE,8DAA8D;IAC9D,MAAM,UAAU,GACZ,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAE,aAAuC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IAEvF,UAAU,CAAC,YAAY,CACnB,2BAA2B,EAC3B;QACI,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EAAE,gBAAgB,CAAC,aAAa,CAAC;QAC5C,WAAW,EAAE,kBAAkB,CAAC,UAAU,CAAC;QAC3C,yDAAyD;QACzD,oDAAoD;QACpD,2DAA2D;QAC3D,yDAAyD;QACzD,0DAA0D;QAC1D,iDAAiD;QACjD,WAAW,EAAE;YACT,KAAK,EAAE,uBAAuB;YAC9B,YAAY,EAAE,KAAK;YACnB,eAAe,EAAE,IAAI;YACrB,cAAc,EAAE,KAAK;YACrB,aAAa,EAAE,IAAI;SACtB;KACJ,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAA2B,EAAE;QAC3C,MAAM,KAAK,GAAG,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9C,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,OAAO,WAAW,CAAC;gBACf,OAAO,EAAE,2BAA2B,IAAI,CAAC,IAAI,IAAI;gBACjD,IAAI,EAAE,cAAc;gBACpB,UAAU,EACN,2DAA2D;oBAC3D,qDAAqD;oBACrD,oCAAoC,iBAAiB,CAAC,aAAa,CAAC,EAAE;gBAC1E,OAAO,EAAE,EAAE,qBAAqB,EAAE,iBAAiB,CAAC,aAAa,CAAC,EAAE;aACvE,CAAC,CAAC;QACP,CAAC;QACD,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;YAAE,OAAO,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC3E,OAAO,mBAAmB,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACxE,CAAC,CACJ,CAAC;AACN,CAAC"}

package/dist/gateway/advanced-tool.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Backward-compat shim for `gateway/advanced-tool.ts`.
+ *
+ * The original 283-LoC module was split into `gateway/advanced-tool/`
+ * (4 files, each ≤ 100 LoC) per Architecture §11 cap (Round-2
+ * R2-A2-CRIT2 audit fix). This shim preserves the public import path
+ * (`from '../gateway/advanced-tool.js'`) so server.ts, src/index.ts,
+ * and the test suite keep working unchanged.
+ *
+ * @license MIT
+ */
+export * from './advanced-tool/index.js';
+//# sourceMappingURL=advanced-tool.d.ts.map

package/dist/gateway/advanced-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced-tool.d.ts","sourceRoot":"","sources":["../../src/gateway/advanced-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,0BAA0B,CAAC"}

package/dist/gateway/advanced-tool.js

@@ -0,0 +1,13 @@
+/**
+ * Backward-compat shim for `gateway/advanced-tool.ts`.
+ *
+ * The original 283-LoC module was split into `gateway/advanced-tool/`
+ * (4 files, each ≤ 100 LoC) per Architecture §11 cap (Round-2
+ * R2-A2-CRIT2 audit fix). This shim preserves the public import path
+ * (`from '../gateway/advanced-tool.js'`) so server.ts, src/index.ts,
+ * and the test suite keep working unchanged.
+ *
+ * @license MIT
+ */
+export * from './advanced-tool/index.js';
+//# sourceMappingURL=advanced-tool.js.map

package/dist/gateway/advanced-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced-tool.js","sourceRoot":"","sources":["../../src/gateway/advanced-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,0BAA0B,CAAC"}

package/dist/gateway/capturing-server.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 type { McpServer, ToolCallback } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AnySchema, ZodRawShapeCompat } from '@modelcontextprotocol/sdk/server/zod-compat.js';
+import type { CallToolResult, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * The input-schema constraint the SDK's `registerTool` accepts — a raw Zod
+ * shape, a Zod schema, or `undefined` (zero-arg tools). Reused so the
+ * `ToolRegistrar.registerTool` generic stays in lockstep with `ToolCallback`.
+ */
+type ToolInputArgs = undefined | ZodRawShapeCompat | AnySchema;
+/**
+ * The config object accepted by `registerTool` — mirrors the SDK's 2nd arg.
+ * `inputSchema` is generic so per-tool handler args stay strongly inferred.
+ */
+interface RegisterToolConfig<InputArgs extends ToolInputArgs> {
+    title?: string;
+    description?: string;
+    inputSchema?: InputArgs;
+    outputSchema?: ZodRawShapeCompat | AnySchema;
+    annotations?: ToolAnnotations;
+    _meta?: Record<string, unknown>;
+}
+/**
+ * The McpServer subsurface our `registerXTools` builders consume.
+ *
+ * `registerTool` is a hand-written generic mirroring the SDK signature with a
+ * `void` return type. A real `McpServer` (whose method returns
+ * `RegisteredTool`) is still assignable here because a value-returning method
+ * satisfies a `void`-returning member. The `InputArgs` generic preserves
+ * per-tool `ToolCallback` argument inference at every call-site.
+ */
+export interface ToolRegistrar {
+    registerTool<InputArgs extends ToolInputArgs = undefined>(name: string, config: RegisterToolConfig<InputArgs>, cb: ToolCallback<InputArgs>): void;
+    registerResource: McpServer['registerResource'];
+}
+/** Config object passed to `registerTool` (the SDK's 2nd arg). */
+export type CapturedToolConfig = Parameters<McpServer['registerTool']>[1];
+/**
+ * Captured-handler shape. The SDK's `registerTool` is generic over the input
+ * shape, so a captured handler is stored with its args erased to
+ * `Record<string, unknown>`. The gateway validates `arguments` against the
+ * tool's Zod schema before calling the handler, so the runtime contract holds.
+ */
+export type CapturedToolHandler = (args: Record<string, unknown>, extra: unknown) => CallToolResult | Promise<CallToolResult>;
+/** A captured advanced tool: its registration config and its handler. */
+export interface AdvancedToolEntry {
+    config: CapturedToolConfig;
+    handler: CapturedToolHandler;
+}
+/**
+ * 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 declare class CapturingServer implements ToolRegistrar {
+    private readonly realServer;
+    private readonly advancedRegistry;
+    constructor(realServer: McpServer);
+    /**
+     * 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<InputArgs extends ToolInputArgs = undefined>(name: string, config: CapturedToolConfig, handler: ToolCallback<InputArgs>): void;
+    /**
+     * 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: McpServer['registerResource'];
+    /** The captured non-essential tools, keyed by tool name. */
+    getAdvancedRegistry(): Map<string, AdvancedToolEntry>;
+}
+export {};
+//# sourceMappingURL=capturing-server.d.ts.map

package/dist/gateway/capturing-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capturing-server.d.ts","sourceRoot":"","sources":["../../src/gateway/capturing-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AACnG,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAI1F;;;;GAIG;AACH,KAAK,aAAa,GAAG,SAAS,GAAG,iBAAiB,GAAG,SAAS,CAAC;AAE/D;;;GAGG;AACH,UAAU,kBAAkB,CAAC,SAAS,SAAS,aAAa;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,YAAY,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC7C,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC1B,YAAY,CAAC,SAAS,SAAS,aAAa,GAAG,SAAS,EACpD,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,kBAAkB,CAAC,SAAS,CAAC,EACrC,EAAE,EAAE,YAAY,CAAC,SAAS,CAAC,GAC5B,IAAI,CAAC;IACR,gBAAgB,EAAE,SAAS,CAAC,kBAAkB,CAAC,CAAC;CACnD;AAED,kEAAkE;AAClE,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAI1E;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,OAAO,KACb,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;AAE9C,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,mBAAmB,CAAC;CAChC;AAED;;;;GAIG;AACH,qBAAa,eAAgB,YAAW,aAAa;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAY;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAwC;gBAE7D,UAAU,EAAE,SAAS;IAIjC;;;;;;;;OAQG;IACH,YAAY,CAAC,SAAS,SAAS,aAAa,GAAG,SAAS,EACpD,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,GACjC,IAAI;IAkCP;;;;;;;;OAQG;IACH,gBAAgB,EAAE,SAAS,CAAC,kBAAkB,CAAC,CACiC;IAEhF,4DAA4D;IAC5D,mBAAmB,IAAI,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC;CAGxD"}

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 27 callable tools (19 domain L1/L3 + 7 advanced L2 + 1 gateway).
+ * The 3-lane shape keeps `tools/list` at 17 (L1) + 2 (L3) + 1 (gateway) =
+ * 20 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"];
+/**
+ * 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,qmBAuClB,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,94 @@
+/**
+ * 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 27 callable tools (19 domain L1/L3 + 7 advanced L2 + 1 gateway).
+ * The 3-lane shape keeps `tools/list` at 17 (L1) + 2 (L3) + 1 (gateway) =
+ * 20 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 we sit at 17 L1 + 2 L3 + 1 gateway = 20,
+    // 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',
+];
+/**
+ * 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,gEAAgE;IAChE,+BAA+B;IAC/B,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;CACvB,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"}