@rui.branco/1password-mcp 0.1.2 → 0.1.4

package/index.js

@@ -1,6 +1,17 @@
 #!/usr/bin/env node
 
-// Handle setup subcommand
+// ============================================================================
+// 1Password MCP Server
+//
+// Exposes 1Password vault/item operations as MCP tools for Claude Code. Uses
+// the official @1password/sdk with either a service-account token or desktop
+// app auth (delegating unlock to 1Password 8 via DesktopAuth).
+//
+// Multi-instance: several 1Password accounts can be configured; each tool
+// accepts an optional `instance` parameter to pick which one to hit.
+// ============================================================================
+
+// Handle `1password-mcp setup` subcommand
 if (process.argv[2] === "setup") {
   require("./setup.js");
   return;
@@ -22,7 +33,10 @@ const { spawn, execSync } = require("child_process");
 const PKG_VERSION = require("./package.json").version;
 const INTEGRATION_NAME = "1password-mcp";
 
-// Auto-update: check GitHub for new commits, install in background
+// ============================================================================
+// Auto-update — same pattern as jira-mcp: check GitHub for a newer commit on
+// every start, install in a detached background process if found.
+// ============================================================================
 const GITHUB_REPO = "rui-branco/1password-mcp";
 const INSTALLED_SHA_FILE = path.join(__dirname, ".installed-sha");
 try {
@@ -47,60 +61,99 @@ try {
     );
     child.unref();
   }
-} catch {}
+} catch {
+  /* offline or git not available — no-op */
+}
 
-// ============ CONFIG ============
+// ============================================================================
+// Config
+// ============================================================================
 
-const configDir = path.join(process.env.HOME, ".config/1password-mcp");
-const configPath = path.join(configDir, "config.json");
+const CONFIG_DIR = path.join(process.env.HOME, ".config/1password-mcp");
+const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 
-if (!fs.existsSync(configDir)) {
-  fs.mkdirSync(configDir, { recursive: true });
+function ensureConfigDir() {
+  if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { recursive: true });
 }
 
 function loadConfigFile() {
   try {
-    return JSON.parse(fs.readFileSync(configPath, "utf8"));
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
   } catch {
     return {};
   }
 }
 
 function saveConfigFile(cfg) {
-  fs.writeFileSync(configPath, JSON.stringify(cfg, null, 2));
+  ensureConfigDir();
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2));
   try {
-    fs.chmodSync(configPath, 0o600);
-  } catch {}
+    fs.chmodSync(CONFIG_PATH, 0o600);
+  } catch {
+    /* chmod can fail on non-POSIX filesystems — non-fatal */
+  }
 }
 
-const rawConfig = fs.existsSync(configPath) ? loadConfigFile() : { instances: [] };
+ensureConfigDir();
 
-let instances = (rawConfig.instances || []).map((i) => ({
-  name: i.name,
-  // "serviceAccount" (default, needs ops_ token) or "desktop" (uses 1Password 8 app biometric unlock)
-  authType: i.authType || (i.token ? "serviceAccount" : "desktop"),
-  token: i.token,
-  accountName: i.accountName,
-  description: i.description || "",
-}));
+/**
+ * Normalize a persisted config entry into the runtime instance shape.
+ * Accepts legacy records that only had a token and infers authType.
+ */
+function normalizeInstance(raw) {
+  return {
+    name: raw.name,
+    authType: raw.authType || (raw.token ? "serviceAccount" : "desktop"),
+    token: raw.token,
+    accountName: raw.accountName,
+    description: raw.description || "",
+  };
+}
 
-const defaultInstance =
-  (rawConfig.defaultInstance && instances.find((i) => i.name === rawConfig.defaultInstance)) ||
+const rawConfig = fs.existsSync(CONFIG_PATH)
+  ? loadConfigFile()
+  : { instances: [] };
+
+let instances = (rawConfig.instances || []).map(normalizeInstance);
+
+let defaultInstance =
+  (rawConfig.defaultInstance &&
+    instances.find((i) => i.name === rawConfig.defaultInstance)) ||
   instances[0] ||
   null;
 
+/**
+ * Resolve an instance by name, falling back to the default if the name is
+ * omitted or unknown. Returns null only when no instances are configured at all.
+ */
 function getInstanceByName(name) {
   if (!name) return defaultInstance;
   return instances.find((i) => i.name === name) || defaultInstance;
 }
 
-// ============ 1PASSWORD CLIENT ============
+// ============================================================================
+// 1Password SDK client
+// ============================================================================
 
-// Cache SDK clients per instance so we don't re-auth on every call. The SDK
-// client holds a WebAssembly runtime internally, so recreating it every call
-// would be wasteful.
+// Cache SDK clients per instance — createClient spins up a WASM runtime and
+// negotiates an auth session, so we want exactly one per process lifetime.
 const clientCache = new Map();
 
+function buildAuth(instance) {
+  if (instance.authType === "desktop") {
+    if (!instance.accountName) {
+      throw new Error(
+        `Instance "${instance.name}" is desktop-auth but has no accountName. Re-run setup.`,
+      );
+    }
+    return new sdk.DesktopAuth(instance.accountName);
+  }
+  if (!instance.token) {
+    throw new Error(`Instance "${instance.name}" has no service account token.`);
+  }
+  return instance.token;
+}
+
 async function getClient(instance) {
   if (!instance) {
     throw new Error(
@@ -109,23 +162,8 @@ async function getClient(instance) {
   }
   if (clientCache.has(instance.name)) return clientCache.get(instance.name);
 
-  let auth;
-  if (instance.authType === "desktop") {
-    if (!instance.accountName) {
-      throw new Error(
-        `Instance "${instance.name}" is desktop-auth but has no accountName. Re-run setup and provide your 1Password account (e.g. "my.1password.com" or "my").`,
-      );
-    }
-    auth = new sdk.DesktopAuth(instance.accountName);
-  } else {
-    if (!instance.token) {
-      throw new Error(`Instance "${instance.name}" has no service account token.`);
-    }
-    auth = instance.token;
-  }
-
   const client = await sdk.createClient({
-    auth,
+    auth: buildAuth(instance),
     integrationName: INTEGRATION_NAME,
     integrationVersion: `v${PKG_VERSION}`,
   });
@@ -137,37 +175,54 @@ function invalidateClient(name) {
   clientCache.delete(name);
 }
 
-// ============ HELPERS ============
+// ============================================================================
+// Helpers — vault/item resolution, redaction, formatting
+// ============================================================================
+
+async function collect(asyncIterable) {
+  const out = [];
+  for await (const x of asyncIterable) out.push(x);
+  return out;
+}
 
-// Pick a vault by id OR by title (case-insensitive exact match, then prefix).
+/**
+ * Resolve a vault from a reference that may be an id, exact title (case-insensitive),
+ * or prefix of a title. Returns null when nothing matches.
+ */
 async function resolveVault(client, vaultRef) {
   if (!vaultRef) return null;
-  const vaults = [];
-  for await (const v of await client.vaults.list()) vaults.push(v);
+  const vaults = await collect(await client.vaults.list());
   const byId = vaults.find((v) => v.id === vaultRef);
   if (byId) return byId;
   const lower = String(vaultRef).toLowerCase();
-  const exact = vaults.find((v) => (v.title || "").toLowerCase() === lower);
-  if (exact) return exact;
-  const prefix = vaults.find((v) => (v.title || "").toLowerCase().startsWith(lower));
-  if (prefix) return prefix;
-  return null;
+  return (
+    vaults.find((v) => (v.title || "").toLowerCase() === lower) ||
+    vaults.find((v) => (v.title || "").toLowerCase().startsWith(lower)) ||
+    null
+  );
 }
 
+/**
+ * Same strategy as resolveVault but for items inside a specific vault.
+ */
 async function resolveItem(client, vault, itemRef) {
   if (!itemRef) return null;
-  const items = [];
-  for await (const it of await client.items.list(vault.id)) items.push(it);
+  const items = await collect(await client.items.list(vault.id));
   const byId = items.find((i) => i.id === itemRef);
   if (byId) return byId;
   const lower = String(itemRef).toLowerCase();
-  const exact = items.find((i) => (i.title || "").toLowerCase() === lower);
-  if (exact) return exact;
-  const prefix = items.find((i) => (i.title || "").toLowerCase().startsWith(lower));
-  if (prefix) return prefix;
-  return null;
+  return (
+    items.find((i) => (i.title || "").toLowerCase() === lower) ||
+    items.find((i) => (i.title || "").toLowerCase().startsWith(lower)) ||
+    null
+  );
 }
 
+/**
+ * Shape a single 1Password field for output. Concealed and TOTP values are
+ * replaced with "[REDACTED]" unless includeConcealed=true. OTP codes are only
+ * surfaced when concealed values are revealed.
+ */
 function redactField(field, includeConcealed) {
   const out = {
     id: field.id,
@@ -178,8 +233,13 @@ function redactField(field, includeConcealed) {
   const isSecret = field.fieldType === "Concealed" || field.fieldType === "Totp";
   if (!isSecret || includeConcealed) {
     out.value = field.value;
-    if (field.details && field.details.type === "Otp" && field.details.content) {
-      out.otp = field.details.content.code || undefined;
+    if (
+      field.details &&
+      field.details.type === "Otp" &&
+      field.details.content &&
+      field.details.content.code
+    ) {
+      out.otp = field.details.content.code;
     }
   } else {
     out.value = "[REDACTED]";
@@ -187,6 +247,10 @@ function redactField(field, includeConcealed) {
   return out;
 }
 
+/**
+ * Flatten a full 1Password item (as returned by client.items.get) into a
+ * stable JSON shape that's safe to display to the model.
+ */
 function formatItem(item, includeConcealed) {
   return {
     id: item.id,
@@ -194,682 +258,894 @@ function formatItem(item, includeConcealed) {
     category: item.category,
     vaultId: item.vaultId,
     tags: item.tags || [],
-    websites: (item.websites || []).map((w) => ({ url: w.url, label: w.label })),
+    websites: (item.websites || []).map((w) => ({
+      url: w.url,
+      label: w.label,
+    })),
     fields: (item.fields || []).map((f) => redactField(f, includeConcealed)),
     sections: (item.sections || []).map((s) => ({ id: s.id, title: s.title })),
   };
 }
 
-// ============ MCP SERVER ============
+// ============================================================================
+// Tool definitions (exposed via tools/list)
+// ============================================================================
 
-const server = new Server(
-  { name: INTEGRATION_NAME, version: PKG_VERSION },
-  { capabilities: { tools: {} } },
-);
-
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  return {
-    tools: [
-      {
-        name: "op_list_instances",
-        description:
-          "List configured 1Password instances (service accounts). Tokens are never returned.",
-        inputSchema: { type: "object", properties: {}, required: [] },
+const TOOL_DEFINITIONS = [
+  {
+    name: "op_list_instances",
+    description:
+      "List configured 1Password instances (service accounts or desktop). Tokens are never returned.",
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "op_add_instance",
+    description:
+      "Add or update a 1Password instance. Two auth modes: (1) 'serviceAccount' — provide token (ops_...). (2) 'desktop' — provide accountName (e.g. 'my.1password.com'); auth is delegated to the installed 1Password 8 desktop app via biometric unlock. Config is stored at ~/.config/1password-mcp/config.json with 0600 permissions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Unique name (e.g., 'work', 'personal').",
+        },
+        authType: {
+          type: "string",
+          description: "'serviceAccount' (default) or 'desktop'.",
+        },
+        token: {
+          type: "string",
+          description:
+            "Service account token (ops_...) — required for authType=serviceAccount.",
+        },
+        accountName: {
+          type: "string",
+          description:
+            "1Password account (e.g. 'my.1password.com' or shorthand) — required for authType=desktop. Uses the logged-in 1Password 8 app.",
+        },
+        description: {
+          type: "string",
+          description: "Optional human-readable description.",
+        },
+        setDefault: {
+          type: "boolean",
+          description: "Set this instance as the default (default: false).",
+        },
       },
-      {
-        name: "op_add_instance",
-        description:
-          "Add or update a 1Password instance. Two auth modes: (1) 'serviceAccount' — provide token (ops_...). (2) 'desktop' — provide accountName (e.g. 'my.1password.com'); auth is delegated to the installed 1Password 8 desktop app via biometric unlock. Config is stored at ~/.config/1password-mcp/config.json with 0600 permissions.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            name: { type: "string", description: "Unique name (e.g., 'work', 'personal')." },
-            authType: {
-              type: "string",
-              description: "'serviceAccount' (default) or 'desktop'.",
-            },
-            token: {
-              type: "string",
-              description: "Service account token (ops_...) — required for authType=serviceAccount.",
-            },
-            accountName: {
-              type: "string",
-              description: "1Password account (e.g. 'my.1password.com' or shorthand) — required for authType=desktop. Uses the logged-in 1Password 8 app.",
-            },
-            description: { type: "string", description: "Optional human-readable description." },
-            setDefault: {
-              type: "boolean",
-              description: "Set this instance as the default (default: false).",
-            },
-          },
-          required: ["name"],
+      required: ["name"],
+    },
+  },
+  {
+    name: "op_remove_instance",
+    description:
+      "Remove a 1Password instance by name. Cannot remove the last one.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Instance name to remove." },
+      },
+      required: ["name"],
+    },
+  },
+  {
+    name: "op_list_vaults",
+    description:
+      "List all vaults visible to the given instance's 1Password account.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        instance: {
+          type: "string",
+          description: "Instance name. Uses default if omitted.",
         },
       },
-      {
-        name: "op_remove_instance",
-        description: "Remove a 1Password instance by name. Cannot remove the last one.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            name: { type: "string", description: "Instance name to remove." },
-          },
-          required: ["name"],
+      required: [],
+    },
+  },
+  {
+    name: "op_list_items",
+    description:
+      "List items in a vault. `vault` accepts a vault id or title (case-insensitive exact, then prefix).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        vault: { type: "string", description: "Vault id or title." },
+        instance: {
+          type: "string",
+          description: "Instance name. Uses default if omitted.",
         },
       },
-      {
-        name: "op_list_vaults",
-        description: "List all vaults visible to the given instance's service account.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            instance: { type: "string", description: "Instance name. Uses default if omitted." },
-          },
-          required: [],
+      required: ["vault"],
+    },
+  },
+  {
+    name: "op_search_items",
+    description:
+      "Search items by title across vaults. When the user asks for a specific credential by name (e.g. 'give me the wifi password', 'what's my GitHub login'), call this with `reveal: true` to get the password/credential values back in a single call — no follow-up op_get_item needed. If `vault` is omitted, searches every vault the account can see. When there are 1–5 matches with reveal=true, return all of them; the user already consented to seeing concealed values by asking for them.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Case-insensitive substring of the item title.",
+        },
+        vault: {
+          type: "string",
+          description: "Optional vault id or title to scope the search.",
+        },
+        limit: {
+          type: "number",
+          description: "Max results (default 25, or 5 when reveal=true to avoid fetching too many items).",
+        },
+        reveal: {
+          type: "boolean",
+          description:
+            "If true, fetch each match's full item and return concealed field values (passwords, TOTPs) in cleartext. Use this when the user is asking for a credential by name — one call gets search + retrieval + reveal. Defaults to false.",
+        },
+        instance: {
+          type: "string",
+          description: "Instance name. Uses default if omitted.",
         },
       },
-      {
-        name: "op_list_items",
-        description:
-          "List items in a vault. `vault` accepts a vault id or title (case-insensitive exact, then prefix).",
-        inputSchema: {
-          type: "object",
-          properties: {
-            vault: { type: "string", description: "Vault id or title." },
-            instance: { type: "string", description: "Instance name. Uses default if omitted." },
-          },
-          required: ["vault"],
+      required: ["query"],
+    },
+  },
+  {
+    name: "op_get_item",
+    description:
+      "Fetch a full item with all fields. By default concealed fields (passwords, TOTP) are redacted; set includeConcealed=true to return them in cleartext. `item` and `vault` accept ids or titles.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        vault: { type: "string", description: "Vault id or title." },
+        item: { type: "string", description: "Item id or title." },
+        includeConcealed: {
+          type: "boolean",
+          description: "Return concealed values in cleartext (default: false).",
+        },
+        instance: {
+          type: "string",
+          description: "Instance name. Uses default if omitted.",
         },
       },
-      {
-        name: "op_search_items",
-        description:
-          "Search items by title across vaults. If `vault` is omitted, searches every vault the service account can see.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            query: { type: "string", description: "Case-insensitive substring of the item title." },
-            vault: { type: "string", description: "Optional vault id or title to scope the search." },
-            limit: { type: "number", description: "Max results (default 25)." },
-            instance: { type: "string", description: "Instance name. Uses default if omitted." },
-          },
-          required: ["query"],
+      required: ["vault", "item"],
+    },
+  },
+  {
+    name: "op_get_secret",
+    description:
+      "Resolve a 1Password secret reference (op://vault/item/field) and return the value.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        reference: {
+          type: "string",
+          description: "Secret reference like 'op://Private/GitHub/password'.",
+        },
+        instance: {
+          type: "string",
+          description: "Instance name. Uses default if omitted.",
         },
       },
-      {
-        name: "op_get_item",
-        description:
-          "Fetch a full item with all fields. By default concealed fields (passwords, TOTP) are redacted; set includeConcealed=true to return them in cleartext. `item` and `vault` accept ids or titles.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            vault: { type: "string", description: "Vault id or title." },
-            item: { type: "string", description: "Item id or title." },
-            includeConcealed: {
-              type: "boolean",
-              description: "Return concealed values in cleartext (default: false).",
-            },
-            instance: { type: "string", description: "Instance name. Uses default if omitted." },
-          },
-          required: ["vault", "item"],
+      required: ["reference"],
+    },
+  },
+  {
+    name: "op_generate_password",
+    description:
+      "Generate a password using 1Password's generator (Random / Memorable / Pin). Does not talk to the account.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: {
+          type: "string",
+          description: "'Random' (default), 'Memorable', or 'Pin'.",
+        },
+        length: {
+          type: "number",
+          description: "Length for Random/Pin (default 20/8).",
+        },
+        includeDigits: {
+          type: "boolean",
+          description: "Random only (default true).",
+        },
+        includeSymbols: {
+          type: "boolean",
+          description: "Random only (default true).",
+        },
+        wordCount: {
+          type: "number",
+          description: "Memorable only (default 5).",
+        },
+        capitalize: {
+          type: "boolean",
+          description: "Memorable only (default true).",
         },
       },
-      {
-        name: "op_get_secret",
-        description:
-          "Resolve a 1Password secret reference (op://vault/item/field) and return the value.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            reference: {
-              type: "string",
-              description: "Secret reference like 'op://Private/GitHub/password'.",
+      required: [],
+    },
+  },
+  {
+    name: "op_create_item",
+    description:
+      "Create a new item in a vault. Fields is an array of { title, type, value, sectionId? }. Type is Text | Concealed | Totp | Email | Url | Phone.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        vault: { type: "string", description: "Vault id or title." },
+        title: { type: "string", description: "Item title." },
+        category: {
+          type: "string",
+          description:
+            "Item category (default: Login). One of: Login, SecureNote, Password, ApiCredentials, Database, Server, Email, Identity, CreditCard, etc.",
+        },
+        fields: {
+          type: "array",
+          description:
+            "Field definitions: [{ title, type, value, sectionId? }].",
+          items: {
+            type: "object",
+            properties: {
+              title: { type: "string" },
+              type: { type: "string" },
+              value: { type: "string" },
+              sectionId: { type: "string" },
             },
-            instance: { type: "string", description: "Instance name. Uses default if omitted." },
+            required: ["title", "type", "value"],
           },
-          required: ["reference"],
         },
-      },
-      {
-        name: "op_generate_password",
-        description:
-          "Generate a password using 1Password's generator (Random / Memorable / Pin). Does not talk to the account.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            type: {
-              type: "string",
-              description: "'Random' (default), 'Memorable', or 'Pin'.",
+        tags: { type: "array", items: { type: "string" } },
+        websites: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              url: { type: "string" },
+              label: { type: "string" },
             },
-            length: { type: "number", description: "Length for Random/Pin (default 20/8)." },
-            includeDigits: { type: "boolean", description: "Random only (default true)." },
-            includeSymbols: { type: "boolean", description: "Random only (default true)." },
-            wordCount: { type: "number", description: "Memorable only (default 5)." },
-            capitalize: { type: "boolean", description: "Memorable only (default true)." },
+            required: ["url"],
           },
-          required: [],
+        },
+        notes: {
+          type: "string",
+          description:
+            "Optional notes (stored as a Text field called 'notesPlain').",
+        },
+        instance: {
+          type: "string",
+          description: "Instance name. Uses default if omitted.",
         },
       },
-      {
-        name: "op_create_item",
-        description:
-          "Create a new item in a vault. Fields is an array of { title, type, value, sectionId? }. Type is Text | Concealed | Totp | Email | Url | Phone.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            vault: { type: "string", description: "Vault id or title." },
-            title: { type: "string", description: "Item title." },
-            category: {
-              type: "string",
-              description:
-                "Item category (default: Login). One of: Login, SecureNote, Password, ApiCredentials, Database, Server, Email, Identity, CreditCard, etc.",
-            },
-            fields: {
-              type: "array",
-              description: "Field definitions: [{ title, type, value, sectionId? }].",
-              items: {
-                type: "object",
-                properties: {
-                  title: { type: "string" },
-                  type: { type: "string" },
-                  value: { type: "string" },
-                  sectionId: { type: "string" },
-                },
-                required: ["title", "type", "value"],
-              },
-            },
-            tags: { type: "array", items: { type: "string" } },
-            websites: {
-              type: "array",
-              items: {
-                type: "object",
-                properties: {
-                  url: { type: "string" },
-                  label: { type: "string" },
-                },
-                required: ["url"],
-              },
+      required: ["vault", "title"],
+    },
+  },
+  {
+    name: "op_update_item",
+    description:
+      "Update an existing item. Patch fields by title — e.g. to change the password on 'GitHub', pass fields: [{title: 'password', value: 'new-pwd'}]. To add a new field, include its type. Omitting fields leaves them untouched. Can also rename the item (title) or replace its tags.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        vault: { type: "string", description: "Vault id or title." },
+        item: { type: "string", description: "Item id or title to update." },
+        title: { type: "string", description: "New title (optional)." },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Replace the item's tag list (optional).",
+        },
+        fields: {
+          type: "array",
+          description:
+            "Field patches: [{title, value, type?, sectionId?}]. Existing fields are matched by title (case-insensitive) and their values replaced. New fields require `type`.",
+          items: {
+            type: "object",
+            properties: {
+              title: { type: "string" },
+              value: { type: "string" },
+              type: { type: "string" },
+              sectionId: { type: "string" },
             },
-            notes: { type: "string", description: "Optional notes (stored as a Text field called 'notesPlain')." },
-            instance: { type: "string", description: "Instance name. Uses default if omitted." },
+            required: ["title", "value"],
           },
-          required: ["vault", "title"],
+        },
+        instance: {
+          type: "string",
+          description: "Instance name. Uses default if omitted.",
         },
       },
-      {
-        name: "op_delete_item",
-        description: "Delete an item by vault + item reference.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            vault: { type: "string", description: "Vault id or title." },
-            item: { type: "string", description: "Item id or title." },
-            instance: { type: "string", description: "Instance name. Uses default if omitted." },
-          },
-          required: ["vault", "item"],
+      required: ["vault", "item"],
+    },
+  },
+  {
+    name: "op_update_vault",
+    description:
+      "Update a vault's title and/or description. Pass at least one of them.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        vault: { type: "string", description: "Vault id or title." },
+        title: { type: "string", description: "New title (optional)." },
+        description: {
+          type: "string",
+          description: "New description (optional).",
+        },
+        instance: {
+          type: "string",
+          description: "Instance name. Uses default if omitted.",
         },
       },
-      {
-        name: "op_create_vault",
-        description: "Create a new vault.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            title: { type: "string", description: "Vault title." },
-            description: { type: "string", description: "Optional description." },
-            instance: { type: "string", description: "Instance name. Uses default if omitted." },
-          },
-          required: ["title"],
+      required: ["vault"],
+    },
+  },
+  {
+    name: "op_delete_item",
+    description: "Delete an item by vault + item reference.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        vault: { type: "string", description: "Vault id or title." },
+        item: { type: "string", description: "Item id or title." },
+        instance: {
+          type: "string",
+          description: "Instance name. Uses default if omitted.",
         },
       },
-      {
-        name: "op_delete_vault",
-        description: "Delete a vault by id or title.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            vault: { type: "string", description: "Vault id or title." },
-            instance: { type: "string", description: "Instance name. Uses default if omitted." },
-          },
-          required: ["vault"],
+      required: ["vault", "item"],
+    },
+  },
+  {
+    name: "op_create_vault",
+    description: "Create a new vault.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "Vault title." },
+        description: {
+          type: "string",
+          description: "Optional description.",
+        },
+        instance: {
+          type: "string",
+          description: "Instance name. Uses default if omitted.",
         },
       },
-    ],
-  };
-});
+      required: ["title"],
+    },
+  },
+  {
+    name: "op_delete_vault",
+    description: "Delete a vault by id or title.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        vault: { type: "string", description: "Vault id or title." },
+        instance: {
+          type: "string",
+          description: "Instance name. Uses default if omitted.",
+        },
+      },
+      required: ["vault"],
+    },
+  },
+];
 
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
+// ============================================================================
+// Handlers
+//
+// Each handler is keyed by tool name and receives the tool arguments. It
+// should return a plain string (rendered as text content by the dispatcher)
+// or throw on failure. The dispatcher handles MCP wrapping and error shape.
+// ============================================================================
 
-  try {
-    if (name === "op_list_instances") {
-      if (instances.length === 0) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "No instances configured. Run `1password-mcp setup` or call op_add_instance.",
-            },
-          ],
-        };
-      }
-      const def = defaultInstance?.name;
-      let text = `# 1Password Instances (${instances.length})\n\n`;
-      for (const inst of instances) {
-        const isDefault = inst.name === def ? " **(default)**" : "";
-        const desc = inst.description ? ` - ${inst.description}` : "";
-        const auth =
-          inst.authType === "desktop"
-            ? ` (desktop: ${inst.accountName})`
-            : " (serviceAccount)";
-        text += `- **${inst.name}**${isDefault}${auth}${desc}\n`;
-      }
-      return { content: [{ type: "text", text }] };
+async function addInstanceHandler(args) {
+  const instName = args.name.trim();
+  const authType = args.authType || (args.token ? "serviceAccount" : "desktop");
+
+  if (authType === "serviceAccount") {
+    if (!args.token) {
+      throw new Error("serviceAccount authType requires a token.");
     }
+    if (!/^ops_[A-Za-z0-9_\-]+/.test(args.token)) {
+      throw new Error(
+        "Token does not look like a 1Password service account token (expected prefix 'ops_').",
+      );
+    }
+  } else if (authType === "desktop") {
+    if (!args.accountName) {
+      throw new Error(
+        "desktop authType requires accountName (e.g. 'my.1password.com').",
+      );
+    }
+  } else {
+    throw new Error(`Unknown authType "${authType}".`);
+  }
 
-    if (name === "op_add_instance") {
-      const instName = args.name.trim();
-      const authType = args.authType || (args.token ? "serviceAccount" : "desktop");
-
-      if (authType === "serviceAccount") {
-        if (!args.token) {
-          return {
-            content: [{ type: "text", text: "serviceAccount authType requires a token." }],
-            isError: true,
-          };
-        }
-        if (!/^ops_[A-Za-z0-9_\-]+/.test(args.token)) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "Token does not look like a 1Password service account token (expected prefix 'ops_').",
-              },
-            ],
-            isError: true,
-          };
-        }
-      } else if (authType === "desktop") {
-        if (!args.accountName) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "desktop authType requires accountName (e.g. 'my.1password.com').",
-              },
-            ],
-            isError: true,
-          };
-        }
-      } else {
-        return {
-          content: [{ type: "text", text: `Unknown authType "${authType}".` }],
-          isError: true,
-        };
-      }
+  // Validate by creating a client and listing one vault.
+  const probeAuth =
+    authType === "desktop" ? new sdk.DesktopAuth(args.accountName) : args.token;
+  const tempClient = await sdk.createClient({
+    auth: probeAuth,
+    integrationName: INTEGRATION_NAME,
+    integrationVersion: `v${PKG_VERSION}`,
+  });
+  const probe = [];
+  for await (const v of await tempClient.vaults.list()) {
+    probe.push(v);
+    if (probe.length >= 1) break;
+  }
 
-      // Validate by creating a client and listing one vault.
-      try {
-        const probeAuth =
-          authType === "desktop"
-            ? new sdk.DesktopAuth(args.accountName)
-            : args.token;
-        const tempClient = await sdk.createClient({
-          auth: probeAuth,
-          integrationName: INTEGRATION_NAME,
-          integrationVersion: `v${PKG_VERSION}`,
-        });
-        const probe = [];
-        for await (const v of await tempClient.vaults.list()) {
-          probe.push(v);
-          if (probe.length >= 1) break;
-        }
-      } catch (e) {
-        return {
-          content: [{ type: "text", text: `Auth validation failed: ${e.message}` }],
-          isError: true,
-        };
-      }
+  const newInst = {
+    name: instName,
+    authType,
+    token: authType === "serviceAccount" ? args.token : undefined,
+    accountName: authType === "desktop" ? args.accountName : undefined,
+    description: args.description || "",
+  };
+  const existingIdx = instances.findIndex((i) => i.name === instName);
+  if (existingIdx >= 0) instances[existingIdx] = newInst;
+  else instances.push(newInst);
+  invalidateClient(instName);
 
-      const newInst = {
-        name: instName,
-        authType,
-        token: authType === "serviceAccount" ? args.token : undefined,
-        accountName: authType === "desktop" ? args.accountName : undefined,
-        description: args.description || "",
-      };
-      const existingIdx = instances.findIndex((i) => i.name === instName);
-      if (existingIdx >= 0) instances[existingIdx] = newInst;
-      else instances.push(newInst);
-      invalidateClient(instName);
-
-      const savedConfig = loadConfigFile();
-      if (!savedConfig.instances) savedConfig.instances = [];
-      const savedIdx = savedConfig.instances.findIndex((i) => i.name === instName);
-      const toSave = { name: instName, authType };
-      if (authType === "serviceAccount") toSave.token = args.token;
-      if (authType === "desktop") toSave.accountName = args.accountName;
-      if (args.description) toSave.description = args.description;
-      if (savedIdx >= 0) savedConfig.instances[savedIdx] = toSave;
-      else savedConfig.instances.push(toSave);
-      if (args.setDefault || !savedConfig.defaultInstance) {
-        savedConfig.defaultInstance = instName;
-      }
-      saveConfigFile(savedConfig);
+  const savedConfig = loadConfigFile();
+  if (!savedConfig.instances) savedConfig.instances = [];
+  const savedIdx = savedConfig.instances.findIndex((i) => i.name === instName);
+  const toSave = { name: instName, authType };
+  if (authType === "serviceAccount") toSave.token = args.token;
+  if (authType === "desktop") toSave.accountName = args.accountName;
+  if (args.description) toSave.description = args.description;
+  if (savedIdx >= 0) savedConfig.instances[savedIdx] = toSave;
+  else savedConfig.instances.push(toSave);
+  if (args.setDefault || !savedConfig.defaultInstance) {
+    savedConfig.defaultInstance = instName;
+    defaultInstance = newInst;
+  }
+  saveConfigFile(savedConfig);
 
-      return {
-        content: [
-          {
-            type: "text",
-            text: `${existingIdx >= 0 ? "Updated" : "Added"} instance "${instName}" (${authType}).${args.setDefault ? " Set as default." : ""}`,
-          },
-        ],
-      };
-    }
+  const verb = existingIdx >= 0 ? "Updated" : "Added";
+  const suffix = args.setDefault ? " Set as default." : "";
+  return `${verb} instance "${instName}" (${authType}).${suffix}`;
+}
 
-    if (name === "op_remove_instance") {
-      if (instances.length <= 1) {
-        return {
-          content: [{ type: "text", text: "Cannot remove the last remaining instance." }],
-          isError: true,
-        };
-      }
-      const idx = instances.findIndex((i) => i.name === args.name);
-      if (idx < 0) {
-        return {
-          content: [{ type: "text", text: `Instance "${args.name}" not found.` }],
-          isError: true,
-        };
-      }
-      instances.splice(idx, 1);
-      invalidateClient(args.name);
-      const savedConfig = loadConfigFile();
-      if (savedConfig.instances) {
-        savedConfig.instances = savedConfig.instances.filter((i) => i.name !== args.name);
-        if (savedConfig.defaultInstance === args.name) {
-          savedConfig.defaultInstance = savedConfig.instances[0]?.name || null;
-        }
-        saveConfigFile(savedConfig);
-      }
-      return { content: [{ type: "text", text: `Removed instance "${args.name}".` }] };
-    }
+async function removeInstanceHandler(args) {
+  if (instances.length <= 1) {
+    throw new Error("Cannot remove the last remaining instance.");
+  }
+  const idx = instances.findIndex((i) => i.name === args.name);
+  if (idx < 0) throw new Error(`Instance "${args.name}" not found.`);
 
-    if (name === "op_list_vaults") {
-      const inst = getInstanceByName(args.instance);
-      const client = await getClient(inst);
-      const vaults = [];
-      for await (const v of await client.vaults.list()) vaults.push(v);
-      if (vaults.length === 0) {
-        return { content: [{ type: "text", text: "No vaults visible to this service account." }] };
-      }
-      let text = `# Vaults (${vaults.length})\n\n`;
-      for (const v of vaults) text += `- **${v.title}** (id: ${v.id})\n`;
-      return { content: [{ type: "text", text }] };
-    }
+  instances.splice(idx, 1);
+  invalidateClient(args.name);
 
-    if (name === "op_list_items") {
-      const inst = getInstanceByName(args.instance);
-      const client = await getClient(inst);
-      const vault = await resolveVault(client, args.vault);
-      if (!vault) {
-        return {
-          content: [{ type: "text", text: `Vault "${args.vault}" not found.` }],
-          isError: true,
-        };
-      }
-      const items = [];
-      for await (const it of await client.items.list(vault.id)) items.push(it);
-      if (items.length === 0) {
-        return { content: [{ type: "text", text: `No items in vault "${vault.title}".` }] };
-      }
-      let text = `# Items in ${vault.title} (${items.length})\n\n`;
-      for (const it of items) {
-        text += `- **${it.title}** (id: ${it.id}, category: ${it.category})\n`;
-      }
-      return { content: [{ type: "text", text }] };
+  const savedConfig = loadConfigFile();
+  if (savedConfig.instances) {
+    savedConfig.instances = savedConfig.instances.filter(
+      (i) => i.name !== args.name,
+    );
+    if (savedConfig.defaultInstance === args.name) {
+      savedConfig.defaultInstance = savedConfig.instances[0]?.name || null;
+      defaultInstance = instances[0] || null;
     }
+    saveConfigFile(savedConfig);
+  }
+  return `Removed instance "${args.name}".`;
+}
 
-    if (name === "op_search_items") {
-      const inst = getInstanceByName(args.instance);
-      const client = await getClient(inst);
-      const limit = args.limit || 25;
-      const q = String(args.query).toLowerCase();
-
-      let targetVaults = [];
-      if (args.vault) {
-        const v = await resolveVault(client, args.vault);
-        if (!v) {
-          return {
-            content: [{ type: "text", text: `Vault "${args.vault}" not found.` }],
-            isError: true,
-          };
-        }
-        targetVaults = [v];
-      } else {
-        for await (const v of await client.vaults.list()) targetVaults.push(v);
-      }
+function listInstancesHandler() {
+  if (instances.length === 0) {
+    return "No instances configured. Run `1password-mcp setup` or call op_add_instance.";
+  }
+  const def = defaultInstance?.name;
+  const lines = instances.map((inst) => {
+    const isDefault = inst.name === def ? " **(default)**" : "";
+    const desc = inst.description ? ` - ${inst.description}` : "";
+    const auth =
+      inst.authType === "desktop"
+        ? ` (desktop: ${inst.accountName})`
+        : " (serviceAccount)";
+    return `- **${inst.name}**${isDefault}${auth}${desc}`;
+  });
+  return `# 1Password Instances (${instances.length})\n\n${lines.join("\n")}`;
+}
 
-      const hits = [];
-      for (const v of targetVaults) {
-        for await (const it of await client.items.list(v.id)) {
-          if ((it.title || "").toLowerCase().includes(q)) {
-            hits.push({ ...it, _vaultTitle: v.title });
-            if (hits.length >= limit) break;
-          }
-        }
-        if (hits.length >= limit) break;
-      }
+async function listVaultsHandler(args) {
+  const client = await getClient(getInstanceByName(args.instance));
+  const vaults = await collect(await client.vaults.list());
+  if (vaults.length === 0) {
+    return "No vaults visible to this instance.";
+  }
+  const lines = vaults.map((v) => `- **${v.title}** (id: ${v.id})`);
+  return `# Vaults (${vaults.length})\n\n${lines.join("\n")}`;
+}
 
-      if (hits.length === 0) {
-        return {
-          content: [{ type: "text", text: `No items matched "${args.query}".` }],
-        };
-      }
-      let text = `# Search: "${args.query}" (${hits.length})\n\n`;
-      for (const it of hits) {
-        text += `- **${it.title}** (id: ${it.id}, vault: ${it._vaultTitle}, category: ${it.category})\n`;
+async function listItemsHandler(args) {
+  const client = await getClient(getInstanceByName(args.instance));
+  const vault = await resolveVault(client, args.vault);
+  if (!vault) throw new Error(`Vault "${args.vault}" not found.`);
+
+  const items = await collect(await client.items.list(vault.id));
+  if (items.length === 0) {
+    return `No items in vault "${vault.title}".`;
+  }
+  const lines = items.map(
+    (i) => `- **${i.title}** (id: ${i.id}, category: ${i.category})`,
+  );
+  return `# Items in ${vault.title} (${items.length})\n\n${lines.join("\n")}`;
+}
+
+/**
+ * Core search implementation — pulled out of the handler so it can be unit
+ * tested with a fake client. Accepts an already-resolved client.
+ */
+async function searchItems(client, { query, vault, reveal, limit }) {
+  const wantReveal = !!reveal;
+  const max = limit || (wantReveal ? 5 : 25);
+  const q = String(query).toLowerCase();
+
+  let targetVaults;
+  if (vault) {
+    const v = await resolveVault(client, vault);
+    if (!v) throw new Error(`Vault "${vault}" not found.`);
+    targetVaults = [v];
+  } else {
+    targetVaults = await collect(await client.vaults.list());
+  }
+
+  const hits = [];
+  for (const v of targetVaults) {
+    for await (const it of await client.items.list(v.id)) {
+      if ((it.title || "").toLowerCase().includes(q)) {
+        hits.push({ ...it, _vaultId: v.id, _vaultTitle: v.title });
+        if (hits.length >= max) break;
       }
-      return { content: [{ type: "text", text }] };
     }
+    if (hits.length >= max) break;
+  }
 
-    if (name === "op_get_item") {
-      const inst = getInstanceByName(args.instance);
-      const client = await getClient(inst);
-      const vault = await resolveVault(client, args.vault);
-      if (!vault) {
-        return {
-          content: [{ type: "text", text: `Vault "${args.vault}" not found.` }],
-          isError: true,
-        };
-      }
-      const itemRef = await resolveItem(client, vault, args.item);
-      if (!itemRef) {
-        return {
-          content: [{ type: "text", text: `Item "${args.item}" not found in vault "${vault.title}".` }],
-          isError: true,
-        };
-      }
-      const full = await client.items.get(vault.id, itemRef.id);
-      const formatted = formatItem(full, !!args.includeConcealed);
-      let text = `# ${formatted.title} (${formatted.category})\n\n`;
-      text += `- **Vault:** ${vault.title} (${formatted.vaultId})\n`;
-      text += `- **Item ID:** ${formatted.id}\n`;
-      if (formatted.tags.length > 0) text += `- **Tags:** ${formatted.tags.join(", ")}\n`;
-      if (formatted.websites.length > 0) {
-        text += `- **Websites:** ${formatted.websites.map((w) => w.url).join(", ")}\n`;
-      }
-      if (formatted.fields.length > 0) {
-        text += `\n## Fields\n\n`;
-        for (const f of formatted.fields) {
-          const val = f.value === undefined ? "" : f.value;
-          text += `- **${f.title}** (${f.type}): ${val}${f.otp ? ` (OTP now: ${f.otp})` : ""}\n`;
-        }
-      }
-      if (!args.includeConcealed) {
-        text += `\n_Concealed fields are redacted. Call with includeConcealed=true to reveal._`;
+  if (hits.length === 0) return `No items matched "${query}".`;
+
+  if (!wantReveal) {
+    const lines = hits.map(
+      (it) =>
+        `- **${it.title}** (id: ${it.id}, vault: ${it._vaultTitle}, category: ${it.category})`,
+    );
+    return `# Search: "${query}" (${hits.length})\n\n${lines.join("\n")}`;
+  }
+
+  // reveal=true: fetch each hit's full item in parallel and render every
+  // field (including concealed values). One-shot path for "give me the X
+  // credential" style queries.
+  const full = await Promise.all(
+    hits.map(async (it) => {
+      try {
+        const item = await client.items.get(it._vaultId, it.id);
+        return { item, _vaultTitle: it._vaultTitle, _error: null };
+      } catch (e) {
+        return { item: it, _vaultTitle: it._vaultTitle, _error: e.message };
       }
-      return { content: [{ type: "text", text }] };
-    }
+    }),
+  );
 
-    if (name === "op_get_secret") {
-      const inst = getInstanceByName(args.instance);
-      const client = await getClient(inst);
-      const value = await client.secrets.resolve(args.reference);
-      return {
-        content: [{ type: "text", text: `Secret for ${args.reference}:\n${value}` }],
-      };
+  const sections = full.map((entry) => {
+    if (entry._error) {
+      return `## ${entry.item.title}\n\n_Failed to fetch: ${entry._error}_`;
     }
+    const it = entry.item;
+    const fields = (it.fields || [])
+      .map((f) => redactField(f, true))
+      .filter((f) => f.value !== undefined && f.value !== "");
+    const fieldLines = fields.length
+      ? fields
+          .map((f) => {
+            const otp = f.otp ? ` (OTP now: ${f.otp})` : "";
+            return `- **${f.title}** (${f.type}): ${f.value}${otp}`;
+          })
+          .join("\n")
+      : "_(no fields)_";
+    const websites = (it.websites || []).map((w) => w.url).filter(Boolean);
+    const websiteLine = websites.length
+      ? `- **URLs:** ${websites.join(", ")}\n`
+      : "";
+    return `## ${it.title} (${it.category})\n\n- **Vault:** ${entry._vaultTitle}\n- **Item ID:** ${it.id}\n${websiteLine}\n${fieldLines}`;
+  });
 
-    if (name === "op_generate_password") {
-      const type = args.type || "Random";
-      let generated;
-      if (type === "Pin") {
-        generated = sdk.Secrets.generatePassword({
-          type: "Pin",
-          parameters: { length: args.length || 8 },
-        });
-      } else if (type === "Memorable") {
-        generated = sdk.Secrets.generatePassword({
-          type: "Memorable",
-          parameters: {
-            separatorType: sdk.SeparatorType.Digits,
-            capitalize: args.capitalize !== false,
-            wordListType: sdk.WordListType.FullWords,
-            wordCount: args.wordCount || 5,
-          },
-        });
-      } else {
-        generated = sdk.Secrets.generatePassword({
-          type: "Random",
-          parameters: {
-            includeDigits: args.includeDigits !== false,
-            includeSymbols: args.includeSymbols !== false,
-            length: args.length || 20,
-          },
-        });
-      }
-      const pwd = typeof generated === "string" ? generated : generated.password || generated;
-      return { content: [{ type: "text", text: `Generated (${type}):\n${pwd}` }] };
+  return `# Search (revealed): "${query}" (${hits.length})\n\n${sections.join("\n\n")}`;
+}
+
+async function searchItemsHandler(args) {
+  const client = await getClient(getInstanceByName(args.instance));
+  return searchItems(client, args);
+}
+
+async function getItemHandler(args) {
+  const client = await getClient(getInstanceByName(args.instance));
+  const vault = await resolveVault(client, args.vault);
+  if (!vault) throw new Error(`Vault "${args.vault}" not found.`);
+  const itemRef = await resolveItem(client, vault, args.item);
+  if (!itemRef) {
+    throw new Error(
+      `Item "${args.item}" not found in vault "${vault.title}".`,
+    );
+  }
+  const full = await client.items.get(vault.id, itemRef.id);
+  const formatted = formatItem(full, !!args.includeConcealed);
+
+  const lines = [
+    `# ${formatted.title} (${formatted.category})`,
+    "",
+    `- **Vault:** ${vault.title} (${formatted.vaultId})`,
+    `- **Item ID:** ${formatted.id}`,
+  ];
+  if (formatted.tags.length) lines.push(`- **Tags:** ${formatted.tags.join(", ")}`);
+  if (formatted.websites.length) {
+    lines.push(
+      `- **Websites:** ${formatted.websites.map((w) => w.url).join(", ")}`,
+    );
+  }
+  if (formatted.fields.length) {
+    lines.push("", "## Fields", "");
+    for (const f of formatted.fields) {
+      const val = f.value === undefined ? "" : f.value;
+      const otp = f.otp ? ` (OTP now: ${f.otp})` : "";
+      lines.push(`- **${f.title}** (${f.type}): ${val}${otp}`);
     }
+  }
+  if (!args.includeConcealed) {
+    lines.push(
+      "",
+      "_Concealed fields are redacted. Call with includeConcealed=true to reveal._",
+    );
+  }
+  return lines.join("\n");
+}
 
-    if (name === "op_create_item") {
-      const inst = getInstanceByName(args.instance);
-      const client = await getClient(inst);
-      const vault = await resolveVault(client, args.vault);
-      if (!vault) {
-        return {
-          content: [{ type: "text", text: `Vault "${args.vault}" not found.` }],
-          isError: true,
-        };
-      }
-      const category = sdk.ItemCategory[args.category || "Login"];
-      if (!category) {
-        return {
-          content: [{ type: "text", text: `Unknown category "${args.category}".` }],
-          isError: true,
-        };
-      }
-      const fields = (args.fields || []).map((f) => {
-        const ft = sdk.ItemFieldType[f.type];
-        if (!ft) throw new Error(`Unknown field type "${f.type}"`);
-        const out = {
-          id: f.title.toLowerCase().replace(/\s+/g, "_"),
-          title: f.title,
-          fieldType: ft,
-          value: f.value,
-        };
-        if (f.sectionId) out.sectionId = f.sectionId;
-        return out;
-      });
-      if (args.notes) {
-        fields.push({
-          id: "notesPlain",
-          title: "notesPlain",
-          fieldType: sdk.ItemFieldType.Text,
-          value: args.notes,
-        });
+async function getSecretHandler(args) {
+  const client = await getClient(getInstanceByName(args.instance));
+  const value = await client.secrets.resolve(args.reference);
+  return `Secret for ${args.reference}:\n${value}`;
+}
+
+function generatePasswordHandler(args) {
+  const type = args.type || "Random";
+  let generated;
+  if (type === "Pin") {
+    generated = sdk.Secrets.generatePassword({
+      type: "Pin",
+      parameters: { length: args.length || 8 },
+    });
+  } else if (type === "Memorable") {
+    generated = sdk.Secrets.generatePassword({
+      type: "Memorable",
+      parameters: {
+        separatorType: sdk.SeparatorType.Digits,
+        capitalize: args.capitalize !== false,
+        wordListType: sdk.WordListType.FullWords,
+        wordCount: args.wordCount || 5,
+      },
+    });
+  } else {
+    generated = sdk.Secrets.generatePassword({
+      type: "Random",
+      parameters: {
+        includeDigits: args.includeDigits !== false,
+        includeSymbols: args.includeSymbols !== false,
+        length: args.length || 20,
+      },
+    });
+  }
+  const pwd =
+    typeof generated === "string" ? generated : generated.password || generated;
+  return `Generated (${type}):\n${pwd}`;
+}
+
+async function updateItemHandler(args) {
+  const client = await getClient(getInstanceByName(args.instance));
+  const vault = await resolveVault(client, args.vault);
+  if (!vault) throw new Error(`Vault "${args.vault}" not found.`);
+  const itemRef = await resolveItem(client, vault, args.item);
+  if (!itemRef) {
+    throw new Error(
+      `Item "${args.item}" not found in vault "${vault.title}".`,
+    );
+  }
+
+  const current = await client.items.get(vault.id, itemRef.id);
+  const updated = { ...current };
+
+  if (args.title) updated.title = args.title;
+  if (args.tags) updated.tags = args.tags;
+
+  if (Array.isArray(args.fields) && args.fields.length > 0) {
+    const existing = current.fields || [];
+    const patchesByTitle = new Map(
+      args.fields.map((p) => [p.title.toLowerCase(), p]),
+    );
+
+    // Patch existing fields in place, preserving id/type/sectionId
+    const patchedExisting = existing.map((f) => {
+      const patch = patchesByTitle.get((f.title || "").toLowerCase());
+      if (!patch) return f;
+      patchesByTitle.delete((f.title || "").toLowerCase());
+      return { ...f, value: patch.value };
+    });
+
+    // Remaining patches = new fields to add (must specify type)
+    const additions = [];
+    for (const patch of patchesByTitle.values()) {
+      if (!patch.type) {
+        throw new Error(
+          `Field "${patch.title}" doesn't exist on the item — pass a 'type' to add it as a new field.`,
+        );
       }
-      const item = await client.items.create({
-        title: args.title,
-        category,
-        vaultId: vault.id,
-        fields,
-        tags: args.tags || [],
-        websites: (args.websites || []).map((w) => ({
-          url: w.url,
-          label: w.label || "website",
-          autofillBehavior: sdk.AutofillBehavior.AnywhereOnWebsite,
-        })),
+      const ft = sdk.ItemFieldType[patch.type];
+      if (!ft) throw new Error(`Unknown field type "${patch.type}".`);
+      additions.push({
+        id: patch.title.toLowerCase().replace(/\s+/g, "_"),
+        title: patch.title,
+        fieldType: ft,
+        value: patch.value,
+        sectionId: patch.sectionId,
       });
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Created item **${item.title}** (id: ${item.id}) in vault "${vault.title}".`,
-          },
-        ],
-      };
     }
+    updated.fields = [...patchedExisting, ...additions];
+  }
 
-    if (name === "op_delete_item") {
-      const inst = getInstanceByName(args.instance);
-      const client = await getClient(inst);
-      const vault = await resolveVault(client, args.vault);
-      if (!vault) {
-        return {
-          content: [{ type: "text", text: `Vault "${args.vault}" not found.` }],
-          isError: true,
-        };
-      }
-      const itemRef = await resolveItem(client, vault, args.item);
-      if (!itemRef) {
-        return {
-          content: [{ type: "text", text: `Item "${args.item}" not found in vault "${vault.title}".` }],
-          isError: true,
-        };
-      }
-      await client.items.delete(vault.id, itemRef.id);
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Deleted item "${itemRef.title}" from vault "${vault.title}".`,
-          },
-        ],
-      };
-    }
+  const result = await client.items.put(updated);
+  return `Updated item "${result.title}" (id: ${result.id}) in vault "${vault.title}".`;
+}
 
-    if (name === "op_create_vault") {
-      const inst = getInstanceByName(args.instance);
-      const client = await getClient(inst);
-      const vault = await client.vaults.create({
-        title: args.title,
-        description: args.description || "",
-      });
-      return {
-        content: [
-          { type: "text", text: `Created vault **${vault.title}** (id: ${vault.id}).` },
-        ],
-      };
-    }
+async function updateVaultHandler(args) {
+  const client = await getClient(getInstanceByName(args.instance));
+  const vault = await resolveVault(client, args.vault);
+  if (!vault) throw new Error(`Vault "${args.vault}" not found.`);
+  if (!args.title && args.description === undefined) {
+    throw new Error("Provide at least one of title or description.");
+  }
+  await client.vaults.update(vault.id, {
+    title: args.title || vault.title,
+    description: args.description !== undefined ? args.description : vault.description || "",
+  });
+  return `Updated vault "${args.title || vault.title}" (id: ${vault.id}).`;
+}
 
-    if (name === "op_delete_vault") {
-      const inst = getInstanceByName(args.instance);
-      const client = await getClient(inst);
-      const vault = await resolveVault(client, args.vault);
-      if (!vault) {
-        return {
-          content: [{ type: "text", text: `Vault "${args.vault}" not found.` }],
-          isError: true,
-        };
-      }
-      await client.vaults.delete(vault.id);
-      return { content: [{ type: "text", text: `Deleted vault "${vault.title}".` }] };
+async function createItemHandler(args) {
+  const client = await getClient(getInstanceByName(args.instance));
+  const vault = await resolveVault(client, args.vault);
+  if (!vault) throw new Error(`Vault "${args.vault}" not found.`);
+
+  const category = sdk.ItemCategory[args.category || "Login"];
+  if (!category) throw new Error(`Unknown category "${args.category}".`);
+
+  const fields = (args.fields || []).map((f) => {
+    const ft = sdk.ItemFieldType[f.type];
+    if (!ft) throw new Error(`Unknown field type "${f.type}"`);
+    const out = {
+      id: f.title.toLowerCase().replace(/\s+/g, "_"),
+      title: f.title,
+      fieldType: ft,
+      value: f.value,
+    };
+    if (f.sectionId) out.sectionId = f.sectionId;
+    return out;
+  });
+  if (args.notes) {
+    fields.push({
+      id: "notesPlain",
+      title: "notesPlain",
+      fieldType: sdk.ItemFieldType.Text,
+      value: args.notes,
+    });
+  }
+
+  const item = await client.items.create({
+    title: args.title,
+    category,
+    vaultId: vault.id,
+    fields,
+    tags: args.tags || [],
+    websites: (args.websites || []).map((w) => ({
+      url: w.url,
+      label: w.label || "website",
+      autofillBehavior: sdk.AutofillBehavior.AnywhereOnWebsite,
+    })),
+  });
+  return `Created item **${item.title}** (id: ${item.id}) in vault "${vault.title}".`;
+}
+
+async function deleteItemHandler(args) {
+  const client = await getClient(getInstanceByName(args.instance));
+  const vault = await resolveVault(client, args.vault);
+  if (!vault) throw new Error(`Vault "${args.vault}" not found.`);
+  const itemRef = await resolveItem(client, vault, args.item);
+  if (!itemRef) {
+    throw new Error(
+      `Item "${args.item}" not found in vault "${vault.title}".`,
+    );
+  }
+  await client.items.delete(vault.id, itemRef.id);
+  return `Deleted item "${itemRef.title}" from vault "${vault.title}".`;
+}
+
+async function createVaultHandler(args) {
+  const client = await getClient(getInstanceByName(args.instance));
+  const vault = await client.vaults.create({
+    title: args.title,
+    description: args.description || "",
+  });
+  return `Created vault **${vault.title}** (id: ${vault.id}).`;
+}
+
+async function deleteVaultHandler(args) {
+  const client = await getClient(getInstanceByName(args.instance));
+  const vault = await resolveVault(client, args.vault);
+  if (!vault) throw new Error(`Vault "${args.vault}" not found.`);
+  await client.vaults.delete(vault.id);
+  return `Deleted vault "${vault.title}".`;
+}
+
+const HANDLERS = {
+  op_list_instances: listInstancesHandler,
+  op_add_instance: addInstanceHandler,
+  op_remove_instance: removeInstanceHandler,
+  op_list_vaults: listVaultsHandler,
+  op_list_items: listItemsHandler,
+  op_search_items: searchItemsHandler,
+  op_get_item: getItemHandler,
+  op_get_secret: getSecretHandler,
+  op_generate_password: generatePasswordHandler,
+  op_create_item: createItemHandler,
+  op_update_item: updateItemHandler,
+  op_delete_item: deleteItemHandler,
+  op_create_vault: createVaultHandler,
+  op_update_vault: updateVaultHandler,
+  op_delete_vault: deleteVaultHandler,
+};
+
+// Drift guard: every declared tool must have a handler and vice versa. This is
+// evaluated at module load so a missing/extra handler fails fast.
+(function assertHandlerCompleteness() {
+  const toolNames = new Set(TOOL_DEFINITIONS.map((t) => t.name));
+  const handlerNames = new Set(Object.keys(HANDLERS));
+  for (const name of toolNames) {
+    if (!handlerNames.has(name)) {
+      throw new Error(`Tool "${name}" is declared but has no handler.`);
     }
+  }
+  for (const name of handlerNames) {
+    if (!toolNames.has(name)) {
+      throw new Error(`Handler "${name}" exists but is not declared in TOOL_DEFINITIONS.`);
+    }
+  }
+})();
+
+// ============================================================================
+// MCP server wiring
+// ============================================================================
 
-    throw new Error(`Unknown tool: ${name}`);
-  } catch (error) {
+const server = new Server(
+  { name: INTEGRATION_NAME, version: PKG_VERSION },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOL_DEFINITIONS,
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const handler = HANDLERS[name];
+  if (!handler) {
     return {
-      content: [{ type: "text", text: `Error: ${error.message}` }],
+      content: [{ type: "text", text: `Unknown tool: ${name}` }],
+      isError: true,
+    };
+  }
+  try {
+    const result = await handler(args || {});
+    return { content: [{ type: "text", text: String(result) }] };
+  } catch (e) {
+    return {
+      content: [{ type: "text", text: `Error: ${e.message}` }],
       isError: true,
     };
   }
@@ -887,13 +1163,38 @@ if (require.main === module) {
   });
 }
 
-// Export for testing
+// ============================================================================
+// Test exports
+// ============================================================================
+
 if (typeof module !== "undefined") {
   module.exports = {
+    // config
+    CONFIG_DIR,
+    CONFIG_PATH,
     loadConfigFile,
     saveConfigFile,
+    normalizeInstance,
+    // instance resolution
     getInstanceByName,
+    // helpers
+    collect,
+    resolveVault,
+    resolveItem,
     redactField,
     formatItem,
+    searchItems,
+    // handler map + tool list (for drift guard tests)
+    TOOL_DEFINITIONS,
+    HANDLERS,
+    // direct handler access for unit tests that don't need the MCP transport
+    listInstancesHandler,
+    listVaultsHandler,
+    listItemsHandler,
+    searchItemsHandler,
+    getItemHandler,
+    generatePasswordHandler,
+    updateItemHandler,
+    updateVaultHandler,
   };
 }