@viewert/mcp 0.1.1 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # @viewert/mcp
 
-MCP server for [Viewert](https://viewert.com) — expose your Librams (AI context collections) to any MCP-compatible AI client.
+MCP server for [Viewert](https://www.viewert.com) — expose your Librams (AI context collections) to any MCP-compatible AI client.
 
 ## What it does
 
@@ -8,11 +8,43 @@ Connects Claude Desktop, Cursor, Windsurf, or any MCP client to your Viewert Lib
 
 ## Setup
 
-### 1. Get an API key
+### Option A — One-command setup (recommended)
 
-Go to **Settings → API Keys** on Viewert and create a key. Copy it — it's shown only once.
+```bash
+npx @viewert/mcp setup
+```
+
+The interactive wizard will:
+- Install the package globally with the correct binary path
+- Verify your API key against your account
+- Auto-detect Claude Desktop, Cursor, and Windsurf
+- Write the config for whichever clients you choose — without overwriting your other MCP servers
+- Print the exact restart steps for each client
+
+---
+
+### Option B — Manual setup
+
+#### 1. Get an API key
+
+Go to **Settings → API Keys** on [viewert.com](https://www.viewert.com/settings) and create a key. Copy it — it's shown only once.
+
+#### 2. Install the package globally
 
-### 2. Add to your MCP client config
+```bash
+npm install -g @viewert/mcp
+```
+
+Then find the installed binary path — you'll need this for your config:
+
+```bash
+which viewert-mcp
+# e.g. /usr/local/bin/viewert-mcp
+```
+
+> **Why global install?** MCP clients like Claude Desktop launch the server as a subprocess and may not propagate environment variables correctly when using `npx`. A global install with an absolute binary path is the most reliable approach.
+
+#### 3. Add to your MCP client config
 
 **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
@@ -20,8 +52,8 @@ Go to **Settings → API Keys** on Viewert and create a key. Copy it — it's sh
 {
   "mcpServers": {
     "viewert": {
-      "command": "npx",
-      "args": ["-y", "@viewert/mcp"],
+      "command": "/usr/local/bin/viewert-mcp",
+      "args": [],
       "env": {
         "VIEWERT_API_KEY": "vwt_your_key_here"
       }
@@ -30,14 +62,16 @@ Go to **Settings → API Keys** on Viewert and create a key. Copy it — it's sh
 }
 ```
 
-**Cursor / Windsurf** (`.cursor/mcp.json` or `.windsurf/mcp.json` in your project, or global config):
+Replace `/usr/local/bin/viewert-mcp` with the path from `which viewert-mcp`.
+
+**Cursor / Windsurf** (`.cursor/mcp.json` or `.windsurf/mcp.json` in your project):
 
 ```json
 {
   "mcpServers": {
     "viewert": {
-      "command": "npx",
-      "args": ["-y", "@viewert/mcp"],
+      "command": "/usr/local/bin/viewert-mcp",
+      "args": [],
       "env": {
         "VIEWERT_API_KEY": "vwt_your_key_here"
       }
@@ -46,9 +80,11 @@ Go to **Settings → API Keys** on Viewert and create a key. Copy it — it's sh
 }
 ```
 
-### 3. Restart your AI client
+#### 4. Restart your AI client
+
+**Claude Desktop:** Right-click the Claude icon in the menu bar → **Quit** (closing the window is not enough). Reopen Claude. A hammer icon in the toolbar confirms MCP tools are active.
 
-The Viewert tools will appear automatically.
+**Cursor / Windsurf:** Run **Reload Window** from the command palette (`Cmd+Shift+P`).
 
 ---
 
@@ -65,7 +101,7 @@ The Viewert tools will appear automatically.
 | Variable | Required | Default |
 |----------|----------|---------|
 | `VIEWERT_API_KEY` | ✅ Yes | — |
-| `VIEWERT_API_URL` | No | `https://viewert.com/api` |
+| `VIEWERT_API_URL` | No | `https://www.viewert.com/api` |
 
 ---
 

package/dist/index.d.ts

@@ -9,6 +9,6 @@
  *   VIEWERT_API_KEY   — your vwt_... API key from viewert.com/settings
  *
  * Optional env vars:
- *   VIEWERT_API_URL   — defaults to https://viewert.com/api
+ *   VIEWERT_API_URL   — defaults to https://www.viewert.com/api
  */
 export {};

package/dist/index.js

@@ -9,13 +9,13 @@
  *   VIEWERT_API_KEY   — your vwt_... API key from viewert.com/settings
  *
  * Optional env vars:
- *   VIEWERT_API_URL   — defaults to https://viewert.com/api
+ *   VIEWERT_API_URL   — defaults to https://www.viewert.com/api
  */
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 const API_KEY = process.env.VIEWERT_API_KEY;
-const API_BASE = (process.env.VIEWERT_API_URL ?? 'https://viewert.com/api').replace(/\/$/, '');
+const API_BASE = (process.env.VIEWERT_API_URL ?? 'https://www.viewert.com/api').replace(/\/$/, '');
 if (!API_KEY) {
     process.stderr.write('[viewert-mcp] ERROR: VIEWERT_API_KEY is not set.\n' +
         'Generate a key at https://viewert.com/settings and add it to your MCP config.\n');

package/dist/setup.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Viewert MCP Setup CLI
+ *
+ * Interactive setup wizard that installs the Viewert MCP server into
+ * Claude Desktop, Cursor, and/or Windsurf with zero manual config editing.
+ *
+ * Usage:  npx @viewert/mcp setup
+ *    or:  viewert-mcp-setup   (after global install)
+ */
+export {};

package/dist/setup.js

@@ -0,0 +1,417 @@
+#!/usr/bin/env node
+/**
+ * Viewert MCP Setup CLI
+ *
+ * Interactive setup wizard that installs the Viewert MCP server into
+ * Claude Desktop, Cursor, and/or Windsurf with zero manual config editing.
+ *
+ * Usage:  npx @viewert/mcp setup
+ *    or:  viewert-mcp-setup   (after global install)
+ */
+import { execSync, spawnSync } from 'child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { createInterface } from 'readline';
+import { homedir, platform } from 'os';
+import { dirname, join } from 'path';
+// ── ANSI helpers ──────────────────────────────────────────────────────────────
+const c = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    cyan: '\x1b[36m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    red: '\x1b[31m',
+    white: '\x1b[37m',
+    bgCyan: '\x1b[46m',
+    bgGreen: '\x1b[42m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+};
+const bold = (s) => `${c.bold}${s}${c.reset}`;
+const dim = (s) => `${c.dim}${s}${c.reset}`;
+const cyan = (s) => `${c.cyan}${s}${c.reset}`;
+const green = (s) => `${c.green}${s}${c.reset}`;
+const yellow = (s) => `${c.yellow}${s}${c.reset}`;
+const red = (s) => `${c.red}${s}${c.reset}`;
+const blue = (s) => `${c.blue}${s}${c.reset}`;
+const CHECK = green('✓');
+const CROSS = red('✗');
+const ARROW = cyan('›');
+const BULLET = dim('•');
+const WARN = yellow('⚠');
+function box(lines, color = cyan) {
+    const stripped = lines.map(l => l.replace(/\x1b\[[0-9;]*m/g, ''));
+    const width = Math.max(...stripped.map(l => l.length), 0) + 4;
+    const top = color('╭' + '─'.repeat(width) + '╮');
+    const bottom = color('╰' + '─'.repeat(width) + '╯');
+    console.log(top);
+    for (let i = 0; i < lines.length; i++) {
+        const pad = width - stripped[i].length - 2;
+        console.log(color('│') + '  ' + lines[i] + ' '.repeat(pad) + color('│'));
+    }
+    console.log(bottom);
+}
+function hr(char = '─', width = 56) {
+    console.log(dim(char.repeat(width)));
+}
+function nl() { console.log(''); }
+// ── Readline helpers ──────────────────────────────────────────────────────────
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+function ask(question) {
+    return new Promise(resolve => {
+        rl.question(question, answer => resolve(answer.trim()));
+    });
+}
+function askSecret(question) {
+    return new Promise(resolve => {
+        // Pause readline so it doesn't compete for stdin events
+        rl.pause();
+        process.stdout.write(question);
+        process.stdin.setRawMode?.(true);
+        process.stdin.resume();
+        process.stdin.setEncoding('utf8');
+        let input = '';
+        let done = false;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            process.stdin.setRawMode?.(false);
+            process.stdin.pause();
+            process.stdin.removeListener('data', onData);
+            process.stdout.write('\n');
+            rl.resume();
+            resolve(input);
+        };
+        const onData = (chunk) => {
+            // Handle multi-char chunks (e.g. paste) character by character
+            for (const ch of chunk) {
+                if (ch === '\r' || ch === '\n') {
+                    finish();
+                    return;
+                }
+                else if (ch === '\u0003') {
+                    process.stdout.write('\n');
+                    process.exit(1);
+                }
+                else if (ch === '\u007f' || ch === '\u0008') {
+                    if (input.length > 0) {
+                        input = input.slice(0, -1);
+                        process.stdout.write('\b \b');
+                    }
+                }
+                else if (ch >= ' ') {
+                    input += ch;
+                    process.stdout.write('*');
+                }
+            }
+        };
+        process.stdin.on('data', onData);
+    });
+}
+async function confirm(question, defaultYes = true) {
+    const hint = defaultYes ? dim('Y/n') : dim('y/N');
+    const answer = await ask(`${question} ${hint} `);
+    if (answer === '')
+        return defaultYes;
+    return answer.toLowerCase().startsWith('y');
+}
+// ── Platform helpers ──────────────────────────────────────────────────────────
+const IS_WIN = platform() === 'win32';
+const IS_MAC = platform() === 'darwin';
+const HOME = homedir();
+function expandHome(p) {
+    return p.startsWith('~') ? join(HOME, p.slice(1)) : p;
+}
+function getBinaryPath() {
+    try {
+        const result = spawnSync(IS_WIN ? 'where' : 'which', ['viewert-mcp'], { encoding: 'utf8' });
+        const path = result.stdout?.trim().split('\n')[0];
+        if (path && existsSync(path))
+            return path;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function getClients() {
+    const clients = [];
+    // Claude Desktop
+    const claudePath = IS_WIN
+        ? expandHome(join('~', 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json'))
+        : expandHome('~/Library/Application Support/Claude/claude_desktop_config.json');
+    clients.push({
+        name: 'Claude Desktop',
+        emoji: '🤖',
+        configPath: claudePath,
+        reloadHint: IS_MAC
+            ? 'Right-click Claude in the menu bar → Quit, then reopen'
+            : 'Fully quit Claude Desktop from the system tray, then reopen',
+        detected: existsSync(dirname(claudePath)) || existsSync(claudePath),
+    });
+    // Cursor (global)
+    const cursorPath = IS_WIN
+        ? expandHome(join('~', '.cursor', 'mcp.json'))
+        : expandHome('~/.cursor/mcp.json');
+    clients.push({
+        name: 'Cursor',
+        emoji: '⚡',
+        configPath: cursorPath,
+        reloadHint: 'Run "Reload Window" in the command palette (Cmd+Shift+P)',
+        detected: existsSync(dirname(cursorPath)) || existsSync(cursorPath),
+    });
+    // Windsurf
+    const windsurfPath = IS_WIN
+        ? expandHome(join('~', '.codeium', 'windsurf', 'mcp_settings.json'))
+        : expandHome('~/.codeium/windsurf/mcp_settings.json');
+    clients.push({
+        name: 'Windsurf',
+        emoji: '🏄',
+        configPath: windsurfPath,
+        reloadHint: 'Run "Reload Window" in the command palette (Cmd+Shift+P)',
+        detected: existsSync(dirname(windsurfPath)) || existsSync(windsurfPath),
+    });
+    return clients;
+}
+// ── Config read/write ─────────────────────────────────────────────────────────
+function readConfig(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null; // signals parse failure — caller should warn and skip
+    }
+}
+function writeConfig(path, data) {
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify(data, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+}
+function injectViewertServer(config, binaryPath, apiKey) {
+    // Deep-clone mcpServers so we don't mutate the original object
+    const existingServers = (config.mcpServers && typeof config.mcpServers === 'object')
+        ? JSON.parse(JSON.stringify(config.mcpServers))
+        : {};
+    return {
+        ...config,
+        mcpServers: {
+            ...existingServers,
+            viewert: {
+                command: binaryPath,
+                args: [],
+                env: { VIEWERT_API_KEY: apiKey },
+            },
+        },
+    };
+}
+function alreadyConfigured(config) {
+    const servers = config.mcpServers;
+    return !!(servers?.['viewert']);
+}
+async function validateKey(apiKey) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 8000);
+    try {
+        const res = await fetch('https://www.viewert.com/api/librams/mine', {
+            headers: { Authorization: `Bearer ${apiKey}` },
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        if (res.ok)
+            return 'valid';
+        // 401/403 = bad key; 429/5xx = server issue, treat as offline
+        if (res.status === 401 || res.status === 403)
+            return 'invalid';
+        return 'offline';
+    }
+    catch (err) {
+        clearTimeout(timeout);
+        if (err instanceof Error && err.name === 'AbortError')
+            return 'offline';
+        return 'offline';
+    }
+}
+// ── Main ──────────────────────────────────────────────────────────────────────
+async function main() {
+    // ── Banner ──
+    nl();
+    box([
+        bold(cyan('  Viewert MCP  ') + dim('setup wizard')),
+        '',
+        dim('  Connect your Librams to Claude, Cursor, Windsurf'),
+        dim('  and any MCP-compatible AI in under 2 minutes.'),
+    ]);
+    nl();
+    // ── Step 1: Check binary ──
+    console.log(`${bold('Step 1')}  ${cyan('Check installation')}`);
+    nl();
+    let binaryPath = getBinaryPath();
+    if (binaryPath) {
+        console.log(`  ${CHECK}  viewert-mcp found at ${dim(binaryPath)}`);
+    }
+    else {
+        console.log(`  ${WARN}  viewert-mcp not found — installing globally…`);
+        nl();
+        try {
+            execSync('npm install -g @viewert/mcp', { stdio: 'inherit' });
+            binaryPath = getBinaryPath();
+            if (!binaryPath)
+                throw new Error('Binary not found after install');
+            nl();
+            console.log(`  ${CHECK}  Installed at ${dim(binaryPath)}`);
+        }
+        catch {
+            nl();
+            console.log(`  ${CROSS}  ${red('Installation failed.')}`);
+            console.log(`      Try manually: ${cyan('npm install -g @viewert/mcp')}`);
+            rl.close();
+            process.exit(1);
+        }
+    }
+    nl();
+    hr();
+    nl();
+    // ── Step 2: API Key ──
+    console.log(`${bold('Step 2')}  ${cyan('API Key')}`);
+    nl();
+    console.log(`  Your API key starts with ${cyan('vwt_')} and can be generated at:`);
+    console.log(`  ${blue('https://www.viewert.com/settings')} ${dim('→ API Keys → Create Key')}`);
+    nl();
+    console.log(`  ${BULLET} The key is shown ${bold('only once')} — copy it before closing that page.`);
+    console.log(`  ${BULLET} Create one key per AI client so you can revoke individually.`);
+    nl();
+    let apiKey = '';
+    let keyValid = false;
+    while (!keyValid) {
+        apiKey = await askSecret(`  ${ARROW} Paste your API key: `);
+        if (!apiKey.startsWith('vwt_')) {
+            console.log(`\n  ${CROSS}  ${red('Key must start with')} ${cyan('vwt_')}${red('.')} ${dim('Check you copied the full key.')}`);
+            nl();
+            continue;
+        }
+        process.stdout.write(`\n  ${dim('Verifying key…')}`);
+        const valid = await validateKey(apiKey);
+        process.stdout.write('\r' + ' '.repeat(40) + '\r');
+        if (valid === 'valid') {
+            console.log(`  ${CHECK}  ${green('Key verified successfully!')}`);
+            keyValid = true;
+        }
+        else if (valid === 'offline') {
+            console.log(`  ${WARN}  ${yellow('Could not reach viewert.com — check your internet connection.')}`);
+            nl();
+            const proceed = await confirm(`  ${ARROW} Continue anyway without verifying?`, false);
+            if (proceed) {
+                console.log(`\n  ${WARN}  ${yellow('Proceeding unverified — the integration may not work if the key is invalid.')}`);
+                keyValid = true;
+            }
+        }
+        else {
+            console.log(`  ${CROSS}  ${red('Key not recognised.')} ${dim('Make sure you copied it from viewert.com/settings and it hasn\'t been revoked.')}`);
+            nl();
+            const retry = await confirm(`  ${ARROW} Try a different key?`, true);
+            if (!retry) {
+                console.log(`\n  ${WARN}  ${yellow('Skipping key verification — setup will continue but the integration may not work.')}`);
+                keyValid = true;
+            }
+        }
+    }
+    nl();
+    hr();
+    nl();
+    // ── Step 3: Choose clients ──
+    console.log(`${bold('Step 3')}  ${cyan('Choose AI clients to configure')}`);
+    nl();
+    const clients = getClients();
+    for (const client of clients) {
+        const status = client.detected ? green('detected') : dim('not detected');
+        console.log(`  ${BULLET}  ${client.emoji}  ${bold(client.name)}  ${status}`);
+    }
+    nl();
+    const selected = [];
+    for (const client of clients) {
+        const defaultVal = client.detected;
+        const yn = await confirm(`  ${ARROW} Configure ${bold(client.name)}?`, defaultVal);
+        if (yn)
+            selected.push(client);
+    }
+    if (selected.length === 0) {
+        nl();
+        console.log(`  ${WARN}  ${yellow('No clients selected. Nothing to configure.')}`);
+        rl.close();
+        process.exit(0);
+    }
+    nl();
+    hr();
+    nl();
+    // ── Step 4: Write configs ──
+    console.log(`${bold('Step 4')}  ${cyan('Writing configuration')}`);
+    nl();
+    const results = [];
+    for (const client of selected) {
+        try {
+            const existing = readConfig(client.configPath);
+            if (existing === null) {
+                // Malformed JSON — don't clobber the existing file
+                throw new Error(`Config file exists but contains invalid JSON.\n      Fix it manually at: ${client.configPath}`);
+            }
+            const wasConfigured = alreadyConfigured(existing);
+            const updated = injectViewertServer(existing, binaryPath, apiKey);
+            writeConfig(client.configPath, updated);
+            const status = wasConfigured ? 'updated' : 'added';
+            results.push({ client, status, hint: client.reloadHint });
+            const action = wasConfigured ? yellow('updated') : green('added');
+            console.log(`  ${CHECK}  ${client.emoji}  ${bold(client.name)}  ${action}`);
+            console.log(`      ${dim(client.configPath)}`);
+        }
+        catch (err) {
+            results.push({ client, status: 'error', hint: '' });
+            console.log(`  ${CROSS}  ${client.emoji}  ${bold(client.name)}  ${red('failed')}`);
+            console.log(`      ${dim(String(err))}`);
+        }
+        nl();
+    }
+    hr();
+    nl();
+    // ── Done ──
+    const succeeded = results.filter(r => r.status !== 'error');
+    const failed = results.filter(r => r.status === 'error');
+    if (succeeded.length > 0) {
+        box([
+            `${green('✓')}  ${bold('Setup complete!')}`,
+            '',
+            ...succeeded.map(r => `   ${r.client.emoji}  ${bold(r.client.name)}  ${dim('→')}  ${r.status === 'updated' ? yellow('config updated') : green('configured')}`),
+        ], green);
+        nl();
+        console.log(`${bold('Next steps')}`);
+        nl();
+        for (const r of succeeded) {
+            console.log(`  ${r.client.emoji}  ${bold(r.client.name)}`);
+            console.log(`     ${ARROW} ${r.hint}`);
+            nl();
+        }
+        console.log(`  ${bold('Then try:')}  ${dim('"Load my [Libram name] and summarise the key points."')}`);
+        nl();
+        console.log(`  ${BULLET}  Manage Librams:  ${blue('https://www.viewert.com/librams')}`);
+        console.log(`  ${BULLET}  Revoke keys:     ${blue('https://www.viewert.com/settings')}`);
+        console.log(`  ${BULLET}  Docs:            ${blue('https://www.viewert.com/docs/api-keys-mcp')}`);
+    }
+    if (failed.length > 0) {
+        nl();
+        console.log(`  ${WARN}  ${yellow('Some clients could not be configured:')}`);
+        for (const r of failed) {
+            console.log(`     ${CROSS}  ${r.client.name}`);
+        }
+        console.log(`\n  ${dim('You can configure them manually — see docs at')} ${blue('https://www.viewert.com/docs/api-keys-mcp')}`);
+    }
+    nl();
+    rl.close();
+}
+main().catch(err => {
+    console.error(`\n${red('Unexpected error:')} ${String(err)}`);
+    process.exit(1);
+});

package/package.json

@@ -1,18 +1,20 @@
 {
   "name": "@viewert/mcp",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "MCP server for Viewert Librams — expose AI-enabled Vellums as context to any MCP-compatible AI client",
   "keywords": ["mcp", "viewert", "libram", "ai-context", "model-context-protocol"],
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "viewert-mcp": "dist/index.js"
+    "viewert-mcp": "dist/index.js",
+    "viewert-mcp-setup": "dist/setup.js"
   },
   "packageManager": "pnpm@9.0.0",
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/index.ts",
+    "setup": "tsx src/setup.ts",
     "start": "node dist/index.js",
     "prepublishOnly": "pnpm run build"
   },

package/src/index.ts

@@ -9,7 +9,7 @@
  *   VIEWERT_API_KEY   — your vwt_... API key from viewert.com/settings
  *
  * Optional env vars:
- *   VIEWERT_API_URL   — defaults to https://viewert.com/api
+ *   VIEWERT_API_URL   — defaults to https://www.viewert.com/api
  */
 
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
@@ -17,7 +17,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod'
 
 const API_KEY = process.env.VIEWERT_API_KEY
-const API_BASE = (process.env.VIEWERT_API_URL ?? 'https://viewert.com/api').replace(/\/$/, '')
+const API_BASE = (process.env.VIEWERT_API_URL ?? 'https://www.viewert.com/api').replace(/\/$/, '')
 
 if (!API_KEY) {
   process.stderr.write(

package/src/setup.ts

@@ -0,0 +1,476 @@
+#!/usr/bin/env node
+/**
+ * Viewert MCP Setup CLI
+ *
+ * Interactive setup wizard that installs the Viewert MCP server into
+ * Claude Desktop, Cursor, and/or Windsurf with zero manual config editing.
+ *
+ * Usage:  npx @viewert/mcp setup
+ *    or:  viewert-mcp-setup   (after global install)
+ */
+
+import { execSync, spawnSync } from 'child_process'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { createInterface } from 'readline'
+import { homedir, platform } from 'os'
+import { dirname, join } from 'path'
+
+// ── ANSI helpers ──────────────────────────────────────────────────────────────
+
+const c = {
+  reset:    '\x1b[0m',
+  bold:     '\x1b[1m',
+  dim:      '\x1b[2m',
+  cyan:     '\x1b[36m',
+  green:    '\x1b[32m',
+  yellow:   '\x1b[33m',
+  red:      '\x1b[31m',
+  white:    '\x1b[37m',
+  bgCyan:   '\x1b[46m',
+  bgGreen:  '\x1b[42m',
+  blue:     '\x1b[34m',
+  magenta:  '\x1b[35m',
+}
+
+const bold   = (s: string) => `${c.bold}${s}${c.reset}`
+const dim    = (s: string) => `${c.dim}${s}${c.reset}`
+const cyan   = (s: string) => `${c.cyan}${s}${c.reset}`
+const green  = (s: string) => `${c.green}${s}${c.reset}`
+const yellow = (s: string) => `${c.yellow}${s}${c.reset}`
+const red    = (s: string) => `${c.red}${s}${c.reset}`
+const blue   = (s: string) => `${c.blue}${s}${c.reset}`
+
+const CHECK  = green('✓')
+const CROSS  = red('✗')
+const ARROW  = cyan('›')
+const BULLET = dim('•')
+const WARN   = yellow('⚠')
+
+function box(lines: string[], color: (s: string) => string = cyan): void {
+  const stripped = lines.map(l => l.replace(/\x1b\[[0-9;]*m/g, ''))
+  const width = Math.max(...stripped.map(l => l.length), 0) + 4
+  const top    = color('╭' + '─'.repeat(width) + '╮')
+  const bottom = color('╰' + '─'.repeat(width) + '╯')
+  console.log(top)
+  for (let i = 0; i < lines.length; i++) {
+    const pad = width - stripped[i].length - 2
+    console.log(color('│') + '  ' + lines[i] + ' '.repeat(pad) + color('│'))
+  }
+  console.log(bottom)
+}
+
+function hr(char = '─', width = 56): void {
+  console.log(dim(char.repeat(width)))
+}
+
+function nl(): void { console.log('') }
+
+// ── Readline helpers ──────────────────────────────────────────────────────────
+
+const rl = createInterface({ input: process.stdin, output: process.stdout })
+
+function ask(question: string): Promise<string> {
+  return new Promise(resolve => {
+    rl.question(question, answer => resolve(answer.trim()))
+  })
+}
+
+function askSecret(question: string): Promise<string> {
+  return new Promise(resolve => {
+    // Pause readline so it doesn't compete for stdin events
+    rl.pause()
+    process.stdout.write(question)
+    process.stdin.setRawMode?.(true)
+    process.stdin.resume()
+    process.stdin.setEncoding('utf8')
+    let input = ''
+    let done = false
+    const finish = () => {
+      if (done) return
+      done = true
+      process.stdin.setRawMode?.(false)
+      process.stdin.pause()
+      process.stdin.removeListener('data', onData)
+      process.stdout.write('\n')
+      rl.resume()
+      resolve(input)
+    }
+    const onData = (chunk: string) => {
+      // Handle multi-char chunks (e.g. paste) character by character
+      for (const ch of chunk) {
+        if (ch === '\r' || ch === '\n') {
+          finish()
+          return
+        } else if (ch === '\u0003') {
+          process.stdout.write('\n')
+          process.exit(1)
+        } else if (ch === '\u007f' || ch === '\u0008') {
+          if (input.length > 0) {
+            input = input.slice(0, -1)
+            process.stdout.write('\b \b')
+          }
+        } else if (ch >= ' ') {
+          input += ch
+          process.stdout.write('*')
+        }
+      }
+    }
+    process.stdin.on('data', onData)
+  })
+}
+
+async function confirm(question: string, defaultYes = true): Promise<boolean> {
+  const hint = defaultYes ? dim('Y/n') : dim('y/N')
+  const answer = await ask(`${question} ${hint} `)
+  if (answer === '') return defaultYes
+  return answer.toLowerCase().startsWith('y')
+}
+
+// ── Platform helpers ──────────────────────────────────────────────────────────
+
+const IS_WIN = platform() === 'win32'
+const IS_MAC = platform() === 'darwin'
+const HOME = homedir()
+
+function expandHome(p: string): string {
+  return p.startsWith('~') ? join(HOME, p.slice(1)) : p
+}
+
+function getBinaryPath(): string | null {
+  try {
+    const result = spawnSync(IS_WIN ? 'where' : 'which', ['viewert-mcp'], { encoding: 'utf8' })
+    const path = result.stdout?.trim().split('\n')[0]
+    if (path && existsSync(path)) return path
+    return null
+  } catch {
+    return null
+  }
+}
+
+// ── Client config paths ───────────────────────────────────────────────────────
+
+interface ClientConfig {
+  name:        string
+  emoji:       string
+  configPath:  string
+  reloadHint:  string
+  detected:    boolean
+}
+
+function getClients(): ClientConfig[] {
+  const clients: ClientConfig[] = []
+
+  // Claude Desktop
+  const claudePath = IS_WIN
+    ? expandHome(join('~', 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json'))
+    : expandHome('~/Library/Application Support/Claude/claude_desktop_config.json')
+  clients.push({
+    name: 'Claude Desktop',
+    emoji: '🤖',
+    configPath: claudePath,
+    reloadHint: IS_MAC
+      ? 'Right-click Claude in the menu bar → Quit, then reopen'
+      : 'Fully quit Claude Desktop from the system tray, then reopen',
+    detected: existsSync(dirname(claudePath)) || existsSync(claudePath),
+  })
+
+  // Cursor (global)
+  const cursorPath = IS_WIN
+    ? expandHome(join('~', '.cursor', 'mcp.json'))
+    : expandHome('~/.cursor/mcp.json')
+  clients.push({
+    name: 'Cursor',
+    emoji: '⚡',
+    configPath: cursorPath,
+    reloadHint: 'Run "Reload Window" in the command palette (Cmd+Shift+P)',
+    detected: existsSync(dirname(cursorPath)) || existsSync(cursorPath),
+  })
+
+  // Windsurf
+  const windsurfPath = IS_WIN
+    ? expandHome(join('~', '.codeium', 'windsurf', 'mcp_settings.json'))
+    : expandHome('~/.codeium/windsurf/mcp_settings.json')
+  clients.push({
+    name: 'Windsurf',
+    emoji: '🏄',
+    configPath: windsurfPath,
+    reloadHint: 'Run "Reload Window" in the command palette (Cmd+Shift+P)',
+    detected: existsSync(dirname(windsurfPath)) || existsSync(windsurfPath),
+  })
+
+  return clients
+}
+
+// ── Config read/write ─────────────────────────────────────────────────────────
+
+function readConfig(path: string): Record<string, unknown> | null {
+  if (!existsSync(path)) return {}
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>
+  } catch {
+    return null // signals parse failure — caller should warn and skip
+  }
+}
+
+function writeConfig(path: string, data: Record<string, unknown>): void {
+  const dir = dirname(path)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 })
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 })
+}
+
+function injectViewertServer(
+  config: Record<string, unknown>,
+  binaryPath: string,
+  apiKey: string,
+): Record<string, unknown> {
+  // Deep-clone mcpServers so we don't mutate the original object
+  const existingServers = (config.mcpServers && typeof config.mcpServers === 'object')
+    ? JSON.parse(JSON.stringify(config.mcpServers)) as Record<string, unknown>
+    : {}
+  return {
+    ...config,
+    mcpServers: {
+      ...existingServers,
+      viewert: {
+        command: binaryPath,
+        args: [],
+        env: { VIEWERT_API_KEY: apiKey },
+      },
+    },
+  }
+}
+
+function alreadyConfigured(config: Record<string, unknown>): boolean {
+  const servers = config.mcpServers as Record<string, unknown> | undefined
+  return !!(servers?.['viewert'])
+}
+
+// ── Validate API key against production ──────────────────────────────────────
+
+type KeyValidationResult = 'valid' | 'invalid' | 'offline'
+
+async function validateKey(apiKey: string): Promise<KeyValidationResult> {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), 8000)
+  try {
+    const res = await fetch('https://www.viewert.com/api/librams/mine', {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: controller.signal,
+    })
+    clearTimeout(timeout)
+    if (res.ok) return 'valid'
+    // 401/403 = bad key; 429/5xx = server issue, treat as offline
+    if (res.status === 401 || res.status === 403) return 'invalid'
+    return 'offline'
+  } catch (err) {
+    clearTimeout(timeout)
+    if (err instanceof Error && err.name === 'AbortError') return 'offline'
+    return 'offline'
+  }
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  // ── Banner ──
+  nl()
+  box([
+    bold(cyan('  Viewert MCP  ') + dim('setup wizard')),
+    '',
+    dim('  Connect your Librams to Claude, Cursor, Windsurf'),
+    dim('  and any MCP-compatible AI in under 2 minutes.'),
+  ])
+  nl()
+
+  // ── Step 1: Check binary ──
+  console.log(`${bold('Step 1')}  ${cyan('Check installation')}`)
+  nl()
+
+  let binaryPath = getBinaryPath()
+
+  if (binaryPath) {
+    console.log(`  ${CHECK}  viewert-mcp found at ${dim(binaryPath)}`)
+  } else {
+    console.log(`  ${WARN}  viewert-mcp not found — installing globally…`)
+    nl()
+    try {
+      execSync('npm install -g @viewert/mcp', { stdio: 'inherit' })
+      binaryPath = getBinaryPath()
+      if (!binaryPath) throw new Error('Binary not found after install')
+      nl()
+      console.log(`  ${CHECK}  Installed at ${dim(binaryPath)}`)
+    } catch {
+      nl()
+      console.log(`  ${CROSS}  ${red('Installation failed.')}`)
+      console.log(`      Try manually: ${cyan('npm install -g @viewert/mcp')}`)
+      rl.close()
+      process.exit(1)
+    }
+  }
+
+  nl()
+  hr()
+  nl()
+
+  // ── Step 2: API Key ──
+  console.log(`${bold('Step 2')}  ${cyan('API Key')}`)
+  nl()
+  console.log(`  Your API key starts with ${cyan('vwt_')} and can be generated at:`)
+  console.log(`  ${blue('https://www.viewert.com/settings')} ${dim('→ API Keys → Create Key')}`)
+  nl()
+  console.log(`  ${BULLET} The key is shown ${bold('only once')} — copy it before closing that page.`)
+  console.log(`  ${BULLET} Create one key per AI client so you can revoke individually.`)
+  nl()
+
+  let apiKey = ''
+  let keyValid = false
+
+  while (!keyValid) {
+    apiKey = await askSecret(`  ${ARROW} Paste your API key: `)
+
+    if (!apiKey.startsWith('vwt_')) {
+      console.log(`\n  ${CROSS}  ${red('Key must start with')} ${cyan('vwt_')}${red('.')} ${dim('Check you copied the full key.')}`)
+      nl()
+      continue
+    }
+
+    process.stdout.write(`\n  ${dim('Verifying key…')}`)
+    const valid = await validateKey(apiKey)
+    process.stdout.write('\r' + ' '.repeat(40) + '\r')
+
+    if (valid === 'valid') {
+      console.log(`  ${CHECK}  ${green('Key verified successfully!')}`)
+      keyValid = true
+    } else if (valid === 'offline') {
+      console.log(`  ${WARN}  ${yellow('Could not reach viewert.com — check your internet connection.')}`)
+      nl()
+      const proceed = await confirm(`  ${ARROW} Continue anyway without verifying?`, false)
+      if (proceed) {
+        console.log(`\n  ${WARN}  ${yellow('Proceeding unverified — the integration may not work if the key is invalid.')}`)
+        keyValid = true
+      }
+    } else {
+      console.log(`  ${CROSS}  ${red('Key not recognised.')} ${dim('Make sure you copied it from viewert.com/settings and it hasn\'t been revoked.')}`)
+      nl()
+      const retry = await confirm(`  ${ARROW} Try a different key?`, true)
+      if (!retry) {
+        console.log(`\n  ${WARN}  ${yellow('Skipping key verification — setup will continue but the integration may not work.')}`)
+        keyValid = true
+      }
+    }
+  }
+
+  nl()
+  hr()
+  nl()
+
+  // ── Step 3: Choose clients ──
+  console.log(`${bold('Step 3')}  ${cyan('Choose AI clients to configure')}`)
+  nl()
+
+  const clients = getClients()
+
+  for (const client of clients) {
+    const status = client.detected ? green('detected') : dim('not detected')
+    console.log(`  ${BULLET}  ${client.emoji}  ${bold(client.name)}  ${status}`)
+  }
+
+  nl()
+
+  const selected: ClientConfig[] = []
+
+  for (const client of clients) {
+    const defaultVal = client.detected
+    const yn = await confirm(`  ${ARROW} Configure ${bold(client.name)}?`, defaultVal)
+    if (yn) selected.push(client)
+  }
+
+  if (selected.length === 0) {
+    nl()
+    console.log(`  ${WARN}  ${yellow('No clients selected. Nothing to configure.')}`)
+    rl.close()
+    process.exit(0)
+  }
+
+  nl()
+  hr()
+  nl()
+
+  // ── Step 4: Write configs ──
+  console.log(`${bold('Step 4')}  ${cyan('Writing configuration')}`)
+  nl()
+
+  const results: { client: ClientConfig; status: 'added' | 'updated' | 'error'; hint: string }[] = []
+
+  for (const client of selected) {
+    try {
+      const existing = readConfig(client.configPath)
+      if (existing === null) {
+        // Malformed JSON — don't clobber the existing file
+        throw new Error(`Config file exists but contains invalid JSON.\n      Fix it manually at: ${client.configPath}`)
+      }
+      const wasConfigured = alreadyConfigured(existing)
+      const updated = injectViewertServer(existing, binaryPath!, apiKey)
+      writeConfig(client.configPath, updated)
+
+      const status = wasConfigured ? 'updated' : 'added'
+      results.push({ client, status, hint: client.reloadHint })
+
+      const action = wasConfigured ? yellow('updated') : green('added')
+      console.log(`  ${CHECK}  ${client.emoji}  ${bold(client.name)}  ${action}`)
+      console.log(`      ${dim(client.configPath)}`)
+    } catch (err) {
+      results.push({ client, status: 'error', hint: '' })
+      console.log(`  ${CROSS}  ${client.emoji}  ${bold(client.name)}  ${red('failed')}`)
+      console.log(`      ${dim(String(err))}`)
+    }
+    nl()
+  }
+
+  hr()
+  nl()
+
+  // ── Done ──
+  const succeeded = results.filter(r => r.status !== 'error')
+  const failed    = results.filter(r => r.status === 'error')
+
+  if (succeeded.length > 0) {
+    box([
+      `${green('✓')}  ${bold('Setup complete!')}`,
+      '',
+      ...succeeded.map(r => `   ${r.client.emoji}  ${bold(r.client.name)}  ${dim('→')}  ${r.status === 'updated' ? yellow('config updated') : green('configured')}`),
+    ], green)
+    nl()
+
+    console.log(`${bold('Next steps')}`)
+    nl()
+    for (const r of succeeded) {
+      console.log(`  ${r.client.emoji}  ${bold(r.client.name)}`)
+      console.log(`     ${ARROW} ${r.hint}`)
+      nl()
+    }
+
+    console.log(`  ${bold('Then try:')}  ${dim('"Load my [Libram name] and summarise the key points."')}`)
+    nl()
+    console.log(`  ${BULLET}  Manage Librams:  ${blue('https://www.viewert.com/librams')}`)
+    console.log(`  ${BULLET}  Revoke keys:     ${blue('https://www.viewert.com/settings')}`)
+    console.log(`  ${BULLET}  Docs:            ${blue('https://www.viewert.com/docs/api-keys-mcp')}`)
+  }
+
+  if (failed.length > 0) {
+    nl()
+    console.log(`  ${WARN}  ${yellow('Some clients could not be configured:')}`)
+    for (const r of failed) {
+      console.log(`     ${CROSS}  ${r.client.name}`)
+    }
+    console.log(`\n  ${dim('You can configure them manually — see docs at')} ${blue('https://www.viewert.com/docs/api-keys-mcp')}`)
+  }
+
+  nl()
+  rl.close()
+}
+
+main().catch(err => {
+  console.error(`\n${red('Unexpected error:')} ${String(err)}`)
+  process.exit(1)
+})