@respira/wordpress-mcp-server 8.3.25 → 8.3.27

package/dist/wordpress-client.js

@@ -647,6 +647,38 @@ function findRedirectRefusal(error) {
     }
     return null;
 }
+/**
+ * A JavaScript non-value that reached a URL as text.
+ *
+ * `${undefined}` is a string, and a template-literal route builder will put it
+ * in the path without complaint. WordPress then answers rest_no_route, which
+ * looks exactly like a route the plugin never registered. Ticket 81c478df:
+ * POST /wp-json/respira/v2/pages/undefined/duplicate was reported to the
+ * operator as an out-of-date plugin, on a site with no update available.
+ */
+const UNUSABLE_PATH_SEGMENTS = new Set(['undefined', 'null', 'nan', '[object object]']);
+/**
+ * The first path segment that cannot possibly identify anything, or null.
+ * Query strings are ignored: only the path can break route matching.
+ */
+function findUnusablePathSegment(url) {
+    const path = String(url || '').split('#')[0].split('?')[0];
+    for (const rawSegment of path.split('/')) {
+        if (!rawSegment)
+            continue;
+        let segment = rawSegment;
+        try {
+            segment = decodeURIComponent(rawSegment);
+        }
+        catch {
+            // A malformed escape is not a question this function answers.
+        }
+        segment = segment.trim();
+        if (segment && UNUSABLE_PATH_SEGMENTS.has(segment.toLowerCase()))
+            return segment;
+    }
+    return null;
+}
 /** Verbs WordPress lets a POST stand in for via `_method` / X-HTTP-Method-Override. */
 const METHOD_OVERRIDE_VERBS = new Set(['PUT', 'PATCH', 'DELETE']);
 function headerValue(headers, name) {
@@ -698,6 +730,183 @@ function writeWasAnsweredAsRead(response, sentMethod) {
         return false;
     return /^[A-Za-z0-9._:-]{8,128}$/.test(headerValue(response?.config?.headers, 'Idempotency-Key'));
 }
+/**
+ * Who answers `/.well-known/oauth-protected-resource`: WordPress, or the host?
+ *
+ * Ticket 087103bc. Managed hosts commonly answer everything under
+ * `/.well-known/` themselves so ACME challenges keep working, and a request
+ * for anything else there gets the host's own 404 page without WordPress ever
+ * running. ChatGPT only ever looks at that address, so the connection fails
+ * while the plugin is perfectly fine: on the site in the ticket, an nginx
+ * SiteGround install, `/.well-known/oauth-protected-resource` answered a host
+ * 404 titled "404 - Not found" with no WordPress markers in it, while
+ * `/wp-json/respira/v1/oauth-protected-resource` answered 200 JSON.
+ *
+ * A body counts as WordPress' own when it is the metadata document (it names a
+ * `resource`), or when it carries something only WordPress emits (wp-content,
+ * wp-includes, wp-json, the api.w.org link rel). A host 404 has none of those,
+ * and neither does a CDN error page.
+ *
+ * Reads two probes the caller already made. No network of its own.
+ */
+export function wellKnownOwnership(wellKnown, restMirror) {
+    const evidence = {
+        well_known_url: wellKnown?.url ?? null,
+        well_known_status: wellKnown?.status ?? null,
+        well_known_title: wellKnown?.title_text ?? null,
+        well_known_looks_like_wordpress: null,
+        rest_mirror_url: restMirror?.url ?? null,
+        rest_mirror_status: restMirror?.status ?? null,
+    };
+    if (!wellKnown || typeof wellKnown.status !== 'number') {
+        evidence.note =
+            'The /.well-known/ probe did not come back, so nothing can be said about who answers it.';
+        return { verdict: 'unknown', evidence, recommendation: null };
+    }
+    const body = String(wellKnown.body_snippet ?? '');
+    const isMetadata = wellKnown.status >= 200 && wellKnown.status < 300 && /"resource"\s*:/.test(body);
+    const hasWordPressMarkers = /wp-content|wp-includes|wp-json|api\.w\.org/i.test(`${body} ${String(wellKnown.headers?.link ?? '')}`);
+    const servedByWordPress = isMetadata || hasWordPressMarkers;
+    evidence.well_known_looks_like_wordpress = servedByWordPress;
+    const mirrorOk = !!restMirror &&
+        typeof restMirror.status === 'number' &&
+        restMirror.status >= 200 &&
+        restMirror.status < 300;
+    if (servedByWordPress) {
+        return { verdict: 'wordpress_serves_it', evidence, recommendation: null };
+    }
+    if (!mirrorOk) {
+        evidence.note =
+            'Neither address answered as WordPress, so this is not the host reserving /.well-known/: the plugin route did not answer either.';
+        return { verdict: 'both_unreachable', evidence, recommendation: null };
+    }
+    return {
+        verdict: 'host_answers_first',
+        evidence,
+        recommendation: `The host answers ${wellKnown.url} itself, before WordPress. It returned ${wellKnown.status}` +
+            (wellKnown.title_text ? ` with a page titled "${wellKnown.title_text}"` : '') +
+            ', and that body carries no WordPress marker, while ' +
+            `${restMirror?.url} returned ${restMirror?.status} as WordPress. ` +
+            'ChatGPT only checks the /.well-known/ address during discovery, so the connection fails there even though the ' +
+            'plugin is working. The fix is one line for the host: let WordPress handle requests under /.well-known/ that are ' +
+            'not ACME challenges, meaning everything except /.well-known/acme-challenge/.',
+    };
+}
+/**
+ * The evidence a web-server 403 leaves behind, in the words of the response.
+ *
+ * Ticket 685d8023. Uploads above roughly 500 bytes were refused with a 403 on
+ * one site while a 250-byte upload went through, and the answer was a ranked
+ * list of things it might be. That list was a guess, and the customer spent
+ * the afternoon checking Cloudflare rules that were not the cause.
+ *
+ * This reports only what is in the request and the response: the verb and
+ * path, how many bytes the body carried, the headers that name the layer, and
+ * the absence of the header the Respira plugin stamps on every REST response
+ * it serves (X-Respira-Plugin-Version). That absence is the proof that
+ * WordPress never ran, which also means the call wrote nothing.
+ *
+ * The upload path is already multipart/form-data, the shape a WAF is least
+ * likely to object to, so there is no smaller or plainer request left to try
+ * from this side. That is why the message asks the host for the rule instead
+ * of promising a workaround.
+ */
+export function nonWordPressBlockEvidence(error) {
+    const response = error?.response ?? {};
+    const config = error?.config ?? {};
+    const headers = {};
+    Object.entries(response.headers || {}).forEach(([key, value]) => {
+        headers[String(key).toLowerCase()] = String(value);
+    });
+    const method = String(config.method || '').toUpperCase() || 'the request';
+    const path = String(config.url || '') || 'the endpoint';
+    const bodyBytes = (() => {
+        const declared = Number(config.headers?.['Content-Length'] ?? config.headers?.['content-length']);
+        if (Number.isFinite(declared) && declared > 0)
+            return declared;
+        const data = config.data;
+        if (data == null)
+            return 0;
+        if (typeof data === 'string')
+            return Buffer.byteLength(data);
+        if (Buffer.isBuffer(data))
+            return data.length;
+        try {
+            return Buffer.byteLength(JSON.stringify(data));
+        }
+        catch {
+            return 0;
+        }
+    })();
+    const contentType = String(config.headers?.['Content-Type'] ?? config.headers?.['content-type'] ?? '');
+    const named = [];
+    for (const header of ['server', 'cf-ray', 'x-sucuri-id', 'x-sucuri-block', 'x-powered-by', 'x-litespeed-cache']) {
+        if (headers[header])
+            named.push(`${header}: ${headers[header]}`);
+    }
+    const lines = [];
+    lines.push(`Evidence from this request: ${method} ${path}` +
+        (bodyBytes ? `, a ${bodyBytes.toLocaleString('en-US')} byte body` : ', no body') +
+        (contentType ? ` sent as ${contentType.split(';')[0]}` : '') +
+        '.');
+    lines.push(headers['x-respira-plugin-version']
+        ? `The response carries X-Respira-Plugin-Version: ${headers['x-respira-plugin-version']}, so WordPress did answer.`
+        : 'The response carries no X-Respira-Plugin-Version header, which the Respira plugin stamps on every REST response it serves. WordPress never ran, so nothing was written and the call is safe to retry once the block is lifted.');
+    lines.push(named.length
+        ? `Response headers that name the layer: ${named.join('; ')}.`
+        : 'The response named no server or CDN in its headers, so the layer that refused it did not identify itself.');
+    return lines.join(' ');
+}
+/**
+ * What to ask the host, with the exact request in it.
+ */
+export function nonWordPressBlockAsk(error) {
+    const config = error?.config ?? {};
+    const method = String(config.method || 'POST').toUpperCase();
+    const path = String(config.url || '');
+    // The base URL carries the namespace the request actually used, so the
+    // address handed to the host is the one in their access log, not a guess.
+    const base = String(config.baseURL || '').replace(/\/+$/, '');
+    const full = path.startsWith('http')
+        ? path
+        : base
+            ? `${base}${path}`
+            : `/wp-json/respira/v1${path}`;
+    return ('What to ask the host, word for word: "A ' +
+        method +
+        ' to ' +
+        full +
+        ' is answered 403 by the web server before PHP runs. Please find the rule that rejected it in the ' +
+        'ModSecurity audit log or the WAF event log at that timestamp, tell me the rule id, and allow that path." ' +
+        'The rule id is the one fact that ends this; everything else is guesswork on both sides.');
+}
+/**
+ * Split a plugin identifier into the path segment and the body field.
+ *
+ * Ticket dfc0e156. WordPress names a plugin by its file: `WP PROTECTION/
+ * SECURITY.php`. That slash cannot travel inside one URL path segment. Encoded
+ * as `%2F`, Apache answers 404 before PHP runs unless AllowEncodedSlashes is
+ * on, and the servers that do pass it through hand WordPress a decoded slash,
+ * which the single-segment route does not match. Both attempts in the report
+ * came back `route_not_found`.
+ *
+ * So the folder goes in the path, where it is always one segment, and the
+ * exact file goes in the body as `plugin_file`. A plugin 9.0.0 site that does
+ * not know `plugin_file` resolves the folder on its own and still acts on the
+ * right plugin; a single-file plugin (`hello.php`) has no slash and is
+ * unchanged.
+ */
+export function pluginRouteTarget(slug) {
+    const identifier = String(slug ?? '').trim().replace(/^\/+/, '');
+    const separator = identifier.indexOf('/');
+    if (separator === -1) {
+        return { segment: identifier, body: {} };
+    }
+    return {
+        segment: identifier.slice(0, separator),
+        body: { plugin_file: identifier },
+    };
+}
 export class WordPressClient {
     client;
     rootClient;
@@ -1891,6 +2100,53 @@ export class WordPressClient {
             return null;
         }
     }
+    /**
+     * Explain a `rest_no_route` that landed under a namespace WordPress DID
+     * register.
+     *
+     * This used to say one thing and one thing only: "the installed plugin is
+     * older than this tool. Update Respira in wp-admin under Plugins." Ticket
+     * 81c478df came from a site running 8.9.1 with no update offered anywhere.
+     * The real cause was the request path, which carried the literal string
+     * `undefined` where the page id belonged. The operator was sent to wp-admin
+     * three times across two sessions to install an update that did not exist,
+     * and the one fact that would have ended it in seconds, the malformed
+     * segment, was sitting in the message already.
+     *
+     * So say only what can be shown:
+     *
+     *   1. An unusable path segment is visible in the URL. Nothing about the
+     *      plugin's age explains it and no update fixes it.
+     *   2. The plugin publishes a max_mcp_version below this build. That is the
+     *      plugin declaring, in its own words, that it does not know this tool
+     *      version, which is the only evidence that supports "update the plugin".
+     *   3. Neither. Then the route is missing for a reason this process cannot
+     *      see, and guessing at the version costs the operator an afternoon.
+     */
+    async explainMissingSubroute(reqUrl) {
+        const lead = 'The Respira namespace IS registered, so the plugin is active and REST works: this specific route is missing.';
+        const badSegment = findUnusablePathSegment(reqUrl);
+        if (badSegment) {
+            return (`${lead} The request carried "${badSegment}" where the route expects an id, so no route could match it. ` +
+                'That is a bad argument on this call, not an out-of-date plugin: retry with the numeric id, ' +
+                'checking the tool schema for the parameter name it wants.');
+        }
+        // checkCompatibility() caches, swallows its own errors, and is usually
+        // already resolved by the time any tool errors out.
+        await this.checkCompatibility();
+        const pluginLabel = this.pluginVersion ? `v${this.pluginVersion}` : 'installed version unknown';
+        const outranksPlugin = this.maxMcpVersion
+            ? this.compareSemver(this.parseSemver(MCP_CLIENT_VERSION), this.parseSemver(this.maxMcpVersion)) > 0
+            : false;
+        if (outranksPlugin) {
+            return (`${lead} The plugin (${pluginLabel}) supports Respira MCP up to v${this.maxMcpVersion} and this tool runs ` +
+                `v${MCP_CLIENT_VERSION}, so the route arrived after the plugin did. Update Respira in wp-admin under Plugins.`);
+        }
+        return (`${lead} The plugin (${pluginLabel}) does not report itself as older than this tool ` +
+            `(MCP v${MCP_CLIENT_VERSION}${this.maxMcpVersion ? `, plugin ceiling v${this.maxMcpVersion}` : ', plugin publishes no version ceiling'}), ` +
+            'so an update is probably not the fix. Check the request path and the arguments first, ' +
+            'then run respira_diagnose_connection.');
+    }
     async handleError(error) {
         if (error.response) {
             const status = error.response.status;
@@ -1982,15 +2238,25 @@ export class WordPressClient {
                     // the wrong place. G.B. at denovoagents.com lost roughly a day to it
                     // in August 2026 and found it himself; the old wording here pointed
                     // him at plugins, which was not where the block lived.
+                    // Ticket 685d8023: the ranked list below used to be the whole
+                    // answer, and it sent a customer through Cloudflare rules that were
+                    // not the cause while uploads over ~500 bytes kept failing and a
+                    // 250-byte one succeeded. The evidence comes first now, and the
+                    // guesses are labelled as the usual suspects rather than as a
+                    // diagnosis. The upload body is already multipart/form-data, so
+                    // there is no plainer shape left to send from this side.
                     return this.codedError(`Site blocked: ${this.siteConfig.url} returned a 403 Forbidden from the web server (not WordPress).\n\n` +
-                        'Something in front of WordPress is refusing the request, so this is not a plugin or license problem. ' +
-                        'In order of how often it turns out to be the cause:\n' +
-                        '1. Cloudflare bot protection. "Block AI Scrapers and Crawlers", Bot Fight Mode, or a WAF rule. ' +
-                        'This is the most common cause and it is invisible from inside WordPress. ' +
-                        'Cloudflare dashboard: Security > Bots, and Security > WAF.\n' +
-                        '2. A security plugin such as Wordfence or Sucuri.\n' +
-                        '3. A host-level firewall or ModSecurity rule.\n\n' +
-                        'The fix in every case is to allow the /wp-json/respira/* path, or the MCP server\'s User-Agent, through that layer.', 'http_403_non_wordpress');
+                        nonWordPressBlockEvidence(error) +
+                        '\n\n' +
+                        nonWordPressBlockAsk(error) +
+                        '\n\n' +
+                        'Where this usually lives, in order, none of it confirmed by the response above: ' +
+                        'Cloudflare bot protection ("Block AI Scrapers and Crawlers", Bot Fight Mode, or a WAF rule, ' +
+                        'under Security > Bots and Security > WAF); a security plugin such as Wordfence or Sucuri; ' +
+                        'a host-level firewall or ModSecurity rule. ' +
+                        'The fix in every case is to allow the /wp-json/respira/* path, or this connector\'s User-Agent, through that layer. ' +
+                        'When small requests to the same path succeed and larger ones do not, the rule is matching on request size or on the ' +
+                        'body, so the size that first fails is worth quoting to the host too.', 'http_403_non_wordpress');
                 }
                 // Format error with instructions if available
                 return this.formatErrorWithInstructions(data);
@@ -2094,9 +2360,8 @@ export class WordPressClient {
                     // above) and retrying cannot help, because ?rest_route= reaches the
                     // same WordPress and gets the same answer. Either the whole respira
                     // namespace is missing, meaning the plugin is not active, or the
-                    // namespace is there and this one route is not, meaning the plugin
-                    // is older than the tool. Those need opposite fixes, and telling
-                    // someone to resave permalinks helps with neither.
+                    // namespace is there and this one route is not. Those need opposite
+                    // fixes, and telling someone to resave permalinks helps with neither.
                     const present = await this.isRespiraNamespaceRegistered();
                     if (present === false) {
                         apiError.message =
@@ -2107,9 +2372,7 @@ export class WordPressClient {
                     }
                     else if (present === true) {
                         apiError.message =
-                            `${apiError.message} The Respira namespace IS registered, so the plugin is active and REST works: ` +
-                                `this specific route is missing, which means the installed plugin is older than this tool. ` +
-                                `Update Respira in wp-admin under Plugins.`;
+                            `${apiError.message} ${await this.explainMissingSubroute(reqUrl)}`;
                     }
                 }
             }
@@ -3435,7 +3698,7 @@ export class WordPressClient {
     /**
      * Inject page builder content
      */
-    async injectBuilderContent(builder, pageId, content, diviVersion, editTarget, mode, confirmReplace) {
+    async injectBuilderContent(builder, pageId, content, diviVersion, editTarget, mode, confirmReplace, expectedVersion) {
         if (builder.toLowerCase() === 'divi') {
             if (!diviVersion) {
                 const existing = await this.extractBuilderContent('divi', pageId);
@@ -3482,6 +3745,7 @@ export class WordPressClient {
             editTarget,
             mode: mode || 'replace',
             confirm_replace: confirmReplace === true,
+            ...(expectedVersion ? { expected_version: expectedVersion } : {}),
         });
         return response.data;
     }
@@ -3576,7 +3840,7 @@ export class WordPressClient {
     /**
      * Update a specific module in a page builder page
      */
-    async updateModule(builder, pageId, moduleIdentifier, updates, editTarget) {
+    async updateModule(builder, pageId, moduleIdentifier, updates, editTarget, expectedVersion) {
         try {
             // Increase timeout for large content updates
             const timeout = updates.content && updates.content.length > 50000
@@ -3586,6 +3850,7 @@ export class WordPressClient {
                 module_identifier: moduleIdentifier,
                 updates,
                 editTarget,
+                ...(expectedVersion ? { expected_version: expectedVersion } : {}),
             }, { timeout });
             return response.data;
         }
@@ -3714,7 +3979,7 @@ export class WordPressClient {
     /**
      * Apply v2 builder patch operations.
      */
-    async applyBuilderPatch(builder, postId, operations, include, editTarget) {
+    async applyBuilderPatch(builder, postId, operations, include, editTarget, expectedVersion) {
         await this.ensureV2();
         // Ticket 9dee06c4: send find_element's vocabulary ({ type: "id", value })
         // in the canonical shape ({ id }), so it resolves on plugins that predate
@@ -3726,6 +3991,9 @@ export class WordPressClient {
         if (editTarget) {
             payload.editTarget = editTarget;
         }
+        if (expectedVersion) {
+            payload.expected_version = expectedVersion;
+        }
         const response = await this.rootClient.post(`/wp-json/respira/v2/builder/${builder}/patch/${postId}`, payload);
         return response.data;
     }
@@ -3974,6 +4242,13 @@ export class WordPressClient {
         // touching anything. What is being measured is whether the verb reaches
         // PHP at all, not whether the route exists.
         await probe('respira_ping_put', 'PUT', `${baseUrl}/wp-json/respira/v1/ping`);
+        // Probe 7 (ticket 087103bc): who answers `/.well-known/`. One request each,
+        // read-only, and only on an explicit diagnose call. ChatGPT's OAuth
+        // discovery looks at the canonical address and nowhere else, so a host that
+        // reserves /.well-known/ for ACME breaks the connection while the plugin is
+        // fine, and nothing inside WordPress can see it happen.
+        await probe('well_known_oauth_protected_resource', 'GET', `${baseUrl}/.well-known/oauth-protected-resource`);
+        await probe('respira_oauth_protected_resource', 'GET', `${baseUrl}/wp-json/respira/v1/oauth-protected-resource`);
         // Plugin diagnostic — go through the standard client so we share auth and
         // pick up errors via the existing handler if the endpoint isn't routed.
         let pluginDiagnostic = null;
@@ -4233,6 +4508,10 @@ export class WordPressClient {
                 'The MCP server will auto-fall-back to `?rest_route=` for this session — set ' +
                 '`forceRestRoute: true` in the site config to skip the pretty-permalink probe entirely.');
         }
+        const wellKnown = wellKnownOwnership(probes.find((p) => p.label === 'well_known_oauth_protected_resource'), probes.find((p) => p.label === 'respira_oauth_protected_resource'));
+        if (wellKnown.recommendation) {
+            recommendations.push(wellKnown.recommendation);
+        }
         return {
             success: true,
             site: {
@@ -4240,6 +4519,10 @@ export class WordPressClient {
                 url: this.siteConfig.url,
             },
             mcp_client_version: MCP_CLIENT_VERSION,
+            // Who serves the OAuth discovery address: 'wordpress_serves_it',
+            // 'host_answers_first' (the host reserves /.well-known/, which is what
+            // breaks ChatGPT discovery), 'both_unreachable' or 'unknown'.
+            well_known_discovery: wellKnown,
             plugin_diagnostic: pluginDiagnostic,
             plugin_diagnostic_error: pluginDiagnosticError,
             outside_probes: probes,
@@ -4445,12 +4728,13 @@ export class WordPressClient {
      * back on the second call with the same slug to complete.
      */
     async activatePlugin(slug, approvalToken, forceWithoutProbe) {
-        const body = {};
+        const target = pluginRouteTarget(slug);
+        const body = { ...target.body };
         if (approvalToken)
             body.approval_token = approvalToken;
         if (forceWithoutProbe)
             body.force_without_probe = true;
-        const response = await this.client.post(`/plugins/${encodeURIComponent(slug)}/activate`, body);
+        const response = await this.client.post(`/plugins/${encodeURIComponent(target.segment)}/activate`, body);
         return response.data;
     }
     /**
@@ -4458,8 +4742,11 @@ export class WordPressClient {
      * back on the second call with the same slug to complete.
      */
     async deactivatePlugin(slug, approvalToken) {
-        const body = approvalToken ? { approval_token: approvalToken } : undefined;
-        const response = await this.client.post(`/plugins/${encodeURIComponent(slug)}/deactivate`, body);
+        const target = pluginRouteTarget(slug);
+        const body = { ...target.body };
+        if (approvalToken)
+            body.approval_token = approvalToken;
+        const response = await this.client.post(`/plugins/${encodeURIComponent(target.segment)}/deactivate`, Object.keys(body).length ? body : undefined);
         return response.data;
     }
     /**
@@ -4467,8 +4754,11 @@ export class WordPressClient {
      * back on the second call with the same slug to complete.
      */
     async updatePlugin(slug, approvalToken) {
-        const body = approvalToken ? { approval_token: approvalToken } : undefined;
-        const response = await this.client.post(`/plugins/${encodeURIComponent(slug)}/update`, body);
+        const target = pluginRouteTarget(slug);
+        const body = { ...target.body };
+        if (approvalToken)
+            body.approval_token = approvalToken;
+        const response = await this.client.post(`/plugins/${encodeURIComponent(target.segment)}/update`, Object.keys(body).length ? body : undefined);
         return response.data;
     }
     /**
@@ -4496,9 +4786,13 @@ export class WordPressClient {
      * back on the second call with the same slug to complete.
      */
     async deletePlugin(slug, approvalToken) {
+        const target = pluginRouteTarget(slug);
+        const data = { ...target.body };
+        if (approvalToken)
+            data.approval_token = approvalToken;
         // axios delete supports a body via the `data` option.
-        const config = approvalToken ? { data: { approval_token: approvalToken } } : undefined;
-        const response = await this.client.delete(`/plugins/${encodeURIComponent(slug)}`, config);
+        const config = Object.keys(data).length ? { data } : undefined;
+        const response = await this.client.delete(`/plugins/${encodeURIComponent(target.segment)}`, config);
         return response.data;
     }
     // Users Management