@icoretech/warden-mcp 0.2.54 → 0.2.56

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.
Files changed (2) hide show
  1. package/README.md +57 -62
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -24,7 +24,6 @@ Use stdio mode when a local MCP host launches the server directly. It is the
24
24
  simplest and most portable setup for desktop agents.
25
25
 
26
26
  Prerequisites:
27
-
28
27
  - Node.js 22.x
29
28
  - npm 10.x
30
29
  - a Vaultwarden or Bitwarden account
@@ -112,11 +111,11 @@ BW_PASSWORD = "your-master-password"
112
111
 
113
112
  Common locations:
114
113
 
115
- | Host | Config file |
116
- | --- | --- |
117
- | Cursor | `~/.cursor/mcp.json` or `.cursor/mcp.json` |
114
+ | Host | Config file |
115
+ | -------------- | ----------------------------------------------------------------- |
116
+ | Cursor | `~/.cursor/mcp.json` or `.cursor/mcp.json` |
118
117
  | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
119
- | Codex | `~/.codex/config.toml` |
118
+ | Codex | `~/.codex/config.toml` |
120
119
 
121
120
  ## Why Use It
122
121
 
@@ -151,11 +150,11 @@ when the process starts.
151
150
 
152
151
  The HTTP server exposes:
153
152
 
154
- | Endpoint | Purpose |
155
- | --- | --- |
156
- | `GET /healthz` | liveness check; does not validate vault credentials |
157
- | `GET /metricsz` | session and runtime guardrail metrics |
158
- | `/sse?v=2` | MCP Streamable HTTP endpoint |
153
+ | Endpoint | Purpose |
154
+ | --------------- | --------------------------------------------------- |
155
+ | `GET /healthz` | liveness check; does not validate vault credentials |
156
+ | `GET /metricsz` | session and runtime guardrail metrics |
157
+ | `/sse?v=2` | MCP Streamable HTTP endpoint |
159
158
 
160
159
  ## Run As A Shared HTTP Service
161
160
 
@@ -177,14 +176,14 @@ curl -fsS http://localhost:3005/healthz
177
176
  MCP tool calls must include these headers unless env fallback is explicitly
178
177
  enabled:
179
178
 
180
- | Header | Meaning |
181
- | --- | --- |
182
- | `X-BW-Host` | HTTPS origin only, for example `https://vaultwarden.example.com` |
183
- | `X-BW-Password` | master password used to unlock the vault |
184
- | `X-BW-ClientId` | Bitwarden API key client id |
185
- | `X-BW-ClientSecret` | Bitwarden API key client secret |
186
- | `X-BW-User` or `X-BW-Username` | username/email alternative to API key login |
187
- | `X-BW-Unlock-Interval` | optional unlock interval in seconds; default `300` |
179
+ | Header | Meaning |
180
+ | ------------------------------ | ---------------------------------------------------------------- |
181
+ | `X-BW-Host` | HTTPS origin only, for example `https://vaultwarden.example.com` |
182
+ | `X-BW-Password` | master password used to unlock the vault |
183
+ | `X-BW-ClientId` | Bitwarden API key client id |
184
+ | `X-BW-ClientSecret` | Bitwarden API key client secret |
185
+ | `X-BW-User` or `X-BW-Username` | username/email alternative to API key login |
186
+ | `X-BW-Unlock-Interval` | optional unlock interval in seconds; default `300` |
188
187
 
189
188
  Example HTTP MCP config for hosts that support custom headers:
190
189
 
@@ -246,7 +245,6 @@ default. If you use a bind mount, make it writable by uid/gid `1000`.
246
245
  The Docker image includes the supported Node runtime.
247
246
 
248
247
  The server resolves `bw` in this order:
249
-
250
248
  1. `BW_BIN`, when set
251
249
  2. bundled `@bitwarden/cli` dependency
252
250
  3. system `bw` from `PATH`
@@ -267,7 +265,6 @@ BW_BIN=/absolute/path/to/bw npx -y @icoretech/warden-mcp@latest --stdio
267
265
 
268
266
  There is no built-in authentication layer in v1. Protect the transport before
269
267
  you expose it.
270
-
271
268
  - **Bind locally by default** - use `WARDEN_MCP_HOST=127.0.0.1`, Docker
272
269
  `-p 127.0.0.1:3005:3005`, a firewall, VPN, or an authenticated reverse proxy
273
270
  - **Use TLS for HTTP mode** - `X-BW-*` headers carry vault credentials
@@ -294,25 +291,25 @@ Returning notes or private keys requires `reveal: true`; `NOREVEAL` and
294
291
 
295
292
  ## Configuration
296
293
 
297
- | Variable | Default | Purpose |
298
- | --- | --- | --- |
299
- | `PORT` | `3005` | HTTP listen port |
300
- | `WARDEN_MCP_HOST` | all interfaces | HTTP bind host |
301
- | `WARDEN_MCP_STDIO` | `false` | force stdio mode without `--stdio` |
302
- | `MCP_APP_NAME` | `keychain-mcp` | advertised MCP server name |
303
- | `TOOL_PREFIX` | `keychain` | public tool namespace |
304
- | `TOOL_SEPARATOR` | `_` | public tool separator; set `.` for legacy clients |
305
- | `KEYCHAIN_BW_HOME_ROOT` | `${HOME}/bw-profiles` | root for per-profile `bw` state |
306
- | `KEYCHAIN_ALLOW_ENV_FALLBACK` | `false` | allow HTTP calls to inherit server `BW_*` env |
307
- | `KEYCHAIN_SYNC_ON_WRITE` | `true` | run `bw sync` before write operations |
308
- | `READONLY` / `KEYCHAIN_READONLY` | `false` | hide and reject mutating tools |
309
- | `NOREVEAL` / `KEYCHAIN_NOREVEAL` | `false` | force `reveal: false` server-side |
310
- | `KEYCHAIN_TEXT_COMPAT_MODE` | unset | set `structured_json` for text-only clients |
311
- | `KEYCHAIN_SESSION_MAX_COUNT` | `32` | max tracked HTTP sessions |
312
- | `KEYCHAIN_SESSION_TTL_MS` | `900000` | inactive session TTL |
313
- | `KEYCHAIN_SESSION_SWEEP_INTERVAL_MS` | `60000` | session cleanup interval |
314
- | `KEYCHAIN_MAX_HEAP_USED_MB` | `1536` | memory fuse; set `0` to disable |
315
- | `KEYCHAIN_METRICS_LOG_INTERVAL_MS` | `0` | periodic metrics logging; `0` disables |
294
+ | Variable | Default | Purpose |
295
+ | ------------------------------------ | --------------------- | ------------------------------------------------- |
296
+ | `PORT` | `3005` | HTTP listen port |
297
+ | `WARDEN_MCP_HOST` | all interfaces | HTTP bind host |
298
+ | `WARDEN_MCP_STDIO` | `false` | force stdio mode without `--stdio` |
299
+ | `MCP_APP_NAME` | `keychain-mcp` | advertised MCP server name |
300
+ | `TOOL_PREFIX` | `keychain` | public tool namespace |
301
+ | `TOOL_SEPARATOR` | `_` | public tool separator; set `.` for legacy clients |
302
+ | `KEYCHAIN_BW_HOME_ROOT` | `${HOME}/bw-profiles` | root for per-profile `bw` state |
303
+ | `KEYCHAIN_ALLOW_ENV_FALLBACK` | `false` | allow HTTP calls to inherit server `BW_*` env |
304
+ | `KEYCHAIN_SYNC_ON_WRITE` | `true` | run `bw sync` before write operations |
305
+ | `READONLY` / `KEYCHAIN_READONLY` | `false` | hide and reject mutating tools |
306
+ | `NOREVEAL` / `KEYCHAIN_NOREVEAL` | `false` | force `reveal: false` server-side |
307
+ | `KEYCHAIN_TEXT_COMPAT_MODE` | unset | set `structured_json` for text-only clients |
308
+ | `KEYCHAIN_SESSION_MAX_COUNT` | `32` | max tracked HTTP sessions |
309
+ | `KEYCHAIN_SESSION_TTL_MS` | `900000` | inactive session TTL |
310
+ | `KEYCHAIN_SESSION_SWEEP_INTERVAL_MS` | `60000` | session cleanup interval |
311
+ | `KEYCHAIN_MAX_HEAP_USED_MB` | `1536` | memory fuse; set `0` to disable |
312
+ | `KEYCHAIN_METRICS_LOG_INTERVAL_MS` | `0` | periodic metrics logging; `0` disables |
316
313
 
317
314
  `KEYCHAIN_TEXT_COMPAT_MODE=structured_json` mirrors supported
318
315
  `structuredContent` into plain text. That helps MCP clients that only pass
@@ -325,7 +322,6 @@ Tool names default to `keychain_*`. Change the prefix with `TOOL_PREFIX` and the
325
322
  separator with `TOOL_SEPARATOR`.
326
323
 
327
324
  Start with these:
328
-
329
325
  - `keychain_status` - inspect raw `bw` status
330
326
  - `keychain_sync` - pull latest vault data with `bw sync`
331
327
  - `keychain_search_items` - find items by name, URI, username, folder,
@@ -338,18 +334,17 @@ Start with these:
338
334
 
339
335
  Full tool groups:
340
336
 
341
- | Group | Tools |
342
- | --- | --- |
343
- | Vault/session | `keychain_status`, `keychain_sync`, `keychain_sdk_version`, `keychain_encode`, `keychain_generate`, `keychain_generate_username` |
344
- | Items | `keychain_search_items`, `keychain_get_item`, `keychain_update_item`, `keychain_create_login`, `keychain_create_logins`, `keychain_set_login_uris`, `keychain_create_note`, `keychain_create_card`, `keychain_create_identity`, `keychain_create_ssh_key`, `keychain_delete_item`, `keychain_delete_items`, `keychain_restore_item` |
345
- | Folders | `keychain_list_folders`, `keychain_create_folder`, `keychain_edit_folder`, `keychain_delete_folder` |
346
- | Organizations and collections | `keychain_list_organizations`, `keychain_list_collections`, `keychain_list_org_collections`, `keychain_create_org_collection`, `keychain_edit_org_collection`, `keychain_delete_org_collection`, `keychain_move_item_to_organization` |
347
- | Attachments | `keychain_create_attachment`, `keychain_delete_attachment`, `keychain_get_attachment` |
348
- | Sends | `keychain_send_list`, `keychain_send_template`, `keychain_send_get`, `keychain_send_create`, `keychain_send_create_encoded`, `keychain_send_edit`, `keychain_send_remove_password`, `keychain_send_delete`, `keychain_receive` |
349
- | Direct `bw get` helpers | `keychain_get_username`, `keychain_get_password`, `keychain_get_totp`, `keychain_get_notes`, `keychain_get_uri`, `keychain_get_exposed`, `keychain_get_folder`, `keychain_get_collection`, `keychain_get_organization`, `keychain_get_org_collection`, `keychain_get_password_history` |
337
+ | Group | Tools |
338
+ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
339
+ | Vault/session | `keychain_status`, `keychain_sync`, `keychain_sdk_version`, `keychain_encode`, `keychain_generate`, `keychain_generate_username` |
340
+ | Items | `keychain_search_items`, `keychain_get_item`, `keychain_update_item`, `keychain_create_login`, `keychain_create_logins`, `keychain_set_login_uris`, `keychain_create_note`, `keychain_create_card`, `keychain_create_identity`, `keychain_create_ssh_key`, `keychain_delete_item`, `keychain_delete_items`, `keychain_restore_item` |
341
+ | Folders | `keychain_list_folders`, `keychain_create_folder`, `keychain_edit_folder`, `keychain_delete_folder` |
342
+ | Organizations and collections | `keychain_list_organizations`, `keychain_list_collections`, `keychain_list_org_collections`, `keychain_create_org_collection`, `keychain_edit_org_collection`, `keychain_delete_org_collection`, `keychain_move_item_to_organization` |
343
+ | Attachments | `keychain_create_attachment`, `keychain_delete_attachment`, `keychain_get_attachment` |
344
+ | Sends | `keychain_send_list`, `keychain_send_template`, `keychain_send_get`, `keychain_send_create`, `keychain_send_create_encoded`, `keychain_send_edit`, `keychain_send_remove_password`, `keychain_send_delete`, `keychain_receive` |
345
+ | Direct `bw get` helpers | `keychain_get_username`, `keychain_get_password`, `keychain_get_totp`, `keychain_get_notes`, `keychain_get_uri`, `keychain_get_exposed`, `keychain_get_folder`, `keychain_get_collection`, `keychain_get_organization`, `keychain_get_org_collection`, `keychain_get_password_history` |
350
346
 
351
347
  Notes:
352
-
353
348
  - `keychain_create_logins` creates several independent login items in one call
354
349
  and reports per-item failures without aborting the whole batch
355
350
  - `keychain_set_login_uris` replaces or merges a login item's URI list without
@@ -379,18 +374,18 @@ account, and runs the MCP server in the foreground.
379
374
 
380
375
  Useful commands:
381
376
 
382
- | Command | Purpose |
383
- | --- | --- |
384
- | `npm run dev` | watch-mode server from source |
385
- | `npm run build` | compile TypeScript to `dist/` |
386
- | `npm run start` | run the compiled server |
387
- | `npm run lint` | Biome autofix plus `tsc --noEmit` |
388
- | `npm run test` | build, then run all compiled tests |
389
- | `npm run test:integration` | build, then run compose-backed integration tests |
390
- | `npm run test:coverage` | build, then run Node test coverage |
391
- | `make test` | run the compose-backed Vaultwarden integration path |
392
- | `make test-org` | run the organization-focused compose stack |
393
- | `make down` | stop the local compose stack |
377
+ | Command | Purpose |
378
+ | -------------------------- | --------------------------------------------------- |
379
+ | `npm run dev` | watch-mode server from source |
380
+ | `npm run build` | compile TypeScript to `dist/` |
381
+ | `npm run start` | run the compiled server |
382
+ | `npm run lint` | Biome autofix plus `tsc --noEmit` |
383
+ | `npm run test` | build, then run all compiled tests |
384
+ | `npm run test:integration` | build, then run compose-backed integration tests |
385
+ | `npm run test:coverage` | build, then run Node test coverage |
386
+ | `make test` | run the compose-backed Vaultwarden integration path |
387
+ | `make test-org` | run the organization-focused compose stack |
388
+ | `make down` | stop the local compose stack |
394
389
 
395
390
  For a quick live MCP smoke against local Vaultwarden, see
396
391
  [agent-instructions/testing.md](agent-instructions/testing.md).
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "private": false,
3
3
  "name": "@icoretech/warden-mcp",
4
- "version": "0.2.54",
4
+ "version": "0.2.56",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "description": "Vaultwarden/Bitwarden MCP server backed by Bitwarden CLI (bw).",
@@ -55,7 +55,7 @@
55
55
  "tmp": "0.2.7"
56
56
  },
57
57
  "devDependencies": {
58
- "@biomejs/biome": "^2.5.15",
58
+ "@biomejs/biome": "2.6.2",
59
59
  "@types/express": "^5.0.6",
60
60
  "@types/node": "^22.20.5",
61
61
  "playwright": "1.64.1",
@@ -67,7 +67,7 @@
67
67
  "access": "public"
68
68
  },
69
69
  "engines": {
70
- "node": "~22.23.3",
70
+ "node": "~22.23.4",
71
71
  "npm": "~10.9.9"
72
72
  }
73
73
  }