@icoretech/warden-mcp 0.2.24 → 0.2.26
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 +4 -67
- package/dist/bw/bwCli.js +11 -2
- package/dist/sdk/keychainSdk.js +12 -25
- package/dist/tools/registerTools.js +9 -6
- package/package.json +6 -2
package/README.md
CHANGED
|
@@ -203,14 +203,6 @@ codex mcp add warden \
|
|
|
203
203
|
|
|
204
204
|
# Claude Code
|
|
205
205
|
claude mcp add-json warden '{"command":"npx","args":["-y","@icoretech/warden-mcp@latest","--stdio"],"env":{"BW_HOST":"https://vaultwarden.example.com","BW_CLIENTID":"user.xxxxx","BW_CLIENTSECRET":"xxxxx","BW_PASSWORD":"your-master-password"}}'
|
|
206
|
-
|
|
207
|
-
# Qwen Code
|
|
208
|
-
qwen mcp add warden \
|
|
209
|
-
-e BW_HOST=https://vaultwarden.example.com \
|
|
210
|
-
-e BW_CLIENTID=user.xxxxx \
|
|
211
|
-
-e BW_CLIENTSECRET=xxxxx \
|
|
212
|
-
-e BW_PASSWORD=your-master-password \
|
|
213
|
-
npx -y @icoretech/warden-mcp@latest --stdio
|
|
214
206
|
```
|
|
215
207
|
|
|
216
208
|
### JSON config hosts
|
|
@@ -220,7 +212,6 @@ These hosts all use the same stdio payload shape. Only the config file location
|
|
|
220
212
|
- Codex: `~/.codex/config.toml`
|
|
221
213
|
- Cursor: `~/.cursor/mcp.json` or `.cursor/mcp.json`
|
|
222
214
|
- Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
223
|
-
- Qwen Code: `~/.qwen/settings.json` or `.qwen/settings.json`
|
|
224
215
|
|
|
225
216
|
Shared JSON shape:
|
|
226
217
|
|
|
@@ -260,27 +251,6 @@ BW_PASSWORD = "your-master-password"
|
|
|
260
251
|
because a cold first launch can spend several seconds downloading and unpacking
|
|
261
252
|
the package before MCP initialization begins.
|
|
262
253
|
|
|
263
|
-
### Windsurf
|
|
264
|
-
|
|
265
|
-
Windsurf uses the same stdio idea but stores it in `~/.codeium/windsurf/mcp_config.json`:
|
|
266
|
-
|
|
267
|
-
```json
|
|
268
|
-
{
|
|
269
|
-
"mcpServers": {
|
|
270
|
-
"warden": {
|
|
271
|
-
"command": "npx",
|
|
272
|
-
"args": ["-y", "@icoretech/warden-mcp@latest", "--stdio"],
|
|
273
|
-
"env": {
|
|
274
|
-
"BW_HOST": "https://vaultwarden.example.com",
|
|
275
|
-
"BW_CLIENTID": "user.xxxxx",
|
|
276
|
-
"BW_CLIENTSECRET": "xxxxx",
|
|
277
|
-
"BW_PASSWORD": "your-master-password"
|
|
278
|
-
}
|
|
279
|
-
}
|
|
280
|
-
}
|
|
281
|
-
}
|
|
282
|
-
```
|
|
283
|
-
|
|
284
254
|
### Shared HTTP connections
|
|
285
255
|
|
|
286
256
|
If your MCP host supports Streamable HTTP with custom headers, you can connect to one long-lived `warden-mcp` service instead of spawning a local stdio process.
|
|
@@ -388,40 +358,6 @@ claude mcp add-json warden '{"type":"http","url":"http://localhost:3005/sse?v=2"
|
|
|
388
358
|
}
|
|
389
359
|
```
|
|
390
360
|
|
|
391
|
-
```json
|
|
392
|
-
// Qwen Code (~/.qwen/settings.json)
|
|
393
|
-
{
|
|
394
|
-
"mcpServers": {
|
|
395
|
-
"warden": {
|
|
396
|
-
"httpUrl": "http://localhost:3005/sse?v=2",
|
|
397
|
-
"headers": {
|
|
398
|
-
"X-BW-Host": "https://vaultwarden.example.com",
|
|
399
|
-
"X-BW-ClientId": "user.xxxxx",
|
|
400
|
-
"X-BW-ClientSecret": "xxxxx",
|
|
401
|
-
"X-BW-Password": "your-master-password"
|
|
402
|
-
}
|
|
403
|
-
}
|
|
404
|
-
}
|
|
405
|
-
}
|
|
406
|
-
```
|
|
407
|
-
|
|
408
|
-
```json
|
|
409
|
-
// Windsurf (~/.codeium/windsurf/mcp_config.json)
|
|
410
|
-
{
|
|
411
|
-
"mcpServers": {
|
|
412
|
-
"warden": {
|
|
413
|
-
"serverUrl": "http://localhost:3005/sse?v=2",
|
|
414
|
-
"headers": {
|
|
415
|
-
"X-BW-Host": "https://vaultwarden.example.com",
|
|
416
|
-
"X-BW-ClientId": "user.xxxxx",
|
|
417
|
-
"X-BW-ClientSecret": "xxxxx",
|
|
418
|
-
"X-BW-Password": "your-master-password"
|
|
419
|
-
}
|
|
420
|
-
}
|
|
421
|
-
}
|
|
422
|
-
}
|
|
423
|
-
```
|
|
424
|
-
|
|
425
361
|
Codex currently fits better with stdio here, because its MCP config supports a bearer token env var for remote servers but not arbitrary custom `X-BW-*` header injection.
|
|
426
362
|
|
|
427
363
|
### Verify bw is available
|
|
@@ -580,7 +516,8 @@ npm run dev
|
|
|
580
516
|
- Start with `keychain_search_items` when you know a name, URI, username, folder, collection, or item type but not the exact item id. Then call `keychain_get_item` with the returned id for the full item shape.
|
|
581
517
|
- Personal folder tools manage one user's vault folders, for example `Example Folder`. Organization collection tools manage shared organization-scoped collections, for example `Example Collection`. `organizationId` is required for `keychain_list_org_collections`, `keychain_create_org_collection`, `keychain_edit_org_collection`, and `keychain_delete_org_collection`, and optional only for `keychain_get_org_collection` when you want to narrow a direct id lookup.
|
|
582
518
|
- `keychain_move_item_to_organization` moves an item out of the personal vault and into an organization, optionally assigning collection ids at the same time.
|
|
583
|
-
- `keychain_send_create` is the quick path for text or file Sends through the normal `bw send` flags. `keychain_send_template`, `keychain_send_create_encoded`, and `keychain_send_edit` are for the full Bitwarden Send JSON template or an encoded edit payload.
|
|
519
|
+
- `keychain_send_create` is the quick path for text or file Sends through the normal `bw send` flags, including `emails` for email-gated access. `emails` is mutually exclusive with `password` and does not share the generated Send URL for you. `keychain_send_template`, `keychain_send_create_encoded`, and `keychain_send_edit` are for the full Bitwarden Send JSON template or an encoded edit payload.
|
|
520
|
+
- `keychain_send_get` returns owned Send metadata, including `accessUrl`, or text content with `text=true`. To download a file Send, pass that `accessUrl` to `keychain_receive` with `downloadFile=true`; the bundled `bw send get` command does not implement file download output.
|
|
584
521
|
- Pass `reveal: true` only to tools that can return secrets, such as password, TOTP, notes, generated secrets, password history, or full item reads. By default these stay redacted. Text-only MCP clients follow the same reveal contract described in [Text-Only MCP Client Behavior](#text-only-mcp-client-behavior), and server-side `NOREVEAL` settings still win.
|
|
585
522
|
|
|
586
523
|
Vault/session:
|
|
@@ -616,10 +553,10 @@ Attachments:
|
|
|
616
553
|
Sends:
|
|
617
554
|
|
|
618
555
|
- `keychain_send_list`, `keychain_send_template`, `keychain_send_get`
|
|
619
|
-
- `keychain_send_create` (quick create via `bw send`)
|
|
556
|
+
- `keychain_send_create` (quick create via `bw send`, including optional `emails`)
|
|
620
557
|
- `keychain_send_create_encoded`, `keychain_send_edit` (advanced create/edit via `bw send create|edit`)
|
|
621
558
|
- `keychain_send_remove_password`, `keychain_send_delete`
|
|
622
|
-
- `keychain_receive`
|
|
559
|
+
- `keychain_receive` (receive shared Sends and download file Send bytes)
|
|
623
560
|
|
|
624
561
|
Direct “bw get …” helpers:
|
|
625
562
|
|
package/dist/bw/bwCli.js
CHANGED
|
@@ -1,6 +1,15 @@
|
|
|
1
1
|
// src/bw/bwCli.ts
|
|
2
2
|
import { spawn } from 'node:child_process';
|
|
3
3
|
import { resolveBundledBwBin } from './resolveBwBin.js';
|
|
4
|
+
const SENSITIVE_ARG_FLAGS = new Set([
|
|
5
|
+
'--apikey',
|
|
6
|
+
'--clientsecret',
|
|
7
|
+
'--emails',
|
|
8
|
+
'--password',
|
|
9
|
+
'--passwordenv',
|
|
10
|
+
'--passwordfile',
|
|
11
|
+
'--session',
|
|
12
|
+
]);
|
|
4
13
|
export class BwCliError extends Error {
|
|
5
14
|
exitCode;
|
|
6
15
|
stdout;
|
|
@@ -67,8 +76,8 @@ export async function runBw(args, opts = {}) {
|
|
|
67
76
|
const out = [];
|
|
68
77
|
for (let i = 0; i < argv.length; i++) {
|
|
69
78
|
const a = argv[i];
|
|
70
|
-
if (a === '
|
|
71
|
-
out.push(
|
|
79
|
+
if (typeof a === 'string' && SENSITIVE_ARG_FLAGS.has(a)) {
|
|
80
|
+
out.push(a);
|
|
72
81
|
if (i + 1 < argv.length) {
|
|
73
82
|
out.push('<redacted>');
|
|
74
83
|
i++;
|
package/dist/sdk/keychainSdk.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
// src/sdk/keychainSdk.ts
|
|
2
|
-
import { mkdtemp,
|
|
2
|
+
import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
|
|
3
3
|
import { tmpdir } from 'node:os';
|
|
4
4
|
import { basename, join } from 'node:path';
|
|
5
5
|
import { BwCliError, isBwAuthSessionInvalidError } from '../bw/bwCli.js';
|
|
@@ -387,19 +387,6 @@ export class KeychainSdk {
|
|
|
387
387
|
return trimmed;
|
|
388
388
|
}
|
|
389
389
|
}
|
|
390
|
-
async readSingleFileAsBase64(dir) {
|
|
391
|
-
const files = await readdir(dir);
|
|
392
|
-
if (files.length !== 1) {
|
|
393
|
-
throw new Error(`Expected exactly 1 downloaded file, found ${files.length}`);
|
|
394
|
-
}
|
|
395
|
-
const filename = files[0] ?? '';
|
|
396
|
-
const buf = await readFile(join(dir, filename));
|
|
397
|
-
return {
|
|
398
|
-
filename,
|
|
399
|
-
bytes: buf.byteLength,
|
|
400
|
-
contentBase64: buf.toString('base64'),
|
|
401
|
-
};
|
|
402
|
-
}
|
|
403
390
|
attachmentsFromItem(item) {
|
|
404
391
|
if (!item || typeof item !== 'object')
|
|
405
392
|
return [];
|
|
@@ -552,22 +539,14 @@ export class KeychainSdk {
|
|
|
552
539
|
});
|
|
553
540
|
}
|
|
554
541
|
async sendGet(input) {
|
|
542
|
+
if (input.downloadFile) {
|
|
543
|
+
throw new Error('keychain_send_get cannot download file Sends because bw send get --output is not implemented by the bundled Bitwarden CLI; use keychain_receive with the Send accessUrl and downloadFile=true instead');
|
|
544
|
+
}
|
|
555
545
|
return this.bw.withSession(async (session) => {
|
|
556
546
|
if (input.text) {
|
|
557
547
|
const { stdout } = await this.bw.runForSession(session, ['--raw', 'send', 'get', input.id, '--text'], { timeoutMs: 60_000 });
|
|
558
548
|
return { text: stdout.trim() };
|
|
559
549
|
}
|
|
560
|
-
if (input.downloadFile) {
|
|
561
|
-
const dir = await mkdtemp(join(tmpdir(), 'keychain-sendfile-'));
|
|
562
|
-
try {
|
|
563
|
-
await this.bw.runForSession(session, ['send', 'get', input.id, '--output', dir], { timeoutMs: 120_000 });
|
|
564
|
-
const file = await this.readSingleFileAsBase64(dir);
|
|
565
|
-
return { file };
|
|
566
|
-
}
|
|
567
|
-
finally {
|
|
568
|
-
await rm(dir, { recursive: true, force: true });
|
|
569
|
-
}
|
|
570
|
-
}
|
|
571
550
|
const { stdout } = await this.bw.runForSession(session, ['send', 'get', input.id], {
|
|
572
551
|
timeoutMs: 60_000,
|
|
573
552
|
});
|
|
@@ -591,12 +570,20 @@ export class KeychainSdk {
|
|
|
591
570
|
async sendCreate(input) {
|
|
592
571
|
return this.bw.withSession(async (session) => {
|
|
593
572
|
const args = ['send'];
|
|
573
|
+
const emails = input.emails
|
|
574
|
+
?.map((email) => email.trim())
|
|
575
|
+
.filter((email) => email.length > 0);
|
|
576
|
+
if (emails && emails.length > 0 && typeof input.password === 'string') {
|
|
577
|
+
throw new Error('Send emails and password are mutually exclusive');
|
|
578
|
+
}
|
|
594
579
|
if (input.type === 'file')
|
|
595
580
|
args.push('--file');
|
|
596
581
|
if (typeof input.deleteInDays === 'number')
|
|
597
582
|
args.push('--deleteInDays', String(input.deleteInDays));
|
|
598
583
|
if (typeof input.password === 'string')
|
|
599
584
|
args.push('--password', input.password);
|
|
585
|
+
if (emails && emails.length > 0)
|
|
586
|
+
args.push('--emails', emails.join(','));
|
|
600
587
|
if (typeof input.maxAccessCount === 'number')
|
|
601
588
|
args.push('--maxAccessCount', String(input.maxAccessCount));
|
|
602
589
|
if (input.hidden)
|
|
@@ -354,6 +354,12 @@ export function registerTools(server, deps) {
|
|
|
354
354
|
.string()
|
|
355
355
|
.optional()
|
|
356
356
|
.describe('Visible filename required with contentBase64 for file sends.');
|
|
357
|
+
const sendEmailsSchema = z
|
|
358
|
+
.array(z.string().trim().email())
|
|
359
|
+
.min(1)
|
|
360
|
+
.max(50)
|
|
361
|
+
.optional()
|
|
362
|
+
.describe('Recipient email addresses for Bitwarden Send email-gated access. Mutually exclusive with password; callers still need to share the Send URL.');
|
|
357
363
|
const itemFieldSchema = z
|
|
358
364
|
.object({
|
|
359
365
|
name: z.string().describe('Custom field name stored on the item.'),
|
|
@@ -1312,7 +1318,7 @@ export function registerTools(server, deps) {
|
|
|
1312
1318
|
});
|
|
1313
1319
|
registerTool(`${deps.toolPrefix}.send_get`, {
|
|
1314
1320
|
title: 'Send Get',
|
|
1315
|
-
description: 'Get Sends owned by you. Use text=true to return text content;
|
|
1321
|
+
description: 'Get Sends owned by you. Use text=true to return text content; file Sends return metadata including accessUrl. To download file Send bytes, call receive with that accessUrl and downloadFile=true.',
|
|
1316
1322
|
annotations: { readOnlyHint: true, openWorldHint: true },
|
|
1317
1323
|
inputSchema: {
|
|
1318
1324
|
id: stableObjectIdSchema,
|
|
@@ -1320,10 +1326,6 @@ export function registerTools(server, deps) {
|
|
|
1320
1326
|
.boolean()
|
|
1321
1327
|
.optional()
|
|
1322
1328
|
.describe('Return the Send text content instead of JSON metadata.'),
|
|
1323
|
-
downloadFile: z
|
|
1324
|
-
.boolean()
|
|
1325
|
-
.optional()
|
|
1326
|
-
.describe('Download a file Send and return its file bytes.'),
|
|
1327
1329
|
},
|
|
1328
1330
|
_meta: toolMeta,
|
|
1329
1331
|
}, async (input, extra) => {
|
|
@@ -1337,7 +1339,7 @@ export function registerTools(server, deps) {
|
|
|
1337
1339
|
});
|
|
1338
1340
|
registerTool(`${deps.toolPrefix}.send_create`, {
|
|
1339
1341
|
title: 'Send Create',
|
|
1340
|
-
description: 'Quick-create a Bitwarden Send through bw send. Use type=text with text, or type=file with filename plus contentBase64; deleteInDays controls expiration deletion, maxAccessCount limits accesses,
|
|
1342
|
+
description: 'Quick-create a Bitwarden Send through bw send. Use type=text with text, or type=file with filename plus contentBase64; deleteInDays controls expiration deletion, maxAccessCount limits accesses, password protects the Send, and emails grant email-gated access. For advanced JSON templates or edits, use send_create_encoded and send_edit instead.',
|
|
1341
1343
|
annotations: {
|
|
1342
1344
|
readOnlyHint: false,
|
|
1343
1345
|
destructiveHint: false,
|
|
@@ -1364,6 +1366,7 @@ export function registerTools(server, deps) {
|
|
|
1364
1366
|
.string()
|
|
1365
1367
|
.optional()
|
|
1366
1368
|
.describe('Optional Send access password required by recipients.'),
|
|
1369
|
+
emails: sendEmailsSchema,
|
|
1367
1370
|
maxAccessCount: z
|
|
1368
1371
|
.number()
|
|
1369
1372
|
.int()
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"private": false,
|
|
3
3
|
"name": "@icoretech/warden-mcp",
|
|
4
|
-
"version": "0.2.
|
|
4
|
+
"version": "0.2.26",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"description": "Vaultwarden/Bitwarden MCP server backed by Bitwarden CLI (bw).",
|
|
@@ -51,11 +51,15 @@
|
|
|
51
51
|
"optionalDependencies": {
|
|
52
52
|
"@bitwarden/cli": "2026.5.0"
|
|
53
53
|
},
|
|
54
|
+
"overrides": {
|
|
55
|
+
"form-data": "4.0.6",
|
|
56
|
+
"tmp": "0.2.7"
|
|
57
|
+
},
|
|
54
58
|
"devDependencies": {
|
|
55
59
|
"@biomejs/biome": "^2.5.0",
|
|
56
60
|
"@types/express": "^5.0.6",
|
|
57
61
|
"@types/node": "^25.9.3",
|
|
58
|
-
"playwright": "1.
|
|
62
|
+
"playwright": "1.61.0",
|
|
59
63
|
"tsx": "^4.22.4",
|
|
60
64
|
"typescript": "^6.0.3"
|
|
61
65
|
},
|