@rui.branco/1password-mcp 0.1.1

package/README.md

@@ -0,0 +1,86 @@
+# 1Password MCP Server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [1Password](https://1password.com/) that runs **entirely locally** — no external services, no telemetry, no leaks. Uses the official [`@1password/sdk`](https://www.npmjs.com/package/@1password/sdk) with a 1Password Service Account token.
+
+Built to mirror the multi-instance pattern of [jira-mcp](https://github.com/rui-branco/jira-mcp) so you can point the same Claude Code session at multiple 1Password accounts (e.g. `work` and `personal`).
+
+## Features
+
+- **Multi-instance** — add several service accounts, switch per tool call via `instance` parameter
+- **Local only** — all calls go directly from your machine to 1Password over TLS; the config file is stored `0600` in `~/.config/1password-mcp/config.json`
+- **Redaction by default** — concealed fields (passwords, TOTP) are redacted unless you explicitly pass `includeConcealed: true`
+- **Read + write** — list vaults/items, fetch full items, resolve `op://` references, generate passwords, create/delete items, create/delete vaults
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18+
+- A 1Password account with permission to create [service accounts](https://developer.1password.com/docs/service-accounts/)
+
+### 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
+
+```bash
+node $HOME/WebstormProjects/1password-mcp/setup.js
+```
+
+Or non-interactively:
+
+```bash
+node $HOME/WebstormProjects/1password-mcp/setup.js add work ops_ABC... "ITO service account"
+```
+
+### Step 3: Add to Claude Code
+
+```bash
+claude mcp add --transport stdio 1password -- node $HOME/WebstormProjects/1password-mcp/index.js
+```
+
+Restart Claude Code and run `/mcp` to verify.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `op_list_instances` | List configured service accounts (tokens never returned) |
+| `op_add_instance` | Add/update an instance. Validates the token against the API. |
+| `op_remove_instance` | Remove an instance by name |
+| `op_list_vaults` | List vaults visible to the service account |
+| `op_list_items` | List items in a vault (by vault id or title) |
+| `op_search_items` | Title-substring search across one or all vaults |
+| `op_get_item` | Fetch a full item. Concealed fields redacted unless `includeConcealed=true`. |
+| `op_get_secret` | Resolve a `op://Vault/Item/field` secret reference |
+| `op_generate_password` | Generate Random / Memorable / Pin passwords via the 1Password generator |
+| `op_create_item` | Create a new item with fields, tags, and websites |
+| `op_delete_item` | Delete an item |
+| `op_create_vault` | Create a new vault |
+| `op_delete_vault` | Delete a vault |
+
+All tools that talk to 1Password accept an optional `instance` parameter. Omit it to use the default instance.
+
+## Security notes
+
+- Tokens live only in `~/.config/1password-mcp/config.json` (chmod 0600) and in the SDK client process. They are never logged or transmitted anywhere except to `*.1password.com`.
+- Service accounts only see vaults that have been explicitly shared with them — personal vaults are inaccessible by design.
+- Concealed fields are redacted by default in tool output so the model cannot accidentally quote a password back. Pass `includeConcealed: true` only when you actually need the cleartext.
+
+## Config shape
+
+```json
+{
+  "instances": [
+    { "name": "work", "token": "ops_...", "description": "ITO service account" }
+  ],
+  "defaultInstance": "work"
+}
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,839 @@
+#!/usr/bin/env node
+
+// Handle setup subcommand
+if (process.argv[2] === "setup") {
+  require("./setup.js");
+  return;
+}
+
+const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
+const {
+  StdioServerTransport,
+} = require("@modelcontextprotocol/sdk/server/stdio.js");
+const {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} = require("@modelcontextprotocol/sdk/types.js");
+const fs = require("fs");
+const path = require("path");
+const sdk = require("@1password/sdk");
+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
+const GITHUB_REPO = "rui-branco/1password-mcp";
+const INSTALLED_SHA_FILE = path.join(__dirname, ".installed-sha");
+try {
+  const localSha = fs.existsSync(INSTALLED_SHA_FILE)
+    ? fs.readFileSync(INSTALLED_SHA_FILE, "utf-8").trim()
+    : "";
+  const remoteSha = execSync(
+    `git ls-remote https://github.com/${GITHUB_REPO}.git HEAD`,
+    { stdio: "pipe", timeout: 5000 },
+  )
+    .toString()
+    .split("\t")[0]
+    .trim();
+  if (remoteSha && remoteSha !== localSha) {
+    const child = spawn(
+      "sh",
+      [
+        "-c",
+        `npm install -g git+ssh://git@github.com/${GITHUB_REPO}.git && echo "${remoteSha}" > "${INSTALLED_SHA_FILE}"`,
+      ],
+      { stdio: "ignore", detached: true },
+    );
+    child.unref();
+  }
+} catch {}
+
+// ============ CONFIG ============
+
+const configDir = path.join(process.env.HOME, ".config/1password-mcp");
+const configPath = path.join(configDir, "config.json");
+
+if (!fs.existsSync(configDir)) {
+  fs.mkdirSync(configDir, { recursive: true });
+}
+
+function loadConfigFile() {
+  try {
+    return JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function saveConfigFile(cfg) {
+  fs.writeFileSync(configPath, JSON.stringify(cfg, null, 2));
+  try {
+    fs.chmodSync(configPath, 0o600);
+  } catch {}
+}
+
+const rawConfig = fs.existsSync(configPath) ? loadConfigFile() : { instances: [] };
+
+let instances = (rawConfig.instances || []).map((i) => ({
+  name: i.name,
+  token: i.token,
+  description: i.description || "",
+}));
+
+const defaultInstance =
+  (rawConfig.defaultInstance && instances.find((i) => i.name === rawConfig.defaultInstance)) ||
+  instances[0] ||
+  null;
+
+function getInstanceByName(name) {
+  if (!name) return defaultInstance;
+  return instances.find((i) => i.name === name) || defaultInstance;
+}
+
+// ============ 1PASSWORD 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.
+const clientCache = new Map();
+
+async function getClient(instance) {
+  if (!instance) {
+    throw new Error(
+      "No 1Password instance configured. Run `1password-mcp setup` or call op_add_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.`);
+  }
+  const client = await sdk.createClient({
+    auth: instance.token,
+    integrationName: INTEGRATION_NAME,
+    integrationVersion: `v${PKG_VERSION}`,
+  });
+  clientCache.set(instance.name, client);
+  return client;
+}
+
+function invalidateClient(name) {
+  clientCache.delete(name);
+}
+
+// ============ HELPERS ============
+
+// Pick a vault by id OR by title (case-insensitive exact match, then prefix).
+async function resolveVault(client, vaultRef) {
+  if (!vaultRef) return null;
+  const vaults = [];
+  for await (const v of await client.vaults.list()) vaults.push(v);
+  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;
+}
+
+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 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;
+}
+
+function redactField(field, includeConcealed) {
+  const out = {
+    id: field.id,
+    title: field.title,
+    type: field.fieldType,
+    sectionId: field.sectionId || undefined,
+  };
+  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;
+    }
+  } else {
+    out.value = "[REDACTED]";
+  }
+  return out;
+}
+
+function formatItem(item, includeConcealed) {
+  return {
+    id: item.id,
+    title: item.title,
+    category: item.category,
+    vaultId: item.vaultId,
+    tags: item.tags || [],
+    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 ============
+
+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: [] },
+      },
+      {
+        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.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Unique name (e.g., 'work', 'personal')." },
+            token: {
+              type: "string",
+              description: "1Password service account token (ops_... prefix).",
+            },
+            description: { type: "string", description: "Optional human-readable description." },
+            setDefault: {
+              type: "boolean",
+              description: "Set this instance as the default (default: false).",
+            },
+          },
+          required: ["name", "token"],
+        },
+      },
+      {
+        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 service account.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            instance: { type: "string", description: "Instance name. Uses default if omitted." },
+          },
+          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." },
+          },
+          required: ["vault"],
+        },
+      },
+      {
+        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"],
+        },
+      },
+      {
+        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"],
+        },
+      },
+      {
+        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." },
+          },
+          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)." },
+          },
+          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" },
+                },
+                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"],
+              },
+            },
+            notes: { type: "string", description: "Optional notes (stored as a Text field called 'notesPlain')." },
+            instance: { type: "string", description: "Instance name. Uses default if omitted." },
+          },
+          required: ["vault", "title"],
+        },
+      },
+      {
+        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"],
+        },
+      },
+      {
+        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;
+
+  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}` : "";
+        text += `- **${inst.name}**${isDefault}${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)) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Token does not look like a 1Password service account token (expected prefix 'ops_').",
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      // Validate by creating a client and listing vaults.
+      try {
+        const tempClient = await sdk.createClient({
+          auth: args.token,
+          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);
+          if (probe.length >= 1) break;
+        }
+      } catch (e) {
+        return {
+          content: [
+            { type: "text", text: `Token validation failed: ${e.message}` },
+          ],
+          isError: true,
+        };
+      }
+
+      const newInst = {
+        name: instName,
+        token: args.token,
+        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, token: args.token };
+      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);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `${existingIdx >= 0 ? "Updated" : "Added"} instance "${instName}".${args.setDefault ? " Set as default." : ""}`,
+          },
+        ],
+      };
+    }
+
+    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}".` }] };
+    }
+
+    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 }] };
+    }
+
+    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 }] };
+    }
+
+    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);
+      }
+
+      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;
+      }
+
+      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`;
+      }
+      return { content: [{ type: "text", text }] };
+    }
+
+    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._`;
+      }
+      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}` }],
+      };
+    }
+
+    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}` }] };
+    }
+
+    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,
+        });
+      }
+      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 {
+        content: [
+          {
+            type: "text",
+            text: `Created item **${item.title}** (id: ${item.id}) in vault "${vault.title}".`,
+          },
+        ],
+      };
+    }
+
+    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}".`,
+          },
+        ],
+      };
+    }
+
+    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}).` },
+        ],
+      };
+    }
+
+    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}".` }] };
+    }
+
+    throw new Error(`Unknown tool: ${name}`);
+  } catch (error) {
+    return {
+      content: [{ type: "text", text: `Error: ${error.message}` }],
+      isError: true,
+    };
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+if (require.main === module) {
+  main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+}
+
+// Export for testing
+if (typeof module !== "undefined") {
+  module.exports = {
+    loadConfigFile,
+    saveConfigFile,
+    getInstanceByName,
+    redactField,
+    formatItem,
+  };
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@rui.branco/1password-mcp",
+  "version": "0.1.1",
+  "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": {
+    "1password-mcp": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "setup.js"
+  ],
+  "scripts": {
+    "setup": "node setup.js",
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "1password",
+    "claude",
+    "claude-code"
+  ],
+  "author": "Rui Branco",
+  "license": "MIT",
+  "dependencies": {
+    "@1password/sdk": "^0.3.1",
+    "@modelcontextprotocol/sdk": "^1.25.3"
+  }
+}

package/setup.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+const readline = require("readline");
+const fs = require("fs");
+const path = require("path");
+
+const configDir = path.join(process.env.HOME, ".config/1password-mcp");
+const configPath = path.join(configDir, "config.json");
+
+let args = process.argv.slice(2);
+if (args[0] === "setup") args = args.slice(1);
+
+function loadConfig() {
+  try {
+    if (fs.existsSync(configPath)) {
+      return JSON.parse(fs.readFileSync(configPath, "utf8"));
+    }
+  } catch {}
+  return null;
+}
+
+function saveConfig(cfg) {
+  if (!fs.existsSync(configDir)) fs.mkdirSync(configDir, { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(cfg, null, 2));
+  try {
+    fs.chmodSync(configPath, 0o600);
+  } catch {}
+}
+
+// Non-interactive: setup add <name> <token> [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 };
+  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}`);
+  process.exit(0);
+}
+
+// Non-interactive: setup remove <name>
+if (args[0] === "remove" && args.length >= 2) {
+  const config = loadConfig();
+  if (!config || !config.instances) {
+    console.error("No config found.");
+    process.exit(1);
+  }
+  config.instances = config.instances.filter((i) => i.name !== args[1]);
+  if (config.defaultInstance === args[1]) {
+    config.defaultInstance = config.instances[0]?.name || null;
+  }
+  saveConfig(config);
+  console.log(`Instance "${args[1]}" removed.`);
+  process.exit(0);
+}
+
+// Interactive
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+function ask(q) {
+  return new Promise((r) => rl.question(q, r));
+}
+
+async function setup() {
+  console.log("\n=== 1Password MCP Setup ===\n");
+  const existing = loadConfig();
+  if (existing?.instances?.length) {
+    console.log("Existing instances:");
+    for (const inst of existing.instances) {
+      const isDefault = inst.name === existing.defaultInstance ? " (default)" : "";
+      const desc = inst.description ? ` - ${inst.description}` : "";
+      console.log(`  - ${inst.name}${isDefault}${desc}`);
+    }
+    console.log();
+    const action = await ask("Add another instance? (y/N): ");
+    if (action.trim().toLowerCase() !== "y") {
+      rl.close();
+      return;
+    }
+  }
+
+  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");
+
+  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 };
+  if (description) instance.description = description;
+  if (idx >= 0) config.instances[idx] = instance;
+  else config.instances.push(instance);
+
+  if (!config.defaultInstance) config.defaultInstance = name;
+  else {
+    const setDefault = await ask(`Set "${name}" as default? (y/N): `);
+    if (setDefault.trim().toLowerCase() === "y") config.defaultInstance = name;
+  }
+
+  saveConfig(config);
+  console.log(`\nConfig saved to ${configPath} (mode 0600)`);
+  console.log("\nAdd to Claude Code with:");
+  console.log("  claude mcp add --transport stdio 1password -- node $HOME/WebstormProjects/1password-mcp/index.js");
+  rl.close();
+}
+
+setup().catch((e) => {
+  console.error("Setup failed:", e.message);
+  rl.close();
+  process.exit(1);
+});