@respira/wordpress-mcp-server 7.2.6 → 7.2.8

package/dist/server.d.ts

@@ -149,6 +149,17 @@ export declare class RespiraWordPressServer {
      * the plugin source (the first release tag that contains each route).
      */
     private static readonly TOOL_MIN_PLUGIN_VERSION;
+    /**
+     * Capability negotiation Phase 2 (7.2.7): the feature flag each version-skewed
+     * tool needs. From plugin 7.4.20 the compatibility endpoint declares these
+     * flags from its LIVE registered REST routes, so this is an exact "does the
+     * route exist on this install" signal — more precise than the version map
+     * above and self-maintaining. The version map stays as the fallback for
+     * plugins older than 7.4.20, which do not declare per-capability features yet.
+     */
+    private static readonly TOOL_REQUIRED_FEATURE;
+    /** First plugin version that declares per-capability features (Phase 2). */
+    private static readonly FEATURE_DECL_MIN_PLUGIN_VERSION;
     /** True when version `a` is strictly older than `b` (both "x.y.z"). */
     private static versionLt;
     private filterToolsByContext;

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoBH,OAAO,KAAK,EAAE,mBAAmB,EAAe,MAAM,kBAAkB,CAAC;AAkQzE,qBAAa,sBAAsB;IACjC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,KAAK,CAA2C;IACxD,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,cAAc,CAAwB;IAC9C,OAAO,CAAC,YAAY,CAA4B;IAChD,8EAA8E;IAC9E,OAAO,CAAC,YAAY,CAA4B;IAChD,8EAA8E;IAC9E,OAAO,CAAC,mBAAmB,CAAS;IAEpC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAsB;IAEhE;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;gBA4Bb,WAAW,EAAE,mBAAmB,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE;IAsVvE,OAAO,CAAC,cAAc;IAItB;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IA4BrB,gEAAgE;IAChE,OAAO,CAAC,aAAa;IAUrB;;;;;;OAMG;YACW,UAAU;IAgDxB;;;;;;;;;;;;;;OAcG;YACW,WAAW;IAiJzB;;;;;;;;;OASG;YACW,kBAAkB;IAiHhC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,6BAA6B;IA0BrC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,yBAAyB;IA+BjC,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,aAAa;YAmQP,kBAAkB;YA6BlB,yBAAyB;IASvC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;YAyBd,QAAQ;IAuwFtB;;;;;;OAMG;IACH,yEAAyE;IACzE,OAAO,CAAC,mBAAmB,CAAoD;IAC/E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAElD;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAQ7C;IAEF,uEAAuE;IACvE,OAAO,CAAC,MAAM,CAAC,SAAS;YAWV,oBAAoB;YAwEpB,2BAA2B;IAazC;;;;OAIG;YACW,cAAc;IAY5B,OAAO,CAAC,mBAAmB;IAwT3B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAe3C;IAEF;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;YAmCpB,cAAc;IAqG5B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,eAAe;YAuCT,gBAAgB;IA22B9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAwUzB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA6UxB,GAAG;CAyCV"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoBH,OAAO,KAAK,EAAE,mBAAmB,EAAe,MAAM,kBAAkB,CAAC;AAqTzE,qBAAa,sBAAsB;IACjC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,KAAK,CAA2C;IACxD,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,cAAc,CAAwB;IAC9C,OAAO,CAAC,YAAY,CAA4B;IAChD,8EAA8E;IAC9E,OAAO,CAAC,YAAY,CAA4B;IAChD,8EAA8E;IAC9E,OAAO,CAAC,mBAAmB,CAAS;IAEpC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAsB;IAEhE;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;gBA4Bb,WAAW,EAAE,mBAAmB,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE;IAsVvE,OAAO,CAAC,cAAc;IAItB;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IA4BrB,gEAAgE;IAChE,OAAO,CAAC,aAAa;IAUrB;;;;;;OAMG;YACW,UAAU;IAgDxB;;;;;;;;;;;;;;OAcG;YACW,WAAW;IAiJzB;;;;;;;;;OASG;YACW,kBAAkB;IAiHhC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,6BAA6B;IA0BrC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,yBAAyB;IA+BjC,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,aAAa;YA2QP,kBAAkB;YA6BlB,yBAAyB;IASvC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;YAyBd,QAAQ;IAuwFtB;;;;;;OAMG;IACH,yEAAyE;IACzE,OAAO,CAAC,mBAAmB,CAAoD;IAC/E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAElD;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAQ7C;IAEF;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAQ3C;IAEF,4EAA4E;IAC5E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,+BAA+B,CAAY;IAEnE,uEAAuE;IACvE,OAAO,CAAC,MAAM,CAAC,SAAS;YAWV,oBAAoB;YAqFpB,2BAA2B;IAazC;;;;OAIG;YACW,cAAc;IAY5B,OAAO,CAAC,mBAAmB;IAwT3B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAe3C;IAEF;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;YAmCpB,cAAc;IAqG5B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,eAAe;YAuCT,gBAAgB;IA22B9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAwUzB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA6UxB,GAAG;CAyCV"}

package/dist/server.js

@@ -17,6 +17,58 @@ import { getBricksTools, dispatchBricksTool } from './bricks-tools.js';
 import { getElementorTools, dispatchElementorTool } from './elementor-tools.js';
 import { getAcfTools, ACF_TOOL_NAMES } from './acf-tools.js';
 import { getUsageEmitter, deriveToolKind } from './usage-emitter.js';
+/**
+ * Per-tool argument aliases. AI clients (especially Cowork / Claude desktop)
+ * frequently pass a natural-but-wrong key for a value: `pageId` / `page_id`
+ * instead of `id`, `filePath` instead of `file`. Because the dispatch never
+ * validated required params, a misnamed id silently produced a broken request
+ * like `/wp-json/respira/v2/pages/undefined`, and a misnamed file produced an
+ * empty upload that failed with "Could not connect — no response received".
+ *
+ * This map fills the canonical key a handler reads from the first present
+ * synonym, and ONLY when the canonical key is absent — an explicit value is
+ * never overwritten. Keyed by the canonical (wordpress_*) tool name, i.e.
+ * after normalizeToolName().
+ */
+const TOOL_ARG_ALIASES = {
+    wordpress_read_page: { id: ['page_id', 'pageId', 'post_id', 'postId'] },
+    wordpress_read_post: { id: ['post_id', 'postId', 'page_id', 'pageId'] },
+    wordpress_create_page_duplicate: {
+        original_id: ['page_id', 'pageId', 'id', 'original_page_id', 'originalId'],
+    },
+    wordpress_create_post_duplicate: {
+        original_id: ['post_id', 'postId', 'id', 'original_post_id', 'originalId'],
+    },
+    wordpress_get_snapshot: { snapshot_uuid: ['snapshot_id', 'snapshotId', 'uuid', 'id'] },
+    wordpress_find_element: { post_id: ['page_id', 'pageId', 'id', 'postId'] },
+    wordpress_upload_media: {
+        file: ['filePath', 'file_path', 'path', 'url', 'file_url', 'fileUrl'],
+        filename: ['file_name', 'fileName', 'name'],
+    },
+};
+/**
+ * Fill canonical argument keys from known synonyms, in place. No-op for tools
+ * without an alias entry and for args that already carry the canonical key.
+ */
+function normalizeToolArgs(canonicalName, args) {
+    if (!args || typeof args !== 'object')
+        return;
+    const aliases = TOOL_ARG_ALIASES[canonicalName];
+    if (!aliases)
+        return;
+    const record = args;
+    const isSet = (v) => v !== undefined && v !== null && v !== '';
+    for (const [canonical, synonyms] of Object.entries(aliases)) {
+        if (isSet(record[canonical]))
+            continue;
+        for (const syn of synonyms) {
+            if (isSet(record[syn])) {
+                record[canonical] = record[syn];
+                break;
+            }
+        }
+    }
+}
 /**
  * Read the server version from package.json at module load time so the
  * MCP handshake, the `instructions` block, and the version-checker all
@@ -1163,6 +1215,12 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             // (wordpress_redeem_token) because normalizeToolName rewrites the
             // respira_* alias to wordpress_* before dispatch.
             const canonical = this.normalizeToolName(name).canonical;
+            // Tolerate natural-but-wrong arg names from AI clients (pageId/page_id
+            // vs id, filePath vs file). Fills canonical keys from synonyms in place
+            // so a misnamed required param no longer yields /pages/undefined or an
+            // empty "no response received" upload. No-op for tools without aliases;
+            // an explicit canonical value is never overwritten.
+            normalizeToolArgs(canonical, args);
             if (canonical === 'wordpress_redeem_token') {
                 // redeemInstallToken returns a plain object. Wrap it in the standard
                 // MCP content envelope — the early-exit path bypasses the normal
@@ -4272,6 +4330,25 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
         wordpress_write_theme_file: '7.0.42',
         wordpress_append_theme_file: '7.0.42',
     };
+    /**
+     * Capability negotiation Phase 2 (7.2.7): the feature flag each version-skewed
+     * tool needs. From plugin 7.4.20 the compatibility endpoint declares these
+     * flags from its LIVE registered REST routes, so this is an exact "does the
+     * route exist on this install" signal — more precise than the version map
+     * above and self-maintaining. The version map stays as the fallback for
+     * plugins older than 7.4.20, which do not declare per-capability features yet.
+     */
+    static TOOL_REQUIRED_FEATURE = {
+        wordpress_run_pagespeed_audit: 'pagespeed',
+        wordpress_analyze_pagespeed: 'pagespeed',
+        wordpress_abilities_gap_report: 'abilities',
+        wordpress_invoke_ability: 'abilities',
+        wordpress_read_theme_file: 'theme_files',
+        wordpress_write_theme_file: 'theme_files',
+        wordpress_append_theme_file: 'theme_files',
+    };
+    /** First plugin version that declares per-capability features (Phase 2). */
+    static FEATURE_DECL_MIN_PLUGIN_VERSION = '7.4.20';
     /** True when version `a` is strictly older than `b` (both "x.y.z"). */
     static versionLt(a, b) {
         const pa = a.split('.').map((n) => parseInt(n, 10) || 0);
@@ -4312,6 +4389,12 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             /* non-fatal — fall through with whatever version we have (possibly null) */
         }
         const pluginVersion = this.currentSite.pluginVersion ?? null;
+        // Phase 2 (7.2.7): plugin 7.4.20+ declares per-capability features from its
+        // live REST routes; trust those exactly. Older plugins do not, so they fall
+        // back to the version map in the per-tool gate below.
+        const pluginFeatures = this.currentSite.pluginFeatures ?? [];
+        const declaresFeatures = !!pluginVersion &&
+            !RespiraWordPressServer.versionLt(pluginVersion, RespiraWordPressServer.FEATURE_DECL_MIN_PLUGIN_VERSION);
         const detectedBuilder = (context?.page_builder?.name || '').toLowerCase();
         const hasWooCommerce = Boolean(context?.woocommerce?.active || context?.addons?.woocommerce?.installed);
         return tools.filter((tool) => {
@@ -4336,10 +4419,16 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             if (name.startsWith('woocommerce_')) {
                 return hasWooCommerce;
             }
-            // Capability negotiation: hide tools whose plugin route only exists from a
-            // newer plugin version than the connected site runs (avoids rest_no_route
-            // 404s on version-skewed sites). Conservative: only when the plugin version
-            // is KNOWN and below the tool's verified minimum.
+            // Capability negotiation: hide tools whose plugin route the connected site
+            // does not expose (avoids rest_no_route 404s on version-skewed sites).
+            // Prefer the plugin's declared per-capability features (7.4.20+, computed
+            // from its live routes — exact), and fall back to the verified version map
+            // for older plugins that do not declare them. Both are conservative: a tool
+            // is hidden only on a positive signal that its route is absent.
+            const reqFeature = RespiraWordPressServer.TOOL_REQUIRED_FEATURE[name];
+            if (reqFeature && declaresFeatures) {
+                return pluginFeatures.includes(reqFeature);
+            }
             const minPv = RespiraWordPressServer.TOOL_MIN_PLUGIN_VERSION[name];
             if (minPv && pluginVersion && RespiraWordPressServer.versionLt(pluginVersion, minPv)) {
                 return false;