@icoretech/warden-mcp 0.1.16 → 0.1.18

package/README.md

@@ -62,12 +62,14 @@ BW_BIN=/absolute/path/to/bw npx -y @icoretech/warden-mcp@latest
 `warden-mcp` intentionally bundles a vetted `@bitwarden/cli` version instead of
 blindly following the newest upstream CLI on every release. New `bw` releases
 can change login and unlock behavior in ways that break automation, so `bw`
-upgrades should be smoke-tested against real Vaultwarden and Bitwarden flows
-before bumping the bundled version.
+upgrades should be smoke-tested against real Vaultwarden flows before bumping
+the bundled version. Official Bitwarden compatibility is intended, but it is
+not continuously proven in CI without a real Bitwarden tenant.
 
-This repository's compose smoke now exercises both username/password auth and
-user API-key auth against a real local Vaultwarden so `@bitwarden/cli` bumps do
-not rely on unit coverage alone.
+This repository's compose smoke now exercises both direct `bw` auth flows and
+the MCP/SDK layers with username/password auth plus user API-key auth against a
+real local Vaultwarden, so `@bitwarden/cli` bumps do not rely on unit coverage
+alone.
 
 ## Install And Run
 
@@ -456,7 +458,8 @@ Run integration tests:
 make test
 ```
 
-`make test` now runs both compose-backed auth paths:
+`make test` now runs both compose-backed auth paths and verifies them at the
+raw CLI plus MCP/SDK layers:
 
 - user/password login from `.env.test`
 - api-key login from `tmp/vaultwarden-bootstrap/apikey.env`, generated by the bootstrap step and kept out of git via `tmp/`

package/bin/patch-bitwarden-cli.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = resolve(__dirname, '..');
+const cliPackageDir = resolve(__dirname, '../node_modules/@bitwarden/cli');
+
+if (!existsSync(cliPackageDir)) {
+  process.exit(0);
+}
+
+const patchPackageEntrypoint = require.resolve('patch-package/dist/index.js');
+const result = spawnSync(process.execPath, [patchPackageEntrypoint], {
+  cwd: rootDir,
+  stdio: 'inherit',
+});
+
+if (result.error) {
+  console.error(
+    `[warden-mcp] failed to execute patch-package: ${result.error.message}`,
+  );
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/bin/warden-mcp.js

@@ -2,50 +2,21 @@
 
 // bin/warden-mcp.js — CLI entry for @icoretech/warden-mcp
 
-import { spawnSync } from 'node:child_process';
-import { accessSync, constants, existsSync, readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
+import { existsSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// Resolve bw binary: optional dep → system PATH
-if (!process.env.BW_BIN) {
-  try {
-    const require = createRequire(import.meta.url);
-    const { resolveBundledBwCandidate } = await import(
-      resolve(__dirname, '../dist/bw/resolveBwBin.js')
-    );
-    const pkgManifest = require.resolve('@bitwarden/cli/package.json');
-    const pkgJson = JSON.parse(readFileSync(pkgManifest, 'utf8'));
-    const candidate = resolveBundledBwCandidate(pkgManifest, pkgJson.bin);
-    if (existsSync(candidate)) {
-      try {
-        accessSync(candidate, constants.X_OK);
-        process.env.BW_BIN = candidate;
-      } catch {
-        // Not executable — fall through to system bw
-      }
-    }
-  } catch {
-    // @bitwarden/cli optional dep not installed — fall through to system bw
-  }
-}
-
-// Verify bw is available (either from optional dep or system PATH)
-if (!process.env.BW_BIN) {
-  const probe = spawnSync('bw', ['--version'], { encoding: 'utf8' });
-  if (probe.error) {
-    console.error(
-      '[warden-mcp] ERROR: bw CLI not found.\n' +
-        'Install it with:  npm install -g @bitwarden/cli\n' +
-        'Or set the BW_BIN environment variable to the path of the bw binary.',
-    );
-    process.exit(1);
-  }
-  // System bw is available — bwCli.ts will find it via PATH
+const startupPath = resolve(__dirname, '../dist/startup/bwStartup.js');
+if (!existsSync(startupPath)) {
+  console.error(
+    '[warden-mcp] ERROR: dist/startup/bwStartup.js not found. Run `npm run build` first.',
+  );
+  process.exit(1);
 }
+const { prepareBwStartup } = await import(startupPath);
+prepareBwStartup(process.env);
 
 // Delegate to the compiled server entry, forwarding all arguments.
 const serverPath = resolve(__dirname, '../dist/server.js');

package/dist/bw/bwCli.js

@@ -1,5 +1,6 @@
 // src/bw/bwCli.ts
 import { spawn } from 'node:child_process';
+import { resolveBundledBwBin } from './resolveBwBin.js';
 export class BwCliError extends Error {
     exitCode;
     stdout;
@@ -13,7 +14,7 @@ export class BwCliError extends Error {
     }
 }
 export async function runBw(args, opts = {}) {
-    const bwBin = process.env.BW_BIN ?? 'bw';
+    const bwBin = process.env.BW_BIN ?? resolveBundledBwBin() ?? 'bw';
     // Ensure the CLI never blocks waiting for a prompt (e.g. master password).
     // This is critical for running as an MCP server / in test automation.
     const injectNoInteraction = opts.noInteraction ?? true;
@@ -80,7 +81,14 @@ export async function runBw(args, opts = {}) {
         }, timeoutMs);
     });
     const completed = new Promise((resolve, reject) => {
-        child.on('error', reject);
+        child.on('error', (error) => {
+            const safeCmd = `${bwBin} ${safeRenderedArgs(finalArgs)}`;
+            if (error.code === 'ENOENT') {
+                reject(new Error(`bw CLI not available for ${safeCmd}. Install @bitwarden/cli or set BW_BIN to a valid bw binary.`));
+                return;
+            }
+            reject(new Error(`Failed to start ${safeCmd}: ${error.message}`));
+        });
         child.on('close', (code) => {
             if (timeout)
                 clearTimeout(timeout);

package/dist/bw/bwSession.js

@@ -3,6 +3,11 @@ import { rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { runBw } from './bwCli.js';
 import { Mutex } from './mutex.js';
+const POST_LOGIN_UNLOCK_RETRY_ATTEMPTS = 20;
+const POST_LOGIN_UNLOCK_RETRY_DELAY_MS = 2_000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function requiredEnv(name) {
     const v = process.env[name];
     if (!v) {
@@ -145,6 +150,19 @@ export class BwSessionManager {
             env: this.baseEnv(opts.env),
         });
     }
+    async resetCliProfile() {
+        this.session = null;
+        this.templateItem = null;
+        this.configuredHost = null;
+        await runBw(['logout'], { env: this.baseEnv(), timeoutMs: 30_000 }).catch(() => { });
+        const home = this.homeDir;
+        await rm(join(home, '.config', 'Bitwarden CLI', 'data.json'), {
+            force: true,
+        }).catch(() => { });
+        await rm(join(home, '.config', 'Bitwarden CLI', 'config.json'), {
+            force: true,
+        }).catch(() => { });
+    }
     async ensureUnlockedInternal() {
         // Ensure server config points to BW_HOST.
         await this.ensureServerConfigured();
@@ -188,7 +206,7 @@ export class BwSessionManager {
                         timeoutMs: 60_000,
                         noInteraction: false,
                     });
-                    return stdout.trim();
+                    return { completed: true, session: stdout.trim() };
                 }
                 const { stdout } = await runBw([
                     'login',
@@ -197,19 +215,47 @@ export class BwSessionManager {
                     'BW_PASSWORD',
                     '--raw',
                 ], { env: unlockEnv, timeoutMs: 60_000, noInteraction: false });
-                return stdout.trim();
+                return { completed: true, session: stdout.trim() };
             }
             catch {
-                return '';
+                return { completed: false, session: '' };
             }
         };
-        // Prefer unlocking first (works when already logged in). If it yields an empty
-        // stdout on exit=0 (observed in some bw builds), fall back to login --raw.
-        let session = await tryUnlock();
-        if (!session)
-            session = await tryLoginRaw();
-        if (!session)
-            session = await tryUnlock();
+        const retryUnlockAfterLogin = async () => {
+            for (let attempt = 0; attempt < POST_LOGIN_UNLOCK_RETRY_ATTEMPTS; attempt += 1) {
+                const session = await tryUnlock();
+                if (session)
+                    return session;
+                if (attempt < POST_LOGIN_UNLOCK_RETRY_ATTEMPTS - 1) {
+                    await sleep(POST_LOGIN_UNLOCK_RETRY_DELAY_MS);
+                }
+            }
+            return '';
+        };
+        const obtainSession = async () => {
+            // Prefer unlocking first (works when already logged in). If it yields an
+            // empty stdout on exit=0 (observed in some bw builds), fall back to
+            // login --raw.
+            let session = await tryUnlock();
+            if (!session) {
+                const login = await tryLoginRaw();
+                if (login.session) {
+                    session = login.session;
+                }
+                else if (login.completed) {
+                    session = await retryUnlockAfterLogin();
+                }
+            }
+            if (!session)
+                session = await tryUnlock();
+            return session;
+        };
+        let session = await obtainSession();
+        if (!session) {
+            await this.resetCliProfile();
+            await this.ensureServerConfigured();
+            session = await obtainSession();
+        }
         if (!session)
             throw new Error('bw login/unlock returned an empty session');
         this.session = session;
@@ -231,13 +277,7 @@ export class BwSessionManager {
         catch {
             // If the CLI data is corrupt/out-of-sync, wiping config is the fastest recovery.
         }
-        const home = this.homeDir;
-        await rm(join(home, '.config', 'Bitwarden CLI', 'data.json'), {
-            force: true,
-        }).catch(() => { });
-        await rm(join(home, '.config', 'Bitwarden CLI', 'config.json'), {
-            force: true,
-        }).catch(() => { });
+        await this.resetCliProfile();
         await runBw(['config', 'server', this.env.host], {
             env: this.baseEnv(),
             timeoutMs: 30_000,

package/dist/bw/resolveBwBin.js

@@ -1,3 +1,5 @@
+import { accessSync, constants, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 export function resolveBundledBwCandidate(pkgManifestPath, pkgBin) {
     const pkgDir = dirname(pkgManifestPath);
@@ -8,3 +10,15 @@ export function resolveBundledBwCandidate(pkgManifestPath, pkgBin) {
             : 'dist/bw';
     return join(pkgDir, binEntry);
 }
+export function resolveBundledBwBin(resolvePackage = createRequire(import.meta.url).resolve) {
+    try {
+        const pkgManifestPath = resolvePackage('@bitwarden/cli/package.json');
+        const pkgJson = JSON.parse(readFileSync(pkgManifestPath, 'utf8'));
+        const candidate = resolveBundledBwCandidate(pkgManifestPath, pkgJson.bin);
+        accessSync(candidate, constants.X_OK);
+        return candidate;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/sdk/keychainSdk.js

@@ -168,8 +168,85 @@ export class KeychainSdk {
     maybeRedact(value, reveal) {
         return (reveal ? value : redactItem(value));
     }
-    valueResult(value, revealed) {
-        return { value, revealed };
+    valueResult(value, revealed, extra) {
+        return { value, revealed, ...(extra ?? {}) };
+    }
+    extractLoginTotp(item) {
+        if (!item || typeof item !== 'object')
+            return null;
+        const login = item.login;
+        if (!login || typeof login !== 'object')
+            return null;
+        const totp = login.totp;
+        return typeof totp === 'string' && totp.trim().length > 0 ? totp : null;
+    }
+    computeTotpMetadata(rawTotp, nowMs = Date.now()) {
+        if (!rawTotp)
+            return { period: null, timeLeft: null };
+        let period = 30;
+        if (rawTotp.startsWith('otpauth://')) {
+            try {
+                const parsed = new URL(rawTotp);
+                const candidate = Number.parseInt(parsed.searchParams.get('period') ?? '', 10);
+                if (Number.isFinite(candidate) && candidate > 0) {
+                    period = candidate;
+                }
+            }
+            catch {
+                return { period: null, timeLeft: null };
+            }
+        }
+        const elapsed = Math.floor(nowMs / 1000) % period;
+        return {
+            period,
+            timeLeft: elapsed === 0 ? period : period - elapsed,
+        };
+    }
+    candidateMatchesTerm(item, terms) {
+        const id = item.id;
+        const name = item.name;
+        const login = item.login && typeof item.login === 'object'
+            ? item.login
+            : null;
+        const username = login?.username;
+        return terms.some((term) => id === term || name === term || username === term);
+    }
+    async resolveTotpConfigForSession(session, term) {
+        const direct = await this.bw
+            .runForSession(session, ['get', 'item', term], { timeoutMs: 60_000 })
+            .then(({ stdout }) => this.parseBwJson(stdout))
+            .catch(() => null);
+        const directTotp = this.extractLoginTotp(direct);
+        if (directTotp)
+            return directTotp;
+        const tokens = term
+            .split('|')
+            .map((token) => token.trim())
+            .filter((token) => token.length > 0);
+        const terms = tokens.length ? tokens : [term];
+        const byId = new Map();
+        for (const searchTerm of terms) {
+            const { stdout } = await this.bw.runForSession(session, ['list', 'items', '--search', searchTerm], { timeoutMs: 120_000 });
+            const results = this.parseBwJson(stdout);
+            for (const raw of results) {
+                if (!raw || typeof raw !== 'object')
+                    continue;
+                const item = raw;
+                if (item.type !== ITEM_TYPE.login)
+                    continue;
+                const id = item.id;
+                if (typeof id === 'string' && id.length > 0)
+                    byId.set(id, item);
+            }
+        }
+        const candidates = [...byId.values()];
+        const candidate = candidates.find((item) => this.candidateMatchesTerm(item, terms)) ??
+            candidates[0];
+        if (!candidate || typeof candidate.id !== 'string')
+            return null;
+        const { stdout } = await this.bw.runForSession(session, ['get', 'item', candidate.id], { timeoutMs: 60_000 });
+        const item = this.parseBwJson(stdout);
+        return this.extractLoginTotp(item);
     }
     parseBwJson(stdout) {
         try {
@@ -848,11 +925,20 @@ export class KeychainSdk {
         });
     }
     async getTotp(input, opts = {}) {
-        if (!opts.reveal)
-            return this.valueResult(null, false);
+        if (!opts.reveal) {
+            return {
+                ...this.valueResult(null, false),
+                period: null,
+                timeLeft: null,
+            };
+        }
         return this.bw.withSession(async (session) => {
             const { stdout } = await this.bw.runForSession(session, ['--raw', 'get', 'totp', input.term], { timeoutMs: 60_000 });
-            return this.valueResult(stdout.trim(), true);
+            const rawTotp = await this.resolveTotpConfigForSession(session, input.term).catch(() => null);
+            return {
+                ...this.valueResult(stdout.trim(), true),
+                ...this.computeTotpMetadata(rawTotp),
+            };
         });
     }
     /** Always reveals — URIs are not considered secrets by Bitwarden. */

package/dist/startup/bwStartup.js

@@ -0,0 +1,24 @@
+import { spawnSync } from 'node:child_process';
+import { resolveBundledBwBin } from '../bw/resolveBwBin.js';
+export function prepareBwStartup(env = process.env, deps = {}) {
+    if (!env.BW_BIN) {
+        const resolveBundled = deps.resolveBundledBwBin ?? resolveBundledBwBin;
+        const candidate = resolveBundled();
+        if (candidate) {
+            env.BW_BIN = candidate;
+            return;
+        }
+    }
+    if (env.BW_BIN)
+        return;
+    const probe = (deps.probeSystemBw ?? spawnSync)('bw', ['--version'], {
+        encoding: 'utf8',
+    });
+    if (!probe.error)
+        return;
+    const warn = deps.warn ?? console.warn;
+    warn('[warden-mcp] WARNING: bw CLI not found.\n' +
+        'Install it with:  npm install -g @bitwarden/cli\n' +
+        'Or set the BW_BIN environment variable to the path of the bw binary.\n' +
+        'The server will start but tool calls will fail until bw is available.');
+}

package/dist/tools/registerTools.js

@@ -35,8 +35,8 @@ export function registerTools(server, deps) {
     function effectiveReveal(input) {
         return isNoReveal ? false : (input.reveal ?? false);
     }
-    function toolResult(kind, value, revealed) {
-        return { result: { kind, value, revealed } };
+    function toolResult(kind, value, revealed, extra) {
+        return { result: { kind, value, revealed, ...(extra ?? {}) } };
     }
     const uriMatchSchema = z.enum([
         'domain',
@@ -926,7 +926,10 @@ export function registerTools(server, deps) {
         const sdk = await deps.getSdk(extra.authInfo);
         const totp = await sdk.getTotp({ term: input.term }, { reveal: effectiveReveal(input) });
         return {
-            structuredContent: toolResult('totp', totp.value, totp.revealed),
+            structuredContent: toolResult('totp', totp.value, totp.revealed, {
+                period: totp.period,
+                timeLeft: totp.timeLeft,
+            }),
             content: [{ type: 'text', text: 'OK' }],
         };
     });

package/package.json

@@ -1,7 +1,7 @@
 {
   "private": false,
   "name": "@icoretech/warden-mcp",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "type": "module",
   "license": "MIT",
   "description": "Vaultwarden/Bitwarden MCP server backed by Bitwarden CLI (bw).",
@@ -29,11 +29,13 @@
   "files": [
     "dist/",
     "bin/",
+    "patches/",
     "!dist/**/*.test.js",
     "!dist/integration/"
   ],
   "scripts": {
     "dev": "tsx watch --clear-screen=false src/server.ts",
+    "postinstall": "node bin/patch-bitwarden-cli.js",
     "build": "tsc -p .",
     "start": "node dist/server.js",
     "test": "npm run build && node --test \"dist/**/*.test.js\"",
@@ -45,10 +47,11 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
     "express": "^5.2.1",
+    "patch-package": "^8.0.1",
     "zod": "^4.3.6"
   },
   "optionalDependencies": {
-    "@bitwarden/cli": "2026.1.0"
+    "@bitwarden/cli": "2026.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.8",

package/patches/@bitwarden+cli+2026.2.0.patch

@@ -0,0 +1,80 @@
+diff --git a/node_modules/@bitwarden/cli/build/bw.js b/node_modules/@bitwarden/cli/build/bw.js
+index 6b02f68..2085f5e 100755
+--- a/node_modules/@bitwarden/cli/build/bw.js
++++ b/node_modules/@bitwarden/cli/build/bw.js
+@@ -27093,7 +27093,17 @@ class AuthRequestLoginStrategy extends LoginStrategy {
+     }
+     setAccountCryptographicState(response, userId) {
+         return auth_request_login_strategy_awaiter(this, void 0, void 0, function* () {
+-            yield this.accountCryptographicStateService.setAccountCryptographicState(response.accountKeysResponseModel.toWrappedAccountCryptographicState(), userId);
++            /* icoretech-vaultwarden-compat */
++            if (response.accountKeysResponseModel) {
++                yield this.accountCryptographicStateService.setAccountCryptographicState(response.accountKeysResponseModel.toWrappedAccountCryptographicState(), userId);
++            }
++            else if (response.privateKey) {
++                yield this.accountCryptographicStateService.setAccountCryptographicState({
++                    V1: {
++                        private_key: response.privateKey,
++                    },
++                }, userId);
++            }
+         });
+     }
+     exportCache() {
+@@ -27203,7 +27213,17 @@ class PasswordLoginStrategy extends LoginStrategy {
+     }
+     setAccountCryptographicState(response, userId) {
+         return password_login_strategy_awaiter(this, void 0, void 0, function* () {
+-            yield this.accountCryptographicStateService.setAccountCryptographicState(response.accountKeysResponseModel.toWrappedAccountCryptographicState(), userId);
++            /* icoretech-vaultwarden-compat */
++            if (response.accountKeysResponseModel) {
++                yield this.accountCryptographicStateService.setAccountCryptographicState(response.accountKeysResponseModel.toWrappedAccountCryptographicState(), userId);
++            }
++            else if (response.privateKey) {
++                yield this.accountCryptographicStateService.setAccountCryptographicState({
++                    V1: {
++                        private_key: response.privateKey,
++                    },
++                }, userId);
++            }
+         });
+     }
+     encryptionKeyMigrationRequired(response) {
+@@ -28327,7 +28347,17 @@ class UserApiLoginStrategy extends LoginStrategy {
+     }
+     setAccountCryptographicState(response, userId) {
+         return user_api_login_strategy_awaiter(this, void 0, void 0, function* () {
+-            yield this.accountCryptographicStateService.setAccountCryptographicState(response.accountKeysResponseModel.toWrappedAccountCryptographicState(), userId);
++            /* icoretech-vaultwarden-compat */
++            if (response.accountKeysResponseModel) {
++                yield this.accountCryptographicStateService.setAccountCryptographicState(response.accountKeysResponseModel.toWrappedAccountCryptographicState(), userId);
++            }
++            else if (response.privateKey) {
++                yield this.accountCryptographicStateService.setAccountCryptographicState({
++                    V1: {
++                        private_key: response.privateKey,
++                    },
++                }, userId);
++            }
+         });
+     }
+     // Overridden to save client ID and secret to token service
+@@ -28457,7 +28487,17 @@ class WebAuthnLoginStrategy extends LoginStrategy {
+     }
+     setAccountCryptographicState(response, userId) {
+         return webauthn_login_strategy_awaiter(this, void 0, void 0, function* () {
+-            yield this.accountCryptographicStateService.setAccountCryptographicState(response.accountKeysResponseModel.toWrappedAccountCryptographicState(), userId);
++            /* icoretech-vaultwarden-compat */
++            if (response.accountKeysResponseModel) {
++                yield this.accountCryptographicStateService.setAccountCryptographicState(response.accountKeysResponseModel.toWrappedAccountCryptographicState(), userId);
++            }
++            else if (response.privateKey) {
++                yield this.accountCryptographicStateService.setAccountCryptographicState({
++                    V1: {
++                        private_key: response.privateKey,
++                    },
++                }, userId);
++            }
+         });
+     }
+     exportCache() {