@vibescope/mcp-server 0.3.0 → 0.3.3

package/dist/api-client.js

@@ -5,46 +5,125 @@
  * All database operations are handled server-side through these endpoints.
  */
 const DEFAULT_API_URL = 'https://vibescope.dev';
+// Retry configuration defaults
+const DEFAULT_RETRY_STATUS_CODES = [429, 503, 504];
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BASE_DELAY_MS = 1000;
+const DEFAULT_MAX_DELAY_MS = 30000;
+/**
+ * Calculate delay for exponential backoff with jitter
+ */
+function calculateBackoffDelay(attempt, baseDelayMs, maxDelayMs, retryAfter) {
+    // If Retry-After header is present, use it (in seconds)
+    if (retryAfter !== undefined && retryAfter > 0) {
+        return Math.min(retryAfter * 1000, maxDelayMs);
+    }
+    // Exponential backoff: base * 2^attempt with jitter
+    const exponentialDelay = baseDelayMs * Math.pow(2, attempt);
+    const jitter = Math.random() * 0.3 * exponentialDelay; // 0-30% jitter
+    return Math.min(exponentialDelay + jitter, maxDelayMs);
+}
+/**
+ * Sleep for a specified duration
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
 export class VibescopeApiClient {
     apiKey;
     baseUrl;
+    retryConfig;
     constructor(config) {
         this.apiKey = config.apiKey;
         this.baseUrl = config.baseUrl || process.env.VIBESCOPE_API_URL || DEFAULT_API_URL;
+        this.retryConfig = {
+            maxRetries: config.retry?.maxRetries ?? DEFAULT_MAX_RETRIES,
+            baseDelayMs: config.retry?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS,
+            maxDelayMs: config.retry?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS,
+            retryStatusCodes: config.retry?.retryStatusCodes ?? DEFAULT_RETRY_STATUS_CODES,
+        };
     }
     async request(method, path, body) {
         const url = `${this.baseUrl}${path}`;
-        try {
-            const response = await fetch(url, {
-                method,
-                headers: {
-                    'Content-Type': 'application/json',
-                    'X-API-Key': this.apiKey
-                },
-                body: body ? JSON.stringify(body) : undefined
-            });
-            const data = await response.json();
-            if (!response.ok) {
+        const { maxRetries, baseDelayMs, maxDelayMs, retryStatusCodes } = this.retryConfig;
+        let lastError = null;
+        let lastResponse = null;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const response = await fetch(url, {
+                    method,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-API-Key': this.apiKey
+                    },
+                    body: body ? JSON.stringify(body) : undefined
+                });
+                // Check if we should retry this status code
+                if (retryStatusCodes.includes(response.status) && attempt < maxRetries) {
+                    lastResponse = response;
+                    // Parse Retry-After header if present (can be seconds or HTTP-date)
+                    const retryAfterHeader = response.headers.get('Retry-After');
+                    let retryAfter;
+                    if (retryAfterHeader) {
+                        const seconds = parseInt(retryAfterHeader, 10);
+                        if (!isNaN(seconds)) {
+                            retryAfter = seconds;
+                        }
+                    }
+                    const delay = calculateBackoffDelay(attempt, baseDelayMs, maxDelayMs, retryAfter);
+                    await sleep(delay);
+                    continue;
+                }
+                const data = await response.json();
+                if (!response.ok) {
+                    return {
+                        ok: false,
+                        status: response.status,
+                        error: data.error || `HTTP ${response.status}`,
+                        data // Include full response data for additional error context
+                    };
+                }
                 return {
-                    ok: false,
+                    ok: true,
                     status: response.status,
-                    error: data.error || `HTTP ${response.status}`,
-                    data // Include full response data for additional error context
+                    data
                 };
             }
-            return {
-                ok: true,
-                status: response.status,
-                data
-            };
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error('Network error');
+                // Retry on network errors (connection failures, timeouts)
+                if (attempt < maxRetries) {
+                    const delay = calculateBackoffDelay(attempt, baseDelayMs, maxDelayMs);
+                    await sleep(delay);
+                    continue;
+                }
+            }
         }
-        catch (err) {
-            return {
-                ok: false,
-                status: 0,
-                error: err instanceof Error ? err.message : 'Network error'
-            };
+        // All retries exhausted
+        if (lastResponse) {
+            // We had a response but it was a retryable error status
+            try {
+                const data = await lastResponse.json();
+                return {
+                    ok: false,
+                    status: lastResponse.status,
+                    error: data.error || `HTTP ${lastResponse.status} after ${maxRetries} retries`,
+                    data
+                };
+            }
+            catch {
+                return {
+                    ok: false,
+                    status: lastResponse.status,
+                    error: `HTTP ${lastResponse.status} after ${maxRetries} retries`
+                };
+            }
         }
+        return {
+            ok: false,
+            status: 0,
+            error: lastError?.message || 'Network error after retries'
+        };
     }
     // Auth endpoints
     async validateAuth() {

package/dist/cli-init.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * Vibescope Init CLI
+ *
+ * Usage: npx vibescope init
+ *
+ * Detects installed AI agents, configures MCP, and stores credentials.
+ */
+export declare function readCredentials(): {
+    apiKey?: string;
+};
+export declare function writeCredentials(apiKey: string): void;
+/**
+ * Resolve API key from env var or credentials file.
+ * Used by the MCP server at startup.
+ */
+export declare function resolveApiKey(): string | null;

package/dist/cli-init.js

@@ -0,0 +1,445 @@
+#!/usr/bin/env node
+/**
+ * Vibescope Init CLI
+ *
+ * Usage: npx vibescope init
+ *
+ * Detects installed AI agents, configures MCP, and stores credentials.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join, dirname } from 'node:path';
+import { exec, execSync } from 'node:child_process';
+import { createInterface } from 'node:readline';
+const VIBESCOPE_SETTINGS_URL = 'https://vibescope.dev/dashboard/settings';
+const VIBESCOPE_API_URL = 'https://vibescope.dev';
+const CREDENTIALS_DIR = join(homedir(), '.vibescope');
+const CREDENTIALS_PATH = join(CREDENTIALS_DIR, 'credentials.json');
+// ============================================================================
+// Terminal Colors
+// ============================================================================
+const c = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+    red: '\x1b[31m',
+    white: '\x1b[37m',
+};
+const icon = {
+    check: `${c.green}✔${c.reset}`,
+    cross: `${c.red}✘${c.reset}`,
+    arrow: `${c.cyan}→${c.reset}`,
+    dot: `${c.dim}·${c.reset}`,
+    warn: `${c.yellow}⚠${c.reset}`,
+};
+// ============================================================================
+// Prompts
+// ============================================================================
+function prompt(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+async function promptConfirm(question, defaultYes = true) {
+    const hint = defaultYes ? 'Y/n' : 'y/N';
+    const answer = await prompt(`${question} (${hint}): `);
+    if (!answer)
+        return defaultYes;
+    return answer.toLowerCase().startsWith('y');
+}
+async function promptCheckboxes(label, items) {
+    console.log(`\n${c.bold}${label}${c.reset}\n`);
+    items.forEach((item, i) => {
+        const tag = item.detected ? `${c.green}detected${c.reset}` : `${c.dim}not detected${c.reset}`;
+        console.log(`  ${i + 1}) ${item.name} [${tag}]`);
+    });
+    console.log(`  ${c.dim}a) All detected${c.reset}`);
+    const answer = await prompt(`\nSelect agents (comma-separated numbers, or 'a' for all detected): `);
+    if (answer.toLowerCase() === 'a') {
+        const detected = items.filter(i => i.detected).map(i => i.id);
+        return detected.length > 0 ? detected : items.map(i => i.id);
+    }
+    const indices = answer.split(',').map(s => parseInt(s.trim(), 10) - 1).filter(i => i >= 0 && i < items.length);
+    if (indices.length === 0) {
+        // Default to all detected
+        const detected = items.filter(i => i.detected).map(i => i.id);
+        return detected.length > 0 ? detected : [items[0].id];
+    }
+    return indices.map(i => items[i].id);
+}
+// ============================================================================
+// Credential Storage
+// ============================================================================
+export function readCredentials() {
+    try {
+        if (existsSync(CREDENTIALS_PATH)) {
+            const data = JSON.parse(readFileSync(CREDENTIALS_PATH, 'utf-8'));
+            return { apiKey: data.apiKey };
+        }
+    }
+    catch { /* ignore */ }
+    return {};
+}
+export function writeCredentials(apiKey) {
+    if (!existsSync(CREDENTIALS_DIR)) {
+        mkdirSync(CREDENTIALS_DIR, { recursive: true });
+    }
+    writeFileSync(CREDENTIALS_PATH, JSON.stringify({ apiKey }, null, 2) + '\n', { mode: 0o600 });
+    try {
+        chmodSync(CREDENTIALS_PATH, 0o600);
+    }
+    catch { /* Windows doesn't support chmod, that's ok */ }
+}
+/**
+ * Resolve API key from env var or credentials file.
+ * Used by the MCP server at startup.
+ */
+export function resolveApiKey() {
+    // 1. Environment variable (highest priority)
+    if (process.env.VIBESCOPE_API_KEY) {
+        return process.env.VIBESCOPE_API_KEY;
+    }
+    // 2. Credentials file
+    const creds = readCredentials();
+    if (creds.apiKey) {
+        return creds.apiKey;
+    }
+    // 3. Not found
+    return null;
+}
+// ============================================================================
+// Agent Detection & Configuration
+// ============================================================================
+function commandExists(cmd) {
+    try {
+        execSync(`which ${cmd}`, { stdio: 'pipe', timeout: 3000 });
+        return true;
+    }
+    catch {
+        // On Windows, try 'where'
+        if (platform() === 'win32') {
+            try {
+                execSync(`where ${cmd}`, { stdio: 'pipe', timeout: 3000 });
+                return true;
+            }
+            catch { /* not found */ }
+        }
+        return false;
+    }
+}
+function dirExists(path) {
+    return existsSync(path);
+}
+function detectAgents() {
+    const home = homedir();
+    const agents = [
+        {
+            id: 'claude-code',
+            name: 'Claude Code',
+            detected: commandExists('claude') || dirExists(join(home, '.claude')),
+            configure: configureClaudeCode,
+        },
+        {
+            id: 'cursor',
+            name: 'Cursor',
+            detected: commandExists('cursor') || dirExists(join(home, '.cursor')),
+            configure: configureCursor,
+        },
+        {
+            id: 'windsurf',
+            name: 'Windsurf',
+            detected: dirExists(join(home, '.windsurf')) || dirExists(join(home, '.codeium')),
+            configure: configureWindsurf,
+        },
+        {
+            id: 'gemini',
+            name: 'Gemini CLI',
+            detected: commandExists('gemini') || dirExists(join(home, '.gemini')),
+            configure: configureGemini,
+        },
+    ];
+    return agents;
+}
+// ============================================================================
+// Agent Configurators
+// ============================================================================
+async function configureClaudeCode(apiKey) {
+    // Try using `claude mcp add` command
+    try {
+        execSync('claude --version', { stdio: 'pipe', timeout: 5000 });
+        // Use project scope for claude mcp add
+        try {
+            execSync(`claude mcp add vibescope -e VIBESCOPE_API_KEY=${apiKey} -- npx -y -p @vibescope/mcp-server@latest vibescope-mcp`, { stdio: 'pipe', timeout: 15000 });
+            console.log(`  ${icon.check} Claude Code configured via ${c.cyan}claude mcp add${c.reset}`);
+            return;
+        }
+        catch {
+            // claude mcp add not available (older version), fall through to manual config
+        }
+    }
+    catch { /* claude CLI not available */ }
+    // Fallback: write .mcp.json
+    const configPath = join(process.cwd(), '.mcp.json');
+    writeMcpJson(configPath, apiKey);
+    console.log(`  ${icon.check} Wrote ${c.cyan}.mcp.json${c.reset} (Claude Code project config)`);
+}
+async function configureCursor(apiKey) {
+    const configPath = join(process.cwd(), '.cursor', 'mcp.json');
+    writeMcpJson(configPath, apiKey);
+    console.log(`  ${icon.check} Wrote ${c.cyan}.cursor/mcp.json${c.reset}`);
+}
+async function configureWindsurf(apiKey) {
+    const configPath = join(homedir(), '.codeium', 'windsurf', 'mcp_config.json');
+    writeMcpJson(configPath, apiKey);
+    console.log(`  ${icon.check} Wrote ${c.cyan}~/.codeium/windsurf/mcp_config.json${c.reset}`);
+}
+async function configureGemini(apiKey) {
+    const configPath = join(homedir(), '.gemini', 'settings.json');
+    const existing = readJsonFile(configPath);
+    const mcpServers = existing.mcpServers || {};
+    mcpServers['vibescope'] = {
+        command: 'npx',
+        args: ['-y', '-p', '@vibescope/mcp-server@latest', 'vibescope-mcp'],
+        env: { VIBESCOPE_API_KEY: apiKey },
+        timeout: 30000,
+        trust: true,
+    };
+    existing.mcpServers = mcpServers;
+    writeJsonFile(configPath, existing);
+    console.log(`  ${icon.check} Wrote ${c.cyan}~/.gemini/settings.json${c.reset}`);
+}
+// ============================================================================
+// Config File Helpers
+// ============================================================================
+function readJsonFile(path) {
+    try {
+        if (existsSync(path)) {
+            return JSON.parse(readFileSync(path, 'utf-8'));
+        }
+    }
+    catch { /* ignore */ }
+    return {};
+}
+function writeJsonFile(path, data) {
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+}
+function writeMcpJson(configPath, apiKey) {
+    const existing = readJsonFile(configPath);
+    const mcpServers = existing.mcpServers || {};
+    mcpServers['vibescope'] = {
+        command: 'npx',
+        args: ['-y', '-p', '@vibescope/mcp-server@latest', 'vibescope-mcp'],
+        env: { VIBESCOPE_API_KEY: apiKey },
+    };
+    existing.mcpServers = mcpServers;
+    writeJsonFile(configPath, existing);
+}
+function checkExistingConfig(agentId) {
+    switch (agentId) {
+        case 'claude-code':
+            return existsSync(join(process.cwd(), '.mcp.json')) &&
+                readJsonFile(join(process.cwd(), '.mcp.json')).mcpServers !== undefined &&
+                'vibescope' in (readJsonFile(join(process.cwd(), '.mcp.json')).mcpServers || {});
+        case 'cursor':
+            return existsSync(join(process.cwd(), '.cursor', 'mcp.json')) &&
+                'vibescope' in (readJsonFile(join(process.cwd(), '.cursor', 'mcp.json')).mcpServers || {});
+        case 'windsurf':
+            return 'vibescope' in (readJsonFile(join(homedir(), '.codeium', 'windsurf', 'mcp_config.json')).mcpServers || {});
+        case 'gemini':
+            return 'vibescope' in (readJsonFile(join(homedir(), '.gemini', 'settings.json')).mcpServers || {});
+        default:
+            return false;
+    }
+}
+// ============================================================================
+// API Key Validation
+// ============================================================================
+async function validateApiKey(apiKey) {
+    try {
+        const response = await fetch(`${VIBESCOPE_API_URL}/api/mcp/auth/validate`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-Key': apiKey,
+            },
+            body: JSON.stringify({ api_key: apiKey }),
+        });
+        const data = await response.json();
+        if (response.ok && data.valid) {
+            return { valid: true, message: 'API key is valid' };
+        }
+        return { valid: false, message: data.error || 'Invalid API key' };
+    }
+    catch {
+        return { valid: true, message: 'Could not validate (network issue), proceeding' };
+    }
+}
+// ============================================================================
+// Browser
+// ============================================================================
+function openBrowser(url) {
+    return new Promise((resolve) => {
+        const plat = platform();
+        const cmd = plat === 'darwin' ? `open "${url}"` :
+            plat === 'win32' ? `start "" "${url}"` :
+                `xdg-open "${url}"`;
+        exec(cmd, () => resolve());
+    });
+}
+// ============================================================================
+// Main Init Flow
+// ============================================================================
+async function runInit() {
+    console.log(`
+${c.bold}${c.magenta}  ╦  ╦╦╔╗ ╔═╗╔═╗╔═╗╔═╗╔═╗╔═╗${c.reset}
+${c.bold}${c.magenta}  ╚╗╔╝║╠╩╗║╣ ╚═╗║  ║ ║╠═╝║╣ ${c.reset}
+${c.bold}${c.magenta}   ╚╝ ╩╚═╝╚═╝╚═╝╚═╝╚═╝╩  ╚═╝${c.reset}
+${c.dim}  AI project tracking for vibe coders${c.reset}
+`);
+    // Step 1: Detect agents
+    const agents = detectAgents();
+    const detected = agents.filter(a => a.detected);
+    if (detected.length > 0) {
+        console.log(`${icon.check} Detected agents:`);
+        detected.forEach(a => console.log(`  ${icon.dot} ${a.name}`));
+    }
+    else {
+        console.log(`${icon.warn} No AI agents detected automatically`);
+    }
+    // Step 2: Select agents
+    const selectedIds = await promptCheckboxes('Which agents do you want to configure?', agents.map(a => ({ id: a.id, name: a.name, detected: a.detected })));
+    const selectedAgents = agents.filter(a => selectedIds.includes(a.id));
+    if (selectedAgents.length === 0) {
+        console.log(`\n${icon.cross} No agents selected. Exiting.`);
+        process.exit(0);
+    }
+    // Step 3: API Key
+    let apiKey = null;
+    // Check env var first
+    if (process.env.VIBESCOPE_API_KEY) {
+        apiKey = process.env.VIBESCOPE_API_KEY;
+        console.log(`\n${icon.check} Using API key from ${c.cyan}VIBESCOPE_API_KEY${c.reset} env var`);
+    }
+    // Check credentials file
+    if (!apiKey) {
+        const creds = readCredentials();
+        if (creds.apiKey) {
+            apiKey = creds.apiKey;
+            console.log(`\n${icon.check} Found existing API key in ${c.cyan}~/.vibescope/credentials.json${c.reset}`);
+            const reuse = await promptConfirm('Use existing API key?', true);
+            if (!reuse)
+                apiKey = null;
+        }
+    }
+    // Prompt for key if needed
+    if (!apiKey) {
+        console.log(`\n${c.bold}API Key Setup${c.reset}`);
+        console.log(`${icon.arrow} Get your API key at ${c.cyan}${VIBESCOPE_SETTINGS_URL}${c.reset}`);
+        const openIt = await promptConfirm('Open settings page in browser?', true);
+        if (openIt)
+            await openBrowser(VIBESCOPE_SETTINGS_URL);
+        for (let attempt = 0; attempt < 3; attempt++) {
+            apiKey = await prompt(`\n${c.bold}Paste your API key:${c.reset} `);
+            if (!apiKey) {
+                console.log(`${icon.cross} API key is required`);
+                continue;
+            }
+            process.stdout.write(`  Validating... `);
+            const result = await validateApiKey(apiKey);
+            if (result.valid) {
+                console.log(`${icon.check} ${result.message}`);
+                break;
+            }
+            else {
+                console.log(`${icon.cross} ${result.message}`);
+                apiKey = null;
+            }
+        }
+        if (!apiKey) {
+            console.log(`\n${icon.cross} Could not get a valid API key. Exiting.`);
+            process.exit(1);
+        }
+        // Store credentials
+        try {
+            writeCredentials(apiKey);
+            console.log(`\n${icon.check} API key saved to ${c.cyan}~/.vibescope/credentials.json${c.reset}`);
+        }
+        catch (err) {
+            console.log(`\n${icon.warn} Could not save credentials: ${err instanceof Error ? err.message : 'unknown error'}`);
+            console.log(`  ${c.dim}Set VIBESCOPE_API_KEY env var as fallback${c.reset}`);
+        }
+    }
+    // Step 4: Configure each agent
+    console.log(`\n${c.bold}Configuring agents...${c.reset}\n`);
+    for (const agent of selectedAgents) {
+        const hasExisting = checkExistingConfig(agent.id);
+        if (hasExisting) {
+            const overwrite = await promptConfirm(`  ${agent.name} already configured. Update?`, true);
+            if (!overwrite) {
+                console.log(`  ${icon.dot} Skipped ${agent.name}`);
+                continue;
+            }
+        }
+        try {
+            await agent.configure(apiKey);
+        }
+        catch (err) {
+            console.log(`  ${icon.cross} Failed to configure ${agent.name}: ${err instanceof Error ? err.message : 'unknown error'}`);
+        }
+    }
+    // Done!
+    console.log(`
+${c.green}${c.bold}Setup complete!${c.reset}
+
+${c.bold}Next steps:${c.reset}
+  ${icon.arrow} Restart your AI agent / IDE
+  ${icon.arrow} Start coding — Vibescope tracks automatically
+
+${c.dim}Need help? https://vibescope.dev/docs${c.reset}
+`);
+}
+// ============================================================================
+// CLI Entry Point
+// ============================================================================
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    if (command === 'init' || !command) {
+        await runInit();
+    }
+    else if (command === '--help' || command === '-h' || command === 'help') {
+        console.log(`
+${c.bold}Vibescope CLI${c.reset}
+
+Usage:
+  npx vibescope init     Set up Vibescope for your AI agents
+  npx vibescope help     Show this help
+
+Docs: https://vibescope.dev/docs
+`);
+    }
+    else {
+        console.log(`Unknown command: ${command}\nRun ${c.cyan}npx vibescope help${c.reset} for usage.`);
+        process.exit(1);
+    }
+}
+const isMainModule = import.meta.url === `file://${process.argv[1]?.replace(/\\/g, '/')}`;
+if (isMainModule || process.argv[1]?.endsWith('cli-init.js')) {
+    main().catch((err) => {
+        console.error(`${icon.cross} ${err instanceof Error ? err.message : 'Unknown error'}`);
+        process.exit(1);
+    });
+}

package/dist/handlers/cloud-agents.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Cloud Agents Handlers
+ *
+ * Handles cloud agent management:
+ * - cleanup_stale_cloud_agents
+ * - list_cloud_agents
+ */
+import type { Handler, HandlerRegistry } from './types.js';
+/**
+ * Clean up stale cloud agents that failed to start or lost connection.
+ * Only operates on agents in the specified project (security scoped).
+ */
+export declare const cleanupStaleCloudAgents: Handler;
+/**
+ * List cloud agents for a project with optional status filter.
+ */
+export declare const listCloudAgents: Handler;
+/**
+ * Cloud agents handlers registry
+ */
+export declare const cloudAgentHandlers: HandlerRegistry;