@icoretech/warden-mcp 0.2.23 → 0.2.25

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
@@ -580,7 +580,8 @@ npm run dev
580
580
  - 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
581
  - 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
582
  - `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.
583
+ - `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.
584
+ - `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
585
  - 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
586
 
586
587
  Vault/session:
@@ -616,10 +617,10 @@ Attachments:
616
617
  Sends:
617
618
 
618
619
  - `keychain_send_list`, `keychain_send_template`, `keychain_send_get`
619
- - `keychain_send_create` (quick create via `bw send`)
620
+ - `keychain_send_create` (quick create via `bw send`, including optional `emails`)
620
621
  - `keychain_send_create_encoded`, `keychain_send_edit` (advanced create/edit via `bw send create|edit`)
621
622
  - `keychain_send_remove_password`, `keychain_send_delete`
622
- - `keychain_receive`
623
+ - `keychain_receive` (receive shared Sends and download file Send bytes)
623
624
 
624
625
  Direct “bw get …” helpers:
625
626
 
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 [];
@@ -436,6 +423,27 @@ export class KeychainSdk {
436
423
  .filter((id) => typeof id === 'string' && id.length > 0);
437
424
  throw new Error(`Attachment selector matched multiple attachments: ${ids.join(', ')}`);
438
425
  }
426
+ attachmentSelectorNotFoundMessage(item, selector, toolNames) {
427
+ const attachments = this.attachmentsFromItem(item);
428
+ const syncTool = toolNames?.sync ?? 'keychain_sync';
429
+ const getItemTool = toolNames?.getItem ?? 'keychain_get_item';
430
+ const getAttachmentTool = toolNames?.getAttachment ?? 'keychain_get_attachment';
431
+ const available = attachments.length > 0
432
+ ? attachments
433
+ .map((a) => {
434
+ const parts = [];
435
+ if (a.id)
436
+ parts.push(`id=${a.id}`);
437
+ if (a.fileName)
438
+ parts.push(`fileName=${a.fileName}`);
439
+ if (a.sizeName)
440
+ parts.push(`sizeName=${a.sizeName}`);
441
+ return `{${parts.join(' ')}}`;
442
+ })
443
+ .join(', ')
444
+ : 'none';
445
+ return `Attachment selector "${selector}" was not found in the current item metadata. Available attachments: ${available}. If the attachment was recently added or renamed, run ${syncTool}, re-read the item with ${getItemTool}, then retry ${getAttachmentTool} with an attachment id or exact filename from refreshed metadata.`;
446
+ }
439
447
  redactPasswordHistoryForTool(history) {
440
448
  // For secret-returning tools we avoid returning sentinel strings like "[REDACTED]"
441
449
  // because downstream utilities might accidentally pass them through.
@@ -496,7 +504,10 @@ export class KeychainSdk {
496
504
  const { stdout: itemOut } = await this.bw.runForSession(session, ['get', 'item', input.itemId], { timeoutMs: 60_000 });
497
505
  const item = this.parseBwJson(itemOut);
498
506
  const metadata = this.resolveAttachment(item, input.attachmentId);
499
- const attachmentSelector = metadata?.id ?? input.attachmentId;
507
+ if (!metadata) {
508
+ throw new Error(this.attachmentSelectorNotFoundMessage(item, input.attachmentId, input.toolNames));
509
+ }
510
+ const attachmentSelector = metadata.id ?? input.attachmentId;
500
511
  const { stdout, stdoutBuffer } = await this.bw.runForSession(session, [
501
512
  'get',
502
513
  'attachment',
@@ -528,22 +539,14 @@ export class KeychainSdk {
528
539
  });
529
540
  }
530
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
+ }
531
545
  return this.bw.withSession(async (session) => {
532
546
  if (input.text) {
533
547
  const { stdout } = await this.bw.runForSession(session, ['--raw', 'send', 'get', input.id, '--text'], { timeoutMs: 60_000 });
534
548
  return { text: stdout.trim() };
535
549
  }
536
- if (input.downloadFile) {
537
- const dir = await mkdtemp(join(tmpdir(), 'keychain-sendfile-'));
538
- try {
539
- await this.bw.runForSession(session, ['send', 'get', input.id, '--output', dir], { timeoutMs: 120_000 });
540
- const file = await this.readSingleFileAsBase64(dir);
541
- return { file };
542
- }
543
- finally {
544
- await rm(dir, { recursive: true, force: true });
545
- }
546
- }
547
550
  const { stdout } = await this.bw.runForSession(session, ['send', 'get', input.id], {
548
551
  timeoutMs: 60_000,
549
552
  });
@@ -567,12 +570,20 @@ export class KeychainSdk {
567
570
  async sendCreate(input) {
568
571
  return this.bw.withSession(async (session) => {
569
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
+ }
570
579
  if (input.type === 'file')
571
580
  args.push('--file');
572
581
  if (typeof input.deleteInDays === 'number')
573
582
  args.push('--deleteInDays', String(input.deleteInDays));
574
583
  if (typeof input.password === 'string')
575
584
  args.push('--password', input.password);
585
+ if (emails && emails.length > 0)
586
+ args.push('--emails', emails.join(','));
576
587
  if (typeof input.maxAccessCount === 'number')
577
588
  args.push('--maxAccessCount', String(input.maxAccessCount));
578
589
  if (input.hidden)
@@ -180,6 +180,7 @@ export function registerTools(server, deps) {
180
180
  .filter((attachment) => attachment !== null);
181
181
  if (attachments.length > 0) {
182
182
  parts.push(`attachments=${quoteText(attachments.join(', '))}`);
183
+ parts.push(`attachmentDownload=${quoteText(`${publicPrefix}get_attachment with this item id plus an attachment id or exact filename; if an expected file is missing, run ${publicPrefix}sync and ${publicPrefix}get_item again first`)}`);
183
184
  }
184
185
  }
185
186
  if (typeof rec.favorite === 'boolean')
@@ -353,6 +354,12 @@ export function registerTools(server, deps) {
353
354
  .string()
354
355
  .optional()
355
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.');
356
363
  const itemFieldSchema = z
357
364
  .object({
358
365
  name: z.string().describe('Custom field name stored on the item.'),
@@ -985,7 +992,7 @@ export function registerTools(server, deps) {
985
992
  });
986
993
  registerTool(`${deps.toolPrefix}.get_item`, {
987
994
  title: 'Get Item',
988
- description: 'Get the full vault item by stable item id. Secret fields and signed attachment URLs are redacted by default; pass reveal=true only when the caller is allowed to receive secrets.',
995
+ description: `Get the full vault item by stable item id. Secret fields and signed attachment URLs are redacted by default; pass reveal=true only when the caller is allowed to receive secrets. When attachments are present, use ${publicPrefix}get_attachment with this item id plus the listed attachment id or filename to download file bytes. If an expected recently-added attachment is missing, run ${publicPrefix}sync and call ${publicPrefix}get_item again before retrying.`,
989
996
  annotations: { readOnlyHint: true },
990
997
  inputSchema: {
991
998
  id: stableObjectIdSchema,
@@ -1252,7 +1259,7 @@ export function registerTools(server, deps) {
1252
1259
  });
1253
1260
  registerTool(`${deps.toolPrefix}.get_attachment`, {
1254
1261
  title: 'Get Attachment',
1255
- description: 'Download an attachment from a parent item and return raw bytes as contentBase64. Pass itemId plus an attachment id, or an unambiguous filename selector resolved from the item metadata before calling bw get attachment. The response includes filename, byte count, and base64 content for local decoding.',
1262
+ description: `Download an attachment from a parent item and return raw bytes as contentBase64. Pass itemId plus an attachment id, or an unambiguous filename selector resolved from the item metadata before calling bw get attachment. The response includes filename, byte count, and base64 content for local decoding. If the expected attachment filename is missing from ${publicPrefix}get_item metadata, run ${publicPrefix}sync and ${publicPrefix}get_item again before retrying.`,
1256
1263
  annotations: { readOnlyHint: true },
1257
1264
  inputSchema: {
1258
1265
  itemId: itemIdSchema,
@@ -1261,7 +1268,14 @@ export function registerTools(server, deps) {
1261
1268
  _meta: toolMeta,
1262
1269
  }, async (input, extra) => {
1263
1270
  const sdk = await deps.getSdk(extra.authInfo);
1264
- const attachment = await sdk.getAttachment(input);
1271
+ const attachment = await sdk.getAttachment({
1272
+ ...input,
1273
+ toolNames: {
1274
+ sync: `${publicPrefix}sync`,
1275
+ getItem: `${publicPrefix}get_item`,
1276
+ getAttachment: `${publicPrefix}get_attachment`,
1277
+ },
1278
+ });
1265
1279
  const structuredContent = { attachment };
1266
1280
  return {
1267
1281
  structuredContent,
@@ -1304,7 +1318,7 @@ export function registerTools(server, deps) {
1304
1318
  });
1305
1319
  registerTool(`${deps.toolPrefix}.send_get`, {
1306
1320
  title: 'Send Get',
1307
- 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.',
1308
1322
  annotations: { readOnlyHint: true, openWorldHint: true },
1309
1323
  inputSchema: {
1310
1324
  id: stableObjectIdSchema,
@@ -1312,10 +1326,6 @@ export function registerTools(server, deps) {
1312
1326
  .boolean()
1313
1327
  .optional()
1314
1328
  .describe('Return the Send text content instead of JSON metadata.'),
1315
- downloadFile: z
1316
- .boolean()
1317
- .optional()
1318
- .describe('Download a file Send and return its file bytes.'),
1319
1329
  },
1320
1330
  _meta: toolMeta,
1321
1331
  }, async (input, extra) => {
@@ -1329,7 +1339,7 @@ export function registerTools(server, deps) {
1329
1339
  });
1330
1340
  registerTool(`${deps.toolPrefix}.send_create`, {
1331
1341
  title: 'Send Create',
1332
- 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.',
1333
1343
  annotations: {
1334
1344
  readOnlyHint: false,
1335
1345
  destructiveHint: false,
@@ -1356,6 +1366,7 @@ export function registerTools(server, deps) {
1356
1366
  .string()
1357
1367
  .optional()
1358
1368
  .describe('Optional Send access password required by recipients.'),
1369
+ emails: sendEmailsSchema,
1359
1370
  maxAccessCount: z
1360
1371
  .number()
1361
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.23",
4
+ "version": "0.2.25",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "description": "Vaultwarden/Bitwarden MCP server backed by Bitwarden CLI (bw).",
@@ -52,9 +52,9 @@
52
52
  "@bitwarden/cli": "2026.5.0"
53
53
  },
54
54
  "devDependencies": {
55
- "@biomejs/biome": "^2.4.16",
55
+ "@biomejs/biome": "^2.5.0",
56
56
  "@types/express": "^5.0.6",
57
- "@types/node": "^25.9.2",
57
+ "@types/node": "^25.9.3",
58
58
  "playwright": "1.60.0",
59
59
  "tsx": "^4.22.4",
60
60
  "typescript": "^6.0.3"