@wickedevolutions/abilities-mcp 1.6.1 → 1.6.3

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to Abilities MCP are documented here.
 
+## [1.6.3] - 2026-05-12
+
+### Fixed
+
+- **Sanitizer normalizes array-shaped `inputSchema.properties` (Issue [#83](https://github.com/Wicked-Evolutions/abilities-mcp/issues/83), Sprint C 2026-05-11).** Extends `validateToolSchema` in `lib/sanitizer.js` so that when a tool's `inputSchema.properties` is an array (PHP `'properties' => array()` JSON-encodes to `[]`), `null`, a string, or any other non-plain-object value, it is normalized to `{}` before client emission. The previous v1.6.2 fix (#78/#79) normalized broken top-level `inputSchema` but left malformed nested `properties` untouched — the value passed `typeof === 'object'` (arrays are objects in JS) and reached the `Object.entries()` loop unchanged. Anthropic's draft 2020-12 validator rejects the entire `tools/list` payload on the first invalid schema (`/properties must be object`), so a single vendor-registered `properties: []` shape breaks the whole catalog. Defends against the entire class of vendor-registered ability schema slips that share the `properties: []` shape; SureCart's `surecart/get-store-info` was the trigger case (live capture from helenawillow.com 2026-05-11, 1 of 789 tools failing) but the fix is name-agnostic. Boundary discipline binding: `inputSchema: { type: "object" }` shapes that omit the `properties` key entirely remain byte-unchanged (early-return on `schema.properties === undefined` before the malformed-shape normalize). Already-valid object-shaped `properties` pass through byte-identical (regression-guarded with reference-equality assertion in `test/sanitizer.test.js`).
+
+- **Bridge orientation: `mcp-adapter-*` reliably visible as the cross-site discovery path when filtering is enabled; `wp_browse_tools` / `wp_load_tools` describe themselves honestly (Issue [#85](https://github.com/Wicked-Evolutions/abilities-mcp/issues/85), Sprint C-follow-up 2026-05-12).** Surfaced during v1.6.3 release validation: AI clients were orienting around the bridge-local meta-tools first, treating their default-site catalog as the full ability surface and missing abilities registered only on non-default sites (e.g., `surecart/get-store-info` on helenawillow when `defaultSite=wickedevolutions`). The cross-site execution path via `mcp-adapter-discover-abilities` / `mcp-adapter-get-ability-info` / `mcp-adapter-execute-ability` already worked correctly — it just wasn't the path clients reached for. Three minimal changes restore orientation without changing architecture: (1) `lib/tool-catalog.js` — when `toolFilter.enabled === true` and the operator has not set their own `alwaysIncludeCategories`, default to `['mcp-adapter']` so the five `mcp-adapter-*` tools are always callable without a prior `wp_load_tools` step. Explicit operator override (including `[]`) is honored — guarded against the `[] || ['mcp-adapter']` truthy-array pitfall with an explicit `undefined`/`null` check. (2) `lib/bridge-tools.js` — `wp_browse_tools` and `wp_load_tools` descriptions now explicitly state they operate on the direct-tool catalog scoped to the default site, not full cross-site ability discovery. (3) `lib/router.js` — `wp_browse_tools` response leads with a `Scope:` line; `wp_load_tools` computes which requested categories are missing from the catalog and returns a structured pointer ("Not in the direct-tool catalog (scoped to defaultSite `<site>`): `<category>`. To call abilities in this category on another site, use `mcp-adapter-discover-abilities` with `{site, category}` then `mcp-adapter-execute-ability` with `{site, ability_name, parameters}`") instead of the prior silent "No changes — categories may already be active" zero-activation. No union-catalog architecture introduced; no `defaultSite`-switching workaround required; adapter unchanged. Acceptance pin: with `defaultSite = wickedevolutions` and `toolFilter.enabled = true`, a fresh session can discover and execute `surecart/get-store-info` on `helenawillow` through the adapter meta-tool path without changing `defaultSite` (empirically verified, MD5-pinned behavior-reversal cycle, 415/415 tests passing).
+
+### Compatibility & operator notes
+
+- **No protocol semantics change** for valid schemas. Healthy operators see no behavioral difference. The fix activates only on the malformed-`properties` shape it closes.
+- **No operator action required** — passive defensive normalization on next bridge restart.
+- **Coordinated release wave** — held for joint release with abilities-mcp-adapter v1.4.8 per the cross-sprint coupling decision.
+
+## [1.6.2] - 2026-05-10
+
+Schema validity polish + boot fragility MVP + multisite topology gate. Four Bridge fixes ship together as a bundled release closing the operator-side schema-400 + the silent-bridge-death-on-expired-refresh-token (both connect-time and request-time refresh boundaries) + the misplaced-multisite-block-cross-product issues.
+
+### Fixed
+
+- **Sanitizer defensively normalizes broken `inputSchema` (Issue [#78](https://github.com/Wicked-Evolutions/abilities-mcp/issues/78)).** `sanitizeToolsList` in `lib/sanitizer.js` now coerces non-object `inputSchema` values (`[]` / `null` / `undefined` / primitives) to `{ type: 'object' }` before forwarding `tools/list` responses. The previous behavior detected non-object schemas via a warn-only log path but forwarded the broken schema unchanged, allowing the Anthropic API to reject the entire request with `400 tools.N.custom.input_schema: JSON schema is invalid. It must match JSON Schema draft 2020-12`. Companion source-of-truth fix in [abilities-for-fluent-plugins#41](https://github.com/Wicked-Evolutions/abilities-for-fluent-plugins/issues/41) (v1.1.3); shipping both as defense-in-depth — either fix alone closes the operator-side 400, the bridge-side normalization absorbs any future upstream registry bug regardless of source plugin. Valid object `inputSchema` values pass through byte-identical (regression-guarded with reference-equality assertion in `test/sanitizer.test.js`).
+
+- **Per-site auth-init isolation prevents silent bridge death on expired refresh token — connect-time AND request-time boundaries (Issue [#76](https://github.com/Wicked-Evolutions/abilities-mcp/issues/76), Schema Validity Polish Sprint Phase B Wave 2 + Wave 2.5).** Pre-1.6.2, the bridge's `pool.connectDefault()` exited the entire process via `process.exit(1)` when the default site's refresh token was expired (or any other auth-init failure on the default site). MCP clients saw EOF on bridge stdout, the JSON-RPC SDK reported the `initialize` response missing required fields (`protocolVersion` / `capabilities` / `serverInfo`), and the runtime became unreachable with no actionable error message — operators had to recover manually via `abilities-mcp reauth <site>` or direct `wp-sites.json` edit. v1.6.2 fixes this at TWO refresh boundaries:
+  - **Connect-time boundary (Wave 2 / PR #81):** per-site try/catch isolation now lives at the auth-init boundary in `lib/connection-pool.js`; one site's expired refresh token (or any per-site connect failure) no longer propagates to bridge-wide exit. Healthy sites' tools remain fully usable. Degraded sites are surfaced through three channels: (i) `tools/list` annotations on the bridge-only `wp_bridge_health` tool, (ii) per-call errors when an operator attempts a tool against a degraded site, (iii) the dedicated `wp_bridge_health` tools/call shape for explicit per-site health querying. The `process.exit(1)` paths in `abilities-mcp.js` bootstrap now fire only on bridge-level bugs (e.g., schema migration failure), never on per-site auth state.
+  - **Request-time boundary (Wave 2.5 / PR #82):** when `transport.connect()` succeeds (transport object created without validating tokens) but the cached `initialize` request gets forwarded and triggers a lazy `refresh()` on first use that fails, the OAuth error was previously wrapped in `CallToolResult` shape (`content[]` + `isError: true`) per the OAuth-error-handling convention — invalid response shape for an `initialize` request, SDK rejects, bridge appears unreachable. `lib/router.js` `handleTransportMessage` now intercepts error responses whose `id` matches the cached `initialize` request, synthesizes a valid `InitializeResult` with all three required fields, and enters degraded mode (reusing the same `enterDegradedMode` plumbing introduced by Wave 2). Live-verified against the operator's actual reproduction shape; pre-fix control output is byte-equivalent to the operator's captured failure. Both connect-time AND request-time refresh failures now produce valid `InitializeResult` responses.
+  - Healthy-site-only boot path is byte-equivalent to pre-fix (regression-guarded with explicit "all-healthy still boots correctly" tests). Together these two fixes close the silent-bridge-death failure mode for the most common operator state — multi-site setup with one site's refresh token aged out, regardless of which OAuth-refresh boundary the failure surfaces at.
+
+- **Multisite probe gates `add-site` block writes on detected-network-root (Issue [#77](https://github.com/Wicked-Evolutions/abilities-mcp/issues/77), Schema Validity Polish Sprint Phase B Wave 2 — gate side).** Pre-1.6.2, `add-site` against a subsite URL ran an unconditional post-OAuth `multisite/list-sites` probe and wrote a multisite block on the subsite's wp-sites.json entry (regardless of whether the URL was a network root or a subsite). For multi-subsite operators who ran `add-site` on each of N subsites independently, this produced N misplaced multisite blocks generating N×N dot-notation cross-products at the MCP tool surface (e.g., a 4-blog network seen via 4 subsite-rooted blocks produces 16 dot-notation site aliases instead of the correct 4 routes from the network root). `lib/cli/multisite-probe.js` now gates `buildMultisiteBlock()` write on detected-network-root verification; subsite URLs skip the block write and emit an operator message redirecting to the network-root URL. Future `add-site` invocations on subsite URLs no longer re-introduce the cross-product noise.
+
+- **Boot-time auto-migration cleans existing misplaced multisite blocks (Issue [#77](https://github.com/Wicked-Evolutions/abilities-mcp/issues/77) — migrate side).** Operators upgrading from pre-1.6.2 with existing wrong wp-sites.json state get auto-recovery on next bridge boot — no manual `abilities-mcp reauth` or wp-sites.json edit required. `migrateMisplacedMultisiteBlocks` in `lib/config.js` runs as part of `loadConfig` on every bridge startup (idempotent — second boot finds nothing to migrate). The migration scans persisted multisite blocks and drops subsite-entry blocks **only** when the network root for that domain is also configured; if the network root is absent, the subsite-entry block is left intact (operators may need it for dot-notation routing until they add the network-root URL via `add-site`). Operators who had been seeing N×N dot-notation cross-products (e.g. 15 sites for a 4-subsite multisite + 2 standalone sites) see clean enumeration after upgrade (e.g. 6 sites total — 4 distinct subsites + 2 standalone). Tests cover three migration paths: subsite-skip-on-add, migration-with-network-root-present (drops the misplaced block), migration-with-network-root-absent (no-op preserves block). Live-verified against operator wp-sites.json on first invocation of v1.6.2 npm-linked bridge: three subsite-rooted multisite blocks dropped (wicked-community, wicked-test1, wicked-knowledge); operator-visible diagnostic output emitted; site enumeration dropped from 15 to 6.
+
+### Compatibility & operator notes
+
+- **All four Bridge fixes ship together** as a single coordinated release per the Schema Validity Polish Sprint v2.2 marketing-launch coupling. Marketing-launch authorization (per the sprint plan) is gated on three smoke checks against an operator-approved test target: (i) Fluent-scoped reconnect produces no 400, (ii) bridge boots and serves valid InitializeResult when ≥1 configured site has expired refresh token (BOTH connect-time AND request-time refresh boundaries verified), (iii) multi-subsite multisite operator sees clean enumeration after upgrade.
+- **No protocol semantics change** for any of the four fixes. Healthy operators on single-site or correctly-configured network-root multisite see no behavioral difference. The fixes activate only on the failure modes they close.
+- **No operator action required** — schema-validity defense (#78), boot-fragility recovery at both refresh boundaries (#76), and multisite-block migration (#77) are all passive on next bridge restart.
+
+### Out of scope (deferred)
+
+- Bridge Boot Fragility research draft surfaces other than #76 + #77 — auth lifecycle redesign (Surface 1 beyond per-site try/catch isolation + request-time refresh-error interception), multi-client coordination races (Surface 3), broader multisite probe architecture (Surface 4 fix-shape-#4), test coverage gap remediation (Surface 5), broader operator-state migrations (Surface 6 beyond multisite-block migration), README troubleshooting section (Surface 7) — deferred to a future sprint.
+
+Closes [#76](https://github.com/Wicked-Evolutions/abilities-mcp/issues/76). Closes [#77](https://github.com/Wicked-Evolutions/abilities-mcp/issues/77). Closes [#78](https://github.com/Wicked-Evolutions/abilities-mcp/issues/78).
+
 ## [1.6.1] - 2026-05-08
 
 Documentation update — README rewrite for OAuth-from-`.mcpb` recommended path + post-v1.5.0/v1.6.0 surface coverage. Code unchanged from v1.6.0.

package/abilities-mcp.js

@@ -212,15 +212,42 @@ if (!isSubcommandInvocation) {
     // Startup — connect to default site
     // -----------------------------------------------------------------------
 
+    // Issue #76: per-site auth-init isolation. `pool.connectDefault` tries the
+    // configured default first and falls back to other configured sites on a
+    // per-site failure (typically RefreshError when refresh tokens expire).
+    // Returns the connected transport, or null when ALL sites failed — in
+    // that case the bridge enters degraded mode (router synthesizes a valid
+    // InitializeResult locally, returns bridge tools only on tools/list, and
+    // surfaces per-call errors on non-bridge tools/call) instead of dying
+    // with the malformed-InitializeResult / EOF symptom that motivated #76.
     try {
       const transport = await pool.connectDefault((parsedMsg, rawLine) => {
         router.handleTransportMessage(parsedMsg, rawLine);
       });
-      router.setDefaultTransport(transport);
-      log(`Default transport connected: ${config.defaultSite}`);
+      if (transport) {
+        router.setDefaultTransport(transport);
+        log(`Default transport connected: ${config.defaultSite}`);
+      } else {
+        const degradedSites = Object.entries(config.sites).map(([siteId, site]) => ({
+          siteId,
+          reason: (site && site._degraded_reason) || 'connect failed',
+        }));
+        process.stderr.write(
+          `abilities-mcp: all configured sites failed to connect at boot — ` +
+          `entering degraded mode. Operators can call wp_bridge_health to see ` +
+          `per-site status; reauth a site to recover.\n`
+        );
+        for (const ds of degradedSites) {
+          process.stderr.write(`  - ${ds.siteId}: ${ds.reason}\n`);
+        }
+        router.enterDegradedMode(degradedSites);
+      }
       router.drainEarlyQueue();
     } catch (err) {
-      process.stderr.write(`abilities-mcp: Failed to connect to default site: ${err.message}\n`);
+      // Reached only on non-per-site errors (bug in connectDefault itself,
+      // or a thrown synchronous error during bootstrap). Per-site failures
+      // are handled inside connectDefault and never surface here.
+      process.stderr.write(`abilities-mcp: bootstrap failed unexpectedly: ${err.message}\n`);
       process.exit(1);
     }
 

package/lib/bridge-tools.js

@@ -23,7 +23,8 @@ const BRIDGE_TOOLS = [
   },
   {
     name: 'wp_browse_tools',
-    description: 'List available WordPress tool categories with tool counts. Shows which categories are currently loaded. Use wp_load_tools to activate categories.',
+    description:
+      'List categories in the bridge\'s direct-tool catalog (scoped to defaultSite) with tool counts and load-state. This is the local-catalog control surface — not full cross-site ability discovery. For abilities on another site, or in a category not listed here, use mcp-adapter-discover-abilities / mcp-adapter-execute-ability with { site }.',
     inputSchema: {
       type: 'object',
       properties: {},
@@ -31,14 +32,16 @@ const BRIDGE_TOOLS = [
   },
   {
     name: 'wp_load_tools',
-    description: 'Activate WordPress tool categories to make their tools available. After loading, the tools list is automatically refreshed.',
+    description:
+      'Activate categories in the bridge\'s direct-tool catalog (scoped to defaultSite) to expose their tools in tools/list. This is the local-catalog control surface — not full cross-site ability discovery. If a requested category is not in the local catalog, the response points to mcp-adapter-discover-abilities + mcp-adapter-execute-ability for the cross-site path.',
     inputSchema: {
       type: 'object',
       properties: {
         categories: {
           type: 'array',
           items: { type: 'string' },
-          description: 'Category names to activate (e.g. ["fluent-crm", "content", "media"]). Use wp_browse_tools to see available categories.',
+          description:
+            'Category names to activate from the direct-tool catalog (e.g. ["fluent-crm", "content", "media"]). Use wp_browse_tools to see available categories. Categories not in the local catalog return a pointer to mcp-adapter-discover-abilities instead of silently activating nothing.',
         },
         deactivate: {
           type: 'array',

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

@@ -222,6 +222,23 @@ async function run(args, ctx) {
         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}`);
+      } else if (probeResult && probeResult.reason === 'subsite-not-root') {
+        // Issue #77: the operator's URL is a subsite of a multisite network,
+        // not the network root. Writing a multisite block from the subsite's
+        // perspective produces parallel cross-product blocks at the MCP tool
+        // surface — so we skip the block write and redirect the operator to
+        // the network-root URL where dot-notation routing belongs.
+        const rootUrl = probeResult.networkRootUrl;
+        const redirect = rootUrl
+          ? `Run: abilities-mcp add-site ${rootUrl}`
+          : 'Re-run add-site with the network-root URL.';
+        errLines.push(
+          `Multisite block not written for "${siteId}": this URL is a subsite, not the ` +
+          `network root${rootUrl ? ` (${rootUrl})` : ''}. Dot-notation routing belongs on ` +
+          `the network-root entry; subsite-rooted blocks describe the network from one ` +
+          `subsite's perspective and surface N×(N-1) cross-products at the MCP tool ` +
+          `surface. Site entry written without multisite block. ${redirect}`
+        );
       }
     } catch (probeErr) {
       _appendProbeAdvisory(probeErr, siteId, errLines);

package/lib/cli/multisite-probe.js

@@ -34,9 +34,14 @@ const PROBE_PAGE_CAP = 50;
 /**
  * @typedef {object} ProbeResult
  * @property {object|null} block      Multisite block, or null when no block
- *                                    should be written (single-site / empty).
+ *                                    should be written (single-site / empty /
+ *                                    subsite-not-root).
  * @property {string} reason          One of: 'multisite-root', 'single-site',
- *                                    'tool-not-registered', 'empty-list'.
+ *                                    'tool-not-registered', 'empty-list',
+ *                                    'subsite-not-root'.
+ * @property {string} [networkRootUrl] Set when reason === 'subsite-not-root'
+ *                                    so callers can emit an operator message
+ *                                    redirecting to the network-root URL.
  */
 
 /**
@@ -144,6 +149,21 @@ async function probeMultisite(opts) {
     return { block: null, reason: 'single-site' };
   }
 
+  // Issue #77: gate block write on detected-network-root.
+  // Without this gate, OAuth super-admin invocations from a subsite URL get
+  // the full network's site list back from multisite/list-sites and write a
+  // subsite-rooted block that describes the network from the subsite's
+  // perspective — surfacing N×(N-1) dot-notation cross-products at the MCP
+  // tool surface (one parallel block per subsite entry).
+  const rootCheck = detectNetworkRoot(siteUrl, items);
+  if (!rootCheck.isRoot) {
+    return {
+      block: null,
+      reason: 'subsite-not-root',
+      networkRootUrl: rootCheck.networkRootUrl,
+    };
+  }
+
   const block = buildMultisiteBlock(siteUrl, items);
   if (!block || Object.keys(block).length === 0) {
     return { block: null, reason: 'empty-list' };
@@ -151,6 +171,55 @@ async function probeMultisite(opts) {
   return { block, reason: 'multisite-root' };
 }
 
+/**
+ * Detect whether `parentSiteUrl` points at the network root of the multisite
+ * list returned by `multisite/list-sites`. Pure function — no I/O.
+ *
+ * Primary signal: the canonical WordPress network-root marker `blog_id === 1`.
+ * When that item exists, parent IS the root iff its URL origin matches.
+ *
+ * Fallback (no blog_id metadata): parent IS the root iff any item's URL
+ * origin matches `parentSiteUrl`. This is conservative — it accepts the
+ * pre-#77 behavior whenever we can't positively identify a non-root
+ * invocation, so an exotic adapter that omits `blog_id` doesn't lose probe
+ * functionality. The new gate fires only when we have positive evidence
+ * (blog_id===1 present and pointing elsewhere, or no URL match at all).
+ *
+ * @param {string} parentSiteUrl
+ * @param {Array<object>} items
+ * @returns {{ isRoot: boolean, networkRootUrl: string|null }}
+ */
+function detectNetworkRoot(parentSiteUrl, items) {
+  let parentOrigin;
+  try { parentOrigin = new URL(parentSiteUrl).origin.toLowerCase(); }
+  catch { return { isRoot: false, networkRootUrl: null }; }
+
+  const rootItem = (items || []).find((it) => it && it.blog_id === 1);
+  if (rootItem && typeof rootItem.url === 'string' && rootItem.url.length > 0) {
+    let rootOrigin;
+    try { rootOrigin = new URL(rootItem.url).origin.toLowerCase(); }
+    catch { return { isRoot: false, networkRootUrl: rootItem.url }; }
+    return {
+      isRoot: rootOrigin === parentOrigin,
+      networkRootUrl: rootItem.url,
+    };
+  }
+
+  // No blog_id metadata — fall back to URL match. Accept the parent as root
+  // when any item's URL origin matches; otherwise this is a subsite invocation
+  // whose root is unknown to us (return isRoot: false, networkRootUrl: null).
+  for (const it of (items || [])) {
+    if (!it || typeof it.url !== 'string' || it.url.length === 0) continue;
+    let itOrigin;
+    try { itOrigin = new URL(it.url).origin.toLowerCase(); }
+    catch { continue; }
+    if (itOrigin === parentOrigin) {
+      return { isRoot: true, networkRootUrl: it.url };
+    }
+  }
+  return { isRoot: false, networkRootUrl: null };
+}
+
 /**
  * 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`
@@ -485,6 +554,7 @@ class InjectedClient {
 module.exports = {
   probeMultisite,
   buildMultisiteBlock,
+  detectNetworkRoot,
   deriveSubsiteSlug,
   parseToolResponse,
   // Exported for direct testing of the per-session HMAC echo contract

package/lib/config.js

@@ -228,6 +228,16 @@ async function loadConfigFile(filePath, source = 'explicit-config') {
     await validateSiteConfig(key, site);
   }
 
+  // Issue #77: bridge-boot migration — drop subsite-rooted multisite blocks
+  // when the network-root URL is also configured. Operator-visible advisory
+  // is emitted to stderr so the change is auditable; the file on disk is left
+  // alone so operators can choose to remove or re-add the network-root entry
+  // without losing the original subsite block. See migrateMisplacedMultisiteBlocks.
+  const migrationMessages = migrateMisplacedMultisiteBlocks(config);
+  for (const msg of migrationMessages) {
+    process.stderr.write(`abilities-mcp: ${msg}\n`);
+  }
+
   config._isMultiSite = Object.keys(config.sites).length > 1 ||
     Object.values(config.sites).some(s => s.multisite);
   config._configPath = filePath;
@@ -237,6 +247,88 @@ async function loadConfigFile(filePath, source = 'explicit-config') {
   return config;
 }
 
+/**
+ * Issue #77 migration. Scan persisted multisite blocks; drop those that were
+ * written from a subsite's perspective when the network-root URL is also a
+ * configured site. Pure function — mutates `config.sites[*].multisite` in
+ * place and returns a list of operator-visible advisory messages. The on-disk
+ * file is NOT rewritten; the migration runs every boot (idempotent — second
+ * boot finds nothing to drop) so operators who later remove the network-root
+ * entry get the original subsite-rooted block back as fallback routing.
+ *
+ * Detection: a multisite block is "subsite-rooted" iff it contains an entry
+ * whose hostname is a parent of the owning site's hostname (e.g. site URL
+ * `https://community.example.com` with a block entry pointing at
+ * `https://example.com`). This matches the failure shape pinned in #77 —
+ * `buildMultisiteBlock` called from a subsite invocation maps the network's
+ * other sites (including the network root) into the block.
+ *
+ * Drop condition: any OTHER configured site has `url` whose origin matches
+ * the candidate network-root entry. Without that, the operator still needs
+ * the misplaced block for dot-notation routing until they add the
+ * network-root URL — leaving it intact preserves utility on the upgrade path.
+ *
+ * @param {object} config  Parsed wp-sites.json — must have `config.sites`.
+ * @returns {string[]}     Advisory messages, one per dropped block.
+ */
+function migrateMisplacedMultisiteBlocks(config) {
+  const messages = [];
+  if (!config || !config.sites || typeof config.sites !== 'object') return messages;
+
+  const siteOrigins = new Map();
+  for (const [key, site] of Object.entries(config.sites)) {
+    if (!site || typeof site.url !== 'string') continue;
+    let origin;
+    try { origin = new URL(site.url).origin.toLowerCase(); }
+    catch { continue; }
+    siteOrigins.set(origin, key);
+  }
+
+  for (const [siteKey, site] of Object.entries(config.sites)) {
+    if (!site || !site.multisite || typeof site.multisite !== 'object') continue;
+    if (typeof site.url !== 'string') continue;
+
+    let siteHost;
+    try { siteHost = new URL(site.url).hostname.toLowerCase().replace(/^www\./, ''); }
+    catch { continue; }
+
+    // Find a block entry whose hostname is a parent domain of this site's
+    // hostname AND maps to a different origin from the site itself. That's
+    // the network-root candidate.
+    let networkRootUrl = null;
+    let networkRootOrigin = null;
+    for (const subsiteUrl of Object.values(site.multisite)) {
+      if (typeof subsiteUrl !== 'string' || subsiteUrl.length === 0) continue;
+      let entryHost, entryOrigin;
+      try {
+        const u = new URL(subsiteUrl);
+        entryHost = u.hostname.toLowerCase().replace(/^www\./, '');
+        entryOrigin = u.origin.toLowerCase();
+      } catch { continue; }
+      if (entryHost === siteHost) continue;
+      if (siteHost.endsWith('.' + entryHost)) {
+        networkRootUrl = subsiteUrl;
+        networkRootOrigin = entryOrigin;
+        break;
+      }
+    }
+    if (!networkRootUrl) continue;
+
+    const rootSiteKey = siteOrigins.get(networkRootOrigin);
+    if (!rootSiteKey || rootSiteKey === siteKey) continue;
+
+    delete site.multisite;
+    messages.push(
+      `Migration (#77): dropped subsite-rooted multisite block from "${siteKey}" ` +
+      `(${site.url}); the network-root entry "${rootSiteKey}" (${networkRootUrl}) ` +
+      `is also configured, so dot-notation routing belongs there. Subsite-rooted ` +
+      `blocks describe the network from one subsite's perspective and surface ` +
+      `parallel cross-product enumerations at the MCP tool surface.`
+    );
+  }
+  return messages;
+}
+
 async function validateSiteConfig(key, site) {
   // v2 OAuth sites carry no transport block (Appendix F.5 + add-site flow).
   // The runtime treats them as HTTP — endpoint comes from auth.mcp_resource
@@ -477,4 +569,5 @@ module.exports = {
   buildSiteKeyEnum,
   buildEnvConfig,
   validateSiteConfig,
+  migrateMisplacedMultisiteBlocks,
 };

package/lib/connection-pool.js

@@ -2,6 +2,7 @@
 
 const { SshTransport } = require('./transports/ssh-transport');
 const { resolveSiteKey, resolveSitePassword } = require('./config');
+const { AUTH_STATUS } = require('./auth/events');
 
 // Incrementing counter for synthetic handshake IDs.
 // Avoids integer overflow from Date.now() (13-digit ms timestamps exceed
@@ -138,14 +139,69 @@ class ConnectionPool {
   /**
    * Create and connect transport for the default site (no handshake replay).
    * Called once at startup — the client handles the handshake directly.
+   *
+   * Issue #76: per-site auth-init isolation. The configured `defaultSite` is
+   * tried first; if its `_createTransport` / `transport.connect()` throws
+   * (typically a `RefreshError` when the refresh token is expired — confirmed
+   * via static trace from `lib/auth/token-manager.js:147-152`), the failure
+   * is captured against the site's in-memory `auth_status` and the next
+   * configured site is tried in `Object.keys(config.sites)` order. The first
+   * site that connects becomes the runtime default (`config.defaultSite` is
+   * reassigned in-memory only — wp-sites.json on disk is untouched).
+   *
+   * Returns `null` when ALL configured sites fail. The bootstrap caller pairs
+   * a `null` return with `router.enterDegradedMode(...)` so the bridge still
+   * answers `initialize` with a valid `InitializeResult` — the failure mode
+   * the gate explicitly forbids (init-time bridge death) cannot recur.
+   *
+   * @param {function} onMessage  Per-site message router callback.
+   * @returns {Promise<Transport|null>}
    */
   async connectDefault(onMessage) {
-    const key = this.config.defaultSite;
-    const transport = await this._createTransport(key, null);
-    transport.onMessage = onMessage;
-    await transport.connect();
-    this.transports.set(key, transport);
-    return transport;
+    const configuredDefault = this.config.defaultSite;
+    const otherKeys = Object.keys(this.config.sites).filter((k) => k !== configuredDefault);
+    const tryOrder = [configuredDefault, ...otherKeys];
+
+    for (const key of tryOrder) {
+      try {
+        const transport = await this._createTransport(key, null);
+        transport.onMessage = onMessage;
+        await transport.connect();
+        this.transports.set(key, transport);
+
+        if (key !== configuredDefault) {
+          this.log(
+            `Configured default "${configuredDefault}" failed to connect; ` +
+            `runtime default fell back to "${key}". The configured default ` +
+            `is marked degraded in-memory; reauth it to restore.`
+          );
+          this.config.defaultSite = key;
+        }
+        return transport;
+      } catch (err) {
+        this.log(`Site "${key}" failed to connect at boot: ${err.message}`);
+        this._markSiteDegraded(key, err);
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Mark a site degraded in the in-memory config so other lookups (tools/list,
+   * resources/read wp-abilities://sites, per-call routing) can surface it
+   * without re-attempting the failed connection. The on-disk wp-sites.json is
+   * NOT rewritten here — degraded state is recoverable (operator runs reauth)
+   * and the next bridge boot will re-attempt the connection from the existing
+   * persisted state.
+   *
+   * @private
+   */
+  _markSiteDegraded(siteId, err) {
+    const site = this.config.sites && this.config.sites[siteId];
+    if (!site) return;
+    site.auth_status = AUTH_STATUS.EXPIRED;
+    site._degraded_reason = (err && err.message) || 'connect failed';
   }
 
   /**

package/lib/router.js

@@ -54,6 +54,15 @@ class McpRouter {
     // Early queue for messages before transport is ready
     this.MAX_EARLY_QUEUE = 50;
     this.earlyQueue = [];
+
+    // Issue #76: degraded mode — entered when ALL configured sites fail to
+    // connect at boot. The bridge still answers `initialize` with a locally
+    // synthesized InitializeResult (so the MCP runtime stays connectable and
+    // the operator can call wp_bridge_health to see which sites are degraded);
+    // tools/list returns the bridge's three local tools only; non-bridge
+    // tools/call surfaces a per-call error naming the degraded sites.
+    this.degraded = false;
+    this.degradedSites = [];  // [{ siteId, reason }]
   }
 
   /**
@@ -63,6 +72,22 @@ class McpRouter {
     this.defaultTransport = transport;
   }
 
+  /**
+   * Issue #76: enter degraded mode when no configured site connected at boot.
+   * The router will synthesize an InitializeResult on the next `initialize`
+   * request and refuse non-bridge tool calls with a descriptive error.
+   *
+   * @param {Array<{siteId:string, reason:string}>} degradedSites
+   */
+  enterDegradedMode(degradedSites) {
+    this.degraded = true;
+    this.degradedSites = Array.isArray(degradedSites) ? degradedSites.slice() : [];
+    this.log(
+      `Router entering degraded mode: ${this.degradedSites.length} site(s) failed to ` +
+      `connect at boot — ` + this.degradedSites.map((s) => `${s.siteId} (${s.reason})`).join('; ')
+    );
+  }
+
   /**
    * Drain messages queued before the default transport was ready.
    */
@@ -90,6 +115,14 @@ class McpRouter {
       if (msg.params && msg.params.protocolVersion) {
         this.clientProtocolVersion = msg.params.protocolVersion;
       }
+      // Issue #76: in degraded mode (no site transport at boot), synthesize
+      // a locally-valid InitializeResult so the MCP runtime stays connectable
+      // and the client can still issue wp_bridge_health / etc. against the
+      // bridge's local tools.
+      if (this.degraded) {
+        this._sendSynthesizedInitializeResult(msg);
+        return;
+      }
       this._forwardToDefault(line);
       return;
     }
@@ -99,12 +132,22 @@ class McpRouter {
       this.cachedInitNotification = msg;
       this.initHandshakeComplete = true;
       this.pool.setHandshakeCache(this.cachedInitRequest, this.cachedInitNotification, this.clientProtocolVersion);
+      // In degraded mode there is no transport to forward to; the notification
+      // is purely informational once the synthesized InitializeResult has been
+      // sent.
+      if (this.degraded) return;
       this._forwardToDefault(line);
       return;
     }
 
     // tools/list — route to default, then inject site param
     if (msg.method === 'tools/list') {
+      // Issue #76: in degraded mode, return only the bridge's local tools so
+      // operators can call wp_bridge_health and see which sites are degraded.
+      if (this.degraded) {
+        this._sendSynthesizedToolsListResult(msg);
+        return;
+      }
       this._forwardToDefault(line);
       return;
     }
@@ -115,6 +158,13 @@ class McpRouter {
         this._handleBridgeToolCall(msg);
         return;
       }
+      // Issue #76: in degraded mode there is no backing site transport; surface
+      // a per-call error naming the degraded sites so the client sees a clear
+      // diagnostic, not a hang.
+      if (this.degraded) {
+        this._sendDegradedToolsCallError(msg);
+        return;
+      }
       this._handleToolsCall(msg);
       return;
     }
@@ -153,6 +203,37 @@ class McpRouter {
       return;
     }
 
+    // Issue #76 follow-up — request-time boundary.
+    //
+    // OAuthHttpTransport.connect() does NOT pre-validate tokens (lib/transports/
+    // oauth-http-transport.js:139-143 — sets ready=true, returns). When the
+    // configured default site has an expired refresh token, _createTransport
+    // and connect() both succeed; the bridge does NOT enter the connect-time
+    // degraded path covered by #81. Instead, drainEarlyQueue() forwards the
+    // cached `initialize` request through the transport, _processMessage
+    // calls _postWithRetry → getAccessToken → refresh → throws RefreshError
+    // synchronously when authStatus===EXPIRED (lib/auth/token-manager.js:147).
+    // _processMessage catches the throw at lib/transports/oauth-http-transport.js:
+    // 379-388 and emits onMessage with `{jsonrpc, id, error}` — the cached
+    // initialize id paired with `OAuth HTTP bridge error: …`. Without this
+    // intercept, the error→CallToolResult conversion below blanket-converts
+    // it to `{result:{content:[],isError:true}}` and the MCP runtime rejects
+    // the response shape. Pin the gate-violating shape here: when the failed
+    // response carries the cached initialize id, synthesize a valid
+    // InitializeResult locally and enter degraded mode for the failed site.
+    if (parsedMsg.error && parsedMsg.id !== undefined &&
+        this.cachedInitRequest && parsedMsg.id === this.cachedInitRequest.id) {
+      const failedSite = this.config && this.config.defaultSite;
+      const reason = (parsedMsg.error && parsedMsg.error.message) || 'unknown';
+      this.log(
+        `Initialize forward failed for "${failedSite || '(unknown)'}": ${reason} — ` +
+        `synthesizing degraded-mode InitializeResult to satisfy MCP runtime`
+      );
+      this._sendSynthesizedInitializeResult(this.cachedInitRequest);
+      this.enterDegradedMode([{ siteId: failedSite || '(unknown)', reason }]);
+      return;
+    }
+
     // Sanitize tools/list responses
     if (isToolsListResponse(parsedMsg)) {
       sanitizeToolsList(parsedMsg, this.log);
@@ -234,22 +315,112 @@ class McpRouter {
   _forwardToDefault(line) {
     if (this.defaultTransport) {
       this.defaultTransport.send(line);
-    } else {
-      if (this.earlyQueue.length >= this.MAX_EARLY_QUEUE) {
-        this.log('Early queue full — rejecting message');
-        try {
-          const msg = JSON.parse(line);
-          if (msg.id !== undefined) {
-            this.sendToClient(JSON.stringify({
-              jsonrpc: '2.0', id: msg.id,
-              error: { code: -32603, message: 'Server not ready — queue full' }
-            }));
-          }
-        } catch (e) { /* non-JSON, drop */ }
-        return;
-      }
-      this.earlyQueue.push(line);
+      return;
+    }
+    // Issue #76: in degraded mode any message that reached this point (i.e.
+    // not handled by a degraded-aware branch above) gets a per-call error
+    // rather than being queued forever waiting for a transport that will
+    // never arrive.
+    if (this.degraded) {
+      try {
+        const msg = JSON.parse(line);
+        if (msg.id !== undefined) {
+          this.sendToClient(JSON.stringify({
+            jsonrpc: '2.0', id: msg.id,
+            error: {
+              code: -32603,
+              message: `Bridge running in degraded mode — no site transport available. ` +
+                this._degradedSummary(),
+            },
+          }));
+        }
+      } catch (e) { /* non-JSON, drop */ }
+      return;
+    }
+    if (this.earlyQueue.length >= this.MAX_EARLY_QUEUE) {
+      this.log('Early queue full — rejecting message');
+      try {
+        const msg = JSON.parse(line);
+        if (msg.id !== undefined) {
+          this.sendToClient(JSON.stringify({
+            jsonrpc: '2.0', id: msg.id,
+            error: { code: -32603, message: 'Server not ready — queue full' }
+          }));
+        }
+      } catch (e) { /* non-JSON, drop */ }
+      return;
+    }
+    this.earlyQueue.push(line);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal — degraded mode (Issue #76)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Synthesize a valid MCP InitializeResult so the client's MCP validator
+   * receives `protocolVersion`, `capabilities`, and `serverInfo` instead of
+   * EOF (the failure mode pinned in #76 — bridge died before any response).
+   *
+   * Echoes the client's `protocolVersion` when present (per MCP spec — the
+   * server returns the negotiated version, defaulting to its own when no
+   * client-side version was provided).
+   */
+  _sendSynthesizedInitializeResult(msg) {
+    const clientProtocol = msg.params && msg.params.protocolVersion;
+    const result = {
+      jsonrpc: '2.0',
+      id: msg.id,
+      result: {
+        protocolVersion: clientProtocol || '2025-06-18',
+        capabilities: { tools: {}, resources: {} },
+        serverInfo: {
+          name: 'abilities-mcp (degraded)',
+          version: this._bridgeVersion(),
+        },
+      },
+    };
+    this.sendToClient(JSON.stringify(result));
+  }
+
+  /**
+   * Synthesize a tools/list response with only the bridge's local tools.
+   * In degraded mode there is no WordPress adapter to answer the real list,
+   * so wp_bridge_health / wp_browse_tools / wp_load_tools are still callable
+   * for diagnostics.
+   */
+  _sendSynthesizedToolsListResult(msg) {
+    const result = { jsonrpc: '2.0', id: msg.id, result: { tools: [] } };
+    injectBridgeTools(result);
+    this.sendToClient(JSON.stringify(result));
+  }
+
+  _sendDegradedToolsCallError(msg) {
+    this.sendToClient(JSON.stringify({
+      jsonrpc: '2.0', id: msg.id,
+      error: {
+        code: -32603,
+        message: `Tool call cannot be served — bridge is running in degraded mode. ` +
+          this._degradedSummary() +
+          ` Run: abilities-mcp reauth <site> to recover, or use the bridge tools ` +
+          `(wp_bridge_health, wp_browse_tools, wp_load_tools) for diagnostics.`,
+      },
+    }));
+  }
+
+  _degradedSummary() {
+    if (!this.degradedSites || this.degradedSites.length === 0) {
+      return 'No degraded-site details available.';
     }
+    const parts = this.degradedSites.map((s) => `${s.siteId}: ${s.reason}`);
+    return `Degraded sites — ${parts.join('; ')}.`;
+  }
+
+  _bridgeVersion() {
+    try {
+      const pkg = require('../package.json');
+      return (pkg && pkg.version) || 'unknown';
+    } catch { return 'unknown'; }
   }
 
   // ---------------------------------------------------------------------------
@@ -292,14 +463,26 @@ class McpRouter {
       }
 
       const summary = this.catalog.getCategorySummary();
-      const lines = summary.map(c =>
-        `${c.active ? '[LOADED]' : '       '} ${c.name} (${c.toolCount} tools)`
+      const lines = [];
+      lines.push(
+        `Scope: direct-tool catalog scoped to defaultSite (${this.config.defaultSite}). ` +
+          `Not full cross-site ability discovery.`
       );
       lines.push('');
+      for (const c of summary) {
+        lines.push(`${c.active ? '[LOADED]' : '       '} ${c.name} (${c.toolCount} tools)`);
+      }
+      lines.push('');
       lines.push(`Total: ${this.catalog.fullTools.length} tools in ${summary.length} categories`);
       lines.push(`Loaded: ${summary.filter(c => c.active).reduce((n, c) => n + c.toolCount, 0)} tools`);
       lines.push('');
       lines.push('Use wp_load_tools with categories array to activate.');
+      lines.push('');
+      lines.push(
+        'For abilities on another site, or in a category not listed here, use ' +
+          'mcp-adapter-discover-abilities { site, category } and ' +
+          'mcp-adapter-execute-ability { site, ability_name, parameters }.'
+      );
 
       this.sendToClient(JSON.stringify({
         jsonrpc: '2.0', id: msg.id,
@@ -325,6 +508,7 @@ class McpRouter {
       }
 
       const activated = this.catalog.activateCategories(toActivate);
+      const missing = toActivate.filter((c) => !this.catalog.categories[c]);
       const lines = [];
 
       if (activated.length > 0) {
@@ -333,8 +517,25 @@ class McpRouter {
       if (toDeactivate.length > 0) {
         lines.push(`Deactivated: ${toDeactivate.join(', ')}`);
       }
-      if (activated.length === 0 && toDeactivate.length === 0) {
-        lines.push('No changes — categories may already be active or not found.');
+      if (missing.length > 0) {
+        lines.push(
+          `Not in the direct-tool catalog (scoped to defaultSite "${this.config.defaultSite}"): ` +
+            missing.join(', ') +
+            '.'
+        );
+        lines.push(
+          'For abilities on another site, or in a category not in this catalog, use the ' +
+            'adapter meta-tools instead:'
+        );
+        for (const cat of missing) {
+          lines.push(`  mcp-adapter-discover-abilities { site: "<site>", category: "${cat}" }`);
+        }
+        lines.push(
+          '  mcp-adapter-execute-ability { site: "<site>", ability_name: "<ability>", parameters: { ... } }'
+        );
+      }
+      if (activated.length === 0 && toDeactivate.length === 0 && missing.length === 0) {
+        lines.push('No changes — categories may already be active.');
       }
 
       const filtered = this.catalog.getFilteredTools();

package/lib/sanitizer.js

@@ -29,7 +29,19 @@ function validateToolSchema(toolName, schema, log) {
     log(`SCHEMA WARN [${toolName}]: invalid top-level type "${schema.type}"`);
   }
 
-  if (!schema.properties || typeof schema.properties !== 'object') return;
+  // Boundary: properties key absent — leave inputSchema byte-unchanged.
+  if (schema.properties === undefined) return;
+
+  // Normalize malformed `properties` shapes (PHP `array()` JSON-encodes to `[]`,
+  // strings, null, primitives) to `{}` before downstream validation. Anthropic's
+  // draft 2020-12 validator rejects the entire tools/list payload on the first
+  // invalid schema, so a single vendor-registered `properties: []` breaks the
+  // whole catalog. Mirror of the top-level inputSchema normalize one frame up.
+  if (schema.properties === null || typeof schema.properties !== 'object' || Array.isArray(schema.properties)) {
+    log(`SCHEMA NORMALIZE [${toolName}]: inputSchema.properties not a plain object — normalized to {}`);
+    schema.properties = {};
+    return;
+  }
 
   for (const [prop, def] of Object.entries(schema.properties)) {
     if (!def || typeof def !== 'object') {
@@ -65,8 +77,14 @@ function sanitizeToolsList(msg, log) {
     delete tool.type;
     delete tool.outputSchema;
 
-    // Validate schema and log warnings
-    if (tool.inputSchema) {
+    // Normalize broken or non-object inputSchema (defensive — broken upstream
+    // schemas would otherwise 400 the API and break the entire tool list).
+    if (!tool.inputSchema || typeof tool.inputSchema !== 'object' || Array.isArray(tool.inputSchema)) {
+      if (tool.inputSchema !== undefined) {
+        _log(`SCHEMA NORMALIZE [${tool.name || '(unnamed)'}]: inputSchema not a valid object — defaulted to {type:'object'}`);
+      }
+      tool.inputSchema = { type: 'object' };
+    } else {
       validateToolSchema(tool.name || '(unnamed)', tool.inputSchema, _log);
     }
 

package/lib/tool-catalog.js

@@ -32,11 +32,22 @@ class ToolCatalog {
     // Active (loaded) categories
     this.activeCategories = new Set();
 
-    // Initialize always-included categories from config
-    if (this.filterConfig && this.filterConfig.alwaysIncludeCategories) {
-      for (const cat of this.filterConfig.alwaysIncludeCategories) {
-        this.activeCategories.add(cat);
-      }
+    // Resolve "always-include" categories once. Explicit operator config wins
+    // (including an explicit empty list, which preserves the operator's choice).
+    // When filtering is enabled and the operator hasn't set their own list,
+    // default to ['mcp-adapter'] so the cross-site adapter meta-tools
+    // (mcp-adapter-discover-abilities / -get-ability-info / -execute-ability)
+    // are always visible without requiring a prior wp_load_tools call.
+    const explicit = this.filterConfig && this.filterConfig.alwaysIncludeCategories;
+    const resolved =
+      explicit !== undefined && explicit !== null
+        ? explicit
+        : this.isEnabled()
+        ? ['mcp-adapter']
+        : [];
+    this.effectiveAlwaysInclude = new Set(resolved);
+    for (const cat of this.effectiveAlwaysInclude) {
+      this.activeCategories.add(cat);
     }
   }
 
@@ -104,12 +115,11 @@ class ToolCatalog {
    * Deactivate categories (return to compact mode).
    */
   deactivateCategories(categoryNames) {
-    // Don't deactivate always-included categories
-    const alwaysIncluded = new Set(
-      (this.filterConfig && this.filterConfig.alwaysIncludeCategories) || []
-    );
+    // Don't deactivate always-included categories (single source of truth:
+    // the set resolved at construction, so the default mcp-adapter inclusion
+    // is treated the same as an explicit operator-configured entry).
     for (const name of categoryNames) {
-      if (!alwaysIncluded.has(name)) {
+      if (!this.effectiveAlwaysInclude.has(name)) {
         this.activeCategories.delete(name);
       }
     }

package/package.json

@@ -1,13 +1,29 @@
 {
   "name": "@wickedevolutions/abilities-mcp",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "description": "Open-source MCP bridge connecting AI clients to WordPress through the Abilities API — multi-site routing, zero dependencies",
   "main": "abilities-mcp.js",
   "bin": {
     "abilities-mcp": "./abilities-mcp.js"
   },
-  "files": ["abilities-mcp.js", "lib/", "wp-sites.example.json", "LICENSE", "README.md", "CHANGELOG.md"],
-  "keywords": ["mcp", "wordpress", "bridge", "abilities", "ai", "open-source", "multi-site", "model-context-protocol"],
+  "files": [
+    "abilities-mcp.js",
+    "lib/",
+    "wp-sites.example.json",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "mcp",
+    "wordpress",
+    "bridge",
+    "abilities",
+    "ai",
+    "open-source",
+    "multi-site",
+    "model-context-protocol"
+  ],
   "license": "GPL-2.0-or-later",
   "author": "Wicked Evolutions",
   "repository": {