@icoretech/warden-mcp 0.2.25 → 0.2.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -13,7 +13,7 @@ Published package: [`@icoretech/warden-mcp`](https://www.npmjs.com/package/@icor
13
13
 
14
14
  ## Highlights
15
15
 
16
- - MCP Streamable HTTP (SSE) endpoint at `POST /sse` + health check at `GET /healthz`
16
+ - MCP Streamable HTTP endpoint at `/sse` (GET/POST; DELETE intentionally unsupported) + health check at `GET /healthz`
17
17
  - Runtime guardrail metrics at `GET /metricsz`
18
18
  - Item types: **login**, **secure note**, **card**, **identity**, plus an **SSH key** convention (secure note + standard fields)
19
19
  - Attachments: create/delete/download
@@ -32,9 +32,9 @@ For search/list tools, the text output includes concise rows with stable ids and
32
32
  safe metadata such as names, item type, username, URI values, organization id,
33
33
  folder id, and collection ids. Secret fields are not included in those summaries.
34
34
  Create/update/move/restore helpers that return a folder, collection, or item use
35
- the same concise visible summaries so text-only clients can immediately reuse the
36
- returned ids in follow-up calls. Delete helpers include the requested ids when no
37
- object is returned.
35
+ concise visible summaries with reusable ids plus safe item metadata, including
36
+ nested login username/URI values and attachment metadata where present. Delete
37
+ helpers include the requested ids when no object is returned.
38
38
 
39
39
  For scalar helper tools, the text output follows the reveal contract:
40
40
 
@@ -52,9 +52,10 @@ For scalar helper tools, the text output follows the reveal contract:
52
52
  - if `NOREVEAL=true` or `KEYCHAIN_NOREVEAL=true`, revealed values are still
53
53
  suppressed server-side
54
54
 
55
- When a lookup term matches multiple login items, credential helpers return an
56
- `AMBIGUOUS_LOOKUP` error with visible candidate ids. Retry with `term` set to an
57
- exact candidate `id`, or call `get_item` with that `id`.
55
+ When a lookup term matches multiple login items, `keychain_get_username` and
56
+ revealed `keychain_get_password` return an `AMBIGUOUS_LOOKUP` error with visible
57
+ candidate ids. Retry with `term` set to an exact candidate `id`, or call
58
+ `get_item` with that `id`.
58
59
 
59
60
  If `KEYCHAIN_TEXT_COMPAT_MODE=structured_json` is enabled, supported success and
60
61
  ambiguity/error results mirror their `structuredContent` into the visible text as
@@ -76,7 +77,10 @@ In practice, this is what makes the server useful for full automation, not just
76
77
 
77
78
  ## Runtime Requirement
78
79
 
79
- This package shells out to the official Bitwarden CLI, `bw`.
80
+ Requires Node.js 24+ and npm when running from npm or source. The Docker image
81
+ already includes the supported Node runtime.
82
+
83
+ At runtime, this package shells out to the official Bitwarden CLI, `bw`.
80
84
 
81
85
  Runtime resolution order:
82
86
 
@@ -89,7 +93,7 @@ That means package installation can succeed even when the optional dependency is
89
93
  Explicit fallback install:
90
94
 
91
95
  ```bash
92
- npm install -g @bitwarden/cli
96
+ npm install -g @bitwarden/cli@2026.5.0
93
97
  ```
94
98
 
95
99
  Or run with an explicit binary path:
@@ -98,25 +102,26 @@ Or run with an explicit binary path:
98
102
  BW_BIN=/absolute/path/to/bw npx -y @icoretech/warden-mcp@latest
99
103
  ```
100
104
 
101
- `warden-mcp` intentionally bundles a vetted `@bitwarden/cli` version instead of
102
- blindly following the newest upstream CLI on every release. New `bw` releases
103
- can change login and unlock behavior in ways that break automation, so `bw`
104
- upgrades should be smoke-tested against real Vaultwarden flows before bumping
105
- the bundled version. Official Bitwarden compatibility is intended, but it is
106
- not continuously proven in CI without a real Bitwarden tenant.
107
-
108
- This repository's compose smoke now exercises both direct `bw` auth flows and
109
- the MCP/SDK layers with username/password auth plus user API-key auth against a
110
- real local Vaultwarden, so `@bitwarden/cli` bumps do not rely on unit coverage
111
- alone. The bundled postinstall compatibility shim rewrites the affected
112
- `build/bw.js` login strategies in place so the same Vaultwarden fallback can
113
- survive compatible CLI bumps without a version-stamped patch artifact.
105
+ `warden-mcp` intentionally bundles a vetted `@bitwarden/cli` version (currently
106
+ `2026.5.0`) instead of blindly following the newest upstream CLI on every
107
+ release. New `bw` releases can change login and unlock behavior in ways that
108
+ break automation, so `bw` upgrades should be smoke-tested against real
109
+ Vaultwarden flows before bumping the bundled version. Official Bitwarden
110
+ compatibility is intended, but it is not continuously proven in CI without a
111
+ real Bitwarden tenant.
112
+
113
+ This repository's compose smoke exercises both direct `bw` auth flows and the
114
+ MCP/SDK layers with username/password auth plus user API-key auth against a real
115
+ local Vaultwarden, so `@bitwarden/cli` bumps do not rely on unit coverage alone.
116
+ The bundled postinstall compatibility shim rewrites the affected `build/bw.js`
117
+ login strategies in place so the same Vaultwarden fallback can survive compatible
118
+ CLI bumps without a version-stamped patch artifact.
114
119
 
115
120
  ## Install And Run
116
121
 
117
122
  ### Choose a transport
118
123
 
119
- - Use `--stdio` when you want a local MCP host to spawn `warden-mcp` directly with one fixed Bitwarden profile
124
+ - Use `--stdio` or `WARDEN_MCP_STDIO=true` when you want a local MCP host to spawn `warden-mcp` directly with one fixed Bitwarden profile
120
125
  - Use default HTTP mode when you want one running `warden-mcp` service to serve multiple clients or multiple Bitwarden profiles via per-request `X-BW-*` headers
121
126
 
122
127
  ### Local stdio mode
@@ -160,17 +165,26 @@ curl -fsS http://localhost:3005/healthz
160
165
 
161
166
  This mode is what makes `warden-mcp` different from a simple local wrapper:
162
167
 
163
- - the server stays stateless at the HTTP boundary
164
- - Bitwarden/Vaultwarden credentials are sent per request via `X-BW-*` headers
168
+ - Bitwarden/Vaultwarden credentials and profile selection are resolved per request via `X-BW-*` headers
169
+ - MCP Streamable HTTP sessions are stateful and tracked by `mcp-session-id`
170
+ - per-profile `bw` state is kept server-side under `KEYCHAIN_BW_HOME_ROOT`
165
171
  - one running server can front different vault hosts or different identities without restarting
166
172
  - it fits shared-agent and gateway setups much better than per-client local processes
167
173
 
168
174
  ### Docker
169
175
 
170
176
  ```bash
171
- docker run --rm -p 3005:3005 ghcr.io/icoretech/warden-mcp:latest
177
+ docker run --rm \
178
+ -p 127.0.0.1:3005:3005 \
179
+ -v warden-mcp-data:/data \
180
+ ghcr.io/icoretech/warden-mcp:latest
172
181
  ```
173
182
 
183
+ The production image runs as the non-root `node` user (uid/gid `1000`), sets
184
+ `HOME=/data`, and stores Bitwarden profile state under `/data/bw-profiles` by
185
+ default. If you use a bind mount instead of the named volume above, make it
186
+ writable by uid/gid `1000`.
187
+
174
188
  ### Global install
175
189
 
176
190
  ```bash
@@ -203,14 +217,6 @@ codex mcp add warden \
203
217
 
204
218
  # Claude Code
205
219
  claude mcp add-json warden '{"command":"npx","args":["-y","@icoretech/warden-mcp@latest","--stdio"],"env":{"BW_HOST":"https://vaultwarden.example.com","BW_CLIENTID":"user.xxxxx","BW_CLIENTSECRET":"xxxxx","BW_PASSWORD":"your-master-password"}}'
206
-
207
- # Qwen Code
208
- qwen mcp add warden \
209
- -e BW_HOST=https://vaultwarden.example.com \
210
- -e BW_CLIENTID=user.xxxxx \
211
- -e BW_CLIENTSECRET=xxxxx \
212
- -e BW_PASSWORD=your-master-password \
213
- npx -y @icoretech/warden-mcp@latest --stdio
214
220
  ```
215
221
 
216
222
  ### JSON config hosts
@@ -220,7 +226,6 @@ These hosts all use the same stdio payload shape. Only the config file location
220
226
  - Codex: `~/.codex/config.toml`
221
227
  - Cursor: `~/.cursor/mcp.json` or `.cursor/mcp.json`
222
228
  - Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`
223
- - Qwen Code: `~/.qwen/settings.json` or `.qwen/settings.json`
224
229
 
225
230
  Shared JSON shape:
226
231
 
@@ -260,27 +265,6 @@ BW_PASSWORD = "your-master-password"
260
265
  because a cold first launch can spend several seconds downloading and unpacking
261
266
  the package before MCP initialization begins.
262
267
 
263
- ### Windsurf
264
-
265
- Windsurf uses the same stdio idea but stores it in `~/.codeium/windsurf/mcp_config.json`:
266
-
267
- ```json
268
- {
269
- "mcpServers": {
270
- "warden": {
271
- "command": "npx",
272
- "args": ["-y", "@icoretech/warden-mcp@latest", "--stdio"],
273
- "env": {
274
- "BW_HOST": "https://vaultwarden.example.com",
275
- "BW_CLIENTID": "user.xxxxx",
276
- "BW_CLIENTSECRET": "xxxxx",
277
- "BW_PASSWORD": "your-master-password"
278
- }
279
- }
280
- }
281
- }
282
- ```
283
-
284
268
  ### Shared HTTP connections
285
269
 
286
270
  If your MCP host supports Streamable HTTP with custom headers, you can connect to one long-lived `warden-mcp` service instead of spawning a local stdio process.
@@ -291,23 +275,21 @@ Start the shared server:
291
275
  npx -y @icoretech/warden-mcp@latest
292
276
  ```
293
277
 
294
- Every MCP request must include:
295
-
296
- - `X-BW-Host`
297
- - `X-BW-Password`
298
- - either `X-BW-ClientId` + `X-BW-ClientSecret`, or `X-BW-User`
299
-
300
- Example health check:
278
+ `GET /healthz` and `GET /metricsz` are liveness/guardrail endpoints and do not
279
+ validate Bitwarden credentials:
301
280
 
302
281
  ```bash
303
- curl -fsS \
304
- -H 'X-BW-Host: https://vaultwarden.example.com' \
305
- -H 'X-BW-ClientId: user.xxxxx' \
306
- -H 'X-BW-ClientSecret: xxxxx' \
307
- -H 'X-BW-Password: your-master-password' \
308
- http://localhost:3005/healthz
282
+ curl -fsS http://localhost:3005/healthz
309
283
  ```
310
284
 
285
+ Bitwarden-backed MCP tool calls must include these headers unless
286
+ `KEYCHAIN_ALLOW_ENV_FALLBACK=true` is enabled:
287
+
288
+ - `X-BW-Host` — HTTPS origin only; no credentials, path, query, or fragment
289
+ - `X-BW-Password`
290
+ - either `X-BW-ClientId` + `X-BW-ClientSecret`, or `X-BW-User` / `X-BW-Username`
291
+ - optional `X-BW-Unlock-Interval` in seconds; default `300`
292
+
311
293
  Example MCP endpoint:
312
294
 
313
295
  ```text
@@ -388,40 +370,6 @@ claude mcp add-json warden '{"type":"http","url":"http://localhost:3005/sse?v=2"
388
370
  }
389
371
  ```
390
372
 
391
- ```json
392
- // Qwen Code (~/.qwen/settings.json)
393
- {
394
- "mcpServers": {
395
- "warden": {
396
- "httpUrl": "http://localhost:3005/sse?v=2",
397
- "headers": {
398
- "X-BW-Host": "https://vaultwarden.example.com",
399
- "X-BW-ClientId": "user.xxxxx",
400
- "X-BW-ClientSecret": "xxxxx",
401
- "X-BW-Password": "your-master-password"
402
- }
403
- }
404
- }
405
- }
406
- ```
407
-
408
- ```json
409
- // Windsurf (~/.codeium/windsurf/mcp_config.json)
410
- {
411
- "mcpServers": {
412
- "warden": {
413
- "serverUrl": "http://localhost:3005/sse?v=2",
414
- "headers": {
415
- "X-BW-Host": "https://vaultwarden.example.com",
416
- "X-BW-ClientId": "user.xxxxx",
417
- "X-BW-ClientSecret": "xxxxx",
418
- "X-BW-Password": "your-master-password"
419
- }
420
- }
421
- }
422
- }
423
- ```
424
-
425
373
  Codex currently fits better with stdio here, because its MCP config supports a bearer token env var for remote servers but not arbitrary custom `X-BW-*` header injection.
426
374
 
427
375
  ### Verify bw is available
@@ -433,29 +381,29 @@ bw --version
433
381
  If that fails after install, your environment likely skipped the optional `@bitwarden/cli` dependency. Install it explicitly:
434
382
 
435
383
  ```bash
436
- npm install -g @bitwarden/cli
384
+ npm install -g @bitwarden/cli@2026.5.0
437
385
  ```
438
386
 
439
387
  ## How It Works
440
388
 
441
389
  The server executes `bw` commands on your behalf:
442
390
 
443
- - In HTTP mode, Bitwarden/Vaultwarden connection + credentials are provided via **HTTP headers** per request. Env-var fallback is disabled by default; set `KEYCHAIN_ALLOW_ENV_FALLBACK=true` to enable it for single-tenant HTTP deployments.
391
+ - In HTTP mode, Bitwarden/Vaultwarden credentials are provided via **HTTP headers** for tool calls. Env-var fallback is disabled by default; set `KEYCHAIN_ALLOW_ENV_FALLBACK=true` only for single-tenant HTTP deployments.
444
392
  - In stdio mode, Bitwarden/Vaultwarden credentials are loaded once from `BW_*` env vars at startup.
445
393
  - The server maintains per-profile `bw` state under `KEYCHAIN_BW_HOME_ROOT` and pins `BITWARDENCLI_APPDATA_DIR` inside that profile so the Bitwarden CLI keeps a stable local device/app identity across restarts instead of looking like a fresh client every time.
446
- - Writes can optionally call `bw sync` (internal; not exposed as an MCP tool).
394
+ - Writes call `bw sync` before mutations by default; set `KEYCHAIN_SYNC_ON_WRITE=false` to skip that pre-write sync. Manual sync is also exposed as `keychain_sync`.
447
395
 
448
396
  Timeout handling is also process-tree aware: if a `bw` command hangs, `warden-mcp` kills the full spawned process group rather than only the direct parent process. That prevents timed-out auth attempts from leaving orphaned `bw`/shell child processes behind.
449
397
 
450
- ### Required Headers
398
+ ### Bitwarden credential inputs
451
399
 
452
- - `X-BW-Host` (must be an HTTPS origin, for example `https://vaultwarden.example.com`)
453
- - `X-BW-Password` (master password; required to unlock)
400
+ - `X-BW-Host` / `BW_HOST` (must be an HTTPS origin, for example `https://vaultwarden.example.com`; no path, query, fragment, or embedded credentials)
401
+ - `X-BW-Password` / `BW_PASSWORD` (master password; required to unlock)
454
402
  - Either:
455
- - `X-BW-ClientId` + `X-BW-ClientSecret` (API key login), or
456
- - `X-BW-User` (email for user/pass login; still uses `X-BW-Password`)
457
- - Optional:
458
- - `X-BW-Unlock-Interval` (seconds)
403
+ - `X-BW-ClientId` + `X-BW-ClientSecret` / `BW_CLIENTID` + `BW_CLIENTSECRET` (API key login), or
404
+ - `X-BW-User` / `X-BW-Username` / `BW_USER` / `BW_USERNAME` (email for user/pass login; still uses the master password)
405
+ - Optional unlock interval:
406
+ - `X-BW-Unlock-Interval` / `BW_UNLOCK_INTERVAL` in seconds; default `300`
459
407
 
460
408
  ## Security Model
461
409
 
@@ -463,25 +411,30 @@ There is **no built-in auth** layer in v1. Run it only on a trusted network boun
463
411
 
464
412
  Credential resolution:
465
413
 
466
- - **HTTP mode** requires `X-BW-*` headers on every request by default. Without them, tools return an error.
414
+ - **HTTP mode** requires `X-BW-*` headers before Bitwarden-backed tools can run by default. `/healthz` and `/metricsz` do not validate vault credentials.
467
415
  - **Stdio mode** reads `BW_*` env vars at startup (single-tenant).
468
416
  - To allow HTTP mode to fall back to server env vars when headers are absent (single-tenant HTTP), set `KEYCHAIN_ALLOW_ENV_FALLBACK=true`. **Security warning:** this means any client that can reach the HTTP endpoint gets full vault access without providing credentials. Only use this behind network-level access control.
469
417
 
470
- Mutation control:
418
+ Runtime and safety controls:
471
419
 
472
- - Set `READONLY=true` to hide mutating tools from the advertised MCP catalog and reject direct write calls (create/edit/delete/move/restore/attachments).
473
- - Set `NOREVEAL=true` to force all `reveal` parameters to `false` server-side. Clients can still request `reveal: true`, but the server will silently downgrade to redacted output. This prevents prompt injection from tricking an LLM agent into exfiltrating secrets.
474
- - Set `KEYCHAIN_TEXT_COMPAT_MODE=structured_json` to mirror supported structured tool results into `TextContent` as serialized JSON. This is useful for text-only MCP clients that ignore `structuredContent`, but it also duplicates revealed secrets into the plain-text transcript.
420
+ - Set `PORT` to change the HTTP port (default `3005`).
421
+ - Set `WARDEN_MCP_HOST` to bind the HTTP server to a specific interface, for example `127.0.0.1` for local-only access.
422
+ - Set `WARDEN_MCP_STDIO=true` as an env-var alternative to `--stdio`.
423
+ - Set `MCP_APP_NAME` to override the advertised MCP server name.
475
424
  - Tool names default to `keychain_*`. Override `TOOL_PREFIX` to change the namespace and `TOOL_SEPARATOR` to change the separator (default `_`, set `.` for legacy clients).
476
- - Session guardrails:
477
- - `KEYCHAIN_SESSION_MAX_COUNT` (default `32`)
478
- - `KEYCHAIN_SESSION_TTL_MS` (default `900000`)
479
- - `KEYCHAIN_SESSION_SWEEP_INTERVAL_MS` (default `60000`)
480
- - `KEYCHAIN_MAX_HEAP_USED_MB` (default `1536`, set `0` to disable memory fuse)
481
- - `KEYCHAIN_METRICS_LOG_INTERVAL_MS` (default `0`, disabled)
482
- - `NOREVEAL` / `KEYCHAIN_NOREVEAL` (default `false`; force all reveals to false)
483
- - `KEYCHAIN_ALLOW_ENV_FALLBACK` (default `false`; HTTP env-var credential fallback)
484
- - `KEYCHAIN_TEXT_COMPAT_MODE` (default unset; set to `structured_json` to copy structured results into `TextContent`)
425
+ - Set `KEYCHAIN_BW_HOME_ROOT` to change where per-profile `bw` state is stored.
426
+ - Set `KEYCHAIN_SYNC_ON_WRITE=false` to skip the default pre-write `bw sync` call.
427
+ - Set `READONLY=true` or `KEYCHAIN_READONLY=true` to hide mutating tools from the advertised MCP catalog and reject direct write calls. This covers item/folder/org collection writes, Sends, attachments, batch creates/deletes, URI updates, moves, and restores.
428
+ - Set `NOREVEAL=true` or `KEYCHAIN_NOREVEAL=true` to force all `reveal` parameters to `false` server-side. Clients can still request `reveal: true`, but the server will silently downgrade to redacted output. This prevents prompt injection from tricking an LLM agent into exfiltrating secrets.
429
+ - Set `KEYCHAIN_TEXT_COMPAT_MODE=structured_json` to mirror supported structured tool results into `TextContent` as serialized JSON. This is useful for text-only MCP clients that ignore `structuredContent`, but it also duplicates revealed secrets into the plain-text transcript.
430
+
431
+ Session guardrails:
432
+
433
+ - `KEYCHAIN_SESSION_MAX_COUNT` (default `32`)
434
+ - `KEYCHAIN_SESSION_TTL_MS` (default `900000`)
435
+ - `KEYCHAIN_SESSION_SWEEP_INTERVAL_MS` (default `60000`)
436
+ - `KEYCHAIN_MAX_HEAP_USED_MB` (default `1536`, set `0` to disable memory fuse)
437
+ - `KEYCHAIN_METRICS_LOG_INTERVAL_MS` (default `0`, disabled)
485
438
 
486
439
  Redaction defaults (item reads):
487
440
 
@@ -489,13 +442,14 @@ Redaction defaults (item reads):
489
442
  - Card: `number`, `code`
490
443
  - Identity: `ssn`, `passportNumber`, `licenseNumber`
491
444
  - Custom fields: hidden fields (Bitwarden `type: 1`)
445
+ - SSH key convention: custom field `private_key` is always redacted
492
446
  - Attachments: `attachments[].url` (signed download URL token)
493
447
  - Password history: `passwordHistory[].password`
494
448
 
495
449
  Reveal rules:
496
450
 
497
451
  - Tools accept `reveal: true` where applicable (default is `false`).
498
- - Secret helper tools (`get_password`, `get_totp`, `get_notes`, `generate`, `get_password_history`) return `structuredContent.result = { kind, value, revealed }`.
452
+ - Secret helper tools (`get_password`, `get_totp`, `get_notes`, `generate`, `generate_username`, `get_password_history`) return `structuredContent.result = { kind, value, revealed }`.
499
453
  - When `reveal` is omitted/false, `value` is `null` (or historic passwords are `null`) and `revealed: false`.
500
454
 
501
455
  ## Production Deployment Checklist
@@ -504,13 +458,13 @@ If you run `warden-mcp` beyond local development, review these items:
504
458
 
505
459
  1. **TLS everywhere.** Always terminate TLS in front of the HTTP endpoint. `X-BW-*` headers carry master passwords in cleartext — without TLS they are visible to anyone on the network.
506
460
 
507
- 2. **Network isolation.** Bind the server to `127.0.0.1` or place it behind an authenticated reverse proxy. The service has no built-in authentication; anyone who can reach `/sse` can issue vault operations.
461
+ 2. **Network isolation.** Bind or publish the server only on a trusted interface, for example `WARDEN_MCP_HOST=127.0.0.1`, Docker `-p 127.0.0.1:3005:3005`, a firewall, VPN, or an authenticated reverse proxy. The service has no built-in authentication; anyone who can reach `/sse` can issue vault operations.
508
462
 
509
463
  3. **Do not enable `KEYCHAIN_ALLOW_ENV_FALLBACK` on shared networks.** This flag makes the server's own vault credentials available to any HTTP client that omits headers. Only use it in single-tenant setups where the network is fully trusted.
510
464
 
511
- 4. **Enable `READONLY=true` when writes are not needed.** This hides mutating tools from the advertised MCP catalog and rejects direct write calls at the MCP layer, limiting blast radius if an agent or client is compromised.
465
+ 4. **Enable `READONLY=true` or `KEYCHAIN_READONLY=true` when writes are not needed.** This hides mutating tools from the advertised MCP catalog and rejects direct write calls at the MCP layer, limiting blast radius if an agent or client is compromised.
512
466
 
513
- 5. **Restrict filesystem access to `/data/bw-profiles`.** The `bw` CLI stores decrypted state under its HOME directory. Ensure the profile directory is not world-readable and is mounted with appropriate permissions (the Docker image runs as non-root by default).
467
+ 5. **Persist and restrict filesystem access to the configured `KEYCHAIN_BW_HOME_ROOT`.** In Docker the default is `/data/bw-profiles`; on host runs it defaults to `${HOME}/bw-profiles`. Ensure the profile directory is not world-readable and is mounted with appropriate permissions (the Docker image runs as non-root uid/gid `1000`).
514
468
 
515
469
  6. **Disable debug logging in production.** `KEYCHAIN_DEBUG_BW` and `KEYCHAIN_DEBUG_HTTP` emit request details and CLI invocations to stdout. Debug logs may include session metadata and request structure. Keep them off unless actively troubleshooting.
516
470
 
@@ -540,6 +494,12 @@ Starts a local Vaultwarden + HTTPS proxy (for `bw`), bootstraps a test user, and
540
494
  ```bash
541
495
  cp .env.example .env
542
496
  make up
497
+ ```
498
+
499
+ `make up` keeps the MCP service in the foreground. In another terminal, verify
500
+ the server is up:
501
+
502
+ ```bash
543
503
  curl -fsS http://localhost:3005/healthz
544
504
  ```
545
505
 
@@ -559,7 +519,18 @@ The compose bootstrap step depends on the Playwright Docker image matching the
559
519
  `playwright` npm package version. If either moves, update the other in the same
560
520
  change.
561
521
 
562
- Run session flood regression locally (guardrail sanity):
522
+ Optional organization-focused integration stack:
523
+
524
+ ```bash
525
+ make test-org
526
+ ```
527
+
528
+ Use `make up-org`, `make bootstrap-org`, `make down-org`, and `make ps-org` when
529
+ you need to inspect that stack manually.
530
+
531
+ Run session flood regression locally after a server is already running on
532
+ `http://127.0.0.1:3005` (override with `KEYCHAIN_FLOOD_BASE_URL` and
533
+ `KEYCHAIN_METRICS_URL` when needed):
563
534
 
564
535
  ```bash
565
536
  npm run test:session-regression
@@ -568,16 +539,35 @@ npm run test:session-regression
568
539
  ### Local dev (host)
569
540
 
570
541
  ```bash
571
- npm install
572
- cp .env.example .env
542
+ npm ci
543
+ set -a && . ./.env && set +a # optional; Docker Compose reads .env automatically, host dev does not
573
544
  npm run dev
574
545
  ```
575
546
 
547
+ For host HTTP mode, vault credentials can still be supplied per request with
548
+ `X-BW-*` headers instead of loading them into the server environment.
549
+
550
+ Useful npm scripts:
551
+
552
+ | Script | Purpose |
553
+ | --- | --- |
554
+ | `npm run build` | Compile TypeScript to `dist/` |
555
+ | `npm run dev` | Watch-mode local HTTP server |
556
+ | `npm run start` | Run the compiled server from `dist/` |
557
+ | `npm run test` | Build, then run all compiled unit tests |
558
+ | `npm run test:integration` | Build, then run compose-backed integration tests one file at a time |
559
+ | `npm run test:coverage` | Build, then run Node test coverage |
560
+ | `npm run lint` | Run Biome autofix plus `tsc --noEmit` |
561
+
562
+
576
563
  ## Tool Reference (v1)
577
564
 
578
565
  ### Choosing the right tool
579
566
 
580
567
  - Start with `keychain_search_items` when you know a name, URI, username, folder, collection, or item type but not the exact item id. Then call `keychain_get_item` with the returned id for the full item shape.
568
+ - Use `keychain_create_logins` when you need to create several independent login items in one call; it returns per-item results and can continue after individual failures.
569
+ - Use `keychain_set_login_uris` to replace or merge a login item's URI list without editing the whole item payload.
570
+ - Use `keychain_delete_items` for bulk soft-delete/hard-delete by id with per-id results.
581
571
  - Personal folder tools manage one user's vault folders, for example `Example Folder`. Organization collection tools manage shared organization-scoped collections, for example `Example Collection`. `organizationId` is required for `keychain_list_org_collections`, `keychain_create_org_collection`, `keychain_edit_org_collection`, and `keychain_delete_org_collection`, and optional only for `keychain_get_org_collection` when you want to narrow a direct id lookup.
582
572
  - `keychain_move_item_to_organization` moves an item out of the personal vault and into an organization, optionally assigning collection ids at the same time.
583
573
  - `keychain_send_create` is the quick path for text or file Sends through the normal `bw send` flags, including `emails` for email-gated access. `emails` is mutually exclusive with `password` and does not share the generated Send URL for you. `keychain_send_template`, `keychain_send_create_encoded`, and `keychain_send_edit` are for the full Bitwarden Send JSON template or an encoded edit payload.
@@ -588,15 +578,16 @@ Vault/session:
588
578
 
589
579
  - `keychain_status`
590
580
  - `keychain_sync` (pull latest vault data from server via `bw sync`)
591
- - `keychain_sdk_version` (returns the Bitwarden SDK version used by the CLI)
581
+ - `keychain_sdk_version` (returns the Bitwarden CLI version reported by `bw --version`)
592
582
  - `keychain_encode` (base64-encode a string via `bw encode`)
593
- - `keychain_generate` (returns a generated secret only when `reveal: true`)
583
+ - `keychain_generate`, `keychain_generate_username` (return generated values only when `reveal: true`)
594
584
 
595
585
  Items:
596
586
 
597
587
  - `keychain_search_items`, `keychain_get_item`, `keychain_update_item`
598
- - `keychain_create_login`, `keychain_create_note`, `keychain_create_card`, `keychain_create_identity`, `keychain_create_ssh_key`
599
- - `keychain_delete_item`, `keychain_restore_item`
588
+ - `keychain_create_login`, `keychain_create_logins`, `keychain_set_login_uris`
589
+ - `keychain_create_note`, `keychain_create_card`, `keychain_create_identity`, `keychain_create_ssh_key`
590
+ - `keychain_delete_item`, `keychain_delete_items`, `keychain_restore_item`
600
591
 
601
592
  Folders:
602
593
 
package/dist/server.js CHANGED
@@ -16,10 +16,16 @@ async function main() {
16
16
  return;
17
17
  }
18
18
  const PORT = Number.parseInt(process.env.PORT ?? '3005', 10);
19
+ const rawHost = process.env.WARDEN_MCP_HOST?.trim();
20
+ const host = rawHost && rawHost.length > 0 ? rawHost : undefined;
19
21
  const app = createKeychainApp();
20
- const server = app.listen(PORT, () => {
21
- console.log(`[warden-mcp] listening on http://localhost:${PORT}/sse`);
22
- });
22
+ const server = host
23
+ ? app.listen(PORT, host, () => {
24
+ console.log(`[warden-mcp] listening on http://${host}:${PORT}/sse`);
25
+ })
26
+ : app.listen(PORT, () => {
27
+ console.log(`[warden-mcp] listening on http://localhost:${PORT}/sse`);
28
+ });
23
29
  await new Promise((resolve, reject) => {
24
30
  server.once('close', resolve);
25
31
  server.once('error', reject);
@@ -134,11 +134,23 @@ export function registerTools(server, deps) {
134
134
  parts.push(`name=${quoteText(rec.name)}`);
135
135
  if (typeof rec.type === 'string')
136
136
  parts.push(`type=${rec.type}`);
137
- if (typeof rec.username === 'string') {
138
- parts.push(`username=${quoteText(rec.username)}`);
139
- }
140
- if (Array.isArray(rec.uris) && rec.uris.length > 0) {
141
- const uris = rec.uris
137
+ const login = rec.login && typeof rec.login === 'object'
138
+ ? rec.login
139
+ : undefined;
140
+ const username = typeof rec.username === 'string'
141
+ ? rec.username
142
+ : typeof login?.username === 'string'
143
+ ? login.username
144
+ : undefined;
145
+ if (username)
146
+ parts.push(`username=${quoteText(username)}`);
147
+ const rawUris = Array.isArray(rec.uris)
148
+ ? rec.uris
149
+ : Array.isArray(login?.uris)
150
+ ? login.uris
151
+ : [];
152
+ if (rawUris.length > 0) {
153
+ const uris = rawUris
142
154
  .map((uri) => {
143
155
  if (!uri || typeof uri !== 'object')
144
156
  return null;
@@ -533,8 +545,8 @@ export function registerTools(server, deps) {
533
545
  };
534
546
  });
535
547
  registerTool(`${deps.toolPrefix}.sdk_version`, {
536
- title: 'SDK Version',
537
- description: 'Return the Bitwarden SDK version reported by the bundled bw CLI. Use this read-only check when diagnosing CLI/runtime compatibility without touching vault data.',
548
+ title: 'CLI Version',
549
+ description: 'Return the Bitwarden CLI version reported by bw --version. Use this read-only check when diagnosing CLI/runtime compatibility without touching vault data.',
538
550
  annotations: { readOnlyHint: true },
539
551
  inputSchema: {},
540
552
  outputSchema: sdkVersionOutputSchema,
@@ -1503,7 +1515,7 @@ export function registerTools(server, deps) {
1503
1515
  });
1504
1516
  registerTool(`${deps.toolPrefix}.send_delete`, {
1505
1517
  title: 'Send Delete',
1506
- description: 'Delete a Bitwarden Send by id through bw send delete. This is destructive for the Send and its shared content; it does not delete any vault item that may have been used to create it. Returns the bw result payload when available.',
1518
+ description: 'Delete a Bitwarden Send by id through bw send delete. This is destructive for the Send and its shared content; it does not delete any vault item that may have been used to create it. The visible text includes the requested Send id, and structured output includes both that id and the bw result payload when available.',
1507
1519
  annotations: {
1508
1520
  readOnlyHint: false,
1509
1521
  destructiveHint: true,
@@ -1518,10 +1530,10 @@ export function registerTools(server, deps) {
1518
1530
  return readonlyBlocked();
1519
1531
  const sdk = await deps.getSdk(extra.authInfo);
1520
1532
  const result = await sdk.sendDelete(input);
1521
- const structuredContent = { result };
1533
+ const structuredContent = { result, id: input.id };
1522
1534
  return {
1523
1535
  structuredContent,
1524
- content: toolScalarContent(structuredContent, 'result', result),
1536
+ content: idTextContent(structuredContent, 'Deleted Send', input.id),
1525
1537
  };
1526
1538
  });
1527
1539
  registerTool(`${deps.toolPrefix}.receive`, {
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "private": false,
3
3
  "name": "@icoretech/warden-mcp",
4
- "version": "0.2.25",
4
+ "version": "0.2.27",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "description": "Vaultwarden/Bitwarden MCP server backed by Bitwarden CLI (bw).",
@@ -51,11 +51,15 @@
51
51
  "optionalDependencies": {
52
52
  "@bitwarden/cli": "2026.5.0"
53
53
  },
54
+ "overrides": {
55
+ "form-data": "4.0.6",
56
+ "tmp": "0.2.7"
57
+ },
54
58
  "devDependencies": {
55
59
  "@biomejs/biome": "^2.5.0",
56
60
  "@types/express": "^5.0.6",
57
- "@types/node": "^25.9.3",
58
- "playwright": "1.60.0",
61
+ "@types/node": "^25.9.4",
62
+ "playwright": "1.61.0",
59
63
  "tsx": "^4.22.4",
60
64
  "typescript": "^6.0.3"
61
65
  },