@respira/wordpress-mcp-server 6.11.1 → 6.11.3

package/dist/wordpress-client.js

@@ -40,6 +40,23 @@ export class WordPressClient {
     versionWarning = null;
     // Last HTML-instead-of-JSON observation, surfaced by wordpress_diagnose_connection.
     lastHtmlInsteadOfJson = null;
+    /**
+     * Per-session sticky flag: once a `?rest_route=` retry succeeds (because a
+     * plugin or theme rewrite rule shadows the pretty `/wp-json/...` path and
+     * `redirect_canonical()` 301s the request to the homepage), every subsequent
+     * REST call from this client instance goes directly to `?rest_route=` form
+     * and skips the pretty-permalink probe. In-memory only, resets on restart.
+     * Can be primed via `siteConfig.forceRestRoute = true`.
+     */
+    useRestRouteFallback = false;
+    restRouteFallbackWarned = false;
+    /**
+     * Diagnostic: whether the most recent `?rest_route=` probe (either the
+     * automatic retry triggered by an HTML response or the explicit probe in
+     * `diagnoseConnection`) returned valid JSON. Surfaced as
+     * `rest_route_fallback_worked` on the diagnose tool result.
+     */
+    lastRestRouteFallbackWorked = null;
     constructor(siteConfig) {
         this.siteConfig = siteConfig;
         this.defaultHeaders = {
@@ -63,6 +80,32 @@ export class WordPressClient {
             headers: this.defaultHeaders,
             timeout: 30000,
         });
+        // Prime the per-session sticky flag from explicit per-site config.
+        if (siteConfig.forceRestRoute === true) {
+            this.useRestRouteFallback = true;
+        }
+        // Request interceptor: when the per-session sticky flag is on (either set
+        // explicitly via siteConfig.forceRestRoute or auto-tripped by a successful
+        // `?rest_route=` retry), rewrite outgoing `/wp-json/...` URLs to the
+        // `?rest_route=` form against the site root. Skips requests already in
+        // fallback form and requests flagged as the retry attempt itself
+        // (`_restRouteFallback: true` on the request config).
+        const requestInterceptor = (config) => {
+            try {
+                if (this.useRestRouteFallback &&
+                    config &&
+                    !config._restRouteFallback &&
+                    this.shouldRewriteToRestRoute(config)) {
+                    this.rewriteRequestToRestRoute(config);
+                }
+            }
+            catch {
+                // Never block a request on a rewrite error — fall through.
+            }
+            return config;
+        };
+        this.client.interceptors.request.use(requestInterceptor);
+        this.rootClient.interceptors.request.use(requestInterceptor);
         // Add response interceptor for error handling
         const errorInterceptor = async (error) => {
             const handledError = await this.handleError(error);
@@ -71,31 +114,72 @@ export class WordPressClient {
         // Success interceptor: detect HTML masquerading as JSON on Respira REST routes.
         // An edge layer (Cloudflare, Wordfence, .htaccess, maintenance page) can return a
         // 200 OK with an HTML body instead of JSON; if we don't catch it here, JSON.parse
-        // explodes deep in a tool handler with an opaque message. Throwing a structured
-        // error here gives diagnose_connection something to fingerprint.
-        const htmlGuard = (response) => {
-            this.detectHtmlInsteadOfJson(response);
-            return response;
+        // explodes deep in a tool handler with an opaque message. As of v6.11.2, when
+        // the failure mode looks like a WordPress rewrite shadowing the path
+        // (`/wp-json/[anything]` → homepage 301 from `redirect_canonical()`), we
+        // automatically retry the same call as `?rest_route=...` against the site
+        // root. If that succeeds, set `useRestRouteFallback` for the rest of the
+        // session and return the retried response. Otherwise surface the original
+        // error with both URLs in the message.
+        const htmlGuard = async (response) => {
+            const observation = this.observeHtmlInsteadOfJson(response);
+            if (!observation)
+                return response;
+            // Cache observation for diagnose_connection.
+            this.lastHtmlInsteadOfJson = observation;
+            // Try the `?rest_route=` fallback only once per request.
+            const requestConfig = response.config || {};
+            const isAlreadyFallback = requestConfig._restRouteFallback === true;
+            const canFallback = !isAlreadyFallback && this.canRewriteToRestRoute(requestConfig);
+            if (canFallback) {
+                try {
+                    const retryResp = await this.retryViaRestRoute(requestConfig);
+                    // If the retry returned HTML too, we drop through to the throw below.
+                    const retryObservation = this.observeHtmlInsteadOfJson(retryResp);
+                    if (!retryObservation) {
+                        // Sticky flag + one-time stderr warning per session per site.
+                        if (!this.useRestRouteFallback) {
+                            this.useRestRouteFallback = true;
+                            if (!this.restRouteFallbackWarned) {
+                                this.restRouteFallbackWarned = true;
+                                process.stderr.write(`[respira-mcp] Site ${this.siteConfig.name} has REST rewrite shadowing; ` +
+                                    `falling back to ?rest_route= for this session. ` +
+                                    `Run wordpress_diagnose_connection for triangulation.\n`);
+                            }
+                        }
+                        this.lastRestRouteFallbackWorked = true;
+                        return retryResp;
+                    }
+                    // Retry also returned HTML — record and fall through to error.
+                    this.lastRestRouteFallbackWorked = false;
+                }
+                catch {
+                    this.lastRestRouteFallbackWorked = false;
+                }
+            }
+            throw this.buildHtmlInsteadOfJsonError(observation, requestConfig);
         };
         this.client.interceptors.response.use(htmlGuard, errorInterceptor);
         this.rootClient.interceptors.response.use(htmlGuard, errorInterceptor);
     }
     /**
-     * Detect HTML responses on what should be JSON REST routes. Throws a structured
-     * Error with code `respira_html_instead_of_json` so callers (and the diagnose
-     * tool) can fingerprint the edge-layer interception.
+     * Inspect a response for the "HTML instead of JSON" failure mode on Respira
+     * REST routes. Returns a structured observation when the response looks like
+     * HTML (or null when it's a normal JSON response or a non-Respira call we
+     * shouldn't guard, e.g. wp-admin/admin-ajax media uploads). Pure detection;
+     * the caller decides whether to retry via `?rest_route=` or throw.
      */
-    detectHtmlInsteadOfJson(response) {
+    observeHtmlInsteadOfJson(response) {
         if (!response || typeof response !== 'object')
-            return;
+            return null;
         const requestUrl = response.config?.url || '';
         const baseUrl = response.config?.baseURL || '';
         const fullUrl = requestUrl.startsWith('http') ? requestUrl : `${baseUrl}${requestUrl}`;
-        // Only guard Respira REST routes — other endpoints (e.g. media uploads to
-        // wp-admin/admin-ajax) may legitimately return HTML.
-        const isRespiraRoute = /\/wp-json\/respira\//i.test(fullUrl);
+        // Guard Respira REST traffic in either form: pretty `/wp-json/respira/...`
+        // or `?rest_route=/respira/...` against the site root.
+        const isRespiraRoute = /\/wp-json\/respira\//i.test(fullUrl) || /[?&]rest_route=\/?respira\//i.test(fullUrl);
         if (!isRespiraRoute)
-            return;
+            return null;
         const headers = response.headers || {};
         const contentType = (headers['content-type'] || headers['Content-Type'] || '').toString().toLowerCase();
         const body = response.data;
@@ -104,11 +188,17 @@ export class WordPressClient {
             : Buffer.isBuffer?.(body)
                 ? body.toString('utf8')
                 : null;
+        // The HTML detector also matches WordPress-style 301 redirects that returned
+        // an empty body with just a `Location:` header (when transformResponse keeps
+        // the body raw, axios usually still has data===''). The caller spots those
+        // via the `x-redirect-by: wordpress` header signature, but in the success
+        // path axios has already followed the redirect, so we end up with the
+        // homepage HTML body — caught by the regex below.
         const looksLikeHtml = contentType.includes('text/html') ||
             (typeof bodyAsString === 'string' &&
                 /^\s*(<!doctype|<html)/i.test(bodyAsString.slice(0, 64)));
         if (!looksLikeHtml)
-            return;
+            return null;
         const status = response.status ?? 0;
         const snippet = (bodyAsString ?? '').slice(0, 200);
         // Extract <title> text if present.
@@ -119,8 +209,7 @@ export class WordPressClient {
                 titleText = m[1].trim();
             }
         }
-        // Cache the observation for diagnose_connection.
-        this.lastHtmlInsteadOfJson = {
+        return {
             url: fullUrl,
             status,
             contentType: contentType || 'unknown',
@@ -128,17 +217,193 @@ export class WordPressClient {
             bodySnippet: snippet,
             detectedAt: new Date().toISOString(),
         };
-        const titleLabel = titleText ? `'${titleText}'` : '(no <title>)';
+    }
+    /**
+     * Build the structured "HTML instead of JSON" Error that gets surfaced when
+     * neither the original pretty-permalink request nor the `?rest_route=`
+     * fallback returned JSON. Includes both URLs so the user can see the fix
+     * was tried.
+     */
+    buildHtmlInsteadOfJsonError(observation, requestConfig) {
+        const titleLabel = observation.titleText ? `'${observation.titleText}'` : '(no <title>)';
+        const fallbackUrl = this.computeRestRouteFallbackUrl(requestConfig);
+        const fallbackHint = fallbackUrl
+            ? ` Auto-fallback to ${fallbackUrl} also returned HTML.`
+            : '';
         const err = new Error(`Got HTML instead of JSON. Page title: ${titleLabel}. ` +
-            `Likely an edge layer (Cloudflare, Wordfence, .htaccess) is intercepting REST requests. ` +
+            `Likely an edge layer (Cloudflare, Wordfence, .htaccess) or a plugin/theme ` +
+            `rewrite rule is intercepting REST requests on ${observation.url}.${fallbackHint} ` +
             `Run wordpress_diagnose_connection for a fingerprint.`);
         err.code = 'respira_html_instead_of_json';
-        err.status = status;
-        err.contentType = contentType;
-        err.bodySnippet = snippet;
-        err.titleText = titleText;
-        err.url = fullUrl;
-        throw err;
+        err.status = observation.status;
+        err.contentType = observation.contentType;
+        err.bodySnippet = observation.bodySnippet;
+        err.titleText = observation.titleText;
+        err.url = observation.url;
+        if (fallbackUrl)
+            err.fallbackUrl = fallbackUrl;
+        return err;
+    }
+    // ---------------------------------------------------------------------------
+    // ?rest_route= fallback helpers (v6.11.2)
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns true when this axios request config targets a `/wp-json/...` path
+     * that we can rewrite to `?rest_route=...` against the site root.
+     */
+    canRewriteToRestRoute(config) {
+        if (!config)
+            return false;
+        const requestUrl = config.url || '';
+        const baseUrl = config.baseURL || '';
+        const fullUrl = requestUrl.startsWith('http') ? requestUrl : `${baseUrl}${requestUrl}`;
+        if (!fullUrl)
+            return false;
+        if (/[?&]rest_route=/i.test(fullUrl))
+            return false;
+        return /\/wp-json\//i.test(fullUrl);
+    }
+    /**
+     * Same as `canRewriteToRestRoute`, plus a guard against rewriting twice (the
+     * request interceptor invokes this; the response interceptor's retry path
+     * uses the lower-level `canRewriteToRestRoute`).
+     */
+    shouldRewriteToRestRoute(config) {
+        if (!config)
+            return false;
+        if (config._restRouteRewritten)
+            return false;
+        return this.canRewriteToRestRoute(config);
+    }
+    /**
+     * Convert a `/wp-json/<namespace>/<route>` request config into an equivalent
+     * `?rest_route=/<namespace>/<route>` request against the site root. Mutates
+     * the config in place so axios picks up the rewrite naturally on the
+     * outgoing request. Marks the config as rewritten so subsequent interceptor
+     * passes don't double-rewrite.
+     */
+    rewriteRequestToRestRoute(config) {
+        const fallbackUrl = this.computeRestRouteFallbackUrl(config);
+        if (!fallbackUrl)
+            return;
+        config.url = fallbackUrl;
+        config.baseURL = undefined;
+        // Wipe `params` because we've folded everything into the URL string and
+        // axios would otherwise re-append them after a `?` it inserts itself.
+        config.params = undefined;
+        config._restRouteRewritten = true;
+    }
+    /**
+     * Pure helper: compute the `?rest_route=` URL that corresponds to a given
+     * axios request config. Returns null when the config doesn't target a
+     * `/wp-json/...` path. Preserves all original query params.
+     */
+    computeRestRouteFallbackUrl(config) {
+        if (!config)
+            return null;
+        const requestUrl = config.url || '';
+        const baseUrl = config.baseURL || '';
+        const fullUrlStr = requestUrl.startsWith('http') ? requestUrl : `${baseUrl}${requestUrl}`;
+        if (!fullUrlStr)
+            return null;
+        // Already in fallback form? Nothing to do.
+        if (/[?&]rest_route=/i.test(fullUrlStr))
+            return null;
+        let parsed;
+        try {
+            parsed = new URL(fullUrlStr);
+        }
+        catch {
+            return null;
+        }
+        // Extract `/<namespace>/<route>` from the pathname after `/wp-json`.
+        const pathMatch = parsed.pathname.match(/^(.*?)\/wp-json(\/.*)?$/i);
+        if (!pathMatch)
+            return null;
+        const beforeWpJson = pathMatch[1] || '';
+        const afterWpJson = pathMatch[2] || '/';
+        // Build the new URL: <origin><beforeWpJson>/?rest_route=<afterWpJson>&<original-params>
+        const fallback = new URL(parsed.origin);
+        fallback.pathname = `${beforeWpJson}/`.replace(/\/+/g, '/');
+        // Build the query string manually so `rest_route` is first and the slashes
+        // inside its value stay literal (some restrictive WAF rules see encoded
+        // slashes and block, even though WP's REST router accepts both forms).
+        const restRouteValue = afterWpJson.startsWith('/') ? afterWpJson : `/${afterWpJson}`;
+        const extraParams = [];
+        // Original query params from the URL itself.
+        parsed.searchParams.forEach((v, k) => {
+            if (k.toLowerCase() === 'rest_route')
+                return;
+            extraParams.push(`${encodeURIComponent(k)}=${encodeURIComponent(v)}`);
+        });
+        // Original axios `params` object (config.params), folded in. axios's default
+        // serializer treats `undefined`/`null` values as "skip"; mirror that here.
+        const cfgParams = config.params;
+        if (cfgParams && typeof cfgParams === 'object') {
+            for (const [k, v] of Object.entries(cfgParams)) {
+                if (v === undefined || v === null)
+                    continue;
+                if (Array.isArray(v)) {
+                    v.forEach((item) => {
+                        if (item === undefined || item === null)
+                            return;
+                        extraParams.push(`${encodeURIComponent(k)}[]=${encodeURIComponent(String(item))}`);
+                    });
+                }
+                else {
+                    extraParams.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+                }
+            }
+        }
+        const queryString = `rest_route=${restRouteValue}` + (extraParams.length ? `&${extraParams.join('&')}` : '');
+        return `${fallback.origin}${fallback.pathname}?${queryString}`;
+    }
+    /**
+     * Re-issue the original request as a `?rest_route=` call against the site
+     * root. Uses a bare `axios.request` (NOT the interceptor-wrapped client) so
+     * the request and response interceptors don't fire on the retry — we handle
+     * the retry's HTML check inline in the caller. Marks the request with
+     * `_restRouteFallback: true` for symmetry / debugging.
+     */
+    async retryViaRestRoute(originalConfig) {
+        const fallbackUrl = this.computeRestRouteFallbackUrl(originalConfig);
+        if (!fallbackUrl) {
+            throw new Error('rest_route fallback URL could not be computed');
+        }
+        const headers = { ...(originalConfig.headers || {}) };
+        // Strip axios-internal `common`/`get`/`post` per-method header buckets if any.
+        delete headers.common;
+        delete headers.get;
+        delete headers.post;
+        delete headers.put;
+        delete headers.patch;
+        delete headers.delete;
+        delete headers.head;
+        const retryConfig = {
+            method: originalConfig.method || 'get',
+            url: fallbackUrl,
+            headers,
+            data: originalConfig.data,
+            timeout: originalConfig.timeout || 30000,
+            // Force raw response body so we can sniff content-type / body for the
+            // HTML detector regardless of what axios would otherwise do.
+            transformResponse: (raw) => {
+                if (typeof raw !== 'string')
+                    return raw;
+                // Try to JSON.parse; if that fails, hand back the string so the HTML
+                // detector can run on it.
+                try {
+                    return JSON.parse(raw);
+                }
+                catch {
+                    return raw;
+                }
+            },
+            validateStatus: (s) => s >= 200 && s < 300,
+            maxRedirects: 5,
+            _restRouteFallback: true,
+        };
+        return axios.request(retryConfig);
     }
     /**
      * Set the current MCP tool name so it's sent as X-Respira-Tool-Name on
@@ -1445,6 +1710,14 @@ export class WordPressClient {
         await probe('respira_diagnostic_report', 'GET', `${baseUrl}/wp-json/respira/v1/diagnostic/report`);
         // Probe 3: a simple plugin ping (fall back gracefully if endpoint absent).
         await probe('respira_ping', 'GET', `${baseUrl}/wp-json/respira/v1/ping`);
+        // Probe 4 (v6.11.2): the `?rest_route=` form against the site root. Confirms
+        // whether the site has rewrite shadowing on `/wp-json/[anything]` (plugin
+        // or theme rewrite rule rewriting the path to `index.php` without
+        // `?rest_route=`, which causes WordPress's `redirect_canonical()` to 301
+        // the request back to the homepage). Probe length BEFORE we infer the
+        // fallback worked.
+        const restRoutePingUrl = `${baseUrl}/?rest_route=/respira/v1/ping`;
+        await probe('respira_ping_rest_route', 'GET', restRoutePingUrl);
         // 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;
@@ -1482,6 +1755,29 @@ export class WordPressClient {
         if (this.lastHtmlInsteadOfJson && !htmlInsteadOfJson) {
             recommendations.push(`Earlier in this session a Respira REST call returned HTML (status ${this.lastHtmlInsteadOfJson.status}, title '${this.lastHtmlInsteadOfJson.titleText ?? 'unknown'}'). Edge layer interception may be intermittent.`);
         }
+        // v6.11.2: derive whether the `?rest_route=` fallback would work. The
+        // pretty-permalink probes (probe 2 / probe 3) hit `/wp-json/respira/...`,
+        // and the explicit fallback probe (probe 4) hit `/?rest_route=/respira/...`.
+        // If the pretty path returned HTML and the rest_route path returned valid
+        // JSON, the site has REST rewrite shadowing — and the auto-fallback in
+        // wordpress-client.ts will work transparently.
+        const prettyPathProbe = probes.find((p) => p.label === 'respira_ping');
+        const restRouteProbe = probes.find((p) => p.label === 'respira_ping_rest_route');
+        const prettyLooksHtml = !!prettyPathProbe?.looks_like_html;
+        const restRouteIsJson = !!restRouteProbe &&
+            typeof restRouteProbe.status === 'number' &&
+            restRouteProbe.status >= 200 &&
+            restRouteProbe.status < 300 &&
+            restRouteProbe.looks_like_html === false;
+        const restRouteFallbackWorked = prettyLooksHtml && restRouteIsJson;
+        if (restRouteFallbackWorked) {
+            this.lastRestRouteFallbackWorked = true;
+            recommendations.push('Pretty `/wp-json/respira/...` path returned HTML but `?rest_route=/respira/...` returned JSON. ' +
+                'A plugin or theme rewrite rule is shadowing `/wp-json/[anything]` and triggering ' +
+                'WordPress `redirect_canonical()` (look for `x-redirect-by: WordPress` on the 301). ' +
+                '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.');
+        }
         return {
             success: true,
             site: {
@@ -1496,6 +1792,10 @@ export class WordPressClient {
             edge_hints: edgeHints,
             html_instead_of_json: htmlInsteadOfJson,
             last_html_observation: this.lastHtmlInsteadOfJson,
+            // v6.11.2: rewrite-shadowing detection + sticky-flag state.
+            rest_route_fallback_worked: restRouteFallbackWorked,
+            rest_route_fallback_active: this.useRestRouteFallback,
+            force_rest_route_configured: this.siteConfig.forceRestRoute === true,
             target_post_id: opts.post_id ?? null,
             recommendations,
         };