@wickedevolutions/abilities-mcp 1.3.1 → 1.5.3

package/CHANGELOG.md

@@ -2,6 +2,117 @@
 
 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.
+
+Companion releases: [abilities-mcp-adapter v1.4.4](https://github.com/Wicked-Evolutions/abilities-mcp-adapter/releases/tag/v1.4.4) and [abilities-for-ai v1.9.1](https://github.com/Wicked-Evolutions/abilities-for-ai/releases/tag/v1.9.1) — coordinated multi-repo release per the Stretch to Stable sprint plan.
+
+### Fixed
+
+- **Schema v1→v2 auto-migration is now actually wired into boot** (PR #25, closes #23). `migrateFile()` shipped in v1.5.0 but the Phase 4/5 OAuth handoff missed the call sites — the migration code existed but never ran. Now invoked at two points before any consumer touches the config: (a) in `abilities-mcp.js` startup before the MCP server reads `wp-sites.json`, and (b) in `lib/cli/index.js`'s `runCommand()` before any subcommand parses the file. Both call sites share a single `KeychainSecretStore` instance. CLI subcommands no longer error with `v<unknown> but CLI expects v2` against legacy v1 configs; the OAuth `add-site` / `upgrade-auth` flows can reach the auth code path on a fresh install. Idempotent — second-run on an already-v2 file is a no-op.
+- **Post-migration v2 apppassword sites validate and connect** (PR #27, closes #26). Helena's Phase B run surfaced a regression: when PR #25's wired migration converted a multi-site v1 config to v2, every non-OAuth site moved to `auth.method: 'apppassword'` with `auth.password_ref`, and the legacy `http.password` / `http.passwordEnv` / `http.passwordCommand` fields were stripped per Appendix F.5 — keychain becomes the sole source of truth. The runtime side still spoke v1 only: `validateSiteConfig()` had no apppassword branch, so v2 sites fell through to the legacy http validator which rejected them with `requires one of http.password, http.passwordEnv, or http.passwordCommand`, and `ConnectionPool._createTransport` had no resolver for `auth.password_ref`. Two parallel branches added (validator + async `resolveSitePassword(site, secretStore)` helper that reads keychain via the SecretStore), pool dispatches on `auth.method === 'apppassword'`, and `KeychainSecretStore` is constructed lazily so SSH-only / v1-only setups still avoid loading keytar. Multi-site acceptance test (1 oauth + 2 apppassword + 1 ssh-carrier) pins the routing.
+
+### Changed
+
+- **Async config loading** (PR #28, closes #5). The boot chain — `resolveConfigFilePath`, `loadConfig`, `loadConfigFile`, `validateSiteConfig`, `resolvePassword` — is async. File reads use `fs.promises`; the `passwordCommand` shell-out goes through `util.promisify(exec)` rather than `execFile` so existing operator configs that rely on shell features (pipes, redirects, `$()` substitution — e.g. `op read 'op://Vault/foo' | tr -d '\n'`) keep working unchanged. `loadConfig` now returns a `Promise`; `abilities-mcp.js`'s bootstrap awaits it (the IIFE was already async per the migration wiring above). Pure-dispatch helpers (`resolveSiteKey`, `buildSiteKeyEnum`, `buildEnvConfig`, `buildLegacyConfig`) stayed synchronous — they have no I/O and converting them would touch every call site for no runtime benefit.
+
+### Internal
+
+- Test count: 237 (+27 since 1.5.0). Node CI matrix: 18, 20, 22.
+- Validator coverage extended: 8 acceptance/reject cases for v2 apppassword (http and ssh carriers, hand-edited reject paths), 9 cases for the async surface (`loadConfig` Promise return, `resolveConfigFilePath` async, `resolvePassword` env / command / shell-feature regression).
+
+## [1.5.0] - 2026-04-28
+
+OAuth 2.1 release. The bridge is now a full OAuth client: it discovers the authorization server via RFC 9728, performs Dynamic Client Registration (RFC 7591), drives the authorization-code grant with PKCE S256 (RFC 7636) through a loopback browser flow (RFC 8252), persists tokens in the OS keychain, refreshes them automatically, and sends Bearer tokens through the runtime MCP transport.
+
+Companion release: [abilities-mcp-adapter v1.4.3](https://github.com/Wicked-Evolutions/abilities-mcp-adapter/releases/tag/v1.4.3) — the OAuth resource server + authorization server.
+
+### Added — OAuth 2.1 client core (#15)
+
+- **`lib/auth/` module** — full OAuth 2.1 client: `oauth-client.js` (state machine), `discovery-client.js` (RFC 9728 + RFC 8414, refuses HTTP, refuses redirects on `.well-known/*`, throws `CapabilityPinningError` on pinned 404), `dcr-client.js` (RFC 7591), `pkce.js` (32-byte verifier, S256, 16-byte hex state, `crypto.timingSafeEqual` with length-mismatch CPU-burn defense), `loopback-server.js` (RFC 8252 loopback callback), `browser-launcher.js` (cross-platform `open`), `token-manager.js` (refresh window, retry semantics, expired/revoked state machine).
+- **`SecretStore` interface** — three implementations: `keychain-secret-store.js` (libsecret on Linux, Keychain on macOS, Credential Manager on Windows), `memory-secret-store.js` (testing), `secret-store.js` (interface). All token persistence flows through this interface.
+- **`BridgeIdentityProvider` interface** + **`FreshEachTimeIdentityProvider`** (v1.0 implementation per Appendix H.3.2 binding amendment): `getClientId()` always returns null → fresh DCR on every flow. `persistClientId()` is a documented no-op pending v1.1's persistent-identity upgrade contract.
+- **`schema-v2.js`** — keychain references replace inline secrets in `wp-sites.json`. `schema_version: 2` with `auth.method`, `access_token_ref`, `refresh_token_ref`, `oauth_capability_pinned`, `apppassword_fallback`. `config-migration.js` upgrades v1 configs in place.
+- **`OAuthHttpTransport`** (#18) — runtime transport that uses `TokenManager.getAccessToken()` before each request, builds `Authorization: Bearer ...`, handles 401 → `forceRefresh` → retry-once, surfaces terminal auth failure via `onAuthStatusChange('expired')`. `ConnectionPool._create()` dispatches to this when `siteConfig.auth.method === 'oauth'`.
+
+### Added — OAuth CLI subcommands (#16)
+
+- **`abilities-mcp <subcommand>`** dispatches to eight new subcommands wrapping `lib/auth/`: the six in the sprint plan — `add-site`, `reauth`, `revoke`, `list-sites`, `test`, `upgrade-auth` — plus two design-doc extensions: `force-downgrade` (J.1, escape hatch for the H.2.3 capability-pin failure) and `self-check` (J.2, the H.2.6 Authorization-header probe). Each subcommand subscribes to the OAuth state machine and prints operator-facing progress lines. Error messages name the exact next action. Bare `node abilities-mcp.js` (no subcommand) still starts the MCP STDIO server unchanged.
+- Exit-code table (`0`/`1`/`2`/`3`/`4`/`5`) mapping success / generic / usage / config / auth / capability-pinning failures, documented in `abilities-mcp --help`.
+- `--debug` flag includes the `cause` stack on errors for troubleshooting.
+- `force-downgrade` audit lives on the site config (`force_downgrade.{at, expires_at, reason}`) and is surfaced in `list-sites` for 30 days.
+
+### Security
+
+- **H-7: removed dead refresh-intent keychain code** (#21). `TokenManager.refresh()` previously wrote a `${siteId}/refresh-intent` keychain entry before sending the refresh request and deleted it on every exit path. The marker had no reader — the original H.2.1 mid-flight crash-recovery semantics were never implemented. With the adapter's C-2 fix shipping encrypt-at-rest grace-window retry on the server (adapter PR #61), the bridge no longer needs an in-flight intent marker. Pure deletion of dead code that paid a keychain write per refresh.
+- **H-8: client_id port guard in `_runRegister`** (#22). `OAuthClient._runRegister` previously returned a persisted `client_id` from `identityProvider.getClientId()` without verifying that the registered loopback redirect_uri's port matched the live loopback port. v1.0 was safe by accident because `FreshEachTimeIdentityProvider.getClientId()` always returns null. v1.1's persistent-identity upgrade (per Appendix H.3.2) would have surfaced the bug: a stale persisted client_id whose registered port no longer matched would fail server-side `redirect_uri_valid()`. Defensive fix: `_runRegister` now always calls `identityProvider.clearClientId()` before DCR. v1.1+ designs that want to short-circuit DCR on persisted client_id must do so at the `OAuthClient.run()` level after verifying the loopback port matches the registration. See follow-up [abilities-mcp-adapter#73](https://github.com/Wicked-Evolutions/abilities-mcp-adapter/issues/73) for the spec amendment.
+
+### Internal
+
+- Test count: 210 (+34 since 1.4.0). Node CI matrix: 18, 20, 22.
+- `infra: retarget project automation` (#14) for the OAuth sprint workflow.
+
+## [1.4.0] - 2026-04-26
+
+### Added
+- `.mcpb` distribution bundle for one-click install in Claude Desktop (#8). `manifest.json` against MCPB spec v0.3, `.mcpbignore`, and `npm run pack:mcpb` script. Application Password is stored encrypted in the OS keychain via `sensitive: true`. Published as a GitHub Release asset.
+- `ABILITIES_MCP_URL` / `ABILITIES_MCP_USERNAME` / `ABILITIES_MCP_PASSWORD` environment-variable config fallback in `lib/config.js`. When no `wp-sites.json` exists, the bridge builds a single-site config from the env vars and auto-derives the MCP adapter endpoint as `<URL>/wp-json/mcp/mcp-adapter-default-server`. Covers the `.mcpb` install path and any env-var-based MCP client (`claude mcp add`, Docker, etc.).
+- `npm run validate:mcpb` — validates `manifest.json` against the MCPB schema.
+
+### Changed
+- README restructured around three install paths: `.mcpb` bundle (recommended for Claude Desktop), env-vars + npm install (Claude Code / Cursor / Docker), and `wp-sites.json` (multi-site / power users). Existing `wp-sites.json` users are unaffected.
+
 ## [1.3.1] - 2026-03-19
 
 ### Fixed

package/README.md

@@ -16,22 +16,26 @@ Open-source MCP bridge that connects any AI client to your WordPress sites throu
 
 ## What You Can Do
 
-The abilities available to your AI agent depend on which ability plugins you install. With [Abilities for AI](https://wickedevolutions.com/abilities-for-ai) installed, your agent gets access to:
+The abilities available to your AI agent depend on which ability plugins you install. With [Abilities for AI](https://community.wickedevolutions.com/item/abilities-for-ai/) installed, your agent gets access to:
 
 **Content & Publishing** — content, blocks, patterns, media, menus, taxonomies, comments, revisions
 **Site Management** — plugins, themes, settings, users, site health, cache, cron, rewrite rules
 **Infrastructure** — filesystem, meta, REST discovery, knowledge layer
 **Third-party integrations** — auto-detected modules for supported plugins (Astra, Spectra, SureCart, Presto Player, and more)
 
-Additional ability plugins extend coverage further. For example, [Abilities for Fluent Plugins](https://github.com/Wicked-Evolutions/abilities-for-fluent-plugins) adds modules for FluentCRM, Fluent Community, Fluent Forms, FluentBooking, Fluent Support, Fluent Boards, FluentSMTP, FluentAuth, Fluent Snippets, Fluent Messaging, FluentCart, and FluentAffiliate.
+**[Abilities for Fluent Plugins](https://github.com/Wicked-Evolutions/abilities-for-fluent-plugins)** is our continuously-enhanced third-party translator — bringing AI control to FluentCRM, FluentCommunity, FluentForms, FluentBooking, FluentSupport, FluentBoards, FluentSMTP, FluentAuth, FluentSnippets, FluentMessaging, FluentCart, and FluentAffiliate. We build and maintain it because we use Fluent's plugins ourselves and wanted them AI-native.
+
+Beyond Fluent, the bridge is plugin-agnostic by design. Any plugin that registers abilities through the WordPress Abilities API becomes available automatically — no configuration in this bridge required. We urge every WordPress plugin developer to prioritize native Abilities API support over anything else.
 
 Every ability enforces `current_user_can()` at execution time — your WordPress role is the security boundary.
 
-> **Sign up for the Abilities for AI alpha release:** https://wickedevolutions.com/abilities-for-ai
+> **Sign up for the Abilities for AI alpha release:** https://community.wickedevolutions.com/item/abilities-for-ai/
+
+## Install
 
-## Quick Start
+There are three install paths. Pick the one that matches how you use AI clients.
 
-### 1. Set up WordPress
+### Set up WordPress (required for all paths)
 
 Create a dedicated WordPress user for AI access and generate an Application Password.
 
@@ -59,24 +63,77 @@ Go to **Users → Edit (your mcp-agent user) → Application Passwords**, enter
 
 Install both on your WordPress site:
 
-1. **[Abilities for AI](https://wickedevolutions.com/abilities-for-ai)** — registers WordPress abilities across content, site management, infrastructure, and third-party integration modules
-2. **[Abilities MCP Adapter](https://github.com/Wicked-Evolutions/abilities-mcp-adapter)** — exposes abilities as MCP tools via REST API
+1. **[Abilities for AI](https://community.wickedevolutions.com/item/abilities-for-ai/)** — registers WordPress abilities across content, site management, infrastructure, and third-party integration modules
+2. **[Abilities MCP Adapter](https://community.wickedevolutions.com/item/abilities-mcp-adapter/)** — exposes abilities as MCP tools via REST API
+
+Both are available as free downloads from our store, or install from GitHub: [abilities-for-ai](https://github.com/Wicked-Evolutions/abilities-for-ai) and [abilities-mcp-adapter](https://github.com/Wicked-Evolutions/abilities-mcp-adapter).
+
+---
+
+### Path 1 — `.mcpb` bundle for Claude Desktop (recommended)
+
+Single-click install for Claude Desktop on macOS and Windows. The Application Password is stored encrypted in your OS keychain (macOS Keychain / Windows Credential Manager).
+
+1. Download `abilities-mcp.mcpb` from the [latest GitHub Release](https://github.com/Wicked-Evolutions/abilities-mcp/releases/latest).
+2. Double-click the file. Claude Desktop opens an "Install Extension" dialog.
+3. Type three things:
+   - **WordPress Site URL** — `https://example.com`
+   - **WordPress Username** — `mcp-agent`
+   - **Application Password** — paste the password from the previous step
+4. Click **Install**. The connection is live.
+
+The bundle covers the single-site case. For multi-site (one bridge connected to several WordPress sites at once), use Path 3.
+
+---
 
-### 2. Configure your sites
+### Path 2 — Env vars (Claude Code, Cursor, Docker, any MCP client)
 
-Copy the example config and edit:
+Install the bridge from npm, then point your client at it with three environment variables:
 
 ```bash
-cp wp-sites.example.json wp-sites.json
+npm install -g @wickedevolutions/abilities-mcp
+```
+
+In your client's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "wordpress": {
+      "command": "abilities-mcp",
+      "env": {
+        "ABILITIES_MCP_URL": "https://example.com",
+        "ABILITIES_MCP_USERNAME": "mcp-agent",
+        "ABILITIES_MCP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
+      }
+    }
+  }
+}
 ```
 
-Edit `wp-sites.json` with your site details.
+The endpoint is auto-derived as `<URL>/wp-json/mcp/mcp-adapter-default-server`. Single-site only — for multi-site, use Path 3.
+
+For `claude mcp add` users:
+
+```bash
+claude mcp add wordpress \
+  --env ABILITIES_MCP_URL=https://example.com \
+  --env ABILITIES_MCP_USERNAME=mcp-agent \
+  --env ABILITIES_MCP_PASSWORD='xxxx xxxx xxxx xxxx xxxx xxxx' \
+  -- abilities-mcp
+```
+
+---
+
+### Path 3 — `wp-sites.json` (multi-site, power users)
 
-### 3. Add to your MCP client
+Use this when you connect one bridge to multiple WordPress sites, when you want passwords sourced from a keychain or shell command, or when you're targeting WordPress multisite networks via dot-notation routing.
 
-Works with any MCP-compatible client — Claude Code, Claude Desktop, Gemini CLI, Cursor, Windsurf, VS Code, and any other IDE or AI tool that supports the Model Context Protocol.
+```bash
+cp wp-sites.example.json wp-sites.json
+```
 
-Add the server to your client's MCP config (usually `.mcp.json`, `settings.json`, or equivalent):
+Edit `wp-sites.json` with your sites, then add the server to your client's MCP config:
 
 ```json
 {
@@ -126,11 +183,15 @@ node abilities-mcp.js --register
 }
 ```
 
-### Config file search order
+### Config search order
 
 1. `--config=/path/to/wp-sites.json` (explicit)
-2. Same directory as `abilities-mcp.js`
+2. `wp-sites.json` in the same directory as `abilities-mcp.js`
 3. `~/.abilities-mcp/wp-sites.json`
+4. `ABILITIES_MCP_URL` / `ABILITIES_MCP_USERNAME` / `ABILITIES_MCP_PASSWORD` env vars (single-site, used by the `.mcpb` bundle)
+5. `--host=<ssh-host> --path=<wp-path>` (legacy SSH single-site)
+
+The first one found wins. If a `wp-sites.json` exists, env vars are ignored.
 
 ### WordPress Multisite
 
@@ -313,9 +374,19 @@ See [docs/architecture.md](docs/architecture.md) for the full technical deep div
 ## Requirements
 
 - Node.js >= 18
-- WordPress 6.9+ with [Abilities for AI](https://wickedevolutions.com/abilities-for-ai) and [Abilities MCP Adapter](https://github.com/Wicked-Evolutions/abilities-mcp-adapter) installed
+- WordPress 6.9+ with [Abilities for AI](https://community.wickedevolutions.com/item/abilities-for-ai/) and [Abilities MCP Adapter](https://github.com/Wicked-Evolutions/abilities-mcp-adapter) installed
 - Application Passwords enabled (default in WordPress 5.6+)
 
+## Evolving Knowledge
+
+We continuously add knowledge docs, skills, and agent patterns to [knowledge.wickedevolutions.com](https://knowledge.wickedevolutions.com).
+
+## Disclaimer
+
+Humans make mistakes — as we know from the present day and history. Humans trained AI. AI acts accordingly. AI predicts probability based on the context window it holds. It is trained to sound certain, as if everything is truth, and to "fix" everything so the human becomes satisfied.
+
+Learn how to communicate with AI. You are fully responsible for using AI in your life, business, and projects. Using these products is your personal responsibility to learn and own.
+
 ## License
 
 GPL-2.0-or-later

package/abilities-mcp.js

@@ -23,147 +23,224 @@
 'use strict';
 
 const { createLogger } = require('./lib/logger');
-const { loadConfig, buildSiteKeyEnum } = require('./lib/config');
+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');
 const { SshTransport } = require('./lib/transports/ssh-transport');
+const { migrateFile } = require('./lib/auth/config-migration');
+const { KeychainSecretStore } = require('./lib/auth/keychain-secret-store');
 
 // ---------------------------------------------------------------------------
-// CLI argument parsing
+// Subcommand routing (Phase 5 OAuth CLI)
 // ---------------------------------------------------------------------------
+// `abilities-mcp <subcommand>` (e.g. add-site, list-sites) dispatches to the
+// OAuth CLI in lib/cli/. With no subcommand the bridge starts the MCP server
+// as before — this preserves backwards compatibility for every existing
+// invocation path (Claude Desktop, .mcpb bundle, bare `node abilities-mcp.js`).
+const { isKnownSubcommand, runCommand, HELP_TEXT, isHelpToken } = require('./lib/cli');
 
-const args = {};
-process.argv.slice(2).forEach(arg => {
-  if (arg.startsWith('--')) {
-    const [key, ...rest] = arg.slice(2).split('=');
-    args[key] = rest.length ? rest.join('=') : true;
-  }
-});
-
-const debug    = !!args.debug;
-const register = !!args.register;
-
-// ---------------------------------------------------------------------------
-// Registration mode (--register)
-// ---------------------------------------------------------------------------
+const rawArgs = process.argv.slice(2);
+const firstToken = rawArgs[0];
 
-if (register) {
-  const { registerClaudeDesktop } = require('./lib/register');
-  registerClaudeDesktop({ name: args.name || 'wordpress', configPath: args.config });
+if (firstToken && isHelpToken(firstToken)) {
+  process.stdout.write(HELP_TEXT.join('\n') + '\n');
   process.exit(0);
 }
 
+const isSubcommandInvocation = firstToken && isKnownSubcommand(firstToken);
+
+if (isSubcommandInvocation) {
+  (async () => {
+    try {
+      const { exitCode, lines, errLines } = await runCommand({
+        subcommand: firstToken,
+        argv: rawArgs.slice(1),
+      });
+      if (lines.length) process.stdout.write(lines.join('\n') + '\n');
+      if (errLines.length) process.stderr.write(errLines.join('\n') + '\n');
+      process.exit(exitCode);
+    } catch (err) {
+      // Last-resort safety net — runCommand normally catches everything.
+      process.stderr.write(`abilities-mcp: ${err.message}\n`);
+      process.exit(1);
+    }
+  })();
+}
+
 // ---------------------------------------------------------------------------
-// Initialize
+// MCP server mode — the original CLI argument parsing (no subcommand).
+// Skipped when a subcommand was dispatched above; otherwise we'd race the
+// IIFE's process.exit() against the bootstrap that awaits loadConfig() and
+// connectDefault().
 // ---------------------------------------------------------------------------
 
-const log = createLogger(debug);
-log('abilities-mcp v1.0.0 starting');
-
-// Ensure SSH agent is available (macOS launchd discovery)
-SshTransport.ensureSshAuthSock();
+if (!isSubcommandInvocation) {
+  const args = {};
+  rawArgs.forEach(arg => {
+    if (arg.startsWith('--')) {
+      const [key, ...rest] = arg.slice(2).split('=');
+      args[key] = rest.length ? rest.join('=') : true;
+    }
+  });
 
-let config;
-try {
-  config = loadConfig(args);
-} catch (err) {
-  process.stderr.write(`abilities-mcp: ${err.message}\n`);
-  process.exit(1);
-}
+  const debug    = !!args.debug;
+  const register = !!args.register;
 
-const isMultiSite = config._isMultiSite;
-const siteKeys = buildSiteKeyEnum(config);
-log(`Config loaded: ${siteKeys.length} site(s): ${siteKeys.join(', ')} (default: ${config.defaultSite})`);
-log(`Multi-site mode: ${isMultiSite}`);
+  if (register) {
+    const { registerClaudeDesktop } = require('./lib/register');
+    registerClaudeDesktop({ name: args.name || 'wordpress', configPath: args.config });
+    process.exit(0);
+  }
 
-const pool = new ConnectionPool(config, log);
-const catalog = new ToolCatalog(config, log);
+  const log = createLogger(debug);
+  log('abilities-mcp v1.0.0 starting');
+
+  // Ensure SSH agent is available (macOS launchd discovery)
+  SshTransport.ensureSshAuthSock();
+
+  // -------------------------------------------------------------------------
+  // Async startup — schema v1→v2 migration must complete BEFORE loadConfig.
+  // -------------------------------------------------------------------------
+  // Per Appendix F.5 (binding): the migration is "Triggered on first bridge
+  // launch after upgrade. One-shot, non-destructive." `migrateFile` is
+  // idempotent — second-run on a v2 file is a no-op. Called before
+  // `loadConfig` so that when v1 is on disk, `loadConfig` reads the freshly
+  // rewritten v2 file (with secrets lifted into the keychain).
+  //
+  // The MCP server uses a fresh `KeychainSecretStore` instance here. The
+  // store is a stateless wrapper over keytar — entry identity is determined
+  // entirely by (service, account), so a freshly constructed instance writes
+  // to the same keychain entries the runtime/CLI later read.
+  //
+  // Env-var single-site mode (.mcpb path) and legacy --host/--path mode have
+  // no on-disk wp-sites.json; `resolveConfigFilePath` returns null and we
+  // skip migration entirely.
+  (async function bootstrap() {
+    const filePath = await resolveConfigFilePath(args);
+    if (filePath) {
+      try {
+        const result = await migrateFile({
+          filePath,
+          secretStore: new KeychainSecretStore(),
+        });
+        if (result.migrated) {
+          log(`Migrated wp-sites.json v1 → v2 (${result.liftedCount} secret(s) lifted; backup: ${result.backupPath})`);
+        }
+      } catch (err) {
+        process.stderr.write(`abilities-mcp: schema migration failed: ${err.message}\n`);
+        process.exit(1);
+      }
+    }
 
-if (catalog.isEnabled()) {
-  log('Tool filtering enabled');
-} else {
-  log('Tool filtering disabled (no toolFilter in config or enabled: false)');
-}
+    let config;
+    try {
+      config = await loadConfig(args);
+    } catch (err) {
+      process.stderr.write(`abilities-mcp: ${err.message}\n`);
+      process.exit(1);
+    }
 
-function sendToClient(data) {
-  process.stdout.write(data + '\n');
-}
+    // 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})`);
+    log(`Multi-site mode: ${isMultiSite}`);
+
+    const pool = new ConnectionPool(config, log);
+    const catalog = new ToolCatalog(config, log);
+
+    if (catalog.isEnabled()) {
+      log('Tool filtering enabled');
+    } else {
+      log('Tool filtering disabled (no toolFilter in config or enabled: false)');
+    }
 
-const router = new McpRouter({
-  config,
-  siteKeys,
-  isMultiSite,
-  pool,
-  catalog,
-  sendToClient,
-  log,
-});
+    function sendToClient(data) {
+      process.stdout.write(data + '\n');
+    }
 
-// ---------------------------------------------------------------------------
-// Client STDIO processing
-// ---------------------------------------------------------------------------
+    const router = new McpRouter({
+      config,
+      siteKeys,
+      isMultiSite,
+      pool,
+      catalog,
+      sendToClient,
+      log,
+    });
 
-let inputBuffer = '';
+    // -----------------------------------------------------------------------
+    // Client STDIO processing
+    // -----------------------------------------------------------------------
+
+    let inputBuffer = '';
+
+    process.stdin.on('data', (chunk) => {
+      inputBuffer += chunk.toString();
+
+      let newlineIdx;
+      while ((newlineIdx = inputBuffer.indexOf('\n')) !== -1) {
+        const line = inputBuffer.slice(0, newlineIdx);
+        inputBuffer = inputBuffer.slice(newlineIdx + 1);
+        if (line.trim()) {
+          let msg;
+          try {
+            msg = JSON.parse(line.trim());
+          } catch (e) {
+            log(`Non-JSON from client (dropped): ${line.substring(0, 200)}`);
+            continue;
+          }
+          router.handleClientMessage(msg, line.trim());
+        }
+      }
+    });
 
-process.stdin.on('data', (chunk) => {
-  inputBuffer += chunk.toString();
+    process.stdin.on('end', () => {
+      log('Client stdin closed — shutting down');
+      shutdown();
+    });
 
-  let newlineIdx;
-  while ((newlineIdx = inputBuffer.indexOf('\n')) !== -1) {
-    const line = inputBuffer.slice(0, newlineIdx);
-    inputBuffer = inputBuffer.slice(newlineIdx + 1);
-    if (line.trim()) {
-      let msg;
-      try {
-        msg = JSON.parse(line.trim());
-      } catch (e) {
-        log(`Non-JSON from client (dropped): ${line.substring(0, 200)}`);
-        continue;
-      }
-      router.handleClientMessage(msg, line.trim());
+    // -----------------------------------------------------------------------
+    // Startup — connect to default site
+    // -----------------------------------------------------------------------
+
+    try {
+      const transport = await pool.connectDefault((parsedMsg, rawLine) => {
+        router.handleTransportMessage(parsedMsg, rawLine);
+      });
+      router.setDefaultTransport(transport);
+      log(`Default transport connected: ${config.defaultSite}`);
+      router.drainEarlyQueue();
+    } catch (err) {
+      process.stderr.write(`abilities-mcp: Failed to connect to default site: ${err.message}\n`);
+      process.exit(1);
     }
-  }
-});
 
-process.stdin.on('end', () => {
-  log('Client stdin closed — shutting down');
-  shutdown();
-});
-
-// ---------------------------------------------------------------------------
-// Startup — connect to default site
-// ---------------------------------------------------------------------------
+    // -----------------------------------------------------------------------
+    // Signal handling
+    // -----------------------------------------------------------------------
+
+    function shutdown() {
+      log('Shutting down');
+      pool.shutdownAll().then(() => {
+        process.exit(0);
+      }).catch(() => {
+        process.exit(1);
+      });
+    }
 
-(async function main() {
-  try {
-    const transport = await pool.connectDefault((parsedMsg, rawLine) => {
-      router.handleTransportMessage(parsedMsg, rawLine);
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+    process.on('unhandledRejection', (reason) => {
+      log(`Unhandled rejection: ${reason}`);
     });
-    router.setDefaultTransport(transport);
-    log(`Default transport connected: ${config.defaultSite}`);
-    router.drainEarlyQueue();
-  } catch (err) {
-    process.stderr.write(`abilities-mcp: Failed to connect to default site: ${err.message}\n`);
-    process.exit(1);
-  }
-})();
-
-// ---------------------------------------------------------------------------
-// Signal handling
-// ---------------------------------------------------------------------------
-
-function shutdown() {
-  log('Shutting down');
-  pool.shutdownAll().then(() => {
-    process.exit(0);
-  }).catch(() => {
-    process.exit(1);
-  });
+  })();
 }
-
-process.on('SIGTERM', shutdown);
-process.on('SIGINT', shutdown);
-process.on('unhandledRejection', (reason) => {
-  log(`Unhandled rejection: ${reason}`);
-});