@wootsup/yt-builder-mcp 1.0.1 → 1.1.0

package/dist/tools/tool-builder/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `tool-builder/types` — pure type declarations for the tool-definition
+ * system. Split from `tool-builder.ts` in Round-1.5 (replaces the
+ * Round-1 LoC-exception spec-amendment with a structural code-fix).
+ *
+ * @license MIT
+ */
+import type { ServerNotification } from '@modelcontextprotocol/sdk/types.js';
+import type { ZodRawShape, z } from 'zod';
+/**
+ * A content item the SDK accepts. Mirrors the SDK
+ * `CallToolResult.content[number]` union (text/image/resource). Tools
+ * in this server only emit text, but the toolkit's structured builders
+ * return the wider union, so the envelope-merger must accept it.
+ */
+export type ToolContent = {
+    type: string;
+    [key: string]: unknown;
+};
+/**
+ * MCP-compatible content envelope. Fields:
+ *  - `content`            — text blocks shown to the LLM.
+ *  - `isError`            — flag honoured by the SDK for error results.
+ *  - `_meta.ui`           — Rich-Card hints (toolkit structured-display
+ *                            protocol: data-table, detail, stats, error).
+ *  - `structuredContent`  — domain-typed payload validated against the
+ *                            tool's optional `outputSchema`.
+ */
+export interface ToolResult {
+    content: ToolContent[];
+    isError?: boolean;
+    _meta?: {
+        ui?: unknown;
+    } & Record<string, unknown>;
+    structuredContent?: Record<string, unknown>;
+}
+export interface ToolAnnotations {
+    readonly title?: string;
+    /** Tool does not mutate state. */
+    readonly readOnlyHint?: boolean;
+    /** Tool may delete or otherwise destroy state. */
+    readonly destructiveHint?: boolean;
+    /** Tool talks to a system outside the host process. */
+    readonly openWorldHint?: boolean;
+    /** Identical invocations have identical effects (PUT-style). */
+    readonly idempotentHint?: boolean;
+}
+/**
+ * Minimal MCP-handler `extra` surface used by Wave G.5 progress reports.
+ * Only `_meta.progressToken` and `sendNotification` are consumed; the
+ * toolkit's `createProgressReporter` is defined against this same
+ * minimal shape so we forward verbatim with no cast at the call site.
+ */
+export interface HandlerExtra {
+    readonly _meta?: {
+        progressToken?: string | number;
+    };
+    readonly sendNotification: (notification: ServerNotification) => Promise<void>;
+}
+export type ToolHandler<TSchema extends ZodRawShape> = (args: z.infer<z.ZodObject<TSchema>>, extra?: HandlerExtra) => Promise<ToolResult>;
+export interface ToolDefinition<TSchema extends ZodRawShape = ZodRawShape> {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: TSchema;
+    /**
+     * Optional Zod schema describing the `structuredContent` payload.
+     * Hosts that support MCP structured output validate responses
+     * against this schema. Set on migrated tools using
+     * `structuredResult` / `tableResult` / `detailResult` /
+     * `statsResult`; tools on `jsonResult` may omit it.
+     */
+    readonly outputSchema?: z.ZodTypeAny;
+    readonly annotations: ToolAnnotations;
+    readonly handler: ToolHandler<TSchema>;
+}
+/**
+ * Type-erased tool definition used by the aggregator and server. Tools
+ * carry their own runtime-typed handler internally — at the registry
+ * boundary we only need the metadata + an opaque handler.
+ */
+export type AnyToolDefinition = ToolDefinition<any>;
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/tool-builder/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-builder/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACvB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,kDAAkD;IAClD,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,uDAAuD;IACvD,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,gEAAgE;IAChE,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACrD,QAAQ,CAAC,gBAAgB,EAAE,CAAC,YAAY,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClF;AAED,MAAM,MAAM,WAAW,CAAC,OAAO,SAAS,WAAW,IAAI,CACnD,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,EACnC,KAAK,CAAC,EAAE,YAAY,KACnB,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB,MAAM,WAAW,cAAc,CAAC,OAAO,SAAS,WAAW,GAAG,WAAW;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED;;;;GAIG;AAEH,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC"}

package/dist/tools/tool-builder/types.js

@@ -0,0 +1,9 @@
+/**
+ * `tool-builder/types` — pure type declarations for the tool-definition
+ * system. Split from `tool-builder.ts` in Round-1.5 (replaces the
+ * Round-1 LoC-exception spec-amendment with a structural code-fix).
+ *
+ * @license MIT
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/tools/tool-builder/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/tools/tool-builder/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/tools/tool-builder.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `tool-builder.ts` — backward-compat re-export barrel.
+ *
+ * The implementation was split into `tool-builder/{types,annotations,
+ * results,define}.ts` in Round-1.5 (replaces the Round-1 LoC-exception
+ * spec-amendment with a structural code-fix). All existing
+ * `./tool-builder.js` imports continue to work via this re-export.
+ *
+ * For new code, prefer importing from `./tool-builder/index.js` (or
+ * the specific submodule) — but the barrel here is the stable
+ * public-import path for the package's internal modules.
+ *
+ * @license MIT
+ */
+export * from './tool-builder/index.js';
+//# sourceMappingURL=tool-builder.d.ts.map

package/dist/tools/tool-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-builder.d.ts","sourceRoot":"","sources":["../../src/tools/tool-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,cAAc,yBAAyB,CAAC"}

package/dist/tools/tool-builder.js

@@ -0,0 +1,16 @@
+/**
+ * `tool-builder.ts` — backward-compat re-export barrel.
+ *
+ * The implementation was split into `tool-builder/{types,annotations,
+ * results,define}.ts` in Round-1.5 (replaces the Round-1 LoC-exception
+ * spec-amendment with a structural code-fix). All existing
+ * `./tool-builder.js` imports continue to work via this re-export.
+ *
+ * For new code, prefer importing from `./tool-builder/index.js` (or
+ * the specific submodule) — but the barrel here is the stable
+ * public-import path for the package's internal modules.
+ *
+ * @license MIT
+ */
+export * from './tool-builder/index.js';
+//# sourceMappingURL=tool-builder.js.map

package/dist/tools/tool-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-builder.js","sourceRoot":"","sources":["../../src/tools/tool-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,cAAc,yBAAyB,CAAC"}

package/manifest.json

@@ -2,9 +2,9 @@
     "dxt_version": "0.1",
     "name": "@wootsup/yt-builder-mcp",
     "display_name": "YT Builder MCP for YOOtheme Pro (unofficial)",
-    "version": "1.0.1",
-    "description": "Drive your page builder programmatically from Claude, Cursor, Codex, Gemini and 5 other MCP-capable AI assistants — read layouts, edit settings, add elements, bind dynamic sources. Built for YOOtheme Pro 4.0+. Independent third-party project, not affiliated with YOOtheme GmbH.",
-    "long_description": "YT Builder MCP gives AI assistants a typed, scoped, and idempotent surface for your YOOtheme Pro page builder. Tools cover page discovery, layout inspection, element CRUD, source binding, and diagnostics. Bearer auth, optimistic locking via ETag, scope hierarchy (read < write < admin), and structured-error responses keep the agent safe and the workflow correct on first try. Independent third-party project — YOOtheme® is a registered trademark of YOOtheme GmbH (yootheme.com); YT Builder MCP is built by WootsUp (getimo productions) and is not affiliated with, endorsed by, or sponsored by YOOtheme.",
+    "version": "1.1.0",
+    "description": "Drive your YOOtheme Pro Page Builder programmatically from Claude, Cursor, Codex, Gemini and 5 other MCP-capable AI assistants — read layouts, edit settings, add elements, bind dynamic sources. Works on WordPress and Joomla 5/6. Built for YOOtheme Pro 4.0+. Independent third-party project, not affiliated with YOOtheme GmbH.",
+    "long_description": "YT Builder MCP gives AI assistants a typed, scoped, and idempotent surface for your YOOtheme Pro Page Builder, on either WordPress or Joomla 5/6. Tools cover page discovery, layout inspection, element CRUD, source binding, and diagnostics. Bearer auth, optimistic locking via ETag, scope hierarchy (read < write < admin), and structured-error responses keep the agent safe and the workflow correct on first try. Independent third-party project — YOOtheme® is a registered trademark of YOOtheme GmbH (yootheme.com); YT Builder MCP is built by WootsUp (getimo productions) and is not affiliated with, endorsed by, or sponsored by YOOtheme.",
     "icon": "icon.png",
     "author": {
         "name": "WootsUp",
@@ -21,6 +21,8 @@
         "yootheme",
         "yootheme-pro",
         "wordpress",
+        "joomla",
+        "cms",
         "page-builder",
         "mcp",
         "model-context-protocol",
@@ -37,23 +39,38 @@
                 "${__dirname}/dist/index.js"
             ],
             "env": {
-                "YTB_MCP_WP_URL": "${user_config.YTB_MCP_WP_URL}",
+                "YTB_MCP_SITES_FILE": "${user_config.YTB_MCP_SITES_FILE}",
+                "YTB_MCP_SITE_URL": "${user_config.YTB_MCP_SITE_URL}",
+                "YTB_MCP_PLATFORM": "${user_config.YTB_MCP_PLATFORM}",
                 "YTB_MCP_BEARER_TOKEN": "${user_config.YTB_MCP_BEARER_TOKEN}"
             }
         }
     },
     "user_config": {
-        "YTB_MCP_WP_URL": {
+        "YTB_MCP_SITES_FILE": {
             "type": "string",
-            "title": "WordPress site URL",
-            "description": "Base URL of the WordPress install (e.g. https://example.com). Without trailing slash.",
-            "required": true
+            "title": "Sites registry file (multi-site mode)",
+            "description": "Path to sites.json for multi-site setups (e.g. ~/.config/yt-builder-mcp/sites.json). When set, the legacy YTB_MCP_SITE_URL / YTB_MCP_BEARER_TOKEN fields are ignored. Create via `npx -y @wootsup/yt-builder-mcp add-site`.",
+            "required": false
+        },
+        "YTB_MCP_SITE_URL": {
+            "type": "string",
+            "title": "Site URL",
+            "description": "Base URL of the site (e.g. https://example.com, https://example.com/wordpress for subdir WordPress, https://example.com/joomla for subdir Joomla). Without trailing slash.",
+            "required": false
+        },
+        "YTB_MCP_PLATFORM": {
+            "type": "string",
+            "title": "Platform (optional)",
+            "description": "CMS platform hint. Allowed values: \"auto\" (default — auto-detect from URL path and, if ambiguous, runtime-probe both platforms' /health endpoints), \"wordpress\", or \"joomla\". Set explicitly only to override auto-detection (e.g. when the host blocks anonymous health probes).",
+            "required": false,
+            "default": "auto"
         },
         "YTB_MCP_BEARER_TOKEN": {
             "type": "string",
             "title": "Bearer token",
-            "description": "Bearer token generated in wp-admin → Tools → YT Builder MCP → Generate Key.",
-            "required": true,
+            "description": "Bearer token generated in the YT Builder MCP admin UI (WordPress: Tools → YT Builder MCP; Joomla: Components → YT Builder MCP) → Generate Key. Scope: write is sufficient for most agent workflows; admin only for key-management.",
+            "required": false,
             "sensitive": true
         }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@wootsup/yt-builder-mcp",
-    "version": "1.0.1",
+    "version": "1.1.0",
     "type": "module",
     "description": "YT Builder MCP — drive your page builder from Claude, Cursor, Codex, Gemini and 5 other MCP-capable AI assistants. Built for YOOtheme Pro 4.0+. Independent third-party project, not affiliated with YOOtheme GmbH.",
     "license": "MIT",
@@ -70,10 +70,12 @@
     },
     "devDependencies": {
         "@types/node": "^20.11.0",
+        "@types/proper-lockfile": "^4.1.4",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
         "@typescript-eslint/parser": "^8.0.0",
         "@vitest/coverage-v8": "^1.4.0",
         "eslint": "^9.0.0",
+        "proper-lockfile": "^4.1.2",
         "typescript": "^5.4.0",
         "typescript-eslint": "^8.0.0",
         "vitest": "^1.4.0"