@icoretech/warden-mcp 0.2.16 → 0.2.17

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
 
@@ -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
  }
@@ -122,6 +123,30 @@ export function registerTools(server, deps) {
122
123
  ...results.map(formatItemSummary),
123
124
  ].join('\n');
124
125
  }
126
+ function structuredTextContent(structuredContent, fallbackText) {
127
+ return toolTextContent(structuredContent, fallbackText);
128
+ }
129
+ function entityTextContent(structuredContent, heading, entity) {
130
+ if (textCompatMode === 'structured_json') {
131
+ return [
132
+ { type: 'text', text: JSON.stringify(structuredContent) },
133
+ ];
134
+ }
135
+ return [
136
+ {
137
+ type: 'text',
138
+ text: [heading, formatItemSummary(entity)].join('\n'),
139
+ },
140
+ ];
141
+ }
142
+ function idTextContent(structuredContent, action, id) {
143
+ return structuredTextContent(structuredContent, `${action} id=${id}.`);
144
+ }
145
+ function formatBatchCreateResult(result) {
146
+ if (result.ok)
147
+ return formatItemSummary(result.item);
148
+ return `- error=${quoteText(result.error ?? 'unknown')}`;
149
+ }
125
150
  function toolValueContent(structuredContent, kind, value, revealed, extraLines = []) {
126
151
  if (textCompatMode === 'structured_json') {
127
152
  return [
@@ -143,15 +168,10 @@ export function registerTools(server, deps) {
143
168
  };
144
169
  return {
145
170
  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
- ],
171
+ content: structuredTextContent(structuredContent, [
172
+ `${error.message}. Retry with term set to an exact id.`,
173
+ ...error.candidates.map(formatItemSummary),
174
+ ].join('\n')),
155
175
  isError: true,
156
176
  };
157
177
  }
@@ -368,7 +388,7 @@ export function registerTools(server, deps) {
368
388
  const folder = await sdk.createFolder({ name: input.name });
369
389
  return {
370
390
  structuredContent: { folder },
371
- content: [{ type: 'text', text: 'Created.' }],
391
+ content: entityTextContent({ folder }, 'Created folder:', folder),
372
392
  };
373
393
  });
374
394
  registerTool(`${deps.toolPrefix}.edit_folder`, {
@@ -387,7 +407,7 @@ export function registerTools(server, deps) {
387
407
  const folder = await sdk.editFolder(input);
388
408
  return {
389
409
  structuredContent: { folder },
390
- content: [{ type: 'text', text: 'Updated.' }],
410
+ content: entityTextContent({ folder }, 'Updated folder:', folder),
391
411
  };
392
412
  });
393
413
  registerTool(`${deps.toolPrefix}.delete_folder`, {
@@ -403,9 +423,10 @@ export function registerTools(server, deps) {
403
423
  return readonlyBlocked();
404
424
  const sdk = await deps.getSdk(extra.authInfo);
405
425
  await sdk.deleteFolder(input);
426
+ const structuredContent = { ok: true, id: input.id };
406
427
  return {
407
- structuredContent: { ok: true },
408
- content: [{ type: 'text', text: 'Deleted.' }],
428
+ structuredContent,
429
+ content: idTextContent(structuredContent, 'Deleted folder', input.id),
409
430
  };
410
431
  });
411
432
  registerTool(`${deps.toolPrefix}.list_org_collections`, {
@@ -457,7 +478,7 @@ export function registerTools(server, deps) {
457
478
  const collection = await sdk.createOrgCollection(input);
458
479
  return {
459
480
  structuredContent: { collection },
460
- content: [{ type: 'text', text: 'Created.' }],
481
+ content: entityTextContent({ collection }, 'Created org collection:', collection),
461
482
  };
462
483
  });
463
484
  registerTool(`${deps.toolPrefix}.edit_org_collection`, {
@@ -477,7 +498,7 @@ export function registerTools(server, deps) {
477
498
  const collection = await sdk.editOrgCollection(input);
478
499
  return {
479
500
  structuredContent: { collection },
480
- content: [{ type: 'text', text: 'Updated.' }],
501
+ content: entityTextContent({ collection }, 'Updated org collection:', collection),
481
502
  };
482
503
  });
483
504
  registerTool(`${deps.toolPrefix}.delete_org_collection`, {
@@ -494,9 +515,14 @@ export function registerTools(server, deps) {
494
515
  return readonlyBlocked();
495
516
  const sdk = await deps.getSdk(extra.authInfo);
496
517
  await sdk.deleteOrgCollection(input);
518
+ const structuredContent = {
519
+ ok: true,
520
+ id: input.id,
521
+ organizationId: input.organizationId ?? null,
522
+ };
497
523
  return {
498
- structuredContent: { ok: true },
499
- content: [{ type: 'text', text: 'Deleted.' }],
524
+ structuredContent,
525
+ content: idTextContent(structuredContent, 'Deleted org collection', input.id),
500
526
  };
501
527
  });
502
528
  registerTool(`${deps.toolPrefix}.move_item_to_organization`, {
@@ -516,7 +542,7 @@ export function registerTools(server, deps) {
516
542
  const item = await sdk.moveItemToOrganization(input);
517
543
  return {
518
544
  structuredContent: { item },
519
- content: [{ type: 'text', text: 'Moved.' }],
545
+ content: entityTextContent({ item }, 'Moved item:', item),
520
546
  };
521
547
  });
522
548
  registerTool(`${deps.toolPrefix}.list_organizations`, {
@@ -621,7 +647,7 @@ export function registerTools(server, deps) {
621
647
  const structuredContent = { item };
622
648
  return {
623
649
  structuredContent,
624
- content: toolTextContent(structuredContent, 'OK'),
650
+ content: entityTextContent(structuredContent, 'Item:', item),
625
651
  };
626
652
  });
627
653
  registerTool(`${deps.toolPrefix}.get_uri`, {
@@ -690,7 +716,7 @@ export function registerTools(server, deps) {
690
716
  const structuredContent = { folder };
691
717
  return {
692
718
  structuredContent,
693
- content: toolTextContent(structuredContent, 'OK'),
719
+ content: entityTextContent(structuredContent, 'Folder:', folder),
694
720
  };
695
721
  });
696
722
  registerTool(`${deps.toolPrefix}.get_collection`, {
@@ -708,7 +734,7 @@ export function registerTools(server, deps) {
708
734
  const structuredContent = { collection };
709
735
  return {
710
736
  structuredContent,
711
- content: toolTextContent(structuredContent, 'OK'),
737
+ content: entityTextContent(structuredContent, 'Collection:', collection),
712
738
  };
713
739
  });
714
740
  registerTool(`${deps.toolPrefix}.get_organization`, {
@@ -725,7 +751,7 @@ export function registerTools(server, deps) {
725
751
  const structuredContent = { organization };
726
752
  return {
727
753
  structuredContent,
728
- content: toolTextContent(structuredContent, 'OK'),
754
+ content: entityTextContent(structuredContent, 'Organization:', organization),
729
755
  };
730
756
  });
731
757
  registerTool(`${deps.toolPrefix}.get_org_collection`, {
@@ -743,7 +769,7 @@ export function registerTools(server, deps) {
743
769
  const structuredContent = { collection };
744
770
  return {
745
771
  structuredContent,
746
- content: toolTextContent(structuredContent, 'OK'),
772
+ content: entityTextContent(structuredContent, 'Org collection:', collection),
747
773
  };
748
774
  });
749
775
  registerTool(`${deps.toolPrefix}.delete_item`, {
@@ -760,9 +786,10 @@ export function registerTools(server, deps) {
760
786
  return readonlyBlocked();
761
787
  const sdk = await deps.getSdk(extra.authInfo);
762
788
  await sdk.deleteItem(input);
789
+ const structuredContent = { ok: true, id: input.id };
763
790
  return {
764
- structuredContent: { ok: true },
765
- content: [{ type: 'text', text: 'Deleted.' }],
791
+ structuredContent,
792
+ content: idTextContent(structuredContent, 'Deleted item', input.id),
766
793
  };
767
794
  });
768
795
  registerTool(`${deps.toolPrefix}.delete_items`, {
@@ -780,11 +807,10 @@ export function registerTools(server, deps) {
780
807
  const sdk = await deps.getSdk(extra.authInfo);
781
808
  const results = await sdk.deleteItems(input);
782
809
  const okCount = results.filter((r) => r.ok).length;
810
+ const structuredContent = { results, okCount, total: results.length };
783
811
  return {
784
- structuredContent: { results, okCount, total: results.length },
785
- content: [
786
- { type: 'text', text: `Deleted ${okCount}/${results.length}.` },
787
- ],
812
+ structuredContent,
813
+ content: structuredTextContent(structuredContent, `Deleted ${okCount}/${results.length}: ${input.ids.join(', ')}`),
788
814
  };
789
815
  });
790
816
  registerTool(`${deps.toolPrefix}.restore_item`, {
@@ -802,7 +828,7 @@ export function registerTools(server, deps) {
802
828
  const item = await sdk.restoreItem(input);
803
829
  return {
804
830
  structuredContent: { item },
805
- content: [{ type: 'text', text: 'Restored.' }],
831
+ content: entityTextContent({ item }, 'Restored item:', item),
806
832
  };
807
833
  });
808
834
  registerTool(`${deps.toolPrefix}.create_attachment`, {
@@ -823,7 +849,7 @@ export function registerTools(server, deps) {
823
849
  const item = await sdk.createAttachment(clampReveal(input));
824
850
  return {
825
851
  structuredContent: { item },
826
- content: [{ type: 'text', text: 'Attached.' }],
852
+ content: entityTextContent({ item }, 'Attached to item:', item),
827
853
  };
828
854
  });
829
855
  registerTool(`${deps.toolPrefix}.delete_attachment`, {
@@ -843,7 +869,7 @@ export function registerTools(server, deps) {
843
869
  const item = await sdk.deleteAttachment(clampReveal(input));
844
870
  return {
845
871
  structuredContent: { item },
846
- content: [{ type: 'text', text: 'Deleted.' }],
872
+ content: entityTextContent({ item }, 'Deleted attachment from item:', item),
847
873
  };
848
874
  });
849
875
  registerTool(`${deps.toolPrefix}.get_attachment`, {
@@ -1214,7 +1240,7 @@ export function registerTools(server, deps) {
1214
1240
  });
1215
1241
  return {
1216
1242
  structuredContent: { item: created },
1217
- content: [{ type: 'text', text: 'Created.' }],
1243
+ content: entityTextContent({ item: created }, 'Created item:', created),
1218
1244
  };
1219
1245
  });
1220
1246
  registerTool(`${deps.toolPrefix}.create_logins`, {
@@ -1266,11 +1292,13 @@ export function registerTools(server, deps) {
1266
1292
  })),
1267
1293
  continueOnError: input.continueOnError,
1268
1294
  });
1295
+ const structuredContent = { results };
1269
1296
  return {
1270
- structuredContent: { results },
1271
- content: [
1272
- { type: 'text', text: `Created ${results.length} login(s).` },
1273
- ],
1297
+ structuredContent,
1298
+ content: structuredTextContent(structuredContent, [
1299
+ `Created ${results.length} login(s):`,
1300
+ ...results.map(formatBatchCreateResult),
1301
+ ].join('\n')),
1274
1302
  };
1275
1303
  });
1276
1304
  registerTool(`${deps.toolPrefix}.set_login_uris`, {
@@ -1299,7 +1327,7 @@ export function registerTools(server, deps) {
1299
1327
  });
1300
1328
  return {
1301
1329
  structuredContent: { item: updated },
1302
- content: [{ type: 'text', text: 'Updated.' }],
1330
+ content: entityTextContent({ item: updated }, 'Updated item:', updated),
1303
1331
  };
1304
1332
  });
1305
1333
  registerTool(`${deps.toolPrefix}.create_note`, {
@@ -1329,7 +1357,7 @@ export function registerTools(server, deps) {
1329
1357
  const created = await sdk.createNote(input);
1330
1358
  return {
1331
1359
  structuredContent: { item: created },
1332
- content: [{ type: 'text', text: 'Created.' }],
1360
+ content: entityTextContent({ item: created }, 'Created item:', created),
1333
1361
  };
1334
1362
  });
1335
1363
  registerTool(`${deps.toolPrefix}.create_ssh_key`, {
@@ -1356,7 +1384,7 @@ export function registerTools(server, deps) {
1356
1384
  const created = await sdk.createSshKey(input);
1357
1385
  return {
1358
1386
  structuredContent: { item: created },
1359
- content: [{ type: 'text', text: 'Created.' }],
1387
+ content: entityTextContent({ item: created }, 'Created item:', created),
1360
1388
  };
1361
1389
  });
1362
1390
  registerTool(`${deps.toolPrefix}.create_card`, {
@@ -1392,7 +1420,7 @@ export function registerTools(server, deps) {
1392
1420
  const created = await sdk.createCard(input);
1393
1421
  return {
1394
1422
  structuredContent: { item: created },
1395
- content: [{ type: 'text', text: 'Created.' }],
1423
+ content: entityTextContent({ item: created }, 'Created item:', created),
1396
1424
  };
1397
1425
  });
1398
1426
  registerTool(`${deps.toolPrefix}.create_identity`, {
@@ -1444,7 +1472,7 @@ export function registerTools(server, deps) {
1444
1472
  const created = await sdk.createIdentity(input);
1445
1473
  return {
1446
1474
  structuredContent: { item: created },
1447
- content: [{ type: 'text', text: 'Created.' }],
1475
+ content: entityTextContent({ item: created }, 'Created item:', created),
1448
1476
  };
1449
1477
  });
1450
1478
  registerTool(`${deps.toolPrefix}.update_item`, {
@@ -1494,7 +1522,7 @@ export function registerTools(server, deps) {
1494
1522
  const updated = await sdk.updateItem(input.id, patch);
1495
1523
  return {
1496
1524
  structuredContent: { item: updated },
1497
- content: [{ type: 'text', text: 'Updated.' }],
1525
+ content: entityTextContent({ item: updated }, 'Updated item:', updated),
1498
1526
  };
1499
1527
  });
1500
1528
  }
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.17",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "description": "Vaultwarden/Bitwarden MCP server backed by Bitwarden CLI (bw).",