@icoretech/warden-mcp 0.2.17 → 0.2.19

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
@@ -567,6 +567,14 @@ npm run dev
567
567
 
568
568
  ## Tool Reference (v1)
569
569
 
570
+ ### Choosing the right tool
571
+
572
+ - 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.
573
+ - 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.
574
+ - `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.
575
+ - `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.
576
+ - 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.
577
+
570
578
  Vault/session:
571
579
 
572
580
  - `keychain_status`
@@ -594,6 +602,8 @@ Orgs/collections:
594
602
  Attachments:
595
603
 
596
604
  - `keychain_create_attachment`, `keychain_delete_attachment`, `keychain_get_attachment`
605
+ - `keychain_get_item` exposes safe attachment metadata (`id`, `fileName`, size) while redacting signed download URLs, so clients can discover the exact attachment id before downloading
606
+ - `keychain_get_attachment` accepts an attachment id or an unambiguous filename and returns `{ filename, bytes, contentBase64 }`; decode `contentBase64` locally when you need the original file bytes
597
607
 
598
608
  Sends:
599
609
 
package/dist/bw/bwCli.js CHANGED
@@ -164,7 +164,7 @@ export async function runBw(args, opts = {}) {
164
164
  if (debug) {
165
165
  console.log(`[bw] ok: ms=${Date.now() - startedAt}`);
166
166
  }
167
- resolve({ stdout, stderr });
167
+ resolve({ stdout, stdoutBuffer: Buffer.concat(stdoutChunks), stderr });
168
168
  });
169
169
  });
170
170
  });
@@ -376,6 +376,42 @@ export class KeychainSdk {
376
376
  contentBase64: buf.toString('base64'),
377
377
  };
378
378
  }
379
+ attachmentsFromItem(item) {
380
+ if (!item || typeof item !== 'object')
381
+ return [];
382
+ const attachments = item.attachments;
383
+ if (!Array.isArray(attachments))
384
+ return [];
385
+ return attachments
386
+ .filter((a) => Boolean(a) && typeof a === 'object')
387
+ .map((a) => ({
388
+ id: typeof a.id === 'string' ? a.id : undefined,
389
+ fileName: typeof a.fileName === 'string' ? a.fileName : undefined,
390
+ size: typeof a.size === 'string' || typeof a.size === 'number'
391
+ ? a.size
392
+ : undefined,
393
+ sizeName: typeof a.sizeName === 'string' ? a.sizeName : undefined,
394
+ }));
395
+ }
396
+ resolveAttachment(item, selector) {
397
+ const needle = selector.toLowerCase();
398
+ const matches = this.attachmentsFromItem(item).filter((a) => {
399
+ const id = a.id?.toLowerCase();
400
+ const fileName = a.fileName?.toLowerCase();
401
+ return id === needle || Boolean(fileName?.includes(needle));
402
+ });
403
+ const exactFileNameMatches = matches.filter((a) => a.fileName?.toLowerCase() === needle);
404
+ if (exactFileNameMatches.length === 1)
405
+ return exactFileNameMatches[0];
406
+ if (matches.length === 0)
407
+ return null;
408
+ if (matches.length === 1)
409
+ return matches[0];
410
+ const ids = matches
411
+ .map((a) => a.id)
412
+ .filter((id) => typeof id === 'string' && id.length > 0);
413
+ throw new Error(`Attachment selector matched multiple attachments: ${ids.join(', ')}`);
414
+ }
379
415
  redactPasswordHistoryForTool(history) {
380
416
  // For secret-returning tools we avoid returning sentinel strings like "[REDACTED]"
381
417
  // because downstream utilities might accidentally pass them through.
@@ -433,22 +469,24 @@ export class KeychainSdk {
433
469
  }
434
470
  async getAttachment(input) {
435
471
  return this.bw.withSession(async (session) => {
436
- const dir = await mkdtemp(join(tmpdir(), 'keychain-attachment-'));
437
- try {
438
- await this.bw.runForSession(session, [
439
- 'get',
440
- 'attachment',
441
- input.attachmentId,
442
- '--itemid',
443
- input.itemId,
444
- '--output',
445
- dir,
446
- ], { timeoutMs: 120_000 });
447
- return await this.readSingleFileAsBase64(dir);
448
- }
449
- finally {
450
- await rm(dir, { recursive: true, force: true });
451
- }
472
+ const { stdout: itemOut } = await this.bw.runForSession(session, ['get', 'item', input.itemId], { timeoutMs: 60_000 });
473
+ const item = this.parseBwJson(itemOut);
474
+ const metadata = this.resolveAttachment(item, input.attachmentId);
475
+ const attachmentSelector = metadata?.id ?? input.attachmentId;
476
+ const { stdout, stdoutBuffer } = await this.bw.runForSession(session, [
477
+ 'get',
478
+ 'attachment',
479
+ attachmentSelector,
480
+ '--itemid',
481
+ input.itemId,
482
+ '--raw',
483
+ ], { timeoutMs: 120_000 });
484
+ const buf = stdoutBuffer ?? Buffer.from(stdout, 'utf8');
485
+ return {
486
+ filename: metadata?.fileName ?? input.attachmentId,
487
+ bytes: buf.byteLength,
488
+ contentBase64: buf.toString('base64'),
489
+ };
452
490
  });
453
491
  }
454
492
  async sendList() {