@icoretech/warden-mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,10 +1,14 @@
 # warden-mcp
 
+[![npm version](https://img.shields.io/npm/v/%40icoretech%2Fwarden-mcp?logo=npm)](https://www.npmjs.com/package/@icoretech/warden-mcp)
+[![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)
+[![license](https://img.shields.io/github/license/icoretech/warden-mcp)](LICENSE)
+
 Programmatic Vaultwarden/Bitwarden vault management over MCP (Model Context Protocol), backed by the official Bitwarden CLI (`bw`).
 
 This project exists to let agents and automation **create/search/read/update/move** vault items without re-implementing Bitwarden’s client-side crypto.
 
-Published package: `@icoretech/warden-mcp`
+Published package: [`@icoretech/warden-mcp`](https://www.npmjs.com/package/@icoretech/warden-mcp)
 
 ## Highlights
 
@@ -15,11 +19,306 @@ Published package: `@icoretech/warden-mcp`
 - Organization + collection helpers (list + org-collection CRUD)
 - Safe-by-default: item reads are **redacted** unless explicitly revealed; secret helper tools return `null` unless `reveal: true`
 
+## Runtime Requirement
+
+This package shells out to the official Bitwarden CLI, `bw`.
+
+Runtime resolution order:
+
+- `BW_BIN` if you set it explicitly
+- bundled `@bitwarden/cli` optional dependency if it is present
+- system `bw` from `PATH`
+
+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.
+
+Explicit fallback install:
+
+```bash
+npm install -g @bitwarden/cli
+```
+
+Or run with an explicit binary path:
+
+```bash
+BW_BIN=/absolute/path/to/bw npx -y @icoretech/warden-mcp
+```
+
+## Install And Run
+
+### Choose a transport
+
+- Use `--stdio` when you want a local MCP host to spawn `warden-mcp` directly with one fixed Bitwarden profile
+- 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
+
+### Local stdio mode
+
+```bash
+npx -y @icoretech/warden-mcp --stdio
+```
+
+For stdio mode, you must provide Bitwarden credentials up front via env vars:
+
+```bash
+BW_HOST=https://vaultwarden.example.com \
+BW_USER=user@example.com \
+BW_PASSWORD='your-master-password' \
+npx -y @icoretech/warden-mcp --stdio
+```
+
+API key login works too:
+
+```bash
+BW_HOST=https://vaultwarden.example.com \
+BW_CLIENTID=user.xxxxx \
+BW_CLIENTSECRET=xxxxx \
+BW_PASSWORD='your-master-password' \
+npx -y @icoretech/warden-mcp --stdio
+```
+
+### Shared HTTP mode
+
+Start one long-lived MCP server:
+
+```bash
+npx -y @icoretech/warden-mcp
+```
+
+Verify it is up:
+
+```bash
+curl -fsS http://localhost:3005/healthz
+```
+
+This mode is what makes `warden-mcp` different from a simple local wrapper:
+
+- the server stays stateless at the HTTP boundary
+- Bitwarden/Vaultwarden credentials are sent per request via `X-BW-*` headers
+- one running server can front different vault hosts or different identities without restarting
+- it fits shared-agent and gateway setups much better than per-client local processes
+
+### Global install
+
+```bash
+npm install -g @icoretech/warden-mcp
+warden-mcp
+```
+
+## Connect From MCP Hosts
+
+For local MCP hosts, stdio is the most portable option.
+
+```bash
+npx -y @icoretech/warden-mcp --stdio
+```
+
+The examples below use Bitwarden API-key auth. If you prefer username/password login, replace `BW_CLIENTID` + `BW_CLIENTSECRET` with `BW_USER`.
+
+### CLI-based hosts
+
+These hosts let you register `warden-mcp` directly from the command line:
+
+```bash
+# Codex
+codex mcp add warden \
+  --env BW_HOST=https://vaultwarden.example.com \
+  --env BW_CLIENTID=user.xxxxx \
+  --env BW_CLIENTSECRET=xxxxx \
+  --env BW_PASSWORD='your-master-password' \
+  -- npx -y @icoretech/warden-mcp --stdio
+
+# Claude Code
+claude mcp add-json warden '{"command":"npx","args":["-y","@icoretech/warden-mcp","--stdio"],"env":{"BW_HOST":"https://vaultwarden.example.com","BW_CLIENTID":"user.xxxxx","BW_CLIENTSECRET":"xxxxx","BW_PASSWORD":"your-master-password"}}'
+
+# Qwen Code
+qwen mcp add warden \
+  -e BW_HOST=https://vaultwarden.example.com \
+  -e BW_CLIENTID=user.xxxxx \
+  -e BW_CLIENTSECRET=xxxxx \
+  -e BW_PASSWORD=your-master-password \
+  npx -y @icoretech/warden-mcp --stdio
+```
+
+### JSON config hosts
+
+These hosts all use the same stdio payload shape. Only the config file location changes:
+
+- Codex: `~/.codex/config.toml`
+- Cursor: `~/.cursor/mcp.json` or `.cursor/mcp.json`
+- Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Qwen Code: `~/.qwen/settings.json` or `.qwen/settings.json`
+
+Shared JSON shape:
+
+```json
+{
+  "mcpServers": {
+    "warden": {
+      "command": "npx",
+      "args": ["-y", "@icoretech/warden-mcp", "--stdio"],
+      "env": {
+        "BW_HOST": "https://vaultwarden.example.com",
+        "BW_CLIENTID": "user.xxxxx",
+        "BW_CLIENTSECRET": "xxxxx",
+        "BW_PASSWORD": "your-master-password"
+      }
+    }
+  }
+}
+```
+
+Codex uses TOML instead of JSON:
+
+```toml
+[mcp_servers.warden]
+command = "npx"
+args = ["-y", "@icoretech/warden-mcp", "--stdio"]
+
+[mcp_servers.warden.env]
+BW_HOST = "https://vaultwarden.example.com"
+BW_CLIENTID = "user.xxxxx"
+BW_CLIENTSECRET = "xxxxx"
+BW_PASSWORD = "your-master-password"
+```
+
+### Windsurf
+
+Windsurf uses the same stdio idea but stores it in `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "warden": {
+      "command": "npx",
+      "args": ["-y", "@icoretech/warden-mcp", "--stdio"],
+      "env": {
+        "BW_HOST": "https://vaultwarden.example.com",
+        "BW_CLIENTID": "user.xxxxx",
+        "BW_CLIENTSECRET": "xxxxx",
+        "BW_PASSWORD": "your-master-password"
+      }
+    }
+  }
+}
+```
+
+### Shared HTTP connections
+
+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.
+
+Start the shared server:
+
+```bash
+npx -y @icoretech/warden-mcp
+```
+
+Every MCP request must include:
+
+- `X-BW-Host`
+- `X-BW-Password`
+- either `X-BW-ClientId` + `X-BW-ClientSecret`, or `X-BW-User`
+
+Example health check:
+
+```bash
+curl -fsS \
+  -H 'X-BW-Host: https://vaultwarden.example.com' \
+  -H 'X-BW-ClientId: user.xxxxx' \
+  -H 'X-BW-ClientSecret: xxxxx' \
+  -H 'X-BW-Password: your-master-password' \
+  http://localhost:3005/healthz
+```
+
+Example MCP endpoint:
+
+```text
+http://localhost:3005/sse?v=2
+```
+
+This shared-server mode is useful when:
+
+- one MCP gateway needs to front multiple Bitwarden profiles
+- you want to rotate vault credentials per request instead of per process
+- you are integrating from a custom client or agent host that can attach HTTP headers
+- you want one always-on service instead of each editor spawning its own `bw`-backed subprocess
+
+Client examples for shared HTTP mode:
+
+```bash
+# Claude Code
+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"}}'
+```
+
+```json
+// Cursor (~/.cursor/mcp.json)
+{
+  "mcpServers": {
+    "warden": {
+      "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"
+      }
+    }
+  }
+}
+```
+
+```json
+// Qwen Code (~/.qwen/settings.json)
+{
+  "mcpServers": {
+    "warden": {
+      "httpUrl": "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"
+      }
+    }
+  }
+}
+```
+
+```json
+// Windsurf (~/.codeium/windsurf/mcp_config.json)
+{
+  "mcpServers": {
+    "warden": {
+      "serverUrl": "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"
+      }
+    }
+  }
+}
+```
+
+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.
+
+### Verify bw is available
+
+```bash
+bw --version
+```
+
+If that fails after install, your environment likely skipped the optional `@bitwarden/cli` dependency. Install it explicitly:
+
+```bash
+npm install -g @bitwarden/cli
+```
+
 ## How It Works
 
 The server executes `bw` commands on your behalf:
 
-- Bitwarden/Vaultwarden connection + credentials are provided via **HTTP headers** per request.
+- In HTTP mode, Bitwarden/Vaultwarden connection + credentials are provided via **HTTP headers** per request.
+- In stdio mode, Bitwarden/Vaultwarden credentials are loaded once from `BW_*` env vars at startup.
 - The server maintains per-profile `bw` state under `KEYCHAIN_BW_HOME_ROOT` to avoid session/config clashes.
 - Writes can optionally call `bw sync` (internal; not exposed as an MCP tool).
 
@@ -64,7 +363,18 @@ Reveal rules:
 
 ## Quick Start
 
-### Docker Compose (recommended)
+### Minimal local run
+
+Run the published package in HTTP mode and verify the server is up:
+
+```bash
+npx -y @icoretech/warden-mcp
+curl -fsS http://localhost:3005/healthz
+```
+
+## Local Development
+
+### Docker Compose
 
 Starts a local Vaultwarden + HTTPS proxy (for `bw`), bootstraps a test user, and runs the MCP server.
 
@@ -86,7 +396,7 @@ Run session flood regression locally (guardrail sanity):
 npm run test:session-regression
 ```
 
-### Local Dev (host)
+### Local dev (host)
 
 ```bash
 npm install
@@ -94,13 +404,6 @@ cp .env.example .env
 npm run dev
 ```
 
-### Run via npx
-
-```bash
-npx -y @icoretech/warden-mcp
-npx -y @icoretech/warden-mcp --stdio
-```
-
 ## Tool Reference (v1)
 
 Vault/session:

package/dist/bw/bwSession.js

@@ -5,8 +5,12 @@ import { runBw } from './bwCli.js';
 import { Mutex } from './mutex.js';
 function requiredEnv(name) {
     const v = process.env[name];
-    if (!v)
-        throw new Error(`Missing required env var: ${name}`);
+    if (!v) {
+        throw new Error(`Missing required env var for stdio mode: ${name}. ` +
+            'For --stdio, set BW_HOST, BW_PASSWORD, and either ' +
+            'BW_CLIENTID+BW_CLIENTSECRET or BW_USER/BW_USERNAME. ' +
+            'For HTTP mode, omit --stdio and send X-BW-* headers per request.');
+    }
     return v;
 }
 export function readBwEnv() {

package/package.json

@@ -1,9 +1,20 @@
 {
   "private": false,
   "name": "@icoretech/warden-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
+  "license": "MIT",
   "description": "Vaultwarden/Bitwarden MCP server backed by Bitwarden CLI (bw).",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "bitwarden",
+    "vaultwarden",
+    "password-manager",
+    "secrets",
+    "automation",
+    "sse"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/icoretech/warden-mcp.git"
@@ -15,7 +26,12 @@
   "bin": {
     "warden-mcp": "bin/warden-mcp.js"
   },
-  "files": ["dist/", "bin/", "!dist/**/*.test.js", "!dist/integration/"],
+  "files": [
+    "dist/",
+    "bin/",
+    "!dist/**/*.test.js",
+    "!dist/integration/"
+  ],
   "scripts": {
     "dev": "tsx watch --clear-screen=false src/server.ts",
     "build": "tsc -p .",
@@ -26,18 +42,18 @@
     "lint": "biome check --write --assist-enabled=true . && tsc --noEmit"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "express": "^5.2.1",
-    "jose": "^6.1.3",
+    "jose": "^6.2.2",
     "zod": "^4.3.6"
   },
   "optionalDependencies": {
-    "@bitwarden/cli": "2026.1.0"
+    "@bitwarden/cli": "2026.2.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.15",
+    "@biomejs/biome": "^2.4.8",
     "@types/express": "^5.0.6",
-    "@types/node": "^25.2.3",
+    "@types/node": "^25.5.0",
     "playwright": "1.58.2",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
@@ -47,6 +63,6 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=24.14.0"
   }
 }