@vibescope/mcp-server 0.2.4 → 0.2.6

package/README.md

@@ -45,14 +45,27 @@ Then configure:
 
 ## Quick Start
 
-### Claude Code
+### Interactive Setup (Recommended)
+
+Run the setup wizard to automatically configure Vibescope for your IDE:
+
+```bash
+npx -p @vibescope/mcp-server vibescope-cli setup
+```
+
+This guides you through:
+1. Selecting your IDE (Claude Code, Claude Desktop, Cursor, or Gemini CLI)
+2. Getting your API key from the Vibescope dashboard
+3. Writing the configuration file
+
+### Claude Code (Manual)
 
 ```bash
 claude mcp add vibescope npx @vibescope/mcp-server@latest \
   --env VIBESCOPE_API_KEY=your_key
 ```
 
-### Gemini CLI
+### Gemini CLI (Manual)
 
 Add to your `~/.gemini/settings.json` or project-level `.gemini/settings.json`:
 

package/dist/cli.d.ts

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
 /**
- * Vibescope CLI - Enforcement verification tool
+ * Vibescope CLI - Setup wizard and enforcement verification tool
  *
- * Used by Claude Code Stop hook to verify agent compliance with Vibescope tracking.
- * Exit codes:
+ * Commands:
+ *   setup   - Interactive wizard to configure Vibescope for your IDE
+ *   verify  - Check agent compliance with Vibescope tracking (used by hooks)
+ *
+ * Exit codes (for verify command):
  *   0 = Compliant (allow exit)
  *   1 = Non-compliant (block exit, loop back)
  *   2 = Error (allow exit with warning)

package/dist/cli.js

@@ -1,14 +1,18 @@
 #!/usr/bin/env node
 /**
- * Vibescope CLI - Enforcement verification tool
+ * Vibescope CLI - Setup wizard and enforcement verification tool
  *
- * Used by Claude Code Stop hook to verify agent compliance with Vibescope tracking.
- * Exit codes:
+ * Commands:
+ *   setup   - Interactive wizard to configure Vibescope for your IDE
+ *   verify  - Check agent compliance with Vibescope tracking (used by hooks)
+ *
+ * Exit codes (for verify command):
  *   0 = Compliant (allow exit)
  *   1 = Non-compliant (block exit, loop back)
  *   2 = Error (allow exit with warning)
  */
 import { execSync } from 'child_process';
+import { runSetup } from './setup.js';
 // ============================================================================
 // Configuration (read at runtime for testability)
 // ============================================================================
@@ -89,7 +93,12 @@ export async function verify(gitUrl, projectId) {
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
-    if (command === 'verify') {
+    if (command === 'setup') {
+        // Run interactive setup wizard
+        await runSetup();
+        process.exit(0);
+    }
+    else if (command === 'verify') {
         // Parse --git-url and --project-id flags
         let gitUrl;
         let projectId;
@@ -115,29 +124,38 @@ async function main() {
         }
     }
     else if (command === 'help' || command === '--help' || command === '-h') {
-        console.log(`
-Vibescope CLI - Enforcement verification tool
-
-Usage:
-  vibescope-cli verify [options]    Check Vibescope compliance before exit
-
-Options:
-  --git-url <url>       Git repository URL (auto-detected if not provided)
-  --project-id <id>     Vibescope project UUID
-
-Exit Codes:
-  0  Compliant - agent can exit
-  1  Non-compliant - agent should continue work
-  2  Error - allow exit with warning
-
-Environment Variables:
-  VIBESCOPE_API_KEY       Required - Your Vibescope API key
-  VIBESCOPE_API_URL       Optional - API URL (default: https://vibescope.dev)
+        console.log(`
+Vibescope CLI - Setup wizard and enforcement verification tool
+
+Usage:
+  vibescope-cli setup                 Interactive setup wizard for your IDE
+  vibescope-cli verify [options]      Check Vibescope compliance before exit
+
+Setup:
+  Configures Vibescope MCP integration for:
+  - Claude Code (CLI)
+  - Claude Desktop
+  - Cursor
+  - Gemini CLI
+
+Verify Options:
+  --git-url <url>       Git repository URL (auto-detected if not provided)
+  --project-id <id>     Vibescope project UUID
+
+Exit Codes (verify):
+  0  Compliant - agent can exit
+  1  Non-compliant - agent should continue work
+  2  Error - allow exit with warning
+
+Environment Variables:
+  VIBESCOPE_API_KEY       Required for verify - Your Vibescope API key
+  VIBESCOPE_API_URL       Optional - API URL (default: https://vibescope.dev)
 `);
         process.exit(0);
     }
     else {
-        console.error('Usage: vibescope-cli verify [--git-url <url>] [--project-id <id>]');
+        console.error('Usage: vibescope-cli setup');
+        console.error('       vibescope-cli verify [--git-url <url>] [--project-id <id>]');
         console.error('       vibescope-cli --help');
         process.exit(2);
     }

package/dist/setup.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Vibescope Setup Wizard
+ * Guides users through setting up Vibescope MCP integration
+ *
+ * Usage: vibescope-cli setup
+ */
+export interface IdeConfig {
+    name: string;
+    displayName: string;
+    configPath: string;
+    detected: boolean;
+    configFormat: 'mcp-json' | 'settings-json';
+}
+export declare function detectIdes(): IdeConfig[];
+export declare function validateApiKey(apiKey: string): Promise<{
+    valid: boolean;
+    message: string;
+}>;
+export declare function readExistingConfig(configPath: string): Record<string, unknown>;
+export declare function writeConfig(configPath: string, config: Record<string, unknown>): void;
+export declare function generateMcpConfig(apiKey: string, ide: IdeConfig): Record<string, unknown>;
+export declare function runSetup(): Promise<void>;

package/dist/setup.js

@@ -0,0 +1,313 @@
+/**
+ * Vibescope Setup Wizard
+ * Guides users through setting up Vibescope MCP integration
+ *
+ * Usage: vibescope-cli setup
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { homedir, platform } from 'node:os';
+import { join, dirname } from 'node:path';
+import { exec } from 'node:child_process';
+const VIBESCOPE_SETTINGS_URL = 'https://vibescope.dev/dashboard/settings';
+const DEFAULT_SUPABASE_URL = 'https://uuneucmuubpgswvfijwd.supabase.co';
+// ============================================================================
+// Config Path Helpers
+// ============================================================================
+function getClaudeDesktopConfigPath() {
+    const plat = platform();
+    const home = homedir();
+    if (plat === 'darwin') {
+        return join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+    }
+    else if (plat === 'win32') {
+        return join(home, 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json');
+    }
+    else {
+        return join(home, '.config', 'Claude', 'claude_desktop_config.json');
+    }
+}
+function getCursorConfigPath() {
+    const plat = platform();
+    const home = homedir();
+    if (plat === 'darwin') {
+        return join(home, 'Library', 'Application Support', 'Cursor', 'User', 'globalStorage', 'saoudrizwan.claude-dev', 'settings', 'cline_mcp_settings.json');
+    }
+    else if (plat === 'win32') {
+        return join(home, 'AppData', 'Roaming', 'Cursor', 'User', 'globalStorage', 'saoudrizwan.claude-dev', 'settings', 'cline_mcp_settings.json');
+    }
+    else {
+        return join(home, '.config', 'Cursor', 'User', 'globalStorage', 'saoudrizwan.claude-dev', 'settings', 'cline_mcp_settings.json');
+    }
+}
+function getGeminiConfigPath() {
+    return join(homedir(), '.gemini', 'settings.json');
+}
+// ============================================================================
+// IDE Detection
+// ============================================================================
+export function detectIdes() {
+    const ides = [
+        {
+            name: 'claude-code',
+            displayName: 'Claude Code (CLI)',
+            configPath: '.mcp.json',
+            detected: true,
+            configFormat: 'mcp-json',
+        },
+        {
+            name: 'claude-desktop',
+            displayName: 'Claude Desktop',
+            configPath: getClaudeDesktopConfigPath(),
+            detected: existsSync(dirname(getClaudeDesktopConfigPath())),
+            configFormat: 'mcp-json',
+        },
+        {
+            name: 'cursor',
+            displayName: 'Cursor',
+            configPath: getCursorConfigPath(),
+            detected: existsSync(dirname(getCursorConfigPath())),
+            configFormat: 'mcp-json',
+        },
+        {
+            name: 'gemini',
+            displayName: 'Gemini CLI',
+            configPath: getGeminiConfigPath(),
+            detected: true,
+            configFormat: 'settings-json',
+        },
+    ];
+    return ides;
+}
+// ============================================================================
+// User Prompts
+// ============================================================================
+async 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 promptSelect(question, options) {
+    console.log('\n' + question + '\n');
+    options.forEach((opt, i) => {
+        console.log('  ' + (i + 1) + ') ' + opt.label);
+    });
+    const answer = await prompt('\nEnter number: ');
+    const index = parseInt(answer, 10) - 1;
+    if (index >= 0 && index < options.length) {
+        return options[index].value;
+    }
+    console.log('Invalid selection, using first option.');
+    return options[0].value;
+}
+// ============================================================================
+// Browser & Validation
+// ============================================================================
+function openBrowser(url) {
+    return new Promise((resolve) => {
+        const plat = platform();
+        let cmd;
+        if (plat === 'darwin') {
+            cmd = 'open "' + url + '"';
+        }
+        else if (plat === 'win32') {
+            cmd = 'start "" "' + url + '"';
+        }
+        else {
+            cmd = 'xdg-open "' + url + '"';
+        }
+        exec(cmd, (error) => {
+            if (error) {
+                console.log('\nCould not open browser automatically.');
+                console.log('Please visit: ' + url + '\n');
+            }
+            resolve();
+        });
+    });
+}
+export async function validateApiKey(apiKey) {
+    try {
+        const response = await fetch(DEFAULT_SUPABASE_URL + '/rest/v1/api_keys?key=eq.' + apiKey + '&select=id', {
+            headers: {
+                'apikey': apiKey,
+                'Authorization': 'Bearer ' + apiKey,
+            },
+        });
+        if (response.ok) {
+            return { valid: true, message: 'API key validated successfully!' };
+        }
+        else {
+            return { valid: false, message: 'API key appears to be invalid.' };
+        }
+    }
+    catch {
+        return { valid: true, message: 'Could not validate API key (network issue), but proceeding.' };
+    }
+}
+// ============================================================================
+// Config Management
+// ============================================================================
+export function readExistingConfig(configPath) {
+    if (existsSync(configPath)) {
+        try {
+            return JSON.parse(readFileSync(configPath, 'utf-8'));
+        }
+        catch {
+            return {};
+        }
+    }
+    return {};
+}
+export function writeConfig(configPath, config) {
+    const dir = dirname(configPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+}
+export function generateMcpConfig(apiKey, ide) {
+    const vibescopeServer = {
+        command: 'npx',
+        args: ['-y', '-p', '@vibescope/mcp-server@latest', 'vibescope-mcp'],
+        env: {
+            VIBESCOPE_API_KEY: apiKey,
+        },
+    };
+    // Gemini CLI uses a different config format with additional options
+    if (ide.configFormat === 'settings-json') {
+        return {
+            mcpServers: {
+                vibescope: {
+                    ...vibescopeServer,
+                    timeout: 30000,
+                    trust: true,
+                },
+            },
+        };
+    }
+    // Standard MCP config for Claude Code, Claude Desktop, Cursor
+    return {
+        mcpServers: {
+            vibescope: vibescopeServer,
+        },
+    };
+}
+// ============================================================================
+// Main Setup Flow
+// ============================================================================
+export async function runSetup() {
+    console.log('\n=================================');
+    console.log('   Vibescope Setup Wizard');
+    console.log('=================================\n');
+    // Step 1: Detect IDEs
+    const ides = detectIdes();
+    const detectedIdes = ides.filter(ide => ide.detected);
+    console.log('Available development environments:');
+    detectedIdes.forEach(ide => {
+        console.log('  - ' + ide.displayName);
+    });
+    // Step 2: Select IDE to configure
+    let selectedIde;
+    if (detectedIdes.length === 1) {
+        selectedIde = detectedIdes[0];
+        console.log('\nConfiguring for ' + selectedIde.displayName + '...');
+    }
+    else {
+        const ideChoice = await promptSelect('Which environment do you want to configure?', detectedIdes.map(ide => ({ label: ide.displayName, value: ide.name })));
+        selectedIde = ides.find(ide => ide.name === ideChoice) || detectedIdes[0];
+    }
+    // Step 3: Check if config already exists
+    if (existsSync(selectedIde.configPath)) {
+        const existingConfig = readExistingConfig(selectedIde.configPath);
+        const hasMcpServers = 'mcpServers' in existingConfig;
+        const hasVibescope = hasMcpServers &&
+            typeof existingConfig.mcpServers === 'object' &&
+            existingConfig.mcpServers !== null &&
+            'vibescope' in existingConfig.mcpServers;
+        if (hasVibescope) {
+            const overwrite = await prompt('\nVibescope is already configured. Reconfigure? (y/N): ');
+            if (overwrite.toLowerCase() !== 'y') {
+                console.log('\nSetup cancelled. Your existing configuration is preserved.');
+                return;
+            }
+        }
+    }
+    // Step 4: Get API key
+    console.log('\n--- Step 1: Get your API key ---\n');
+    console.log('Opening Vibescope settings page in your browser...');
+    console.log("Create an API key if you don't have one, then copy it.\n");
+    await openBrowser(VIBESCOPE_SETTINGS_URL);
+    const apiKey = await prompt('Paste your Vibescope API key: ');
+    if (!apiKey) {
+        console.error('\nError: API key is required.');
+        process.exit(1);
+    }
+    // Validate API key
+    console.log('\nValidating API key...');
+    const validation = await validateApiKey(apiKey);
+    console.log(validation.message);
+    if (!validation.valid) {
+        const proceed = await prompt('Proceed anyway? (y/N): ');
+        if (proceed.toLowerCase() !== 'y') {
+            process.exit(1);
+        }
+    }
+    // Step 5: Write configuration
+    console.log('\n--- Step 2: Writing Configuration ---\n');
+    const mcpConfig = generateMcpConfig(apiKey, selectedIde);
+    // Merge with existing config if present
+    const existingConfig = readExistingConfig(selectedIde.configPath);
+    const existingMcpServers = typeof existingConfig.mcpServers === 'object' && existingConfig.mcpServers !== null
+        ? existingConfig.mcpServers
+        : {};
+    const newMcpServers = mcpConfig.mcpServers;
+    const mergedConfig = {
+        ...existingConfig,
+        mcpServers: {
+            ...existingMcpServers,
+            ...newMcpServers,
+        },
+    };
+    writeConfig(selectedIde.configPath, mergedConfig);
+    console.log('Configuration written to: ' + selectedIde.configPath);
+    // Step 6: IDE-specific next steps
+    console.log('\n=================================');
+    console.log('   Setup Complete!');
+    console.log('=================================\n');
+    switch (selectedIde.name) {
+        case 'claude-code':
+            console.log('Next steps:');
+            console.log('  1. Restart Claude Code (or run: claude mcp reload)');
+            console.log('  2. Verify connection: claude mcp list');
+            console.log('  3. Start using Vibescope in your conversation');
+            break;
+        case 'claude-desktop':
+            console.log('Next steps:');
+            console.log('  1. Restart Claude Desktop');
+            console.log('  2. Vibescope tools will be available in your conversations');
+            break;
+        case 'cursor':
+            console.log('Next steps:');
+            console.log('  1. Restart Cursor');
+            console.log('  2. Open the MCP settings to verify Vibescope is connected');
+            break;
+        case 'gemini':
+            console.log('Next steps:');
+            console.log('  1. Restart Gemini CLI');
+            console.log('  2. Verify connection: gemini mcp list');
+            console.log('  3. Start using Vibescope in your conversation');
+            break;
+        default:
+            console.log('Next steps:');
+            console.log('  1. Restart your IDE/CLI');
+            console.log('  2. Verify Vibescope is connected');
+    }
+    console.log('\nHappy building!\n');
+}

package/dist/token-tracking.js

@@ -19,8 +19,10 @@ export function estimateTokens(obj) {
         const json = JSON.stringify(obj);
         return Math.max(1, Math.ceil(json.length / 4));
     }
-    catch {
-        // If JSON serialization fails, return a minimal estimate
+    catch (error) {
+        // Log warning when serialization fails (e.g., circular references, BigInt)
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.warn(`[Vibescope] Token estimation failed: ${errorMessage}. Returning minimal estimate of 1 token.`);
         return 1;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibescope/mcp-server",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "MCP server for Vibescope - AI project tracking tools",
   "type": "module",
   "main": "dist/index.js",