@icoretech/warden-mcp 0.2.14 → 0.2.16

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,29 @@ 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
+
35
+ For scalar helper tools, the text output follows the reveal contract:
36
+
37
+ - `get_username` shows the username because Bitwarden treats it as non-secret
38
+ - `get_password`, `get_totp`, and `get_notes` show `not revealed` unless you pass
39
+ `reveal: true`
40
+ - if `NOREVEAL=true` or `KEYCHAIN_NOREVEAL=true`, revealed values are still
41
+ suppressed server-side
42
+
43
+ When a lookup term matches multiple login items, credential helpers return an
44
+ `AMBIGUOUS_LOOKUP` error with visible candidate ids. Retry with `term` set to an
45
+ exact candidate `id`, or call `get_item` with that `id`.
46
+
24
47
  ## LLM Automation Use Case
25
48
 
26
49
  `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 +455,7 @@ Mutation control:
432
455
 
433
456
  - Set `READONLY=true` to block all write operations (create/edit/delete/move/restore/attachments).
434
457
  - 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.
458
+ - 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
459
  - 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
460
  - Session guardrails:
438
461
  - `KEYCHAIN_SESSION_MAX_COUNT` (default `32`)
@@ -172,7 +172,9 @@ export class BwSessionManager {
172
172
  }
173
173
  const summaryParts = isUnlocked
174
174
  ? ['Vault access ready']
175
- : ['Vault access not ready'];
175
+ : [
176
+ 'Vault access not ready yet; this lazy status check does not unlock the vault, but keychain tools will attempt unlock/recovery on demand',
177
+ ];
176
178
  if (userEmail)
177
179
  summaryParts.push(`for ${userEmail}`);
178
180
  if (serverUrl)
@@ -183,6 +185,10 @@ export class BwSessionManager {
183
185
  operational: {
184
186
  ready: isUnlocked,
185
187
  sessionValid: isUnlocked,
188
+ recoverable: !isUnlocked,
189
+ nextAction: isUnlocked
190
+ ? 'continue'
191
+ : 'call a keychain tool such as search_items or get_username to initialize vault access on demand',
186
192
  source: 'session_manager',
187
193
  },
188
194
  };
@@ -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 = {
@@ -62,6 +63,98 @@ export function registerTools(server, deps) {
62
63
  : fallbackText;
63
64
  return [{ type: 'text', text }];
64
65
  }
66
+ function quoteText(value) {
67
+ return JSON.stringify(value);
68
+ }
69
+ function stringifyScalar(value) {
70
+ if (value === null || value === undefined)
71
+ return 'null';
72
+ if (typeof value === 'string')
73
+ return quoteText(value);
74
+ return JSON.stringify(value) ?? String(value);
75
+ }
76
+ function formatItemSummary(item) {
77
+ if (!item || typeof item !== 'object')
78
+ return `- ${stringifyScalar(item)}`;
79
+ const rec = item;
80
+ const parts = [];
81
+ if (typeof rec.id === 'string')
82
+ parts.push(`id=${rec.id}`);
83
+ if (typeof rec.name === 'string')
84
+ parts.push(`name=${quoteText(rec.name)}`);
85
+ if (typeof rec.type === 'string')
86
+ parts.push(`type=${rec.type}`);
87
+ if (typeof rec.username === 'string') {
88
+ parts.push(`username=${quoteText(rec.username)}`);
89
+ }
90
+ if (Array.isArray(rec.uris) && rec.uris.length > 0) {
91
+ const uris = rec.uris
92
+ .map((uri) => {
93
+ if (!uri || typeof uri !== 'object')
94
+ return null;
95
+ const value = uri.uri;
96
+ return typeof value === 'string' ? value : null;
97
+ })
98
+ .filter((uri) => uri !== null);
99
+ if (uris.length > 0)
100
+ parts.push(`uris=${quoteText(uris.join(', '))}`);
101
+ }
102
+ if (typeof rec.organizationId === 'string') {
103
+ parts.push(`organizationId=${rec.organizationId}`);
104
+ }
105
+ if (typeof rec.folderId === 'string')
106
+ parts.push(`folderId=${rec.folderId}`);
107
+ if (Array.isArray(rec.collectionIds) && rec.collectionIds.length > 0) {
108
+ parts.push(`collectionIds=${quoteText(rec.collectionIds.join(', '))}`);
109
+ }
110
+ if (typeof rec.favorite === 'boolean')
111
+ parts.push(`favorite=${rec.favorite}`);
112
+ return `- ${parts.length > 0 ? parts.join(' ') : stringifyScalar(rec)}`;
113
+ }
114
+ function formatResultsText(label, results) {
115
+ if (textCompatMode === 'structured_json') {
116
+ return JSON.stringify({ results });
117
+ }
118
+ if (results.length === 0)
119
+ return `Found 0 ${label}.`;
120
+ return [
121
+ `Found ${results.length} ${label}:`,
122
+ ...results.map(formatItemSummary),
123
+ ].join('\n');
124
+ }
125
+ function toolValueContent(structuredContent, kind, value, revealed, extraLines = []) {
126
+ if (textCompatMode === 'structured_json') {
127
+ return [
128
+ { type: 'text', text: JSON.stringify(structuredContent) },
129
+ ];
130
+ }
131
+ const lines = [
132
+ `${kind}: ${revealed ? stringifyScalar(value) : 'not revealed'}`,
133
+ ...extraLines,
134
+ ];
135
+ return [{ type: 'text', text: lines.join('\n') }];
136
+ }
137
+ function ambiguousLookupResult(error) {
138
+ const structuredContent = {
139
+ ok: false,
140
+ error: 'AMBIGUOUS_LOOKUP',
141
+ message: error.message,
142
+ candidates: error.candidates,
143
+ };
144
+ return {
145
+ 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
+ ],
155
+ isError: true,
156
+ };
157
+ }
65
158
  const uriMatchSchema = z.enum([
66
159
  'domain',
67
160
  'host',
@@ -108,7 +201,7 @@ export function registerTools(server, deps) {
108
201
  }
109
202
  registerTool(`${deps.toolPrefix}.status`, {
110
203
  title: 'Vault Status',
111
- description: 'Returns Bitwarden CLI status (locked/unlocked, server, user).',
204
+ 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.',
112
205
  annotations: { readOnlyHint: true },
113
206
  inputSchema: {},
114
207
  _meta: toolMeta,
@@ -255,7 +348,9 @@ export function registerTools(server, deps) {
255
348
  });
256
349
  return {
257
350
  structuredContent: { results },
258
- content: [{ type: 'text', text: `Found ${results.length} folder(s).` }],
351
+ content: [
352
+ { type: 'text', text: formatResultsText('folder(s)', results) },
353
+ ],
259
354
  };
260
355
  });
261
356
  registerTool(`${deps.toolPrefix}.create_folder`, {
@@ -339,7 +434,10 @@ export function registerTools(server, deps) {
339
434
  return {
340
435
  structuredContent: { results },
341
436
  content: [
342
- { type: 'text', text: `Found ${results.length} org collection(s).` },
437
+ {
438
+ type: 'text',
439
+ text: formatResultsText('org collection(s)', results),
440
+ },
343
441
  ],
344
442
  };
345
443
  });
@@ -441,7 +539,7 @@ export function registerTools(server, deps) {
441
539
  });
442
540
  return {
443
541
  structuredContent: { results },
444
- content: [{ type: 'text', text: `Found ${results.length} org(s).` }],
542
+ content: [{ type: 'text', text: formatResultsText('org(s)', results) }],
445
543
  };
446
544
  });
447
545
  registerTool(`${deps.toolPrefix}.list_collections`, {
@@ -470,7 +568,7 @@ export function registerTools(server, deps) {
470
568
  return {
471
569
  structuredContent: { results },
472
570
  content: [
473
- { type: 'text', text: `Found ${results.length} collection(s).` },
571
+ { type: 'text', text: formatResultsText('collection(s)', results) },
474
572
  ],
475
573
  };
476
574
  });
@@ -501,7 +599,9 @@ export function registerTools(server, deps) {
501
599
  const minimal = items.map((i) => sdk.minimalSummary(i));
502
600
  return {
503
601
  structuredContent: { results: minimal },
504
- content: [{ type: 'text', text: `Found ${minimal.length} item(s).` }],
602
+ content: [
603
+ { type: 'text', text: formatResultsText('item(s)', minimal) },
604
+ ],
505
605
  };
506
606
  });
507
607
  registerTool(`${deps.toolPrefix}.get_item`, {
@@ -556,7 +656,7 @@ export function registerTools(server, deps) {
556
656
  const structuredContent = toolResult('notes', notes.value, notes.revealed);
557
657
  return {
558
658
  structuredContent,
559
- content: toolTextContent(structuredContent, 'OK'),
659
+ content: toolValueContent(structuredContent, 'notes', notes.value, notes.revealed),
560
660
  };
561
661
  });
562
662
  registerTool(`${deps.toolPrefix}.get_exposed`, {
@@ -981,11 +1081,20 @@ export function registerTools(server, deps) {
981
1081
  _meta: toolMeta,
982
1082
  }, async (input, extra) => {
983
1083
  const sdk = await deps.getSdk(extra.authInfo);
984
- const username = await sdk.getUsername(input);
1084
+ let username;
1085
+ try {
1086
+ username = await sdk.getUsername(input);
1087
+ }
1088
+ catch (error) {
1089
+ if (error instanceof AmbiguousLoginLookupError) {
1090
+ return ambiguousLookupResult(error);
1091
+ }
1092
+ throw error;
1093
+ }
985
1094
  const structuredContent = toolResult('username', username.value, username.revealed);
986
1095
  return {
987
1096
  structuredContent,
988
- content: toolTextContent(structuredContent, 'OK'),
1097
+ content: toolValueContent(structuredContent, 'username', username.value, username.revealed),
989
1098
  };
990
1099
  });
991
1100
  registerTool(`${deps.toolPrefix}.get_password`, {
@@ -999,11 +1108,20 @@ export function registerTools(server, deps) {
999
1108
  _meta: toolMeta,
1000
1109
  }, async (input, extra) => {
1001
1110
  const sdk = await deps.getSdk(extra.authInfo);
1002
- const password = await sdk.getPassword({ term: input.term }, { reveal: effectiveReveal(input) });
1111
+ let password;
1112
+ try {
1113
+ password = await sdk.getPassword({ term: input.term }, { reveal: effectiveReveal(input) });
1114
+ }
1115
+ catch (error) {
1116
+ if (error instanceof AmbiguousLoginLookupError) {
1117
+ return ambiguousLookupResult(error);
1118
+ }
1119
+ throw error;
1120
+ }
1003
1121
  const structuredContent = toolResult('password', password.value, password.revealed);
1004
1122
  return {
1005
1123
  structuredContent,
1006
- content: toolTextContent(structuredContent, 'OK'),
1124
+ content: toolValueContent(structuredContent, 'password', password.value, password.revealed),
1007
1125
  };
1008
1126
  });
1009
1127
  registerTool(`${deps.toolPrefix}.get_totp`, {
@@ -1022,9 +1140,13 @@ export function registerTools(server, deps) {
1022
1140
  period: totp.period,
1023
1141
  timeLeft: totp.timeLeft,
1024
1142
  });
1143
+ const extraLines = [
1144
+ `period: ${stringifyScalar(totp.period)}`,
1145
+ `timeLeft: ${stringifyScalar(totp.timeLeft)}`,
1146
+ ];
1025
1147
  return {
1026
1148
  structuredContent,
1027
- content: toolTextContent(structuredContent, 'OK'),
1149
+ content: toolValueContent(structuredContent, 'totp', totp.value, totp.revealed, extraLines),
1028
1150
  };
1029
1151
  });
1030
1152
  registerTool(`${deps.toolPrefix}.get_password_history`, {
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "private": false,
3
3
  "name": "@icoretech/warden-mcp",
4
- "version": "0.2.14",
4
+ "version": "0.2.16",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "description": "Vaultwarden/Bitwarden MCP server backed by Bitwarden CLI (bw).",