@vibescope/mcp-server 0.4.6 → 0.4.7

package/dist/api-client.d.ts

@@ -27,7 +27,9 @@ export declare class VibescopeApiClient {
     private retryConfig;
     constructor(config: ApiClientConfig);
     private request;
-    validateAuth(): Promise<ApiResponse<{
+    validateAuth(options?: {
+        timeoutMs?: number;
+    }): Promise<ApiResponse<{
         valid: boolean;
         user_id: string;
         api_key_id: string;

package/dist/api-client.js

@@ -47,21 +47,30 @@ export class VibescopeApiClient {
             retryStatusCodes: config.retry?.retryStatusCodes ?? DEFAULT_RETRY_STATUS_CODES,
         };
     }
-    async request(method, path, body) {
+    async request(method, path, body, options) {
         const url = `${this.baseUrl}${path}`;
         const { maxRetries, baseDelayMs, maxDelayMs, retryStatusCodes } = this.retryConfig;
         let lastError = null;
         let lastResponse = null;
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            let timeoutId;
             try {
-                const response = await fetch(url, {
+                const fetchOptions = {
                     method,
                     headers: {
                         'Content-Type': 'application/json',
                         'X-API-Key': this.apiKey
                     },
-                    body: body ? JSON.stringify(body) : undefined
-                });
+                    body: body ? JSON.stringify(body) : undefined,
+                };
+                if (options?.timeoutMs) {
+                    const controller = new AbortController();
+                    timeoutId = setTimeout(() => controller.abort(), options.timeoutMs);
+                    fetchOptions.signal = controller.signal;
+                }
+                const response = await fetch(url, fetchOptions);
+                if (timeoutId)
+                    clearTimeout(timeoutId);
                 // Check if we should retry this status code
                 if (retryStatusCodes.includes(response.status) && attempt < maxRetries) {
                     lastResponse = response;
@@ -94,7 +103,15 @@ export class VibescopeApiClient {
                 };
             }
             catch (err) {
-                lastError = err instanceof Error ? err : new Error('Network error');
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+                // Detect AbortError from timeout
+                if (err instanceof Error && err.name === 'AbortError' && options?.timeoutMs) {
+                    lastError = new Error(`Request timed out after ${options.timeoutMs}ms`);
+                }
+                else {
+                    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);
@@ -130,10 +147,10 @@ export class VibescopeApiClient {
         };
     }
     // Auth endpoints
-    async validateAuth() {
+    async validateAuth(options) {
         return this.request('POST', '/api/mcp/auth/validate', {
             api_key: this.apiKey
-        });
+        }, options);
     }
     // Session endpoints
     async startSession(params) {

package/dist/cli-init.js

@@ -236,16 +236,17 @@ function writeJsonFile(path, data) {
 }
 function buildMcpServerConfig(apiKey) {
     const isWindows = platform() === 'win32';
+    // Prefer globally installed binary (instant start) with npx fallback
     if (isWindows) {
         return {
             command: 'cmd',
-            args: ['/c', 'npx', '-y', '-p', '@vibescope/mcp-server@latest', 'vibescope-mcp'],
+            args: ['/c', 'where vibescope-mcp >nul 2>&1 && vibescope-mcp || npx -y -p @vibescope/mcp-server@latest vibescope-mcp'],
             env: { VIBESCOPE_API_KEY: apiKey },
         };
     }
     return {
-        command: 'npx',
-        args: ['-y', '-p', '@vibescope/mcp-server@latest', 'vibescope-mcp'],
+        command: 'bash',
+        args: ['-c', 'command -v vibescope-mcp >/dev/null 2>&1 && exec vibescope-mcp || exec npx -y -p @vibescope/mcp-server@latest vibescope-mcp'],
         env: { VIBESCOPE_API_KEY: apiKey },
     };
 }

package/dist/handlers/version.js

@@ -7,7 +7,7 @@ import { checkVersion, getLocalVersion } from '../version.js';
 const PACKAGE_NAME = '@vibescope/mcp-server';
 export const versionHandlers = {
     check_mcp_version: async (_args, _ctx) => {
-        const info = await checkVersion();
+        const info = await checkVersion({ bypassCache: true });
         if (info.error) {
             return success({
                 current_version: info.current,

package/dist/index.js

@@ -141,9 +141,9 @@ initApiClient({ apiKey: API_KEY });
 // ============================================================================
 // Authentication
 // ============================================================================
-async function validateApiKey() {
+async function validateApiKey(timeoutMs) {
     const apiClient = getApiClient();
-    const response = await apiClient.validateAuth();
+    const response = await apiClient.validateAuth(timeoutMs ? { timeoutMs } : undefined);
     if (!response.ok || !response.data?.valid) {
         return null;
     }
@@ -153,6 +153,61 @@ async function validateApiKey() {
         scope: 'personal', // API handles authorization, scope not needed locally
     };
 }
+// Deferred auth: started eagerly but awaited on first tool call
+let deferredAuthPromise = null;
+let resolvedAuth = null;
+let authError = null;
+function startDeferredAuth() {
+    deferredAuthPromise = validateApiKey(10000)
+        .then((auth) => {
+        resolvedAuth = auth;
+        if (!auth)
+            authError = 'Invalid API key';
+        return auth;
+    })
+        .catch((err) => {
+        authError = err instanceof Error ? err.message : 'Auth validation failed';
+        return null;
+    });
+}
+async function getAuth() {
+    // If already resolved, return immediately
+    if (resolvedAuth)
+        return resolvedAuth;
+    // Await the deferred promise
+    if (deferredAuthPromise) {
+        const auth = await deferredAuthPromise;
+        if (auth)
+            return auth;
+    }
+    // Auth failed — return structured error
+    const troubleshooting = [
+        'MCP auth validation failed.',
+        authError ? `Reason: ${authError}` : '',
+        'Troubleshooting:',
+        '1. Check your API key is valid at https://vibescope.dev/dashboard/settings',
+        '2. Verify VIBESCOPE_API_KEY environment variable is set correctly',
+        '3. Check network connectivity to vibescope.dev',
+        '4. Restart Claude Code and try again',
+    ].filter(Boolean).join('\n');
+    throw new Error(troubleshooting);
+}
+// Deferred update warning: fire-and-forget, delivered on first tool call
+let updateWarningPromise = null;
+let resolvedUpdateWarning = undefined; // undefined = not yet resolved
+function startDeferredUpdateCheck() {
+    updateWarningPromise = getUpdateWarning().catch(() => null);
+    updateWarningPromise.then((warning) => {
+        resolvedUpdateWarning = warning;
+    });
+}
+function consumeUpdateWarning() {
+    if (resolvedUpdateWarning === undefined)
+        return null; // not ready yet
+    const warning = resolvedUpdateWarning;
+    resolvedUpdateWarning = null; // deliver only once
+    return warning;
+}
 // Tool definitions imported from tools.ts
 // ============================================================================
 // Tool Handlers
@@ -205,17 +260,10 @@ async function handleTool(auth, name, args) {
 // Server Setup
 // ============================================================================
 async function main() {
-    // Validate API key on startup via API
-    const auth = await validateApiKey();
-    if (!auth) {
-        console.error('Invalid API key');
-        process.exit(1);
-    }
-    // Check for updates (non-blocking, with timeout)
-    const updateWarning = await getUpdateWarning();
-    const serverInstructions = updateWarning
-        ? `${updateWarning}\n\nVibescope MCP server - AI project tracking and coordination tools.`
-        : 'Vibescope MCP server - AI project tracking and coordination tools.';
+    // Start auth validation eagerly in background (10s timeout) — don't block startup
+    startDeferredAuth();
+    // Start update check in background — delivered on first tool call if available
+    startDeferredUpdateCheck();
     const server = new Server({
         name: 'vibescope',
         version: '0.1.0',
@@ -223,7 +271,7 @@ async function main() {
         capabilities: {
             tools: {},
         },
-        instructions: serverInstructions,
+        instructions: 'Vibescope MCP server - AI project tracking and coordination tools.',
     });
     // List available tools
     server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -242,6 +290,22 @@ async function main() {
     // Handle tool calls
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
+        // Await deferred auth on first tool call (usually already resolved)
+        let auth;
+        try {
+            auth = await getAuth();
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: err instanceof Error ? err.message : 'Auth validation failed',
+                    },
+                ],
+                isError: true,
+            };
+        }
         // Check rate limit
         const rateCheck = rateLimiter.check(auth.apiKeyId);
         if (!rateCheck.allowed) {
@@ -267,6 +331,14 @@ async function main() {
                     text: JSON.stringify(result, null, 2),
                 },
             ];
+            // Deliver update warning on first tool call (if available)
+            const updateWarning = consumeUpdateWarning();
+            if (updateWarning) {
+                content.push({
+                    type: 'text',
+                    text: `\n--- ${updateWarning} ---`,
+                });
+            }
             // Include reminder nudge if applicable
             const reminder = getReminder(name);
             if (reminder) {

package/dist/setup.js

@@ -176,13 +176,19 @@ export function writeConfig(configPath, config) {
     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,
-        },
-    };
+    // Prefer globally installed binary (instant start) with npx fallback
+    const isWindows = platform() === 'win32';
+    const vibescopeServer = isWindows
+        ? {
+            command: 'cmd',
+            args: ['/c', 'where vibescope-mcp >nul 2>&1 && vibescope-mcp || npx -y -p @vibescope/mcp-server@latest vibescope-mcp'],
+            env: { VIBESCOPE_API_KEY: apiKey },
+        }
+        : {
+            command: 'bash',
+            args: ['-c', 'command -v vibescope-mcp >/dev/null 2>&1 && exec vibescope-mcp || exec npx -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 {

package/dist/version.d.ts

@@ -2,7 +2,9 @@
  * Version checking utilities
  *
  * Compares the locally installed version against the latest published
- * version on npm to detect available updates.
+ * version on npm to detect available updates. Uses a file-based cache
+ * (~/.vibescope/version-cache.json) with 1-hour TTL to avoid hitting
+ * the npm registry on every startup.
  */
 export interface VersionInfo {
     current: string;
@@ -17,11 +19,15 @@ export declare function getLocalVersion(): string;
 /**
  * Fetch the latest published version from npm registry
  */
-export declare function getLatestVersion(): Promise<string | null>;
+export declare function getLatestVersion(options?: {
+    bypassCache?: boolean;
+}): Promise<string | null>;
 /**
  * Check if an update is available
  */
-export declare function checkVersion(): Promise<VersionInfo>;
+export declare function checkVersion(options?: {
+    bypassCache?: boolean;
+}): Promise<VersionInfo>;
 /**
  * Get the update warning message for server instructions, or null if up to date
  */

package/dist/version.js

@@ -2,13 +2,19 @@
  * Version checking utilities
  *
  * Compares the locally installed version against the latest published
- * version on npm to detect available updates.
+ * version on npm to detect available updates. Uses a file-based cache
+ * (~/.vibescope/version-cache.json) with 1-hour TTL to avoid hitting
+ * the npm registry on every startup.
  */
-import { readFileSync } from 'fs';
-import { resolve, dirname } from 'path';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { resolve, dirname, join } from 'path';
 import { fileURLToPath } from 'url';
+import { homedir } from 'os';
 const NPM_REGISTRY_URL = 'https://registry.npmjs.org/@vibescope/mcp-server';
 const PACKAGE_NAME = '@vibescope/mcp-server';
+const CACHE_DIR = join(homedir(), '.vibescope');
+const CACHE_PATH = join(CACHE_DIR, 'version-cache.json');
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 /**
  * Get the current locally installed version from package.json
  */
@@ -23,13 +29,51 @@ export function getLocalVersion() {
         return 'unknown';
     }
 }
+/**
+ * Read version from file-based cache if still valid
+ */
+function readVersionCache() {
+    try {
+        if (!existsSync(CACHE_PATH))
+            return null;
+        const raw = JSON.parse(readFileSync(CACHE_PATH, 'utf-8'));
+        if (Date.now() - raw.fetchedAt < CACHE_TTL_MS) {
+            return raw.latestVersion;
+        }
+        return null; // expired
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write version to file-based cache
+ */
+function writeVersionCache(version) {
+    try {
+        if (!existsSync(CACHE_DIR)) {
+            mkdirSync(CACHE_DIR, { recursive: true });
+        }
+        const cache = { latestVersion: version, fetchedAt: Date.now() };
+        writeFileSync(CACHE_PATH, JSON.stringify(cache, null, 2) + '\n');
+    }
+    catch {
+        // Non-critical — silently ignore write failures
+    }
+}
 /**
  * Fetch the latest published version from npm registry
  */
-export async function getLatestVersion() {
+export async function getLatestVersion(options) {
+    // Check cache first (unless bypassed)
+    if (!options?.bypassCache) {
+        const cached = readVersionCache();
+        if (cached)
+            return cached;
+    }
     try {
         const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), 5000);
+        const timeout = setTimeout(() => controller.abort(), 3000);
         const response = await fetch(`${NPM_REGISTRY_URL}/latest`, {
             signal: controller.signal,
             headers: { 'Accept': 'application/json' },
@@ -38,7 +82,11 @@ export async function getLatestVersion() {
         if (!response.ok)
             return null;
         const data = (await response.json());
-        return data.version ?? null;
+        const version = data.version ?? null;
+        // Write to cache on successful fetch
+        if (version)
+            writeVersionCache(version);
+        return version;
     }
     catch {
         return null;
@@ -62,9 +110,9 @@ function isNewer(current, latest) {
 /**
  * Check if an update is available
  */
-export async function checkVersion() {
+export async function checkVersion(options) {
     const current = getLocalVersion();
-    const latest = await getLatestVersion();
+    const latest = await getLatestVersion(options);
     if (!latest) {
         return {
             current,

package/docs/TOOLS.md

@@ -2,7 +2,7 @@
 
 > Auto-generated from tool definitions. Do not edit manually.
 >
-> Generated: 2026-03-01
+> Generated: 2026-03-04
 >
 > Total tools: 167
 

package/package.json

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

package/src/api-client.ts

@@ -81,22 +81,32 @@ export class VibescopeApiClient {
 		};
 	}
 
-	private async request<T>(method: string, path: string, body?: unknown): Promise<ApiResponse<T>> {
+	private async request<T>(method: string, path: string, body?: unknown, options?: { timeoutMs?: number }): Promise<ApiResponse<T>> {
 		const url = `${this.baseUrl}${path}`;
 		const { maxRetries, baseDelayMs, maxDelayMs, retryStatusCodes } = this.retryConfig;
 		let lastError: Error | null = null;
 		let lastResponse: Response | null = null;
 
 		for (let attempt = 0; attempt <= maxRetries; attempt++) {
+			let timeoutId: ReturnType<typeof setTimeout> | undefined;
 			try {
-				const response = await fetch(url, {
+				const fetchOptions: RequestInit = {
 					method,
 					headers: {
 						'Content-Type': 'application/json',
 						'X-API-Key': this.apiKey
 					},
-					body: body ? JSON.stringify(body) : undefined
-				});
+					body: body ? JSON.stringify(body) : undefined,
+				};
+
+				if (options?.timeoutMs) {
+					const controller = new AbortController();
+					timeoutId = setTimeout(() => controller.abort(), options.timeoutMs);
+					fetchOptions.signal = controller.signal;
+				}
+
+				const response = await fetch(url, fetchOptions);
+				if (timeoutId) clearTimeout(timeoutId);
 
 				// Check if we should retry this status code
 				if (retryStatusCodes.includes(response.status) && attempt < maxRetries) {
@@ -132,7 +142,13 @@ export class VibescopeApiClient {
 					data
 				};
 			} catch (err) {
-				lastError = err instanceof Error ? err : new Error('Network error');
+				if (timeoutId) clearTimeout(timeoutId);
+				// Detect AbortError from timeout
+				if (err instanceof Error && err.name === 'AbortError' && options?.timeoutMs) {
+					lastError = new Error(`Request timed out after ${options.timeoutMs}ms`);
+				} else {
+					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);
@@ -170,7 +186,7 @@ export class VibescopeApiClient {
 	}
 
 	// Auth endpoints
-	async validateAuth(): Promise<ApiResponse<{
+	async validateAuth(options?: { timeoutMs?: number }): Promise<ApiResponse<{
 		valid: boolean;
 		user_id: string;
 		api_key_id: string;
@@ -178,7 +194,7 @@ export class VibescopeApiClient {
 	}>> {
 		return this.request('POST', '/api/mcp/auth/validate', {
 			api_key: this.apiKey
-		});
+		}, options);
 	}
 
 	// Session endpoints

package/src/cli-init.ts

@@ -275,16 +275,17 @@ function writeJsonFile(path: string, data: Record<string, unknown>): void {
 
 function buildMcpServerConfig(apiKey: string): Record<string, unknown> {
 	const isWindows = platform() === 'win32';
+	// Prefer globally installed binary (instant start) with npx fallback
 	if (isWindows) {
 		return {
 			command: 'cmd',
-			args: ['/c', 'npx', '-y', '-p', '@vibescope/mcp-server@latest', 'vibescope-mcp'],
+			args: ['/c', 'where vibescope-mcp >nul 2>&1 && vibescope-mcp || npx -y -p @vibescope/mcp-server@latest vibescope-mcp'],
 			env: { VIBESCOPE_API_KEY: apiKey },
 		};
 	}
 	return {
-		command: 'npx',
-		args: ['-y', '-p', '@vibescope/mcp-server@latest', 'vibescope-mcp'],
+		command: 'bash',
+		args: ['-c', 'command -v vibescope-mcp >/dev/null 2>&1 && exec vibescope-mcp || exec npx -y -p @vibescope/mcp-server@latest vibescope-mcp'],
 		env: { VIBESCOPE_API_KEY: apiKey },
 	};
 }

package/src/handlers/version.ts

@@ -11,7 +11,7 @@ const PACKAGE_NAME = '@vibescope/mcp-server';
 
 export const versionHandlers: HandlerRegistry = {
 	check_mcp_version: async (_args, _ctx) => {
-		const info = await checkVersion();
+		const info = await checkVersion({ bypassCache: true });
 
 		if (info.error) {
 			return success({

package/src/index.ts

@@ -574,9 +574,9 @@ initApiClient({ apiKey: API_KEY });
 // Authentication
 // ============================================================================
 
-async function validateApiKey(): Promise<AuthContext | null> {
+async function validateApiKey(timeoutMs?: number): Promise<AuthContext | null> {
 	const apiClient = getApiClient();
-	const response = await apiClient.validateAuth();
+	const response = await apiClient.validateAuth(timeoutMs ? { timeoutMs } : undefined);
 
 	if (!response.ok || !response.data?.valid) {
 		return null;
@@ -589,6 +589,66 @@ async function validateApiKey(): Promise<AuthContext | null> {
 	};
 }
 
+// Deferred auth: started eagerly but awaited on first tool call
+let deferredAuthPromise: Promise<AuthContext | null> | null = null;
+let resolvedAuth: AuthContext | null = null;
+let authError: string | null = null;
+
+function startDeferredAuth(): void {
+	deferredAuthPromise = validateApiKey(10000)
+		.then((auth) => {
+			resolvedAuth = auth;
+			if (!auth) authError = 'Invalid API key';
+			return auth;
+		})
+		.catch((err) => {
+			authError = err instanceof Error ? err.message : 'Auth validation failed';
+			return null;
+		});
+}
+
+async function getAuth(): Promise<AuthContext> {
+	// If already resolved, return immediately
+	if (resolvedAuth) return resolvedAuth;
+
+	// Await the deferred promise
+	if (deferredAuthPromise) {
+		const auth = await deferredAuthPromise;
+		if (auth) return auth;
+	}
+
+	// Auth failed — return structured error
+	const troubleshooting = [
+		'MCP auth validation failed.',
+		authError ? `Reason: ${authError}` : '',
+		'Troubleshooting:',
+		'1. Check your API key is valid at https://vibescope.dev/dashboard/settings',
+		'2. Verify VIBESCOPE_API_KEY environment variable is set correctly',
+		'3. Check network connectivity to vibescope.dev',
+		'4. Restart Claude Code and try again',
+	].filter(Boolean).join('\n');
+
+	throw new Error(troubleshooting);
+}
+
+// Deferred update warning: fire-and-forget, delivered on first tool call
+let updateWarningPromise: Promise<string | null> | null = null;
+let resolvedUpdateWarning: string | null | undefined = undefined; // undefined = not yet resolved
+
+function startDeferredUpdateCheck(): void {
+	updateWarningPromise = getUpdateWarning().catch(() => null);
+	updateWarningPromise.then((warning) => {
+		resolvedUpdateWarning = warning;
+	});
+}
+
+function consumeUpdateWarning(): string | null {
+	if (resolvedUpdateWarning === undefined) return null; // not ready yet
+	const warning = resolvedUpdateWarning;
+	resolvedUpdateWarning = null; // deliver only once
+	return warning;
+}
+
 // Tool definitions imported from tools.ts
 
 
@@ -648,19 +708,11 @@ async function handleTool(
 // ============================================================================
 
 async function main() {
-	// Validate API key on startup via API
-	const auth = await validateApiKey();
-	if (!auth) {
-		console.error('Invalid API key');
-		process.exit(1);
-	}
-
-	// Check for updates (non-blocking, with timeout)
-	const updateWarning = await getUpdateWarning();
+	// Start auth validation eagerly in background (10s timeout) — don't block startup
+	startDeferredAuth();
 
-	const serverInstructions = updateWarning
-		? `${updateWarning}\n\nVibescope MCP server - AI project tracking and coordination tools.`
-		: 'Vibescope MCP server - AI project tracking and coordination tools.';
+	// Start update check in background — delivered on first tool call if available
+	startDeferredUpdateCheck();
 
 	const server = new Server(
 		{
@@ -671,7 +723,7 @@ async function main() {
 			capabilities: {
 				tools: {},
 			},
-			instructions: serverInstructions,
+			instructions: 'Vibescope MCP server - AI project tracking and coordination tools.',
 		}
 	);
 
@@ -695,6 +747,22 @@ async function main() {
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
 		const { name, arguments: args } = request.params;
 
+		// Await deferred auth on first tool call (usually already resolved)
+		let auth: AuthContext;
+		try {
+			auth = await getAuth();
+		} catch (err) {
+			return {
+				content: [
+					{
+						type: 'text',
+						text: err instanceof Error ? err.message : 'Auth validation failed',
+					},
+				],
+				isError: true,
+			};
+		}
+
 		// Check rate limit
 		const rateCheck = rateLimiter.check(auth.apiKeyId);
 		if (!rateCheck.allowed) {
@@ -728,6 +796,15 @@ async function main() {
 				},
 			];
 
+			// Deliver update warning on first tool call (if available)
+			const updateWarning = consumeUpdateWarning();
+			if (updateWarning) {
+				content.push({
+					type: 'text',
+					text: `\n--- ${updateWarning} ---`,
+				});
+			}
+
 			// Include reminder nudge if applicable
 			const reminder = getReminder(name);
 			if (reminder) {

package/src/setup.test.ts

@@ -186,8 +186,11 @@ describe('Setup module', () => {
 			const mcpServers = config.mcpServers as Record<string, unknown>;
 			const vibescope = mcpServers.vibescope as Record<string, unknown>;
 
-			expect(vibescope.command).toBe('npx');
-			expect(vibescope.args).toContain('@vibescope/mcp-server@latest');
+			// Config uses shell wrapper to prefer global binary with npx fallback
+			expect(['cmd', 'bash']).toContain(vibescope.command);
+			const argsStr = JSON.stringify(vibescope.args);
+			expect(argsStr).toContain('vibescope-mcp');
+			expect(argsStr).toContain('npx');
 			expect((vibescope.env as Record<string, string>).VIBESCOPE_API_KEY).toBe('test-api-key');
 			// Standard MCP config should NOT have timeout/trust
 			expect(vibescope.timeout).toBeUndefined();
@@ -207,14 +210,16 @@ describe('Setup module', () => {
 			const mcpServers = config.mcpServers as Record<string, unknown>;
 			const vibescope = mcpServers.vibescope as Record<string, unknown>;
 
-			expect(vibescope.command).toBe('npx');
-			expect(vibescope.args).toContain('@vibescope/mcp-server@latest');
+			expect(['cmd', 'bash']).toContain(vibescope.command);
+			const argsStr = JSON.stringify(vibescope.args);
+			expect(argsStr).toContain('vibescope-mcp');
+			expect(argsStr).toContain('npx');
 			expect((vibescope.env as Record<string, string>).VIBESCOPE_API_KEY).toBe('test-api-key');
 			expect(vibescope.timeout).toBe(30000);
 			expect(vibescope.trust).toBe(true);
 		});
 
-		it('should use correct npx args format', () => {
+		it('should use shell wrapper with global binary fallback', () => {
 			const ide: IdeConfig = {
 				name: 'claude-code',
 				displayName: 'Claude Code (CLI)',
@@ -226,8 +231,13 @@ describe('Setup module', () => {
 			const config = generateMcpConfig('my-key', ide);
 			const mcpServers = config.mcpServers as Record<string, unknown>;
 			const vibescope = mcpServers.vibescope as Record<string, unknown>;
+			const args = vibescope.args as string[];
 
-			expect(vibescope.args).toEqual(['-y', '-p', '@vibescope/mcp-server@latest', 'vibescope-mcp']);
+			// Should check for global binary first, then fall back to npx
+			const shellCmd = args.join(' ');
+			expect(shellCmd).toContain('vibescope-mcp');
+			expect(shellCmd).toContain('npx');
+			expect(shellCmd).toContain('@vibescope/mcp-server@latest');
 		});
 	});
 });

package/src/setup.ts

@@ -210,13 +210,19 @@ export function writeConfig(configPath: string, config: Record<string, unknown>)
 }
 
 export function generateMcpConfig(apiKey: string, ide: IdeConfig): Record<string, unknown> {
-	const vibescopeServer = {
-		command: 'npx',
-		args: ['-y', '-p', '@vibescope/mcp-server@latest', 'vibescope-mcp'],
-		env: {
-			VIBESCOPE_API_KEY: apiKey,
-		},
-	};
+	// Prefer globally installed binary (instant start) with npx fallback
+	const isWindows = platform() === 'win32';
+	const vibescopeServer = isWindows
+		? {
+			command: 'cmd',
+			args: ['/c', 'where vibescope-mcp >nul 2>&1 && vibescope-mcp || npx -y -p @vibescope/mcp-server@latest vibescope-mcp'],
+			env: { VIBESCOPE_API_KEY: apiKey },
+		}
+		: {
+			command: 'bash',
+			args: ['-c', 'command -v vibescope-mcp >/dev/null 2>&1 && exec vibescope-mcp || exec npx -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') {

package/src/version.ts

@@ -2,15 +2,26 @@
  * Version checking utilities
  *
  * Compares the locally installed version against the latest published
- * version on npm to detect available updates.
+ * version on npm to detect available updates. Uses a file-based cache
+ * (~/.vibescope/version-cache.json) with 1-hour TTL to avoid hitting
+ * the npm registry on every startup.
  */
 
-import { readFileSync } from 'fs';
-import { resolve, dirname } from 'path';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { resolve, dirname, join } from 'path';
 import { fileURLToPath } from 'url';
+import { homedir } from 'os';
 
 const NPM_REGISTRY_URL = 'https://registry.npmjs.org/@vibescope/mcp-server';
 const PACKAGE_NAME = '@vibescope/mcp-server';
+const CACHE_DIR = join(homedir(), '.vibescope');
+const CACHE_PATH = join(CACHE_DIR, 'version-cache.json');
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+
+interface VersionCache {
+	latestVersion: string;
+	fetchedAt: number; // epoch ms
+}
 
 export interface VersionInfo {
 	current: string;
@@ -33,13 +44,50 @@ export function getLocalVersion(): string {
 	}
 }
 
+/**
+ * Read version from file-based cache if still valid
+ */
+function readVersionCache(): string | null {
+	try {
+		if (!existsSync(CACHE_PATH)) return null;
+		const raw = JSON.parse(readFileSync(CACHE_PATH, 'utf-8')) as VersionCache;
+		if (Date.now() - raw.fetchedAt < CACHE_TTL_MS) {
+			return raw.latestVersion;
+		}
+		return null; // expired
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Write version to file-based cache
+ */
+function writeVersionCache(version: string): void {
+	try {
+		if (!existsSync(CACHE_DIR)) {
+			mkdirSync(CACHE_DIR, { recursive: true });
+		}
+		const cache: VersionCache = { latestVersion: version, fetchedAt: Date.now() };
+		writeFileSync(CACHE_PATH, JSON.stringify(cache, null, 2) + '\n');
+	} catch {
+		// Non-critical — silently ignore write failures
+	}
+}
+
 /**
  * Fetch the latest published version from npm registry
  */
-export async function getLatestVersion(): Promise<string | null> {
+export async function getLatestVersion(options?: { bypassCache?: boolean }): Promise<string | null> {
+	// Check cache first (unless bypassed)
+	if (!options?.bypassCache) {
+		const cached = readVersionCache();
+		if (cached) return cached;
+	}
+
 	try {
 		const controller = new AbortController();
-		const timeout = setTimeout(() => controller.abort(), 5000);
+		const timeout = setTimeout(() => controller.abort(), 3000);
 
 		const response = await fetch(`${NPM_REGISTRY_URL}/latest`, {
 			signal: controller.signal,
@@ -51,7 +99,12 @@ export async function getLatestVersion(): Promise<string | null> {
 		if (!response.ok) return null;
 
 		const data = (await response.json()) as { version?: string };
-		return data.version ?? null;
+		const version = data.version ?? null;
+
+		// Write to cache on successful fetch
+		if (version) writeVersionCache(version);
+
+		return version;
 	} catch {
 		return null;
 	}
@@ -75,9 +128,9 @@ function isNewer(current: string, latest: string): boolean {
 /**
  * Check if an update is available
  */
-export async function checkVersion(): Promise<VersionInfo> {
+export async function checkVersion(options?: { bypassCache?: boolean }): Promise<VersionInfo> {
 	const current = getLocalVersion();
-	const latest = await getLatestVersion();
+	const latest = await getLatestVersion(options);
 
 	if (!latest) {
 		return {