@wickedevolutions/abilities-mcp 1.5.1 → 1.5.3

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 All notable changes to Abilities MCP are documented here.
 
+## [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/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/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.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": {
@@ -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"
   }
 }