@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 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
 
@@ -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({
@@ -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: '0.1.0' });
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;
@@ -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: '0.1.0' });
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);
@@ -0,0 +1,2 @@
1
+ import packageJson from '../package.json' with { type: 'json' };
2
+ export const SERVER_VERSION = packageJson.version;
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "private": false,
3
3
  "name": "@icoretech/warden-mcp",
4
- "version": "0.2.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.27.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.8",
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": "^5.9.3"
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.14.0"
69
+ "node": ">=24"
70
70
  }
71
71
  }