@wickedevolutions/abilities-mcp 1.5.1 → 1.5.4

package/CHANGELOG.md

@@ -2,6 +2,81 @@
 
 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.
+
+Bridge-only release — no companion adapter or ai release this hotfix.
+
+### Fixed
+
+- **`KeychainSecretStore` falls back to the macOS `security` CLI when keytar fails to load on darwin** (PR [#40](https://github.com/Wicked-Evolutions/abilities-mcp/pull/40), closes [#39](https://github.com/Wicked-Evolutions/abilities-mcp/issues/39)). When `require('keytar')` throws on darwin (the hardened-runtime Team ID mismatch), `_load()` sets `_fallbackMode = 'security-cli'` instead of throwing. `get` / `set` / `delete` then dispatch to `security find-generic-password -w` / `add-generic-password -U` / `delete-generic-password` via `child_process.execFile` (no shell — argv passes verbatim, no shell-injection surface). `findAll` returns `[]` in fallback mode (security CLI has no clean enumerate-by-service; the bridge runtime path doesn't depend on it — only the CLI subcommand `list-sites` does, which runs in system Node where keytar loads normally). Stderr matching `/could not be found/i` maps to keytar's null (get) / false (delete) return semantics; other stderr propagates as `SecretStoreError` code `security_cli_failed`. `isAvailable()` returns true in both keytar and fallback modes. **Linux/Windows behavior unchanged** — keytar load failures on those platforms still throw `keytar_unavailable` (no fallback engaged; the security CLI is darwin-only). Test seams (`requireKeytar`, `platform`, `exec` injection on the constructor) added for fallback-path unit testing without breaking the test runtime's real `require('keytar')`. New `test/auth/keychain-secret-store-darwin-fallback.test.js` covers keytar-success preservation, fallback engagement on darwin, "could not be found" mapping, error propagation, `isAvailable` in both modes, linux/win32 throw-not-fallback, and `findAll` in fallback mode. The first time the `.mcpb`-installed bridge accesses a keychain entry on darwin, macOS will prompt for keychain access — operator clicks "Always Allow" once per entry and the prompt persists thereafter. This is a macOS keychain ACL property; the same prompt would have appeared with keytar-native if it had loaded.
+
+### Internal
+
+- **Test count:** `265 → 275` (+10 in `keychain-secret-store-darwin-fallback.test.js`).
+- **Bundle size unchanged** (~420 kB packed, ~1.3 MB unpacked — the four platform-specific keytar binaries dominate; the secret-store code change is small relative to that).
+
+### Known unverified — research outstanding for a follow-up release
+
+- **Linux:** whether keytar's libsecret native binding loads cleanly inside Linux Claude Desktop's `.mcpb` runtime is unverified. Likely works (Linux's runtime model differs from macOS — no Team ID matching), but no Linux Claude Desktop access during this hotfix to test empirically. Operators on Linux Claude Desktop should test and report.
+- **Windows:** whether keytar's win32 native binding loads cleanly inside Windows Claude Desktop's hardened process is unverified. If it doesn't, a separate Windows-specific fix shape is needed (PowerShell credential cmdlets, or formally limiting Windows operators to the CLI install path). Tracked for a follow-up release.
+
+## [1.5.2] - 2026-05-03
+
+**OAuth flow now works inside `.mcpb`.** This release makes the documented `.mcpb` operator UX work end-to-end: install the extension from Claude Desktop with an Application Password, then run `abilities-mcp upgrade-auth <site>` from a terminal to migrate that single connection to OAuth in place, then `abilities-mcp add-site https://other.com` to add more sites — all surfacing through the same Claude Desktop "Abilities MCP" entry. Before this release, the keytar binary wasn't bundled with the `.mcpb` and the `.mcpb` install never persisted to `~/.abilities-mcp/wp-sites.json`, so the documented progression failed at the moment OAuth touched the keychain.
+
+Bridge-only release — no companion adapter or ai release this sprint.
+
+### Fixed
+
+- **`.mcpb` bundle now ships keytar prebuilds for darwin x64, darwin arm64, win32 x64, and linux x64** (PR [#35](https://github.com/Wicked-Evolutions/abilities-mcp/pull/35), closes [#33](https://github.com/Wicked-Evolutions/abilities-mcp/issues/33)). Without these, `KeychainSecretStore` failed at first request with `Cannot find module 'keytar'` even on the host platform — verified empirically against the v1.5.1 bundle. The pack pipeline moves from a single-line `mcpb pack` invocation to a staging-directory build (`scripts/pack-mcpb.js`) that fetches each platform's prebuild via `prebuild-install` and patches keytar's hardcoded single-slot loader (`var keytar = require('../build/Release/keytar.node')` in keytar 7.9.0) with a multi-platform-aware loader keyed on `process.platform`-`process.arch`. The patch is staging-only — `node_modules/keytar/` in the project tree is byte-identical pre-pack and post-pack, pinned by the new `scripts/verify-pack-isolation.js` (run via `npm run verify:pack-isolation`). Pre-patch substring assertion on the upstream loader fails loud if a future keytar bump changes the loader shape.
+
+- **Bridge emits one operator-visible `Config source:` line on startup to stderr** (PR [#36](https://github.com/Wicked-Evolutions/abilities-mcp/pull/36), closes [#32](https://github.com/Wicked-Evolutions/abilities-mcp/issues/32)). Captured in Claude Desktop's per-server MCP log so the operator can tell at a glance which `loadConfig` source won. Names the source (`env-var` / `[explicit-config]` / `[script-adjacent]` / `[home-dir]` / `legacy-cli`), the file path (tildified) or hostname, the site count, and the per-site auth method. Sample output:
+  ```
+  Config source: ABILITIES_MCP_URL env var (single-site basic auth: example.com as wp_user)
+  Config source: [home-dir] ~/.abilities-mcp/wp-sites.json (3 sites: helena oauth, wicked oauth, tnn apppassword)
+  ```
+  No secrets — only IDs, methods, hostnames, paths, counts. Always-on, not gated by `--debug`.
+
+- **`.mcpb` install seeds `~/.abilities-mcp/wp-sites.json` on first launch** (PR [#37](https://github.com/Wicked-Evolutions/abilities-mcp/pull/37), closes [#34](https://github.com/Wicked-Evolutions/abilities-mcp/issues/34)). When the env-var-mode bridge boots and the home-dir config doesn't exist, `seedFromEnvIfMissing` writes a v2 apppassword entry derived from the `ABILITIES_MCP_*` env vars before serving the first MCP request. `list-sites`, `upgrade-auth`, and `add-site` now operate on a single source of truth that already includes the `.mcpb`-installed site. The site-id is derived from the URL hostname, matching `add-site`'s `deriveSiteId`. Guards: pre-existing `wp-sites.json` is **never overwritten**; missing env vars / malformed URL / keytar unavailable → graceful no-op (bridge falls back to env-var-only mode); file-write failure → keychain entry rolled back so operators don't accumulate orphan secrets.
+
+### Changed
+
+- **keytar pinned `^7.9.0` → `~7.9.0`** (patch versions only) so the staging script's pre-patch loader-shape substring assertion has a stable target. CLI install behavior is unchanged — keytar stays in `optionalDependencies` (skips gracefully on platforms without prebuilds).
+- **`_configSource` discriminant renamed `'env'` → `'env-var'`** to align with the documented set (`explicit-config`, `script-adjacent`, `home-dir`, `env-var`, `legacy-cli`). Internal field, prefixed with underscore; only one test was reading the prior value (updated).
+
+### Internal
+
+- **Bundle size:** `~115 kB → ~413 kB` packed / `~1.2 MB` unpacked. The four platform-specific keytar prebuilds (darwin-x64 ~83 kB, darwin-arm64 ~99 kB, win32-x64 ~707 kB, linux-x64 ~76 kB) are embedded for the `.mcpb` install path. CLI install paths are unaffected — keytar stays in `optionalDependencies` and is host-only via the operator's `npm install`.
+- **Test count:** `237 → 265` (+28 across the sprint: 0 new in PR #35, +15 in PR #36, +13 in PR #37). Node CI matrix unchanged: 18, 20, 22.
+- New maintenance scripts: `npm run pack:mcpb` (staging build + multi-platform prebuild fetch), `npm run verify:pack-isolation` (asserts `node_modules/keytar/` byte-identity across pack runs).
+
 ## [1.5.1] - 2026-05-02
 
 Stretch-to-stable release. Closes the OAuth 2.1 alpha audit pass and the two integration-seam regressions surfaced during Helena's Phase B operator verification, plus the async-config tech-debt sweep that shares the bridge's startup path. No new features, no surface changes — the v1.5.x line is now stable for broader operator adoption.

package/abilities-mcp.js

@@ -24,6 +24,7 @@
 
 const { createLogger } = require('./lib/logger');
 const { loadConfig, buildSiteKeyEnum, resolveConfigFilePath } = require('./lib/config');
+const { formatConfigSourceLine } = require('./lib/config-source-line');
 const { ConnectionPool } = require('./lib/connection-pool');
 const { ToolCatalog } = require('./lib/tool-catalog');
 const { McpRouter } = require('./lib/router');
@@ -141,6 +142,13 @@ if (!isSubcommandInvocation) {
       process.exit(1);
     }
 
+    // Emit a single config-source line to stderr so operators can diagnose
+    // which mode the bridge is in at a glance (Claude Desktop's MCP log
+    // captures the server's stderr stream). Always-on, not gated by --debug:
+    // operator-visibility is the entire point of #32 and createLogger is a
+    // debug-only file logger that wouldn't reach Claude Desktop's log.
+    process.stderr.write(formatConfigSourceLine(config) + '\n');
+
     const isMultiSite = config._isMultiSite;
     const siteKeys = buildSiteKeyEnum(config);
     log(`Config loaded: ${siteKeys.length} site(s): ${siteKeys.join(', ')} (default: ${config.defaultSite})`);

package/lib/auth/keychain-secret-store.js

@@ -1,16 +1,36 @@
 'use strict';
 
+const { execFile } = require('node:child_process');
+
 const { SecretStoreError } = require('./errors');
 
 /**
- * KeychainSecretStore — keytar-backed SecretStore.
+ * KeychainSecretStore — keytar-backed SecretStore with a darwin-only
+ * `security` CLI fallback for Claude Desktop's hardened-runtime barrier.
+ *
+ * keytar wraps macOS Keychain, Windows Credential Manager, and Linux libsecret
+ * via a native binding (`build/Release/keytar.node`). It is declared as an
+ * `optionalDependency` so a failed native build does not break `npm install`
+ * for env-var-only operators.
+ *
+ * **The darwin fallback (issue #39).** When the bundled keytar binary fails
+ * to dlopen inside Claude Desktop's hardened-runtime process — the macOS
+ * code-signing rejects native binaries with mismatched Team IDs, Anthropic-
+ * signed Claude Desktop refuses to load npm-distribution-signed keytar.node —
+ * we fall back to shelling out to the macOS `security` CLI via
+ * `child_process.execFile`. `security` is always installed on macOS, doesn't
+ * require dynamic native loading, operates against the same macOS Keychain,
+ * and runs as a child process out from under Claude Desktop's hardened-
+ * runtime restrictions. The fallback fires only on darwin; on linux/win32 a
+ * keytar load failure still throws `keytar_unavailable` (current behavior).
+ *
+ * Outside the .mcpb path — system Node, CLI install, npx, source clone —
+ * keytar loads normally and the fallback never engages.
  *
- * keytar wraps macOS Keychain, Windows Credential Manager, and Linux libsecret.
- * It is declared as an `optionalDependency` so a failed native build does not
- * break `npm install` for env-var-only operators. If keytar is unavailable at
- * runtime, every method on this store throws `SecretStoreError` with code
- * `keytar_unavailable` — callers can detect that and fall back to a different
- * store (e.g. MemorySecretStore for tests, or surface to the user).
+ * If keytar is unavailable at runtime AND the darwin fallback also can't run,
+ * every method throws `SecretStoreError` with code `keytar_unavailable` —
+ * callers can detect that and fall back to a different store (e.g.
+ * MemorySecretStore for tests, or surface to the user).
  *
  * Implements the SecretStore interface defined in `secret-store.js`.
  *
@@ -21,38 +41,67 @@ const { SecretStoreError } = require('./errors');
 class KeychainSecretStore {
   /**
    * @param {object} [opts]
-   * @param {object} [opts.keytar]  Inject a keytar module — primarily for tests.
-   *                                When omitted, keytar is required lazily on
-   *                                first use.
+   * @param {object} [opts.keytar]         Inject a keytar module — primarily for tests.
+   *                                       When omitted, keytar is required lazily on
+   *                                       first use.
+   * @param {Function} [opts.requireKeytar] Override the require call used to load
+   *                                       keytar. Test seam: pass a function that
+   *                                       throws to simulate the .mcpb-path dlopen
+   *                                       rejection without breaking the real
+   *                                       require('keytar') in the test runtime.
+   * @param {string} [opts.platform]       Override `process.platform` for the
+   *                                       fallback-eligibility decision. Test seam.
+   * @param {Function} [opts.exec]         Override `child_process.execFile`. Test
+   *                                       seam for the security-CLI fallback path.
    */
   constructor(opts = {}) {
     this._injected = opts.keytar || null;
     this._keytar = null;
     this._loadAttempted = false;
     this._loadError = null;
+    this._fallbackMode = null; // null | 'security-cli'
+
+    this._requireKeytar = opts.requireKeytar || ((id) => require(id));
+    this._platform = opts.platform || process.platform;
+    this._exec = opts.exec || execFile;
   }
 
+  /**
+   * Lazy load. Sets one of three terminal states:
+   *  - `this._keytar` populated (keytar loaded normally; primary path)
+   *  - `this._fallbackMode === 'security-cli'` (darwin fallback engaged)
+   *  - `this._loadError` set + throws (non-darwin keytar failure)
+   */
   _load() {
-    if (this._keytar) return this._keytar;
+    if (this._keytar || this._fallbackMode) {
+      return;
+    }
     if (this._loadAttempted) {
-      if (this._loadError) {
-        throw new SecretStoreError(
-          `OS keychain unavailable: ${this._loadError.message}`,
-          { code: 'keytar_unavailable', cause: this._loadError }
-        );
-      }
-      return this._keytar;
+      // Previously failed and we cached the error.
+      throw new SecretStoreError(
+        `OS keychain unavailable: ${this._loadError.message}`,
+        { code: 'keytar_unavailable', cause: this._loadError }
+      );
     }
     this._loadAttempted = true;
+
     if (this._injected) {
       this._keytar = this._injected;
-      return this._keytar;
+      return;
     }
+
     try {
-      // eslint-disable-next-line global-require
-      this._keytar = require('keytar');
-      return this._keytar;
+      this._keytar = this._requireKeytar('keytar');
+      return;
     } catch (err) {
+      // darwin: Claude Desktop's hardened-runtime rejects bundled keytar.node
+      // with a Team ID mismatch (issue #39). Fall back to the `security` CLI
+      // rather than throwing — the bridge keeps working against the same
+      // macOS Keychain, just via shell-out.
+      if (this._platform === 'darwin') {
+        this._fallbackMode = 'security-cli';
+        return;
+      }
       this._loadError = err;
       throw new SecretStoreError(
         `OS keychain unavailable: ${err.message}`,
@@ -61,7 +110,10 @@ class KeychainSecretStore {
     }
   }
 
-  /** @returns {Promise<boolean>} true if keytar can be loaded on this host. */
+  /**
+   * @returns {Promise<boolean>} true if keytar can be loaded on this host OR
+   *                             the darwin security-CLI fallback is engaged.
+   */
   async isAvailable() {
     try {
       this._load();
@@ -72,27 +124,142 @@ class KeychainSecretStore {
   }
 
   async get(service, account) {
-    const keytar = this._load();
-    return keytar.getPassword(service, account);
+    this._load();
+    if (this._fallbackMode === 'security-cli') {
+      return this._securityGet(service, account);
+    }
+    return this._keytar.getPassword(service, account);
   }
 
   async set(service, account, secret) {
     if (typeof secret !== 'string') {
       throw new TypeError('SecretStore.set: secret must be a string');
     }
-    const keytar = this._load();
-    await keytar.setPassword(service, account, secret);
+    this._load();
+    if (this._fallbackMode === 'security-cli') {
+      return this._securitySet(service, account, secret);
+    }
+    await this._keytar.setPassword(service, account, secret);
   }
 
   async delete(service, account) {
-    const keytar = this._load();
-    return keytar.deletePassword(service, account);
+    this._load();
+    if (this._fallbackMode === 'security-cli') {
+      return this._securityDelete(service, account);
+    }
+    return this._keytar.deletePassword(service, account);
   }
 
   async findAll(service) {
-    const keytar = this._load();
-    return keytar.findCredentials(service);
+    this._load();
+    if (this._fallbackMode === 'security-cli') {
+      // The macOS `security` CLI has no clean enumerate-by-service mode.
+      // Returning [] here is safe because the bridge runtime path never
+      // calls findAll — only the CLI subcommand `list-sites` does, and that
+      // runs in system Node where keytar loads normally and this branch
+      // is never taken. Documented in the issue body's "findAll" note.
+      return [];
+    }
+    return this._keytar.findCredentials(service);
   }
+
+  // ---------------------------------------------------------------------
+  // darwin `security` CLI fallback — internal helpers.
+  // ---------------------------------------------------------------------
+
+  /**
+   * Run the `security` CLI with the given args. Returns { stdout, stderr }
+   * on success, rejects with an error carrying `.stderr` / `.stdout` /
+   * `.code` (exit code) on failure. Uses `execFile` (not `exec`) so args
+   * are not shell-interpreted — the password / account / service strings
+   * pass through verbatim, no shell injection surface.
+   */
+  _execSecurity(args) {
+    return new Promise((resolve, reject) => {
+      this._exec('security', args, {}, (err, stdout, stderr) => {
+        const stdoutStr = typeof stdout === 'string'
+          ? stdout
+          : (stdout ? stdout.toString() : '');
+        const stderrStr = typeof stderr === 'string'
+          ? stderr
+          : (stderr ? stderr.toString() : '');
+        if (err) {
+          // Real child_process.execFile populates err.stderr / err.stdout
+          // and ALSO passes them as cb args. Preserve whichever the caller
+          // already attached (some test doubles attach to the err object
+          // and don't pass via cb args); fall back to the cb args otherwise.
+          if (typeof err.stderr !== 'string') err.stderr = stderrStr;
+          if (typeof err.stdout !== 'string') err.stdout = stdoutStr;
+          return reject(err);
+        }
+        resolve({ stdout: stdoutStr, stderr: stderrStr });
+      });
+    });
+  }
+
+  async _securityGet(service, account) {
+    try {
+      const { stdout } = await this._execSecurity([
+        'find-generic-password', '-s', service, '-a', account, '-w',
+      ]);
+      // -w prints just the password to stdout, terminated by a newline.
+      return stdout.replace(/\n$/, '');
+    } catch (err) {
+      if (_isNotFound(err)) return null;
+      throw new SecretStoreError(
+        `security find-generic-password failed: ${(err.stderr || err.message || '').trim()}`,
+        { code: 'security_cli_failed', cause: err }
+      );
+    }
+  }
+
+  async _securitySet(service, account, secret) {
+    // -U updates the existing entry if present, adds it otherwise.
+    // Note: passing the password as the last argv element is the standard
+    // pattern for non-interactive `security` use; the macOS `security` CLI
+    // exposes no stdin-only password input mode for non-interactive callers.
+    // This is the same trade-off keytar's own native binding makes — the
+    // password lives in process memory until the syscall completes.
+    try {
+      await this._execSecurity([
+        'add-generic-password', '-U', '-s', service, '-a', account, '-w', secret,
+      ]);
+    } catch (err) {
+      throw new SecretStoreError(
+        `security add-generic-password failed: ${(err.stderr || err.message || '').trim()}`,
+        { code: 'security_cli_failed', cause: err }
+      );
+    }
+  }
+
+  async _securityDelete(service, account) {
+    try {
+      await this._execSecurity([
+        'delete-generic-password', '-s', service, '-a', account,
+      ]);
+      return true;
+    } catch (err) {
+      if (_isNotFound(err)) return false;
+      throw new SecretStoreError(
+        `security delete-generic-password failed: ${(err.stderr || err.message || '').trim()}`,
+        { code: 'security_cli_failed', cause: err }
+      );
+    }
+  }
+}
+
+/**
+ * Detect the macOS `security` CLI's "entry not found" condition. Stderr from
+ * `find-generic-password` / `delete-generic-password` against a missing entry
+ * looks like:
+ *   security: SecKeychainSearchCopyNext: The specified item could not be
+ *   found in the keychain.
+ * Match on the substring "could not be found" (case-insensitive) to map it
+ * to keytar's null/false return semantics.
+ */
+function _isNotFound(err) {
+  const stderr = (err && err.stderr) || '';
+  return /could not be found/i.test(stderr);
 }
 
 module.exports = { KeychainSecretStore };

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/config-store.js

@@ -6,8 +6,12 @@ const os = require('node:os');
 
 const { SCHEMA_VERSION, validate, emptyConfig } = require('../auth/schema-v2');
 const { _atomicWrite } = require('../auth/config-migration');
+const { AUTH_STATUS } = require('../auth/events');
+const { makeRef } = require('../auth/secret-store');
 const { CliError, EXIT_CONFIG } = require('./errors');
 
+const SECRET_SERVICE = 'abilities-mcp';
+
 /**
  * Read / write the v2 wp-sites.json file from a CLI command.
  *
@@ -152,10 +156,173 @@ function freshConfig() {
   return emptyConfig();
 }
 
+/**
+ * Derive a site-id from a URL hostname. Mirrors `add-site`'s deriveSiteId so a
+ * `.mcpb`-seeded site collides with a CLI-added entry for the same host (the
+ * file-absence guard in `seedFromEnvIfMissing` prevents the collision in
+ * practice; the parity matters for `upgrade-auth <site-id>` to be intuitive).
+ *
+ * @param {string} siteUrl
+ * @returns {string|null}  Site-id or null if URL is unparseable.
+ */
+function deriveSiteId(siteUrl) {
+  let host;
+  try { host = new URL(siteUrl).hostname; }
+  catch { return null; }
+  const trimmed = host.replace(/^www\./, '');
+  const dot = trimmed.indexOf('.');
+  return dot > 0 ? trimmed.slice(0, dot) : trimmed;
+}
+
+/**
+ * Seed wp-sites.json from env vars (`ABILITIES_MCP_URL/USERNAME/PASSWORD`)
+ * when the file doesn't yet exist. Used on first launch of the `.mcpb`
+ * extension so subsequent CLI commands (`list-sites`, `upgrade-auth`,
+ * `add-site`) operate on a single source of truth that already includes
+ * the site Claude Desktop is connected to.
+ *
+ * Behavior:
+ *  - If `configPath` already exists → no-op. Operators who manage their own
+ *    `wp-sites.json` are never overwritten.
+ *  - If keytar isn't loadable on this host (e.g. the .mcpb is somehow
+ *    running without the bundled keytar prebuild) → no-op. The bridge
+ *    falls back to env-var-only mode. Graceful degradation.
+ *  - If any of the three env vars is missing → no-op. Should not happen
+ *    in the .mcpb path (manifest user_config marks all three required) but
+ *    guards against partial env in other invocations.
+ *  - Otherwise: writes the App Password to keychain via the shared
+ *    SecretStore, builds a v2 apppassword entry shaped to pass both the
+ *    schema-v2 validator and the bridge's runtime validateSiteConfig
+ *    (matching the migration `_convertSite` pattern — preserves
+ *    `transport: 'http'` and the legacy http block alongside the v2 auth
+ *    block, with `password_ref` in both).
+ *
+ * If the keychain write succeeds but the file write fails the keychain
+ * entry is rolled back so the operator's keychain doesn't accumulate
+ * orphans on repeated failures.
+ *
+ * @param {string} configPath  Absolute path of the wp-sites.json to seed.
+ * @param {object} env         Environment shape — expects ABILITIES_MCP_URL,
+ *                             ABILITIES_MCP_USERNAME, ABILITIES_MCP_PASSWORD.
+ *                             Defaults to process.env.
+ * @param {object} [deps]
+ * @param {object} [deps.secretStore]  Inject for tests (a MemorySecretStore).
+ *                                     Defaults to a fresh KeychainSecretStore.
+ * @returns {Promise<{
+ *   seeded: boolean,
+ *   reason?: 'exists'|'missing-env-vars'|'keytar-unavailable'|'invalid-url'|'error',
+ *   siteId?: string,
+ *   configPath?: string,
+ *   error?: Error,
+ * }>}
+ */
+async function seedFromEnvIfMissing(configPath, env, deps = {}) {
+  if (!configPath) {
+    return { seeded: false, reason: 'missing-env-vars' };
+  }
+  if (fs.existsSync(configPath)) {
+    return { seeded: false, reason: 'exists' };
+  }
+
+  const url = env && env.ABILITIES_MCP_URL;
+  const username = env && env.ABILITIES_MCP_USERNAME;
+  const password = env && env.ABILITIES_MCP_PASSWORD;
+  if (!url || !username || !password) {
+    return { seeded: false, reason: 'missing-env-vars' };
+  }
+
+  let parsedUrl;
+  try { parsedUrl = new URL(url); }
+  catch { return { seeded: false, reason: 'invalid-url' }; }
+
+  const siteId = deriveSiteId(url);
+  if (!siteId) {
+    return { seeded: false, reason: 'invalid-url' };
+  }
+
+  // Lazily build a SecretStore so SSH-only / env-var-only setups never load
+  // keytar on the seed path — the no-op "missing env vars" exit above keeps
+  // them out, but keep the require deferred for symmetry with the runtime.
+  let secretStore = deps.secretStore;
+  if (!secretStore) {
+    const { KeychainSecretStore } = require('../auth/keychain-secret-store');
+    secretStore = new KeychainSecretStore();
+  }
+
+  // Probe keytar before writing. If it isn't loadable (e.g. the .mcpb
+  // somehow shipped without the bundled binary) we skip seeding — the
+  // bridge keeps working in env-var-only mode and the operator can run
+  // `abilities-mcp add-site` from a CLI install instead.
+  if (typeof secretStore.isAvailable === 'function') {
+    const available = await secretStore.isAvailable();
+    if (!available) {
+      return { seeded: false, reason: 'keytar-unavailable' };
+    }
+  }
+
+  // Build the endpoint the same way buildEnvConfig does — strip trailing
+  // slash, append the adapter route. This is the URL the runtime will hit
+  // for App-Password requests.
+  const base = (parsedUrl.origin + parsedUrl.pathname).replace(/\/+$/, '');
+  const endpoint = `${base}/wp-json/mcp/mcp-adapter-default-server`;
+  const account = `${siteId}/apppassword`;
+  const passwordRef = makeRef(SECRET_SERVICE, account);
+
+  // Write the secret to keychain first. If the file write below fails we
+  // roll this back so the keychain doesn't accumulate orphan entries on
+  // repeated seed attempts.
+  try {
+    await secretStore.set(SECRET_SERVICE, account, password);
+  } catch (err) {
+    return { seeded: false, reason: 'error', error: err };
+  }
+
+  const allowInsecure = parsedUrl.protocol === 'http:';
+  const site = {
+    label: parsedUrl.hostname,
+    url: parsedUrl.origin,
+    transport: 'http',
+    http: {
+      endpoint,
+      username,
+      password_ref: passwordRef,
+    },
+    auth: {
+      method: 'apppassword',
+      username,
+      password_ref: passwordRef,
+    },
+    auth_status: AUTH_STATUS.ACTIVE,
+  };
+  if (allowInsecure) site.allowInsecure = true;
+
+  const v2Config = {
+    $schema: 'https://wickedevolutions.com/schemas/abilities-mcp/wp-sites/v2.json',
+    schema_version: SCHEMA_VERSION,
+    defaultSite: siteId,
+    sites: { [siteId]: site },
+  };
+
+  try {
+    const dir = path.dirname(configPath);
+    await fs.promises.mkdir(dir, { recursive: true });
+    await _atomicWrite(configPath, v2Config);
+  } catch (err) {
+    // Roll back the keychain write so we don't leave an orphan secret.
+    try { await secretStore.delete(SECRET_SERVICE, account); }
+    catch { /* best-effort rollback */ }
+    return { seeded: false, reason: 'error', error: err };
+  }
+
+  return { seeded: true, siteId, configPath };
+}
+
 module.exports = {
   resolveConfigPath,
   readConfig,
   writeConfig,
   freshConfig,
+  seedFromEnvIfMissing,
+  deriveSiteId,
   HOME_DIR_REL,
 };

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/lib/config-source-line.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const os = require('os');
+
+/**
+ * Format the operator-visible startup diagnostic line that names which config
+ * source `loadConfig` resolved to and what's in it.
+ *
+ * Output goes to stderr where Claude Desktop's MCP log captures it
+ * (visible in `mcp-server-WordPress (Abilities MCP).log` on macOS), so the
+ * operator can tell at a glance:
+ *  - Whether the .mcpb extension is in env-var single-site mode or has
+ *    handed off to a home-dir wp-sites.json.
+ *  - How many sites are configured and what auth method each uses.
+ *  - Which file path or env var is the source of truth right now.
+ *
+ * Discriminants set in `lib/config.js`:
+ *  - 'explicit-config' — args.config / --config=<path>
+ *  - 'script-adjacent' — wp-sites.json next to abilities-mcp.js
+ *  - 'home-dir'        — ~/.abilities-mcp/wp-sites.json
+ *  - 'env-var'         — ABILITIES_MCP_URL injected by Claude Desktop user_config
+ *  - 'legacy-cli'      — --host / --path (mcp-ssh-bridge backward compat)
+ *
+ * The line never includes secrets — only site IDs, auth methods, hostnames,
+ * tildified file paths, and counts.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+/**
+ * Replace a leading $HOME prefix with `~/` so logs don't leak the operator's
+ * full username path. No-op for paths outside $HOME.
+ */
+function tildify(p) {
+  if (!p) return p;
+  const home = os.homedir();
+  if (home && (p === home || p.startsWith(home + '/'))) {
+    return '~' + p.slice(home.length);
+  }
+  return p;
+}
+
+/**
+ * Per-site short auth label: prefer auth.method (v2 schema), fall back to
+ * transport (v1 schema), 'unknown' if neither is set.
+ */
+function siteAuthLabel(site) {
+  if (site && site.auth && site.auth.method) return site.auth.method;
+  if (site && site.transport) return site.transport;
+  return 'unknown';
+}
+
+/**
+ * Build the Config-source line.
+ *
+ * @param {object} config  Output of `loadConfig` — must carry `_configSource`
+ *                         and `_configSourceLabel`.
+ * @returns {string}       One-line operator diagnostic, no trailing newline.
+ */
+function formatConfigSourceLine(config) {
+  const source = config && config._configSource;
+  const rawLabel = (config && config._configSourceLabel) || '';
+
+  if (source === 'env-var') {
+    const site = config.sites && config.sites[config.defaultSite];
+    const username = (site && site.http && site.http.username) || '?';
+    return `Config source: ABILITIES_MCP_URL env var (single-site basic auth: ${rawLabel} as ${username})`;
+  }
+
+  if (source === 'legacy-cli') {
+    return `Config source: --host/--path legacy CLI (single-site SSH: ${rawLabel})`;
+  }
+
+  // File-based: explicit-config / script-adjacent / home-dir
+  const label = tildify(rawLabel);
+  const siteEntries = Object.entries(config.sites || {}).map(
+    ([id, site]) => `${id} ${siteAuthLabel(site)}`
+  );
+  const sitesHeader = siteEntries.length === 1 ? '1 site' : `${siteEntries.length} sites`;
+  const sourcePrefix = source ? `[${source}] ` : '';
+  return `Config source: ${sourcePrefix}${label} (${sitesHeader}: ${siteEntries.join(', ')})`;
+}
+
+module.exports = { formatConfigSourceLine, tildify, siteAuthLabel };

package/lib/config.js

@@ -75,25 +75,39 @@ async function resolveConfigFilePath(args) {
 async function loadConfig(args) {
   // Explicit config path
   if (args.config) {
-    return loadConfigFile(args.config);
+    return loadConfigFile(args.config, 'explicit-config');
   }
 
   // Check alongside script (lib/ → package root)
   const scriptDir = path.resolve(__dirname, '..');
   const scriptConfig = path.join(scriptDir, 'wp-sites.json');
   if (await _exists(scriptConfig)) {
-    return loadConfigFile(scriptConfig);
+    return loadConfigFile(scriptConfig, 'script-adjacent');
   }
 
   // Check home directory
   const homeConfig = path.join(os.homedir(), '.abilities-mcp', 'wp-sites.json');
   if (await _exists(homeConfig)) {
-    return loadConfigFile(homeConfig);
+    return loadConfigFile(homeConfig, 'home-dir');
   }
 
   // Env-var single-site config — covers the .mcpb install path and any
   // env-var-based MCP client configuration (claude mcp add, Docker, etc.)
+  //
+  // First-launch seed (#34): if the .mcpb just installed and no home-dir
+  // wp-sites.json exists yet, seed one from the env vars so subsequent CLI
+  // commands (`list-sites`, `upgrade-auth`, `add-site`) operate on a single
+  // source of truth that already includes the site Claude Desktop is
+  // connected to. On success the bridge loads the freshly seeded file —
+  // same shape it would read on next restart — so the runtime path stays
+  // identical regardless of whether seeding just happened. On failure
+  // (keytar unavailable, file-already-exists, write error) the seed is a
+  // graceful no-op and we fall back to env-var-only mode below.
   if (process.env.ABILITIES_MCP_URL) {
+    const seedResult = await _seedFromEnvIfMissing(homeConfig, process.env);
+    if (seedResult && seedResult.seeded) {
+      return loadConfigFile(homeConfig, 'home-dir');
+    }
     return buildEnvConfig(process.env);
   }
 
@@ -173,14 +187,15 @@ function buildEnvConfig(env) {
   return {
     defaultSite: 'default',
     _isMultiSite: false,
-    _configSource: 'env',
+    _configSource: 'env-var',
+    _configSourceLabel: parsedUrl.hostname,
     sites: {
       default: siteConfig,
     },
   };
 }
 
-async function loadConfigFile(filePath) {
+async function loadConfigFile(filePath, source = 'explicit-config') {
   const raw = await fsp.readFile(filePath, 'utf8');
 
   // Warn if config file is readable by group or world
@@ -216,6 +231,8 @@ async function loadConfigFile(filePath) {
   config._isMultiSite = Object.keys(config.sites).length > 1 ||
     Object.values(config.sites).some(s => s.multisite);
   config._configPath = filePath;
+  config._configSource = source;
+  config._configSourceLabel = filePath;
 
   return config;
 }
@@ -301,6 +318,8 @@ function buildLegacyConfig(args) {
   return {
     defaultSite: 'default',
     _isMultiSite: false,
+    _configSource: 'legacy-cli',
+    _configSourceLabel: args.host,
     sites: {
       default: {
         label: args.host,
@@ -428,6 +447,17 @@ async function resolveSitePassword(site, secretStore) {
   throw new Error('No password source configured for site');
 }
 
+/**
+ * Lazy wrapper around `lib/cli/config-store.js#seedFromEnvIfMissing`. Only
+ * loads the CLI config-store + KeychainSecretStore modules when the env-var
+ * branch of `loadConfig` actually fires — so SSH-only, explicit-config, and
+ * legacy-CLI install paths never pay the keytar import cost.
+ */
+async function _seedFromEnvIfMissing(configPath, env) {
+  const { seedFromEnvIfMissing } = require('./cli/config-store');
+  return seedFromEnvIfMissing(configPath, env);
+}
+
 module.exports = {
   loadConfig,
   resolveConfigFilePath,
@@ -436,4 +466,5 @@ module.exports = {
   resolveSiteKey,
   buildSiteKeyEnum,
   buildEnvConfig,
+  validateSiteConfig,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wickedevolutions/abilities-mcp",
-  "version": "1.5.1",
+  "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": {
@@ -17,12 +17,13 @@
   "scripts": {
     "test": "node --test test/*.test.js test/auth/*.test.js test/cli/*.test.js test/transports/*.test.js",
     "validate:mcpb": "npx --yes @anthropic-ai/mcpb validate manifest.json",
-    "pack:mcpb": "npx --yes @anthropic-ai/mcpb pack . abilities-mcp.mcpb"
+    "pack:mcpb": "node scripts/pack-mcpb.js",
+    "verify:pack-isolation": "node scripts/verify-pack-isolation.js"
   },
   "engines": {
     "node": ">=18.0.0"
   },
   "optionalDependencies": {
-    "keytar": "^7.9.0"
+    "keytar": "~7.9.0"
   }
 }