@icoretech/warden-mcp 0.2.18 → 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.
@@ -58,6 +58,40 @@ export function registerTools(server, deps) {
58
58
  function toolResult(kind, value, revealed, extra) {
59
59
  return { result: { kind, value, revealed, ...(extra ?? {}) } };
60
60
  }
61
+ function valueResultOutputSchema(kind) {
62
+ return {
63
+ result: z.object({
64
+ kind: z.literal(kind),
65
+ value: z.string().nullable(),
66
+ revealed: z.boolean(),
67
+ }),
68
+ };
69
+ }
70
+ const statusOutputSchema = { status: z.unknown() };
71
+ const sdkVersionOutputSchema = { version: z.string() };
72
+ const encodeOutputSchema = { encoded: z.string() };
73
+ const generatedResultOutputSchema = valueResultOutputSchema('generated');
74
+ const usernameResultOutputSchema = valueResultOutputSchema('username');
75
+ const passwordResultOutputSchema = valueResultOutputSchema('password');
76
+ const notesResultOutputSchema = valueResultOutputSchema('notes');
77
+ const uriResultOutputSchema = valueResultOutputSchema('uri');
78
+ const exposedResultOutputSchema = valueResultOutputSchema('exposed');
79
+ const totpResultOutputSchema = {
80
+ result: z.object({
81
+ kind: z.literal('totp'),
82
+ value: z.string().nullable(),
83
+ revealed: z.boolean(),
84
+ period: z.number().nullable(),
85
+ timeLeft: z.number().nullable(),
86
+ }),
87
+ };
88
+ const passwordHistoryResultOutputSchema = {
89
+ result: z.object({
90
+ kind: z.literal('password_history'),
91
+ value: z.array(z.unknown()),
92
+ revealed: z.boolean(),
93
+ }),
94
+ };
61
95
  function toolTextContent(structuredContent, fallbackText) {
62
96
  const text = textCompatMode === 'structured_json'
63
97
  ? JSON.stringify(structuredContent)
@@ -216,6 +250,187 @@ export function registerTools(server, deps) {
216
250
  // bw uses numeric match values internally (0..5)
217
251
  z.number().int().min(0).max(5),
218
252
  ]);
253
+ const stableObjectIdSchema = z
254
+ .string()
255
+ .describe('Stable Bitwarden object id returned by list/search/get/create tools.');
256
+ const itemIdSchema = z
257
+ .string()
258
+ .describe('Parent Bitwarden item id for attachment or item-specific operations.');
259
+ const attachmentIdSchema = z
260
+ .string()
261
+ .describe('Attachment id returned by item metadata, or an unambiguous filename selector for downloads.');
262
+ const organizationIdSchema = z
263
+ .string()
264
+ .describe('Bitwarden organization id; required for org-scoped collection operations.');
265
+ const optionalOrganizationIdSchema = z
266
+ .string()
267
+ .optional()
268
+ .describe('Bitwarden organization id; used for org-scoped collection operations.');
269
+ const collectionIdSchema = z
270
+ .string()
271
+ .optional()
272
+ .describe('Bitwarden collection id, not a folder id.');
273
+ const collectionIdsSchema = z
274
+ .array(z.string())
275
+ .optional()
276
+ .describe('Bitwarden collection ids, not folder ids.');
277
+ const folderIdSchema = z
278
+ .string()
279
+ .optional()
280
+ .describe('Personal folder id, not an organization collection id.');
281
+ const searchSchema = z
282
+ .string()
283
+ .optional()
284
+ .describe('Optional text filter; empty means no text filter.');
285
+ const limitSchema = z
286
+ .number()
287
+ .int()
288
+ .min(1)
289
+ .max(500)
290
+ .optional()
291
+ .describe('Maximum returned rows (1-500).');
292
+ const revealSchema = z
293
+ .boolean()
294
+ .optional()
295
+ .describe('Whether secret values are returned; default false and can be forced false by NOREVEAL.');
296
+ const uriSchema = z
297
+ .string()
298
+ .describe('URI value to store on the login item.');
299
+ const uriMatchInputDescription = 'URI match semantics: domain, host, startsWith, exact, regex, or never; aliases and numeric values are normalized.';
300
+ const optionalUriMatchSchema = uriMatchInputSchema
301
+ .optional()
302
+ .describe(uriMatchInputDescription);
303
+ const uriEntrySchema = z
304
+ .object({
305
+ uri: uriSchema,
306
+ match: optionalUriMatchSchema,
307
+ })
308
+ .describe('URI entry with match semantics for a login item.');
309
+ const urisSchema = z
310
+ .array(uriEntrySchema)
311
+ .optional()
312
+ .describe('URI entries to store or update on the login item.');
313
+ const optionalModeSchema = z
314
+ .enum(['replace', 'merge'])
315
+ .optional()
316
+ .describe('URI merge behavior: replace overwrites the full list; merge updates existing URIs and adds new ones by URI.');
317
+ const contentBase64Schema = z
318
+ .string()
319
+ .describe('Base64-encoded file bytes, not a filesystem path.');
320
+ const optionalContentBase64Schema = z
321
+ .string()
322
+ .optional()
323
+ .describe('Base64-encoded file bytes for file sends, not a filesystem path.');
324
+ const filenameSchema = z
325
+ .string()
326
+ .describe('Visible attachment or send filename stored in Bitwarden metadata.');
327
+ const optionalFilenameSchema = z
328
+ .string()
329
+ .optional()
330
+ .describe('Visible filename required with contentBase64 for file sends.');
331
+ const itemFieldSchema = z
332
+ .object({
333
+ name: z.string().describe('Custom field name stored on the item.'),
334
+ value: z.string().describe('Custom field value stored on the item.'),
335
+ hidden: z
336
+ .boolean()
337
+ .optional()
338
+ .describe('Hide the field value in summaries when true.'),
339
+ })
340
+ .describe('Custom field stored on the item.');
341
+ const itemFieldsSchema = z
342
+ .array(itemFieldSchema)
343
+ .optional()
344
+ .describe('Custom fields to store on the item. Hidden fields are redacted in summaries.');
345
+ const itemAttachmentSchema = z
346
+ .object({
347
+ filename: filenameSchema,
348
+ contentBase64: contentBase64Schema,
349
+ })
350
+ .describe('Attachment file payload to add to the item.');
351
+ const itemAttachmentsSchema = z
352
+ .array(itemAttachmentSchema)
353
+ .optional()
354
+ .describe('Attachments to add to the item.');
355
+ const identitySchema = z
356
+ .object({
357
+ title: z
358
+ .string()
359
+ .optional()
360
+ .describe('Honorific or title for the identity.'),
361
+ firstName: z.string().optional().describe('Given name for the identity.'),
362
+ middleName: z
363
+ .string()
364
+ .optional()
365
+ .describe('Middle name for the identity.'),
366
+ lastName: z.string().optional().describe('Family name for the identity.'),
367
+ address1: z.string().optional().describe('Primary street address line.'),
368
+ address2: z
369
+ .string()
370
+ .optional()
371
+ .describe('Secondary street address line.'),
372
+ address3: z.string().optional().describe('Tertiary street address line.'),
373
+ city: z.string().optional().describe('City for the identity.'),
374
+ state: z
375
+ .string()
376
+ .optional()
377
+ .describe('State, province, or region for the identity.'),
378
+ postalCode: z
379
+ .string()
380
+ .optional()
381
+ .describe('Postal or ZIP code for the identity.'),
382
+ country: z.string().optional().describe('Country for the identity.'),
383
+ company: z.string().optional().describe('Company or organization name.'),
384
+ email: z.string().optional().describe('Email address for the identity.'),
385
+ phone: z.string().optional().describe('Phone number for the identity.'),
386
+ ssn: z
387
+ .string()
388
+ .optional()
389
+ .describe('Social security number or equivalent national id.'),
390
+ username: z
391
+ .string()
392
+ .optional()
393
+ .describe('Username associated with the identity.'),
394
+ passportNumber: z
395
+ .string()
396
+ .optional()
397
+ .describe('Passport number associated with the identity.'),
398
+ licenseNumber: z
399
+ .string()
400
+ .optional()
401
+ .describe('Driver license or similar id number for the identity.'),
402
+ })
403
+ .optional()
404
+ .describe('Structured identity profile data to store on the item.');
405
+ const updateLoginSchema = z
406
+ .object({
407
+ username: z.string().optional().describe('Login username to update.'),
408
+ password: z.string().optional().describe('Login password to update.'),
409
+ totp: z
410
+ .string()
411
+ .optional()
412
+ .describe('TOTP secret or otpauth value to update.'),
413
+ uris: urisSchema.describe('Login URIs to replace on the existing item.'),
414
+ })
415
+ .optional()
416
+ .describe('Login-specific fields to patch on the item.');
417
+ const patchSchema = z
418
+ .object({
419
+ name: z.string().optional().describe('New item name.'),
420
+ notes: z.string().optional().describe('New notes text for the item.'),
421
+ favorite: z
422
+ .boolean()
423
+ .optional()
424
+ .describe('Mark the item as a favorite when true.'),
425
+ folderId: z
426
+ .union([z.string(), z.null()])
427
+ .optional()
428
+ .describe('Personal folder id, not an organization collection id.'),
429
+ collectionIds: collectionIdsSchema.describe('Collection ids to replace on the item.'),
430
+ login: updateLoginSchema,
431
+ fields: itemFieldsSchema.describe('Custom fields to replace on the item.'),
432
+ })
433
+ .describe('Partial item fields to update on the current item.');
219
434
  function normalizeUriMatchInput(match) {
220
435
  if (match === 'base_domain' || match === 'baseDomain')
221
436
  return 'domain';
@@ -249,6 +464,7 @@ export function registerTools(server, deps) {
249
464
  description: 'Returns Bitwarden CLI status (locked/unlocked, server, user). This is a lazy check: not-ready status does not mean later keychain tool calls cannot unlock or recover on demand.',
250
465
  annotations: { readOnlyHint: true },
251
466
  inputSchema: {},
467
+ outputSchema: statusOutputSchema,
252
468
  _meta: toolMeta,
253
469
  }, async (_input, extra) => {
254
470
  const sdk = await deps.getSdk(extra.authInfo);
@@ -286,9 +502,10 @@ export function registerTools(server, deps) {
286
502
  });
287
503
  registerTool(`${deps.toolPrefix}.sdk_version`, {
288
504
  title: 'SDK Version',
289
- description: 'Returns the Bitwarden SDK version used by the CLI.',
505
+ description: 'Return the Bitwarden SDK version reported by the bundled bw CLI. Use this read-only check when diagnosing CLI/runtime compatibility without touching vault data.',
290
506
  annotations: { readOnlyHint: true },
291
507
  inputSchema: {},
508
+ outputSchema: sdkVersionOutputSchema,
292
509
  _meta: toolMeta,
293
510
  }, async (_input, extra) => {
294
511
  const sdk = await deps.getSdk(extra.authInfo);
@@ -300,11 +517,12 @@ export function registerTools(server, deps) {
300
517
  });
301
518
  registerTool(`${deps.toolPrefix}.encode`, {
302
519
  title: 'Encode',
303
- description: 'Base64-encode a string (bw encode).',
520
+ description: 'Base64-encode a string with bw encode. This never mutates the vault; it only returns encoded text.',
304
521
  annotations: { readOnlyHint: true },
305
522
  inputSchema: {
306
- value: z.string(),
523
+ value: z.string().describe('Plain text value to base64-encode.'),
307
524
  },
525
+ outputSchema: encodeOutputSchema,
308
526
  _meta: toolMeta,
309
527
  }, async (input, extra) => {
310
528
  const sdk = await deps.getSdk(extra.authInfo);
@@ -316,24 +534,76 @@ export function registerTools(server, deps) {
316
534
  });
317
535
  registerTool(`${deps.toolPrefix}.generate`, {
318
536
  title: 'Generate',
319
- description: 'Generate a password/passphrase (bw generate). Returning the value requires reveal=true.',
537
+ description: 'Generate a password or passphrase with bw generate. This never mutates the vault; pass reveal=true to return the value, and NOREVEAL or KEYCHAIN_NOREVEAL force redaction.',
320
538
  annotations: { readOnlyHint: true },
321
539
  inputSchema: {
322
- uppercase: z.boolean().optional(),
323
- lowercase: z.boolean().optional(),
324
- number: z.boolean().optional(),
325
- special: z.boolean().optional(),
326
- passphrase: z.boolean().optional(),
327
- length: z.number().int().min(5).max(256).optional(),
328
- words: z.number().int().min(3).max(50).optional(),
329
- minNumber: z.number().int().min(0).max(50).optional(),
330
- minSpecial: z.number().int().min(0).max(50).optional(),
331
- separator: z.string().optional(),
332
- capitalize: z.boolean().optional(),
333
- includeNumber: z.boolean().optional(),
334
- ambiguous: z.boolean().optional(),
335
- reveal: z.boolean().optional(),
540
+ uppercase: z
541
+ .boolean()
542
+ .optional()
543
+ .describe('Include uppercase letters when generating a password.'),
544
+ lowercase: z
545
+ .boolean()
546
+ .optional()
547
+ .describe('Include lowercase letters when generating a password.'),
548
+ number: z
549
+ .boolean()
550
+ .optional()
551
+ .describe('Include numeric digits when generating a password.'),
552
+ special: z
553
+ .boolean()
554
+ .optional()
555
+ .describe('Include special characters when generating a password.'),
556
+ passphrase: z
557
+ .boolean()
558
+ .optional()
559
+ .describe('Generate a word-based passphrase instead of a password.'),
560
+ length: z
561
+ .number()
562
+ .int()
563
+ .min(5)
564
+ .max(256)
565
+ .optional()
566
+ .describe('Password length in characters, between 5 and 256.'),
567
+ words: z
568
+ .number()
569
+ .int()
570
+ .min(3)
571
+ .max(50)
572
+ .optional()
573
+ .describe('Passphrase word count, between 3 and 50.'),
574
+ minNumber: z
575
+ .number()
576
+ .int()
577
+ .min(0)
578
+ .max(50)
579
+ .optional()
580
+ .describe('Minimum number of digits to include.'),
581
+ minSpecial: z
582
+ .number()
583
+ .int()
584
+ .min(0)
585
+ .max(50)
586
+ .optional()
587
+ .describe('Minimum number of special characters to include.'),
588
+ separator: z
589
+ .string()
590
+ .optional()
591
+ .describe('Separator to use between words in passphrase mode.'),
592
+ capitalize: z
593
+ .boolean()
594
+ .optional()
595
+ .describe('Capitalize passphrase words when supported by bw.'),
596
+ includeNumber: z
597
+ .boolean()
598
+ .optional()
599
+ .describe('Include a number in passphrase mode when supported by bw.'),
600
+ ambiguous: z
601
+ .boolean()
602
+ .optional()
603
+ .describe('Allow ambiguous characters in generated passwords.'),
604
+ reveal: revealSchema,
336
605
  },
606
+ outputSchema: generatedResultOutputSchema,
337
607
  _meta: toolMeta,
338
608
  }, async (input, extra) => {
339
609
  const sdk = await deps.getSdk(extra.authInfo);
@@ -346,7 +616,7 @@ export function registerTools(server, deps) {
346
616
  });
347
617
  registerTool(`${deps.toolPrefix}.generate_username`, {
348
618
  title: 'Generate Username',
349
- description: 'Generate a username like the Bitwarden generator (random word, plus-addressed email, catch-all). Returning the value requires reveal=true.',
619
+ description: 'Generate a username like the Bitwarden generator (random word, plus-addressed email, catch-all, forwarded alias). This never mutates the vault; pass reveal=true to return the value, and NOREVEAL or KEYCHAIN_NOREVEAL force redaction.',
350
620
  annotations: { readOnlyHint: true },
351
621
  inputSchema: {
352
622
  type: z
@@ -356,13 +626,27 @@ export function registerTools(server, deps) {
356
626
  'catch_all_email',
357
627
  'forwarded_email_alias',
358
628
  ])
359
- .optional(),
360
- capitalize: z.boolean().optional(),
361
- includeNumber: z.boolean().optional(),
362
- email: z.string().optional(),
363
- domain: z.string().optional(),
364
- reveal: z.boolean().optional(),
629
+ .optional()
630
+ .describe('Username generation strategy: random word, plus-addressed email, catch-all email, or forwarded alias.'),
631
+ capitalize: z
632
+ .boolean()
633
+ .optional()
634
+ .describe('Capitalize the generated random word when supported.'),
635
+ includeNumber: z
636
+ .boolean()
637
+ .optional()
638
+ .describe('Append a number to generated usernames when supported.'),
639
+ email: z
640
+ .string()
641
+ .optional()
642
+ .describe('Base email address for plus-addressed username generation.'),
643
+ domain: z
644
+ .string()
645
+ .optional()
646
+ .describe('Domain for catch-all email username generation.'),
647
+ reveal: revealSchema,
365
648
  },
649
+ outputSchema: generatedResultOutputSchema,
366
650
  _meta: toolMeta,
367
651
  }, async (input, extra) => {
368
652
  const sdk = await deps.getSdk(extra.authInfo);
@@ -375,11 +659,11 @@ export function registerTools(server, deps) {
375
659
  });
376
660
  registerTool(`${deps.toolPrefix}.list_folders`, {
377
661
  title: 'List Folders',
378
- description: 'List Bitwarden folders (personal).',
662
+ description: 'List personal Bitwarden folders visible to the current user. Use this to discover folder ids for item organization; returns safe folder id/name summaries only.',
379
663
  annotations: { readOnlyHint: true },
380
664
  inputSchema: {
381
- search: z.string().optional(),
382
- limit: z.number().int().min(1).max(500).optional(),
665
+ search: searchSchema,
666
+ limit: limitSchema,
383
667
  },
384
668
  _meta: toolMeta,
385
669
  }, async (input, extra) => {
@@ -400,10 +684,10 @@ export function registerTools(server, deps) {
400
684
  });
401
685
  registerTool(`${deps.toolPrefix}.create_folder`, {
402
686
  title: 'Create Folder',
403
- description: 'Create a Bitwarden folder (personal).',
687
+ description: 'Create a personal Bitwarden folder. Use this to organize items outside organization collections.',
404
688
  annotations: mutatingToolAnnotations,
405
689
  inputSchema: {
406
- name: z.string(),
690
+ name: z.string().describe('Display name for the personal folder.'),
407
691
  },
408
692
  _meta: toolMeta,
409
693
  }, async (input, extra) => {
@@ -418,11 +702,11 @@ export function registerTools(server, deps) {
418
702
  });
419
703
  registerTool(`${deps.toolPrefix}.edit_folder`, {
420
704
  title: 'Edit Folder',
421
- description: 'Rename a Bitwarden folder (personal).',
705
+ description: 'Rename an existing personal Bitwarden folder by id. This mutates only folder metadata, not the items inside it, and returns the updated folder id/name summary.',
422
706
  annotations: mutatingToolAnnotations,
423
707
  inputSchema: {
424
- id: z.string(),
425
- name: z.string(),
708
+ id: stableObjectIdSchema,
709
+ name: z.string().describe('New display name for the personal folder.'),
426
710
  },
427
711
  _meta: toolMeta,
428
712
  }, async (input, extra) => {
@@ -437,10 +721,10 @@ export function registerTools(server, deps) {
437
721
  });
438
722
  registerTool(`${deps.toolPrefix}.delete_folder`, {
439
723
  title: 'Delete Folder',
440
- description: 'Delete a Bitwarden folder (personal).',
724
+ description: 'Delete a personal Bitwarden folder. Destructive: there is no restore helper in this server.',
441
725
  annotations: destructiveToolAnnotations,
442
726
  inputSchema: {
443
- id: z.string(),
727
+ id: stableObjectIdSchema,
444
728
  },
445
729
  _meta: toolMeta,
446
730
  }, async (input, extra) => {
@@ -456,12 +740,12 @@ export function registerTools(server, deps) {
456
740
  });
457
741
  registerTool(`${deps.toolPrefix}.list_org_collections`, {
458
742
  title: 'List Org Collections',
459
- description: 'List organization collections.',
743
+ description: 'List organization-scoped collections for the required organizationId. Use this after discovering an organization to find collection ids; returns safe id/name summaries.',
460
744
  annotations: { readOnlyHint: true },
461
745
  inputSchema: {
462
- organizationId: z.string(),
463
- search: z.string().optional(),
464
- limit: z.number().int().min(1).max(500).optional(),
746
+ organizationId: organizationIdSchema,
747
+ search: searchSchema,
748
+ limit: limitSchema,
465
749
  },
466
750
  _meta: toolMeta,
467
751
  }, async (input, extra) => {
@@ -489,11 +773,13 @@ export function registerTools(server, deps) {
489
773
  });
490
774
  registerTool(`${deps.toolPrefix}.create_org_collection`, {
491
775
  title: 'Create Org Collection',
492
- description: 'Create an organization collection.',
776
+ description: 'Create a new organization-scoped collection inside the required organizationId. Use this for shared vault grouping; returns the created collection summary.',
493
777
  annotations: mutatingToolAnnotations,
494
778
  inputSchema: {
495
- organizationId: z.string(),
496
- name: z.string(),
779
+ organizationId: organizationIdSchema,
780
+ name: z
781
+ .string()
782
+ .describe('Display name for the organization collection.'),
497
783
  },
498
784
  _meta: toolMeta,
499
785
  }, async (input, extra) => {
@@ -508,12 +794,14 @@ export function registerTools(server, deps) {
508
794
  });
509
795
  registerTool(`${deps.toolPrefix}.edit_org_collection`, {
510
796
  title: 'Edit Org Collection',
511
- description: 'Rename an organization collection.',
797
+ description: 'Rename an existing organization-scoped collection inside the required organizationId. This mutates collection metadata only and returns the updated collection summary.',
512
798
  annotations: mutatingToolAnnotations,
513
799
  inputSchema: {
514
- organizationId: z.string(),
515
- id: z.string(),
516
- name: z.string(),
800
+ organizationId: organizationIdSchema,
801
+ id: stableObjectIdSchema,
802
+ name: z
803
+ .string()
804
+ .describe('New display name for the organization collection.'),
517
805
  },
518
806
  _meta: toolMeta,
519
807
  }, async (input, extra) => {
@@ -528,11 +816,11 @@ export function registerTools(server, deps) {
528
816
  });
529
817
  registerTool(`${deps.toolPrefix}.delete_org_collection`, {
530
818
  title: 'Delete Org Collection',
531
- description: 'Delete an organization collection.',
819
+ description: 'Delete an organization collection. Destructive: there is no restore helper in this server.',
532
820
  annotations: destructiveToolAnnotations,
533
821
  inputSchema: {
534
- organizationId: z.string(),
535
- id: z.string(),
822
+ organizationId: organizationIdSchema,
823
+ id: stableObjectIdSchema,
536
824
  },
537
825
  _meta: toolMeta,
538
826
  }, async (input, extra) => {
@@ -552,12 +840,12 @@ export function registerTools(server, deps) {
552
840
  });
553
841
  registerTool(`${deps.toolPrefix}.move_item_to_organization`, {
554
842
  title: 'Move Item To Organization',
555
- description: 'Move an item to an organization (optionally assigning collection ids).',
843
+ description: 'Move an existing vault item into the required organizationId. Optionally pass collectionIds to assign organization collections during the move; collection ids are organization collections, not personal folders. Returns the moved item summary with normal redaction rules.',
556
844
  annotations: mutatingToolAnnotations,
557
845
  inputSchema: {
558
- id: z.string(),
559
- organizationId: z.string(),
560
- collectionIds: z.array(z.string()).optional(),
846
+ id: stableObjectIdSchema,
847
+ organizationId: organizationIdSchema,
848
+ collectionIds: collectionIdsSchema,
561
849
  },
562
850
  _meta: toolMeta,
563
851
  }, async (input, extra) => {
@@ -572,11 +860,11 @@ export function registerTools(server, deps) {
572
860
  });
573
861
  registerTool(`${deps.toolPrefix}.list_organizations`, {
574
862
  title: 'List Organizations',
575
- description: 'List organizations available to the current Bitwarden user.',
863
+ description: 'List organizations available to the current Bitwarden user so you can discover the organizationId required for org-scoped tools.',
576
864
  annotations: { readOnlyHint: true },
577
865
  inputSchema: {
578
- search: z.string().optional(),
579
- limit: z.number().int().min(1).max(500).optional(),
866
+ search: searchSchema,
867
+ limit: limitSchema,
580
868
  },
581
869
  _meta: toolMeta,
582
870
  }, async (input, extra) => {
@@ -595,12 +883,15 @@ export function registerTools(server, deps) {
595
883
  });
596
884
  registerTool(`${deps.toolPrefix}.list_collections`, {
597
885
  title: 'List Collections',
598
- description: 'List collections (optionally filtered by organization).',
886
+ description: 'List collections in the current vault, optionally filtered by organizationId. Use list_org_collections when you already know the organization and only want organization-scoped collections.',
599
887
  annotations: { readOnlyHint: true },
600
888
  inputSchema: {
601
- search: z.string().optional(),
602
- organizationId: z.string().optional(),
603
- limit: z.number().int().min(1).max(500).optional(),
889
+ search: searchSchema,
890
+ organizationId: z
891
+ .string()
892
+ .optional()
893
+ .describe('Optional organization id filter for collections.'),
894
+ limit: limitSchema,
604
895
  },
605
896
  _meta: toolMeta,
606
897
  }, async (input, extra) => {
@@ -625,23 +916,35 @@ export function registerTools(server, deps) {
625
916
  });
626
917
  registerTool(`${deps.toolPrefix}.search_items`, {
627
918
  title: 'Search Items',
628
- description: 'Search vault items by text and filters (org/folder/collection/url).',
919
+ description: 'Search vault items by text and filters (org/folder/collection/url). This wraps bw list items --search, which does not reliably search custom field values.',
629
920
  annotations: { readOnlyHint: true },
630
921
  inputSchema: {
631
- text: z.string().optional(),
922
+ text: z
923
+ .string()
924
+ .optional()
925
+ .describe('Optional text filter for item names, usernames, URIs, and other indexed fields. Custom field values are not reliably searched.'),
632
926
  type: z
633
927
  .enum(['login', 'note', 'ssh_key', 'card', 'identity'])
634
- .optional(),
928
+ .optional()
929
+ .describe('Optional item type filter: login, note, ssh_key, card, or identity.'),
635
930
  organizationId: z
636
931
  .union([z.string(), z.literal('null'), z.literal('notnull')])
637
- .optional(),
932
+ .optional()
933
+ .describe('Bitwarden organization id filter for org-scoped item search.'),
638
934
  folderId: z
639
935
  .union([z.string(), z.literal('null'), z.literal('notnull')])
640
- .optional(),
641
- collectionId: z.string().optional(),
642
- url: z.string().optional(),
643
- trash: z.boolean().optional(),
644
- limit: z.number().int().min(1).max(500).optional(),
936
+ .optional()
937
+ .describe('Personal folder id, not an organization collection id.'),
938
+ collectionId: collectionIdSchema,
939
+ url: z
940
+ .string()
941
+ .optional()
942
+ .describe('Optional URL filter for item lookup.'),
943
+ trash: z
944
+ .boolean()
945
+ .optional()
946
+ .describe('Search items in trash when true.'),
947
+ limit: limitSchema,
645
948
  },
646
949
  _meta: toolMeta,
647
950
  }, async (input, extra) => {
@@ -657,11 +960,11 @@ export function registerTools(server, deps) {
657
960
  });
658
961
  registerTool(`${deps.toolPrefix}.get_item`, {
659
962
  title: 'Get Item',
660
- description: 'Get a vault item by id.',
963
+ 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.',
661
964
  annotations: { readOnlyHint: true },
662
965
  inputSchema: {
663
- id: z.string(),
664
- reveal: z.boolean().optional(),
966
+ id: stableObjectIdSchema,
967
+ reveal: revealSchema,
665
968
  },
666
969
  _meta: toolMeta,
667
970
  }, async (input, extra) => {
@@ -677,11 +980,14 @@ export function registerTools(server, deps) {
677
980
  });
678
981
  registerTool(`${deps.toolPrefix}.get_uri`, {
679
982
  title: 'Get URI',
680
- description: 'Get a login URI by search term (bw get uri).',
983
+ description: 'Get the first login URI matched by bw get uri for a search term. Terms can be names, ids, or other bw-supported selectors and may be ambiguous, so use an exact item id when possible. URI values are returned as non-secret scalar results.',
681
984
  annotations: { readOnlyHint: true },
682
985
  inputSchema: {
683
- term: z.string(),
986
+ term: z
987
+ .string()
988
+ .describe('Search term or exact item id; exact ids avoid ambiguous bw lookups.'),
684
989
  },
990
+ outputSchema: uriResultOutputSchema,
685
991
  _meta: toolMeta,
686
992
  }, async (input, extra) => {
687
993
  const sdk = await deps.getSdk(extra.authInfo);
@@ -694,12 +1000,15 @@ export function registerTools(server, deps) {
694
1000
  });
695
1001
  registerTool(`${deps.toolPrefix}.get_notes`, {
696
1002
  title: 'Get Notes',
697
- description: 'Get item notes by search term (bw get notes).',
1003
+ description: 'Get item notes matched by bw get notes for a search term. Notes are treated as secret output here: value is null unless reveal=true and NOREVEAL is not active. Terms can be ambiguous, so prefer an exact item id when possible.',
698
1004
  annotations: { readOnlyHint: true },
699
1005
  inputSchema: {
700
- term: z.string(),
701
- reveal: z.boolean().optional(),
1006
+ term: z
1007
+ .string()
1008
+ .describe('Search term or exact item id; exact ids avoid ambiguous bw lookups.'),
1009
+ reveal: revealSchema,
702
1010
  },
1011
+ outputSchema: notesResultOutputSchema,
703
1012
  _meta: toolMeta,
704
1013
  }, async (input, extra) => {
705
1014
  const sdk = await deps.getSdk(extra.authInfo);
@@ -712,11 +1021,14 @@ export function registerTools(server, deps) {
712
1021
  });
713
1022
  registerTool(`${deps.toolPrefix}.get_exposed`, {
714
1023
  title: 'Get Exposed',
715
- description: 'Check exposed status by search term (bw get exposed).',
1024
+ description: 'Check the exposed-password count returned by bw get exposed for a search term. Terms follow bw lookup behavior and may be ambiguous; use an exact item id or precise selector when possible. Not-found results return a null scalar value instead of a thrown not-found error.',
716
1025
  annotations: { readOnlyHint: true },
717
1026
  inputSchema: {
718
- term: z.string(),
1027
+ term: z
1028
+ .string()
1029
+ .describe('Search term or exact item id; exact ids avoid ambiguous bw lookups.'),
719
1030
  },
1031
+ outputSchema: exposedResultOutputSchema,
720
1032
  _meta: toolMeta,
721
1033
  }, async (input, extra) => {
722
1034
  const sdk = await deps.getSdk(extra.authInfo);
@@ -729,10 +1041,10 @@ export function registerTools(server, deps) {
729
1041
  });
730
1042
  registerTool(`${deps.toolPrefix}.get_folder`, {
731
1043
  title: 'Get Folder',
732
- description: 'Get a folder by id (bw get folder).',
1044
+ description: 'Get one personal Bitwarden folder by stable folder id via bw get folder. Use this to verify a folder id before item updates; returns safe folder metadata only.',
733
1045
  annotations: { readOnlyHint: true },
734
1046
  inputSchema: {
735
- id: z.string(),
1047
+ id: stableObjectIdSchema,
736
1048
  },
737
1049
  _meta: toolMeta,
738
1050
  }, async (input, extra) => {
@@ -746,11 +1058,14 @@ export function registerTools(server, deps) {
746
1058
  });
747
1059
  registerTool(`${deps.toolPrefix}.get_collection`, {
748
1060
  title: 'Get Collection',
749
- description: 'Get a collection by id (bw get collection).',
1061
+ description: 'Get a collection by id (bw get collection). Use organizationId when you need to disambiguate an organization-scoped lookup.',
750
1062
  annotations: { readOnlyHint: true },
751
1063
  inputSchema: {
752
- id: z.string(),
753
- organizationId: z.string().optional(),
1064
+ id: stableObjectIdSchema,
1065
+ organizationId: z
1066
+ .string()
1067
+ .optional()
1068
+ .describe('Optional organization id used to disambiguate the lookup.'),
754
1069
  },
755
1070
  _meta: toolMeta,
756
1071
  }, async (input, extra) => {
@@ -764,10 +1079,10 @@ export function registerTools(server, deps) {
764
1079
  });
765
1080
  registerTool(`${deps.toolPrefix}.get_organization`, {
766
1081
  title: 'Get Organization',
767
- description: 'Get an organization by id (bw get organization).',
1082
+ description: 'Get one Bitwarden organization by stable organization id via bw get organization. Use list_organizations first when the id is unknown; returns organization metadata only.',
768
1083
  annotations: { readOnlyHint: true },
769
1084
  inputSchema: {
770
- id: z.string(),
1085
+ id: stableObjectIdSchema,
771
1086
  },
772
1087
  _meta: toolMeta,
773
1088
  }, async (input, extra) => {
@@ -781,11 +1096,14 @@ export function registerTools(server, deps) {
781
1096
  });
782
1097
  registerTool(`${deps.toolPrefix}.get_org_collection`, {
783
1098
  title: 'Get Org Collection',
784
- description: 'Get an org collection by id (bw get org-collection).',
1099
+ description: 'Get an organization collection by id (bw get org-collection). organizationId is optional and narrows the org-scoped lookup when provided.',
785
1100
  annotations: { readOnlyHint: true },
786
1101
  inputSchema: {
787
- id: z.string(),
788
- organizationId: z.string().optional(),
1102
+ id: stableObjectIdSchema,
1103
+ organizationId: z
1104
+ .string()
1105
+ .optional()
1106
+ .describe('Optional organization id used to disambiguate the org collection lookup.'),
789
1107
  },
790
1108
  _meta: toolMeta,
791
1109
  }, async (input, extra) => {
@@ -799,11 +1117,14 @@ export function registerTools(server, deps) {
799
1117
  });
800
1118
  registerTool(`${deps.toolPrefix}.delete_item`, {
801
1119
  title: 'Delete Item',
802
- description: 'Delete an item by id (soft-delete by default; set permanent=true to hard delete).',
1120
+ description: 'Delete a vault item by id. By default this is a soft delete to trash and can be restored with restore_item; set permanent=true to hard delete through bw. Returns only the requested id, not the deleted item contents.',
803
1121
  annotations: destructiveToolAnnotations,
804
1122
  inputSchema: {
805
- id: z.string(),
806
- permanent: z.boolean().optional(),
1123
+ id: stableObjectIdSchema,
1124
+ permanent: z
1125
+ .boolean()
1126
+ .optional()
1127
+ .describe('Hard delete immediately when true; omit or false to soft-delete to trash.'),
807
1128
  },
808
1129
  _meta: toolMeta,
809
1130
  }, async (input, extra) => {
@@ -819,11 +1140,18 @@ export function registerTools(server, deps) {
819
1140
  });
820
1141
  registerTool(`${deps.toolPrefix}.delete_items`, {
821
1142
  title: 'Delete Items',
822
- description: 'Delete multiple items by id. Returns per-id results (soft-delete by default; set permanent=true to hard delete).',
1143
+ description: 'Delete multiple vault items by id in one session. Soft-deletes to trash by default; set permanent=true to hard delete every id. Returns per-id ok/error results so partial failures are visible.',
823
1144
  annotations: destructiveToolAnnotations,
824
1145
  inputSchema: {
825
- ids: z.array(z.string()).min(1).max(200),
826
- permanent: z.boolean().optional(),
1146
+ ids: z
1147
+ .array(z.string())
1148
+ .min(1)
1149
+ .max(200)
1150
+ .describe('Vault item ids to delete; returns one result per id.'),
1151
+ permanent: z
1152
+ .boolean()
1153
+ .optional()
1154
+ .describe('Hard delete each id immediately when true; omit or false to soft-delete to trash.'),
827
1155
  },
828
1156
  _meta: toolMeta,
829
1157
  }, async (input, extra) => {
@@ -840,10 +1168,10 @@ export function registerTools(server, deps) {
840
1168
  });
841
1169
  registerTool(`${deps.toolPrefix}.restore_item`, {
842
1170
  title: 'Restore Item',
843
- description: 'Restore an item from trash by id.',
1171
+ description: 'Restore a soft-deleted vault item from trash by id. Use this after delete_item or delete_items when permanent was omitted or false; hard-deleted items cannot be restored. Returns the restored item summary with normal redaction rules.',
844
1172
  annotations: mutatingToolAnnotations,
845
1173
  inputSchema: {
846
- id: z.string(),
1174
+ id: stableObjectIdSchema,
847
1175
  },
848
1176
  _meta: toolMeta,
849
1177
  }, async (input, extra) => {
@@ -858,13 +1186,13 @@ export function registerTools(server, deps) {
858
1186
  });
859
1187
  registerTool(`${deps.toolPrefix}.create_attachment`, {
860
1188
  title: 'Create Attachment',
861
- description: 'Attach a file (base64) to an existing item. Returns the updated (redacted) item.',
1189
+ description: 'Attach base64-encoded file bytes to an existing item. Returns the updated item summary with normal redaction rules, so secrets stay hidden unless reveal is allowed.',
862
1190
  annotations: mutatingToolAnnotations,
863
1191
  inputSchema: {
864
- itemId: z.string(),
865
- filename: z.string(),
866
- contentBase64: z.string(),
867
- reveal: z.boolean().optional(),
1192
+ itemId: itemIdSchema,
1193
+ filename: filenameSchema,
1194
+ contentBase64: contentBase64Schema,
1195
+ reveal: revealSchema,
868
1196
  },
869
1197
  _meta: toolMeta,
870
1198
  }, async (input, extra) => {
@@ -879,12 +1207,12 @@ export function registerTools(server, deps) {
879
1207
  });
880
1208
  registerTool(`${deps.toolPrefix}.delete_attachment`, {
881
1209
  title: 'Delete Attachment',
882
- description: 'Delete an attachment from an item. Returns the updated (redacted) item.',
1210
+ description: 'Delete an attachment from its parent item using itemId plus attachmentId. The attachment id comes from item attachment metadata; this is destructive for that attachment and then refetches the parent item. Returns the updated item summary with normal redaction rules.',
883
1211
  annotations: destructiveToolAnnotations,
884
1212
  inputSchema: {
885
- itemId: z.string(),
886
- attachmentId: z.string(),
887
- reveal: z.boolean().optional(),
1213
+ itemId: itemIdSchema,
1214
+ attachmentId: attachmentIdSchema,
1215
+ reveal: revealSchema,
888
1216
  },
889
1217
  _meta: toolMeta,
890
1218
  }, async (input, extra) => {
@@ -899,11 +1227,11 @@ export function registerTools(server, deps) {
899
1227
  });
900
1228
  registerTool(`${deps.toolPrefix}.get_attachment`, {
901
1229
  title: 'Get Attachment',
902
- description: 'Download an attachment from an item and return it as base64 (bw get attachment).',
1230
+ 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.',
903
1231
  annotations: { readOnlyHint: true },
904
1232
  inputSchema: {
905
- itemId: z.string(),
906
- attachmentId: z.string(),
1233
+ itemId: itemIdSchema,
1234
+ attachmentId: attachmentIdSchema,
907
1235
  },
908
1236
  _meta: toolMeta,
909
1237
  }, async (input, extra) => {
@@ -917,7 +1245,7 @@ export function registerTools(server, deps) {
917
1245
  });
918
1246
  registerTool(`${deps.toolPrefix}.send_list`, {
919
1247
  title: 'Send List',
920
- description: 'List all the Sends owned by you (bw send list).',
1248
+ description: 'List all the Sends owned by you (bw send list). This is read-only and does not mutate the vault.',
921
1249
  annotations: { readOnlyHint: true, openWorldHint: true },
922
1250
  inputSchema: {},
923
1251
  _meta: toolMeta,
@@ -932,10 +1260,12 @@ export function registerTools(server, deps) {
932
1260
  });
933
1261
  registerTool(`${deps.toolPrefix}.send_template`, {
934
1262
  title: 'Send Template',
935
- description: 'Get json templates for send objects (bw send template).',
1263
+ description: 'Get a Bitwarden Send JSON template from bw send template. Choose a text or file template with object values send.text/text or send.file/file before using encoded create/edit flows. This is read-only and does not create a Send.',
936
1264
  annotations: { readOnlyHint: true, openWorldHint: true },
937
1265
  inputSchema: {
938
- object: z.enum(['send.text', 'text', 'send.file', 'file']),
1266
+ object: z
1267
+ .enum(['send.text', 'text', 'send.file', 'file'])
1268
+ .describe('Template object to fetch: text/send.text for text Sends or file/send.file for file Sends.'),
939
1269
  },
940
1270
  _meta: toolMeta,
941
1271
  }, async (input, extra) => {
@@ -952,9 +1282,15 @@ export function registerTools(server, deps) {
952
1282
  description: 'Get Sends owned by you. Use text=true to return text content; downloadFile=true to download a file send (bw send get).',
953
1283
  annotations: { readOnlyHint: true, openWorldHint: true },
954
1284
  inputSchema: {
955
- id: z.string(),
956
- text: z.boolean().optional(),
957
- downloadFile: z.boolean().optional(),
1285
+ id: stableObjectIdSchema,
1286
+ text: z
1287
+ .boolean()
1288
+ .optional()
1289
+ .describe('Return the Send text content instead of JSON metadata.'),
1290
+ downloadFile: z
1291
+ .boolean()
1292
+ .optional()
1293
+ .describe('Download a file Send and return its file bytes.'),
958
1294
  },
959
1295
  _meta: toolMeta,
960
1296
  }, async (input, extra) => {
@@ -968,24 +1304,53 @@ export function registerTools(server, deps) {
968
1304
  });
969
1305
  registerTool(`${deps.toolPrefix}.send_create`, {
970
1306
  title: 'Send Create',
971
- description: 'Create a Bitwarden Send. For file sends, pass filename+contentBase64. (bw send).',
1307
+ 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.',
972
1308
  annotations: {
973
1309
  readOnlyHint: false,
974
1310
  destructiveHint: false,
975
1311
  openWorldHint: true,
976
1312
  },
977
1313
  inputSchema: {
978
- type: z.enum(['text', 'file']),
979
- text: z.string().optional(),
980
- filename: z.string().optional(),
981
- contentBase64: z.string().optional(),
982
- deleteInDays: z.number().int().min(1).max(3650).optional(),
983
- password: z.string().optional(),
984
- maxAccessCount: z.number().int().min(1).max(1_000_000).optional(),
985
- hidden: z.boolean().optional(),
986
- name: z.string().optional(),
987
- notes: z.string().optional(),
988
- fullObject: z.boolean().optional(),
1314
+ type: z
1315
+ .enum(['text', 'file'])
1316
+ .describe('Send payload type: text uses text; file uses filename plus contentBase64.'),
1317
+ text: z
1318
+ .string()
1319
+ .optional()
1320
+ .describe('Text content for type=text Sends.'),
1321
+ filename: optionalFilenameSchema,
1322
+ contentBase64: optionalContentBase64Schema,
1323
+ deleteInDays: z
1324
+ .number()
1325
+ .int()
1326
+ .min(1)
1327
+ .max(3650)
1328
+ .optional()
1329
+ .describe('Days until Bitwarden automatically deletes the Send (1-3650).'),
1330
+ password: z
1331
+ .string()
1332
+ .optional()
1333
+ .describe('Optional Send access password required by recipients.'),
1334
+ maxAccessCount: z
1335
+ .number()
1336
+ .int()
1337
+ .min(1)
1338
+ .max(1_000_000)
1339
+ .optional()
1340
+ .describe('Maximum number of Send accesses before it becomes unavailable.'),
1341
+ hidden: z
1342
+ .boolean()
1343
+ .optional()
1344
+ .describe('Hide text Send content by default when recipients open it.'),
1345
+ name: z.string().optional().describe('Optional Send display name.'),
1346
+ notes: z
1347
+ .string()
1348
+ .optional()
1349
+ .describe('Optional private notes on the Send.'),
1350
+ fullObject: z
1351
+ .boolean()
1352
+ .optional()
1353
+ .describe('Ask bw send to return the full Send object when supported.'),
989
1354
  },
990
1355
  _meta: toolMeta,
991
1356
  }, async (input, extra) => {
@@ -1001,23 +1366,36 @@ export function registerTools(server, deps) {
1001
1366
  });
1002
1367
  registerTool(`${deps.toolPrefix}.send_create_encoded`, {
1003
1368
  title: 'Send Create (Encoded JSON)',
1004
- description: 'Create a Send via `bw send create`. Provide `encodedJson` (base64) or `json` (will be bw-encoded). Optional: `text`, `hidden`, or `file` (filename+contentBase64).',
1369
+ description: 'Create a Send with the advanced bw send create flow. Provide an encodedJson template or raw json to encode, or create directly from text/file fields; file uses filename plus contentBase64 and hidden only affects text Sends. Use this when you need template-level fields beyond the quick send_create options.',
1005
1370
  annotations: {
1006
1371
  readOnlyHint: false,
1007
1372
  destructiveHint: false,
1008
1373
  openWorldHint: true,
1009
1374
  },
1010
1375
  inputSchema: {
1011
- encodedJson: z.string().optional(),
1012
- json: z.unknown().optional(),
1013
- text: z.string().optional(),
1014
- hidden: z.boolean().optional(),
1376
+ encodedJson: z
1377
+ .string()
1378
+ .optional()
1379
+ .describe('Base64-encoded Send JSON template passed to bw send create.'),
1380
+ json: z
1381
+ .unknown()
1382
+ .optional()
1383
+ .describe('Raw Send JSON template; the server encodes it before bw send create.'),
1384
+ text: z
1385
+ .string()
1386
+ .optional()
1387
+ .describe('Direct text payload alternative to encodedJson/json.'),
1388
+ hidden: z
1389
+ .boolean()
1390
+ .optional()
1391
+ .describe('Hide direct text Send content by default when true.'),
1015
1392
  file: z
1016
1393
  .object({
1017
- filename: z.string(),
1018
- contentBase64: z.string(),
1394
+ filename: filenameSchema,
1395
+ contentBase64: contentBase64Schema,
1019
1396
  })
1020
- .optional(),
1397
+ .optional()
1398
+ .describe('Direct file payload alternative using filename and contentBase64.'),
1021
1399
  },
1022
1400
  _meta: toolMeta,
1023
1401
  }, async (input, extra) => {
@@ -1033,16 +1411,24 @@ export function registerTools(server, deps) {
1033
1411
  });
1034
1412
  registerTool(`${deps.toolPrefix}.send_edit`, {
1035
1413
  title: 'Send Edit (Encoded JSON)',
1036
- description: 'Edit a Send via `bw send edit`. Provide `encodedJson` (base64) or `json` (will be bw-encoded). Optional: `itemId` (maps to --itemid).',
1414
+ description: 'Edit an existing Send with the advanced bw send edit flow. Provide encodedJson or raw json containing the Send edit payload; raw json is encoded before invoking bw. Optional itemId maps to --itemid for item-linked Send edits.',
1037
1415
  annotations: {
1038
1416
  readOnlyHint: false,
1039
1417
  destructiveHint: false,
1040
1418
  openWorldHint: true,
1041
1419
  },
1042
1420
  inputSchema: {
1043
- encodedJson: z.string().optional(),
1044
- json: z.unknown().optional(),
1045
- itemId: z.string().optional(),
1421
+ encodedJson: z
1422
+ .string()
1423
+ .optional()
1424
+ .describe('Base64-encoded Send edit JSON payload passed to bw send edit.'),
1425
+ json: z
1426
+ .unknown()
1427
+ .optional()
1428
+ .describe('Raw Send edit JSON payload; the server encodes it before bw send edit.'),
1429
+ itemId: itemIdSchema
1430
+ .optional()
1431
+ .describe('Optional parent item id passed to bw send edit as --itemid.'),
1046
1432
  },
1047
1433
  _meta: toolMeta,
1048
1434
  }, async (input, extra) => {
@@ -1058,14 +1444,14 @@ export function registerTools(server, deps) {
1058
1444
  });
1059
1445
  registerTool(`${deps.toolPrefix}.send_remove_password`, {
1060
1446
  title: 'Send Remove Password',
1061
- description: "Remove a Send's saved password (bw send remove-password).",
1447
+ description: "Remove a Send's saved password so recipients no longer need that password. This is destructive for the Send password only; it does not delete the Send content. Use send_delete when the entire Send should be removed.",
1062
1448
  annotations: {
1063
1449
  readOnlyHint: false,
1064
1450
  destructiveHint: true,
1065
1451
  openWorldHint: true,
1066
1452
  },
1067
1453
  inputSchema: {
1068
- id: z.string(),
1454
+ id: stableObjectIdSchema,
1069
1455
  },
1070
1456
  _meta: toolMeta,
1071
1457
  }, async (input, extra) => {
@@ -1081,14 +1467,14 @@ export function registerTools(server, deps) {
1081
1467
  });
1082
1468
  registerTool(`${deps.toolPrefix}.send_delete`, {
1083
1469
  title: 'Send Delete',
1084
- description: 'Delete a Send (bw send delete).',
1470
+ 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. Returns the bw result payload when available.',
1085
1471
  annotations: {
1086
1472
  readOnlyHint: false,
1087
1473
  destructiveHint: true,
1088
1474
  openWorldHint: true,
1089
1475
  },
1090
1476
  inputSchema: {
1091
- id: z.string(),
1477
+ id: stableObjectIdSchema,
1092
1478
  },
1093
1479
  _meta: toolMeta,
1094
1480
  }, async (input, extra) => {
@@ -1104,13 +1490,22 @@ export function registerTools(server, deps) {
1104
1490
  });
1105
1491
  registerTool(`${deps.toolPrefix}.receive`, {
1106
1492
  title: 'Receive',
1107
- description: 'Access a Bitwarden Send from a url. Use obj=true for JSON object; downloadFile=true for file content. (bw receive)',
1493
+ description: 'Receive a Bitwarden Send from an HTTPS url. Provide password when the Send is protected; obj=true returns the parsed JSON object, downloadFile=true downloads file bytes as base64, and the default returns received text. This reads a shared Send and does not create or modify vault items.',
1108
1494
  annotations: { readOnlyHint: true, openWorldHint: true },
1109
1495
  inputSchema: {
1110
- url: z.string(),
1111
- password: z.string().optional(),
1112
- obj: z.boolean().optional(),
1113
- downloadFile: z.boolean().optional(),
1496
+ url: z.string().describe('HTTPS Bitwarden Send URL to receive.'),
1497
+ password: z
1498
+ .string()
1499
+ .optional()
1500
+ .describe('Password required by the Send, when one was configured.'),
1501
+ obj: z
1502
+ .boolean()
1503
+ .optional()
1504
+ .describe('Return the full parsed Send JSON object instead of raw text.'),
1505
+ downloadFile: z
1506
+ .boolean()
1507
+ .optional()
1508
+ .describe('Download a file Send and return filename, bytes, and contentBase64.'),
1114
1509
  },
1115
1510
  _meta: toolMeta,
1116
1511
  }, async (input, extra) => {
@@ -1124,11 +1519,14 @@ export function registerTools(server, deps) {
1124
1519
  });
1125
1520
  registerTool(`${deps.toolPrefix}.get_username`, {
1126
1521
  title: 'Get Username',
1127
- description: 'Get a login username by search term (bw get username).',
1522
+ description: 'Get a login username matched by bw get username for a search term. Usernames are treated as non-secret scalar output, but exact item ids are safest for ambiguous names.',
1128
1523
  annotations: { readOnlyHint: true },
1129
1524
  inputSchema: {
1130
- term: z.string(),
1525
+ term: z
1526
+ .string()
1527
+ .describe('Search term or exact item id used for bw get username.'),
1131
1528
  },
1529
+ outputSchema: usernameResultOutputSchema,
1132
1530
  _meta: toolMeta,
1133
1531
  }, async (input, extra) => {
1134
1532
  const sdk = await deps.getSdk(extra.authInfo);
@@ -1150,12 +1548,15 @@ export function registerTools(server, deps) {
1150
1548
  });
1151
1549
  registerTool(`${deps.toolPrefix}.get_password`, {
1152
1550
  title: 'Get Password',
1153
- description: 'Get a login password by search term (bw get password). Returning a password requires reveal=true.',
1551
+ description: 'Get a login password by search term (bw get password). The value is null unless reveal=true, and NOREVEAL or KEYCHAIN_NOREVEAL can still force redaction.',
1154
1552
  annotations: { readOnlyHint: true },
1155
1553
  inputSchema: {
1156
- term: z.string(),
1157
- reveal: z.boolean().optional(),
1554
+ term: z
1555
+ .string()
1556
+ .describe('Search term or exact item id used for bw get password.'),
1557
+ reveal: revealSchema,
1158
1558
  },
1559
+ outputSchema: passwordResultOutputSchema,
1159
1560
  _meta: toolMeta,
1160
1561
  }, async (input, extra) => {
1161
1562
  const sdk = await deps.getSdk(extra.authInfo);
@@ -1177,12 +1578,15 @@ export function registerTools(server, deps) {
1177
1578
  });
1178
1579
  registerTool(`${deps.toolPrefix}.get_totp`, {
1179
1580
  title: 'Get TOTP',
1180
- description: 'Get a TOTP code/seed by search term (bw get totp). Returning a TOTP requires reveal=true.',
1581
+ description: 'Get the current TOTP code by search term (bw get totp). The value is null unless reveal=true, and NOREVEAL or KEYCHAIN_NOREVEAL can still force redaction.',
1181
1582
  annotations: { readOnlyHint: true },
1182
1583
  inputSchema: {
1183
- term: z.string(),
1184
- reveal: z.boolean().optional(),
1584
+ term: z
1585
+ .string()
1586
+ .describe('Search term or exact item id used for bw get totp.'),
1587
+ reveal: revealSchema,
1185
1588
  },
1589
+ outputSchema: totpResultOutputSchema,
1186
1590
  _meta: toolMeta,
1187
1591
  }, async (input, extra) => {
1188
1592
  const sdk = await deps.getSdk(extra.authInfo);
@@ -1205,9 +1609,10 @@ export function registerTools(server, deps) {
1205
1609
  description: 'Get an item password history (if any). Returning passwords requires reveal=true.',
1206
1610
  annotations: { readOnlyHint: true },
1207
1611
  inputSchema: {
1208
- id: z.string(),
1209
- reveal: z.boolean().optional(),
1612
+ id: stableObjectIdSchema,
1613
+ reveal: revealSchema,
1210
1614
  },
1615
+ outputSchema: passwordHistoryResultOutputSchema,
1211
1616
  _meta: toolMeta,
1212
1617
  }, async (input, extra) => {
1213
1618
  const sdk = await deps.getSdk(extra.authInfo);
@@ -1222,37 +1627,36 @@ export function registerTools(server, deps) {
1222
1627
  });
1223
1628
  registerTool(`${deps.toolPrefix}.create_login`, {
1224
1629
  title: 'Create Login',
1225
- description: 'Create a login item.',
1630
+ description: 'Create a login item with username/password/TOTP/URI data. Use this for website or app credentials instead of a secure note, card, or identity. Accepts custom fields and attachments, supports folder/organization/collection scoping, and returns a redacted item summary by default.',
1226
1631
  annotations: mutatingToolAnnotations,
1227
1632
  inputSchema: {
1228
- name: z.string(),
1229
- username: z.string().optional(),
1230
- password: z.string().optional(),
1231
- uris: z
1232
- .array(z.object({
1233
- uri: z.string(),
1234
- match: uriMatchInputSchema.optional(),
1235
- }))
1236
- .optional(),
1237
- totp: z.string().optional(),
1238
- notes: z.string().optional(),
1239
- fields: z
1240
- .array(z.object({
1241
- name: z.string(),
1242
- value: z.string(),
1243
- hidden: z.boolean().optional(),
1244
- }))
1245
- .optional(),
1246
- attachments: z
1247
- .array(z.object({
1248
- filename: z.string(),
1249
- contentBase64: z.string(),
1250
- }))
1251
- .optional(),
1252
- favorite: z.boolean().optional(),
1253
- organizationId: z.string().optional(),
1254
- collectionIds: z.array(z.string()).optional(),
1255
- folderId: z.string().optional(),
1633
+ name: z.string().describe('Display name for the login item.'),
1634
+ username: z
1635
+ .string()
1636
+ .optional()
1637
+ .describe('Login username or email address.'),
1638
+ password: z
1639
+ .string()
1640
+ .optional()
1641
+ .describe('Password to store on the login item.'),
1642
+ uris: urisSchema,
1643
+ totp: z
1644
+ .string()
1645
+ .optional()
1646
+ .describe('TOTP secret or otpauth value for the login item.'),
1647
+ notes: z
1648
+ .string()
1649
+ .optional()
1650
+ .describe('Optional free-form notes for the login item.'),
1651
+ fields: itemFieldsSchema,
1652
+ attachments: itemAttachmentsSchema,
1653
+ favorite: z
1654
+ .boolean()
1655
+ .optional()
1656
+ .describe('Mark the item as a favorite when true.'),
1657
+ organizationId: optionalOrganizationIdSchema,
1658
+ collectionIds: collectionIdsSchema,
1659
+ folderId: folderIdSchema,
1256
1660
  },
1257
1661
  _meta: toolMeta,
1258
1662
  }, async (input, extra) => {
@@ -1270,40 +1674,44 @@ export function registerTools(server, deps) {
1270
1674
  });
1271
1675
  registerTool(`${deps.toolPrefix}.create_logins`, {
1272
1676
  title: 'Create Logins',
1273
- description: 'Create multiple login items in a single call.',
1677
+ description: 'Create multiple login items in one call. Use this when you need several independent credentials at once, with the same login-item behavior as create_login. Set continueOnError to keep going after a failure and receive per-item ok/error results; returned items are redacted by default.',
1274
1678
  annotations: mutatingToolAnnotations,
1275
1679
  inputSchema: {
1276
- items: z.array(z.object({
1277
- name: z.string(),
1278
- username: z.string().optional(),
1279
- password: z.string().optional(),
1280
- uris: z
1281
- .array(z.object({
1282
- uri: z.string(),
1283
- match: uriMatchInputSchema.optional(),
1284
- }))
1285
- .optional(),
1286
- totp: z.string().optional(),
1287
- notes: z.string().optional(),
1288
- fields: z
1289
- .array(z.object({
1290
- name: z.string(),
1291
- value: z.string(),
1292
- hidden: z.boolean().optional(),
1293
- }))
1294
- .optional(),
1295
- attachments: z
1296
- .array(z.object({
1297
- filename: z.string(),
1298
- contentBase64: z.string(),
1299
- }))
1300
- .optional(),
1301
- favorite: z.boolean().optional(),
1302
- organizationId: z.string().optional(),
1303
- collectionIds: z.array(z.string()).optional(),
1304
- folderId: z.string().optional(),
1305
- })),
1306
- continueOnError: z.boolean().optional(),
1680
+ items: z
1681
+ .array(z.object({
1682
+ name: z.string().describe('Display name for the login item.'),
1683
+ username: z
1684
+ .string()
1685
+ .optional()
1686
+ .describe('Login username or email address.'),
1687
+ password: z
1688
+ .string()
1689
+ .optional()
1690
+ .describe('Password to store on the login item.'),
1691
+ uris: urisSchema,
1692
+ totp: z
1693
+ .string()
1694
+ .optional()
1695
+ .describe('TOTP secret or otpauth value for the login item.'),
1696
+ notes: z
1697
+ .string()
1698
+ .optional()
1699
+ .describe('Optional free-form notes for the login item.'),
1700
+ fields: itemFieldsSchema,
1701
+ attachments: itemAttachmentsSchema,
1702
+ favorite: z
1703
+ .boolean()
1704
+ .optional()
1705
+ .describe('Mark the item as a favorite when true.'),
1706
+ organizationId: optionalOrganizationIdSchema,
1707
+ collectionIds: collectionIdsSchema,
1708
+ folderId: folderIdSchema,
1709
+ }))
1710
+ .describe('Login item payloads to create; each item follows create_login fields and returns its own ok/error result.'),
1711
+ continueOnError: z
1712
+ .boolean()
1713
+ .optional()
1714
+ .describe('Continue after failures and return per-item ok/error results when true.'),
1307
1715
  },
1308
1716
  _meta: toolMeta,
1309
1717
  }, async (input, extra) => {
@@ -1328,16 +1736,15 @@ export function registerTools(server, deps) {
1328
1736
  });
1329
1737
  registerTool(`${deps.toolPrefix}.set_login_uris`, {
1330
1738
  title: 'Set Login URIs',
1331
- description: 'Set or update the URIs (and per-URI match types) for a login item. mode=replace overwrites; mode=merge updates/adds by uri.',
1739
+ description: 'Set or update the URI list on a login item. mode=replace overwrites the full list; mode=merge updates existing URIs and adds new ones by URI. Match values can be domain, host, startsWith, exact, regex, or never.',
1332
1740
  annotations: mutatingToolAnnotations,
1333
1741
  inputSchema: {
1334
- id: z.string(),
1335
- mode: z.enum(['replace', 'merge']).optional(),
1336
- uris: z.array(z.object({
1337
- uri: z.string(),
1338
- match: uriMatchInputSchema.optional(),
1339
- })),
1340
- reveal: z.boolean().optional(),
1742
+ id: stableObjectIdSchema,
1743
+ mode: optionalModeSchema,
1744
+ uris: z
1745
+ .array(uriEntrySchema)
1746
+ .describe('URI entries to store or update on the login item.'),
1747
+ reveal: revealSchema,
1341
1748
  },
1342
1749
  _meta: toolMeta,
1343
1750
  }, async (input, extra) => {
@@ -1357,22 +1764,22 @@ export function registerTools(server, deps) {
1357
1764
  });
1358
1765
  registerTool(`${deps.toolPrefix}.create_note`, {
1359
1766
  title: 'Create Note',
1360
- description: 'Create a secure note item.',
1767
+ description: 'Create a secure note item. Use this for free-form text or secrets that do not belong in a login, card, identity, or SSH key item. Accepts custom fields plus folder/organization/collection scoping, and returns a redacted item summary by default.',
1361
1768
  annotations: mutatingToolAnnotations,
1362
1769
  inputSchema: {
1363
- name: z.string(),
1364
- notes: z.string().optional(),
1365
- fields: z
1366
- .array(z.object({
1367
- name: z.string(),
1368
- value: z.string(),
1369
- hidden: z.boolean().optional(),
1370
- }))
1371
- .optional(),
1372
- favorite: z.boolean().optional(),
1373
- organizationId: z.string().optional(),
1374
- collectionIds: z.array(z.string()).optional(),
1375
- folderId: z.string().optional(),
1770
+ name: z.string().describe('Display name for the secure note item.'),
1771
+ notes: z
1772
+ .string()
1773
+ .optional()
1774
+ .describe('Optional note text stored on the item.'),
1775
+ fields: itemFieldsSchema,
1776
+ favorite: z
1777
+ .boolean()
1778
+ .optional()
1779
+ .describe('Mark the item as a favorite when true.'),
1780
+ organizationId: optionalOrganizationIdSchema,
1781
+ collectionIds: collectionIdsSchema,
1782
+ folderId: folderIdSchema,
1376
1783
  },
1377
1784
  _meta: toolMeta,
1378
1785
  }, async (input, extra) => {
@@ -1387,19 +1794,35 @@ export function registerTools(server, deps) {
1387
1794
  });
1388
1795
  registerTool(`${deps.toolPrefix}.create_ssh_key`, {
1389
1796
  title: 'Create SSH Key',
1390
- description: 'Create an SSH key object (stored as secure note with fields).',
1797
+ description: 'Create an SSH key object stored as a secure note with standard fields. Use this when you need a public/private key pair plus optional fingerprint or comment, not a login or payment card. The private key is stored in a hidden field and redacted in returned summaries; folder, organization, and collection scoping is supported.',
1391
1798
  annotations: mutatingToolAnnotations,
1392
1799
  inputSchema: {
1393
- name: z.string(),
1394
- publicKey: z.string(),
1395
- privateKey: z.string(),
1396
- fingerprint: z.string().optional(),
1397
- comment: z.string().optional(),
1398
- notes: z.string().optional(),
1399
- favorite: z.boolean().optional(),
1400
- organizationId: z.string().optional(),
1401
- collectionIds: z.array(z.string()).optional(),
1402
- folderId: z.string().optional(),
1800
+ name: z.string().describe('Display name for the SSH key item.'),
1801
+ publicKey: z
1802
+ .string()
1803
+ .describe('SSH public key material to store on the item.'),
1804
+ privateKey: z
1805
+ .string()
1806
+ .describe('SSH private key material to store on the item.'),
1807
+ fingerprint: z
1808
+ .string()
1809
+ .optional()
1810
+ .describe('Optional SSH key fingerprint.'),
1811
+ comment: z
1812
+ .string()
1813
+ .optional()
1814
+ .describe('Optional SSH key comment or label.'),
1815
+ notes: z
1816
+ .string()
1817
+ .optional()
1818
+ .describe('Optional note text stored on the item.'),
1819
+ favorite: z
1820
+ .boolean()
1821
+ .optional()
1822
+ .describe('Mark the item as a favorite when true.'),
1823
+ organizationId: optionalOrganizationIdSchema,
1824
+ collectionIds: collectionIdsSchema,
1825
+ folderId: folderIdSchema,
1403
1826
  },
1404
1827
  _meta: toolMeta,
1405
1828
  }, async (input, extra) => {
@@ -1414,28 +1837,37 @@ export function registerTools(server, deps) {
1414
1837
  });
1415
1838
  registerTool(`${deps.toolPrefix}.create_card`, {
1416
1839
  title: 'Create Card',
1417
- description: 'Create a payment card item.',
1840
+ description: 'Create a payment card item. Use this for cardholder name, brand, number, expiry, and code, not for login credentials or notes. Accepts custom fields plus folder/organization/collection scoping, and returned summaries redact the card number, code, and hidden fields.',
1418
1841
  annotations: mutatingToolAnnotations,
1419
1842
  inputSchema: {
1420
- name: z.string(),
1421
- cardholderName: z.string().optional(),
1422
- brand: z.string().optional(),
1423
- number: z.string().optional(),
1424
- expMonth: z.string().optional(),
1425
- expYear: z.string().optional(),
1426
- code: z.string().optional(),
1427
- notes: z.string().optional(),
1428
- fields: z
1429
- .array(z.object({
1430
- name: z.string(),
1431
- value: z.string(),
1432
- hidden: z.boolean().optional(),
1433
- }))
1434
- .optional(),
1435
- favorite: z.boolean().optional(),
1436
- organizationId: z.string().optional(),
1437
- collectionIds: z.array(z.string()).optional(),
1438
- folderId: z.string().optional(),
1843
+ name: z.string().describe('Display name for the payment card item.'),
1844
+ cardholderName: z
1845
+ .string()
1846
+ .optional()
1847
+ .describe('Cardholder name to store on the card.'),
1848
+ brand: z
1849
+ .string()
1850
+ .optional()
1851
+ .describe('Card brand, such as visa or mastercard.'),
1852
+ number: z
1853
+ .string()
1854
+ .optional()
1855
+ .describe('Primary card number to store on the card.'),
1856
+ expMonth: z.string().optional().describe('Card expiration month.'),
1857
+ expYear: z.string().optional().describe('Card expiration year.'),
1858
+ code: z.string().optional().describe('Card security code or CVV.'),
1859
+ notes: z
1860
+ .string()
1861
+ .optional()
1862
+ .describe('Optional note text stored on the item.'),
1863
+ fields: itemFieldsSchema,
1864
+ favorite: z
1865
+ .boolean()
1866
+ .optional()
1867
+ .describe('Mark the item as a favorite when true.'),
1868
+ organizationId: optionalOrganizationIdSchema,
1869
+ collectionIds: collectionIdsSchema,
1870
+ folderId: folderIdSchema,
1439
1871
  },
1440
1872
  _meta: toolMeta,
1441
1873
  }, async (input, extra) => {
@@ -1450,44 +1882,23 @@ export function registerTools(server, deps) {
1450
1882
  });
1451
1883
  registerTool(`${deps.toolPrefix}.create_identity`, {
1452
1884
  title: 'Create Identity',
1453
- description: 'Create an identity item.',
1885
+ description: 'Create an identity item. Use this for personal, contact, and address data instead of a login or card. Accepts structured identity fields plus custom fields and scoping, and returned summaries redact sensitive identity fields and hidden custom fields.',
1454
1886
  annotations: mutatingToolAnnotations,
1455
1887
  inputSchema: {
1456
- name: z.string(),
1457
- identity: z
1458
- .object({
1459
- title: z.string().optional(),
1460
- firstName: z.string().optional(),
1461
- middleName: z.string().optional(),
1462
- lastName: z.string().optional(),
1463
- address1: z.string().optional(),
1464
- address2: z.string().optional(),
1465
- address3: z.string().optional(),
1466
- city: z.string().optional(),
1467
- state: z.string().optional(),
1468
- postalCode: z.string().optional(),
1469
- country: z.string().optional(),
1470
- company: z.string().optional(),
1471
- email: z.string().optional(),
1472
- phone: z.string().optional(),
1473
- ssn: z.string().optional(),
1474
- username: z.string().optional(),
1475
- passportNumber: z.string().optional(),
1476
- licenseNumber: z.string().optional(),
1477
- })
1478
- .optional(),
1479
- notes: z.string().optional(),
1480
- fields: z
1481
- .array(z.object({
1482
- name: z.string(),
1483
- value: z.string(),
1484
- hidden: z.boolean().optional(),
1485
- }))
1486
- .optional(),
1487
- favorite: z.boolean().optional(),
1488
- organizationId: z.string().optional(),
1489
- collectionIds: z.array(z.string()).optional(),
1490
- folderId: z.string().optional(),
1888
+ name: z.string().describe('Display name for the identity item.'),
1889
+ identity: identitySchema,
1890
+ notes: z
1891
+ .string()
1892
+ .optional()
1893
+ .describe('Optional note text stored on the item.'),
1894
+ fields: itemFieldsSchema,
1895
+ favorite: z
1896
+ .boolean()
1897
+ .optional()
1898
+ .describe('Mark the item as a favorite when true.'),
1899
+ organizationId: optionalOrganizationIdSchema,
1900
+ collectionIds: collectionIdsSchema,
1901
+ folderId: folderIdSchema,
1491
1902
  },
1492
1903
  _meta: toolMeta,
1493
1904
  }, async (input, extra) => {
@@ -1502,37 +1913,11 @@ export function registerTools(server, deps) {
1502
1913
  });
1503
1914
  registerTool(`${deps.toolPrefix}.update_item`, {
1504
1915
  title: 'Update Item',
1505
- description: 'Update selected fields of an item by id.',
1916
+ description: 'Update selected fields of an item by id. The patch is applied to the current item, so omitted fields stay unchanged while explicit nulls and empty arrays overwrite the stored folder, collection, login URI, or custom-field values. Use this for partial edits instead of reconstructing the full item.',
1506
1917
  annotations: mutatingToolAnnotations,
1507
1918
  inputSchema: {
1508
- id: z.string(),
1509
- patch: z.object({
1510
- name: z.string().optional(),
1511
- notes: z.string().optional(),
1512
- favorite: z.boolean().optional(),
1513
- folderId: z.union([z.string(), z.null()]).optional(),
1514
- collectionIds: z.array(z.string()).optional(),
1515
- login: z
1516
- .object({
1517
- username: z.string().optional(),
1518
- password: z.string().optional(),
1519
- totp: z.string().optional(),
1520
- uris: z
1521
- .array(z.object({
1522
- uri: z.string(),
1523
- match: uriMatchInputSchema.optional(),
1524
- }))
1525
- .optional(),
1526
- })
1527
- .optional(),
1528
- fields: z
1529
- .array(z.object({
1530
- name: z.string(),
1531
- value: z.string(),
1532
- hidden: z.boolean().optional(),
1533
- }))
1534
- .optional(),
1535
- }),
1919
+ id: stableObjectIdSchema,
1920
+ patch: patchSchema,
1536
1921
  },
1537
1922
  _meta: toolMeta,
1538
1923
  }, async (input, extra) => {