decoy-mcp-server 1.0.0

package/dist/index.js

@@ -0,0 +1,1409 @@
+#!/usr/bin/env node
+/**
+ * Decoy MCP Server v2.2 — Streamable HTTP transport
+ *
+ * Setup: first run opens decoys.me/connect?code=... in the user's browser → scan QR
+ * with the Decoy iOS app → approved token saved to ~/.decoy/mcp-token and reused
+ * on subsequent runs. No localhost setup page — the public website is the kiosk.
+ *
+ * Auth priority:
+ *   1. DECOY_AGENT_TOKEN env var (explicit override)
+ *   2. ~/.decoy/mcp-token config file (saved after first pairing)
+ *   3. Interactive pairing via decoys.me/connect (first-time setup)
+ *
+ * ENV:
+ *   DECOY_AGENT_TOKEN    Explicit agent token (skips pairing)
+ *   DECOY_AGENT_API_URL  Base URL for agent API (default: https://api.decoys.me/api/agent)
+ *   DECOY_CONNECT_URL    Frontend pairing page (default: https://decoys.me/connect)
+ *   DECOY_AGENT_FOR      Slug for ?for= param so the website shows the right agent
+ *                        name (e.g. claude-code, cursor, gemini, codex). Default: mcp
+ *   PORT                 HTTP port (default: 3001)
+ *   DEV_MODE             "true" → use dev-api.decoys.me
+ */
+import express from 'express';
+import { randomUUID, generateKeyPairSync, privateDecrypt, createDecipheriv, createCipheriv, randomBytes, publicEncrypt, createPublicKey, constants } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { exec } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { cxfItemToStructured } from './cxf-structured.js';
+// ── Config ────────────────────────────────────────────────────────────────────
+const DEV_MODE = process.env.DEV_MODE === 'true';
+const DEFAULT_API_URL = DEV_MODE
+    ? 'https://dev-api.decoys.me/api/agent'
+    : 'https://api.decoys.me/api/agent';
+const AGENT_API_URL = process.env.DECOY_AGENT_API_URL ?? DEFAULT_API_URL;
+const CONNECT_API_URL = AGENT_API_URL.replace(/\/agent$/, '/connect');
+const CONNECT_FRONTEND_URL = process.env.DECOY_CONNECT_URL ?? 'https://decoys.me/connect';
+const AGENT_FOR = process.env.DECOY_AGENT_FOR ?? 'mcp';
+const PORT = Number(process.env.PORT ?? 3001);
+const TOKEN_FILE = path.join(os.homedir(), '.decoy', 'mcp-token');
+const KEY_FILE = path.join(os.homedir(), '.decoy', 'mcp-agent-key.json');
+function loadOrGenerateKeyPair() {
+    // Try load existing keypair from disk
+    try {
+        if (fs.existsSync(KEY_FILE)) {
+            const raw = fs.readFileSync(KEY_FILE, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (parsed.publicKeySpki && parsed.privateKeyPem)
+                return parsed;
+        }
+    }
+    catch { /* fall through to generate */ }
+    // Generate new RSA-2048 keypair
+    const { publicKey, privateKey } = generateKeyPairSync('rsa', {
+        modulusLength: 2048,
+        publicKeyEncoding: { type: 'spki', format: 'der' },
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+    });
+    const pair = {
+        publicKeySpki: publicKey.toString('base64'),
+        privateKeyPem: privateKey,
+    };
+    try {
+        fs.mkdirSync(path.dirname(KEY_FILE), { recursive: true });
+        fs.writeFileSync(KEY_FILE, JSON.stringify(pair), { mode: 0o600 });
+    }
+    catch (e) {
+        console.error('[Decoy] Warning: could not save agent keypair to', KEY_FILE, e);
+    }
+    return pair;
+}
+/**
+ * Decrypt content produced by CryptoService.encrypt(data:withRSAPublicKeyBase64:).
+ * Envelope format: [2-byte key length (BE)][RSA-OAEP-SHA256 encrypted AES key][12-byte IV][ciphertext][16-byte auth tag]
+ */
+function decryptAgentContent(ciphertextBase64, privateKeyPem) {
+    const buf = Buffer.from(ciphertextBase64, 'base64');
+    const keyLen = buf.readUInt16BE(0);
+    const encryptedAesKey = buf.subarray(2, 2 + keyLen);
+    const iv = buf.subarray(2 + keyLen, 2 + keyLen + 12);
+    const ciphertextWithTag = buf.subarray(2 + keyLen + 12);
+    const authTag = ciphertextWithTag.subarray(ciphertextWithTag.length - 16);
+    const ciphertext = ciphertextWithTag.subarray(0, ciphertextWithTag.length - 16);
+    const aesKey = privateDecrypt({ key: privateKeyPem, padding: constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' }, encryptedAesKey);
+    const decipher = createDecipheriv('aes-256-gcm', aesKey, iv);
+    decipher.setAuthTag(authTag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf-8');
+}
+/**
+ * Like decryptAgentContent but returns raw bytes — used to unwrap the vault-key
+ * grant (GET /api/agent/vault-key), which is the same RSA-OAEP+AES-GCM envelope
+ * but carries 32 raw key bytes rather than UTF-8.
+ */
+function decryptAgentContentRaw(ciphertextBase64, privateKeyPem) {
+    const buf = Buffer.from(ciphertextBase64, 'base64');
+    const keyLen = buf.readUInt16BE(0);
+    const encryptedAesKey = buf.subarray(2, 2 + keyLen);
+    const iv = buf.subarray(2 + keyLen, 2 + keyLen + 12);
+    const ctWithTag = buf.subarray(2 + keyLen + 12);
+    const authTag = ctWithTag.subarray(ctWithTag.length - 16);
+    const ciphertext = ctWithTag.subarray(0, ctWithTag.length - 16);
+    const aesKey = privateDecrypt({ key: privateKeyPem, padding: constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' }, encryptedAesKey);
+    const decipher = createDecipheriv('aes-256-gcm', aesKey, iv);
+    decipher.setAuthTag(authTag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+// ── SealedBlob VAULT codec (Phase 3b) ─────────────────────────────────────────
+// Vendored from canonical decoy-api/lib/sealed-blob.ts — MUST stay byte-identical.
+// VAULT layout: [0]=0x01 version [1]=0x01 mode [2..13]=nonce [14..]=AES-256-GCM(ct)+tag.
+const SEALED_BLOB_VERSION = 0x01;
+const SEAL_MODE_VAULT = 0x01;
+export function openVault(blobBase64, vaultKey) {
+    const blob = Buffer.from(blobBase64, 'base64');
+    if (blob.length <= 14 || blob[0] !== SEALED_BLOB_VERSION || blob[1] !== SEAL_MODE_VAULT) {
+        throw new Error('not a VAULT-mode SealedBlob');
+    }
+    const nonce = blob.subarray(2, 14);
+    const ctWithTag = blob.subarray(14);
+    const tag = ctWithTag.subarray(ctWithTag.length - 16);
+    const ct = ctWithTag.subarray(0, ctWithTag.length - 16);
+    const decipher = createDecipheriv('aes-256-gcm', vaultKey, nonce);
+    decipher.setAuthTag(tag);
+    const out = Buffer.concat([decipher.update(ct), decipher.final()]);
+    return JSON.parse(out.toString('utf-8'));
+}
+export function sealVault(value, vaultKey) {
+    const nonce = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', vaultKey, nonce);
+    const ct = Buffer.concat([cipher.update(Buffer.from(JSON.stringify(value), 'utf-8')), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([Buffer.from([SEALED_BLOB_VERSION, SEAL_MODE_VAULT]), nonce, ct, tag]).toString('base64');
+}
+// ── Token resolution ──────────────────────────────────────────────────────────
+function loadSavedToken() {
+    try {
+        if (fs.existsSync(TOKEN_FILE))
+            return fs.readFileSync(TOKEN_FILE, 'utf-8').trim() || null;
+    }
+    catch { /* ignore */ }
+    return null;
+}
+function saveToken(token) {
+    try {
+        fs.mkdirSync(path.dirname(TOKEN_FILE), { recursive: true });
+        fs.writeFileSync(TOKEN_FILE, token + '\n', { mode: 0o600 });
+    }
+    catch (e) {
+        console.error('[Decoy] Warning: could not save token to', TOKEN_FILE, e);
+    }
+}
+function openBrowser(url) {
+    const cmd = process.platform === 'win32' ? `start "" "${url}"`
+        : process.platform === 'darwin' ? `open "${url}"`
+            : `xdg-open "${url}"`;
+    exec(cmd, (err) => {
+        if (err)
+            console.error('[Decoy] Could not open browser automatically — visit:', url);
+    });
+}
+/**
+ * First-time setup: creates a connect session, opens decoys.me/connect?code=... in
+ * the user's browser, then resolves when the iOS app approves. Returns the agent
+ * token. The website renders the branded QR and polls status; the MCP polls here
+ * independently so both sides converge on approval.
+ */
+// Scopes the bridge requests at pairing — one per tool family it exposes.
+// (Colon-form legacy aliases; the server maps them to canonical capabilities.)
+const MCP_REQUESTED_SCOPES = [
+    'decoys:read', 'decoys:write',
+    'inbox:read', 'inbox:content',
+    'forwarding:read', 'forwarding:write',
+    'alerts:read', 'alerts:write',
+    'profile:read', 'profile:write',
+    'accounts:read', 'accounts:write',
+];
+async function runBrowserPairing(keyPair) {
+    const createRes = await fetch(`${CONNECT_API_URL}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            name: process.env.DECOY_AGENT_NAME || 'MCP Server',
+            platform: 'mcp',
+            agent_public_key: keyPair.publicKeySpki,
+            // Request scopes for ALL the tool families this bridge exposes. The
+            // server's DEFAULT_MCP_SCOPES historically omitted accounts, so a default
+            // pairing couldn't use account_* tools at all. The user still approves
+            // (and may downgrade) this set in the app.
+            scopes: MCP_REQUESTED_SCOPES,
+        }),
+    });
+    if (!createRes.ok)
+        throw new Error(`Failed to start pairing session: HTTP ${createRes.status}`);
+    const { code, expires_at } = await createRes.json();
+    // Hand off to the public, branded pairing page on decoys.me
+    const pairingUrl = `${CONNECT_FRONTEND_URL}?code=${encodeURIComponent(code)}&for=${encodeURIComponent(AGENT_FOR)}`;
+    console.error(`\n🔑  Decoy MCP — open this page to pair:`);
+    console.error(`   ${pairingUrl}\n`);
+    openBrowser(pairingUrl);
+    // Poll server-side until approved
+    return new Promise((resolve, reject) => {
+        const expiresAt = new Date(expires_at);
+        const interval = setInterval(async () => {
+            try {
+                const res = await fetch(`${CONNECT_API_URL}?code=${code}`);
+                if (!res.ok)
+                    return;
+                const { status, access_token } = await res.json();
+                if (status === 'approved' && access_token) {
+                    clearInterval(interval);
+                    saveToken(access_token);
+                    console.error('✅  Paired! Token saved to', TOKEN_FILE);
+                    resolve(access_token);
+                }
+                else if (status === 'denied') {
+                    clearInterval(interval);
+                    reject(new Error('Pairing was denied in the Decoy app.'));
+                }
+                else if (status === 'expired' || Date.now() > expiresAt.getTime()) {
+                    clearInterval(interval);
+                    reject(new Error('Pairing code expired. Restart the server to try again.'));
+                }
+            }
+            catch { /* transient, retry */ }
+        }, 2000);
+    });
+}
+async function resolveToken(keyPair) {
+    if (process.env.DECOY_AGENT_TOKEN?.trim()) {
+        console.error('[Decoy] Using token from DECOY_AGENT_TOKEN env var');
+        return process.env.DECOY_AGENT_TOKEN.trim();
+    }
+    const saved = loadSavedToken();
+    if (saved) {
+        console.error('[Decoy] Using saved token from', TOKEN_FILE);
+        return saved;
+    }
+    return runBrowserPairing(keyPair);
+}
+// ── Agent API client ──────────────────────────────────────────────────────────
+function makeClient(agentToken) {
+    async function call(path, method = 'GET', body) {
+        const res = await fetch(`${AGENT_API_URL}${path}`, {
+            method,
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${agentToken}`,
+            },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const data = await res.json();
+        if (!res.ok) {
+            const err = data.error ?? `HTTP ${res.status}`;
+            throw new Error(err);
+        }
+        return data;
+    }
+    return { call };
+}
+// Structured (multi-part) field input for account_create / account_update.
+// `values` keys are the CXF member names: address →
+// streetAddress/apt/city/territory/postalCode/country; credit-card →
+// number/fullName/expiryDate/verificationNumber. The MCP stamps an `id` per
+// entry (iOS StructuredFieldBlob.id is required — a missing id makes the device
+// decode the whole array to nil) before sealing into the blob.
+const STRUCTURED_INPUT_SCHEMA = z.array(z.object({
+    kind: z.enum(['address', 'credit-card']),
+    label: z.string().max(100).optional(),
+    values: z.record(z.string(), z.string()),
+})).max(20);
+function normalizeStructured(input) {
+    if (!Array.isArray(input) || input.length === 0)
+        return null;
+    return input.map((s) => ({
+        id: randomUUID(),
+        kind: s.kind,
+        label: s.label ?? null,
+        values: s.values ?? {},
+    }));
+}
+export function buildMcpServer(agentToken, privateKeyPem, deps = {}) {
+    const server = new McpServer({ name: 'decoy', version: '2.1.0' });
+    const call = deps.call ?? makeClient(agentToken).call;
+    const ok = (data) => ({
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    });
+    // ── SealedBlob (Phase 3b): vault key + account decrypt/seal ─────────────────
+    // The vault key is granted to this agent at pairing (wrapped to our public key).
+    // We unwrap it ONCE with our local private key and cache it in memory — the
+    // Decoy server never holds it, so account metadata is decrypted only here.
+    let vaultKeyCache = null;
+    async function defaultGetVaultKey() {
+        if (vaultKeyCache)
+            return vaultKeyCache;
+        if (!privateKeyPem)
+            return null;
+        try {
+            const resp = await call('/vault-key');
+            vaultKeyCache = decryptAgentContentRaw(resp.wrapped_vault_key, privateKeyPem);
+            return vaultKeyCache;
+        }
+        catch {
+            return null; // 404 = no grant → operate on opaque ids only
+        }
+    }
+    const getVaultKey = deps.getVaultKey ?? defaultGetVaultKey;
+    // CXF dual-read (identity-ontology P1): account blobs may now be a CXF v1.0
+    // Item (cxf-v1.0-rd-20250313) instead of the legacy flat metadata object.
+    // Vendored mappers (this package can't import ../../lib). Password is folded
+    // into basic-auth but intentionally NOT surfaced here — it's a secret, gated
+    // to the dedicated credential path, never in default account reads.
+    function isCxfItem(v) {
+        return !!v && typeof v === 'object' && Array.isArray(v.credentials) && typeof v.type === 'string';
+    }
+    function cxfItemToFields(item) {
+        const creds = item.credentials || [];
+        const ba = creds.find(c => c?.type === 'basic-auth');
+        const cf = creds.find(c => c?.type === 'custom-fields');
+        const notesField = (cf?.fields || []).find((f) => f?.designation === 'notes' || f?.label === 'Notes');
+        const categoryExt = (item.extensions || []).find((e) => e?.name === 'decoys.me/category');
+        const urls = ba?.urls || [];
+        // NOTE: `structured` (address/credit-card) is intentionally NOT surfaced here.
+        // This feeds the agent-facing account_get/account_list reads, and a card's
+        // number/CVV are secrets — gated like the password (see decryptAccount), never
+        // in default reads. The re-seal source (decryptAccountFull) adds it separately.
+        return {
+            service_name: item.title === 'Untitled' ? null : item.title,
+            service_url: urls[0] ?? null,
+            login_url: urls[1] ?? null,
+            username: ba?.username?.value ?? null,
+            category: categoryExt?.value ?? null,
+            notes: notesField?.value ?? null,
+            tags: (Array.isArray(item.tags) && item.tags.length) ? item.tags : null,
+        };
+    }
+    // Agent-facing safe projection of a FLAT v1 blob. CRITICAL: a flat blob holds
+    // password / customFields / structured at top level. account_update re-seals as
+    // flat v1, so without this projection the very next account_get/account_list
+    // (or the update's own response) would leak the password + card data to the
+    // agent context. Mirror cxfItemToFields' key set exactly so flat and CXF reads
+    // expose the SAME safe fields — secrets stay gated to the dedicated paths.
+    const SAFE_META_KEYS = ['service_name', 'service_url', 'login_url', 'username', 'category', 'notes', 'tags'];
+    function flatToSafeFields(decoded) {
+        const out = {};
+        for (const k of SAFE_META_KEYS)
+            if (decoded[k] !== undefined)
+                out[k] = decoded[k];
+        return out;
+    }
+    /** Merge decrypted metadata over a row; strips the blob. Legacy plaintext rows pass through. */
+    async function decryptAccount(row) {
+        const blob = row.encrypted_data;
+        if (!blob) {
+            const { encrypted_data, ...rest } = row;
+            return rest;
+        }
+        const vk = await getVaultKey();
+        if (!vk)
+            return { id: row.id, agent_label: row.agent_label ?? null, _encrypted: true,
+                _note: 'No vault-key grant on this agent — re-pair from a device to decrypt.' };
+        try {
+            const decoded = openVault(blob, vk);
+            const meta = isCxfItem(decoded) ? cxfItemToFields(decoded) : flatToSafeFields(decoded);
+            const { encrypted_data, ...rest } = row;
+            return { ...rest, ...meta };
+        }
+        catch {
+            return { ...row, _decrypt_failed: true };
+        }
+    }
+    /** Like decryptAccount but INCLUDES the password — for internal re-seal only
+     *  (account_update read-modify-write); never returned to the agent context. */
+    async function decryptAccountFull(row) {
+        const blob = row.encrypted_data;
+        if (!blob) {
+            const { encrypted_data, ...rest } = row;
+            return rest;
+        }
+        const vk = await getVaultKey();
+        if (!vk)
+            return {};
+        try {
+            const decoded = openVault(blob, vk);
+            if (isCxfItem(decoded)) {
+                const creds = decoded.credentials || [];
+                const ba = creds.find(c => c?.type === 'basic-auth');
+                const cf = creds.find(c => c?.type === 'custom-fields');
+                const kindFromCxf = (ft, d) => {
+                    if (ft === 'email')
+                        return 'email';
+                    if (ft === 'number')
+                        return 'number';
+                    if (ft === 'date')
+                        return 'date';
+                    if (ft === 'concealed-string')
+                        return 'secret';
+                    if (ft === 'string' && d === 'tel')
+                        return 'phone';
+                    if (ft === 'string' && d === 'url')
+                        return 'url';
+                    if (ft === 'string' && d === 'cf-note')
+                        return 'note';
+                    return 'custom';
+                };
+                const userFields = ((cf?.fields) || [])
+                    .filter((f) => f?.designation !== 'notes')
+                    .map((f) => ({
+                    id: f.id ?? '', label: f.label ?? '', value: f.value,
+                    secret: f.fieldType === 'concealed-string',
+                    kind: kindFromCxf(f.fieldType, f.designation),
+                }));
+                const structured = cxfItemToStructured(decoded);
+                return {
+                    ...cxfItemToFields(decoded),
+                    password: ba?.password?.value ?? null,
+                    customFields: userFields.length ? userFields : null,
+                    // Full structured (incl. card number/CVV) — this object is the re-seal
+                    // source and is NEVER returned to the agent context; omitting it dropped
+                    // the user's address/card on any metadata update.
+                    structured: structured.length ? structured : null,
+                };
+            }
+            return decoded; // legacy v1 flat object already includes password + customFields + structured
+        }
+        catch {
+            return {};
+        }
+    }
+    /** Page through /accounts applying only non-content (server-safe) filters. */
+    async function fetchAllAccounts(serverParams, cap = 500) {
+        const out = [];
+        let cursor;
+        do {
+            const p = new URLSearchParams(serverParams);
+            p.set('limit', '100');
+            if (cursor)
+                p.set('cursor', cursor);
+            const page = await call(`/accounts?${p}`);
+            out.push(...(page.accounts ?? []));
+            cursor = page.pagination?.next_cursor;
+        } while (cursor && out.length < cap);
+        return out;
+    }
+    // ── Decoy management ────────────────────────────────────────────────────────
+    server.tool('decoy_list', 'List decoy email identities with filtering, sorting, and pagination.', {
+        status: z.enum(['active', 'inactive', 'all']).default('active')
+            .describe('Filter by status (default: active)'),
+        search: z.string().optional()
+            .describe('Search agent_label (e.g. "nike")'),
+        sort_by: z.enum(['created_at', 'updated_at']).default('created_at')
+            .describe('Sort column (default: created_at)'),
+        order: z.enum(['asc', 'desc']).default('desc')
+            .describe('Sort direction (default: desc)'),
+        limit: z.number().int().min(1).max(100).default(20)
+            .describe('Max results (default: 20, max: 100)'),
+        cursor: z.string().optional()
+            .describe('Opaque cursor from previous page\'s pagination.next_cursor'),
+        created_after: z.string().optional()
+            .describe('ISO8601 — only decoys created after this date'),
+        created_before: z.string().optional()
+            .describe('ISO8601 — only decoys created before this date'),
+    }, async ({ status, search, sort_by, order, limit, cursor, created_after, created_before }) => {
+        const params = new URLSearchParams({ status, sort_by, order, limit: String(limit) });
+        if (search)
+            params.set('search', search);
+        if (cursor)
+            params.set('cursor', cursor);
+        if (created_after)
+            params.set('created_after', created_after);
+        if (created_before)
+            params.set('created_before', created_before);
+        return ok(await call(`/decoys?${params}`));
+    });
+    server.tool('decoy_get', 'Get a single decoy identity by ID. Returns agent_label if set.', {
+        decoy_id: z.string().uuid().describe('The decoy ID'),
+    }, async ({ decoy_id }) => ok(await call(`/decoys/${decoy_id}`)));
+    server.tool('decoy_create', 'Create a new decoy email identity for a service', {
+        service_name: z.string().min(1).max(200).describe('Name of the service (e.g. "Nike", "OpenSource Newsletter"). Required, 1-200 chars.'),
+        service_url: z.string().url().max(2000).optional().describe('URL of the service (must include https://)'),
+        avatar: z.string().optional()
+            .describe('Avatar variant name. Options: cool, chef, space, wizard, pirate, dj, baseball, floral-crown, bucket, chic-berret, chic-big-hat, chic-headband, headphones, cowboy, detective, explorer, jester, luchador, ninja, pilot, pinkrock, queen, samurai, ski, snorkle, steampunk, super, viking, beekeeper, firefighter, mariachi, nurse, pharoh, robot, aqua, farmer, gladiator, knight, painter, angel. Random if omitted.'),
+        label: z.string().max(200).optional()
+            .describe('Short plaintext reference tag visible to agents (e.g. "nike-promo"). Not user PII — stored unencrypted. Max 200 chars.'),
+        forward_enabled: z.boolean().optional()
+            .describe('Whether to forward emails to a real email address (default: false)'),
+        forwarding_email_id: z.string().uuid().optional()
+            .describe('ID of the forwarding email address to use (from forwarding_get). Required if forward_enabled is true.'),
+    }, async ({ service_name, service_url, avatar, label, forward_enabled, forwarding_email_id }) => ok(await call('/decoys', 'POST', {
+        service_name,
+        ...(service_url && { service_url }),
+        ...(avatar && { avatar }),
+        ...(label && { label }),
+        ...(forward_enabled && forwarding_email_id && { forward_enabled: true, forwarding_email_id }),
+    })));
+    server.tool('decoy_update', 'Update a decoy\'s avatar, service name, or label. Only provided fields are changed; omitted fields are left unchanged. ' +
+        'When changing avatar or service_name, the server re-encrypts metadata with the user\'s public key.', {
+        decoy_id: z.string().uuid().describe('The decoy ID to update'),
+        avatar: z.string().optional()
+            .describe('New avatar variant name. Options: cool, chef, space, wizard, pirate, dj, baseball, floral-crown, bucket, chic-berret, chic-big-hat, chic-headband, headphones, cowboy, detective, explorer, jester, luchador, ninja, pilot, pinkrock, queen, samurai, ski, snorkle, steampunk, super, viking, beekeeper, firefighter, mariachi, nurse, pharoh, robot, aqua, farmer, gladiator, knight, painter, angel'),
+        service_name: z.string().min(1).max(200).optional()
+            .describe('New service name (1-200 chars)'),
+        label: z.string().max(200).optional()
+            .describe('New label for the decoy (agent-visible plaintext tag, max 200 chars)'),
+    }, async ({ decoy_id, avatar, service_name, label }) => ok(await call(`/decoys/${decoy_id}`, 'PATCH', {
+        ...(avatar && { avatar }),
+        ...(service_name && { service_name }),
+        ...(label !== undefined && { label }),
+    })));
+    server.tool('decoy_disable', 'Disable a decoy email so it stops receiving mail. Reversible — use decoy_enable to turn it back on. ' +
+        'The decoy row and its history are preserved.', { decoy_id: z.string().uuid().describe('The decoy ID to disable') }, async ({ decoy_id }) => ok(await call(`/decoys/${decoy_id}`, 'PATCH', { status: 'inactive' })));
+    server.tool('decoy_enable', 'Re-enable a previously disabled decoy so it starts receiving mail again.', { decoy_id: z.string().uuid().describe('The decoy ID to enable') }, async ({ decoy_id }) => ok(await call(`/decoys/${decoy_id}`, 'PATCH', { status: 'active' })));
+    server.tool('decoy_burn', 'Permanently delete a decoy and its message history. IRREVERSIBLE. Use decoy_disable to just stop mail while preserving data.', { decoy_id: z.string().uuid().describe('The decoy ID to burn (hard-delete)') }, async ({ decoy_id }) => ok(await call(`/decoys/${decoy_id}`, 'DELETE')));
+    // ── Batch operations ────────────────────────────────────────────────────────
+    server.tool('decoy_burn_batch', 'Permanently delete multiple decoys in one call. IRREVERSIBLE. Max 20 per request. Use decoy_disable for a reversible per-decoy toggle.', {
+        decoy_ids: z.array(z.string().uuid()).min(1).max(20)
+            .describe('Array of decoy IDs to burn (hard-delete, max 20)'),
+    }, async ({ decoy_ids }) => ok(await call('/decoys/batch/burn', 'POST', { decoy_ids })));
+    server.tool('decoy_pause_batch', 'Disable email forwarding on multiple decoy identities in one call. Max 20 per request. ' +
+        'Does not disable the decoy itself — mail still arrives, just is not forwarded.', {
+        decoy_ids: z.array(z.string().uuid()).min(1).max(20)
+            .describe('Array of decoy IDs to pause forwarding on (max 20)'),
+    }, async ({ decoy_ids }) => ok(await call('/decoys/batch/pause', 'POST', { decoy_ids })));
+    // ── Notification settings ───────────────────────────────────────────────────
+    server.tool('decoy_notifications_get', 'Get notification settings for a decoy identity', { decoy_id: z.string().uuid().describe('The decoy ID') }, async ({ decoy_id }) => ok(await call(`/decoys/${decoy_id}/notifications`)));
+    server.tool('decoy_notifications_update', 'Update notification settings for a decoy identity', {
+        decoy_id: z.string().uuid().describe('The decoy ID'),
+        notify_all_messages: z.boolean()
+            .describe('When true, push notifications are sent for every message (not just alerts)'),
+    }, async ({ decoy_id, notify_all_messages }) => ok(await call(`/decoys/${decoy_id}/notifications`, 'PATCH', { notify_all_messages })));
+    // ── Inbox ───────────────────────────────────────────────────────────────────
+    server.tool('inbox_list', 'List messages with filtering, sorting, and pagination. Returns metadata only — no email bodies.', {
+        decoy_id: z.string().optional()
+            .describe('Filter to a single decoy ID (legacy — prefer decoy_ids)'),
+        decoy_ids: z.array(z.string()).optional()
+            .describe('Filter to specific decoy IDs (omit for all inboxes)'),
+        is_read: z.boolean().optional()
+            .describe('Filter by read status (true = read, false = unread)'),
+        channel: z.enum(['email', 'sms', 'call']).optional()
+            .describe('Filter by channel'),
+        direction: z.enum(['inbound', 'outbound']).optional()
+            .describe('Filter by direction'),
+        sort_by: z.enum(['received_at']).default('received_at')
+            .describe('Sort column (default: received_at)'),
+        order: z.enum(['asc', 'desc']).default('desc')
+            .describe('Sort direction (default: desc)'),
+        limit: z.number().int().min(1).max(100).default(20)
+            .describe('Max results (default: 20, max: 100)'),
+        cursor: z.string().optional()
+            .describe('Opaque cursor from previous page\'s pagination.next_cursor'),
+        received_after: z.string().optional()
+            .describe('ISO8601 — only messages received after this date'),
+        received_before: z.string().optional()
+            .describe('ISO8601 — only messages received before this date'),
+        sender_domain: z.string().optional()
+            .describe('Filter by sender email domain (parsed from smtp_message_id, e.g. "nike.com")'),
+    }, async ({ decoy_id, decoy_ids, is_read, channel, direction, sort_by, order, limit, cursor, received_after, received_before, sender_domain }) => {
+        const params = new URLSearchParams({ sort_by, order, limit: String(limit) });
+        const ids = decoy_ids ?? (decoy_id ? [decoy_id] : []);
+        if (ids.length > 0)
+            params.set('decoy_ids', ids.join(','));
+        if (is_read !== undefined)
+            params.set('is_read', String(is_read));
+        if (channel)
+            params.set('channel', channel);
+        if (direction)
+            params.set('direction', direction);
+        if (cursor)
+            params.set('cursor', cursor);
+        if (received_after)
+            params.set('received_after', received_after);
+        if (received_before)
+            params.set('received_before', received_before);
+        if (sender_domain)
+            params.set('sender_domain', sender_domain);
+        return ok(await call(`/inbox?${params}`));
+    });
+    server.tool('inbox_get', 'Get metadata for a single message. Does not return email body content.', { message_id: z.string().uuid().describe('The message ID') }, async ({ message_id }) => ok(await call(`/inbox/messages/${message_id}`)));
+    server.tool('message_reply', 'Reply to an existing inbound message. Sends from the decoy\'s email address. ' +
+        'The reply is threaded (In-Reply-To + References headers) with the original message. ' +
+        'Use message_read first to get the subject and context for a meaningful reply. ' +
+        'Pass to/cc/bcc to Reply-All (include additional recipients); when omitted, the reply goes ' +
+        'to the original sender only. Combined recipients (to + cc + bcc) must not exceed 10. ' +
+        'Requires inbox:write scope. At least one of body_text or body_html is required.', {
+        message_id: z.string().uuid().describe('The message ID to reply to (from inbox_list or inbox_get)'),
+        subject: z.string().min(1).max(200)
+            .describe('Reply subject line (required, 1-200 chars — typically "Re: <original subject>")'),
+        body_text: z.string().max(51200).optional()
+            .describe('Plain-text reply body (required if body_html not provided, max 50KB)'),
+        body_html: z.string().max(102400).optional()
+            .describe('HTML reply body (overrides body_text if both provided, max 100KB)'),
+        to: z.union([z.string().email(), z.array(z.string().email()).min(1).max(10)]).optional()
+            .describe('Optional Reply-All override: recipient(s) instead of the original sender'),
+        cc: z.union([z.string().email(), z.array(z.string().email()).max(10)]).optional()
+            .describe('Optional Cc recipient(s) for Reply-All'),
+        bcc: z.union([z.string().email(), z.array(z.string().email()).max(10)]).optional()
+            .describe('Optional Bcc recipient(s)'),
+    }, async ({ message_id, body_text, body_html, subject, to, cc, bcc }) => ok(await call(`/inbox/messages/${message_id}/reply`, 'POST', {
+        subject,
+        ...(body_text && { body_text }),
+        ...(body_html && { body_html }),
+        ...(to && { to }),
+        ...(cc && { cc }),
+        ...(bcc && { bcc }),
+    })));
+    server.tool('message_send', 'Send a new email from a decoy identity (not a reply — starts a new conversation). ' +
+        'Supports to, cc, and bcc recipients. Combined recipients (to + cc + bcc) must not exceed 10. ' +
+        'Requires inbox:write scope. Rate limited to 50 outbound emails per hour. ' +
+        'At least one of body_text or body_html is required.', {
+        decoy_id: z.string().uuid().describe('The decoy ID to send from'),
+        to: z.union([z.string().email(), z.array(z.string().email()).min(1).max(10)])
+            .describe('Recipient email address(es) — string or array of strings'),
+        subject: z.string().min(1).max(200).describe('Email subject line (required, 1-200 chars)'),
+        body_text: z.string().max(51200).optional()
+            .describe('Plain-text email body (required if body_html not provided, max 50KB)'),
+        body_html: z.string().max(102400).optional()
+            .describe('HTML email body (overrides body_text if both provided, max 100KB)'),
+        cc: z.union([z.string().email(), z.array(z.string().email()).max(10)]).optional()
+            .describe('Optional Cc recipient(s) — string or array of strings'),
+        bcc: z.union([z.string().email(), z.array(z.string().email()).max(10)]).optional()
+            .describe('Optional Bcc recipient(s) — string or array of strings'),
+    }, async ({ decoy_id, to, subject, body_text, body_html, cc, bcc }) => ok(await call('/inbox/send', 'POST', {
+        decoy_id,
+        to,
+        subject,
+        ...(body_text && { body_text }),
+        ...(body_html && { body_html }),
+        ...(cc && { cc }),
+        ...(bcc && { bcc }),
+    })));
+    server.tool('message_toggle_read', 'Mark a message as read or unread. Updates the is_read flag on the message.', {
+        message_id: z.string().uuid().describe('The message ID'),
+        is_read: z.boolean().describe('true to mark as read, false to mark as unread'),
+    }, async ({ message_id, is_read }) => ok(await call(`/inbox/messages/${message_id}`, 'PATCH', { is_read })));
+    server.tool('message_delete', 'Permanently delete a message. The message must belong to a decoy owned by the user.', {
+        message_id: z.string().uuid().describe('The message ID to delete'),
+    }, async ({ message_id }) => ok(await call(`/inbox/messages/${message_id}`, 'DELETE')));
+    server.tool('decoy_stats', 'Get per-decoy message statistics: total/unread counts, activity timestamps, and outbound metrics.', { decoy_id: z.string().uuid().describe('The decoy ID') }, async ({ decoy_id }) => ok(await call(`/decoys/${decoy_id}/stats`)));
+    // ── Forwarding ──────────────────────────────────────────────────────────────
+    server.tool('forwarding_get', 'Get the current email forwarding state for a decoy identity', { decoy_id: z.string().uuid().describe('The decoy ID') }, async ({ decoy_id }) => ok(await call(`/forwarding/${decoy_id}`)));
+    server.tool('forwarding_enable', 'Enable email forwarding for a decoy identity to a configured forwarding address', {
+        decoy_id: z.string().uuid().describe('The decoy ID'),
+        forwarding_email_id: z.string().uuid().describe('ID of the forwarding email address to send to'),
+    }, async ({ decoy_id, forwarding_email_id }) => ok(await call(`/forwarding/${decoy_id}`, 'PUT', { forward_enabled: true, forwarding_email_id })));
+    server.tool('forwarding_disable', 'Disable email forwarding for a decoy identity', { decoy_id: z.string().uuid().describe('The decoy ID') }, async ({ decoy_id }) => ok(await call(`/forwarding/${decoy_id}`, 'PUT', { forward_enabled: false, forwarding_email_id: null })));
+    // ── Forwarding emails (CRUD) ───────────────────────────────────────────────
+    server.tool('forwarding_email_list', 'List all forwarding email addresses configured for the user. ' +
+        'These are the real email addresses that decoy emails can be forwarded to.', {}, async () => ok(await call('/forwarding-emails')));
+    server.tool('forwarding_email_add', 'Add a new forwarding email address. A verification email will be sent. ' +
+        'The email must be verified before it can be used for forwarding.', {
+        email: z.string().email().describe('The email address to add for forwarding (e.g. "john@gmail.com")'),
+    }, async ({ email }) => ok(await call('/forwarding-emails', 'POST', { email })));
+    server.tool('forwarding_email_delete', 'Remove a forwarding email address. Cannot delete if any decoys are actively using it for forwarding.', {
+        id: z.string().uuid().describe('The forwarding email ID to delete'),
+    }, async ({ id }) => ok(await call(`/forwarding-emails?id=${id}`, 'DELETE')));
+    // ── Alerts ──────────────────────────────────────────────────────────────────
+    server.tool('alert_list', 'List alerts with filtering, sorting, and pagination.', {
+        decoy_id: z.string().optional()
+            .describe('Filter to a specific decoy (omit for all)'),
+        type: z.string().optional()
+            .describe('Filter by alert type (e.g. security, money, hygiene)'),
+        include_dismissed: z.boolean().default(false)
+            .describe('Include dismissed alerts (default: false)'),
+        sort_by: z.enum(['created_at']).default('created_at')
+            .describe('Sort column (default: created_at)'),
+        order: z.enum(['asc', 'desc']).default('desc')
+            .describe('Sort direction (default: desc)'),
+        limit: z.number().int().min(1).max(100).default(50)
+            .describe('Max results (default: 50, max: 100)'),
+        cursor: z.string().optional()
+            .describe('Opaque cursor from previous page\'s pagination.next_cursor'),
+        created_after: z.string().optional()
+            .describe('ISO8601 — only alerts created after this date'),
+        created_before: z.string().optional()
+            .describe('ISO8601 — only alerts created before this date'),
+    }, async ({ decoy_id, type, include_dismissed, sort_by, order, limit, cursor, created_after, created_before }) => {
+        const params = new URLSearchParams({ sort_by, order, limit: String(limit) });
+        if (decoy_id)
+            params.set('decoy_id', decoy_id);
+        if (type)
+            params.set('type', type);
+        if (include_dismissed)
+            params.set('include_dismissed', 'true');
+        if (cursor)
+            params.set('cursor', cursor);
+        if (created_after)
+            params.set('created_after', created_after);
+        if (created_before)
+            params.set('created_before', created_before);
+        return ok(await call(`/alerts?${params}`));
+    });
+    server.tool('alert_dismiss', 'Dismiss an alert by ID', { alert_id: z.string().uuid().describe('The alert ID to dismiss') }, async ({ alert_id }) => ok(await call(`/alerts?id=${alert_id}`, 'DELETE')));
+    server.tool('alert_dismiss_all', 'Dismiss all undismissed alerts for the user in one call. Returns count of dismissed alerts.', {}, async () => ok(await call('/alerts/batch/dismiss', 'POST', {})));
+    // ── Rules ───────────────────────────────────────────────────────────────────
+    server.tool('rule_list', 'List notification rules for a decoy identity with optional filtering and pagination.', {
+        decoy_id: z.string().uuid().describe('The decoy ID'),
+        is_enabled: z.boolean().optional()
+            .describe('Filter by enabled status'),
+        sort_by: z.enum(['created_at', 'trigger_count']).default('created_at')
+            .describe('Sort column (default: created_at)'),
+        order: z.enum(['asc', 'desc']).default('desc')
+            .describe('Sort direction (default: desc)'),
+        limit: z.number().int().min(1).max(100).default(20)
+            .describe('Max results (default: 20, max: 100)'),
+        cursor: z.string().optional()
+            .describe('Opaque cursor from previous page\'s pagination.next_cursor'),
+    }, async ({ decoy_id, is_enabled, sort_by, order, limit, cursor }) => {
+        const params = new URLSearchParams({ decoy_id, sort_by, order, limit: String(limit) });
+        if (is_enabled !== undefined)
+            params.set('is_enabled', String(is_enabled));
+        if (cursor)
+            params.set('cursor', cursor);
+        return ok(await call(`/rules?${params}`));
+    });
+    server.tool('rule_create', 'Create a notification rule for a decoy identity (e.g. alert when sender matches a pattern)', {
+        decoy_id: z.string().uuid().describe('The decoy ID'),
+        label: z.string().min(1).max(200).describe('Human-readable rule label (1-200 chars)'),
+        pattern: z.string().min(1).max(200).describe('Sender or subject pattern to match (1-200 chars)'),
+    }, async ({ decoy_id, label, pattern }) => ok(await call('/rules', 'POST', { decoy_id, label, pattern })));
+    server.tool('rule_update', 'Update a notification rule\'s label and/or pattern', {
+        rule_id: z.string().uuid().describe('The rule ID to update'),
+        label: z.string().min(1).max(200).optional().describe('New human-readable rule label (1-200 chars)'),
+        pattern: z.string().min(1).optional().describe('New sender or subject pattern to match'),
+    }, async ({ rule_id, label, pattern }) => {
+        const body = {};
+        if (label !== undefined)
+            body.label = label;
+        if (pattern !== undefined)
+            body.pattern = pattern;
+        return ok(await call(`/rules?id=${rule_id}`, 'PATCH', body));
+    });
+    server.tool('rule_delete', 'Delete a notification rule by ID', { rule_id: z.string().uuid().describe('The rule ID to delete') }, async ({ rule_id }) => ok(await call(`/rules?id=${rule_id}`, 'DELETE')));
+    // ── Personal Info ──────────────────────────────────────────────────────────
+    server.tool('personal_info_list', 'List personal info entries (emails, phones, cards, addresses). Returns types, IDs, and counts — not decrypted content.', {}, async () => ok(await call('/personal-info')));
+    server.tool('personal_info_add', 'Add a reusable personal-info entry (email, phone, card, address, name, or date of birth). ' +
+        'Sealed locally with the user\'s vault key — the server stores only ciphertext and the iPhone reads it natively.', {
+        type: z.enum(['email', 'phone', 'card', 'address', 'name', 'birthday']).describe('Type of personal info'),
+        data: z.union([
+            z.object({
+                email: z.string().describe('Email address'),
+                label: z.string().optional().describe('Optional label'),
+            }),
+            z.object({
+                phone: z.string().describe('Phone number'),
+                label: z.string().optional().describe('Optional label'),
+            }),
+            z.object({
+                number: z.string().describe('Card number (only the last 4 are stored)'),
+                expiration: z.string().describe('Expiration date (e.g. "12/25")'),
+                cvv: z.string().optional().describe('CVV code (not stored)'),
+                label: z.string().optional().describe('Optional label'),
+            }),
+            z.object({
+                street: z.string().describe('Street address'),
+                city: z.string().describe('City'),
+                state: z.string().describe('State/province'),
+                zip: z.string().describe('ZIP/postal code'),
+                country: z.string().optional().describe('Country (default: US)'),
+                label: z.string().optional().describe('Optional label'),
+            }),
+            z.object({
+                name: z.string().describe('Full name'),
+                label: z.string().optional().describe('Optional label (e.g. Legal, Preferred)'),
+            }),
+            z.object({
+                date: z.string().describe('Date of birth, YYYY-MM-DD'),
+                label: z.string().optional().describe('Optional label'),
+            }),
+        ]).describe('Data fields — shape depends on type'),
+    }, async ({ type, data }) => {
+        const d = data;
+        const label = d.label ?? '';
+        const vaultKey = await getVaultKey();
+        if (vaultKey) {
+            // Shape the payload to exactly what iOS decryptPersonalInfo expects per
+            // type, then seal with the vault key → an iOS-readable VAULT SealedBlob.
+            // (The legacy server-side RSA path produces blobs iOS cannot decrypt.)
+            let payload;
+            switch (type) {
+                case 'email':
+                    payload = { email: d.email, label };
+                    break;
+                case 'phone':
+                    payload = { phone: d.phone, label };
+                    break;
+                case 'name':
+                    payload = { name: d.name, label };
+                    break;
+                case 'birthday':
+                    payload = { date: d.date, label };
+                    break;
+                case 'address':
+                    payload = { street: d.street, city: d.city, state: d.state, zip: d.zip, label };
+                    break;
+                // Never store the full PAN/CVV — keep only the last four, like the app.
+                case 'card':
+                    payload = { lastFour: (d.number || '').replace(/\D/g, '').slice(-4), cardType: 'Card', expiration: d.expiration, label };
+                    break;
+                default: payload = { ...d, label };
+            }
+            const encrypted_data = sealVault(payload, vaultKey);
+            return ok(await call('/personal-info', 'POST', { type, encrypted_data }));
+        }
+        // No vault grant — fall back to the legacy server-side RSA path (re-pair to seal).
+        return ok(await call('/personal-info', 'POST', { type, data }));
+    });
+    server.tool('personal_info_delete', 'Delete a personal info entry by ID and type', {
+        id: z.string().uuid().describe('The personal info entry ID'),
+        type: z.enum(['email', 'phone', 'card', 'address', 'name', 'birthday']).describe('Type of personal info'),
+    }, async ({ id, type }) => ok(await call(`/personal-info?id=${id}&type=${type}`, 'DELETE')));
+    // ── Webhooks ─────────────────────────────────────────────────────────────────
+    server.tool('webhook_register', 'Register a webhook to receive events instead of polling. Payload is metadata only (no E2EE content). Signature sent in X-Decoy-Signature header.', {
+        url: z.string().url().describe('HTTPS URL to deliver events to'),
+        events: z.array(z.enum([
+            'message.received', 'message.sent', 'message.delivered', 'message.bounced',
+            'alert.triggered', 'alert.dismissed',
+            'decoy.burned', 'decoy.disabled', 'decoy.enabled', 'decoy.created', 'decoy.paused',
+        ])).min(1)
+            .describe('Event types to subscribe to'),
+        secret: z.string().min(16)
+            .describe('Secret for HMAC-SHA256 signature verification (min 16 chars)'),
+    }, async ({ url, events, secret }) => ok(await call('/webhooks', 'POST', { url, events, secret })));
+    server.tool('webhook_list', 'List webhook registrations with optional filtering.', {
+        active: z.boolean().optional()
+            .describe('Filter by active status'),
+        event: z.string().optional()
+            .describe('Filter to webhooks subscribed to this event (e.g. message.received)'),
+        sort_by: z.enum(['created_at', 'last_triggered_at', 'failure_count']).default('created_at')
+            .describe('Sort column (default: created_at)'),
+        order: z.enum(['asc', 'desc']).default('desc')
+            .describe('Sort direction (default: desc)'),
+        limit: z.number().int().min(1).max(100).default(20)
+            .describe('Max results (default: 20, max: 100)'),
+        cursor: z.string().optional()
+            .describe('Opaque cursor from previous page\'s pagination.next_cursor'),
+    }, async ({ active, event, sort_by, order, limit, cursor }) => {
+        const params = new URLSearchParams({ sort_by, order, limit: String(limit) });
+        if (active !== undefined)
+            params.set('active', String(active));
+        if (event)
+            params.set('event', event);
+        if (cursor)
+            params.set('cursor', cursor);
+        return ok(await call(`/webhooks?${params}`));
+    });
+    server.tool('webhook_delete', 'Remove a webhook registration by ID', { webhook_id: z.string().uuid().describe('The webhook ID to delete') }, async ({ webhook_id }) => ok(await call(`/webhooks?id=${webhook_id}`, 'DELETE')));
+    // ── Profile ─────────────────────────────────────────────────────────────────
+    server.tool('profile_stats', 'Get protection score and aggregate stats across all identities', {}, async () => {
+        const data = await call('/profile');
+        const active = data.stats?.active_decoys ?? 0;
+        const protection_score = Math.min(100, Math.round((active / Math.max(active + 1, 5)) * 100));
+        return ok({ stats: data.stats, protection_score });
+    });
+    // ── Approvals ────────────────────────────────────────────────────────────────
+    server.tool('request_approval', 'Request user approval via push notification before taking a sensitive action. ' +
+        'Sends a push to the user\'s iPhone with Approve/Deny buttons. ' +
+        'Returns ephemeral_token on approval (valid 60s). Throws on denial or expiry. ' +
+        'Use this before decoy_burn (hard-delete), decoy_burn_batch, forwarding changes, rule creation, or webhook registration. ' +
+        'decoy_disable / decoy_enable are reversible and do not require approval.', {
+        action: z.enum(['decoy.burn', 'decoy.burn_batch', 'forwarding.change', 'rule.create', 'webhook.register'])
+            .describe('The sensitive action requiring approval'),
+        description: z.string().max(200)
+            .describe('Human-readable description shown verbatim in the push notification (max 200 chars). E.g. "Burn bright.stone42@decoys.me — detected in breach alert"'),
+        metadata: z.record(z.unknown()).optional()
+            .describe('Optional context passed to the approval request: { decoy_id?, decoy_email?, count? }'),
+    }, async ({ action, description, metadata }) => {
+        // Create the approval request
+        const req = await call('/approvals', 'POST', { action, description, ...(metadata && { metadata }) });
+        // Poll for up to 5 minutes (150 × 2s)
+        for (let i = 0; i < 150; i++) {
+            await new Promise(r => setTimeout(r, 2000));
+            const status = await call(`/approvals?id=${req.id}`);
+            if (status.status === 'approved') {
+                return ok({ approved: true, ephemeral_token: status.ephemeral_token });
+            }
+            if (status.status === 'denied') {
+                throw new Error('User denied the request');
+            }
+            if (status.status === 'expired') {
+                throw new Error('Approval request expired without a response');
+            }
+        }
+        throw new Error('Approval timed out after 5 minutes');
+    });
+    // ── Accounts ─────────────────────────────────────────────────────────────────
+    // Accounts represent the user's relationship with a service.
+    // A decoy email is a privacy protection layer on top — not the account itself.
+    // This mirrors password-manager semantics: track the service, protect the identity.
+    server.tool('account_list', 'List accounts with filtering, sorting, and pagination. Each account represents a service relationship.', {
+        status: z.enum(['active', 'inactive', 'all']).default('active')
+            .describe('Filter by account status (default: active)'),
+        category: z.string().optional()
+            .describe('Filter by category: shopping, social, streaming, finance, travel, food, health, productivity, other'),
+        has_decoy: z.boolean().optional()
+            .describe('Filter to accounts with (true) or without (false) a linked decoy email'),
+        search: z.string().optional()
+            .describe('Search service_name, username, or agent_label'),
+        sort_by: z.enum(['created_at', 'updated_at', 'service_name']).default('created_at')
+            .describe('Sort column (default: created_at)'),
+        order: z.enum(['asc', 'desc']).default('desc')
+            .describe('Sort direction (default: desc)'),
+        limit: z.number().int().min(1).max(100).default(20)
+            .describe('Max results (default: 20, max: 100)'),
+        cursor: z.string().optional()
+            .describe('Opaque cursor from previous page\'s pagination.next_cursor'),
+        created_after: z.string().optional()
+            .describe('ISO8601 — only accounts created after this date'),
+        created_before: z.string().optional()
+            .describe('ISO8601 — only accounts created before this date'),
+    }, async ({ status, category, has_decoy, search, sort_by, order, limit, created_after, created_before }) => {
+        // SealedBlob (Phase 3b): only non-content filters run server-side; content
+        // search / category / name-sort run HERE after decrypting each blob locally.
+        const serverParams = new URLSearchParams({ status });
+        if (has_decoy !== undefined)
+            serverParams.set('has_decoy', String(has_decoy));
+        if (created_after)
+            serverParams.set('created_after', created_after);
+        if (created_before)
+            serverParams.set('created_before', created_before);
+        const raw = await fetchAllAccounts(serverParams);
+        let items = await Promise.all(raw.map(decryptAccount));
+        if (search) {
+            const q = search.toLowerCase();
+            items = items.filter(a => [a.service_name, a.username, a.notes, a.agent_label]
+                .some(v => typeof v === 'string' && v.toLowerCase().includes(q)));
+        }
+        if (category)
+            items = items.filter(a => a.category === category);
+        const dir = order === 'asc' ? 1 : -1;
+        items.sort((a, b) => dir * String(a[sort_by] ?? '').localeCompare(String(b[sort_by] ?? '')));
+        const total = items.length;
+        const capped = raw.length >= 500;
+        return ok({
+            accounts: items.slice(0, limit),
+            count: Math.min(items.length, limit),
+            total,
+            ...(capped && { note: 'Fetched accounts capped at 500; narrow filters for completeness.' }),
+        });
+    });
+    server.tool('account_get', 'Get a single account by ID, including its linked decoy email hash if protected.', { account_id: z.string().uuid().describe('The account ID') }, async ({ account_id }) => ok(await decryptAccount(await call(`/accounts/${account_id}`))));
+    server.tool('account_create', 'Create an account record for a service. Optionally link an existing decoy email by providing decoy_id. ' +
+        'To auto-create and attach a new decoy email, use account_protect after creating the account.', {
+        service_name: z.string().min(1).max(200).describe('Name of the service (e.g. "Nike", "GitHub"). Required, 1-200 chars.'),
+        service_url: z.string().url().max(2000).optional().describe('URL of the service (must include https://)'),
+        login_url: z.string().url().max(2000).optional().describe('Login page URL (must include https://)'),
+        username: z.string().max(200).optional()
+            .describe('Login identifier for this account — typically the email used to sign up. Not a password.'),
+        category: z.enum(['shopping', 'social', 'streaming', 'finance', 'travel', 'food', 'health', 'productivity', 'other']).optional()
+            .describe('Account category for organization'),
+        notes: z.string().max(2000).optional().describe('Free-text notes about this account (max 2000 chars)'),
+        tags: z.array(z.string().min(1).max(50)).max(20).optional()
+            .describe('Tags for organization (max 20 tags, each max 50 chars)'),
+        two_factor_enabled: z.boolean().optional()
+            .describe('Whether 2FA is enabled on this account'),
+        agent_label: z.string().max(200).optional()
+            .describe('Stable plaintext tag for agent references (e.g. "nike-account")'),
+        decoy_id: z.string().uuid().optional()
+            .describe('Link an existing decoy email to this account at creation time'),
+        structured: STRUCTURED_INPUT_SCHEMA.optional()
+            .describe('Multi-part typed fields. Each: { kind: "address"|"credit-card", label?, values }. ' +
+            'values keys = CXF member names — address: streetAddress, apt, city, territory, postalCode, country; ' +
+            'credit-card: number, fullName, expiryDate (YYYY-MM), verificationNumber.'),
+    }, async ({ service_name, service_url, login_url, username, category, notes, tags, two_factor_enabled, agent_label, decoy_id, structured }) => {
+        // SealedBlob (Phase 3b): seal sensitive metadata locally with the vault key
+        // so the server only ever sees ciphertext. agent_label/decoy_id/2FA stay top-level.
+        const vk = await getVaultKey();
+        const normStructured = normalizeStructured(structured);
+        const body = {
+            ...(two_factor_enabled !== undefined && { two_factor_enabled }),
+            ...(agent_label && { agent_label }),
+            ...(decoy_id && { decoy_id }),
+        };
+        if (vk) {
+            body.encrypted_data = sealVault({ service_name, service_url: service_url ?? null, login_url: login_url ?? null,
+                username: username ?? null, category: category ?? null, notes: notes ?? null, tags: tags ?? null,
+                ...(normStructured && { structured: normStructured }) }, vk);
+        }
+        else {
+            // No grant — fall back to plaintext (server-visible). Re-pair to seal.
+            Object.assign(body, { service_name,
+                ...(service_url && { service_url }), ...(login_url && { login_url }), ...(username && { username }),
+                ...(category && { category }), ...(notes && { notes }), ...(tags && { tags }) });
+        }
+        return ok(await decryptAccount(await call('/accounts', 'POST', body)));
+    });
+    server.tool('account_update', 'Update account metadata. Only provided fields are changed; omitted fields are left unchanged.', {
+        account_id: z.string().uuid().describe('The account ID to update'),
+        service_name: z.string().min(1).max(200).optional().describe('Updated service name (1-200 chars)'),
+        service_url: z.string().url().max(2000).optional().describe('Updated service URL (must include https://)'),
+        login_url: z.string().url().max(2000).optional().describe('Updated login page URL (must include https://)'),
+        username: z.string().max(200).optional().describe('Updated login identifier (max 200 chars)'),
+        category: z.enum(['shopping', 'social', 'streaming', 'finance', 'travel', 'food', 'health', 'productivity', 'other']).optional()
+            .describe('Updated category'),
+        notes: z.string().max(2000).optional().describe('Updated notes (max 2000 chars)'),
+        tags: z.array(z.string().min(1).max(50)).max(20).optional()
+            .describe('Updated tags (max 20 tags, each max 50 chars)'),
+        two_factor_enabled: z.boolean().optional()
+            .describe('Whether 2FA is enabled on this account'),
+        agent_label: z.string().max(200).optional().describe('Updated agent label (max 200 chars)'),
+        status: z.enum(['active', 'inactive']).optional().describe('Updated account status'),
+        structured: STRUCTURED_INPUT_SCHEMA.optional()
+            .describe('Replace the multi-part typed fields (address/credit-card). Omit to leave unchanged; ' +
+            'pass [] to clear. Same shape as account_create.structured.'),
+    }, async ({ account_id, ...fields }) => {
+        // SealedBlob (Phase 3b): metadata is one sealed blob, so an update is a
+        // read-modify-write — decrypt current, merge provided fields, re-seal.
+        const { status, agent_label, two_factor_enabled, ...metaFields } = fields;
+        // Normalize provided structured (stamp ids) so it round-trips into the blob.
+        // `[]` is a deliberate clear; undefined means "leave current" (pick handles it).
+        if (metaFields.structured !== undefined) {
+            metaFields.structured = normalizeStructured(metaFields.structured) ?? [];
+        }
+        const body = {
+            ...(status !== undefined && { status }),
+            ...(agent_label !== undefined && { agent_label }),
+            ...(two_factor_enabled !== undefined && { two_factor_enabled }),
+        };
+        const vk = await getVaultKey();
+        if (vk && Object.keys(metaFields).length > 0) {
+            // Full decrypt (incl. password) as the re-seal source so a metadata-only
+            // update can't strip the password; not returned to the agent.
+            const current = await decryptAccountFull(await call(`/accounts/${account_id}`));
+            const pick = (k) => (metaFields[k] !== undefined ? metaFields[k] : (current[k] ?? null));
+            // One record = one sealed blob: re-seal ALL fields, incl. the password
+            // (folded into the blob like a decoy). Omitting `password` here would
+            // strip an account's password on any metadata update — the exact
+            // bespoke-scheme fragmentation we must never reintroduce.
+            body.encrypted_data = sealVault({
+                service_name: pick('service_name'), service_url: pick('service_url'), login_url: pick('login_url'),
+                username: pick('username'), category: pick('category'), notes: pick('notes'), tags: pick('tags'),
+                password: pick('password'), customFields: pick('customFields'),
+                // Preserve multi-part typed fields (address, credit-card). Omitting this
+                // dropped the user's address/card on ANY agent metadata update — the same
+                // bespoke-scheme data loss we must never reintroduce (cf. password above).
+                structured: pick('structured'),
+            }, vk);
+            // Keep the client-maintained flag accurate: the re-seal preserves the
+            // password, so has_password must reflect whether one is present. (No
+            // password_changed — a metadata update doesn't change the password.)
+            body.has_password = !!pick('password');
+        }
+        else {
+            Object.assign(body, metaFields); // no grant or no metadata change → passthrough
+        }
+        return ok(await decryptAccount(await call(`/accounts/${account_id}`, 'PATCH', body)));
+    });
+    server.tool('account_protect', 'Attach a decoy email to an account as a privacy protection layer. ' +
+        'If decoy_id is provided, links that existing decoy. ' +
+        'If decoy_id is omitted, auto-creates a new decoy email for the service and links it. ' +
+        'Returns the decoy_id and decoy_email (plaintext, only returned at creation time).', {
+        account_id: z.string().uuid().describe('The account ID to protect'),
+        decoy_id: z.string().uuid().optional()
+            .describe('Existing decoy ID to link (optional — omit to auto-create a new decoy email)'),
+    }, async ({ account_id, decoy_id }) => ok(await call(`/accounts/${account_id}/protect`, 'POST', decoy_id ? { decoy_id } : {})));
+    server.tool('account_burn_decoy', 'Permanently delete (burn) the decoy email attached to an account. IRREVERSIBLE. ' +
+        'By default (replace=true), auto-creates and links a fresh decoy email immediately after burning. ' +
+        'Set replace=false to just burn and leave the account unprotected. ' +
+        'Returns the burned decoy ID and, if replaced, the new decoy email (plaintext).', {
+        account_id: z.string().uuid().describe('The account ID whose decoy email should be burned (hard-deleted)'),
+        replace: z.boolean().default(true)
+            .describe('Auto-create and link a new decoy email after burning (default: true)'),
+    }, async ({ account_id, replace }) => ok(await call(`/accounts/${account_id}/burn-decoy`, 'POST', { replace })));
+    // ── Credentials (E2EE password manager) ────────────────────────────────────
+    //
+    // Passwords generated here exist only in MCP server memory until account_set_credential
+    // is called. The MCP server fetches the user's RSA public key, encrypts locally with
+    // RSA-OAEP + AES-256-GCM, and sends only the ciphertext to the API. Plaintext never
+    // travels over any network connection.
+    server.tool('password_generate', 'Generate a strong random password in MCP server memory. ' +
+        'The password is returned to the agent context and is NEVER stored or sent anywhere automatically. ' +
+        'Pass it to account_set_credential to store it E2EE in the user\'s vault.', {
+        length: z.number().int().min(8).max(128).default(20)
+            .describe('Password length (default: 20)'),
+        symbols: z.boolean().default(true)
+            .describe('Include symbols like !@#$%^&* (default: true)'),
+        memorable: z.boolean().default(false)
+            .describe('Generate a memorable word-based passphrase instead of random chars (default: false)'),
+    }, async ({ length, symbols, memorable }) => {
+        let password;
+        if (memorable) {
+            // Word-based passphrase: AdjectiveNounNumber (e.g. "correct-horse-42")
+            const words = ['correct', 'horse', 'battery', 'staple', 'purple', 'monkey',
+                'swift', 'cloud', 'river', 'stone', 'frost', 'ember',
+                'lunar', 'solar', 'ocean', 'forest', 'amber', 'cedar'];
+            const w1 = words[Math.floor(Math.random() * words.length)];
+            const w2 = words[Math.floor(Math.random() * words.length)];
+            const w3 = words[Math.floor(Math.random() * words.length)];
+            const num = Math.floor(Math.random() * 9000) + 1000;
+            password = `${w1}-${w2}-${w3}-${num}`;
+        }
+        else {
+            const alpha = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+            const sym = '!@#$%^&*()-_=+[]{}|;:,.<>?';
+            const charset = symbols ? alpha + sym : alpha;
+            const bytes = new Uint8Array(length);
+            crypto.getRandomValues(bytes);
+            password = Array.from(bytes).map(b => charset[b % charset.length]).join('');
+        }
+        return ok({ password, length: password.length, has_symbols: symbols });
+    });
+    server.tool('account_set_credential', 'Store a password for an account using end-to-end encryption. ' +
+        'The MCP server fetches the user\'s RSA public key, encrypts the password locally ' +
+        '(RSA-OAEP + AES-256-GCM), and sends only the encrypted blob to the API. ' +
+        'Plaintext never leaves this process over any network connection. ' +
+        'After storage, the user\'s iPhone receives a silent push and syncs the credential ' +
+        'to AutoFill and the Safari extension automatically.', {
+        account_id: z.string().uuid().describe('The account ID to store the credential for'),
+        password: z.string().min(1).describe('The plaintext password to encrypt and store'),
+    }, async ({ account_id, password }) => {
+        const vaultKey = await getVaultKey();
+        if (vaultKey) {
+            // One blob (SealedBlob): fold the password into the SAME encrypted_data as
+            // the rest of the account (read-modify-write), exactly like the iOS app —
+            // retiring the bespoke encrypted_password column write. The server can't
+            // read the blob, so we set the client-maintained has_password flag.
+            const current = await decryptAccountFull(await call(`/accounts/${account_id}`));
+            const keep = (k) => current[k] ?? null;
+            const encrypted_data = sealVault({
+                service_name: keep('service_name'), service_url: keep('service_url'), login_url: keep('login_url'),
+                username: keep('username'), category: keep('category'), notes: keep('notes'), tags: keep('tags'),
+                password,
+                customFields: keep('customFields'), structured: keep('structured'),
+            }, vaultKey);
+            const result = await call(`/accounts/${account_id}`, 'PATCH', { encrypted_data, has_password: true, password_changed: true });
+            // decryptAccount returns the SAFE projection — never echoes the password back.
+            return ok(await decryptAccount(result));
+        }
+        // No vault-key grant — fall back to the legacy RSA-OAEP envelope + the
+        // dedicated credential endpoint (encrypted_password). Re-pair to seal into
+        // the vault blob.
+        const keyData = await call('/accounts/public-key');
+        const publicKeyDer = Buffer.from(keyData.public_key, 'base64');
+        const pub = createPublicKey({ key: publicKeyDer, format: 'der', type: 'spki' });
+        const aesKey = randomBytes(32);
+        const iv = randomBytes(12);
+        const cipher = createCipheriv('aes-256-gcm', aesKey, iv);
+        const ciphertext = Buffer.concat([cipher.update(password, 'utf-8'), cipher.final(), cipher.getAuthTag()]);
+        const encryptedAesKey = publicEncrypt({ key: pub, padding: constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' }, aesKey);
+        const keyLenBuf = Buffer.alloc(2);
+        keyLenBuf.writeUInt16BE(encryptedAesKey.length, 0);
+        const encrypted_password = Buffer.concat([keyLenBuf, encryptedAesKey, iv, ciphertext]).toString('base64');
+        const result = await call(`/accounts/${account_id}/credential`, 'POST', { encrypted_password });
+        return ok(result);
+    });
+    server.tool('account_credential_status', 'Check whether a stored credential exists for an account, and when it was last updated. ' +
+        'Returns has_password (boolean) and password_last_changed (ISO 8601 or null). ' +
+        'Never returns the encrypted blob or any decrypted value.', {
+        account_id: z.string().uuid().describe('The account ID to check'),
+    }, async ({ account_id }) => ok(await call(`/accounts/${account_id}/credential/status`)));
+    server.tool('message_read', '[Deprecated — prefer message_unlock] Request decrypted content for one or more messages via the E2EE content bridge. ' +
+        'Requires inbox:content (legacy) or message.unlock (canonical) scope AND agent_public_key registered during pairing. ' +
+        '\n\nFlow: creates a content request → sends APNs push to user\'s iPhone → user approves ' +
+        '→ iOS app decrypts with user private key, re-encrypts for this agent → poll returns ' +
+        'agent_encrypted_content (base64) per message → decrypt with your agent private key. ' +
+        '\n\nThe server never sees plaintext. Two ciphertexts per message at most. ' +
+        '\n\nDecryption: RSA-OAEP-SHA256 for AES key, AES-256-GCM for content (same format as ' +
+        'existing account_set_credential). ' +
+        '\n\nReturns: items[].{ message_id, from, subject, text, html } on approval, or throws on deny/expire. subject/from decrypted on-device — server never sees them.', {
+        message_ids: z.array(z.string().uuid())
+            .min(1).max(20)
+            .describe('Array of 1–20 message UUIDs to decrypt (from inbox_list or inbox_get)'),
+        reason: z.string().max(200).optional()
+            .describe('Optional plain-text reason shown to user in the approval notification. E.g. "Summarize your inbox"'),
+        poll_timeout_seconds: z.number().int().min(10).max(300).default(300).optional()
+            .describe('How long to poll for approval (default 300s / 5 minutes)'),
+    }, async ({ message_ids, reason, poll_timeout_seconds = 300 }) => {
+        if (!privateKeyPem) {
+            throw new Error('message_read requires the MCP server to have an agent keypair. ' +
+                'Delete ~/.decoy/mcp-token and restart the server to re-pair with a keypair.');
+        }
+        // Create the content request
+        const req = await call('/content', 'POST', { message_ids, reason });
+        const maxAttempts = Math.ceil(poll_timeout_seconds / 2);
+        // Poll until ready, denied, or expired
+        for (let i = 0; i < maxAttempts; i++) {
+            await new Promise(r => setTimeout(r, 2000));
+            const result = await call(`/content/${req.id}`);
+            if (result.status === 'ready') {
+                if (!result.items || result.items.length === 0) {
+                    throw new Error('Content request approved but no items returned (already consumed or no messages decrypted)');
+                }
+                // Decrypt each item and parse the structured content from the iOS content bridge.
+                // The bridge now sends { from, subject, text, html } — same fields as any email API.
+                const decrypted = result.items.map(item => {
+                    try {
+                        const raw = decryptAgentContent(item.agent_encrypted_content, privateKeyPem);
+                        let parsed;
+                        try {
+                            parsed = JSON.parse(raw);
+                        }
+                        catch {
+                            // Fallback for old-format blobs that contain raw text
+                            parsed = { text: raw };
+                        }
+                        return {
+                            message_id: item.message_id,
+                            from: parsed.from ?? null,
+                            subject: parsed.subject ?? null,
+                            text: parsed.text ?? null,
+                            html: parsed.html ?? null,
+                        };
+                    }
+                    catch {
+                        return {
+                            message_id: item.message_id,
+                            from: null, subject: null, text: '[decryption failed]', html: null,
+                        };
+                    }
+                });
+                return ok(decrypted);
+            }
+            if (result.status === 'denied') {
+                throw new Error('User denied the content access request');
+            }
+            if (result.status === 'expired') {
+                throw new Error('Content access request expired before user responded');
+            }
+        }
+        throw new Error(`Content access request timed out after ${poll_timeout_seconds}s waiting for user approval`);
+    });
+    // ── Unified unlock bridge (messages / accounts / personal info) ─────────────
+    // The polymorphic /api/agent/unlock endpoint replaces message_read and adds
+    // credential + personal-info reads, with one approval UX, one wire format,
+    // and one consumed-once envelope per kind.
+    async function runUnlock(kind, target, reason, pollTimeoutSeconds) {
+        if (!privateKeyPem) {
+            throw new Error('unlock tools require the MCP server to have an agent keypair. ' +
+                'Delete ~/.decoy/mcp-token and restart the server to re-pair with a keypair.');
+        }
+        const req = await call('/unlock', 'POST', { target: { kind, ...target }, reason });
+        const maxAttempts = Math.ceil(pollTimeoutSeconds / 2);
+        for (let i = 0; i < maxAttempts; i++) {
+            await new Promise((r) => setTimeout(r, 2000));
+            const result = await call(`/unlock/${req.id}`);
+            if (result.status === 'ready') {
+                if (!result.items || result.items.length === 0) {
+                    throw new Error('Unlock approved but no items returned (already consumed)');
+                }
+                return result.items.map((item) => {
+                    const raw = decryptAgentContent(item.sealed_envelope, privateKeyPem);
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(raw);
+                    }
+                    catch {
+                        parsed = { value: raw };
+                    }
+                    return { target_id: item.target_id, data: parsed };
+                });
+            }
+            if (result.status === 'denied') {
+                throw new Error('User denied the unlock request');
+            }
+            if (result.status === 'expired') {
+                throw new Error('Unlock request expired before user responded');
+            }
+        }
+        throw new Error(`Unlock request timed out after ${pollTimeoutSeconds}s waiting for user approval`);
+    }
+    server.tool('account_unlock', 'Unlock a stored credential via the E2EE bridge. Pass either { domain } ' +
+        '(e.g. "foreup.com") to find the account by hostname or { account_id } for ' +
+        'a direct lookup. Fires an APNs push; user approves on iPhone; sealed ' +
+        'envelope is decrypted in this MCP process and the plaintext credential ' +
+        'returned. Requires account.unlock scope AND agent_public_key registered ' +
+        'during pairing. The credential shape is { username?, password, … } as ' +
+        'encoded by iOS — exact fields depend on the stored account.', {
+        domain: z.string().optional()
+            .describe('Hostname to resolve (e.g. "foreup.com"). Use this OR account_id.'),
+        account_id: z.string().uuid().optional()
+            .describe('Direct account UUID. Use this OR domain.'),
+        reason: z.string().max(200).optional()
+            .describe('Plain-text rationale shown to the user in the approval sheet'),
+        poll_timeout_seconds: z.number().int().min(10).max(300).default(300).optional(),
+    }, async ({ domain, account_id, reason, poll_timeout_seconds = 300 }) => {
+        if (!domain && !account_id)
+            throw new Error('Provide either domain or account_id');
+        if (domain && account_id)
+            throw new Error('Provide either domain or account_id, not both');
+        const items = await runUnlock('account', domain ? { domain } : { id: account_id }, reason, poll_timeout_seconds);
+        return ok(items[0]?.data ?? null);
+    });
+    server.tool('message_unlock', 'Unlock decrypted content for one or more messages via the E2EE bridge. ' +
+        'Preferred over message_read for new code — same E2EE guarantees, unified ' +
+        'flow with account_unlock and personal_unlock. Requires message.unlock ' +
+        'scope (legacy inbox:content also satisfies). Returns items[] with ' +
+        '{ target_id, data: { from, subject, text, html } } per message.', {
+        message_ids: z.array(z.string().uuid()).min(1).max(20)
+            .describe('1–20 message UUIDs to decrypt'),
+        reason: z.string().max(200).optional(),
+        poll_timeout_seconds: z.number().int().min(10).max(300).default(300).optional(),
+    }, async ({ message_ids, reason, poll_timeout_seconds = 300 }) => {
+        const items = await runUnlock('message', { ids: message_ids }, reason, poll_timeout_seconds);
+        return ok(items);
+    });
+    server.tool('personal_unlock', 'Unlock a personal-info field (email, phone, card, address) via the E2EE ' +
+        'bridge. Pass the personal_info_id from personal_info_list. Returns the ' +
+        'decrypted JSON payload as encoded by iOS — shape depends on the field ' +
+        'type. Requires personal.unlock scope AND agent_public_key registered.', {
+        personal_info_id: z.string().uuid().describe('UUID from personal_info_list'),
+        reason: z.string().max(200).optional(),
+        poll_timeout_seconds: z.number().int().min(10).max(300).default(300).optional(),
+    }, async ({ personal_info_id, reason, poll_timeout_seconds = 300 }) => {
+        const items = await runUnlock('personal', { id: personal_info_id }, reason, poll_timeout_seconds);
+        return ok(items[0]?.data ?? null);
+    });
+    // ── Personal alias (subdomain) management ──────────────────────────────────
+    server.tool('subdomain_status', 'Get the user\'s personal alias (subdomain) status — whether claimed, enabled, and disabled alias count.', {}, async () => ok(await call('/subdomain')));
+    server.tool('subdomain_claim', 'Claim a personal alias subdomain (e.g. "yourname" gives you *@yourname.decoys.me). ' +
+        'This is permanent and cannot be changed. The subdomain must be 3-32 chars, ' +
+        'lowercase alphanumeric + hyphens, no leading/trailing hyphens.', {
+        subdomain: z.string().min(3).max(32)
+            .describe('The subdomain to claim (3-32 chars, lowercase alphanumeric + hyphens)'),
+    }, async ({ subdomain }) => ok(await call('/subdomain', 'PUT', { subdomain })));
+    server.tool('subdomain_toggle', 'Enable or disable the personal alias catch-all. When disabled, emails to *@yourname.decoys.me are not received.', {
+        enabled: z.boolean()
+            .describe('true to enable, false to disable'),
+    }, async ({ enabled }) => ok(await call('/subdomain?action=toggle', 'PUT', { enabled })));
+    server.tool('alias_list_disabled', 'List all disabled (blocked) aliases for the personal subdomain. ' +
+        'Disabled aliases no longer receive emails; re-enable them with alias_enable.', {}, async () => ok(await call('/subdomain?action=disabled')));
+    server.tool('alias_disable', 'Disable (block) a personal alias so it no longer receives emails. Reversible — use alias_enable to restore. ' +
+        'For example, disable "netflix" to block netflix@yourname.decoys.me.', {
+        alias: z.string().min(1).max(64)
+            .describe('The alias local part to disable (e.g. "netflix")'),
+    }, async ({ alias }) => ok(await call('/subdomain?action=disable', 'POST', { alias })));
+    server.tool('alias_enable', 'Restore a previously disabled alias so it receives emails again.', {
+        alias: z.string().min(1).max(64)
+            .describe('The alias local part to restore (e.g. "netflix")'),
+    }, async ({ alias }) => ok(await call('/subdomain?action=disable', 'DELETE', { alias })));
+    server.tool('alias_stats', 'Get first-seen dates for personal aliases (when each alias first received an email). ' +
+        'Useful for tracking when a service started sending to a specific alias.', {
+        aliases: z.array(z.string().min(1).max(64)).min(1).max(100)
+            .describe('List of alias names to check (max 100)'),
+    }, async ({ aliases }) => ok(await call('/subdomain?action=alias-stats', 'POST', { aliases })));
+    return server;
+}
+// ── Express server ────────────────────────────────────────────────────────────
+const app = express();
+app.use(express.json());
+const transports = new Map();
+// Resolved at startup — set before MCP routes become active
+let globalToken = '';
+let globalKeyPair = null;
+app.post('/mcp', async (req, res) => {
+    // Per-request Authorization header overrides the global token (advanced/multi-user setups)
+    const authHeader = req.headers.authorization ?? '';
+    const requestToken = authHeader.startsWith('Bearer ') ? authHeader.slice(7).trim() : '';
+    const agentToken = requestToken || globalToken;
+    if (!agentToken) {
+        res.status(503).json({ error: 'Server is not yet paired — restart the MCP server to trigger browser-based pairing on ' + CONNECT_FRONTEND_URL });
+        return;
+    }
+    const existingId = req.headers['mcp-session-id'];
+    let transport = existingId ? transports.get(existingId) : undefined;
+    if (!transport || isInitializeRequest(req.body)) {
+        const sessionId = randomUUID();
+        transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => sessionId,
+            onsessioninitialized: (id) => { transports.set(id, transport); },
+        });
+        transport.onclose = () => transports.delete(existingId ?? sessionId);
+        await buildMcpServer(agentToken, globalKeyPair?.privateKeyPem).connect(transport);
+    }
+    await transport.handleRequest(req, res, req.body);
+});
+app.get('/mcp', async (req, res) => {
+    const transport = transports.get(req.headers['mcp-session-id']);
+    if (!transport) {
+        res.status(404).json({ error: 'Session not found' });
+        return;
+    }
+    await transport.handleRequest(req, res);
+});
+app.delete('/mcp', async (req, res) => {
+    const sessionId = req.headers['mcp-session-id'];
+    const transport = transports.get(sessionId);
+    if (!transport) {
+        res.status(404).json({ error: 'Session not found' });
+        return;
+    }
+    await transport.handleRequest(req, res);
+    transports.delete(sessionId);
+});
+app.get('/health', (_req, res) => res.json({ status: 'ok', version: '2.2.0', mode: DEV_MODE ? 'dev' : 'prod', paired: !!globalToken }));
+// ── Main entry point ──────────────────────────────────────────────────────────
+async function main() {
+    // Start the HTTP server (serves /mcp + /health; pairing UI lives on decoys.me)
+    await new Promise(resolve => app.listen(PORT, resolve));
+    console.error(`Decoy MCP Server v2.2 on :${PORT} (${DEV_MODE ? 'dev' : 'prod'})`);
+    try {
+        globalKeyPair = loadOrGenerateKeyPair();
+        console.error('[Decoy] Agent keypair ready (public key registered during pairing)');
+        globalToken = await resolveToken(globalKeyPair);
+    }
+    catch (err) {
+        console.error('\n❌  Setup failed:', err.message);
+        process.exit(1);
+    }
+    console.error(`Agent API: ${AGENT_API_URL}`);
+    console.error('Ready — connect Claude Desktop to http://localhost:' + PORT + '/mcp');
+}
+// Only boot the HTTP server when run as the entrypoint (`node dist/index.js`).
+// Importing this module (e.g. from tests) must NOT start listening or pair.
+const isEntrypoint = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isEntrypoint) {
+    main();
+}