@icoretech/warden-mcp 0.2.2 → 0.2.4
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 +45 -0
- package/dist/sdk/keychainSdk.js +17 -0
- package/dist/tools/registerTools.js +63 -0
- package/dist/transports/http.js +2 -1
- package/dist/transports/stdio.js +2 -1
- package/dist/version.js +2 -0
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -280,6 +280,49 @@ This shared-server mode is useful when:
|
|
|
280
280
|
- you are integrating from a custom client or agent host that can attach HTTP headers
|
|
281
281
|
- you want one always-on service instead of each editor spawning its own `bw`-backed subprocess
|
|
282
282
|
|
|
283
|
+
#### Headerless SSE clients (`claude.ai` web, similar hosts)
|
|
284
|
+
|
|
285
|
+
Some web MCP hosts can connect to a Streamable HTTP / SSE endpoint but cannot
|
|
286
|
+
attach custom `X-BW-*` headers. In that case, run `warden-mcp` as a
|
|
287
|
+
single-tenant shared server with fixed server-side credentials and explicit env
|
|
288
|
+
fallback enabled:
|
|
289
|
+
|
|
290
|
+
```bash
|
|
291
|
+
BW_HOST=https://vaultwarden.example.com \
|
|
292
|
+
BW_CLIENTID=user.xxxxx \
|
|
293
|
+
BW_CLIENTSECRET=xxxxx \
|
|
294
|
+
BW_PASSWORD='your-master-password' \
|
|
295
|
+
KEYCHAIN_ALLOW_ENV_FALLBACK=true \
|
|
296
|
+
npx -y @icoretech/warden-mcp@latest
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
Some hosted or browser-based MCP clients expect the server URL to be available
|
|
300
|
+
over **HTTPS** rather than plain `http://localhost:3005/...`.
|
|
301
|
+
|
|
302
|
+
If you are running `warden-mcp` locally, that usually means putting one of
|
|
303
|
+
these in front of it:
|
|
304
|
+
|
|
305
|
+
- a local HTTPS reverse proxy in front of `warden-mcp`
|
|
306
|
+
- a temporary tunnel such as Cloudflare Tunnel, ngrok, or Tailscale Funnel
|
|
307
|
+
|
|
308
|
+
Then point the client at the HTTPS endpoint, for example:
|
|
309
|
+
|
|
310
|
+
```text
|
|
311
|
+
https://warden-mcp.example.com/sse?v=2
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
This works because headerless HTTP requests can inherit the server's own
|
|
315
|
+
`BW_*` configuration when `KEYCHAIN_ALLOW_ENV_FALLBACK=true`. You can use
|
|
316
|
+
`BW_USER` + `BW_PASSWORD` here as well; the example above shows the API-key
|
|
317
|
+
variant because it is the default convention used elsewhere in this README.
|
|
318
|
+
|
|
319
|
+
Important limits:
|
|
320
|
+
|
|
321
|
+
- this is single-tenant only: every headerless client gets the same vault identity
|
|
322
|
+
- per-request profile switching does not work in this mode
|
|
323
|
+
- if a client can send `X-BW-*` headers, those headers still take priority over the server env
|
|
324
|
+
- anyone who can reach that endpoint inherits that vault access, so keep it behind trusted network access, VPN, tunnel access policies, IP allowlists, or another private boundary
|
|
325
|
+
|
|
283
326
|
Client examples for shared HTTP mode:
|
|
284
327
|
|
|
285
328
|
```bash
|
|
@@ -484,6 +527,8 @@ npm run dev
|
|
|
484
527
|
Vault/session:
|
|
485
528
|
|
|
486
529
|
- `keychain_status`
|
|
530
|
+
- `keychain_sync` (pull latest vault data from server via `bw sync`)
|
|
531
|
+
- `keychain_sdk_version` (returns the Bitwarden SDK version used by the CLI)
|
|
487
532
|
- `keychain_encode` (base64-encode a string via `bw encode`)
|
|
488
533
|
- `keychain_generate` (returns a generated secret only when `reveal: true`)
|
|
489
534
|
|
package/dist/sdk/keychainSdk.js
CHANGED
|
@@ -300,6 +300,23 @@ export class KeychainSdk {
|
|
|
300
300
|
async status() {
|
|
301
301
|
return this.bw.status();
|
|
302
302
|
}
|
|
303
|
+
async sync() {
|
|
304
|
+
await this.bw.withSession(async (session) => {
|
|
305
|
+
await this.bw.runForSession(session, ['sync'], { timeoutMs: 120_000 });
|
|
306
|
+
});
|
|
307
|
+
// After sync, fetch status to get the lastSync timestamp.
|
|
308
|
+
const status = (await this.bw.status());
|
|
309
|
+
const lastSync = typeof status.lastSync === 'string' ? status.lastSync : null;
|
|
310
|
+
return { success: true, lastSync };
|
|
311
|
+
}
|
|
312
|
+
async sdkVersion() {
|
|
313
|
+
const { stdout } = await this.bw.withSession(async (session) => {
|
|
314
|
+
return this.bw.runForSession(session, ['--version'], {
|
|
315
|
+
timeoutMs: 30_000,
|
|
316
|
+
});
|
|
317
|
+
});
|
|
318
|
+
return { version: stdout.trim() };
|
|
319
|
+
}
|
|
303
320
|
async encode(input) {
|
|
304
321
|
// `bw encode` base64-encodes stdin.
|
|
305
322
|
const { stdout } = await this.bw.withSession(async (session) => {
|
|
@@ -2,6 +2,14 @@
|
|
|
2
2
|
import { z } from 'zod';
|
|
3
3
|
export function registerTools(server, deps) {
|
|
4
4
|
const toolMeta = {};
|
|
5
|
+
const mutatingToolAnnotations = {
|
|
6
|
+
readOnlyHint: false,
|
|
7
|
+
destructiveHint: false,
|
|
8
|
+
};
|
|
9
|
+
const destructiveToolAnnotations = {
|
|
10
|
+
readOnlyHint: false,
|
|
11
|
+
destructiveHint: true,
|
|
12
|
+
};
|
|
5
13
|
const rawRegisterTool = server.registerTool.bind(server);
|
|
6
14
|
const legacyPrefix = `${deps.toolPrefix}.`;
|
|
7
15
|
const publicPrefix = `${deps.toolPrefix}${deps.toolSeparator}`;
|
|
@@ -110,6 +118,41 @@ export function registerTools(server, deps) {
|
|
|
110
118
|
content: [{ type: 'text', text: summary }],
|
|
111
119
|
};
|
|
112
120
|
});
|
|
121
|
+
registerTool(`${deps.toolPrefix}.sync`, {
|
|
122
|
+
title: 'Sync Vault',
|
|
123
|
+
description: 'Pull the latest vault data from the server (bw sync). Returns the last sync timestamp.',
|
|
124
|
+
annotations: { readOnlyHint: true },
|
|
125
|
+
inputSchema: {},
|
|
126
|
+
_meta: toolMeta,
|
|
127
|
+
}, async (_input, extra) => {
|
|
128
|
+
const sdk = await deps.getSdk(extra.authInfo);
|
|
129
|
+
const result = await sdk.sync();
|
|
130
|
+
return {
|
|
131
|
+
structuredContent: result,
|
|
132
|
+
content: [
|
|
133
|
+
{
|
|
134
|
+
type: 'text',
|
|
135
|
+
text: result.lastSync
|
|
136
|
+
? `Synced. Last sync: ${result.lastSync}`
|
|
137
|
+
: 'Synced.',
|
|
138
|
+
},
|
|
139
|
+
],
|
|
140
|
+
};
|
|
141
|
+
});
|
|
142
|
+
registerTool(`${deps.toolPrefix}.sdk_version`, {
|
|
143
|
+
title: 'SDK Version',
|
|
144
|
+
description: 'Returns the Bitwarden SDK version used by the CLI.',
|
|
145
|
+
annotations: { readOnlyHint: true },
|
|
146
|
+
inputSchema: {},
|
|
147
|
+
_meta: toolMeta,
|
|
148
|
+
}, async (_input, extra) => {
|
|
149
|
+
const sdk = await deps.getSdk(extra.authInfo);
|
|
150
|
+
const result = await sdk.sdkVersion();
|
|
151
|
+
return {
|
|
152
|
+
structuredContent: result,
|
|
153
|
+
content: [{ type: 'text', text: result.version }],
|
|
154
|
+
};
|
|
155
|
+
});
|
|
113
156
|
registerTool(`${deps.toolPrefix}.encode`, {
|
|
114
157
|
title: 'Encode',
|
|
115
158
|
description: 'Base64-encode a string (bw encode).',
|
|
@@ -209,6 +252,7 @@ export function registerTools(server, deps) {
|
|
|
209
252
|
registerTool(`${deps.toolPrefix}.create_folder`, {
|
|
210
253
|
title: 'Create Folder',
|
|
211
254
|
description: 'Create a Bitwarden folder (personal).',
|
|
255
|
+
annotations: mutatingToolAnnotations,
|
|
212
256
|
inputSchema: {
|
|
213
257
|
name: z.string(),
|
|
214
258
|
},
|
|
@@ -226,6 +270,7 @@ export function registerTools(server, deps) {
|
|
|
226
270
|
registerTool(`${deps.toolPrefix}.edit_folder`, {
|
|
227
271
|
title: 'Edit Folder',
|
|
228
272
|
description: 'Rename a Bitwarden folder (personal).',
|
|
273
|
+
annotations: mutatingToolAnnotations,
|
|
229
274
|
inputSchema: {
|
|
230
275
|
id: z.string(),
|
|
231
276
|
name: z.string(),
|
|
@@ -244,6 +289,7 @@ export function registerTools(server, deps) {
|
|
|
244
289
|
registerTool(`${deps.toolPrefix}.delete_folder`, {
|
|
245
290
|
title: 'Delete Folder',
|
|
246
291
|
description: 'Delete a Bitwarden folder (personal).',
|
|
292
|
+
annotations: destructiveToolAnnotations,
|
|
247
293
|
inputSchema: {
|
|
248
294
|
id: z.string(),
|
|
249
295
|
},
|
|
@@ -291,6 +337,7 @@ export function registerTools(server, deps) {
|
|
|
291
337
|
registerTool(`${deps.toolPrefix}.create_org_collection`, {
|
|
292
338
|
title: 'Create Org Collection',
|
|
293
339
|
description: 'Create an organization collection.',
|
|
340
|
+
annotations: mutatingToolAnnotations,
|
|
294
341
|
inputSchema: {
|
|
295
342
|
organizationId: z.string(),
|
|
296
343
|
name: z.string(),
|
|
@@ -309,6 +356,7 @@ export function registerTools(server, deps) {
|
|
|
309
356
|
registerTool(`${deps.toolPrefix}.edit_org_collection`, {
|
|
310
357
|
title: 'Edit Org Collection',
|
|
311
358
|
description: 'Rename an organization collection.',
|
|
359
|
+
annotations: mutatingToolAnnotations,
|
|
312
360
|
inputSchema: {
|
|
313
361
|
organizationId: z.string(),
|
|
314
362
|
id: z.string(),
|
|
@@ -328,6 +376,7 @@ export function registerTools(server, deps) {
|
|
|
328
376
|
registerTool(`${deps.toolPrefix}.delete_org_collection`, {
|
|
329
377
|
title: 'Delete Org Collection',
|
|
330
378
|
description: 'Delete an organization collection.',
|
|
379
|
+
annotations: destructiveToolAnnotations,
|
|
331
380
|
inputSchema: {
|
|
332
381
|
organizationId: z.string(),
|
|
333
382
|
id: z.string(),
|
|
@@ -346,6 +395,7 @@ export function registerTools(server, deps) {
|
|
|
346
395
|
registerTool(`${deps.toolPrefix}.move_item_to_organization`, {
|
|
347
396
|
title: 'Move Item To Organization',
|
|
348
397
|
description: 'Move an item to an organization (optionally assigning collection ids).',
|
|
398
|
+
annotations: mutatingToolAnnotations,
|
|
349
399
|
inputSchema: {
|
|
350
400
|
id: z.string(),
|
|
351
401
|
organizationId: z.string(),
|
|
@@ -582,6 +632,7 @@ export function registerTools(server, deps) {
|
|
|
582
632
|
registerTool(`${deps.toolPrefix}.delete_item`, {
|
|
583
633
|
title: 'Delete Item',
|
|
584
634
|
description: 'Delete an item by id (soft-delete by default; set permanent=true to hard delete).',
|
|
635
|
+
annotations: destructiveToolAnnotations,
|
|
585
636
|
inputSchema: {
|
|
586
637
|
id: z.string(),
|
|
587
638
|
permanent: z.boolean().optional(),
|
|
@@ -600,6 +651,7 @@ export function registerTools(server, deps) {
|
|
|
600
651
|
registerTool(`${deps.toolPrefix}.delete_items`, {
|
|
601
652
|
title: 'Delete Items',
|
|
602
653
|
description: 'Delete multiple items by id. Returns per-id results (soft-delete by default; set permanent=true to hard delete).',
|
|
654
|
+
annotations: destructiveToolAnnotations,
|
|
603
655
|
inputSchema: {
|
|
604
656
|
ids: z.array(z.string()).min(1).max(200),
|
|
605
657
|
permanent: z.boolean().optional(),
|
|
@@ -621,6 +673,7 @@ export function registerTools(server, deps) {
|
|
|
621
673
|
registerTool(`${deps.toolPrefix}.restore_item`, {
|
|
622
674
|
title: 'Restore Item',
|
|
623
675
|
description: 'Restore an item from trash by id.',
|
|
676
|
+
annotations: mutatingToolAnnotations,
|
|
624
677
|
inputSchema: {
|
|
625
678
|
id: z.string(),
|
|
626
679
|
},
|
|
@@ -638,6 +691,7 @@ export function registerTools(server, deps) {
|
|
|
638
691
|
registerTool(`${deps.toolPrefix}.create_attachment`, {
|
|
639
692
|
title: 'Create Attachment',
|
|
640
693
|
description: 'Attach a file (base64) to an existing item. Returns the updated (redacted) item.',
|
|
694
|
+
annotations: mutatingToolAnnotations,
|
|
641
695
|
inputSchema: {
|
|
642
696
|
itemId: z.string(),
|
|
643
697
|
filename: z.string(),
|
|
@@ -658,6 +712,7 @@ export function registerTools(server, deps) {
|
|
|
658
712
|
registerTool(`${deps.toolPrefix}.delete_attachment`, {
|
|
659
713
|
title: 'Delete Attachment',
|
|
660
714
|
description: 'Delete an attachment from an item. Returns the updated (redacted) item.',
|
|
715
|
+
annotations: destructiveToolAnnotations,
|
|
661
716
|
inputSchema: {
|
|
662
717
|
itemId: z.string(),
|
|
663
718
|
attachmentId: z.string(),
|
|
@@ -964,6 +1019,7 @@ export function registerTools(server, deps) {
|
|
|
964
1019
|
registerTool(`${deps.toolPrefix}.create_login`, {
|
|
965
1020
|
title: 'Create Login',
|
|
966
1021
|
description: 'Create a login item.',
|
|
1022
|
+
annotations: mutatingToolAnnotations,
|
|
967
1023
|
inputSchema: {
|
|
968
1024
|
name: z.string(),
|
|
969
1025
|
username: z.string().optional(),
|
|
@@ -1011,6 +1067,7 @@ export function registerTools(server, deps) {
|
|
|
1011
1067
|
registerTool(`${deps.toolPrefix}.create_logins`, {
|
|
1012
1068
|
title: 'Create Logins',
|
|
1013
1069
|
description: 'Create multiple login items in a single call.',
|
|
1070
|
+
annotations: mutatingToolAnnotations,
|
|
1014
1071
|
inputSchema: {
|
|
1015
1072
|
items: z.array(z.object({
|
|
1016
1073
|
name: z.string(),
|
|
@@ -1066,6 +1123,7 @@ export function registerTools(server, deps) {
|
|
|
1066
1123
|
registerTool(`${deps.toolPrefix}.set_login_uris`, {
|
|
1067
1124
|
title: 'Set Login URIs',
|
|
1068
1125
|
description: 'Set or update the URIs (and per-URI match types) for a login item. mode=replace overwrites; mode=merge updates/adds by uri.',
|
|
1126
|
+
annotations: mutatingToolAnnotations,
|
|
1069
1127
|
inputSchema: {
|
|
1070
1128
|
id: z.string(),
|
|
1071
1129
|
mode: z.enum(['replace', 'merge']).optional(),
|
|
@@ -1094,6 +1152,7 @@ export function registerTools(server, deps) {
|
|
|
1094
1152
|
registerTool(`${deps.toolPrefix}.create_note`, {
|
|
1095
1153
|
title: 'Create Note',
|
|
1096
1154
|
description: 'Create a secure note item.',
|
|
1155
|
+
annotations: mutatingToolAnnotations,
|
|
1097
1156
|
inputSchema: {
|
|
1098
1157
|
name: z.string(),
|
|
1099
1158
|
notes: z.string().optional(),
|
|
@@ -1123,6 +1182,7 @@ export function registerTools(server, deps) {
|
|
|
1123
1182
|
registerTool(`${deps.toolPrefix}.create_ssh_key`, {
|
|
1124
1183
|
title: 'Create SSH Key',
|
|
1125
1184
|
description: 'Create an SSH key object (stored as secure note with fields).',
|
|
1185
|
+
annotations: mutatingToolAnnotations,
|
|
1126
1186
|
inputSchema: {
|
|
1127
1187
|
name: z.string(),
|
|
1128
1188
|
publicKey: z.string(),
|
|
@@ -1149,6 +1209,7 @@ export function registerTools(server, deps) {
|
|
|
1149
1209
|
registerTool(`${deps.toolPrefix}.create_card`, {
|
|
1150
1210
|
title: 'Create Card',
|
|
1151
1211
|
description: 'Create a payment card item.',
|
|
1212
|
+
annotations: mutatingToolAnnotations,
|
|
1152
1213
|
inputSchema: {
|
|
1153
1214
|
name: z.string(),
|
|
1154
1215
|
cardholderName: z.string().optional(),
|
|
@@ -1184,6 +1245,7 @@ export function registerTools(server, deps) {
|
|
|
1184
1245
|
registerTool(`${deps.toolPrefix}.create_identity`, {
|
|
1185
1246
|
title: 'Create Identity',
|
|
1186
1247
|
description: 'Create an identity item.',
|
|
1248
|
+
annotations: mutatingToolAnnotations,
|
|
1187
1249
|
inputSchema: {
|
|
1188
1250
|
name: z.string(),
|
|
1189
1251
|
identity: z
|
|
@@ -1235,6 +1297,7 @@ export function registerTools(server, deps) {
|
|
|
1235
1297
|
registerTool(`${deps.toolPrefix}.update_item`, {
|
|
1236
1298
|
title: 'Update Item',
|
|
1237
1299
|
description: 'Update selected fields of an item by id.',
|
|
1300
|
+
annotations: mutatingToolAnnotations,
|
|
1238
1301
|
inputSchema: {
|
|
1239
1302
|
id: z.string(),
|
|
1240
1303
|
patch: z.object({
|
package/dist/transports/http.js
CHANGED
|
@@ -8,6 +8,7 @@ import { bwEnvFromHeadersOrEnv } from '../bw/bwHeaders.js';
|
|
|
8
8
|
import { BwSessionPool } from '../bw/bwPool.js';
|
|
9
9
|
import { KeychainSdk } from '../sdk/keychainSdk.js';
|
|
10
10
|
import { registerTools } from '../tools/registerTools.js';
|
|
11
|
+
import { SERVER_VERSION } from '../version.js';
|
|
11
12
|
export function createKeychainApp(opts = {}) {
|
|
12
13
|
const parsePositiveInt = (raw, fallback) => {
|
|
13
14
|
const parsed = Number.parseInt(raw ?? '', 10);
|
|
@@ -44,7 +45,7 @@ export function createKeychainApp(opts = {}) {
|
|
|
44
45
|
`${process.env.HOME ?? '/data'}/bw-profiles`,
|
|
45
46
|
});
|
|
46
47
|
function createMcpServer() {
|
|
47
|
-
const server = new McpServer({ name: APP_NAME, version:
|
|
48
|
+
const server = new McpServer({ name: APP_NAME, version: SERVER_VERSION });
|
|
48
49
|
registerTools(server, {
|
|
49
50
|
getSdk: async (authInfo) => {
|
|
50
51
|
const extra = authInfo?.extra;
|
package/dist/transports/stdio.js
CHANGED
|
@@ -5,6 +5,7 @@ import { BwSessionPool } from '../bw/bwPool.js';
|
|
|
5
5
|
import { readBwEnv } from '../bw/bwSession.js';
|
|
6
6
|
import { KeychainSdk } from '../sdk/keychainSdk.js';
|
|
7
7
|
import { registerTools } from '../tools/registerTools.js';
|
|
8
|
+
import { SERVER_VERSION } from '../version.js';
|
|
8
9
|
export async function runStdioTransport() {
|
|
9
10
|
const TOOL_PREFIX = process.env.TOOL_PREFIX ?? 'keychain';
|
|
10
11
|
const TOOL_SEPARATOR = process.env.TOOL_SEPARATOR ?? '_';
|
|
@@ -15,7 +16,7 @@ export async function runStdioTransport() {
|
|
|
15
16
|
rootDir: process.env.KEYCHAIN_BW_HOME_ROOT ??
|
|
16
17
|
`${process.env.HOME ?? '/data'}/bw-profiles`,
|
|
17
18
|
});
|
|
18
|
-
const server = new McpServer({ name: APP_NAME, version:
|
|
19
|
+
const server = new McpServer({ name: APP_NAME, version: SERVER_VERSION });
|
|
19
20
|
registerTools(server, {
|
|
20
21
|
getSdk: async () => {
|
|
21
22
|
const bw = await pool.getOrCreate(bwEnv);
|
package/dist/version.js
ADDED
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.4",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"description": "Vaultwarden/Bitwarden MCP server backed by Bitwarden CLI (bw).",
|
|
@@ -45,7 +45,7 @@
|
|
|
45
45
|
"lint": "biome check --write --assist-enabled=true . && tsc --noEmit"
|
|
46
46
|
},
|
|
47
47
|
"dependencies": {
|
|
48
|
-
"@modelcontextprotocol/sdk": "^1.
|
|
48
|
+
"@modelcontextprotocol/sdk": "^1.28.0",
|
|
49
49
|
"express": "^5.2.1",
|
|
50
50
|
"patch-package": "^8.0.1",
|
|
51
51
|
"zod": "^4.3.6"
|
|
@@ -54,18 +54,18 @@
|
|
|
54
54
|
"@bitwarden/cli": "2026.2.0"
|
|
55
55
|
},
|
|
56
56
|
"devDependencies": {
|
|
57
|
-
"@biomejs/biome": "^2.4.
|
|
57
|
+
"@biomejs/biome": "^2.4.9",
|
|
58
58
|
"@types/express": "^5.0.6",
|
|
59
59
|
"@types/node": "^25.5.0",
|
|
60
60
|
"playwright": "1.58.2",
|
|
61
61
|
"tsx": "^4.21.0",
|
|
62
|
-
"typescript": "^
|
|
62
|
+
"typescript": "^6.0.2"
|
|
63
63
|
},
|
|
64
64
|
"publishConfig": {
|
|
65
65
|
"registry": "https://registry.npmjs.org",
|
|
66
66
|
"access": "public"
|
|
67
67
|
},
|
|
68
68
|
"engines": {
|
|
69
|
-
"node": ">=24
|
|
69
|
+
"node": ">=24"
|
|
70
70
|
}
|
|
71
71
|
}
|