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

package/README.md

@@ -16,33 +16,44 @@ Built to mirror the multi-instance pattern of [jira-mcp](https://github.com/rui-
 ### Prerequisites
 
 - Node.js 18+
-- A 1Password account with permission to create [service accounts](https://developer.1password.com/docs/service-accounts/)
+- Either:
+  - **The 1Password 8 desktop app** (recommended — no admin permissions needed, and you get access to all vaults you can already see), or
+  - A 1Password **service account** token (needs admin to provision, scoped to shared vaults only — good for CI/headless use)
 
-### Step 1: Create a service account token
-
-1. Go to <https://start.1password.com/developer-tools/infrastructure-secrets/serviceaccount>
-2. Create a service account and grant it access to the vaults you want to use
-3. Copy the token — it starts with `ops_`
-
-### Step 2: Configure
+### Step 1: Install and register the MCP
 
 ```bash
-node $HOME/WebstormProjects/1password-mcp/setup.js
+claude mcp add --scope user --transport stdio 1password -- npx -y @rui.branco/1password-mcp
 ```
 
-Or non-interactively:
+### Step 2: Run setup
 
 ```bash
-node $HOME/WebstormProjects/1password-mcp/setup.js add work ops_ABC... "ITO service account"
+npx @rui.branco/1password-mcp setup
 ```
 
-### Step 3: Add to Claude Code
+The setup wizard walks you through picking an auth mode and validates the connection before saving.
 
-```bash
-claude mcp add --transport stdio 1password -- node $HOME/WebstormProjects/1password-mcp/index.js
-```
+### Step 3 (desktop auth only): One-time 1Password 8 toggles
+
+Desktop auth delegates unlock to the 1Password 8 desktop app, so you need to enable the SDK integration **once** per machine:
+
+1. Open the **1Password 8 desktop app** (not `my.1password.com` in the browser).
+2. Open **Settings** (cmd+, on Mac / ctrl+, on Windows).
+3. Click the **Developer** tab.
+4. Under *Command-Line Interface (CLI)*, tick **"Integrate with 1Password CLI"**.
+5. Under *Integrate with the 1Password SDKs*, tick **"Integrate with other apps"**. ← **This is the critical one.** Without it, the SDK cannot unlock and every call will fail with `DesktopSessionExpiredError`.
+6. Optional: **Settings → Security → Unlock using Touch ID** so the OS prompt can be cleared with your fingerprint.
+
+The first time the MCP actually calls 1Password, your OS will pop an authorization prompt asking whether `1password-mcp-setup` (during the wizard) and `1password-mcp` (at runtime) can talk to 1Password. Click Approve.
+
+### Finding your account name
+
+When the wizard asks for "Account name", open the 1Password 8 desktop app and click the **account switcher** in the top-left. The signin address shown next to your name is what you want — it looks like `my.1password.com`, `my-team.1password.com`, or similar.
+
+### Step 4: Reconnect
 
-Restart Claude Code and run `/mcp` to verify.
+Run `/mcp` in Claude Code to reconnect the 1password server and pick up the new config.
 
 ## Tools
 

package/index.js

@@ -77,7 +77,10 @@ const rawConfig = fs.existsSync(configPath) ? loadConfigFile() : { instances: []
 
 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 || "",
 }));
 
@@ -105,11 +108,24 @@ async function getClient(instance) {
     );
   }
   if (clientCache.has(instance.name)) return clientCache.get(instance.name);
-  if (!instance.token) {
-    throw new Error(`Instance "${instance.name}" has no service account token.`);
+
+  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: instance.token,
+    auth,
     integrationName: INTEGRATION_NAME,
     integrationVersion: `v${PKG_VERSION}`,
   });
@@ -203,14 +219,22 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       {
         name: "op_add_instance",
         description:
-          "Add or update a 1Password service-account instance. Provide name + token (and optional description). Token is stored in ~/.config/1password-mcp/config.json with 0600 permissions.",
+          "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: "1Password service account token (ops_... prefix).",
+              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: {
@@ -218,7 +242,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               description: "Set this instance as the default (default: false).",
             },
           },
-          required: ["name", "token"],
+          required: ["name"],
         },
       },
       {
@@ -433,33 +457,67 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       for (const inst of instances) {
         const isDefault = inst.name === def ? " **(default)**" : "";
         const desc = inst.description ? ` - ${inst.description}` : "";
-        text += `- **${inst.name}**${isDefault}${desc}\n`;
+        const auth =
+          inst.authType === "desktop"
+            ? ` (desktop: ${inst.accountName})`
+            : " (serviceAccount)";
+        text += `- **${inst.name}**${isDefault}${auth}${desc}\n`;
       }
       return { content: [{ type: "text", text }] };
     }
 
     if (name === "op_add_instance") {
       const instName = args.name.trim();
-      if (!/^ops_[A-Za-z0-9_\-]+/.test(args.token)) {
+      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: "Token does not look like a 1Password service account token (expected prefix 'ops_').",
-            },
-          ],
+          content: [{ type: "text", text: `Unknown authType "${authType}".` }],
           isError: true,
         };
       }
 
-      // Validate by creating a client and listing vaults.
+      // 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: args.token,
+          auth: probeAuth,
           integrationName: INTEGRATION_NAME,
           integrationVersion: `v${PKG_VERSION}`,
         });
-        // consume iterator to force a real API call
         const probe = [];
         for await (const v of await tempClient.vaults.list()) {
           probe.push(v);
@@ -467,16 +525,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
       } catch (e) {
         return {
-          content: [
-            { type: "text", text: `Token validation failed: ${e.message}` },
-          ],
+          content: [{ type: "text", text: `Auth validation failed: ${e.message}` }],
           isError: true,
         };
       }
 
       const newInst = {
         name: instName,
-        token: args.token,
+        authType,
+        token: authType === "serviceAccount" ? args.token : undefined,
+        accountName: authType === "desktop" ? args.accountName : undefined,
         description: args.description || "",
       };
       const existingIdx = instances.findIndex((i) => i.name === instName);
@@ -487,7 +545,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const savedConfig = loadConfigFile();
       if (!savedConfig.instances) savedConfig.instances = [];
       const savedIdx = savedConfig.instances.findIndex((i) => i.name === instName);
-      const toSave = { name: instName, token: args.token };
+      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);
@@ -500,7 +560,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         content: [
           {
             type: "text",
-            text: `${existingIdx >= 0 ? "Updated" : "Added"} instance "${instName}".${args.setDefault ? " Set as default." : ""}`,
+            text: `${existingIdx >= 0 ? "Updated" : "Added"} instance "${instName}" (${authType}).${args.setDefault ? " Set as default." : ""}`,
           },
         ],
       };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rui.branco/1password-mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "1Password MCP server for Claude Code - list vaults and items, get secrets, generate passwords, manage items via service accounts. Multi-instance like jira-mcp.",
   "main": "index.js",
   "bin": {
@@ -24,7 +24,7 @@
   "author": "Rui Branco",
   "license": "MIT",
   "dependencies": {
-    "@1password/sdk": "^0.3.1",
+    "@1password/sdk": "^0.4.0",
     "@modelcontextprotocol/sdk": "^1.25.3"
   }
 }

package/setup.js

@@ -28,19 +28,37 @@ function saveConfig(cfg) {
 }
 
 // Non-interactive: setup add <name> <token> [description]
+//                  setup add-desktop <name> <accountName> [description]
 if (args[0] === "add" && args.length >= 3) {
   const [, name, token, ...descArgs] = args;
   const description = descArgs.join(" ").trim();
   const config = loadConfig() || {};
   if (!config.instances) config.instances = [];
   const existing = config.instances.findIndex((i) => i.name === name);
-  const instance = { name, token };
+  const instance = { name, authType: "serviceAccount", token };
   if (description) instance.description = description;
   if (existing >= 0) config.instances[existing] = instance;
   else config.instances.push(instance);
   if (!config.defaultInstance) config.defaultInstance = name;
   saveConfig(config);
-  console.log(`Instance "${name}" saved to ${configPath}`);
+  console.log(`Instance "${name}" saved to ${configPath} (serviceAccount)`);
+  process.exit(0);
+}
+
+if (args[0] === "add-desktop" && args.length >= 3) {
+  const [, name, accountName, ...descArgs] = args;
+  const description = descArgs.join(" ").trim();
+  const config = loadConfig() || {};
+  if (!config.instances) config.instances = [];
+  const existing = config.instances.findIndex((i) => i.name === name);
+  const instance = { name, authType: "desktop", accountName };
+  if (description) instance.description = description;
+  if (existing >= 0) config.instances[existing] = instance;
+  else config.instances.push(instance);
+  if (!config.defaultInstance) config.defaultInstance = name;
+  saveConfig(config);
+  console.log(`Instance "${name}" saved to ${configPath} (desktop: ${accountName})`);
+  console.log("Make sure the 1Password 8 desktop app is installed and the CLI integration is enabled (Settings → Developer → Connect with 1Password CLI).");
   process.exit(0);
 }
 
@@ -88,19 +106,86 @@ async function setup() {
     }
   }
 
-  console.log("To create a 1Password service account token:");
-  console.log("1. Go to https://start.1password.com/developer-tools/infrastructure-secrets/serviceaccount");
-  console.log("2. Create a service account and grant it access to the vaults you need");
-  console.log("3. Copy the token (starts with 'ops_')\n");
+  console.log("Pick auth mode:");
+  console.log("  1. Desktop app (recommended for personal use — uses 1Password 8 biometric unlock, full vault access)");
+  console.log("  2. Service account token (recommended for CI/shared — needs admin to provision, scoped vaults only)\n");
+  const mode = (await ask("Auth mode (1/2, default 1): ")).trim() || "1";
 
   const name = (await ask("Instance name (e.g., work): ")).trim();
-  const token = (await ask("Service account token: ")).trim();
   const description = (await ask("Description (optional): ")).trim();
 
   const config = existing || { instances: [] };
   if (!config.instances) config.instances = [];
   const idx = config.instances.findIndex((i) => i.name === name);
-  const instance = { name, token };
+  let instance;
+
+  if (mode === "2") {
+    console.log("\nCreate a service account token at:");
+    console.log("  https://start.1password.com/developer-tools/infrastructure-secrets/serviceaccount");
+    const token = (await ask("Service account token (ops_...): ")).trim();
+    instance = { name, authType: "serviceAccount", token };
+  } else {
+    console.log("\n=== One-time 1Password 8 setup (required for desktop auth) ===");
+    console.log("");
+    console.log("Open the 1Password 8 desktop app (not the browser — the Mac/Windows app).");
+    console.log("");
+    console.log("  1. Open Settings (cmd+, on Mac / ctrl+, on Windows)");
+    console.log("  2. Click the 'Developer' tab on the left");
+    console.log("  3. Tick 'Integrate with 1Password CLI'");
+    console.log("     (under 'Command-Line Interface (CLI)')");
+    console.log("  4. Tick 'Integrate with other apps'");
+    console.log("     (under 'Integrate with the 1Password SDKs')");
+    console.log("     ** THIS IS THE KEY ONE — without it the SDK can't unlock. **");
+    console.log("  5. (Optional) Settings → Security → 'Unlock using Touch ID'");
+    console.log("");
+    console.log("The first time the MCP calls 1Password you'll get a system prompt");
+    console.log("asking to authorize '1password-mcp' — click Approve.");
+    console.log("");
+    console.log("=== Finding your account name ===");
+    console.log("");
+    console.log("Open 1Password 8 → click the account switcher in the top-left.");
+    console.log("The signin address shown next to your name is what you want here,");
+    console.log("e.g. 'my.1password.com' or 'my-team.1password.com'.");
+    console.log("");
+    const accountName = (await ask("Account name (e.g., my.1password.com): ")).trim();
+    if (!accountName) {
+      console.error("Account name is required. Aborting.");
+      rl.close();
+      process.exit(1);
+    }
+    instance = { name, authType: "desktop", accountName };
+
+    // Validate by actually trying to talk to the desktop app. This will pop the
+    // OS-level authorization prompt on first use.
+    console.log("\nValidating with 1Password desktop app (you may get an auth prompt)…");
+    try {
+      const sdk = require("@1password/sdk");
+      const client = await sdk.createClient({
+        auth: new sdk.DesktopAuth(accountName),
+        integrationName: "1password-mcp-setup",
+        integrationVersion: "v1",
+      });
+      const probe = [];
+      for await (const v of await client.vaults.list()) {
+        probe.push(v);
+        if (probe.length >= 1) break;
+      }
+      console.log(`Validated. Saw vault: ${probe[0]?.title || "(none visible)"}.`);
+    } catch (e) {
+      console.error("");
+      console.error("Validation failed: " + e.message);
+      console.error("");
+      console.error("Common causes:");
+      console.error("  - 'Integrate with other apps' is NOT ticked in 1Password Settings → Developer");
+      console.error("  - 1Password 8 desktop app is not running or locked");
+      console.error("  - Account name is wrong (check the account switcher in 1Password 8)");
+      console.error("");
+      console.error("Fix the issue and re-run this setup.");
+      rl.close();
+      process.exit(1);
+    }
+  }
+
   if (description) instance.description = description;
   if (idx >= 0) config.instances[idx] = instance;
   else config.instances.push(instance);