@icoretech/warden-mcp 0.2.26 → 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
@@ -261,23 +275,21 @@ Start the shared server:
261
275
  npx -y @icoretech/warden-mcp@latest
262
276
  ```
263
277
 
264
- Every MCP request must include:
265
-
266
- - `X-BW-Host`
267
- - `X-BW-Password`
268
- - either `X-BW-ClientId` + `X-BW-ClientSecret`, or `X-BW-User`
269
-
270
- Example health check:
278
+ `GET /healthz` and `GET /metricsz` are liveness/guardrail endpoints and do not
279
+ validate Bitwarden credentials:
271
280
 
272
281
  ```bash
273
- curl -fsS \
274
- -H 'X-BW-Host: https://vaultwarden.example.com' \
275
- -H 'X-BW-ClientId: user.xxxxx' \
276
- -H 'X-BW-ClientSecret: xxxxx' \
277
- -H 'X-BW-Password: your-master-password' \
278
- http://localhost:3005/healthz
282
+ curl -fsS http://localhost:3005/healthz
279
283
  ```
280
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
+
281
293
  Example MCP endpoint:
282
294
 
283
295
  ```text
@@ -369,29 +381,29 @@ bw --version
369
381
  If that fails after install, your environment likely skipped the optional `@bitwarden/cli` dependency. Install it explicitly:
370
382
 
371
383
  ```bash
372
- npm install -g @bitwarden/cli
384
+ npm install -g @bitwarden/cli@2026.5.0
373
385
  ```
374
386
 
375
387
  ## How It Works
376
388
 
377
389
  The server executes `bw` commands on your behalf:
378
390
 
379
- - 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.
380
392
  - In stdio mode, Bitwarden/Vaultwarden credentials are loaded once from `BW_*` env vars at startup.
381
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.
382
- - 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`.
383
395
 
384
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.
385
397
 
386
- ### Required Headers
398
+ ### Bitwarden credential inputs
387
399
 
388
- - `X-BW-Host` (must be an HTTPS origin, for example `https://vaultwarden.example.com`)
389
- - `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)
390
402
  - Either:
391
- - `X-BW-ClientId` + `X-BW-ClientSecret` (API key login), or
392
- - `X-BW-User` (email for user/pass login; still uses `X-BW-Password`)
393
- - Optional:
394
- - `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`
395
407
 
396
408
  ## Security Model
397
409
 
@@ -399,25 +411,30 @@ There is **no built-in auth** layer in v1. Run it only on a trusted network boun
399
411
 
400
412
  Credential resolution:
401
413
 
402
- - **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.
403
415
  - **Stdio mode** reads `BW_*` env vars at startup (single-tenant).
404
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.
405
417
 
406
- Mutation control:
418
+ Runtime and safety controls:
407
419
 
408
- - Set `READONLY=true` to hide mutating tools from the advertised MCP catalog and reject direct write calls (create/edit/delete/move/restore/attachments).
409
- - 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.
410
- - 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.
411
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).
412
- - Session guardrails:
413
- - `KEYCHAIN_SESSION_MAX_COUNT` (default `32`)
414
- - `KEYCHAIN_SESSION_TTL_MS` (default `900000`)
415
- - `KEYCHAIN_SESSION_SWEEP_INTERVAL_MS` (default `60000`)
416
- - `KEYCHAIN_MAX_HEAP_USED_MB` (default `1536`, set `0` to disable memory fuse)
417
- - `KEYCHAIN_METRICS_LOG_INTERVAL_MS` (default `0`, disabled)
418
- - `NOREVEAL` / `KEYCHAIN_NOREVEAL` (default `false`; force all reveals to false)
419
- - `KEYCHAIN_ALLOW_ENV_FALLBACK` (default `false`; HTTP env-var credential fallback)
420
- - `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)
421
438
 
422
439
  Redaction defaults (item reads):
423
440
 
@@ -425,13 +442,14 @@ Redaction defaults (item reads):
425
442
  - Card: `number`, `code`
426
443
  - Identity: `ssn`, `passportNumber`, `licenseNumber`
427
444
  - Custom fields: hidden fields (Bitwarden `type: 1`)
445
+ - SSH key convention: custom field `private_key` is always redacted
428
446
  - Attachments: `attachments[].url` (signed download URL token)
429
447
  - Password history: `passwordHistory[].password`
430
448
 
431
449
  Reveal rules:
432
450
 
433
451
  - Tools accept `reveal: true` where applicable (default is `false`).
434
- - 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 }`.
435
453
  - When `reveal` is omitted/false, `value` is `null` (or historic passwords are `null`) and `revealed: false`.
436
454
 
437
455
  ## Production Deployment Checklist
@@ -440,13 +458,13 @@ If you run `warden-mcp` beyond local development, review these items:
440
458
 
441
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.
442
460
 
443
- 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.
444
462
 
445
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.
446
464
 
447
- 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.
448
466
 
449
- 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`).
450
468
 
451
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.
452
470
 
@@ -476,6 +494,12 @@ Starts a local Vaultwarden + HTTPS proxy (for `bw`), bootstraps a test user, and
476
494
  ```bash
477
495
  cp .env.example .env
478
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
479
503
  curl -fsS http://localhost:3005/healthz
480
504
  ```
481
505
 
@@ -495,7 +519,18 @@ The compose bootstrap step depends on the Playwright Docker image matching the
495
519
  `playwright` npm package version. If either moves, update the other in the same
496
520
  change.
497
521
 
498
- 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):
499
534
 
500
535
  ```bash
501
536
  npm run test:session-regression
@@ -504,16 +539,35 @@ npm run test:session-regression
504
539
  ### Local dev (host)
505
540
 
506
541
  ```bash
507
- npm install
508
- cp .env.example .env
542
+ npm ci
543
+ set -a && . ./.env && set +a # optional; Docker Compose reads .env automatically, host dev does not
509
544
  npm run dev
510
545
  ```
511
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
+
512
563
  ## Tool Reference (v1)
513
564
 
514
565
  ### Choosing the right tool
515
566
 
516
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.
517
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.
518
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.
519
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.
@@ -524,15 +578,16 @@ Vault/session:
524
578
 
525
579
  - `keychain_status`
526
580
  - `keychain_sync` (pull latest vault data from server via `bw sync`)
527
- - `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`)
528
582
  - `keychain_encode` (base64-encode a string via `bw encode`)
529
- - `keychain_generate` (returns a generated secret only when `reveal: true`)
583
+ - `keychain_generate`, `keychain_generate_username` (return generated values only when `reveal: true`)
530
584
 
531
585
  Items:
532
586
 
533
587
  - `keychain_search_items`, `keychain_get_item`, `keychain_update_item`
534
- - `keychain_create_login`, `keychain_create_note`, `keychain_create_card`, `keychain_create_identity`, `keychain_create_ssh_key`
535
- - `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`
536
591
 
537
592
  Folders:
538
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.26",
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).",
@@ -58,7 +58,7 @@
58
58
  "devDependencies": {
59
59
  "@biomejs/biome": "^2.5.0",
60
60
  "@types/express": "^5.0.6",
61
- "@types/node": "^25.9.3",
61
+ "@types/node": "^25.9.4",
62
62
  "playwright": "1.61.0",
63
63
  "tsx": "^4.22.4",
64
64
  "typescript": "^6.0.3"