@icoretech/warden-mcp 0.2.24 → 0.2.26

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
@@ -203,14 +203,6 @@ codex mcp add warden \
203
203
 
204
204
  # Claude Code
205
205
  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
206
  ```
215
207
 
216
208
  ### JSON config hosts
@@ -220,7 +212,6 @@ These hosts all use the same stdio payload shape. Only the config file location
220
212
  - Codex: `~/.codex/config.toml`
221
213
  - Cursor: `~/.cursor/mcp.json` or `.cursor/mcp.json`
222
214
  - Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`
223
- - Qwen Code: `~/.qwen/settings.json` or `.qwen/settings.json`
224
215
 
225
216
  Shared JSON shape:
226
217
 
@@ -260,27 +251,6 @@ BW_PASSWORD = "your-master-password"
260
251
  because a cold first launch can spend several seconds downloading and unpacking
261
252
  the package before MCP initialization begins.
262
253
 
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
254
  ### Shared HTTP connections
285
255
 
286
256
  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.
@@ -388,40 +358,6 @@ claude mcp add-json warden '{"type":"http","url":"http://localhost:3005/sse?v=2"
388
358
  }
389
359
  ```
390
360
 
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
361
  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
362
 
427
363
  ### Verify bw is available
@@ -580,7 +516,8 @@ npm run dev
580
516
  - 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.
581
517
  - 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
518
  - `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
- - `keychain_send_create` is the quick path for text or file Sends through the normal `bw send` flags. `keychain_send_template`, `keychain_send_create_encoded`, and `keychain_send_edit` are for the full Bitwarden Send JSON template or an encoded edit payload.
519
+ - `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.
520
+ - `keychain_send_get` returns owned Send metadata, including `accessUrl`, or text content with `text=true`. To download a file Send, pass that `accessUrl` to `keychain_receive` with `downloadFile=true`; the bundled `bw send get` command does not implement file download output.
584
521
  - Pass `reveal: true` only to tools that can return secrets, such as password, TOTP, notes, generated secrets, password history, or full item reads. By default these stay redacted. Text-only MCP clients follow the same reveal contract described in [Text-Only MCP Client Behavior](#text-only-mcp-client-behavior), and server-side `NOREVEAL` settings still win.
585
522
 
586
523
  Vault/session:
@@ -616,10 +553,10 @@ Attachments:
616
553
  Sends:
617
554
 
618
555
  - `keychain_send_list`, `keychain_send_template`, `keychain_send_get`
619
- - `keychain_send_create` (quick create via `bw send`)
556
+ - `keychain_send_create` (quick create via `bw send`, including optional `emails`)
620
557
  - `keychain_send_create_encoded`, `keychain_send_edit` (advanced create/edit via `bw send create|edit`)
621
558
  - `keychain_send_remove_password`, `keychain_send_delete`
622
- - `keychain_receive`
559
+ - `keychain_receive` (receive shared Sends and download file Send bytes)
623
560
 
624
561
  Direct “bw get …” helpers:
625
562
 
package/dist/bw/bwCli.js CHANGED
@@ -1,6 +1,15 @@
1
1
  // src/bw/bwCli.ts
2
2
  import { spawn } from 'node:child_process';
3
3
  import { resolveBundledBwBin } from './resolveBwBin.js';
4
+ const SENSITIVE_ARG_FLAGS = new Set([
5
+ '--apikey',
6
+ '--clientsecret',
7
+ '--emails',
8
+ '--password',
9
+ '--passwordenv',
10
+ '--passwordfile',
11
+ '--session',
12
+ ]);
4
13
  export class BwCliError extends Error {
5
14
  exitCode;
6
15
  stdout;
@@ -67,8 +76,8 @@ export async function runBw(args, opts = {}) {
67
76
  const out = [];
68
77
  for (let i = 0; i < argv.length; i++) {
69
78
  const a = argv[i];
70
- if (a === '--session') {
71
- out.push('--session');
79
+ if (typeof a === 'string' && SENSITIVE_ARG_FLAGS.has(a)) {
80
+ out.push(a);
72
81
  if (i + 1 < argv.length) {
73
82
  out.push('<redacted>');
74
83
  i++;
@@ -1,5 +1,5 @@
1
1
  // src/sdk/keychainSdk.ts
2
- import { mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises';
2
+ import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
3
3
  import { tmpdir } from 'node:os';
4
4
  import { basename, join } from 'node:path';
5
5
  import { BwCliError, isBwAuthSessionInvalidError } from '../bw/bwCli.js';
@@ -387,19 +387,6 @@ export class KeychainSdk {
387
387
  return trimmed;
388
388
  }
389
389
  }
390
- async readSingleFileAsBase64(dir) {
391
- const files = await readdir(dir);
392
- if (files.length !== 1) {
393
- throw new Error(`Expected exactly 1 downloaded file, found ${files.length}`);
394
- }
395
- const filename = files[0] ?? '';
396
- const buf = await readFile(join(dir, filename));
397
- return {
398
- filename,
399
- bytes: buf.byteLength,
400
- contentBase64: buf.toString('base64'),
401
- };
402
- }
403
390
  attachmentsFromItem(item) {
404
391
  if (!item || typeof item !== 'object')
405
392
  return [];
@@ -552,22 +539,14 @@ export class KeychainSdk {
552
539
  });
553
540
  }
554
541
  async sendGet(input) {
542
+ if (input.downloadFile) {
543
+ throw new Error('keychain_send_get cannot download file Sends because bw send get --output is not implemented by the bundled Bitwarden CLI; use keychain_receive with the Send accessUrl and downloadFile=true instead');
544
+ }
555
545
  return this.bw.withSession(async (session) => {
556
546
  if (input.text) {
557
547
  const { stdout } = await this.bw.runForSession(session, ['--raw', 'send', 'get', input.id, '--text'], { timeoutMs: 60_000 });
558
548
  return { text: stdout.trim() };
559
549
  }
560
- if (input.downloadFile) {
561
- const dir = await mkdtemp(join(tmpdir(), 'keychain-sendfile-'));
562
- try {
563
- await this.bw.runForSession(session, ['send', 'get', input.id, '--output', dir], { timeoutMs: 120_000 });
564
- const file = await this.readSingleFileAsBase64(dir);
565
- return { file };
566
- }
567
- finally {
568
- await rm(dir, { recursive: true, force: true });
569
- }
570
- }
571
550
  const { stdout } = await this.bw.runForSession(session, ['send', 'get', input.id], {
572
551
  timeoutMs: 60_000,
573
552
  });
@@ -591,12 +570,20 @@ export class KeychainSdk {
591
570
  async sendCreate(input) {
592
571
  return this.bw.withSession(async (session) => {
593
572
  const args = ['send'];
573
+ const emails = input.emails
574
+ ?.map((email) => email.trim())
575
+ .filter((email) => email.length > 0);
576
+ if (emails && emails.length > 0 && typeof input.password === 'string') {
577
+ throw new Error('Send emails and password are mutually exclusive');
578
+ }
594
579
  if (input.type === 'file')
595
580
  args.push('--file');
596
581
  if (typeof input.deleteInDays === 'number')
597
582
  args.push('--deleteInDays', String(input.deleteInDays));
598
583
  if (typeof input.password === 'string')
599
584
  args.push('--password', input.password);
585
+ if (emails && emails.length > 0)
586
+ args.push('--emails', emails.join(','));
600
587
  if (typeof input.maxAccessCount === 'number')
601
588
  args.push('--maxAccessCount', String(input.maxAccessCount));
602
589
  if (input.hidden)
@@ -354,6 +354,12 @@ export function registerTools(server, deps) {
354
354
  .string()
355
355
  .optional()
356
356
  .describe('Visible filename required with contentBase64 for file sends.');
357
+ const sendEmailsSchema = z
358
+ .array(z.string().trim().email())
359
+ .min(1)
360
+ .max(50)
361
+ .optional()
362
+ .describe('Recipient email addresses for Bitwarden Send email-gated access. Mutually exclusive with password; callers still need to share the Send URL.');
357
363
  const itemFieldSchema = z
358
364
  .object({
359
365
  name: z.string().describe('Custom field name stored on the item.'),
@@ -1312,7 +1318,7 @@ export function registerTools(server, deps) {
1312
1318
  });
1313
1319
  registerTool(`${deps.toolPrefix}.send_get`, {
1314
1320
  title: 'Send Get',
1315
- description: 'Get Sends owned by you. Use text=true to return text content; downloadFile=true to download a file send (bw send get).',
1321
+ description: 'Get Sends owned by you. Use text=true to return text content; file Sends return metadata including accessUrl. To download file Send bytes, call receive with that accessUrl and downloadFile=true.',
1316
1322
  annotations: { readOnlyHint: true, openWorldHint: true },
1317
1323
  inputSchema: {
1318
1324
  id: stableObjectIdSchema,
@@ -1320,10 +1326,6 @@ export function registerTools(server, deps) {
1320
1326
  .boolean()
1321
1327
  .optional()
1322
1328
  .describe('Return the Send text content instead of JSON metadata.'),
1323
- downloadFile: z
1324
- .boolean()
1325
- .optional()
1326
- .describe('Download a file Send and return its file bytes.'),
1327
1329
  },
1328
1330
  _meta: toolMeta,
1329
1331
  }, async (input, extra) => {
@@ -1337,7 +1339,7 @@ export function registerTools(server, deps) {
1337
1339
  });
1338
1340
  registerTool(`${deps.toolPrefix}.send_create`, {
1339
1341
  title: 'Send Create',
1340
- description: 'Quick-create a Bitwarden Send through bw send. Use type=text with text, or type=file with filename plus contentBase64; deleteInDays controls expiration deletion, maxAccessCount limits accesses, and password protects the Send. For advanced JSON templates or edits, use send_create_encoded and send_edit instead.',
1342
+ description: 'Quick-create a Bitwarden Send through bw send. Use type=text with text, or type=file with filename plus contentBase64; deleteInDays controls expiration deletion, maxAccessCount limits accesses, password protects the Send, and emails grant email-gated access. For advanced JSON templates or edits, use send_create_encoded and send_edit instead.',
1341
1343
  annotations: {
1342
1344
  readOnlyHint: false,
1343
1345
  destructiveHint: false,
@@ -1364,6 +1366,7 @@ export function registerTools(server, deps) {
1364
1366
  .string()
1365
1367
  .optional()
1366
1368
  .describe('Optional Send access password required by recipients.'),
1369
+ emails: sendEmailsSchema,
1367
1370
  maxAccessCount: z
1368
1371
  .number()
1369
1372
  .int()
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "private": false,
3
3
  "name": "@icoretech/warden-mcp",
4
- "version": "0.2.24",
4
+ "version": "0.2.26",
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
61
  "@types/node": "^25.9.3",
58
- "playwright": "1.60.0",
62
+ "playwright": "1.61.0",
59
63
  "tsx": "^4.22.4",
60
64
  "typescript": "^6.0.3"
61
65
  },