@respira/wordpress-mcp-server 8.2.3 → 8.2.4

package/dist/server.js

@@ -18,6 +18,7 @@ import { getBricksTools, dispatchBricksTool } from './bricks-tools.js';
 import { getElementorTools, dispatchElementorTool } from './elementor-tools.js';
 import { getAcfTools, resolveAcfToolName } from './acf-tools.js';
 import { getUsageEmitter, deriveToolKind } from './usage-emitter.js';
+import { collapseLauncherProcesses, validateApiKeyShape } from './config.js';
 // Process-local secret keeps target hashes useful for same-session retry
 // detection without making low-entropy WordPress ids reversible centrally.
 const TELEMETRY_HASH_SECRET = randomUUID();
@@ -144,6 +145,35 @@ function getMaxToolTimeoutMs() {
  * possible top-level `dropped_settings` array, and a pre-summarised
  * `styling_dropped` count/string if the plugin sends one.
  */
+/**
+ * The `ability` argument for wordpress_invoke_ability, or a refusal that says
+ * how to fix the call.
+ *
+ * Validated here rather than letting `undefined` ride to the site. The POST
+ * body drops the key, WordPress answers `rest_missing_callback_param`, and the
+ * agent is told a REST parameter is missing without being told which one or
+ * what this tool calls it. Seven of those across three sites, and the recovery
+ * path from that message is guesswork.
+ *
+ * Aliases are named in the error rather than silently accepted. Quietly
+ * honouring `ability_name` would make the tool's own schema a lie, and the next
+ * agent would learn the wrong contract from a call that happened to work.
+ */
+export function requireAbilityName(args) {
+    const ability = args?.ability;
+    if (typeof ability === 'string' && ability.trim() !== '') {
+        return ability.trim();
+    }
+    const aliases = ['name', 'ability_name', 'abilityName', 'tool', 'slug'].filter((key) => typeof args?.[key] === 'string' && String(args[key]).trim() !== '');
+    const sawInstead = aliases.length
+        ? ` You sent ${aliases.map((k) => '`' + k + '`').join(' and ')} instead; rename it to \`ability\`.`
+        : '';
+    throw new Error('wordpress_invoke_ability requires `ability`, the full registered name in the form ' +
+        '"vendor/ability-name" (for example "rankmath/get-meta").' +
+        sawInstead +
+        ' Arguments for the ability go in `args`, not at the top level.' +
+        ' Call wordpress_search_abilities first if you do not know the exact name.');
+}
 function hoistDroppedStylingWarnings(result) {
     if (!result || typeof result !== 'object') {
         return result;
@@ -1019,6 +1049,18 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 message: 'The token redeemed but the account has no connected WordPress sites yet. Add a site at respira.press/dashboard/sites and try again.',
             };
         }
+        // Make the redeemed sites live in THIS session before touching the disk.
+        //
+        // This is the fix for the shape M.S. reported twice (ce28ca7e, 135558a9):
+        // redeem returns success, writes a file, and the running server carries on
+        // with exactly the site list it booted with. Under RESPIRA_CONFIG_B64 the
+        // next start ignores that file too, so the redeem is a no-op that reports
+        // success — the worst possible combination. Merging into the live map is
+        // the same in-memory path maybeSelfHealSiteList already uses, and it works
+        // identically under B64 and inside a sandbox that cannot write at all.
+        // Deliberately before the write, so a write failure still leaves a working
+        // session instead of nothing.
+        const activation = this.activateRedeemedSites(config.sites);
         // Write ~/.respira/config.json with the canonical shape. Make the
         // directory if absent. If a file already exists, back it up first
         // so the user can recover the previous config if they want.
@@ -1088,12 +1130,18 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
         }
         catch (err) {
             const attempted = process.env.RESPIRA_CONFIG_FILE?.trim() || '~/.respira/config.json';
+            const liveNow = activation.activated.length + activation.already_active.length;
             return {
                 success: false,
                 error: 'write_failed',
                 // Name the ABSOLUTE path that failed. "could not write
                 // ~/.respira/config.json" sends someone looking in the wrong home.
-                message: `Token redeemed but could not write the config to ${attempted} (${err?.message || 'unknown error'}). Download it from respira.press/dashboard/mcp and place it at that exact path.`,
+                message: `Token redeemed but could not write the config to ${attempted} (${err?.message || 'unknown error'}). ` +
+                    (liveNow > 0
+                        ? `${liveNow} site${liveNow === 1 ? ' is' : 's are'} usable in THIS session anyway, but the redeem will not survive a restart until the file exists. `
+                        : '') +
+                    'Download it from respira.press/dashboard/mcp and place it at that exact path.',
+                activated_in_session: activation.activated,
             };
         }
         // This token's own sites (what was just redeemed) vs. the merged total
@@ -1135,9 +1183,15 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             };
         }
         const hasConfigB64 = Boolean(process.env.RESPIRA_CONFIG_B64);
-        const baseMessage = `Connected ${tokenSites.length} site${tokenSites.length === 1 ? '' : 's'} via this Respira Cowork token. ${allSites.length} site${allSites.length === 1 ? '' : 's'} total now configured at ${configPath}. Restart this Cowork chat (or open a new one) so the MCP server picks up the new sites.`;
+        const liveCount = this.sites.size;
+        const activationSentence = activation.activated.length > 0
+            ? `${activation.activated.length} of them ${activation.activated.length === 1 ? 'is' : 'are'} live in this session already, no restart needed (${liveCount} site${liveCount === 1 ? '' : 's'} usable right now).`
+            : activation.failed.length > 0
+                ? `None of them could be activated in this session (${activation.failed.map((f) => `${f.url}: ${f.reason}`).join('; ')}). Restart the client after fixing that.`
+                : 'They were already connected in this session, so nothing changed here.';
+        const baseMessage = `Connected ${tokenSites.length} site${tokenSites.length === 1 ? '' : 's'} via this Respira Cowork token. ${allSites.length} site${allSites.length === 1 ? '' : 's'} total now written to ${configPath}. ${activationSentence}`;
         const message = hasConfigB64
-            ? `${baseMessage} IMPORTANT: your MCP server is currently configured via the RESPIRA_CONFIG_B64 environment variable, which takes precedence over the file on disk. To activate the new site, update RESPIRA_CONFIG_B64 in your agent's MCP server config with the base64-encoded contents of the new ~/.respira/config.json file, then restart the agent.`
+            ? `${baseMessage} Note for next time: your MCP server is configured via the RESPIRA_CONFIG_B64 environment variable, which takes precedence over the file on disk. The sites above work now, but to keep them after a restart, update RESPIRA_CONFIG_B64 in your agent's MCP server config with the base64-encoded contents of ${configPath}.`
             : baseMessage;
         return {
             success: true,
@@ -1149,9 +1203,81 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             // Proof rather than assumption: what landed on disk, and whether the
             // next start will actually read it.
             write_verification: writeVerification,
+            // Proof for the OTHER half: what this running server can use right now.
+            // A redeem that changes neither of these two is a no-op, and now says so.
+            session_activation: {
+                activated_now: activation.activated,
+                already_active: activation.already_active,
+                failed: activation.failed,
+                sites_usable_this_session: liveCount,
+            },
             message,
         };
     }
+    /**
+     * Merge freshly redeemed sites into the LIVE site map.
+     *
+     * Same mechanism as maybeSelfHealSiteList, applied at the moment of redeem
+     * instead of on the next list_sites call. Deduped by id and by normalised
+     * URL, because a stale frozen config can hold the same site under a
+     * different id than the token returns. Never throws: one malformed entry
+     * must not fail a redeem that otherwise worked.
+     */
+    activateRedeemedSites(sites) {
+        const activated = [];
+        const alreadyActive = [];
+        const failed = [];
+        const knownUrls = new Set();
+        for (const client of this.sites.values()) {
+            knownUrls.add(this.normalizeSiteUrl(client.getSiteUrl()));
+        }
+        for (const s of Array.isArray(sites) ? sites : []) {
+            if (!s || typeof s !== 'object' || !s.id || !s.url || !s.apiKey) {
+                failed.push({ url: String(s?.url || '(no url)'), reason: 'incomplete site entry (id, url or key missing)' });
+                continue;
+            }
+            const normalized = this.normalizeSiteUrl(s.url);
+            if (this.sites.has(s.id) || knownUrls.has(normalized)) {
+                alreadyActive.push({ id: String(s.id), url: String(s.url) });
+                continue;
+            }
+            try {
+                // Same gate loadConfig applies (8.1.4): a masked key must fail here,
+                // loudly, not become a live site that 401s on its first tool call.
+                validateApiKeyShape(String(s.apiKey), `redeemed site "${s.id}"`);
+                const client = new WordPressClient({
+                    id: s.id,
+                    url: s.url,
+                    apiKey: s.apiKey,
+                    name: s.name || s.id,
+                    default: false,
+                });
+                this.sites.set(s.id, client);
+                knownUrls.add(normalized);
+                if (!this.currentSite) {
+                    this.currentSite = client;
+                    this.defaultSiteId = s.id;
+                }
+                try {
+                    getUsageEmitter().registerSiteToken(s.url, s.apiKey, () => client.getTelemetryToken());
+                }
+                catch {
+                    // usage telemetry never blocks a redeem
+                }
+                activated.push({ id: String(s.id), url: String(s.url) });
+            }
+            catch (err) {
+                failed.push({ url: String(s.url), reason: String(err?.message || err) });
+            }
+        }
+        if (activated.length > 0) {
+            // The tool catalog is filtered per site; a new site can change it.
+            this.cachedFilterContext = null;
+            console.error(`respira-mcp: redeem activated ${activated.length} site${activated.length === 1 ? '' : 's'} in the running session ` +
+                `(now ${this.sites.size} connected).`);
+        }
+        return { activated, already_active: alreadyActive, failed };
+    }
     /**
      * Self-heal the in-memory site list from respira.press.
      *
@@ -3155,7 +3281,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_diagnose_connection',
-                description: 'Run a connection-fingerprint diagnostic for the active site. Combines the plugin\'s server-side report (route registration, php/wp/plugin versions, edge plugin presence) with outside-in probes from the MCP server (REST root reachability, content-type sanity check on Respira routes, edge-layer headers). Use when a tool returns "html instead of json", an opaque 5xx, or when a connection that worked yesterday silently breaks. Returns a structured object including detected edge layers (Cloudflare, Wordfence, Sucuri) and concrete remediation recommendations.',
+                description: 'Run a connection-fingerprint diagnostic for the active site. Combines the plugin\'s server-side report (route registration, php/wp/plugin versions, edge plugin presence) with outside-in probes from the MCP server (REST root reachability, content-type sanity check on Respira routes, edge-layer headers). Use when a tool returns "html instead of json", an opaque 5xx, or when a connection that worked yesterday silently breaks. ALSO use it when the user suspects the wrong site, a stale connection, or a setup step that "did nothing": the response carries transport_mode (which install is answering: mcpb_bundle, npx_cache, global_npm_install, project_local_install, source_checkout), transport.duplicate_entries (whether a second Respira server is running, which usually means the client config lists Respira twice), and client_config (which config source won and how many sites came out of it). Returns a structured object including detected edge layers (Cloudflare, Wordfence, Sucuri) and concrete remediation recommendations.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -5934,7 +6060,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         dry_run: { type: 'boolean' },
                         edit_target: {
                             type: 'string',
-                            enum: ['live', 'duplicate'],
+                            enum: ['approval', 'live'],
                             description: 'Set "live" to write the template directly instead of creating an approval proposal. Requires respira_allow_direct_edit on the site; without that option the call is refused rather than silently downgraded. Omit to keep the default proposal flow.',
                         },
                         verification_marker: {
@@ -5958,7 +6084,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         dry_run: { type: 'boolean' },
                         edit_target: {
                             type: 'string',
-                            enum: ['live', 'duplicate'],
+                            enum: ['approval', 'live'],
                             description: 'Set "live" to write the template directly instead of creating an approval proposal. Requires respira_allow_direct_edit on the site; without that option the call is refused rather than silently downgraded. Omit to keep the default proposal flow.',
                         },
                         verification_marker: {
@@ -5978,7 +6104,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         dry_run: { type: 'boolean' },
                         edit_target: {
                             type: 'string',
-                            enum: ['live', 'duplicate'],
+                            enum: ['approval', 'live'],
                             description: 'Set "live" to write the template directly instead of creating an approval proposal. Requires respira_allow_direct_edit on the site; without that option the call is refused rather than silently downgraded. Omit to keep the default proposal flow.',
                         },
                         verification_marker: {
@@ -6008,7 +6134,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         dry_run: { type: 'boolean' },
                         edit_target: {
                             type: 'string',
-                            enum: ['live', 'duplicate'],
+                            enum: ['approval', 'live'],
                             description: 'Set "live" to write the template directly instead of creating an approval proposal. Requires respira_allow_direct_edit on the site; without that option the call is refused rather than silently downgraded. Omit to keep the default proposal flow.',
                         },
                         verification_marker: {
@@ -6998,7 +7124,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             case 'wordpress_search_abilities':
                 return await client.searchAbilities(args);
             case 'wordpress_invoke_ability':
-                return await client.invokeInhaledAbility(args?.ability, args?.args || {});
+                return await client.invokeInhaledAbility(requireAbilityName(args), args?.args || {});
             case 'wordpress_list_pages':
                 return await client.listPages(args);
             case 'wordpress_read_page':
@@ -7212,7 +7338,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             }
             case 'wordpress_diagnose_connection': {
                 const siteDiag = await client.diagnoseConnection({ post_id: args.post_id, probe_timeout_ms: args.probe_timeout_ms });
-                const { describeEffectiveConfig } = await import('./config.js');
+                const { describeEffectiveConfig, describeTransportMode } = await import('./config.js');
                 // v6.17.2: append process-level runtime info so version drift,
                 // orphan processes, and a stale RESPIRA_SITES filter become
                 // visible from a single tool call rather than requiring shell
@@ -7220,14 +7346,34 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 // processes flapping the tool catalog because npm exec ignored
                 // the @latest pin and bound to a homebrew v6.14.2 install).
                 const binaryPath = process.argv[1] || '<unknown>';
+                const siblingScan = findSiblingServerProcesses();
+                // Which INSTALL is answering, and whether a second one is running.
+                //
+                // client_config below says which configuration won. This says which
+                // binary won. Desmond installed the .mcpb bundle while an older npx
+                // entry stayed in his client config; both were valid Respira servers,
+                // the client picked one, and nothing said which. See
+                // describeTransportMode and describeDuplicateEntries in config.ts for
+                // exactly what is and is not knowable from inside the server.
+                const transport = describeTransportMode({
+                    binaryPath,
+                    siblings: siblingScan.siblings,
+                    processScanWorked: siblingScan.scanned,
+                });
                 return {
                     ...siteDiag,
+                    // Promoted to the top level because it is the field support asks for
+                    // first: 'mcpb_bundle' | 'npx_cache' | 'global_npm_install' |
+                    // 'project_local_install' | 'source_checkout' | 'unknown'.
+                    transport_mode: transport.transport_mode,
+                    transport,
                     runtime: {
                         version: MCP_SERVER_VERSION,
                         pid: process.pid,
                         binary_path: binaryPath,
-                        is_global_install: /\/opt\/homebrew\/|\/usr\/local\//.test(binaryPath),
-                        sibling_pids: findSiblingProcesses(),
+                        launch_mode: transport.transport_mode,
+                        is_global_install: transport.is_global_install,
+                        sibling_pids: collapseLauncherProcesses(process.pid, process.ppid, siblingScan.siblings).map((s) => s.pid),
                         uptime_seconds: Math.round(process.uptime()),
                         node_version: process.version,
                     },
@@ -8771,24 +8917,72 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
     }
 }
 /**
- * v6.17.2: detect orphan wordpress-mcp-server processes from prior
- * supervisor reconnect cycles. Pure function — does not log. Used by
- * the boot warning and by respira_diagnose_connection so diagnose
- * doesn't re-emit a stderr warning on every call.
+ * Command lines that belong to a Respira MCP server.
+ *
+ * The first two alternatives are the npm binaries. The third is the desktop
+ * bundle, which the old filter missed: the .mcpb wrapper launches
+ * `node .../Claude Extensions/<id>/server/index.js` and imports the package
+ * in-process, so the string 'wordpress-mcp-server' never appears on its
+ * command line. That blind spot is why a bundle running alongside an npx
+ * entry — Desmond's case — showed up as zero siblings.
  */
-function findSiblingProcesses() {
+function isRespiraMcpProcess(command) {
+    if (/wordpress-mcp-server|respira-wordpress-mcp/i.test(command))
+        return true;
+    // The bundle: a Respira-named extension directory running server/index.js.
+    // Both halves are required so another vendor's desktop extension, which also
+    // ends in server/index.js, is never counted as a second Respira server.
+    return /respira/i.test(command) && /[/\\]server[/\\]index\.js/.test(command);
+}
+/**
+ * v6.17.2: detect other Respira MCP server processes — orphans from prior
+ * supervisor reconnect cycles, or a second install the client also started.
+ * Pure function — does not log. Used by the boot warning and by
+ * respira_diagnose_connection so diagnose doesn't re-emit a stderr warning
+ * on every call.
+ *
+ * Filtering happens in JS rather than in awk so the caller can also see each
+ * sibling's command line and classify how it was launched.
+ */
+function findSiblingServerProcesses() {
     try {
-        // ps -eo lists every process; awk filters to ones that contain
-        // 'wordpress-mcp-server' in their command and aren't our own PID.
-        const psOutput = execSync(`ps -eo pid,command 2>/dev/null | awk -v me=${process.pid} '$0 ~ /wordpress-mcp-server/ && $0 !~ /awk/ && $1 != me { print $1 }'`, { encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-        return psOutput
-            ? psOutput.split('\n').map((s) => parseInt(s.trim(), 10)).filter((n) => !Number.isNaN(n))
-            : [];
+        // ppid is what lets collapseLauncherProcesses tell one npx entry's
+        // three-process launcher chain apart from three separate servers.
+        const psOutput = execSync('ps -eo pid=,ppid=,command= 2>/dev/null', {
+            encoding: 'utf8',
+            timeout: 2000,
+            maxBuffer: 8 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const siblings = [];
+        for (const line of psOutput.split('\n')) {
+            const match = line.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/);
+            if (!match)
+                continue;
+            const pid = Number.parseInt(match[1], 10);
+            const ppid = Number.parseInt(match[2], 10);
+            const command = match[3];
+            if (Number.isNaN(pid) || pid === process.pid)
+                continue;
+            if (!isRespiraMcpProcess(command))
+                continue;
+            siblings.push({ pid, ppid, command });
+        }
+        return { scanned: true, siblings };
     }
     catch {
-        return [];
+        return { scanned: false, siblings: [] };
     }
 }
+/**
+ * Leaf server processes only. The launcher chain above an npx run belongs to
+ * the same logical server, so counting it would make the boot warning fire on
+ * every healthy npx install.
+ */
+function findSiblingProcesses() {
+    const { siblings } = findSiblingServerProcesses();
+    return collapseLauncherProcesses(process.pid, process.ppid, siblings).map((s) => s.pid);
+}
 /**
  * v6.17.2: emit a one-shot stderr warning at boot if any sibling
  * wordpress-mcp-server processes are running. We can't kill them