@icoretech/warden-mcp 0.2.16 → 0.2.18

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
@@ -31,6 +31,10 @@ follow-up calls into visible text by default.
31
31
  For search/list tools, the text output includes concise rows with stable ids and
32
32
  safe metadata such as names, item type, username, URI values, organization id,
33
33
  folder id, and collection ids. Secret fields are not included in those summaries.
34
+ Create/update/move/restore helpers that return a folder, collection, or item use
35
+ the same concise visible summaries so text-only clients can immediately reuse the
36
+ returned ids in follow-up calls. Delete helpers include the requested ids when no
37
+ object is returned.
34
38
 
35
39
  For scalar helper tools, the text output follows the reveal contract:
36
40
 
@@ -44,6 +48,10 @@ When a lookup term matches multiple login items, credential helpers return an
44
48
  `AMBIGUOUS_LOOKUP` error with visible candidate ids. Retry with `term` set to an
45
49
  exact candidate `id`, or call `get_item` with that `id`.
46
50
 
51
+ If `KEYCHAIN_TEXT_COMPAT_MODE=structured_json` is enabled, supported success and
52
+ ambiguity/error results mirror their `structuredContent` into the visible text as
53
+ serialized JSON instead of the human summaries.
54
+
47
55
  ## LLM Automation Use Case
48
56
 
49
57
  `warden-mcp` is not only useful for vault administration. A very practical use case is pairing it with an LLM that can also drive a browser.
@@ -465,7 +473,7 @@ Mutation control:
465
473
  - `KEYCHAIN_METRICS_LOG_INTERVAL_MS` (default `0`, disabled)
466
474
  - `NOREVEAL` / `KEYCHAIN_NOREVEAL` (default `false`; force all reveals to false)
467
475
  - `KEYCHAIN_ALLOW_ENV_FALLBACK` (default `false`; HTTP env-var credential fallback)
468
- - `KEYCHAIN_TEXT_COMPAT_MODE` (default unset; set to `structured_json` to copy structured `OK` results into `TextContent`)
476
+ - `KEYCHAIN_TEXT_COMPAT_MODE` (default unset; set to `structured_json` to copy structured results into `TextContent`)
469
477
 
470
478
  Redaction defaults (item reads):
471
479
 
@@ -586,6 +594,8 @@ Orgs/collections:
586
594
  Attachments:
587
595
 
588
596
  - `keychain_create_attachment`, `keychain_delete_attachment`, `keychain_get_attachment`
597
+ - `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
598
+ - `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
589
599
 
590
600
  Sends:
591
601
 
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() {
@@ -38,9 +38,10 @@ export function registerTools(server, deps) {
38
38
  const isNoReveal = parseBoolEnv('NOREVEAL', 'KEYCHAIN_NOREVEAL');
39
39
  const textCompatMode = process.env.KEYCHAIN_TEXT_COMPAT_MODE?.trim().toLowerCase();
40
40
  function readonlyBlocked() {
41
+ const structuredContent = { ok: false, error: 'READONLY' };
41
42
  return {
42
- structuredContent: { ok: false, error: 'READONLY' },
43
- content: [{ type: 'text', text: 'Blocked: READONLY=true' }],
43
+ structuredContent,
44
+ content: toolTextContent(structuredContent, 'Blocked: READONLY=true'),
44
45
  isError: true,
45
46
  };
46
47
  }
@@ -107,6 +108,31 @@ export function registerTools(server, deps) {
107
108
  if (Array.isArray(rec.collectionIds) && rec.collectionIds.length > 0) {
108
109
  parts.push(`collectionIds=${quoteText(rec.collectionIds.join(', '))}`);
109
110
  }
111
+ if (Array.isArray(rec.attachments) && rec.attachments.length > 0) {
112
+ const attachments = rec.attachments
113
+ .map((attachment) => {
114
+ if (!attachment || typeof attachment !== 'object')
115
+ return null;
116
+ const att = attachment;
117
+ const attParts = [];
118
+ if (typeof att.id === 'string')
119
+ attParts.push(`id=${att.id}`);
120
+ if (typeof att.fileName === 'string') {
121
+ attParts.push(`fileName=${quoteText(att.fileName)}`);
122
+ }
123
+ if (typeof att.size === 'string' || typeof att.size === 'number') {
124
+ attParts.push(`size=${att.size}`);
125
+ }
126
+ if (typeof att.sizeName === 'string') {
127
+ attParts.push(`sizeName=${quoteText(att.sizeName)}`);
128
+ }
129
+ return attParts.length > 0 ? `{${attParts.join(' ')}}` : null;
130
+ })
131
+ .filter((attachment) => attachment !== null);
132
+ if (attachments.length > 0) {
133
+ parts.push(`attachments=${quoteText(attachments.join(', '))}`);
134
+ }
135
+ }
110
136
  if (typeof rec.favorite === 'boolean')
111
137
  parts.push(`favorite=${rec.favorite}`);
112
138
  return `- ${parts.length > 0 ? parts.join(' ') : stringifyScalar(rec)}`;
@@ -122,6 +148,30 @@ export function registerTools(server, deps) {
122
148
  ...results.map(formatItemSummary),
123
149
  ].join('\n');
124
150
  }
151
+ function structuredTextContent(structuredContent, fallbackText) {
152
+ return toolTextContent(structuredContent, fallbackText);
153
+ }
154
+ function entityTextContent(structuredContent, heading, entity) {
155
+ if (textCompatMode === 'structured_json') {
156
+ return [
157
+ { type: 'text', text: JSON.stringify(structuredContent) },
158
+ ];
159
+ }
160
+ return [
161
+ {
162
+ type: 'text',
163
+ text: [heading, formatItemSummary(entity)].join('\n'),
164
+ },
165
+ ];
166
+ }
167
+ function idTextContent(structuredContent, action, id) {
168
+ return structuredTextContent(structuredContent, `${action} id=${id}.`);
169
+ }
170
+ function formatBatchCreateResult(result) {
171
+ if (result.ok)
172
+ return formatItemSummary(result.item);
173
+ return `- error=${quoteText(result.error ?? 'unknown')}`;
174
+ }
125
175
  function toolValueContent(structuredContent, kind, value, revealed, extraLines = []) {
126
176
  if (textCompatMode === 'structured_json') {
127
177
  return [
@@ -143,15 +193,10 @@ export function registerTools(server, deps) {
143
193
  };
144
194
  return {
145
195
  structuredContent,
146
- content: [
147
- {
148
- type: 'text',
149
- text: [
150
- `${error.message}. Retry with term set to an exact id.`,
151
- ...error.candidates.map(formatItemSummary),
152
- ].join('\n'),
153
- },
154
- ],
196
+ content: structuredTextContent(structuredContent, [
197
+ `${error.message}. Retry with term set to an exact id.`,
198
+ ...error.candidates.map(formatItemSummary),
199
+ ].join('\n')),
155
200
  isError: true,
156
201
  };
157
202
  }
@@ -368,7 +413,7 @@ export function registerTools(server, deps) {
368
413
  const folder = await sdk.createFolder({ name: input.name });
369
414
  return {
370
415
  structuredContent: { folder },
371
- content: [{ type: 'text', text: 'Created.' }],
416
+ content: entityTextContent({ folder }, 'Created folder:', folder),
372
417
  };
373
418
  });
374
419
  registerTool(`${deps.toolPrefix}.edit_folder`, {
@@ -387,7 +432,7 @@ export function registerTools(server, deps) {
387
432
  const folder = await sdk.editFolder(input);
388
433
  return {
389
434
  structuredContent: { folder },
390
- content: [{ type: 'text', text: 'Updated.' }],
435
+ content: entityTextContent({ folder }, 'Updated folder:', folder),
391
436
  };
392
437
  });
393
438
  registerTool(`${deps.toolPrefix}.delete_folder`, {
@@ -403,9 +448,10 @@ export function registerTools(server, deps) {
403
448
  return readonlyBlocked();
404
449
  const sdk = await deps.getSdk(extra.authInfo);
405
450
  await sdk.deleteFolder(input);
451
+ const structuredContent = { ok: true, id: input.id };
406
452
  return {
407
- structuredContent: { ok: true },
408
- content: [{ type: 'text', text: 'Deleted.' }],
453
+ structuredContent,
454
+ content: idTextContent(structuredContent, 'Deleted folder', input.id),
409
455
  };
410
456
  });
411
457
  registerTool(`${deps.toolPrefix}.list_org_collections`, {
@@ -457,7 +503,7 @@ export function registerTools(server, deps) {
457
503
  const collection = await sdk.createOrgCollection(input);
458
504
  return {
459
505
  structuredContent: { collection },
460
- content: [{ type: 'text', text: 'Created.' }],
506
+ content: entityTextContent({ collection }, 'Created org collection:', collection),
461
507
  };
462
508
  });
463
509
  registerTool(`${deps.toolPrefix}.edit_org_collection`, {
@@ -477,7 +523,7 @@ export function registerTools(server, deps) {
477
523
  const collection = await sdk.editOrgCollection(input);
478
524
  return {
479
525
  structuredContent: { collection },
480
- content: [{ type: 'text', text: 'Updated.' }],
526
+ content: entityTextContent({ collection }, 'Updated org collection:', collection),
481
527
  };
482
528
  });
483
529
  registerTool(`${deps.toolPrefix}.delete_org_collection`, {
@@ -494,9 +540,14 @@ export function registerTools(server, deps) {
494
540
  return readonlyBlocked();
495
541
  const sdk = await deps.getSdk(extra.authInfo);
496
542
  await sdk.deleteOrgCollection(input);
543
+ const structuredContent = {
544
+ ok: true,
545
+ id: input.id,
546
+ organizationId: input.organizationId ?? null,
547
+ };
497
548
  return {
498
- structuredContent: { ok: true },
499
- content: [{ type: 'text', text: 'Deleted.' }],
549
+ structuredContent,
550
+ content: idTextContent(structuredContent, 'Deleted org collection', input.id),
500
551
  };
501
552
  });
502
553
  registerTool(`${deps.toolPrefix}.move_item_to_organization`, {
@@ -516,7 +567,7 @@ export function registerTools(server, deps) {
516
567
  const item = await sdk.moveItemToOrganization(input);
517
568
  return {
518
569
  structuredContent: { item },
519
- content: [{ type: 'text', text: 'Moved.' }],
570
+ content: entityTextContent({ item }, 'Moved item:', item),
520
571
  };
521
572
  });
522
573
  registerTool(`${deps.toolPrefix}.list_organizations`, {
@@ -621,7 +672,7 @@ export function registerTools(server, deps) {
621
672
  const structuredContent = { item };
622
673
  return {
623
674
  structuredContent,
624
- content: toolTextContent(structuredContent, 'OK'),
675
+ content: entityTextContent(structuredContent, 'Item:', item),
625
676
  };
626
677
  });
627
678
  registerTool(`${deps.toolPrefix}.get_uri`, {
@@ -690,7 +741,7 @@ export function registerTools(server, deps) {
690
741
  const structuredContent = { folder };
691
742
  return {
692
743
  structuredContent,
693
- content: toolTextContent(structuredContent, 'OK'),
744
+ content: entityTextContent(structuredContent, 'Folder:', folder),
694
745
  };
695
746
  });
696
747
  registerTool(`${deps.toolPrefix}.get_collection`, {
@@ -708,7 +759,7 @@ export function registerTools(server, deps) {
708
759
  const structuredContent = { collection };
709
760
  return {
710
761
  structuredContent,
711
- content: toolTextContent(structuredContent, 'OK'),
762
+ content: entityTextContent(structuredContent, 'Collection:', collection),
712
763
  };
713
764
  });
714
765
  registerTool(`${deps.toolPrefix}.get_organization`, {
@@ -725,7 +776,7 @@ export function registerTools(server, deps) {
725
776
  const structuredContent = { organization };
726
777
  return {
727
778
  structuredContent,
728
- content: toolTextContent(structuredContent, 'OK'),
779
+ content: entityTextContent(structuredContent, 'Organization:', organization),
729
780
  };
730
781
  });
731
782
  registerTool(`${deps.toolPrefix}.get_org_collection`, {
@@ -743,7 +794,7 @@ export function registerTools(server, deps) {
743
794
  const structuredContent = { collection };
744
795
  return {
745
796
  structuredContent,
746
- content: toolTextContent(structuredContent, 'OK'),
797
+ content: entityTextContent(structuredContent, 'Org collection:', collection),
747
798
  };
748
799
  });
749
800
  registerTool(`${deps.toolPrefix}.delete_item`, {
@@ -760,9 +811,10 @@ export function registerTools(server, deps) {
760
811
  return readonlyBlocked();
761
812
  const sdk = await deps.getSdk(extra.authInfo);
762
813
  await sdk.deleteItem(input);
814
+ const structuredContent = { ok: true, id: input.id };
763
815
  return {
764
- structuredContent: { ok: true },
765
- content: [{ type: 'text', text: 'Deleted.' }],
816
+ structuredContent,
817
+ content: idTextContent(structuredContent, 'Deleted item', input.id),
766
818
  };
767
819
  });
768
820
  registerTool(`${deps.toolPrefix}.delete_items`, {
@@ -780,11 +832,10 @@ export function registerTools(server, deps) {
780
832
  const sdk = await deps.getSdk(extra.authInfo);
781
833
  const results = await sdk.deleteItems(input);
782
834
  const okCount = results.filter((r) => r.ok).length;
835
+ const structuredContent = { results, okCount, total: results.length };
783
836
  return {
784
- structuredContent: { results, okCount, total: results.length },
785
- content: [
786
- { type: 'text', text: `Deleted ${okCount}/${results.length}.` },
787
- ],
837
+ structuredContent,
838
+ content: structuredTextContent(structuredContent, `Deleted ${okCount}/${results.length}: ${input.ids.join(', ')}`),
788
839
  };
789
840
  });
790
841
  registerTool(`${deps.toolPrefix}.restore_item`, {
@@ -802,7 +853,7 @@ export function registerTools(server, deps) {
802
853
  const item = await sdk.restoreItem(input);
803
854
  return {
804
855
  structuredContent: { item },
805
- content: [{ type: 'text', text: 'Restored.' }],
856
+ content: entityTextContent({ item }, 'Restored item:', item),
806
857
  };
807
858
  });
808
859
  registerTool(`${deps.toolPrefix}.create_attachment`, {
@@ -823,7 +874,7 @@ export function registerTools(server, deps) {
823
874
  const item = await sdk.createAttachment(clampReveal(input));
824
875
  return {
825
876
  structuredContent: { item },
826
- content: [{ type: 'text', text: 'Attached.' }],
877
+ content: entityTextContent({ item }, 'Attached to item:', item),
827
878
  };
828
879
  });
829
880
  registerTool(`${deps.toolPrefix}.delete_attachment`, {
@@ -843,7 +894,7 @@ export function registerTools(server, deps) {
843
894
  const item = await sdk.deleteAttachment(clampReveal(input));
844
895
  return {
845
896
  structuredContent: { item },
846
- content: [{ type: 'text', text: 'Deleted.' }],
897
+ content: entityTextContent({ item }, 'Deleted attachment from item:', item),
847
898
  };
848
899
  });
849
900
  registerTool(`${deps.toolPrefix}.get_attachment`, {
@@ -861,7 +912,7 @@ export function registerTools(server, deps) {
861
912
  const structuredContent = { attachment };
862
913
  return {
863
914
  structuredContent,
864
- content: toolTextContent(structuredContent, 'OK'),
915
+ content: toolTextContent(structuredContent, `Downloaded attachment: filename=${quoteText(attachment.filename)} bytes=${attachment.bytes}`),
865
916
  };
866
917
  });
867
918
  registerTool(`${deps.toolPrefix}.send_list`, {
@@ -1214,7 +1265,7 @@ export function registerTools(server, deps) {
1214
1265
  });
1215
1266
  return {
1216
1267
  structuredContent: { item: created },
1217
- content: [{ type: 'text', text: 'Created.' }],
1268
+ content: entityTextContent({ item: created }, 'Created item:', created),
1218
1269
  };
1219
1270
  });
1220
1271
  registerTool(`${deps.toolPrefix}.create_logins`, {
@@ -1266,11 +1317,13 @@ export function registerTools(server, deps) {
1266
1317
  })),
1267
1318
  continueOnError: input.continueOnError,
1268
1319
  });
1320
+ const structuredContent = { results };
1269
1321
  return {
1270
- structuredContent: { results },
1271
- content: [
1272
- { type: 'text', text: `Created ${results.length} login(s).` },
1273
- ],
1322
+ structuredContent,
1323
+ content: structuredTextContent(structuredContent, [
1324
+ `Created ${results.length} login(s):`,
1325
+ ...results.map(formatBatchCreateResult),
1326
+ ].join('\n')),
1274
1327
  };
1275
1328
  });
1276
1329
  registerTool(`${deps.toolPrefix}.set_login_uris`, {
@@ -1299,7 +1352,7 @@ export function registerTools(server, deps) {
1299
1352
  });
1300
1353
  return {
1301
1354
  structuredContent: { item: updated },
1302
- content: [{ type: 'text', text: 'Updated.' }],
1355
+ content: entityTextContent({ item: updated }, 'Updated item:', updated),
1303
1356
  };
1304
1357
  });
1305
1358
  registerTool(`${deps.toolPrefix}.create_note`, {
@@ -1329,7 +1382,7 @@ export function registerTools(server, deps) {
1329
1382
  const created = await sdk.createNote(input);
1330
1383
  return {
1331
1384
  structuredContent: { item: created },
1332
- content: [{ type: 'text', text: 'Created.' }],
1385
+ content: entityTextContent({ item: created }, 'Created item:', created),
1333
1386
  };
1334
1387
  });
1335
1388
  registerTool(`${deps.toolPrefix}.create_ssh_key`, {
@@ -1356,7 +1409,7 @@ export function registerTools(server, deps) {
1356
1409
  const created = await sdk.createSshKey(input);
1357
1410
  return {
1358
1411
  structuredContent: { item: created },
1359
- content: [{ type: 'text', text: 'Created.' }],
1412
+ content: entityTextContent({ item: created }, 'Created item:', created),
1360
1413
  };
1361
1414
  });
1362
1415
  registerTool(`${deps.toolPrefix}.create_card`, {
@@ -1392,7 +1445,7 @@ export function registerTools(server, deps) {
1392
1445
  const created = await sdk.createCard(input);
1393
1446
  return {
1394
1447
  structuredContent: { item: created },
1395
- content: [{ type: 'text', text: 'Created.' }],
1448
+ content: entityTextContent({ item: created }, 'Created item:', created),
1396
1449
  };
1397
1450
  });
1398
1451
  registerTool(`${deps.toolPrefix}.create_identity`, {
@@ -1444,7 +1497,7 @@ export function registerTools(server, deps) {
1444
1497
  const created = await sdk.createIdentity(input);
1445
1498
  return {
1446
1499
  structuredContent: { item: created },
1447
- content: [{ type: 'text', text: 'Created.' }],
1500
+ content: entityTextContent({ item: created }, 'Created item:', created),
1448
1501
  };
1449
1502
  });
1450
1503
  registerTool(`${deps.toolPrefix}.update_item`, {
@@ -1494,7 +1547,7 @@ export function registerTools(server, deps) {
1494
1547
  const updated = await sdk.updateItem(input.id, patch);
1495
1548
  return {
1496
1549
  structuredContent: { item: updated },
1497
- content: [{ type: 'text', text: 'Updated.' }],
1550
+ content: entityTextContent({ item: updated }, 'Updated item:', updated),
1498
1551
  };
1499
1552
  });
1500
1553
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "private": false,
3
3
  "name": "@icoretech/warden-mcp",
4
- "version": "0.2.16",
4
+ "version": "0.2.18",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "description": "Vaultwarden/Bitwarden MCP server backed by Bitwarden CLI (bw).",