@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 +129 -74
- package/dist/server.js +9 -3
- package/dist/tools/registerTools.js +22 -10
- package/package.json +2 -2
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
|
|
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
|
-
|
|
36
|
-
|
|
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,
|
|
56
|
-
`
|
|
57
|
-
|
|
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
|
-
|
|
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
|
|
102
|
-
blindly following the newest upstream CLI on every
|
|
103
|
-
can change login and unlock behavior in ways that
|
|
104
|
-
upgrades should be smoke-tested against real
|
|
105
|
-
the bundled version. Official Bitwarden
|
|
106
|
-
not continuously proven in CI without a
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
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
|
-
-
|
|
164
|
-
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
###
|
|
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
|
|
393
|
-
- Optional:
|
|
394
|
-
- `X-BW-Unlock-Interval`
|
|
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
|
|
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
|
-
|
|
418
|
+
Runtime and safety controls:
|
|
407
419
|
|
|
408
|
-
- Set `
|
|
409
|
-
- Set `
|
|
410
|
-
- Set `
|
|
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
|
-
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
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
|
|
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. **
|
|
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
|
-
|
|
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
|
|
508
|
-
|
|
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
|
|
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` (
|
|
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`, `
|
|
535
|
-
- `
|
|
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 =
|
|
21
|
-
|
|
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
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
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: '
|
|
537
|
-
description: 'Return the Bitwarden
|
|
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.
|
|
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:
|
|
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.
|
|
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.
|
|
61
|
+
"@types/node": "^25.9.4",
|
|
62
62
|
"playwright": "1.61.0",
|
|
63
63
|
"tsx": "^4.22.4",
|
|
64
64
|
"typescript": "^6.0.3"
|