@icoretech/warden-mcp 0.2.15 → 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
@@ -21,6 +21,37 @@ Published package: [`@icoretech/warden-mcp`](https://www.npmjs.com/package/@icor
21
21
  - Safe-by-default: item reads are **redacted** unless explicitly revealed; secret helper tools return `null` unless `reveal: true`
22
22
  - Strong fit for LLM automation: pair it with a browser-capable MCP host so an agent can fetch credentials, complete sign-in flows, read TOTP codes, and keep automating after login
23
23
 
24
+ ## Text-Only MCP Client Behavior
25
+
26
+ Some MCP hosts, including agent shells that optimize tool output for the model,
27
+ only forward `content[]` text blocks and do not expose `structuredContent` to
28
+ the agent. `warden-mcp` therefore mirrors the non-secret identifiers needed for
29
+ follow-up calls into visible text by default.
30
+
31
+ For search/list tools, the text output includes concise rows with stable ids and
32
+ safe metadata such as names, item type, username, URI values, organization id,
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.
38
+
39
+ For scalar helper tools, the text output follows the reveal contract:
40
+
41
+ - `get_username` shows the username because Bitwarden treats it as non-secret
42
+ - `get_password`, `get_totp`, and `get_notes` show `not revealed` unless you pass
43
+ `reveal: true`
44
+ - if `NOREVEAL=true` or `KEYCHAIN_NOREVEAL=true`, revealed values are still
45
+ suppressed server-side
46
+
47
+ When a lookup term matches multiple login items, credential helpers return an
48
+ `AMBIGUOUS_LOOKUP` error with visible candidate ids. Retry with `term` set to an
49
+ exact candidate `id`, or call `get_item` with that `id`.
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
+
24
55
  ## LLM Automation Use Case
25
56
 
26
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.
@@ -432,7 +463,7 @@ Mutation control:
432
463
 
433
464
  - Set `READONLY=true` to block all write operations (create/edit/delete/move/restore/attachments).
434
465
  - Set `NOREVEAL=true` to force all `reveal` parameters to `false` server-side. Clients can still request `reveal: true`, but the server will silently downgrade to redacted output. This prevents prompt injection from tricking an LLM agent into exfiltrating secrets.
435
- - Set `KEYCHAIN_TEXT_COMPAT_MODE=structured_json` to mirror any structured `OK` tool result into `TextContent` as serialized JSON. This is useful for text-only MCP clients that ignore `structuredContent`, but it also duplicates revealed secrets into the plain-text transcript.
466
+ - Set `KEYCHAIN_TEXT_COMPAT_MODE=structured_json` to mirror supported structured tool results into `TextContent` as serialized JSON. This is useful for text-only MCP clients that ignore `structuredContent`, but it also duplicates revealed secrets into the plain-text transcript.
436
467
  - Tool names default to `keychain_*`. Override `TOOL_PREFIX` to change the namespace and `TOOL_SEPARATOR` to change the separator (default `_`, set `.` for legacy clients).
437
468
  - Session guardrails:
438
469
  - `KEYCHAIN_SESSION_MAX_COUNT` (default `32`)
@@ -442,7 +473,7 @@ Mutation control:
442
473
  - `KEYCHAIN_METRICS_LOG_INTERVAL_MS` (default `0`, disabled)
443
474
  - `NOREVEAL` / `KEYCHAIN_NOREVEAL` (default `false`; force all reveals to false)
444
475
  - `KEYCHAIN_ALLOW_ENV_FALLBACK` (default `false`; HTTP env-var credential fallback)
445
- - `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`)
446
477
 
447
478
  Redaction defaults (item reads):
448
479
 
@@ -115,6 +115,14 @@ function isSshKeyItem(item) {
115
115
  .filter((n) => typeof n === 'string'));
116
116
  return names.has('public_key') && names.has('private_key');
117
117
  }
118
+ export class AmbiguousLoginLookupError extends Error {
119
+ candidates;
120
+ constructor(message, candidates) {
121
+ super(message);
122
+ this.name = 'AmbiguousLoginLookupError';
123
+ this.candidates = candidates;
124
+ }
125
+ }
118
126
  export class KeychainSdk {
119
127
  bw;
120
128
  constructor(bw) {
@@ -235,6 +243,65 @@ export class KeychainSdk {
235
243
  const username = login?.username;
236
244
  return terms.some((term) => id === term || name === term || username === term);
237
245
  }
246
+ loginCandidateSummary(item) {
247
+ const login = item.login && typeof item.login === 'object'
248
+ ? item.login
249
+ : null;
250
+ const username = login?.username;
251
+ return {
252
+ id: typeof item.id === 'string' ? item.id : undefined,
253
+ name: typeof item.name === 'string' ? item.name : undefined,
254
+ type: kindFromItem(item),
255
+ username: typeof username === 'string' ? username : undefined,
256
+ uris: denormalizeUris(login?.uris),
257
+ organizationId: typeof item.organizationId === 'string' ? item.organizationId : null,
258
+ folderId: typeof item.folderId === 'string' ? item.folderId : null,
259
+ collectionIds: Array.isArray(item.collectionIds)
260
+ ? item.collectionIds
261
+ : undefined,
262
+ favorite: typeof item.favorite === 'boolean' ? item.favorite : undefined,
263
+ };
264
+ }
265
+ async searchLoginCandidatesForSession(session, term) {
266
+ const tokens = term
267
+ .split('|')
268
+ .map((token) => token.trim())
269
+ .filter((token) => token.length > 0);
270
+ const terms = tokens.length ? tokens : [term];
271
+ const byId = new Map();
272
+ for (const searchTerm of terms) {
273
+ const { stdout } = await this.bw.runForSession(session, ['list', 'items', '--search', searchTerm], { timeoutMs: 120_000 });
274
+ const results = this.parseBwJson(stdout);
275
+ for (const raw of results) {
276
+ if (!raw || typeof raw !== 'object')
277
+ continue;
278
+ const item = raw;
279
+ if (item.type !== ITEM_TYPE.login)
280
+ continue;
281
+ const id = item.id;
282
+ if (typeof id === 'string' && id.length > 0)
283
+ byId.set(id, item);
284
+ }
285
+ }
286
+ return { terms, candidates: [...byId.values()] };
287
+ }
288
+ narrowLoginCandidates(candidates, terms) {
289
+ const exactCandidates = candidates.filter((item) => this.candidateMatchesTerm(item, terms));
290
+ return exactCandidates.length > 0 ? exactCandidates : candidates;
291
+ }
292
+ async resolveUniqueLoginCandidateForSession(session, term, kind) {
293
+ if (!term.trim())
294
+ throw new Error(`${kind} lookup term is empty`);
295
+ const { terms, candidates } = await this.searchLoginCandidatesForSession(session, term);
296
+ if (candidates.length === 0) {
297
+ throw new Error(`${kind} lookup failed: no login item found`);
298
+ }
299
+ const narrowed = this.narrowLoginCandidates(candidates, terms);
300
+ if (narrowed.length !== 1) {
301
+ throw new AmbiguousLoginLookupError(`${kind} lookup failed: multiple matching login items found`, narrowed.map((item) => this.loginCandidateSummary(item)));
302
+ }
303
+ return narrowed[0];
304
+ }
238
305
  async resolveTotpConfigForSession(session, term) {
239
306
  const direct = await this.bw
240
307
  .runForSession(session, ['get', 'item', term], { timeoutMs: 60_000 })
@@ -969,21 +1036,9 @@ export class KeychainSdk {
969
1036
  throw error;
970
1037
  if (!isUsernameLookupFailure(error))
971
1038
  throw error;
972
- const { stdout } = await this.bw.runForSession(session, ['list', 'items', '--search', term], { timeoutMs: 120_000 });
973
- const rawResults = this.parseBwJson(stdout);
974
- const candidates = rawResults.filter((raw) => !!raw &&
975
- typeof raw === 'object' &&
976
- raw.type === ITEM_TYPE.login);
977
- if (candidates.length === 0) {
978
- throw new Error('Username lookup failed: no login item found');
979
- }
980
- const exactCandidates = candidates.filter((item) => this.candidateMatchesTerm(item, [term]));
981
- const narrowed = exactCandidates.length > 0 ? exactCandidates : candidates;
982
- if (narrowed.length !== 1) {
983
- throw new Error('Username lookup failed: multiple matching login items found');
984
- }
985
- const login = narrowed[0]?.login && typeof narrowed[0].login === 'object'
986
- ? narrowed[0].login
1039
+ const candidate = await this.resolveUniqueLoginCandidateForSession(session, term, 'Username');
1040
+ const login = candidate.login && typeof candidate.login === 'object'
1041
+ ? candidate.login
987
1042
  : null;
988
1043
  const username = login?.username;
989
1044
  if (typeof username !== 'string' || username.trim().length === 0) {
@@ -997,9 +1052,31 @@ export class KeychainSdk {
997
1052
  async getPassword(input, opts = {}) {
998
1053
  if (!opts.reveal)
999
1054
  return this.valueResult(null, false);
1055
+ const term = input.term.trim();
1056
+ if (!term)
1057
+ throw new Error('Password lookup term is empty');
1000
1058
  return this.bw.withSession(async (session) => {
1001
- const { stdout } = await this.bw.runForSession(session, ['--raw', 'get', 'password', input.term], { timeoutMs: 60_000 });
1002
- return this.valueResult(stdout.trim(), true);
1059
+ try {
1060
+ const { stdout } = await this.bw.runForSession(session, ['--raw', 'get', 'password', term], { timeoutMs: 60_000 });
1061
+ return this.valueResult(stdout.trim(), true);
1062
+ }
1063
+ catch (error) {
1064
+ if (isBwAuthSessionInvalidError(error))
1065
+ throw error;
1066
+ if (!(error instanceof BwCliError) || error.exitCode !== 1)
1067
+ throw error;
1068
+ if (!isUsernameLookupFailure(error))
1069
+ throw error;
1070
+ const candidate = await this.resolveUniqueLoginCandidateForSession(session, term, 'Password');
1071
+ const login = candidate.login && typeof candidate.login === 'object'
1072
+ ? candidate.login
1073
+ : null;
1074
+ const password = login?.password;
1075
+ if (typeof password !== 'string') {
1076
+ throw new Error('Password lookup found an empty password');
1077
+ }
1078
+ return this.valueResult(password, true);
1079
+ }
1003
1080
  });
1004
1081
  }
1005
1082
  async getTotp(input, opts = {}) {
@@ -1384,10 +1461,16 @@ export class KeychainSdk {
1384
1461
  if (!item || typeof item !== 'object')
1385
1462
  return item;
1386
1463
  const rec = item;
1387
- return {
1464
+ const login = rec.login && typeof rec.login === 'object'
1465
+ ? rec.login
1466
+ : null;
1467
+ const username = login?.username;
1468
+ const summary = {
1388
1469
  id: typeof rec.id === 'string' ? rec.id : undefined,
1389
1470
  name: typeof rec.name === 'string' ? rec.name : undefined,
1390
1471
  type: kindFromItem(rec),
1472
+ username: typeof username === 'string' ? username : undefined,
1473
+ uris: denormalizeUris(login?.uris),
1391
1474
  organizationId: typeof rec.organizationId === 'string' ? rec.organizationId : null,
1392
1475
  folderId: typeof rec.folderId === 'string' ? rec.folderId : null,
1393
1476
  collectionIds: Array.isArray(rec.collectionIds)
@@ -1395,5 +1478,6 @@ export class KeychainSdk {
1395
1478
  : undefined,
1396
1479
  favorite: typeof rec.favorite === 'boolean' ? rec.favorite : undefined,
1397
1480
  };
1481
+ return summary;
1398
1482
  }
1399
1483
  }
@@ -1,5 +1,6 @@
1
1
  // src/tools/registerTools.ts
2
2
  import { z } from 'zod';
3
+ import { AmbiguousLoginLookupError, } from '../sdk/keychainSdk.js';
3
4
  export function registerTools(server, deps) {
4
5
  const toolMeta = {};
5
6
  const mutatingToolAnnotations = {
@@ -37,9 +38,10 @@ export function registerTools(server, deps) {
37
38
  const isNoReveal = parseBoolEnv('NOREVEAL', 'KEYCHAIN_NOREVEAL');
38
39
  const textCompatMode = process.env.KEYCHAIN_TEXT_COMPAT_MODE?.trim().toLowerCase();
39
40
  function readonlyBlocked() {
41
+ const structuredContent = { ok: false, error: 'READONLY' };
40
42
  return {
41
- structuredContent: { ok: false, error: 'READONLY' },
42
- content: [{ type: 'text', text: 'Blocked: READONLY=true' }],
43
+ structuredContent,
44
+ content: toolTextContent(structuredContent, 'Blocked: READONLY=true'),
43
45
  isError: true,
44
46
  };
45
47
  }
@@ -62,6 +64,117 @@ export function registerTools(server, deps) {
62
64
  : fallbackText;
63
65
  return [{ type: 'text', text }];
64
66
  }
67
+ function quoteText(value) {
68
+ return JSON.stringify(value);
69
+ }
70
+ function stringifyScalar(value) {
71
+ if (value === null || value === undefined)
72
+ return 'null';
73
+ if (typeof value === 'string')
74
+ return quoteText(value);
75
+ return JSON.stringify(value) ?? String(value);
76
+ }
77
+ function formatItemSummary(item) {
78
+ if (!item || typeof item !== 'object')
79
+ return `- ${stringifyScalar(item)}`;
80
+ const rec = item;
81
+ const parts = [];
82
+ if (typeof rec.id === 'string')
83
+ parts.push(`id=${rec.id}`);
84
+ if (typeof rec.name === 'string')
85
+ parts.push(`name=${quoteText(rec.name)}`);
86
+ if (typeof rec.type === 'string')
87
+ parts.push(`type=${rec.type}`);
88
+ if (typeof rec.username === 'string') {
89
+ parts.push(`username=${quoteText(rec.username)}`);
90
+ }
91
+ if (Array.isArray(rec.uris) && rec.uris.length > 0) {
92
+ const uris = rec.uris
93
+ .map((uri) => {
94
+ if (!uri || typeof uri !== 'object')
95
+ return null;
96
+ const value = uri.uri;
97
+ return typeof value === 'string' ? value : null;
98
+ })
99
+ .filter((uri) => uri !== null);
100
+ if (uris.length > 0)
101
+ parts.push(`uris=${quoteText(uris.join(', '))}`);
102
+ }
103
+ if (typeof rec.organizationId === 'string') {
104
+ parts.push(`organizationId=${rec.organizationId}`);
105
+ }
106
+ if (typeof rec.folderId === 'string')
107
+ parts.push(`folderId=${rec.folderId}`);
108
+ if (Array.isArray(rec.collectionIds) && rec.collectionIds.length > 0) {
109
+ parts.push(`collectionIds=${quoteText(rec.collectionIds.join(', '))}`);
110
+ }
111
+ if (typeof rec.favorite === 'boolean')
112
+ parts.push(`favorite=${rec.favorite}`);
113
+ return `- ${parts.length > 0 ? parts.join(' ') : stringifyScalar(rec)}`;
114
+ }
115
+ function formatResultsText(label, results) {
116
+ if (textCompatMode === 'structured_json') {
117
+ return JSON.stringify({ results });
118
+ }
119
+ if (results.length === 0)
120
+ return `Found 0 ${label}.`;
121
+ return [
122
+ `Found ${results.length} ${label}:`,
123
+ ...results.map(formatItemSummary),
124
+ ].join('\n');
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
+ }
150
+ function toolValueContent(structuredContent, kind, value, revealed, extraLines = []) {
151
+ if (textCompatMode === 'structured_json') {
152
+ return [
153
+ { type: 'text', text: JSON.stringify(structuredContent) },
154
+ ];
155
+ }
156
+ const lines = [
157
+ `${kind}: ${revealed ? stringifyScalar(value) : 'not revealed'}`,
158
+ ...extraLines,
159
+ ];
160
+ return [{ type: 'text', text: lines.join('\n') }];
161
+ }
162
+ function ambiguousLookupResult(error) {
163
+ const structuredContent = {
164
+ ok: false,
165
+ error: 'AMBIGUOUS_LOOKUP',
166
+ message: error.message,
167
+ candidates: error.candidates,
168
+ };
169
+ return {
170
+ structuredContent,
171
+ content: structuredTextContent(structuredContent, [
172
+ `${error.message}. Retry with term set to an exact id.`,
173
+ ...error.candidates.map(formatItemSummary),
174
+ ].join('\n')),
175
+ isError: true,
176
+ };
177
+ }
65
178
  const uriMatchSchema = z.enum([
66
179
  'domain',
67
180
  'host',
@@ -255,7 +368,9 @@ export function registerTools(server, deps) {
255
368
  });
256
369
  return {
257
370
  structuredContent: { results },
258
- content: [{ type: 'text', text: `Found ${results.length} folder(s).` }],
371
+ content: [
372
+ { type: 'text', text: formatResultsText('folder(s)', results) },
373
+ ],
259
374
  };
260
375
  });
261
376
  registerTool(`${deps.toolPrefix}.create_folder`, {
@@ -273,7 +388,7 @@ export function registerTools(server, deps) {
273
388
  const folder = await sdk.createFolder({ name: input.name });
274
389
  return {
275
390
  structuredContent: { folder },
276
- content: [{ type: 'text', text: 'Created.' }],
391
+ content: entityTextContent({ folder }, 'Created folder:', folder),
277
392
  };
278
393
  });
279
394
  registerTool(`${deps.toolPrefix}.edit_folder`, {
@@ -292,7 +407,7 @@ export function registerTools(server, deps) {
292
407
  const folder = await sdk.editFolder(input);
293
408
  return {
294
409
  structuredContent: { folder },
295
- content: [{ type: 'text', text: 'Updated.' }],
410
+ content: entityTextContent({ folder }, 'Updated folder:', folder),
296
411
  };
297
412
  });
298
413
  registerTool(`${deps.toolPrefix}.delete_folder`, {
@@ -308,9 +423,10 @@ export function registerTools(server, deps) {
308
423
  return readonlyBlocked();
309
424
  const sdk = await deps.getSdk(extra.authInfo);
310
425
  await sdk.deleteFolder(input);
426
+ const structuredContent = { ok: true, id: input.id };
311
427
  return {
312
- structuredContent: { ok: true },
313
- content: [{ type: 'text', text: 'Deleted.' }],
428
+ structuredContent,
429
+ content: idTextContent(structuredContent, 'Deleted folder', input.id),
314
430
  };
315
431
  });
316
432
  registerTool(`${deps.toolPrefix}.list_org_collections`, {
@@ -339,7 +455,10 @@ export function registerTools(server, deps) {
339
455
  return {
340
456
  structuredContent: { results },
341
457
  content: [
342
- { type: 'text', text: `Found ${results.length} org collection(s).` },
458
+ {
459
+ type: 'text',
460
+ text: formatResultsText('org collection(s)', results),
461
+ },
343
462
  ],
344
463
  };
345
464
  });
@@ -359,7 +478,7 @@ export function registerTools(server, deps) {
359
478
  const collection = await sdk.createOrgCollection(input);
360
479
  return {
361
480
  structuredContent: { collection },
362
- content: [{ type: 'text', text: 'Created.' }],
481
+ content: entityTextContent({ collection }, 'Created org collection:', collection),
363
482
  };
364
483
  });
365
484
  registerTool(`${deps.toolPrefix}.edit_org_collection`, {
@@ -379,7 +498,7 @@ export function registerTools(server, deps) {
379
498
  const collection = await sdk.editOrgCollection(input);
380
499
  return {
381
500
  structuredContent: { collection },
382
- content: [{ type: 'text', text: 'Updated.' }],
501
+ content: entityTextContent({ collection }, 'Updated org collection:', collection),
383
502
  };
384
503
  });
385
504
  registerTool(`${deps.toolPrefix}.delete_org_collection`, {
@@ -396,9 +515,14 @@ export function registerTools(server, deps) {
396
515
  return readonlyBlocked();
397
516
  const sdk = await deps.getSdk(extra.authInfo);
398
517
  await sdk.deleteOrgCollection(input);
518
+ const structuredContent = {
519
+ ok: true,
520
+ id: input.id,
521
+ organizationId: input.organizationId ?? null,
522
+ };
399
523
  return {
400
- structuredContent: { ok: true },
401
- content: [{ type: 'text', text: 'Deleted.' }],
524
+ structuredContent,
525
+ content: idTextContent(structuredContent, 'Deleted org collection', input.id),
402
526
  };
403
527
  });
404
528
  registerTool(`${deps.toolPrefix}.move_item_to_organization`, {
@@ -418,7 +542,7 @@ export function registerTools(server, deps) {
418
542
  const item = await sdk.moveItemToOrganization(input);
419
543
  return {
420
544
  structuredContent: { item },
421
- content: [{ type: 'text', text: 'Moved.' }],
545
+ content: entityTextContent({ item }, 'Moved item:', item),
422
546
  };
423
547
  });
424
548
  registerTool(`${deps.toolPrefix}.list_organizations`, {
@@ -441,7 +565,7 @@ export function registerTools(server, deps) {
441
565
  });
442
566
  return {
443
567
  structuredContent: { results },
444
- content: [{ type: 'text', text: `Found ${results.length} org(s).` }],
568
+ content: [{ type: 'text', text: formatResultsText('org(s)', results) }],
445
569
  };
446
570
  });
447
571
  registerTool(`${deps.toolPrefix}.list_collections`, {
@@ -470,7 +594,7 @@ export function registerTools(server, deps) {
470
594
  return {
471
595
  structuredContent: { results },
472
596
  content: [
473
- { type: 'text', text: `Found ${results.length} collection(s).` },
597
+ { type: 'text', text: formatResultsText('collection(s)', results) },
474
598
  ],
475
599
  };
476
600
  });
@@ -501,7 +625,9 @@ export function registerTools(server, deps) {
501
625
  const minimal = items.map((i) => sdk.minimalSummary(i));
502
626
  return {
503
627
  structuredContent: { results: minimal },
504
- content: [{ type: 'text', text: `Found ${minimal.length} item(s).` }],
628
+ content: [
629
+ { type: 'text', text: formatResultsText('item(s)', minimal) },
630
+ ],
505
631
  };
506
632
  });
507
633
  registerTool(`${deps.toolPrefix}.get_item`, {
@@ -521,7 +647,7 @@ export function registerTools(server, deps) {
521
647
  const structuredContent = { item };
522
648
  return {
523
649
  structuredContent,
524
- content: toolTextContent(structuredContent, 'OK'),
650
+ content: entityTextContent(structuredContent, 'Item:', item),
525
651
  };
526
652
  });
527
653
  registerTool(`${deps.toolPrefix}.get_uri`, {
@@ -556,7 +682,7 @@ export function registerTools(server, deps) {
556
682
  const structuredContent = toolResult('notes', notes.value, notes.revealed);
557
683
  return {
558
684
  structuredContent,
559
- content: toolTextContent(structuredContent, 'OK'),
685
+ content: toolValueContent(structuredContent, 'notes', notes.value, notes.revealed),
560
686
  };
561
687
  });
562
688
  registerTool(`${deps.toolPrefix}.get_exposed`, {
@@ -590,7 +716,7 @@ export function registerTools(server, deps) {
590
716
  const structuredContent = { folder };
591
717
  return {
592
718
  structuredContent,
593
- content: toolTextContent(structuredContent, 'OK'),
719
+ content: entityTextContent(structuredContent, 'Folder:', folder),
594
720
  };
595
721
  });
596
722
  registerTool(`${deps.toolPrefix}.get_collection`, {
@@ -608,7 +734,7 @@ export function registerTools(server, deps) {
608
734
  const structuredContent = { collection };
609
735
  return {
610
736
  structuredContent,
611
- content: toolTextContent(structuredContent, 'OK'),
737
+ content: entityTextContent(structuredContent, 'Collection:', collection),
612
738
  };
613
739
  });
614
740
  registerTool(`${deps.toolPrefix}.get_organization`, {
@@ -625,7 +751,7 @@ export function registerTools(server, deps) {
625
751
  const structuredContent = { organization };
626
752
  return {
627
753
  structuredContent,
628
- content: toolTextContent(structuredContent, 'OK'),
754
+ content: entityTextContent(structuredContent, 'Organization:', organization),
629
755
  };
630
756
  });
631
757
  registerTool(`${deps.toolPrefix}.get_org_collection`, {
@@ -643,7 +769,7 @@ export function registerTools(server, deps) {
643
769
  const structuredContent = { collection };
644
770
  return {
645
771
  structuredContent,
646
- content: toolTextContent(structuredContent, 'OK'),
772
+ content: entityTextContent(structuredContent, 'Org collection:', collection),
647
773
  };
648
774
  });
649
775
  registerTool(`${deps.toolPrefix}.delete_item`, {
@@ -660,9 +786,10 @@ export function registerTools(server, deps) {
660
786
  return readonlyBlocked();
661
787
  const sdk = await deps.getSdk(extra.authInfo);
662
788
  await sdk.deleteItem(input);
789
+ const structuredContent = { ok: true, id: input.id };
663
790
  return {
664
- structuredContent: { ok: true },
665
- content: [{ type: 'text', text: 'Deleted.' }],
791
+ structuredContent,
792
+ content: idTextContent(structuredContent, 'Deleted item', input.id),
666
793
  };
667
794
  });
668
795
  registerTool(`${deps.toolPrefix}.delete_items`, {
@@ -680,11 +807,10 @@ export function registerTools(server, deps) {
680
807
  const sdk = await deps.getSdk(extra.authInfo);
681
808
  const results = await sdk.deleteItems(input);
682
809
  const okCount = results.filter((r) => r.ok).length;
810
+ const structuredContent = { results, okCount, total: results.length };
683
811
  return {
684
- structuredContent: { results, okCount, total: results.length },
685
- content: [
686
- { type: 'text', text: `Deleted ${okCount}/${results.length}.` },
687
- ],
812
+ structuredContent,
813
+ content: structuredTextContent(structuredContent, `Deleted ${okCount}/${results.length}: ${input.ids.join(', ')}`),
688
814
  };
689
815
  });
690
816
  registerTool(`${deps.toolPrefix}.restore_item`, {
@@ -702,7 +828,7 @@ export function registerTools(server, deps) {
702
828
  const item = await sdk.restoreItem(input);
703
829
  return {
704
830
  structuredContent: { item },
705
- content: [{ type: 'text', text: 'Restored.' }],
831
+ content: entityTextContent({ item }, 'Restored item:', item),
706
832
  };
707
833
  });
708
834
  registerTool(`${deps.toolPrefix}.create_attachment`, {
@@ -723,7 +849,7 @@ export function registerTools(server, deps) {
723
849
  const item = await sdk.createAttachment(clampReveal(input));
724
850
  return {
725
851
  structuredContent: { item },
726
- content: [{ type: 'text', text: 'Attached.' }],
852
+ content: entityTextContent({ item }, 'Attached to item:', item),
727
853
  };
728
854
  });
729
855
  registerTool(`${deps.toolPrefix}.delete_attachment`, {
@@ -743,7 +869,7 @@ export function registerTools(server, deps) {
743
869
  const item = await sdk.deleteAttachment(clampReveal(input));
744
870
  return {
745
871
  structuredContent: { item },
746
- content: [{ type: 'text', text: 'Deleted.' }],
872
+ content: entityTextContent({ item }, 'Deleted attachment from item:', item),
747
873
  };
748
874
  });
749
875
  registerTool(`${deps.toolPrefix}.get_attachment`, {
@@ -981,11 +1107,20 @@ export function registerTools(server, deps) {
981
1107
  _meta: toolMeta,
982
1108
  }, async (input, extra) => {
983
1109
  const sdk = await deps.getSdk(extra.authInfo);
984
- const username = await sdk.getUsername(input);
1110
+ let username;
1111
+ try {
1112
+ username = await sdk.getUsername(input);
1113
+ }
1114
+ catch (error) {
1115
+ if (error instanceof AmbiguousLoginLookupError) {
1116
+ return ambiguousLookupResult(error);
1117
+ }
1118
+ throw error;
1119
+ }
985
1120
  const structuredContent = toolResult('username', username.value, username.revealed);
986
1121
  return {
987
1122
  structuredContent,
988
- content: toolTextContent(structuredContent, 'OK'),
1123
+ content: toolValueContent(structuredContent, 'username', username.value, username.revealed),
989
1124
  };
990
1125
  });
991
1126
  registerTool(`${deps.toolPrefix}.get_password`, {
@@ -999,11 +1134,20 @@ export function registerTools(server, deps) {
999
1134
  _meta: toolMeta,
1000
1135
  }, async (input, extra) => {
1001
1136
  const sdk = await deps.getSdk(extra.authInfo);
1002
- const password = await sdk.getPassword({ term: input.term }, { reveal: effectiveReveal(input) });
1137
+ let password;
1138
+ try {
1139
+ password = await sdk.getPassword({ term: input.term }, { reveal: effectiveReveal(input) });
1140
+ }
1141
+ catch (error) {
1142
+ if (error instanceof AmbiguousLoginLookupError) {
1143
+ return ambiguousLookupResult(error);
1144
+ }
1145
+ throw error;
1146
+ }
1003
1147
  const structuredContent = toolResult('password', password.value, password.revealed);
1004
1148
  return {
1005
1149
  structuredContent,
1006
- content: toolTextContent(structuredContent, 'OK'),
1150
+ content: toolValueContent(structuredContent, 'password', password.value, password.revealed),
1007
1151
  };
1008
1152
  });
1009
1153
  registerTool(`${deps.toolPrefix}.get_totp`, {
@@ -1022,9 +1166,13 @@ export function registerTools(server, deps) {
1022
1166
  period: totp.period,
1023
1167
  timeLeft: totp.timeLeft,
1024
1168
  });
1169
+ const extraLines = [
1170
+ `period: ${stringifyScalar(totp.period)}`,
1171
+ `timeLeft: ${stringifyScalar(totp.timeLeft)}`,
1172
+ ];
1025
1173
  return {
1026
1174
  structuredContent,
1027
- content: toolTextContent(structuredContent, 'OK'),
1175
+ content: toolValueContent(structuredContent, 'totp', totp.value, totp.revealed, extraLines),
1028
1176
  };
1029
1177
  });
1030
1178
  registerTool(`${deps.toolPrefix}.get_password_history`, {
@@ -1092,7 +1240,7 @@ export function registerTools(server, deps) {
1092
1240
  });
1093
1241
  return {
1094
1242
  structuredContent: { item: created },
1095
- content: [{ type: 'text', text: 'Created.' }],
1243
+ content: entityTextContent({ item: created }, 'Created item:', created),
1096
1244
  };
1097
1245
  });
1098
1246
  registerTool(`${deps.toolPrefix}.create_logins`, {
@@ -1144,11 +1292,13 @@ export function registerTools(server, deps) {
1144
1292
  })),
1145
1293
  continueOnError: input.continueOnError,
1146
1294
  });
1295
+ const structuredContent = { results };
1147
1296
  return {
1148
- structuredContent: { results },
1149
- content: [
1150
- { type: 'text', text: `Created ${results.length} login(s).` },
1151
- ],
1297
+ structuredContent,
1298
+ content: structuredTextContent(structuredContent, [
1299
+ `Created ${results.length} login(s):`,
1300
+ ...results.map(formatBatchCreateResult),
1301
+ ].join('\n')),
1152
1302
  };
1153
1303
  });
1154
1304
  registerTool(`${deps.toolPrefix}.set_login_uris`, {
@@ -1177,7 +1327,7 @@ export function registerTools(server, deps) {
1177
1327
  });
1178
1328
  return {
1179
1329
  structuredContent: { item: updated },
1180
- content: [{ type: 'text', text: 'Updated.' }],
1330
+ content: entityTextContent({ item: updated }, 'Updated item:', updated),
1181
1331
  };
1182
1332
  });
1183
1333
  registerTool(`${deps.toolPrefix}.create_note`, {
@@ -1207,7 +1357,7 @@ export function registerTools(server, deps) {
1207
1357
  const created = await sdk.createNote(input);
1208
1358
  return {
1209
1359
  structuredContent: { item: created },
1210
- content: [{ type: 'text', text: 'Created.' }],
1360
+ content: entityTextContent({ item: created }, 'Created item:', created),
1211
1361
  };
1212
1362
  });
1213
1363
  registerTool(`${deps.toolPrefix}.create_ssh_key`, {
@@ -1234,7 +1384,7 @@ export function registerTools(server, deps) {
1234
1384
  const created = await sdk.createSshKey(input);
1235
1385
  return {
1236
1386
  structuredContent: { item: created },
1237
- content: [{ type: 'text', text: 'Created.' }],
1387
+ content: entityTextContent({ item: created }, 'Created item:', created),
1238
1388
  };
1239
1389
  });
1240
1390
  registerTool(`${deps.toolPrefix}.create_card`, {
@@ -1270,7 +1420,7 @@ export function registerTools(server, deps) {
1270
1420
  const created = await sdk.createCard(input);
1271
1421
  return {
1272
1422
  structuredContent: { item: created },
1273
- content: [{ type: 'text', text: 'Created.' }],
1423
+ content: entityTextContent({ item: created }, 'Created item:', created),
1274
1424
  };
1275
1425
  });
1276
1426
  registerTool(`${deps.toolPrefix}.create_identity`, {
@@ -1322,7 +1472,7 @@ export function registerTools(server, deps) {
1322
1472
  const created = await sdk.createIdentity(input);
1323
1473
  return {
1324
1474
  structuredContent: { item: created },
1325
- content: [{ type: 'text', text: 'Created.' }],
1475
+ content: entityTextContent({ item: created }, 'Created item:', created),
1326
1476
  };
1327
1477
  });
1328
1478
  registerTool(`${deps.toolPrefix}.update_item`, {
@@ -1372,7 +1522,7 @@ export function registerTools(server, deps) {
1372
1522
  const updated = await sdk.updateItem(input.id, patch);
1373
1523
  return {
1374
1524
  structuredContent: { item: updated },
1375
- content: [{ type: 'text', text: 'Updated.' }],
1525
+ content: entityTextContent({ item: updated }, 'Updated item:', updated),
1376
1526
  };
1377
1527
  });
1378
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.15",
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).",