@wootsup/yt-builder-mcp 1.1.6 → 1.1.7

package/dist/platform/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Platform abstraction — Wave G.0.
+ *
+ * A `Platform` is the seam between the MCP server and a host CMS. Today
+ * the only concrete impl is `WordPressPlatform`; `joomla` is reserved
+ * as a typed seam-marker so Wave G.4+ can land Joomla without rippling
+ * through every call site.
+ *
+ * Why an interface instead of a tagged union?
+ *   - Each platform owns its REST-namespace path verbatim (WP uses
+ *     `/wp-json/<ns>`, Joomla will use `/index.php?option=com_ajax&…`).
+ *   - Adding a platform = implement the interface + add a `PlatformKind`
+ *     member. No switch statements to update.
+ *
+ * The `RestClient` accepts EITHER a `Platform` OR the legacy
+ * `{baseUrl}` form (which internally builds a `WordPressPlatform`),
+ * so existing callers keep working unchanged.
+ *
+ * @license MIT
+ */
+/** Tagged union of supported host platforms. */
+export type PlatformKind = 'wordpress' | 'joomla';
+/**
+ * A `Platform` describes WHERE and HOW the MCP server reaches the
+ * REST surface of the host CMS.
+ */
+export interface Platform {
+    /** Discriminator for runtime checks. */
+    readonly kind: PlatformKind;
+    /** Origin (scheme + host + optional port). No trailing-slash normalisation here. */
+    readonly baseUrl: string;
+    /** Path prefix appended to baseUrl to form the REST root (must start with `/`). */
+    readonly restNamespacePath: string;
+}
+/** Canonical WordPress REST-namespace path for this plugin. */
+export declare const WORDPRESS_REST_NAMESPACE_PATH = "/wp-json/yt-builder-mcp/v1";
+/**
+ * WordPress platform implementation.
+ *
+ * `restNamespacePath` is fixed to the plugin's namespace; the caller
+ * supplies only the site origin.
+ */
+export declare class WordPressPlatform implements Platform {
+    readonly kind: "wordpress";
+    readonly baseUrl: string;
+    readonly restNamespacePath: string;
+    constructor(baseUrl: string);
+}
+export { JoomlaPlatform, JOOMLA_REST_NAMESPACE_PATH } from './joomla.js';
+/**
+ * Detect which {@link Platform} a base URL targets based on the URL
+ * shape alone (no network call).
+ *
+ *   - pathname starts with `/wp-json/` → `'wordpress'`
+ *   - pathname starts with `/api/index.php/` → `'joomla'`
+ *   - otherwise → `null` (ambiguous — caller may probe `/identity`)
+ *
+ * Round-6 A1 polish: detection switched from `String.includes` to a
+ * proper `URL`-parse + `pathname.startsWith` so query-string payloads
+ * cannot cause mis-detection (e.g. a Joomla site URL like
+ * `https://example.com/?redirect=/wp-json/foo` no longer pretends to
+ * be WordPress). Malformed URLs that the `URL` constructor rejects
+ * gracefully fall back to the legacy substring scan so callers that
+ * accidentally pass a host-only string (e.g. `example.com`) keep
+ * working — they would have already failed the actual network call
+ * with a clearer error before this function was reached in practice.
+ *
+ * Cookbook §3.7.1 — the runtime tie-breaker (when this returns `null`)
+ * is the `/identity` endpoint, which returns
+ * `{ product: 'yt-builder-mcp', platform: 'wordpress'|'joomla', ... }`
+ * on both platforms.
+ */
+export declare function detectPlatformFromUrl(url: string): PlatformKind | null;
+/**
+ * Construct the right {@link Platform} for a base URL.
+ *
+ * When the URL shape gives an unambiguous hint via
+ * {@link detectPlatformFromUrl}, that wins. Otherwise the caller can
+ * pass an explicit `hint` (e.g. from a config flag) or fall back to
+ * the default (`'wordpress'` for back-compat — Joomla support landed
+ * in Wave 7, so existing WordPress installs never need to flag).
+ *
+ * Synchronous variant — kept for back-compat with callers that cannot
+ * (or do not need to) probe over the network. Prefer
+ * {@link platformForUrlAsync} when running in the server boot path:
+ * it adds a runtime probe that disambiguates origin-only / subfolder
+ * URLs (e.g. `https://example.com/joomla`) where the URL shape alone
+ * is silent.
+ */
+export declare function platformForUrl(baseUrl: string, hint?: PlatformKind): Platform;
+/**
+ * Async variant of {@link platformForUrl} that adds a runtime probe
+ * step for URLs the URL-shape heuristic cannot disambiguate.
+ *
+ * Resolution order (first match wins):
+ *   1. Explicit `hint` from `YTB_MCP_PLATFORM` env var → no probe.
+ *   2. URL-shape via {@link detectPlatformFromUrl} (clear `/wp-json/`
+ *      or `/api/index.php/` marker) → no probe.
+ *   3. Runtime probe via `detectPlatformAtRuntime` (the F-Platform-
+ *      Detect-Probe fix — handles subfolder installs like
+ *      `https://dev.example.com/joomla` where steps 1+2 return null).
+ *   4. Final fallback: `'wordpress'` (back-compat).
+ *
+ * The probe step is what unblocks origin-only Joomla customers without
+ * forcing them to manually set `YTB_MCP_PLATFORM=joomla` — the DXT
+ * default of `auto` finally lives up to its name.
+ *
+ * If both probes fail (server unreachable, plugin not installed, etc.)
+ * we fall back to the wordpress default and emit a single stderr note
+ * so the customer at least sees *why* the next authenticated call may
+ * 404; the real diagnosis still belongs to the first authenticated
+ * tool invocation.
+ *
+ * @param opts.probe Optional probe override (tests / DI).
+ * @param opts.logger Optional stderr writer (defaults to `process.stderr.write`).
+ */
+export declare function platformForUrlAsync(baseUrl: string, hint?: PlatformKind, opts?: {
+    readonly probe?: (url: string) => Promise<PlatformKind | null>;
+    readonly logger?: (msg: string) => void;
+}): Promise<Platform>;
+//# sourceMappingURL=index.d.ts.map

package/dist/platform/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/platform/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,gDAAgD;AAChD,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;AAElD;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACrB,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACtC;AAED,+DAA+D;AAC/D,eAAO,MAAM,6BAA6B,+BAA+B,CAAC;AAE1E;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,QAAQ;IAC9C,SAAgB,IAAI,EAAG,WAAW,CAAU;IAC5C,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,SAAgB,iBAAiB,EAAE,MAAM,CAAC;gBAE9B,OAAO,EAAE,MAAM;CAI9B;AAOD,OAAO,EAAE,cAAc,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAetE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC1B,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,YAAY,GACpB,QAAQ,CAMV;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,mBAAmB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,YAAY,EACnB,IAAI,GAAE;IACF,QAAQ,CAAC,KAAK,CAAC,EAAE,CACb,GAAG,EAAE,MAAM,KACV,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC,GACP,OAAO,CAAC,QAAQ,CAAC,CA0CnB"}

package/dist/platform/index.js

@@ -0,0 +1,176 @@
+/**
+ * Platform abstraction — Wave G.0.
+ *
+ * A `Platform` is the seam between the MCP server and a host CMS. Today
+ * the only concrete impl is `WordPressPlatform`; `joomla` is reserved
+ * as a typed seam-marker so Wave G.4+ can land Joomla without rippling
+ * through every call site.
+ *
+ * Why an interface instead of a tagged union?
+ *   - Each platform owns its REST-namespace path verbatim (WP uses
+ *     `/wp-json/<ns>`, Joomla will use `/index.php?option=com_ajax&…`).
+ *   - Adding a platform = implement the interface + add a `PlatformKind`
+ *     member. No switch statements to update.
+ *
+ * The `RestClient` accepts EITHER a `Platform` OR the legacy
+ * `{baseUrl}` form (which internally builds a `WordPressPlatform`),
+ * so existing callers keep working unchanged.
+ *
+ * @license MIT
+ */
+/** Canonical WordPress REST-namespace path for this plugin. */
+export const WORDPRESS_REST_NAMESPACE_PATH = '/wp-json/yt-builder-mcp/v1';
+/**
+ * WordPress platform implementation.
+ *
+ * `restNamespacePath` is fixed to the plugin's namespace; the caller
+ * supplies only the site origin.
+ */
+export class WordPressPlatform {
+    kind = 'wordpress';
+    baseUrl;
+    restNamespacePath;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+        this.restNamespacePath = WORDPRESS_REST_NAMESPACE_PATH;
+    }
+}
+// Local import keeps the symbol in scope for `platformForUrl` below;
+// the re-export immediately after surfaces it to outside callers so
+// the platform barrel remains the single import point (cookbook
+// Ch1 Finding 2).
+import { JoomlaPlatform } from './joomla.js';
+export { JoomlaPlatform, JOOMLA_REST_NAMESPACE_PATH } from './joomla.js';
+/**
+ * Detect which {@link Platform} a base URL targets based on the URL
+ * shape alone (no network call).
+ *
+ *   - pathname starts with `/wp-json/` → `'wordpress'`
+ *   - pathname starts with `/api/index.php/` → `'joomla'`
+ *   - otherwise → `null` (ambiguous — caller may probe `/identity`)
+ *
+ * Round-6 A1 polish: detection switched from `String.includes` to a
+ * proper `URL`-parse + `pathname.startsWith` so query-string payloads
+ * cannot cause mis-detection (e.g. a Joomla site URL like
+ * `https://example.com/?redirect=/wp-json/foo` no longer pretends to
+ * be WordPress). Malformed URLs that the `URL` constructor rejects
+ * gracefully fall back to the legacy substring scan so callers that
+ * accidentally pass a host-only string (e.g. `example.com`) keep
+ * working — they would have already failed the actual network call
+ * with a clearer error before this function was reached in practice.
+ *
+ * Cookbook §3.7.1 — the runtime tie-breaker (when this returns `null`)
+ * is the `/identity` endpoint, which returns
+ * `{ product: 'yt-builder-mcp', platform: 'wordpress'|'joomla', ... }`
+ * on both platforms.
+ */
+export function detectPlatformFromUrl(url) {
+    let pathname;
+    try {
+        pathname = new URL(url).pathname;
+    }
+    catch {
+        // Fallback for inputs the URL constructor rejects (host-only
+        // strings, relative paths). Preserves the legacy substring
+        // behaviour as a defensive net.
+        if (url.includes('/wp-json/'))
+            return 'wordpress';
+        if (url.includes('/api/index.php/'))
+            return 'joomla';
+        return null;
+    }
+    if (pathname.startsWith('/wp-json/'))
+        return 'wordpress';
+    if (pathname.startsWith('/api/index.php/'))
+        return 'joomla';
+    return null;
+}
+/**
+ * Construct the right {@link Platform} for a base URL.
+ *
+ * When the URL shape gives an unambiguous hint via
+ * {@link detectPlatformFromUrl}, that wins. Otherwise the caller can
+ * pass an explicit `hint` (e.g. from a config flag) or fall back to
+ * the default (`'wordpress'` for back-compat — Joomla support landed
+ * in Wave 7, so existing WordPress installs never need to flag).
+ *
+ * Synchronous variant — kept for back-compat with callers that cannot
+ * (or do not need to) probe over the network. Prefer
+ * {@link platformForUrlAsync} when running in the server boot path:
+ * it adds a runtime probe that disambiguates origin-only / subfolder
+ * URLs (e.g. `https://example.com/joomla`) where the URL shape alone
+ * is silent.
+ */
+export function platformForUrl(baseUrl, hint) {
+    const detected = detectPlatformFromUrl(baseUrl);
+    const kind = detected ?? hint ?? 'wordpress';
+    return kind === 'joomla'
+        ? new JoomlaPlatform(baseUrl)
+        : new WordPressPlatform(baseUrl);
+}
+/**
+ * Async variant of {@link platformForUrl} that adds a runtime probe
+ * step for URLs the URL-shape heuristic cannot disambiguate.
+ *
+ * Resolution order (first match wins):
+ *   1. Explicit `hint` from `YTB_MCP_PLATFORM` env var → no probe.
+ *   2. URL-shape via {@link detectPlatformFromUrl} (clear `/wp-json/`
+ *      or `/api/index.php/` marker) → no probe.
+ *   3. Runtime probe via `detectPlatformAtRuntime` (the F-Platform-
+ *      Detect-Probe fix — handles subfolder installs like
+ *      `https://dev.example.com/joomla` where steps 1+2 return null).
+ *   4. Final fallback: `'wordpress'` (back-compat).
+ *
+ * The probe step is what unblocks origin-only Joomla customers without
+ * forcing them to manually set `YTB_MCP_PLATFORM=joomla` — the DXT
+ * default of `auto` finally lives up to its name.
+ *
+ * If both probes fail (server unreachable, plugin not installed, etc.)
+ * we fall back to the wordpress default and emit a single stderr note
+ * so the customer at least sees *why* the next authenticated call may
+ * 404; the real diagnosis still belongs to the first authenticated
+ * tool invocation.
+ *
+ * @param opts.probe Optional probe override (tests / DI).
+ * @param opts.logger Optional stderr writer (defaults to `process.stderr.write`).
+ */
+export async function platformForUrlAsync(baseUrl, hint, opts = {}) {
+    // 1. Explicit hint wins — probe-less, by design (user override).
+    if (hint !== undefined) {
+        return hint === 'joomla'
+            ? new JoomlaPlatform(baseUrl)
+            : new WordPressPlatform(baseUrl);
+    }
+    // 2. Static URL-shape heuristic.
+    const detected = detectPlatformFromUrl(baseUrl);
+    if (detected !== null) {
+        return detected === 'joomla'
+            ? new JoomlaPlatform(baseUrl)
+            : new WordPressPlatform(baseUrl);
+    }
+    // 3. Runtime probe. Lazy-imported so the sync `platformForUrl`
+    //    barrel above stays free of any fetch dependency for callers
+    //    that do not opt-in.
+    const probe = opts.probe
+        ?? (async (url) => {
+            const mod = await import('./detect.js');
+            return mod.detectPlatformAtRuntime(url);
+        });
+    const probed = await probe(baseUrl);
+    if (probed !== null) {
+        return probed === 'joomla'
+            ? new JoomlaPlatform(baseUrl)
+            : new WordPressPlatform(baseUrl);
+    }
+    // 4. Final fallback — emit a single soft note so the user knows
+    //    we tried and that explicit YTB_MCP_PLATFORM may rescue.
+    const logger = opts.logger
+        ?? ((msg) => {
+            process.stderr.write(msg);
+        });
+    logger('[yt-builder-mcp] notice: platform auto-detection probe failed for '
+        + `${baseUrl} — falling back to wordpress. Set YTB_MCP_PLATFORM=joomla `
+        + 'if this is a Joomla install.\n');
+    return new WordPressPlatform(baseUrl);
+}
+//# sourceMappingURL=index.js.map

package/dist/platform/index.js.map

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

package/dist/platform/joomla.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Joomla 5/6 platform implementation — Wave 7 prep.
+ *
+ * Mirrors {@link WordPressPlatform} but targets the Joomla Web Services
+ * API surface registered by `plg_system_ytbmcp` (see
+ * `src/packaging/joomla/extensions/plg_system_ytbmcp/src/Extension/Ytbmcp.php`
+ * — `onBeforeApiRoute()` mounts the routes under
+ * `v1/yt-builder-mcp/...` against `com_ytbmcp`).
+ *
+ * The full request URL composed by {@link RestClient} is:
+ *
+ *     {baseUrl}/api/index.php/v1/yt-builder-mcp/{path}
+ *
+ * — where `{baseUrl}` is the Joomla site origin (e.g. `https://example.com`
+ * or `https://example.com/joomla` for a subfolder install) and `{path}`
+ * is the per-tool REST path (e.g. `/health`, `/pages`, `/etag`).
+ *
+ * Cookbook Ch1 Finding 2: the `PlatformKind` union already declared
+ * `'joomla'` in Wave G.0; this class fills the seam so no tool handler
+ * has to change.
+ *
+ * Cookbook §3.7 (cross-platform parity): the REST byte-shape returned
+ * by every endpoint is identical across platforms — only the route
+ * prefix differs.
+ *
+ * @license MIT
+ */
+import type { Platform } from './index.js';
+/** Canonical Joomla REST namespace prefix for this plugin. */
+export declare const JOOMLA_REST_NAMESPACE_PATH = "/api/index.php/v1/yt-builder-mcp";
+/**
+ * Joomla platform implementation.
+ *
+ * `restNamespacePath` is fixed to the Web Services API mount point that
+ * `plg_system_ytbmcp::onBeforeApiRoute()` registers; the caller supplies
+ * only the site origin.
+ */
+export declare class JoomlaPlatform implements Platform {
+    readonly kind: "joomla";
+    readonly baseUrl: string;
+    readonly restNamespacePath: string;
+    constructor(baseUrl: string);
+}
+//# sourceMappingURL=joomla.d.ts.map

package/dist/platform/joomla.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"joomla.d.ts","sourceRoot":"","sources":["../../src/platform/joomla.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,8DAA8D;AAC9D,eAAO,MAAM,0BAA0B,qCAAqC,CAAC;AAE7E;;;;;;GAMG;AACH,qBAAa,cAAe,YAAW,QAAQ;IAC3C,SAAgB,IAAI,EAAG,QAAQ,CAAU;IACzC,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,SAAgB,iBAAiB,EAAE,MAAM,CAAC;gBAE9B,OAAO,EAAE,MAAM;CAI9B"}

package/dist/platform/joomla.js

@@ -0,0 +1,46 @@
+/**
+ * Joomla 5/6 platform implementation — Wave 7 prep.
+ *
+ * Mirrors {@link WordPressPlatform} but targets the Joomla Web Services
+ * API surface registered by `plg_system_ytbmcp` (see
+ * `src/packaging/joomla/extensions/plg_system_ytbmcp/src/Extension/Ytbmcp.php`
+ * — `onBeforeApiRoute()` mounts the routes under
+ * `v1/yt-builder-mcp/...` against `com_ytbmcp`).
+ *
+ * The full request URL composed by {@link RestClient} is:
+ *
+ *     {baseUrl}/api/index.php/v1/yt-builder-mcp/{path}
+ *
+ * — where `{baseUrl}` is the Joomla site origin (e.g. `https://example.com`
+ * or `https://example.com/joomla` for a subfolder install) and `{path}`
+ * is the per-tool REST path (e.g. `/health`, `/pages`, `/etag`).
+ *
+ * Cookbook Ch1 Finding 2: the `PlatformKind` union already declared
+ * `'joomla'` in Wave G.0; this class fills the seam so no tool handler
+ * has to change.
+ *
+ * Cookbook §3.7 (cross-platform parity): the REST byte-shape returned
+ * by every endpoint is identical across platforms — only the route
+ * prefix differs.
+ *
+ * @license MIT
+ */
+/** Canonical Joomla REST namespace prefix for this plugin. */
+export const JOOMLA_REST_NAMESPACE_PATH = '/api/index.php/v1/yt-builder-mcp';
+/**
+ * Joomla platform implementation.
+ *
+ * `restNamespacePath` is fixed to the Web Services API mount point that
+ * `plg_system_ytbmcp::onBeforeApiRoute()` registers; the caller supplies
+ * only the site origin.
+ */
+export class JoomlaPlatform {
+    kind = 'joomla';
+    baseUrl;
+    restNamespacePath;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+        this.restNamespacePath = JOOMLA_REST_NAMESPACE_PATH;
+    }
+}
+//# sourceMappingURL=joomla.js.map

package/dist/platform/joomla.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"joomla.js","sourceRoot":"","sources":["../../src/platform/joomla.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,0BAA0B,GAAG,kCAAkC,CAAC;AAE7E;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IACP,IAAI,GAAG,QAAiB,CAAC;IACzB,OAAO,CAAS;IAChB,iBAAiB,CAAS;IAE1C,YAAY,OAAe;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,iBAAiB,GAAG,0BAA0B,CAAC;IACxD,CAAC;CACJ"}

package/dist/server.d.ts

@@ -0,0 +1,110 @@
+/**
+ * MCP server factory — Wave G.1 / Gateway-Hub edition.
+ *
+ * `createServer({client})` builds a configured `McpServer` with a 3-lane
+ * tool registration:
+ *
+ *   L3 — direct top-level (yootheme_builder_health + yootheme_builder_diagnose)
+ *        Registered FIRST, BEFORE the CapturingServer wraps the real server.
+ *        These tools must reach the LLM even when the gateway itself
+ *        misbehaves (chicken-and-egg: the LLM diagnoses gateway breakage
+ *        via these two).
+ *
+ *   L1 — essential forwarded (17 tools)
+ *        Routed through the CapturingServer to the real server. Appear in
+ *        `tools/list` as first-class entries (Cursor-cap-safe).
+ *
+ *   L2 — advanced captured (7 tools)
+ *        Routed through the CapturingServer into its in-process advanced
+ *        registry; reachable via the single `yootheme_builder_advanced`
+ *        gateway tool. Hidden from `tools/list`.
+ *
+ *   Gateway — `yootheme_builder_advanced`
+ *        Registered LAST on the real server, after every L1/L2 tool is
+ *        placed and the advanced registry is final.
+ *
+ * Result: `tools/list.length === 20` (17 L1 + 2 L3 + 1 gateway), and the
+ * full callable tool surface is 27 (20 advertised + 7 advanced reachable
+ * through the gateway).
+ *
+ * @license MIT
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { CapturingServer } from './gateway/capturing-server.js';
+import type { ClientPool } from './sites/client-pool.js';
+import type { SiteRegistry } from './sites/registry.js';
+import { type ToolDefinition } from './tools/index.js';
+export declare const SERVER_NAME = "@wootsup/yt-builder-mcp";
+export declare const SERVER_VERSION: string;
+/**
+ * W8 — stable URI under which the live sites snapshot is exposed via
+ * MCP `resources/*`. Single fixed resource (no list-changed needed) —
+ * MCP hosts can fetch the current registry roster on demand without
+ * having to invoke a tool.
+ */
+export declare const SITES_RESOURCE_URI = "sites://current";
+/** Human-readable resource name surfaced in `resources/list`. */
+export declare const SITES_RESOURCE_NAME = "Currently configured sites";
+/** Short description for `resources/list` consumers. */
+export declare const SITES_RESOURCE_DESCRIPTION: string;
+/** MIME type for the `sites://current` payload. */
+export declare const SITES_RESOURCE_MIME_TYPE = "application/json";
+/**
+ * Bearer-redacted JSON payload shape for the W8 `sites://current`
+ * resource. Mirrors the structured-content shape of the
+ * `yootheme_builder_sites_list` tool but never reveals bearer or
+ * bearer_ref — only safe-to-render display fields land in the
+ * `sites[]` rows.
+ */
+export interface SitesResourcePayload {
+    readonly default_site_id: string | null;
+    readonly sites: readonly SitesResourceRow[];
+}
+/**
+ * One row inside {@link SitesResourcePayload.sites}. Strictly the
+ * fields enumerated by plan §W8 Z.929 — no bearer / bearer_ref /
+ * bearer_source. `label` and `platform_resolved` are optional (only
+ * present when the underlying registry entry / probe carries them).
+ */
+export interface SitesResourceRow {
+    readonly site_id: string;
+    readonly url: string;
+    readonly platform: 'wordpress' | 'joomla' | 'auto';
+    readonly is_default: boolean;
+    readonly label?: string;
+}
+/**
+ * Build the JSON payload served by the `sites://current` resource.
+ *
+ * Field projection (per plan §W8 Z.925-933):
+ *  - `default_site_id` from {@link SiteRegistry.defaultSiteId}.
+ *  - `sites[].site_id` / `url` / `is_default` / `label` verbatim.
+ *  - `sites[].platform` prefers the resolved kind from the W3 memo
+ *    cache (peek-only, no probe) and falls back to the configured
+ *    hint when no probe has run.
+ *
+ * Bearer fields are NEVER referenced. The `bearer_source` hint that
+ * the W7 `sites_list` tool exposes is intentionally omitted from this
+ * resource: even the "plain" vs "op" hint hints at storage layout,
+ * and the resource is positioned as a host-facing public roster.
+ */
+export declare function buildSitesResourcePayload(registry: SiteRegistry): SitesResourcePayload;
+export interface CreateServerOptions {
+    /**
+     * Multi-site client pool — replaces the single `client` parameter
+     * shipped pre-W6. Each tool handler asks `pool.resolve(site_id)`
+     * for the per-call REST client + resolved site descriptor.
+     */
+    readonly pool: ClientPool;
+    /** Override the tool set (defaults to `buildAllTools`). */
+    readonly tools?: readonly ToolDefinition[];
+}
+export interface CreatedServer {
+    readonly mcp: McpServer;
+    /** The full set of tool definitions registered across all 3 lanes + gateway. */
+    readonly tools: readonly ToolDefinition[];
+    /** The CapturingServer wrapping `mcp` — exposed for test helpers. */
+    readonly capturing: CapturingServer;
+}
+export declare function createServer(options: CreateServerOptions): CreatedServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAMH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAAE,eAAe,EAAsB,MAAM,+BAA+B,CAAC;AAEpF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AASxD,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEtE,eAAO,MAAM,WAAW,4BAA4B,CAAC;AA4BrD,eAAO,MAAM,cAAc,QAAuB,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AAEpD,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAEhE,wDAAwD;AACxD,eAAO,MAAM,0BAA0B,QAGsB,CAAC;AAE9D,mDAAmD;AACnD,eAAO,MAAM,wBAAwB,qBAAqB,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC/C;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;IACnD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACrC,QAAQ,EAAE,YAAY,GACvB,oBAAoB,CAmBtB;AAED,MAAM,WAAW,mBAAmB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CAC9C;AAED,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;CACvC;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,aAAa,CAuIxE"}