@wickedevolutions/abilities-mcp 1.5.3 → 1.5.4

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to Abilities MCP are documented here.
 
+## [1.5.4] - 2026-05-04
+
+This release lands the bridge-side foundations for the multisite UX promised in [#43](https://github.com/Wicked-Evolutions/abilities-mcp/issues/43). `add-site` now requests multisite OAuth scopes during DCR (so super-admin operators consent through the standard consent flow), runs a one-shot `multisite/list-sites` probe after OAuth completes, and on success writes a slug→subsite-URL `multisite` block to `wp-sites.json` so the bridge's existing dot-notation routing serves multi-site OAuth in any AI client without operator JSON editing. End-to-end dot-notation routing validated on darwin-arm64 against a 4-subsite multisite by manually populating the block from the verified `multisite/list-sites` response.
+
+Bridge-only release — no companion adapter or ai release this release.
+
+### Added
+
+- **`add-site` auto-populate: probes `multisite/list-sites` after OAuth on the freshly-authenticated bridge connection** (PR [#44](https://github.com/Wicked-Evolutions/abilities-mcp/pull/44), closes [#43](https://github.com/Wicked-Evolutions/abilities-mcp/issues/43)). Builds the slug→subsite-URL block from the response and attaches it to the new site entry before persisting `wp-sites.json`. Schema verified against the existing dot-notation routing implementation (`lib/config.js:resolveSiteKey` + `lib/connection-pool.js:_findExistingHttpTransport`) — slug→URL string map, no schema migration. Single-site / non-multisite / permission-denied / network-error all degrade gracefully, with stderr advisory naming the failure where appropriate (silent for the expected single-site case). New `lib/cli/multisite-probe.js` houses a one-shot bearer JSON-RPC client (minimal MCP handshake + `tools/call`, distinct from the runtime `OAuthHttpTransport` so the probe runs once with the freshly-minted in-memory access token without the queue/batch machinery) plus pure schema-mapping helpers (`buildMultisiteBlock`, `deriveSubsiteSlug`) covering subdomain mode, path-based mode, slug-collision disambiguation by `blog_id`, and `www.` parent stripping.
+- **`add-site` DCR scope request now includes `abilities:multisite:read` and `abilities:multisite:write`** (PR [#46](https://github.com/Wicked-Evolutions/abilities-mcp/pull/46), closes [#45](https://github.com/Wicked-Evolutions/abilities-mcp/issues/45)). The adapter's `ScopeRegistry` classifies multisite scopes as `SENSITIVE_SCOPES` and intentionally excludes them from the `abilities:read` / `abilities:write` umbrella expansion, so explicit DCR requests are the only way the consent screen surfaces them for super-admin operators on a Multisite Network root. Single source of truth in `DEFAULT_SCOPE` (`lib/auth/oauth-client.js`), picked up by `add-site` / `reauth` / `upgrade-auth` automatically. Single-site WP installs unaffected — the adapter declines to grant scopes the OAuth user lacks WP capability for, so single-site operator UX is preserved.
+
+### Changed
+
+- **Permission-denied advisory wording in `add-site` rewritten to surface BOTH possible failure causes** so operators don't chase the wrong layer: (1) the OAuth user lacks the `manage_network_options` WP capability, or (2) the OAuth token lacks the `abilities:multisite:read` scope (granted on the consent screen). Both gates can produce the same observable rejection from `multisite/list-sites`; the advisory now names both explicitly with re-run guidance.
+
+### Internal
+
+- **Test count:** `275 → 293` (+18 across PR #44 +14 and PR #46 +4). Node CI matrix unchanged: 18, 20, 22.
+- **Bundle size unchanged** (~413 kB packed / ~1.2 MB unpacked — no binary or dependency changes this release).
+- **Run-contract extension:** `lib/cli/index.js` now forwards `errLines` from successful subcommand returns so non-fatal stderr advisories can surface without changing exit semantics. Backwards-compatible — subcommands that don't set `errLines` get the previous empty-array behavior. Internal CLI surface only; the bin entrypoint already writes `errLines` to stderr (`abilities-mcp.js:62`).
+
+### Known issue (linked to adapter follow-up)
+
+- **The auto-populate's happy path does not currently fire end-to-end** due to an adapter-side bearer-auth quirk that rejects `multisite/list-sites` from the bridge's fresh-token one-shot probe — even when the OAuth user is a super admin and the token carries the required scopes. The same operation against the same tokens succeeds when invoked from an established MCP runtime session in any AI client. Tracked at [abilities-mcp-adapter#87](https://github.com/Wicked-Evolutions/abilities-mcp-adapter/issues/87) — adapter-side fix; bridge code is correct in isolation. Operators following the documented v1.5.4 flow today will hit the bridge's documented graceful-degrade path: site entry written without the `multisite` block, advisory printed, manual block edit OR an immediate `multisite/list-sites` call from any already-connected MCP client (which writes nothing — operator copies the response into `wp-sites.json`) lets dot-notation routing work end-to-end. End-to-end dot-notation routing validated on darwin-arm64 against `wickedevolutions.com` multisite (4 subsites: `main`, `community`, `knowledge`, `test1`) by manually populating the block — 106 published posts returned correctly from `wickedevolutions.community` through the bridge's existing routing.
+
 ## [1.5.3] - 2026-05-04
 
 **macOS hotfix: OAuth in Claude Desktop's `.mcpb` runtime now works.** Hotfix to v1.5.2's `.mcpb` operator UX on macOS. v1.5.2 shipped with keytar prebuilds bundled, but Claude Desktop's hardened-runtime host process on macOS rejects native modules with mismatched code-signing Team IDs — a system-level macOS protection that applies to every hardened app, not a Claude Desktop quirk. This blocked OAuth inside Claude Desktop's `.mcpb` runtime even though the bundle itself is structurally correct (loads cleanly via system Node from the extracted `.mcpb`). The hotfix adds a darwin-only shell-out to the macOS `security` CLI when keytar fails to load. Validated end-to-end on darwin-arm64 by an operator running the documented progression (install `.mcpb` → `upgrade-auth` → `add-site` → multi-site OAuth in the same Claude Desktop entry, read and write confirmed live on two production WordPress sites via OAuth bearer) before release.

package/lib/auth/oauth-client.js

@@ -46,7 +46,17 @@ const {
  * @license GPL-2.0-or-later
  */
 
-const DEFAULT_SCOPE = 'abilities:read abilities:write';
+// `abilities:multisite:read` / `abilities:multisite:write` are SENSITIVE_SCOPES
+// in the adapter's ScopeRegistry (Auth/OAuth/ScopeRegistry.php) — never implied
+// by the `abilities:read` / `abilities:write` umbrella expansion. Requesting
+// them explicitly during DCR is the only way the consent screen can surface
+// them for super-admin operators on a Multisite Network root, which in turn
+// is the only way `add-site`'s post-OAuth multisite/list-sites probe (#43)
+// can fire end-to-end. Single-site WP installs accept the request — the
+// adapter simply won't grant scopes the OAuth user lacks WP capability for,
+// so single-site UX is preserved.
+const DEFAULT_SCOPE =
+  'abilities:read abilities:write abilities:multisite:read abilities:multisite:write';
 const DEFAULT_LOOPBACK_TIMEOUT_MS = 5 * 60_000;
 
 class OAuthClient extends EventEmitter {

package/lib/cli/commands/add-site.js

@@ -12,6 +12,7 @@ const { makeRef } = require('../../auth/secret-store');
 const { CliError, EXIT_USAGE, EXIT_CONFIG, fromAuthError } = require('../errors');
 const { subscribeProgress } = require('../output');
 const { readConfig, writeConfig, freshConfig } = require('../config-store');
+const { probeMultisite: defaultProbeMultisite } = require('../multisite-probe');
 
 /**
  * `add-site <url>` — register a new site with the bridge using OAuth (default)
@@ -108,6 +109,7 @@ async function run(args, ctx) {
   }
 
   const out = [];
+  const errLines = [];
   let exitCode = 0;
 
   if (args.apppassword) {
@@ -139,7 +141,7 @@ async function run(args, ctx) {
     await writeConfig(ctx.configPath, config);
     out.push(`✓ Site "${siteId}" configured with App Password authentication.`);
     out.push(`  Config: ${ctx.configPath}`);
-    return { exitCode, lines: out };
+    return { exitCode, lines: out, errLines };
   }
 
   // OAuth path — full authorization-code + PKCE flow via OAuthClient.
@@ -199,12 +201,73 @@ async function run(args, ctx) {
   if (result.prMetadata && result.prMetadata.resource) {
     config.sites[siteId].mcp_resource = result.prMetadata.resource;
   }
+
+  // Multisite Network root probe. If the freshly authenticated bridge can
+  // resolve `multisite/list-sites`, populate the multisite block so dot-
+  // notation routing works without operator JSON editing. Single-site,
+  // permission-denied, and network errors all degrade gracefully — the
+  // site entry is still written without a multisite block.
+  const probeEndpoint = result.prMetadata && result.prMetadata.resource;
+  if (probeEndpoint && result.tokens && result.tokens.access_token) {
+    const probe = (ctx.deps && ctx.deps.probeMultisite) || defaultProbeMultisite;
+    try {
+      const probeResult = await probe({
+        endpoint: probeEndpoint,
+        accessToken: result.tokens.access_token,
+        siteUrl: parsedUrl.origin,
+        log: typeof ctx.log === 'function' ? ctx.log : null,
+        deps: ctx.deps && ctx.deps.probeMultisiteDeps,
+      });
+      if (probeResult && probeResult.block && Object.keys(probeResult.block).length > 0) {
+        config.sites[siteId].multisite = probeResult.block;
+        const slugs = Object.keys(probeResult.block).join(', ');
+        out.push(`  Multisite: discovered ${Object.keys(probeResult.block).length} subsite(s) → ${slugs}`);
+      }
+    } catch (probeErr) {
+      _appendProbeAdvisory(probeErr, siteId, errLines);
+    }
+  }
+
   if (!config.defaultSite) config.defaultSite = siteId;
   await writeConfig(ctx.configPath, config);
 
   out.push(`✓ Site "${siteId}" configured. Granted scopes: ${result.scopes.join(', ')}.`);
   out.push(`  Config: ${ctx.configPath}`);
-  return { exitCode, lines: out };
+  return { exitCode, lines: out, errLines };
+}
+
+/**
+ * Append a stderr advisory naming the multisite-probe failure so operators
+ * who expected dot-notation routing know why it isn't wired and can either
+ * fix the underlying issue or hand-add the block per existing docs.
+ *
+ * Silent for `tool_not_registered` (single-site is the expected case for
+ * the vast majority of `add-site` invocations).
+ */
+function _appendProbeAdvisory(probeErr, siteId, errLines) {
+  const code = probeErr && probeErr.code;
+  if (code === 'tool_not_registered') return;
+
+  if (code === 'permission_denied' || code === 'unauthorized') {
+    errLines.push(
+      `Multisite discovery skipped for "${siteId}": multisite/list-sites was rejected ` +
+      `by the adapter. Two possible causes — verify both before manually adding the block: ` +
+      `(1) the OAuth user lacks the manage_network_options WP capability (super-admin ` +
+      `required on a Multisite Network root), or (2) the OAuth token lacks the ` +
+      `abilities:multisite:read scope (it must be granted on the consent screen — ` +
+      `re-run add-site and confirm the multisite scope checkbox if it was unchecked). ` +
+      `Site entry written without multisite block — dot-notation subsite routing ` +
+      `will not be available until the block is added manually or add-site is re-run.`
+    );
+    return;
+  }
+
+  const detail = (probeErr && probeErr.message) || String(probeErr);
+  errLines.push(
+    `Multisite discovery failed for "${siteId}": ${detail}. ` +
+    `Site entry written without multisite block — dot-notation subsite routing ` +
+    `will not be available until the block is added manually or add-site is re-run.`
+  );
 }
 
 /**

package/lib/cli/index.js

@@ -100,7 +100,12 @@ async function runCommand(opts) {
     const lines = preLines.length
       ? preLines.concat(r.lines || [])
       : (r.lines || []);
-    return { exitCode: r.exitCode || EXIT_OK, lines, errLines: [] };
+    // Commands may return non-fatal advisories alongside a success exit
+    // code (e.g. add-site emits one when the multisite-discovery probe
+    // degrades gracefully). Surface them on stderr without changing
+    // exit semantics.
+    const errLines = Array.isArray(r.errLines) ? r.errLines : [];
+    return { exitCode: r.exitCode || EXIT_OK, lines, errLines };
   } catch (err) {
     const cliErr = err instanceof CliError ? err : fromAuthError(err);
     const errLines = renderNextAction(cliErr);

package/lib/cli/multisite-probe.js

@@ -0,0 +1,392 @@
+'use strict';
+
+const https = require('node:https');
+const http = require('node:http');
+const { URL } = require('node:url');
+
+/**
+ * Multisite Network root probe for `abilities-mcp add-site`.
+ *
+ * After OAuth completes, call `multisite/list-sites` against the freshly
+ * authenticated bridge connection. If the URL points to a Multisite Network
+ * root, build the `multisite` block (slug → subsite-URL map) the bridge's
+ * dot-notation routing already expects (see `lib/config.js:resolveSiteKey`,
+ * `lib/connection-pool.js:_findExistingHttpTransport`). If the URL is a
+ * single-site install, the OAuth user lacks `manage_network_options`, or the
+ * call fails for any other reason, the probe returns null / a structured
+ * error so `add-site` can degrade gracefully without writing the block.
+ *
+ * Schema (verified against routing read paths):
+ *   site.multisite = { [slug]: subsiteUrlString }
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const PROBE_PROTOCOL_VERSION = '2025-06-18';
+const PROBE_PER_PAGE = 100;
+const PROBE_TIMEOUT_MS = 30000;
+
+/**
+ * @typedef {object} ProbeResult
+ * @property {object|null} block      Multisite block, or null when no block
+ *                                    should be written (single-site / empty).
+ * @property {string} reason          One of: 'multisite-root', 'single-site',
+ *                                    'tool-not-registered', 'empty-list'.
+ */
+
+/**
+ * @param {object} opts
+ * @param {string} opts.endpoint      MCP resource URL (from prMetadata.resource).
+ * @param {string} opts.accessToken   Freshly minted OAuth access token.
+ * @param {string} opts.siteUrl       Parent network-root URL (parsedUrl.origin).
+ * @param {function} [opts.log]       Logger.
+ * @param {object} [opts.deps]
+ * @param {function} [opts.deps.request]  Inject for tests; replaces the inline
+ *                                        bearer JSON-RPC client. Receives the
+ *                                        full message and resolves the parsed
+ *                                        JSON-RPC response (or rejects with a
+ *                                        structured error).
+ * @returns {Promise<ProbeResult>}
+ */
+async function probeMultisite(opts) {
+  const { endpoint, accessToken, siteUrl, log } = opts;
+  const logger = typeof log === 'function' ? log : function noop() {};
+
+  if (!endpoint) {
+    const e = new Error('multisite probe: no MCP endpoint available');
+    e.code = 'no_endpoint';
+    throw e;
+  }
+  if (!accessToken) {
+    const e = new Error('multisite probe: no access token available');
+    e.code = 'no_access_token';
+    throw e;
+  }
+
+  const client = (opts.deps && opts.deps.request)
+    ? new InjectedClient(opts.deps.request)
+    : new BearerJsonRpcClient(endpoint, accessToken, logger);
+
+  await client.initialize();
+  const toolResp = await client.callTool('multisite/list-sites', { per_page: PROBE_PER_PAGE });
+  const payload = parseToolResponse(toolResp);
+  const items = extractSites(payload);
+
+  if (items === null) {
+    return { block: null, reason: 'empty-list' };
+  }
+  if (items.length === 0) {
+    return { block: null, reason: 'empty-list' };
+  }
+  if (items.length === 1) {
+    // Only the network root came back — treat as single-site for routing
+    // purposes. Operators can still call `multisite/*` abilities at the
+    // network level; dot-notation routing isn't useful with no subsites.
+    return { block: null, reason: 'single-site' };
+  }
+
+  const block = buildMultisiteBlock(siteUrl, items);
+  if (!block || Object.keys(block).length === 0) {
+    return { block: null, reason: 'empty-list' };
+  }
+  return { block, reason: 'multisite-root' };
+}
+
+/**
+ * Build the multisite block (slug → subsite URL) from a `multisite/list-sites`
+ * response. Pure function — no I/O, no logging. Exported so `add-site.js`
+ * tests can verify the schema-mapping logic in isolation.
+ */
+function buildMultisiteBlock(parentSiteUrl, items) {
+  let parentHost;
+  try { parentHost = new URL(parentSiteUrl).hostname.toLowerCase().replace(/^www\./, ''); }
+  catch { return null; }
+
+  const block = {};
+  const used = new Set();
+  for (const item of items) {
+    if (!item || typeof item.url !== 'string' || item.url.length === 0) continue;
+    const baseSlug = deriveSubsiteSlug(parentHost, item);
+    if (!baseSlug) continue;
+    const slug = uniqueSlug(baseSlug, used, item);
+    used.add(slug);
+    block[slug] = item.url;
+  }
+  return block;
+}
+
+/**
+ * Map a `multisite/list-sites` item to a slug usable for dot-notation
+ * routing. Subdomain mode → first label of the subdomain. Path mode →
+ * first segment of the path. Network root → 'main'. Mapped-domain
+ * subsites → first label of the domain.
+ */
+function deriveSubsiteSlug(parentHost, item) {
+  const itemDomain = String(item.domain || '').toLowerCase().replace(/^www\./, '');
+  const itemPath = String(item.path || '/').replace(/^\/+|\/+$/g, '');
+
+  if (itemDomain === parentHost) {
+    return itemPath === '' ? 'main' : itemPath.split('/')[0];
+  }
+  if (itemDomain.endsWith('.' + parentHost)) {
+    const prefix = itemDomain.slice(0, itemDomain.length - parentHost.length - 1);
+    const first = prefix.split('.')[0];
+    return first || null;
+  }
+  // Mapped / different domain — fall back to first label
+  const first = itemDomain.split('.')[0];
+  return first || null;
+}
+
+function uniqueSlug(base, used, item) {
+  if (!used.has(base)) return base;
+  // Disambiguate with blog_id when slugs collide (e.g. two subsites whose
+  // first path segments match). Never silently overwrite a previously
+  // mapped subsite.
+  const blogId = item && item.blog_id;
+  if (blogId !== undefined && blogId !== null) {
+    const candidate = `${base}-${blogId}`;
+    if (!used.has(candidate)) return candidate;
+  }
+  let n = 2;
+  while (used.has(`${base}-${n}`)) n += 1;
+  return `${base}-${n}`;
+}
+
+function parseToolResponse(resp) {
+  if (resp && resp.error) {
+    const e = new Error(resp.error.message || 'JSON-RPC error');
+    e.code = mapJsonRpcErrorCode(resp.error.code, resp.error.message);
+    e.jsonrpcCode = resp.error.code;
+    throw e;
+  }
+  const result = resp && resp.result;
+  if (!result) {
+    const e = new Error('multisite/list-sites: empty result');
+    e.code = 'empty_result';
+    throw e;
+  }
+  const content = Array.isArray(result.content) ? result.content : [];
+  const first = content[0];
+  let payload = null;
+  if (first && first.type === 'text' && typeof first.text === 'string') {
+    try { payload = JSON.parse(first.text); }
+    catch { payload = { _raw: first.text }; }
+  }
+
+  if (result.isError) {
+    const errMsg = (payload && (payload.error || payload._raw))
+      || (first && first.text)
+      || 'tool error';
+    const errCode = (payload && payload.error_code) || 'tool_error';
+    const e = new Error(errMsg);
+    e.code = mapAbilityErrorCode(errCode, errMsg);
+    e.abilityCode = errCode;
+    e.data = payload && payload.error_data;
+    throw e;
+  }
+
+  return payload || result;
+}
+
+function extractSites(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  if (Array.isArray(payload.sites)) return payload.sites;
+  if (payload.data && Array.isArray(payload.data.sites)) return payload.data.sites;
+  return null;
+}
+
+function mapJsonRpcErrorCode(code, message) {
+  // -32601 = Method not found → tool not registered (single-site install)
+  if (code === -32601) return 'tool_not_registered';
+  if (typeof message === 'string' && /unknown\s+tool/i.test(message)) return 'tool_not_registered';
+  return 'jsonrpc_error';
+}
+
+function mapAbilityErrorCode(abilityCode, message) {
+  const code = String(abilityCode || '').toLowerCase();
+  if (code === 'rest_forbidden_context'
+      || code === 'rest_forbidden'
+      || code === 'permission_denied'
+      || code === 'forbidden_context'
+      || code.indexOf('forbidden') !== -1) {
+    return 'permission_denied';
+  }
+  if (code === 'rest_no_route' || code === 'not_multisite') {
+    return 'tool_not_registered';
+  }
+  if (typeof message === 'string' && /manage_network_options|insufficient.*capabilit|forbidden/i.test(message)) {
+    return 'permission_denied';
+  }
+  return 'tool_error';
+}
+
+// ---------------------------------------------------------------------------
+// Bearer JSON-RPC client — minimal MCP handshake + tools/call over HTTP.
+// Distinct from OAuthHttpTransport: this runs once during add-site with a
+// fresh in-memory access token, so it skips TokenManager + queue/batch.
+// ---------------------------------------------------------------------------
+
+class BearerJsonRpcClient {
+  constructor(endpoint, accessToken, log) {
+    this.url = new URL(endpoint);
+    this.accessToken = accessToken;
+    this.log = log;
+    this.module = this.url.protocol === 'https:' ? https : http;
+    this.sessionId = null;
+    this.cookies = new Map();
+    this._idCounter = 1;
+  }
+
+  async initialize() {
+    const initResp = await this._post({
+      jsonrpc: '2.0',
+      id: this._idCounter++,
+      method: 'initialize',
+      params: {
+        protocolVersion: PROBE_PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: 'abilities-mcp-add-site', version: '1.5.4' },
+      },
+    });
+    if (initResp && initResp.error) {
+      const e = new Error(initResp.error.message || 'initialize failed');
+      e.code = 'initialize_failed';
+      e.jsonrpcCode = initResp.error.code;
+      throw e;
+    }
+    await this._post({
+      jsonrpc: '2.0',
+      method: 'notifications/initialized',
+    });
+  }
+
+  callTool(name, args) {
+    return this._post({
+      jsonrpc: '2.0',
+      id: this._idCounter++,
+      method: 'tools/call',
+      params: { name, arguments: args || {} },
+    });
+  }
+
+  _post(message) {
+    return new Promise((resolve, reject) => {
+      const body = JSON.stringify(message);
+      const headers = {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+        'Authorization': `Bearer ${this.accessToken}`,
+        'Content-Length': Buffer.byteLength(body),
+      };
+      if (this.sessionId) headers['Mcp-Session-Id'] = this.sessionId;
+      if (this.cookies.size > 0) {
+        headers['Cookie'] = Array.from(this.cookies.entries())
+          .map(([k, v]) => `${k}=${v}`).join('; ');
+      }
+
+      const req = this.module.request({
+        hostname: this.url.hostname,
+        port: this.url.port || (this.url.protocol === 'https:' ? 443 : 80),
+        path: this.url.pathname + this.url.search,
+        method: 'POST',
+        headers,
+      }, (res) => {
+        const chunks = [];
+        res.on('data', (chunk) => chunks.push(chunk));
+        res.on('end', () => {
+          const newSession = res.headers['mcp-session-id'];
+          if (newSession) this.sessionId = newSession;
+          const setCookie = res.headers['set-cookie'];
+          if (setCookie) {
+            const list = Array.isArray(setCookie) ? setCookie : [setCookie];
+            for (const raw of list) {
+              const nv = raw.split(';')[0].trim();
+              const eq = nv.indexOf('=');
+              if (eq > 0) this.cookies.set(nv.slice(0, eq), nv.slice(eq + 1));
+            }
+          }
+          if (res.statusCode === 401) {
+            const e = new Error('multisite probe: HTTP 401 (token rejected)');
+            e.code = 'unauthorized';
+            return reject(e);
+          }
+          if (res.statusCode === 403) {
+            const e = new Error('multisite probe: HTTP 403 (forbidden)');
+            e.code = 'permission_denied';
+            return reject(e);
+          }
+          const text = Buffer.concat(chunks).toString('utf8');
+          if (!text.trim()) return resolve(null);
+          let parsed;
+          try { parsed = JSON.parse(text); }
+          catch (err) {
+            const e = new Error(`multisite probe: response parse error: ${err.message}`);
+            e.code = 'parse_error';
+            return reject(e);
+          }
+          // Tolerate single-element JSON-RPC batch responses (some servers
+          // wrap a single response in an array).
+          if (Array.isArray(parsed) && parsed.length === 1) parsed = parsed[0];
+          resolve(parsed);
+        });
+      });
+
+      req.setTimeout(PROBE_TIMEOUT_MS, () => {
+        req.destroy(new Error('multisite probe: request timeout'));
+      });
+      req.on('error', (err) => {
+        const e = new Error(`multisite probe: ${err.message}`);
+        e.code = 'network_error';
+        e.cause = err;
+        reject(e);
+      });
+      req.write(body);
+      req.end();
+    });
+  }
+}
+
+/**
+ * Test injection seam — wraps a function `(message) => Promise<jsonrpcResp>`
+ * and presents the same surface (`initialize`, `callTool`) the inline client
+ * does so the probe code path is identical.
+ */
+class InjectedClient {
+  constructor(requestFn) {
+    this._request = requestFn;
+    this._idCounter = 1;
+  }
+  async initialize() {
+    const resp = await this._request({
+      jsonrpc: '2.0',
+      id: this._idCounter++,
+      method: 'initialize',
+      params: { protocolVersion: PROBE_PROTOCOL_VERSION, capabilities: {} },
+    });
+    if (resp && resp.error) {
+      const e = new Error(resp.error.message || 'initialize failed');
+      e.code = 'initialize_failed';
+      e.jsonrpcCode = resp.error.code;
+      throw e;
+    }
+    await this._request({ jsonrpc: '2.0', method: 'notifications/initialized' });
+  }
+  callTool(name, args) {
+    return this._request({
+      jsonrpc: '2.0',
+      id: this._idCounter++,
+      method: 'tools/call',
+      params: { name, arguments: args || {} },
+    });
+  }
+}
+
+module.exports = {
+  probeMultisite,
+  buildMultisiteBlock,
+  deriveSubsiteSlug,
+  parseToolResponse,
+  PROBE_PROTOCOL_VERSION,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wickedevolutions/abilities-mcp",
-  "version": "1.5.3",
+  "version": "1.5.4",
   "description": "Open-source MCP bridge connecting AI clients to WordPress through the Abilities API — multi-site routing, zero dependencies",
   "main": "abilities-mcp.js",
   "bin": {