@icoretech/warden-mcp 0.2.28 → 0.2.30

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
@@ -1,233 +1,97 @@
1
1
  # warden-mcp
2
2
 
3
+ **Vaultwarden / Bitwarden MCP server for credential-aware AI agents.**
4
+
3
5
  [![npm version](https://img.shields.io/npm/v/%40icoretech%2Fwarden-mcp?logo=npm)](https://www.npmjs.com/package/@icoretech/warden-mcp)
4
- [![ghcr](https://img.shields.io/badge/ghcr.io-icoretech%2Fwarden--mcp-blue?logo=docker)](https://ghcr.io/icoretech/warden-mcp)
5
6
  [![CI](https://img.shields.io/github/actions/workflow/status/icoretech/warden-mcp/ci.yml?branch=main&label=ci)](https://github.com/icoretech/warden-mcp/actions/workflows/ci.yml)
6
7
  [![license](https://img.shields.io/github/license/icoretech/warden-mcp)](LICENSE)
8
+ [![node](https://img.shields.io/badge/node-%3E%3D24-339933?logo=node.js)](package.json)
9
+ [![docker](https://img.shields.io/badge/ghcr.io-icoretech%2Fwarden--mcp-blue?logo=docker)](https://ghcr.io/icoretech/warden-mcp)
7
10
 
8
- Programmatic Vaultwarden/Bitwarden vault management over MCP (Model Context Protocol), backed by the official Bitwarden CLI (`bw`).
9
-
10
- This project exists to let agents and automation **create/search/read/update/move** vault items without re-implementing Bitwarden’s client-side crypto.
11
-
12
- Published package: [`@icoretech/warden-mcp`](https://www.npmjs.com/package/@icoretech/warden-mcp)
13
-
14
- ## Highlights
15
-
16
- - MCP Streamable HTTP endpoint at `/sse` (GET/POST; DELETE intentionally unsupported) + health check at `GET /healthz`
17
- - Runtime guardrail metrics at `GET /metricsz`
18
- - Item types: **login**, **secure note**, **card**, **identity**, plus an **SSH key** convention (secure note + standard fields)
19
- - Attachments: create/delete/download
20
- - Organization + collection helpers (list + org-collection CRUD)
21
- - Safe-by-default: item reads are **redacted** unless explicitly revealed; secret helper tools return `null` unless `reveal: true`
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
-
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
- concise visible summaries with reusable ids plus safe item metadata, including
36
- nested login username/URI values and attachment metadata where present. Delete
37
- helpers include the requested ids when no object is returned.
38
-
39
- For scalar helper tools, the text output follows the reveal contract:
40
-
41
- - `encode`, `get_uri`, and `get_exposed` show their returned scalar value
42
- - `get_username` shows the username because Bitwarden treats it as non-secret
43
- - `get_password`, `get_totp`, and `get_notes` show `not revealed` unless you pass
44
- `reveal: true`
45
- - `generate` and `generate_username` follow the same reveal contract: they show
46
- `generated: not revealed` by default and the generated value only with
47
- `reveal: true`
48
- - `get_password_history` shows `not revealed` unless you pass `reveal: true`
49
- - Send helpers mirror their returned Send payloads into visible text so
50
- text-only clients can use created Send links, fetched Send metadata, received
51
- text, and file-download metadata without reading `structuredContent`
52
- - if `NOREVEAL=true` or `KEYCHAIN_NOREVEAL=true`, revealed values are still
53
- suppressed server-side
54
-
55
- When a lookup term matches multiple login items, `keychain_get_username` and
56
- revealed `keychain_get_password` return an `AMBIGUOUS_LOOKUP` error with visible
57
- candidate ids. Retry with `term` set to an exact candidate `id`, or call
58
- `get_item` with that `id`.
59
-
60
- If `KEYCHAIN_TEXT_COMPAT_MODE=structured_json` is enabled, supported success and
61
- ambiguity/error results mirror their `structuredContent` into the visible text as
62
- serialized JSON instead of the human summaries.
63
-
64
- ## LLM Automation Use Case
65
-
66
- `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.
67
-
68
- That lets the agent do end-to-end authenticated workflows such as:
69
-
70
- - open a site or backoffice in the browser
71
- - read the right login from Vaultwarden or Bitwarden
72
- - fill username and password without hardcoding secrets in prompts or config
73
- - retrieve a current TOTP code with `keychain_get_totp` for TOTP-based MFA
74
- - continue the real task after login, such as navigation, data entry, exports, or routine admin work
75
-
76
- In practice, this is what makes the server useful for full automation, not just secret lookup. The same MCP session that gives the model browser control can also give it scoped access to the credentials and MFA material needed to finish the workflow.
77
-
78
- ## Runtime Requirement
79
-
80
- Requires Node.js 24+ and npm when running from npm or source. The Docker image
81
- already includes the supported Node runtime.
82
-
83
- At runtime, this package shells out to the official Bitwarden CLI, `bw`.
84
-
85
- Runtime resolution order:
86
-
87
- - `BW_BIN` if you set it explicitly
88
- - bundled `@bitwarden/cli` optional dependency if it is present
89
- - system `bw` from `PATH`
90
-
91
- That means package installation can succeed even when the optional dependency is skipped by the environment. In that case you must install `bw` separately or point `BW_BIN` to it.
92
-
93
- Explicit fallback install:
94
-
95
- ```bash
96
- npm install -g @bitwarden/cli@2026.5.0
97
- ```
98
-
99
- Or run with an explicit binary path:
11
+ `warden-mcp` lets MCP clients search, create, update, move, and read
12
+ Vaultwarden or Bitwarden vault items through the official Bitwarden CLI (`bw`).
13
+ It is built for agents and automation that need credentials, TOTP codes, secure
14
+ notes, attachments, Sends, folders, organizations, and collections without
15
+ re-implementing Bitwarden client-side crypto.
100
16
 
101
- ```bash
102
- BW_BIN=/absolute/path/to/bw npx -y @icoretech/warden-mcp@latest
103
- ```
104
-
105
- `warden-mcp` intentionally bundles a vetted `@bitwarden/cli` version (currently
106
- `2026.5.0`) instead of blindly following the newest upstream CLI on every
107
- release. New `bw` releases can change login and unlock behavior in ways that
108
- break automation, so `bw` upgrades should be smoke-tested against real
109
- Vaultwarden flows before bumping the bundled version. Official Bitwarden
110
- compatibility is intended, but it is not continuously proven in CI without a
111
- real Bitwarden tenant.
112
-
113
- This repository's compose smoke exercises both direct `bw` auth flows and the
114
- MCP/SDK layers with username/password auth plus user API-key auth against a real
115
- local Vaultwarden, so `@bitwarden/cli` bumps do not rely on unit coverage alone.
116
- The bundled postinstall compatibility shim rewrites the affected `build/bw.js`
117
- login strategies in place so the same Vaultwarden fallback can survive compatible
118
- CLI bumps without a version-stamped patch artifact.
17
+ Use it when an agent needs to log in to real systems during a browser or admin
18
+ workflow, but you do not want passwords hardcoded in prompts, config files, or
19
+ one-off scripts.
119
20
 
120
- ## Install And Run
121
-
122
- ### Choose a transport
21
+ ## Quick Start
123
22
 
124
- - Use `--stdio` or `WARDEN_MCP_STDIO=true` when you want a local MCP host to spawn `warden-mcp` directly with one fixed Bitwarden profile
125
- - Use default HTTP mode when you want one running `warden-mcp` service to serve multiple clients or multiple Bitwarden profiles via per-request `X-BW-*` headers
23
+ Use stdio mode when a local MCP host launches the server directly. It is the
24
+ simplest and most portable setup for desktop agents.
126
25
 
127
- ### Local stdio mode
26
+ Prerequisites:
128
27
 
129
- ```bash
130
- npx -y @icoretech/warden-mcp@latest --stdio
131
- ```
28
+ - Node.js 24+
29
+ - npm
30
+ - a Vaultwarden or Bitwarden account
31
+ - either a Bitwarden API key pair or username/password login
132
32
 
133
- For stdio mode, you must provide Bitwarden credentials up front via env vars:
33
+ Run the server:
134
34
 
135
35
  ```bash
136
36
  BW_HOST=https://vaultwarden.example.com \
137
- BW_USER=user@example.com \
37
+ BW_CLIENTID=user.xxxxx \
38
+ BW_CLIENTSECRET=xxxxx \
138
39
  BW_PASSWORD='your-master-password' \
139
40
  npx -y @icoretech/warden-mcp@latest --stdio
140
41
  ```
141
42
 
142
- API key login works too:
43
+ Username login also works:
143
44
 
144
45
  ```bash
145
46
  BW_HOST=https://vaultwarden.example.com \
146
- BW_CLIENTID=user.xxxxx \
147
- BW_CLIENTSECRET=xxxxx \
47
+ BW_USER=user@example.com \
148
48
  BW_PASSWORD='your-master-password' \
149
49
  npx -y @icoretech/warden-mcp@latest --stdio
150
50
  ```
151
51
 
152
- ### Shared HTTP mode
153
-
154
- Start one long-lived MCP server:
155
-
156
- ```bash
157
- npx -y @icoretech/warden-mcp@latest
158
- ```
159
-
160
- Verify it is up:
52
+ If the package is useful, [star the repository](https://github.com/icoretech/warden-mcp)
53
+ so other agent builders can find it.
161
54
 
162
- ```bash
163
- curl -fsS http://localhost:3005/healthz
164
- ```
165
-
166
- This mode is what makes `warden-mcp` different from a simple local wrapper:
55
+ ## Install In MCP Hosts
167
56
 
168
- - Bitwarden/Vaultwarden credentials and profile selection are resolved per request via `X-BW-*` headers
169
- - MCP Streamable HTTP sessions are stateful and tracked by `mcp-session-id`
170
- - per-profile `bw` state is kept server-side under `KEYCHAIN_BW_HOME_ROOT`
171
- - one running server can front different vault hosts or different identities without restarting
172
- - it fits shared-agent and gateway setups much better than per-client local processes
57
+ Most local hosts should use stdio. The examples below use API-key auth; replace
58
+ `BW_CLIENTID` and `BW_CLIENTSECRET` with `BW_USER` if you prefer username login.
173
59
 
174
- ### Docker
60
+ ### Claude Code
175
61
 
176
62
  ```bash
177
- docker run --rm \
178
- -p 127.0.0.1:3005:3005 \
179
- -v warden-mcp-data:/data \
180
- ghcr.io/icoretech/warden-mcp:latest
181
- ```
182
-
183
- The production image runs as the non-root `node` user (uid/gid `1000`), sets
184
- `HOME=/data`, and stores Bitwarden profile state under `/data/bw-profiles` by
185
- default. If you use a bind mount instead of the named volume above, make it
186
- writable by uid/gid `1000`.
187
-
188
- ### Global install
189
-
190
- ```bash
191
- npm install -g @icoretech/warden-mcp@latest
192
- warden-mcp
193
- ```
194
-
195
- ## Connect From MCP Hosts
196
-
197
- For local MCP hosts, stdio is the most portable option.
198
-
199
- ```bash
200
- npx -y @icoretech/warden-mcp@latest --stdio
63
+ 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"}}'
201
64
  ```
202
65
 
203
- The examples below use Bitwarden API-key auth. If you prefer username/password login, replace `BW_CLIENTID` + `BW_CLIENTSECRET` with `BW_USER`.
204
-
205
- ### CLI-based hosts
206
-
207
- These hosts let you register `warden-mcp` directly from the command line:
66
+ ### Codex
208
67
 
209
68
  ```bash
210
- # Codex
211
69
  codex mcp add warden \
212
70
  --env BW_HOST=https://vaultwarden.example.com \
213
71
  --env BW_CLIENTID=user.xxxxx \
214
72
  --env BW_CLIENTSECRET=xxxxx \
215
73
  --env BW_PASSWORD='your-master-password' \
216
74
  -- npx -y @icoretech/warden-mcp@latest --stdio
217
-
218
- # Claude Code
219
- 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"}}'
220
75
  ```
221
76
 
222
- ### JSON config hosts
77
+ Codex TOML config:
223
78
 
224
- These hosts all use the same stdio payload shape. Only the config file location changes:
79
+ ```toml
80
+ [mcp_servers.warden]
81
+ command = "npx"
82
+ args = ["-y", "@icoretech/warden-mcp@latest", "--stdio"]
83
+ startup_timeout_sec = 30
225
84
 
226
- - Codex: `~/.codex/config.toml`
227
- - Cursor: `~/.cursor/mcp.json` or `.cursor/mcp.json`
228
- - Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`
85
+ [mcp_servers.warden.env]
86
+ BW_HOST = "https://vaultwarden.example.com"
87
+ BW_CLIENTID = "user.xxxxx"
88
+ BW_CLIENTSECRET = "xxxxx"
89
+ BW_PASSWORD = "your-master-password"
90
+ ```
91
+
92
+ `startup_timeout_sec = 30` gives `npx` enough time for a cold first launch.
229
93
 
230
- Shared JSON shape:
94
+ ### Cursor, Claude Desktop, And JSON Config Hosts
231
95
 
232
96
  ```json
233
97
  {
@@ -246,115 +110,85 @@ Shared JSON shape:
246
110
  }
247
111
  ```
248
112
 
249
- Codex uses TOML instead of JSON:
250
-
251
- ```toml
252
- [mcp_servers.warden]
253
- command = "npx"
254
- args = ["-y", "@icoretech/warden-mcp@latest", "--stdio"]
255
- startup_timeout_sec = 30
113
+ Common locations:
256
114
 
257
- [mcp_servers.warden.env]
258
- BW_HOST = "https://vaultwarden.example.com"
259
- BW_CLIENTID = "user.xxxxx"
260
- BW_CLIENTSECRET = "xxxxx"
261
- BW_PASSWORD = "your-master-password"
262
- ```
263
-
264
- `startup_timeout_sec = 30` is a practical Codex default when using `npx`,
265
- because a cold first launch can spend several seconds downloading and unpacking
266
- the package before MCP initialization begins.
267
-
268
- ### Shared HTTP connections
269
-
270
- 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.
271
-
272
- Start the shared server:
273
-
274
- ```bash
275
- npx -y @icoretech/warden-mcp@latest
276
- ```
115
+ | Host | Config file |
116
+ | --- | --- |
117
+ | Cursor | `~/.cursor/mcp.json` or `.cursor/mcp.json` |
118
+ | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
119
+ | Codex | `~/.codex/config.toml` |
120
+
121
+ ## Why Use It
122
+
123
+ - **Agent login flows** - fetch usernames, passwords, and TOTP codes during real
124
+ browser automation without storing secrets in the agent prompt
125
+ - **Safe by default** - secret fields stay redacted unless a tool supports
126
+ `reveal: true` and the client explicitly asks for it
127
+ - **Vault administration** - create, update, move, restore, and delete common
128
+ Bitwarden item types, folders, organization collections, attachments, and Sends
129
+ - **Shared HTTP mode** - one long-running service can front multiple vault hosts
130
+ or identities through per-request `X-BW-*` headers
131
+ - **Text-only client support** - safe identifiers are mirrored into text output
132
+ for MCP hosts that ignore `structuredContent`
133
+ - **Vaultwarden-first CI** - the integration suite exercises real local
134
+ Vaultwarden and `bw` auth/session flows, not only mocked SDK behavior
277
135
 
278
- `GET /healthz` and `GET /metricsz` are liveness/guardrail endpoints and do not
279
- validate Bitwarden credentials:
136
+ ## How It Works
280
137
 
281
- ```bash
282
- curl -fsS http://localhost:3005/healthz
138
+ ```mermaid
139
+ flowchart LR
140
+ Agent["AI agent or MCP client"] --> Transport["stdio or Streamable HTTP"]
141
+ Transport --> Server["warden-mcp"]
142
+ Server --> BW["Bitwarden CLI (bw)"]
143
+ BW --> Vault["Vaultwarden or Bitwarden"]
144
+ Server --> State["per-profile bw state"]
283
145
  ```
284
146
 
285
- Bitwarden-backed MCP tool calls must include these headers unless
286
- `KEYCHAIN_ALLOW_ENV_FALLBACK=true` is enabled:
287
-
288
- - `X-BW-Host` — HTTPS origin only; no credentials, path, query, or fragment
289
- - `X-BW-Password`
290
- - either `X-BW-ClientId` + `X-BW-ClientSecret`, or `X-BW-User` / `X-BW-Username`
291
- - optional `X-BW-Unlock-Interval` in seconds; default `300`
147
+ `warden-mcp` shells out to `bw` and keeps profile state under
148
+ `KEYCHAIN_BW_HOME_ROOT`. In HTTP mode, profile selection and credentials come
149
+ from request headers. In stdio mode, credentials are loaded from `BW_*` env vars
150
+ when the process starts.
292
151
 
293
- Example MCP endpoint:
152
+ The HTTP server exposes:
294
153
 
295
- ```text
296
- http://localhost:3005/sse?v=2
297
- ```
298
-
299
- This shared-server mode is useful when:
154
+ | Endpoint | Purpose |
155
+ | --- | --- |
156
+ | `GET /healthz` | liveness check; does not validate vault credentials |
157
+ | `GET /metricsz` | session and runtime guardrail metrics |
158
+ | `/sse?v=2` | MCP Streamable HTTP endpoint |
300
159
 
301
- - one MCP gateway needs to front multiple Bitwarden profiles
302
- - you want to rotate vault credentials per request instead of per process
303
- - you are integrating from a custom client or agent host that can attach HTTP headers
304
- - you want one always-on service instead of each editor spawning its own `bw`-backed subprocess
160
+ ## Run As A Shared HTTP Service
305
161
 
306
- #### Headerless SSE clients (`claude.ai` web, similar hosts)
162
+ HTTP mode is useful when one service should serve multiple clients or multiple
163
+ vault profiles.
307
164
 
308
- Some web MCP hosts can connect to a Streamable HTTP / SSE endpoint but cannot
309
- attach custom `X-BW-*` headers. In that case, run `warden-mcp` as a
310
- single-tenant shared server with fixed server-side credentials and explicit env
311
- fallback enabled:
165
+ Start the server:
312
166
 
313
167
  ```bash
314
- BW_HOST=https://vaultwarden.example.com \
315
- BW_CLIENTID=user.xxxxx \
316
- BW_CLIENTSECRET=xxxxx \
317
- BW_PASSWORD='your-master-password' \
318
- KEYCHAIN_ALLOW_ENV_FALLBACK=true \
319
168
  npx -y @icoretech/warden-mcp@latest
320
169
  ```
321
170
 
322
- Some hosted or browser-based MCP clients expect the server URL to be available
323
- over **HTTPS** rather than plain `http://localhost:3005/...`.
324
-
325
- If you are running `warden-mcp` locally, that usually means putting one of
326
- these in front of it:
327
-
328
- - a local HTTPS reverse proxy in front of `warden-mcp`
329
- - a temporary tunnel such as Cloudflare Tunnel, ngrok, or Tailscale Funnel
171
+ Verify liveness:
330
172
 
331
- Then point the client at the HTTPS endpoint, for example:
332
-
333
- ```text
334
- https://warden-mcp.example.com/sse?v=2
173
+ ```bash
174
+ curl -fsS http://localhost:3005/healthz
335
175
  ```
336
176
 
337
- This works because headerless HTTP requests can inherit the server's own
338
- `BW_*` configuration when `KEYCHAIN_ALLOW_ENV_FALLBACK=true`. You can use
339
- `BW_USER` + `BW_PASSWORD` here as well; the example above shows the API-key
340
- variant because it is the default convention used elsewhere in this README.
341
-
342
- Important limits:
343
-
344
- - this is single-tenant only: every headerless client gets the same vault identity
345
- - per-request profile switching does not work in this mode
346
- - if a client can send `X-BW-*` headers, those headers still take priority over the server env
347
- - 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
177
+ MCP tool calls must include these headers unless env fallback is explicitly
178
+ enabled:
348
179
 
349
- Client examples for shared HTTP mode:
180
+ | Header | Meaning |
181
+ | --- | --- |
182
+ | `X-BW-Host` | HTTPS origin only, for example `https://vaultwarden.example.com` |
183
+ | `X-BW-Password` | master password used to unlock the vault |
184
+ | `X-BW-ClientId` | Bitwarden API key client id |
185
+ | `X-BW-ClientSecret` | Bitwarden API key client secret |
186
+ | `X-BW-User` or `X-BW-Username` | username/email alternative to API key login |
187
+ | `X-BW-Unlock-Interval` | optional unlock interval in seconds; default `300` |
350
188
 
351
- ```bash
352
- # Claude Code
353
- claude mcp add-json warden '{"type":"http","url":"http://localhost:3005/sse?v=2","headers":{"X-BW-Host":"https://vaultwarden.example.com","X-BW-ClientId":"user.xxxxx","X-BW-ClientSecret":"xxxxx","X-BW-Password":"your-master-password"}}'
354
- ```
189
+ Example HTTP MCP config for hosts that support custom headers:
355
190
 
356
191
  ```json
357
- // Cursor (~/.cursor/mcp.json)
358
192
  {
359
193
  "mcpServers": {
360
194
  "warden": {
@@ -370,263 +204,229 @@ claude mcp add-json warden '{"type":"http","url":"http://localhost:3005/sse?v=2"
370
204
  }
371
205
  ```
372
206
 
373
- 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.
374
-
375
- ### Verify bw is available
376
-
377
- ```bash
378
- bw --version
379
- ```
380
-
381
- If that fails after install, your environment likely skipped the optional `@bitwarden/cli` dependency. Install it explicitly:
382
-
383
- ```bash
384
- npm install -g @bitwarden/cli@2026.5.0
385
- ```
386
-
387
- ## How It Works
388
-
389
- The server executes `bw` commands on your behalf:
390
-
391
- - In HTTP mode, Bitwarden/Vaultwarden credentials are provided via **HTTP headers** for tool calls. Env-var fallback is disabled by default; set `KEYCHAIN_ALLOW_ENV_FALLBACK=true` only for single-tenant HTTP deployments.
392
- - In stdio mode, Bitwarden/Vaultwarden credentials are loaded once from `BW_*` env vars at startup.
393
- - The server maintains per-profile `bw` state under `KEYCHAIN_BW_HOME_ROOT` and pins `BITWARDENCLI_APPDATA_DIR` inside that profile so the Bitwarden CLI keeps a stable local device/app identity across restarts instead of looking like a fresh client every time.
394
- - Writes call `bw sync` before mutations by default; set `KEYCHAIN_SYNC_ON_WRITE=false` to skip that pre-write sync. Manual sync is also exposed as `keychain_sync`.
395
-
396
- Timeout handling is also process-tree aware: if a `bw` command hangs, `warden-mcp` kills the full spawned process group rather than only the direct parent process. That prevents timed-out auth attempts from leaving orphaned `bw`/shell child processes behind.
397
-
398
- ### Bitwarden credential inputs
399
-
400
- - `X-BW-Host` / `BW_HOST` (must be an HTTPS origin, for example `https://vaultwarden.example.com`; no path, query, fragment, or embedded credentials)
401
- - `X-BW-Password` / `BW_PASSWORD` (master password; required to unlock)
402
- - Either:
403
- - `X-BW-ClientId` + `X-BW-ClientSecret` / `BW_CLIENTID` + `BW_CLIENTSECRET` (API key login), or
404
- - `X-BW-User` / `X-BW-Username` / `BW_USER` / `BW_USERNAME` (email for user/pass login; still uses the master password)
405
- - Optional unlock interval:
406
- - `X-BW-Unlock-Interval` / `BW_UNLOCK_INTERVAL` in seconds; default `300`
407
-
408
- ## Security Model
409
-
410
- There is **no built-in auth** layer in v1. Run it only on a trusted network boundary (localhost, private subnet, VPN, etc.).
411
-
412
- Credential resolution:
413
-
414
- - **HTTP mode** requires `X-BW-*` headers before Bitwarden-backed tools can run by default. `/healthz` and `/metricsz` do not validate vault credentials.
415
- - **Stdio mode** reads `BW_*` env vars at startup (single-tenant).
416
- - To allow HTTP mode to fall back to server env vars when headers are absent (single-tenant HTTP), set `KEYCHAIN_ALLOW_ENV_FALLBACK=true`. **Security warning:** this means any client that can reach the HTTP endpoint gets full vault access without providing credentials. Only use this behind network-level access control.
417
-
418
- Runtime and safety controls:
419
-
420
- - Set `PORT` to change the HTTP port (default `3005`).
421
- - Set `WARDEN_MCP_HOST` to bind the HTTP server to a specific interface, for example `127.0.0.1` for local-only access.
422
- - Set `WARDEN_MCP_STDIO=true` as an env-var alternative to `--stdio`.
423
- - Set `MCP_APP_NAME` to override the advertised MCP server name.
424
- - Tool names default to `keychain_*`. Override `TOOL_PREFIX` to change the namespace and `TOOL_SEPARATOR` to change the separator (default `_`, set `.` for legacy clients).
425
- - Set `KEYCHAIN_BW_HOME_ROOT` to change where per-profile `bw` state is stored.
426
- - Set `KEYCHAIN_SYNC_ON_WRITE=false` to skip the default pre-write `bw sync` call.
427
- - Set `READONLY=true` or `KEYCHAIN_READONLY=true` to hide mutating tools from the advertised MCP catalog and reject direct write calls. This covers item/folder/org collection writes, Sends, attachments, batch creates/deletes, URI updates, moves, and restores.
428
- - Set `NOREVEAL=true` or `KEYCHAIN_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.
429
- - 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.
430
-
431
- Session guardrails:
432
-
433
- - `KEYCHAIN_SESSION_MAX_COUNT` (default `32`)
434
- - `KEYCHAIN_SESSION_TTL_MS` (default `900000`)
435
- - `KEYCHAIN_SESSION_SWEEP_INTERVAL_MS` (default `60000`)
436
- - `KEYCHAIN_MAX_HEAP_USED_MB` (default `1536`, set `0` to disable memory fuse)
437
- - `KEYCHAIN_METRICS_LOG_INTERVAL_MS` (default `0`, disabled)
438
-
439
- Redaction defaults (item reads):
440
-
441
- - Login: `password`, `totp`
442
- - Card: `number`, `code`
443
- - Identity: `ssn`, `passportNumber`, `licenseNumber`
444
- - Custom fields: hidden fields (Bitwarden `type: 1`)
445
- - SSH key convention: custom field `private_key` is always redacted
446
- - Attachments: `attachments[].url` (signed download URL token)
447
- - Password history: `passwordHistory[].password`
448
-
449
- Reveal rules:
450
-
451
- - Tools accept `reveal: true` where applicable (default is `false`).
452
- - Secret helper tools (`get_password`, `get_totp`, `get_notes`, `generate`, `generate_username`, `get_password_history`) return `structuredContent.result = { kind, value, revealed }`.
453
- - When `reveal` is omitted/false, `value` is `null` (or historic passwords are `null`) and `revealed: false`.
454
-
455
- ## Production Deployment Checklist
456
-
457
- If you run `warden-mcp` beyond local development, review these items:
458
-
459
- 1. **TLS everywhere.** Always terminate TLS in front of the HTTP endpoint. `X-BW-*` headers carry master passwords in cleartext — without TLS they are visible to anyone on the network.
460
-
461
- 2. **Network isolation.** Bind or publish the server only on a trusted interface, for example `WARDEN_MCP_HOST=127.0.0.1`, Docker `-p 127.0.0.1:3005:3005`, a firewall, VPN, or an authenticated reverse proxy. The service has no built-in authentication; anyone who can reach `/sse` can issue vault operations.
462
-
463
- 3. **Do not enable `KEYCHAIN_ALLOW_ENV_FALLBACK` on shared networks.** This flag makes the server's own vault credentials available to any HTTP client that omits headers. Only use it in single-tenant setups where the network is fully trusted.
464
-
465
- 4. **Enable `READONLY=true` or `KEYCHAIN_READONLY=true` when writes are not needed.** This hides mutating tools from the advertised MCP catalog and rejects direct write calls at the MCP layer, limiting blast radius if an agent or client is compromised.
466
-
467
- 5. **Persist and restrict filesystem access to the configured `KEYCHAIN_BW_HOME_ROOT`.** In Docker the default is `/data/bw-profiles`; on host runs it defaults to `${HOME}/bw-profiles`. Ensure the profile directory is not world-readable and is mounted with appropriate permissions (the Docker image runs as non-root uid/gid `1000`).
468
-
469
- 6. **Disable debug logging in production.** `KEYCHAIN_DEBUG_BW` and `KEYCHAIN_DEBUG_HTTP` emit request details and CLI invocations to stdout. Debug logs may include session metadata and request structure. Keep them off unless actively troubleshooting.
470
-
471
- 7. **Set `NOREVEAL=true` when secrets should never leave the server.** This forces all `reveal` parameters to `false` server-side, regardless of what the client requests. Use this when the MCP host is an LLM agent that could be influenced by prompt injection — it prevents tricked agents from exfiltrating passwords or TOTP codes.
472
-
473
- 8. **Monitor `/metricsz`.** The endpoint is intentionally unauthenticated (for scraper compatibility) but exposes session counts, heap usage, and rejection counters. If this data is sensitive in your environment, restrict access at the network level.
474
-
475
- 9. **Only enable `KEYCHAIN_TEXT_COMPAT_MODE=structured_json` for text-only clients you trust.** It improves compatibility with clients that ignore `structuredContent`, but any revealed secret will also appear in plain-text `TextContent`, making transcript leakage easier.
476
-
477
- ## Quick Start
478
-
479
- ### Minimal local run
480
-
481
- Run the published package in HTTP mode and verify the server is up:
207
+ Some browser-hosted MCP clients can connect to an HTTP/SSE endpoint but cannot
208
+ send custom `X-BW-*` headers. For those clients, run a single-tenant HTTP server
209
+ with env fallback:
482
210
 
483
211
  ```bash
212
+ BW_HOST=https://vaultwarden.example.com \
213
+ BW_CLIENTID=user.xxxxx \
214
+ BW_CLIENTSECRET=xxxxx \
215
+ BW_PASSWORD='your-master-password' \
216
+ KEYCHAIN_ALLOW_ENV_FALLBACK=true \
484
217
  npx -y @icoretech/warden-mcp@latest
485
- curl -fsS http://localhost:3005/healthz
486
218
  ```
487
219
 
488
- ## Local Development
489
-
490
- ### Docker Compose
220
+ Only use `KEYCHAIN_ALLOW_ENV_FALLBACK=true` behind a trusted network boundary.
221
+ Every client that can reach the endpoint inherits the configured vault identity.
491
222
 
492
- Starts a local Vaultwarden + HTTPS proxy (for `bw`), bootstraps a test user, and runs the MCP server.
223
+ For hosted clients that require HTTPS, put a reverse proxy, private tunnel, VPN,
224
+ or equivalent protected endpoint in front of `warden-mcp`, then connect to:
493
225
 
494
- ```bash
495
- cp .env.example .env
496
- make up
226
+ ```text
227
+ https://warden-mcp.example.com/sse?v=2
497
228
  ```
498
229
 
499
- `make up` keeps the MCP service in the foreground. In another terminal, verify
500
- the server is up:
230
+ ## Docker
501
231
 
502
232
  ```bash
503
- curl -fsS http://localhost:3005/healthz
233
+ docker run --rm \
234
+ -p 127.0.0.1:3005:3005 \
235
+ -v warden-mcp-data:/data \
236
+ ghcr.io/icoretech/warden-mcp:latest
504
237
  ```
505
238
 
506
- Run integration tests:
239
+ The production image runs as the non-root `node` user with uid/gid `1000`, sets
240
+ `HOME=/data`, and stores Bitwarden profile state under `/data/bw-profiles` by
241
+ default. If you use a bind mount, make it writable by uid/gid `1000`.
507
242
 
508
- ```bash
509
- make test
510
- ```
243
+ ## Runtime Requirements
244
+
245
+ `warden-mcp` requires Node.js 24+ when running from npm or source. The Docker
246
+ image includes the supported Node runtime.
511
247
 
512
- `make test` now runs both compose-backed auth paths and verifies them at the
513
- raw CLI plus MCP/SDK layers:
248
+ The server resolves `bw` in this order:
514
249
 
515
- - user/password login from `.env.test`
516
- - api-key login from `tmp/vaultwarden-bootstrap/apikey.env`, generated by the bootstrap step and kept out of git via `tmp/`
250
+ 1. `BW_BIN`, when set
251
+ 2. bundled `@bitwarden/cli` optional dependency, when installed
252
+ 3. system `bw` from `PATH`
517
253
 
518
- The compose bootstrap step depends on the Playwright Docker image matching the
519
- `playwright` npm package version. If either moves, update the other in the same
520
- change.
254
+ The bundled `@bitwarden/cli` version is currently `2026.6.0`. This project keeps
255
+ that version vetted instead of blindly tracking every upstream release, because
256
+ auth and unlock behavior can change in ways that break automation.
521
257
 
522
- Optional organization-focused integration stack:
258
+ If your package manager skips optional dependencies and `bw` is missing, install
259
+ the CLI explicitly or point `BW_BIN` to a known binary:
523
260
 
524
261
  ```bash
525
- make test-org
262
+ npm install -g @bitwarden/cli@2026.6.0
263
+ BW_BIN=/absolute/path/to/bw npx -y @icoretech/warden-mcp@latest --stdio
526
264
  ```
527
265
 
528
- Use `make up-org`, `make bootstrap-org`, `make down-org`, and `make ps-org` when
529
- you need to inspect that stack manually.
266
+ ## Security Model
530
267
 
531
- Run session flood regression locally after a server is already running on
532
- `http://127.0.0.1:3005` (override with `KEYCHAIN_FLOOD_BASE_URL` and
533
- `KEYCHAIN_METRICS_URL` when needed):
268
+ There is no built-in authentication layer in v1. Protect the transport before
269
+ you expose it.
270
+
271
+ - **Bind locally by default** - use `WARDEN_MCP_HOST=127.0.0.1`, Docker
272
+ `-p 127.0.0.1:3005:3005`, a firewall, VPN, or an authenticated reverse proxy
273
+ - **Use TLS for HTTP mode** - `X-BW-*` headers carry vault credentials
274
+ - **Avoid env fallback on shared networks** - `KEYCHAIN_ALLOW_ENV_FALLBACK=true`
275
+ makes server-side vault credentials available to headerless clients
276
+ - **Use read-only mode when writes are not needed** - `READONLY=true` or
277
+ `KEYCHAIN_READONLY=true` hides mutating tools and rejects direct write calls
278
+ - **Use no-reveal mode for untrusted agent contexts** - `NOREVEAL=true` or
279
+ `KEYCHAIN_NOREVEAL=true` forces all secret-returning tools to stay redacted
280
+ - **Keep debug logs off in production** - do not enable `KEYCHAIN_DEBUG_BW` or
281
+ `KEYCHAIN_DEBUG_HTTP` unless actively troubleshooting
282
+ - **Restrict profile storage** - protect `KEYCHAIN_BW_HOME_ROOT`, which stores
283
+ local `bw` profile state
284
+ - **Protect `/metricsz` if needed** - it is unauthenticated for scraper
285
+ compatibility and exposes runtime/session counters
286
+
287
+ Redacted fields include login passwords, TOTP seeds/codes, card numbers and
288
+ codes, identity SSNs/passport/license numbers, hidden custom fields, SSH private
289
+ keys stored through the secure-note convention, signed attachment URLs, and
290
+ password history entries.
291
+
292
+ ## Configuration
293
+
294
+ | Variable | Default | Purpose |
295
+ | --- | --- | --- |
296
+ | `PORT` | `3005` | HTTP listen port |
297
+ | `WARDEN_MCP_HOST` | all interfaces | HTTP bind host |
298
+ | `WARDEN_MCP_STDIO` | `false` | force stdio mode without `--stdio` |
299
+ | `MCP_APP_NAME` | `keychain-mcp` | advertised MCP server name |
300
+ | `TOOL_PREFIX` | `keychain` | public tool namespace |
301
+ | `TOOL_SEPARATOR` | `_` | public tool separator; set `.` for legacy clients |
302
+ | `KEYCHAIN_BW_HOME_ROOT` | `${HOME}/bw-profiles` | root for per-profile `bw` state |
303
+ | `KEYCHAIN_ALLOW_ENV_FALLBACK` | `false` | allow HTTP calls to inherit server `BW_*` env |
304
+ | `KEYCHAIN_SYNC_ON_WRITE` | `true` | run `bw sync` before write operations |
305
+ | `READONLY` / `KEYCHAIN_READONLY` | `false` | hide and reject mutating tools |
306
+ | `NOREVEAL` / `KEYCHAIN_NOREVEAL` | `false` | force `reveal: false` server-side |
307
+ | `KEYCHAIN_TEXT_COMPAT_MODE` | unset | set `structured_json` for text-only clients |
308
+ | `KEYCHAIN_SESSION_MAX_COUNT` | `32` | max tracked HTTP sessions |
309
+ | `KEYCHAIN_SESSION_TTL_MS` | `900000` | inactive session TTL |
310
+ | `KEYCHAIN_SESSION_SWEEP_INTERVAL_MS` | `60000` | session cleanup interval |
311
+ | `KEYCHAIN_MAX_HEAP_USED_MB` | `1536` | memory fuse; set `0` to disable |
312
+ | `KEYCHAIN_METRICS_LOG_INTERVAL_MS` | `0` | periodic metrics logging; `0` disables |
313
+
314
+ `KEYCHAIN_TEXT_COMPAT_MODE=structured_json` mirrors supported
315
+ `structuredContent` into plain text. That helps MCP clients that only pass
316
+ `content[]` to the model, but any revealed secret will also appear in the text
317
+ transcript.
318
+
319
+ ## Tool Reference
320
+
321
+ Tool names default to `keychain_*`. Change the prefix with `TOOL_PREFIX` and the
322
+ separator with `TOOL_SEPARATOR`.
323
+
324
+ Start with these:
325
+
326
+ - `keychain_status` - inspect raw `bw` status
327
+ - `keychain_sync` - pull latest vault data with `bw sync`
328
+ - `keychain_search_items` - find items by name, URI, username, folder,
329
+ collection, or type
330
+ - `keychain_get_item` - read a full item by id, redacted by default
331
+ - `keychain_get_username`, `keychain_get_password`, `keychain_get_totp` - fetch
332
+ common login values; password and TOTP require `reveal: true`
333
+ - `keychain_create_login`, `keychain_update_item`,
334
+ `keychain_move_item_to_organization` - common write paths
335
+
336
+ Full tool groups:
337
+
338
+ | Group | Tools |
339
+ | --- | --- |
340
+ | Vault/session | `keychain_status`, `keychain_sync`, `keychain_sdk_version`, `keychain_encode`, `keychain_generate`, `keychain_generate_username` |
341
+ | Items | `keychain_search_items`, `keychain_get_item`, `keychain_update_item`, `keychain_create_login`, `keychain_create_logins`, `keychain_set_login_uris`, `keychain_create_note`, `keychain_create_card`, `keychain_create_identity`, `keychain_create_ssh_key`, `keychain_delete_item`, `keychain_delete_items`, `keychain_restore_item` |
342
+ | Folders | `keychain_list_folders`, `keychain_create_folder`, `keychain_edit_folder`, `keychain_delete_folder` |
343
+ | Organizations and collections | `keychain_list_organizations`, `keychain_list_collections`, `keychain_list_org_collections`, `keychain_create_org_collection`, `keychain_edit_org_collection`, `keychain_delete_org_collection`, `keychain_move_item_to_organization` |
344
+ | Attachments | `keychain_create_attachment`, `keychain_delete_attachment`, `keychain_get_attachment` |
345
+ | Sends | `keychain_send_list`, `keychain_send_template`, `keychain_send_get`, `keychain_send_create`, `keychain_send_create_encoded`, `keychain_send_edit`, `keychain_send_remove_password`, `keychain_send_delete`, `keychain_receive` |
346
+ | Direct `bw get` helpers | `keychain_get_username`, `keychain_get_password`, `keychain_get_totp`, `keychain_get_notes`, `keychain_get_uri`, `keychain_get_exposed`, `keychain_get_folder`, `keychain_get_collection`, `keychain_get_organization`, `keychain_get_org_collection`, `keychain_get_password_history` |
347
+
348
+ Notes:
349
+
350
+ - `keychain_create_logins` creates several independent login items in one call
351
+ and reports per-item failures without aborting the whole batch
352
+ - `keychain_set_login_uris` replaces or merges a login item's URI list without
353
+ editing the entire item payload
354
+ - `keychain_delete_items` supports bulk soft-delete or hard-delete by id
355
+ - `keychain_get_item` exposes safe attachment metadata, including `id`,
356
+ `fileName`, and size, while redacting signed download URLs
357
+ - `keychain_get_attachment` accepts an attachment id or an unambiguous filename
358
+ and returns `{ filename, bytes, contentBase64 }`
359
+ - `keychain_send_get` returns owned Send metadata and text content; use
360
+ `keychain_receive` with a Send `accessUrl` to receive shared Sends or download
361
+ file Send bytes
362
+ - Ambiguous login lookups return `AMBIGUOUS_LOOKUP` with visible candidate ids;
363
+ retry with the exact item id
534
364
 
535
- ```bash
536
- npm run test:session-regression
537
- ```
365
+ ## Local Development
538
366
 
539
- ### Local dev (host)
367
+ Use Docker Compose when you need the full Vaultwarden-backed stack.
540
368
 
541
369
  ```bash
542
- npm ci
543
- set -a && . ./.env && set +a # optional; Docker Compose reads .env automatically, host dev does not
544
- npm run dev
370
+ cp .env.example .env
371
+ make up
545
372
  ```
546
373
 
547
- For host HTTP mode, vault credentials can still be supplied per request with
548
- `X-BW-*` headers instead of loading them into the server environment.
374
+ `make up` starts local Vaultwarden, an HTTPS proxy for `bw`, bootstraps a test
375
+ account, and runs the MCP server in the foreground.
549
376
 
550
- Useful npm scripts:
377
+ Useful commands:
551
378
 
552
- | Script | Purpose |
379
+ | Command | Purpose |
553
380
  | --- | --- |
554
- | `npm run build` | Compile TypeScript to `dist/` |
555
- | `npm run dev` | Watch-mode local HTTP server |
556
- | `npm run start` | Run the compiled server from `dist/` |
557
- | `npm run test` | Build, then run all compiled unit tests |
558
- | `npm run test:integration` | Build, then run compose-backed integration tests one file at a time |
559
- | `npm run test:coverage` | Build, then run Node test coverage |
560
- | `npm run lint` | Run Biome autofix plus `tsc --noEmit` |
561
-
562
-
563
- ## Tool Reference (v1)
564
-
565
- ### Choosing the right tool
566
-
567
- - 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.
568
- - Use `keychain_create_logins` when you need to create several independent login items in one call; it returns per-item results and can continue after individual failures.
569
- - Use `keychain_set_login_uris` to replace or merge a login item's URI list without editing the whole item payload.
570
- - Use `keychain_delete_items` for bulk soft-delete/hard-delete by id with per-id results.
571
- - 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.
572
- - `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.
573
- - `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.
574
- - `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.
575
- - 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.
576
-
577
- Vault/session:
381
+ | `npm run dev` | watch-mode server from source |
382
+ | `npm run build` | compile TypeScript to `dist/` |
383
+ | `npm run start` | run the compiled server |
384
+ | `npm run lint` | Biome autofix plus `tsc --noEmit` |
385
+ | `npm run test` | build, then run all compiled tests |
386
+ | `npm run test:integration` | build, then run compose-backed integration tests |
387
+ | `npm run test:coverage` | build, then run Node test coverage |
388
+ | `make test` | run the compose-backed Vaultwarden integration path |
389
+ | `make test-org` | run the organization-focused compose stack |
390
+ | `make down` | stop the local compose stack |
391
+
392
+ For a quick live MCP smoke against local Vaultwarden, see
393
+ [agent-instructions/testing.md](agent-instructions/testing.md).
394
+
395
+ ## Compatibility
396
+
397
+ Vaultwarden is the continuously proven target in CI. Official Bitwarden
398
+ compatibility is intended, but it is not continuously proven without a real
399
+ Bitwarden tenant.
400
+
401
+ `@bitwarden/cli` upgrades are treated as compatibility decisions. The suite
402
+ checks direct `bw` auth behavior, SDK behavior, and MCP integration behavior
403
+ against a local Vaultwarden instance before a CLI bump should ship.
578
404
 
579
- - `keychain_status`
580
- - `keychain_sync` (pull latest vault data from server via `bw sync`)
581
- - `keychain_sdk_version` (returns the Bitwarden CLI version reported by `bw --version`)
582
- - `keychain_encode` (base64-encode a string via `bw encode`)
583
- - `keychain_generate`, `keychain_generate_username` (return generated values only when `reveal: true`)
584
-
585
- Items:
586
-
587
- - `keychain_search_items`, `keychain_get_item`, `keychain_update_item`
588
- - `keychain_create_login`, `keychain_create_logins`, `keychain_set_login_uris`
589
- - `keychain_create_note`, `keychain_create_card`, `keychain_create_identity`, `keychain_create_ssh_key`
590
- - `keychain_delete_item`, `keychain_delete_items`, `keychain_restore_item`
591
-
592
- Folders:
593
-
594
- - `keychain_list_folders`, `keychain_create_folder`, `keychain_edit_folder`, `keychain_delete_folder`
595
-
596
- Orgs/collections:
597
-
598
- - `keychain_list_organizations`, `keychain_list_collections`
599
- - `keychain_list_org_collections`, `keychain_create_org_collection`, `keychain_edit_org_collection`, `keychain_delete_org_collection`
600
- - `keychain_move_item_to_organization`
601
-
602
- Attachments:
603
-
604
- - `keychain_create_attachment`, `keychain_delete_attachment`, `keychain_get_attachment`
605
- - `keychain_get_item` exposes safe attachment metadata (`id`, `fileName`, size) while redacting signed download URLs, so clients can discover the exact attachment id before downloading
606
- - `keychain_get_attachment` accepts an attachment id or an unambiguous filename and returns `{ filename, bytes, contentBase64 }`; decode `contentBase64` locally when you need the original file bytes
607
-
608
- Sends:
405
+ ## Known Limitations
609
406
 
610
- - `keychain_send_list`, `keychain_send_template`, `keychain_send_get`
611
- - `keychain_send_create` (quick create via `bw send`, including optional `emails`)
612
- - `keychain_send_create_encoded`, `keychain_send_edit` (advanced create/edit via `bw send create|edit`)
613
- - `keychain_send_remove_password`, `keychain_send_delete`
614
- - `keychain_receive` (receive shared Sends and download file Send bytes)
407
+ - `bw list items --search`, and therefore `keychain_search_items`, does not
408
+ reliably search inside custom field values
409
+ - SSH keys are stored as secure notes with standard fields until `bw` supports
410
+ native SSH key item creation
411
+ - high-risk `bw` features such as export/import are intentionally not exposed
412
+ - Vaultwarden report pages are not mirrored as MCP tools; the current
413
+ report-like helper is `keychain_get_exposed`
615
414
 
616
- Direct “bw get …” helpers:
415
+ ## Project Links
617
416
 
618
- - `keychain_get_username` (returns `{ kind:"username", value, revealed:true }`)
619
- - `keychain_get_password` / `keychain_get_totp` / `keychain_get_notes` (only return real values when `reveal: true`)
620
- - `keychain_get_uri`, `keychain_get_exposed`
621
- - `keychain_get_folder`, `keychain_get_collection`, `keychain_get_organization`, `keychain_get_org_collection`
622
- - `keychain_get_password_history` (only returns historic passwords when `reveal: true`)
417
+ - npm package: [`@icoretech/warden-mcp`](https://www.npmjs.com/package/@icoretech/warden-mcp)
418
+ - Docker image: [`ghcr.io/icoretech/warden-mcp`](https://ghcr.io/icoretech/warden-mcp)
419
+ - Changelog: [CHANGELOG.md](CHANGELOG.md)
420
+ - Security policy: [SECURITY.md](SECURITY.md)
421
+ - Threat model: [THREAT_MODEL.md](THREAT_MODEL.md)
422
+ - Repository guidance: [AGENTS.md](AGENTS.md)
623
423
 
624
- ## Known Limitations
424
+ ## Contributing
625
425
 
626
- - `bw list items --search` (and thus `keychain_search_items`) does not reliably search inside **custom field values**.
627
- - SSH keys are stored as secure notes in v1 (until `bw` supports native SSH key item creation).
628
- - High-risk CLI features are intentionally not exposed yet (export/import).
426
+ Issues and PRs are welcome. Run `npm run lint` and the relevant test command
427
+ before opening a PR; use `make test` when behavior depends on real Vaultwarden
428
+ or `bw` interaction.
629
429
 
630
- ## Contributing
430
+ ## License
631
431
 
632
- See `AGENTS.md` for repo guidelines, dev commands, and testing conventions.
432
+ [MIT](LICENSE)
@@ -1,5 +1,5 @@
1
1
  // src/bw/bwSession.ts
2
- import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
2
+ import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
3
3
  import { join } from 'node:path';
4
4
  import { isBwAuthSessionInvalidError, runBw } from './bwCli.js';
5
5
  import { Mutex } from './mutex.js';
@@ -7,9 +7,38 @@ const POST_LOGIN_UNLOCK_RETRY_ATTEMPTS = 20;
7
7
  const POST_LOGIN_UNLOCK_RETRY_DELAY_MS = 2_000;
8
8
  const PROCESS_LOCK_WAIT_MS = 100;
9
9
  const PROCESS_LOCK_TIMEOUT_MS = 90_000;
10
+ const PROCESS_LOCK_OWNER_FILE = 'owner.json';
10
11
  function sleep(ms) {
11
12
  return new Promise((resolve) => setTimeout(resolve, ms));
12
13
  }
14
+ function isProcessLockOwner(value) {
15
+ return (typeof value === 'object' &&
16
+ value !== null &&
17
+ 'pid' in value &&
18
+ 'createdAt' in value &&
19
+ typeof value.pid === 'number' &&
20
+ Number.isInteger(value.pid) &&
21
+ typeof value.createdAt === 'string');
22
+ }
23
+ function isProcessAlive(pid) {
24
+ if (pid <= 0)
25
+ return false;
26
+ try {
27
+ process.kill(pid, 0);
28
+ return true;
29
+ }
30
+ catch (error) {
31
+ if (!(error instanceof Error))
32
+ throw error;
33
+ return errorCode(error) !== 'ESRCH';
34
+ }
35
+ }
36
+ function errorCode(error) {
37
+ if (typeof error !== 'object' || error === null || !('code' in error)) {
38
+ return undefined;
39
+ }
40
+ return error.code;
41
+ }
13
42
  function requiredEnv(name) {
14
43
  const v = process.env[name];
15
44
  if (!v) {
@@ -99,7 +128,9 @@ export class BwSessionManager {
99
128
  try {
100
129
  await this.ensureUnlockedInternal();
101
130
  }
102
- catch {
131
+ catch (error) {
132
+ if (!(error instanceof Error))
133
+ throw error;
103
134
  // Keepalive is best-effort; tools will surface failures.
104
135
  }
105
136
  });
@@ -236,7 +267,9 @@ export class BwSessionManager {
236
267
  return base;
237
268
  }
238
269
  }
239
- catch {
270
+ catch (error) {
271
+ if (!(error instanceof Error))
272
+ throw error;
240
273
  // Fall back to the CLI if local state is absent or unreadable.
241
274
  }
242
275
  try {
@@ -419,12 +452,20 @@ export class BwSessionManager {
419
452
  while (true) {
420
453
  try {
421
454
  await mkdir(this.processLockDir);
455
+ try {
456
+ await this.writeProcessLockOwner();
457
+ }
458
+ catch (error) {
459
+ await rm(this.processLockDir, { recursive: true, force: true });
460
+ throw error;
461
+ }
422
462
  break;
423
463
  }
424
464
  catch (error) {
425
- const err = error;
426
- if (err?.code !== 'EEXIST')
465
+ if (errorCode(error) !== 'EEXIST')
427
466
  throw error;
467
+ if (await this.reclaimProcessAuthLockIfStale())
468
+ continue;
428
469
  if (Date.now() - startedAt >= PROCESS_LOCK_TIMEOUT_MS) {
429
470
  throw new Error(`Timed out waiting for process auth lock after ${PROCESS_LOCK_TIMEOUT_MS}ms`);
430
471
  }
@@ -438,6 +479,36 @@ export class BwSessionManager {
438
479
  await rm(this.processLockDir, { recursive: true, force: true }).catch(() => { });
439
480
  }
440
481
  }
482
+ async writeProcessLockOwner() {
483
+ const owner = {
484
+ pid: process.pid,
485
+ createdAt: new Date().toISOString(),
486
+ };
487
+ await writeFile(join(this.processLockDir, PROCESS_LOCK_OWNER_FILE), JSON.stringify(owner), 'utf8');
488
+ }
489
+ async reclaimProcessAuthLockIfStale() {
490
+ const ownerPath = join(this.processLockDir, PROCESS_LOCK_OWNER_FILE);
491
+ try {
492
+ const parsed = JSON.parse(await readFile(ownerPath, 'utf8'));
493
+ if (isProcessLockOwner(parsed) && !isProcessAlive(parsed.pid)) {
494
+ await rm(this.processLockDir, { recursive: true, force: true });
495
+ return true;
496
+ }
497
+ }
498
+ catch (error) {
499
+ if (!(error instanceof SyntaxError)) {
500
+ if (errorCode(error) !== 'ENOENT')
501
+ throw error;
502
+ }
503
+ }
504
+ const lockStats = await stat(this.processLockDir).catch(() => null);
505
+ if (lockStats &&
506
+ Date.now() - lockStats.mtimeMs >= PROCESS_LOCK_TIMEOUT_MS) {
507
+ await rm(this.processLockDir, { recursive: true, force: true });
508
+ return true;
509
+ }
510
+ return false;
511
+ }
441
512
  async ensureServerConfigured() {
442
513
  if (this.configuredHost === this.env.host)
443
514
  return;
@@ -456,7 +527,9 @@ export class BwSessionManager {
456
527
  this.configuredHost = this.env.host;
457
528
  return;
458
529
  }
459
- catch {
530
+ catch (error) {
531
+ if (!(error instanceof Error))
532
+ throw error;
460
533
  // If the CLI data is corrupt/out-of-sync, wiping config is the fastest recovery.
461
534
  }
462
535
  await this.resetCliProfile();
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "private": false,
3
3
  "name": "@icoretech/warden-mcp",
4
- "version": "0.2.28",
4
+ "version": "0.2.30",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "description": "Vaultwarden/Bitwarden MCP server backed by Bitwarden CLI (bw).",
@@ -44,24 +44,24 @@
44
44
  "lint": "biome check --write --assist-enabled=true . && tsc --noEmit"
45
45
  },
46
46
  "dependencies": {
47
- "@modelcontextprotocol/sdk": "^1.29.0",
47
+ "@modelcontextprotocol/sdk": "^1.30.0",
48
48
  "express": "^5.2.1",
49
49
  "zod": "^4.4.3"
50
50
  },
51
51
  "optionalDependencies": {
52
- "@bitwarden/cli": "2026.5.0"
52
+ "@bitwarden/cli": "2026.6.0"
53
53
  },
54
54
  "overrides": {
55
55
  "form-data": "4.0.6",
56
56
  "tmp": "0.2.7"
57
57
  },
58
58
  "devDependencies": {
59
- "@biomejs/biome": "^2.5.1",
59
+ "@biomejs/biome": "^2.5.6",
60
60
  "@types/express": "^5.0.6",
61
- "@types/node": "^25.9.4",
62
- "playwright": "1.61.0",
63
- "tsx": "^4.22.4",
64
- "typescript": "^6.0.3"
61
+ "@types/node": "^26.1.2",
62
+ "playwright": "1.62.0",
63
+ "tsx": "^4.23.1",
64
+ "typescript": "^7.0.2"
65
65
  },
66
66
  "publishConfig": {
67
67
  "registry": "https://registry.npmjs.org",