@vibescope/mcp-server 0.3.3 → 0.3.5

package/dist/cli-init.js

@@ -173,24 +173,27 @@ function detectAgents() {
 // 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
+    // Write project-level .mcp.json (works reliably across all platforms)
     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)`);
+    // Also offer to write user-level config for global access
+    const globalConfig = platform() === 'win32'
+        ? join(homedir(), '.claude', 'settings.json')
+        : join(homedir(), '.claude', 'settings.json');
+    const addGlobal = await promptConfirm(`  Also add Vibescope globally (all projects)?`, true);
+    if (addGlobal) {
+        const existing = readJsonFile(globalConfig);
+        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(globalConfig, existing);
+        console.log(`  ${icon.check} Wrote ${c.cyan}~/.claude/settings.json${c.reset} (global config)`);
+    }
 }
 async function configureCursor(apiKey) {
     const configPath = join(process.cwd(), '.cursor', 'mcp.json');

package/dist/handlers/index.d.ts

@@ -28,6 +28,7 @@ export * from './file-checkouts.js';
 export * from './roles.js';
 export * from './connectors.js';
 export * from './cloud-agents.js';
+export * from './version.js';
 import type { HandlerRegistry } from './types.js';
 /**
  * Build the complete handler registry from all modules

package/dist/handlers/index.js

@@ -28,6 +28,7 @@ export * from './file-checkouts.js';
 export * from './roles.js';
 export * from './connectors.js';
 export * from './cloud-agents.js';
+export * from './version.js';
 import { milestoneHandlers } from './milestones.js';
 import { sessionHandlers } from './session.js';
 import { ideaHandlers } from './ideas.js';
@@ -51,6 +52,7 @@ import { fileCheckoutHandlers } from './file-checkouts.js';
 import { roleHandlers } from './roles.js';
 import { connectorHandlers } from './connectors.js';
 import { cloudAgentHandlers } from './cloud-agents.js';
+import { versionHandlers } from './version.js';
 /**
  * Build the complete handler registry from all modules
  */
@@ -79,5 +81,6 @@ export function buildHandlerRegistry() {
         ...roleHandlers,
         ...connectorHandlers,
         ...cloudAgentHandlers,
+        ...versionHandlers,
     };
 }

package/dist/handlers/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Version management handlers
+ */
+import type { HandlerRegistry } from './types.js';
+export declare const versionHandlers: HandlerRegistry;

package/dist/handlers/version.js

@@ -0,0 +1,53 @@
+/**
+ * Version management handlers
+ */
+import { execSync } from 'child_process';
+import { success, error } from './types.js';
+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();
+        if (info.error) {
+            return success({
+                current_version: info.current,
+                latest_version: info.latest,
+                update_available: false,
+                warning: info.error,
+            });
+        }
+        return success({
+            current_version: info.current,
+            latest_version: info.latest,
+            update_available: info.updateAvailable,
+            message: info.updateAvailable
+                ? `Update available! v${info.current} → v${info.latest}. Ask the user if they would like to update using the update_mcp_server tool.`
+                : `Vibescope MCP server is up to date (v${info.current}).`,
+        });
+    },
+    update_mcp_server: async (args, _ctx) => {
+        const useGlobal = args.global !== false; // default true
+        const flag = useGlobal ? '-g ' : '';
+        const command = `npm install ${flag}${PACKAGE_NAME}@latest`;
+        try {
+            const output = execSync(command, {
+                encoding: 'utf-8',
+                timeout: 60000,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            // Check the new version
+            const newVersion = getLocalVersion();
+            return success({
+                updated: true,
+                command_run: command,
+                output: output.trim(),
+                new_version: newVersion,
+                message: 'Update complete. The MCP server must be restarted to use the new version. Please ask the user to restart their editor/MCP client, or reconnect the MCP server.',
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return error(`Failed to update: ${message}. The user may need to run manually: ${command}`);
+        }
+    },
+};

package/dist/index.js

@@ -9,6 +9,7 @@ import { RateLimiter, getErrorMessage, } from './utils.js';
 import { buildHandlerRegistry } from './handlers/index.js';
 import { tools } from './tools/index.js';
 import { createTokenUsage, trackTokenUsage as trackTokens, } from './token-tracking.js';
+import { getUpdateWarning } from './version.js';
 // ============================================================================
 // Agent Instance Tracking
 // ============================================================================
@@ -210,6 +211,11 @@ async function main() {
         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.';
     const server = new Server({
         name: 'vibescope',
         version: '0.1.0',
@@ -217,6 +223,7 @@ async function main() {
         capabilities: {
             tools: {},
         },
+        instructions: serverInstructions,
     });
     // List available tools
     server.setRequestHandler(ListToolsRequestSchema, async () => {

package/dist/tools/index.d.ts

@@ -30,6 +30,7 @@ import { sprintTools } from './sprints.js';
 import { gitIssueTools } from './git-issues.js';
 import { connectorTools } from './connectors.js';
 import { cloudAgentTools } from './cloud-agents.js';
+import { versionTools } from './version.js';
 /**
  * All MCP tool definitions combined
  */
@@ -67,5 +68,6 @@ export declare const toolCategories: {
     readonly gitIssues: string[];
     readonly connectors: string[];
     readonly cloudAgents: string[];
+    readonly version: string[];
 };
-export { sessionTools, costTools, discoveryTools, worktreeTools, projectTools, taskTools, progressTools, blockerTools, decisionTools, ideaTools, findingTools, validationTools, deploymentTools, fallbackTools, requestTools, milestoneTools, bodiesOfWorkTools, organizationTools, fileCheckoutTools, roleTools, sprintTools, gitIssueTools, connectorTools, cloudAgentTools, };
+export { sessionTools, costTools, discoveryTools, worktreeTools, projectTools, taskTools, progressTools, blockerTools, decisionTools, ideaTools, findingTools, validationTools, deploymentTools, fallbackTools, requestTools, milestoneTools, bodiesOfWorkTools, organizationTools, fileCheckoutTools, roleTools, sprintTools, gitIssueTools, connectorTools, cloudAgentTools, versionTools, };

package/dist/tools/index.js

@@ -29,6 +29,7 @@ import { sprintTools } from './sprints.js';
 import { gitIssueTools } from './git-issues.js';
 import { connectorTools } from './connectors.js';
 import { cloudAgentTools } from './cloud-agents.js';
+import { versionTools } from './version.js';
 /**
  * All MCP tool definitions combined
  */
@@ -57,6 +58,7 @@ export const tools = [
     ...gitIssueTools,
     ...connectorTools,
     ...cloudAgentTools,
+    ...versionTools,
 ];
 /**
  * Build the complete tool list from all domain modules
@@ -93,6 +95,7 @@ export const toolCategories = {
     gitIssues: gitIssueTools.map((t) => t.name),
     connectors: connectorTools.map((t) => t.name),
     cloudAgents: cloudAgentTools.map((t) => t.name),
+    version: versionTools.map((t) => t.name),
 };
 // Re-export domain tools for selective imports
-export { sessionTools, costTools, discoveryTools, worktreeTools, projectTools, taskTools, progressTools, blockerTools, decisionTools, ideaTools, findingTools, validationTools, deploymentTools, fallbackTools, requestTools, milestoneTools, bodiesOfWorkTools, organizationTools, fileCheckoutTools, roleTools, sprintTools, gitIssueTools, connectorTools, cloudAgentTools, };
+export { sessionTools, costTools, discoveryTools, worktreeTools, projectTools, taskTools, progressTools, blockerTools, decisionTools, ideaTools, findingTools, validationTools, deploymentTools, fallbackTools, requestTools, milestoneTools, bodiesOfWorkTools, organizationTools, fileCheckoutTools, roleTools, sprintTools, gitIssueTools, connectorTools, cloudAgentTools, versionTools, };

package/dist/tools/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Version management tool definitions
+ */
+import type { Tool } from './types.js';
+export declare const versionTools: Tool[];

package/dist/tools/version.js

@@ -0,0 +1,28 @@
+/**
+ * Version management tool definitions
+ */
+export const versionTools = [
+    {
+        name: 'check_mcp_version',
+        description: 'Check if the Vibescope MCP server is up to date. Compares the locally installed version against the latest published version on npm. Call this when starting a session or when the server instructions indicate an update is available.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'update_mcp_server',
+        description: 'Update the Vibescope MCP server to the latest version. Runs npm install to fetch the latest version. After updating, the server must be restarted (the agent should ask the user to restart their MCP client/editor). Only call this when the user agrees to update.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                global: {
+                    type: 'boolean',
+                    description: 'If true, update the global installation (npm install -g). If false, update locally. Default: true.',
+                },
+            },
+            required: [],
+        },
+    },
+];

package/dist/version.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Version checking utilities
+ *
+ * Compares the locally installed version against the latest published
+ * version on npm to detect available updates.
+ */
+export interface VersionInfo {
+    current: string;
+    latest: string | null;
+    updateAvailable: boolean;
+    error?: string;
+}
+/**
+ * Get the current locally installed version from package.json
+ */
+export declare function getLocalVersion(): string;
+/**
+ * Fetch the latest published version from npm registry
+ */
+export declare function getLatestVersion(): Promise<string | null>;
+/**
+ * Check if an update is available
+ */
+export declare function checkVersion(): Promise<VersionInfo>;
+/**
+ * Get the update warning message for server instructions, or null if up to date
+ */
+export declare function getUpdateWarning(): Promise<string | null>;

package/dist/version.js

@@ -0,0 +1,91 @@
+/**
+ * Version checking utilities
+ *
+ * Compares the locally installed version against the latest published
+ * version on npm to detect available updates.
+ */
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+const NPM_REGISTRY_URL = 'https://registry.npmjs.org/@vibescope/mcp-server';
+const PACKAGE_NAME = '@vibescope/mcp-server';
+/**
+ * Get the current locally installed version from package.json
+ */
+export function getLocalVersion() {
+    try {
+        const __dirname = dirname(fileURLToPath(import.meta.url));
+        const pkgPath = resolve(__dirname, '..', 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        return pkg.version;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Fetch the latest published version from npm registry
+ */
+export async function getLatestVersion() {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+        const response = await fetch(`${NPM_REGISTRY_URL}/latest`, {
+            signal: controller.signal,
+            headers: { 'Accept': 'application/json' },
+        });
+        clearTimeout(timeout);
+        if (!response.ok)
+            return null;
+        const data = (await response.json());
+        return data.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compare semver strings. Returns true if latest > current.
+ */
+function isNewer(current, latest) {
+    const parse = (v) => v.split('.').map(Number);
+    const c = parse(current);
+    const l = parse(latest);
+    for (let i = 0; i < 3; i++) {
+        if ((l[i] ?? 0) > (c[i] ?? 0))
+            return true;
+        if ((l[i] ?? 0) < (c[i] ?? 0))
+            return false;
+    }
+    return false;
+}
+/**
+ * Check if an update is available
+ */
+export async function checkVersion() {
+    const current = getLocalVersion();
+    const latest = await getLatestVersion();
+    if (!latest) {
+        return {
+            current,
+            latest: null,
+            updateAvailable: false,
+            error: 'Could not reach npm registry to check for updates',
+        };
+    }
+    return {
+        current,
+        latest,
+        updateAvailable: isNewer(current, latest),
+    };
+}
+/**
+ * Get the update warning message for server instructions, or null if up to date
+ */
+export async function getUpdateWarning() {
+    const info = await checkVersion();
+    if (info.updateAvailable && info.latest) {
+        return `⚠️ UPDATE AVAILABLE: Vibescope MCP server v${info.current} is outdated. Latest version is v${info.latest}. Before starting work, inform the user that an update is available and recommend running the \`check_mcp_version\` tool, or ask them to update with: npm install -g ${PACKAGE_NAME}@latest (or npx @vibescope/mcp-server@latest for auto-update on next run).`;
+    }
+    return null;
+}

package/docs/TOOLS.md

@@ -2,9 +2,9 @@
 
 > Auto-generated from tool definitions. Do not edit manually.
 >
-> Generated: 2026-02-06
+> Generated: 2026-02-12
 >
-> Total tools: 154
+> Total tools: 156
 
 ## Table of Contents
 
@@ -2457,3 +2457,27 @@ Use this to check the state of cloud agents before/after cleanup.
 | `status` | `"starting" | "running" | "stopped" | "failed" | "all"` | No | Filter by status (default: all) |
 
 ---
+
+## Uncategorized
+
+*Tools not yet assigned to a category*
+
+### check_mcp_version
+
+Check if the Vibescope MCP server is up to date. Compares the locally installed version against the latest published version on npm. Call this when starting a session or when the server instructions indicate an update is available.
+
+**Parameters:** None
+
+---
+
+### update_mcp_server
+
+Update the Vibescope MCP server to the latest version. Runs npm install to fetch the latest version. After updating, the server must be restarted (the agent should ask the user to restart their MCP client/editor). Only call this when the user agrees to update.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `global` | `boolean` | No | If true, update the global installation (npm install -g). If false, update locally. Default: true. |
+
+---

package/package.json

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

package/src/cli-init.ts

@@ -204,26 +204,29 @@ function detectAgents(): Agent[] {
 // ============================================================================
 
 async function configureClaudeCode(apiKey: string): Promise<void> {
-	// 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
+	// Write project-level .mcp.json (works reliably across all platforms)
 	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)`);
+
+	// Also offer to write user-level config for global access
+	const globalConfig = platform() === 'win32'
+		? join(homedir(), '.claude', 'settings.json')
+		: join(homedir(), '.claude', 'settings.json');
+
+	const addGlobal = await promptConfirm(`  Also add Vibescope globally (all projects)?`, true);
+	if (addGlobal) {
+		const existing = readJsonFile(globalConfig);
+		const mcpServers = (existing.mcpServers as Record<string, unknown>) || {};
+		mcpServers['vibescope'] = {
+			command: 'npx',
+			args: ['-y', '-p', '@vibescope/mcp-server@latest', 'vibescope-mcp'],
+			env: { VIBESCOPE_API_KEY: apiKey },
+		};
+		existing.mcpServers = mcpServers;
+		writeJsonFile(globalConfig, existing);
+		console.log(`  ${icon.check} Wrote ${c.cyan}~/.claude/settings.json${c.reset} (global config)`);
+	}
 }
 
 async function configureCursor(apiKey: string): Promise<void> {

package/src/handlers/index.ts

@@ -29,6 +29,7 @@ export * from './file-checkouts.js';
 export * from './roles.js';
 export * from './connectors.js';
 export * from './cloud-agents.js';
+export * from './version.js';
 
 import type { HandlerRegistry } from './types.js';
 import { milestoneHandlers } from './milestones.js';
@@ -54,6 +55,7 @@ import { fileCheckoutHandlers } from './file-checkouts.js';
 import { roleHandlers } from './roles.js';
 import { connectorHandlers } from './connectors.js';
 import { cloudAgentHandlers } from './cloud-agents.js';
+import { versionHandlers } from './version.js';
 
 /**
  * Build the complete handler registry from all modules
@@ -83,5 +85,6 @@ export function buildHandlerRegistry(): HandlerRegistry {
 		...roleHandlers,
 		...connectorHandlers,
 		...cloudAgentHandlers,
+		...versionHandlers,
 	};
 }

package/src/handlers/version.ts

@@ -0,0 +1,63 @@
+/**
+ * Version management handlers
+ */
+
+import { execSync } from 'child_process';
+import type { HandlerRegistry } from './types.js';
+import { success, error } from './types.js';
+import { checkVersion, getLocalVersion } from '../version.js';
+
+const PACKAGE_NAME = '@vibescope/mcp-server';
+
+export const versionHandlers: HandlerRegistry = {
+	check_mcp_version: async (_args, _ctx) => {
+		const info = await checkVersion();
+
+		if (info.error) {
+			return success({
+				current_version: info.current,
+				latest_version: info.latest,
+				update_available: false,
+				warning: info.error,
+			});
+		}
+
+		return success({
+			current_version: info.current,
+			latest_version: info.latest,
+			update_available: info.updateAvailable,
+			message: info.updateAvailable
+				? `Update available! v${info.current} → v${info.latest}. Ask the user if they would like to update using the update_mcp_server tool.`
+				: `Vibescope MCP server is up to date (v${info.current}).`,
+		});
+	},
+
+	update_mcp_server: async (args, _ctx) => {
+		const useGlobal = args.global !== false; // default true
+		const flag = useGlobal ? '-g ' : '';
+		const command = `npm install ${flag}${PACKAGE_NAME}@latest`;
+
+		try {
+			const output = execSync(command, {
+				encoding: 'utf-8',
+				timeout: 60000,
+				stdio: ['pipe', 'pipe', 'pipe'],
+			});
+
+			// Check the new version
+			const newVersion = getLocalVersion();
+
+			return success({
+				updated: true,
+				command_run: command,
+				output: output.trim(),
+				new_version: newVersion,
+				message:
+					'Update complete. The MCP server must be restarted to use the new version. Please ask the user to restart their editor/MCP client, or reconnect the MCP server.',
+			});
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			return error(`Failed to update: ${message}. The user may need to run manually: ${command}`);
+		}
+	},
+};

package/src/index.ts

@@ -43,6 +43,7 @@ import {
 	setCurrentModel,
 	type TokenUsage,
 } from './token-tracking.js';
+import { getUpdateWarning } from './version.js';
 
 // ============================================================================
 // Agent Instance Tracking
@@ -654,6 +655,13 @@ async function main() {
 		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.';
+
 	const server = new Server(
 		{
 			name: 'vibescope',
@@ -663,6 +671,7 @@ async function main() {
 			capabilities: {
 				tools: {},
 			},
+			instructions: serverInstructions,
 		}
 	);
 

package/src/tools/index.ts

@@ -33,6 +33,7 @@ import { sprintTools } from './sprints.js';
 import { gitIssueTools } from './git-issues.js';
 import { connectorTools } from './connectors.js';
 import { cloudAgentTools } from './cloud-agents.js';
+import { versionTools } from './version.js';
 
 /**
  * All MCP tool definitions combined
@@ -62,6 +63,7 @@ export const tools: Tool[] = [
 	...gitIssueTools,
 	...connectorTools,
 	...cloudAgentTools,
+	...versionTools,
 ];
 
 /**
@@ -100,6 +102,7 @@ export const toolCategories = {
 	gitIssues: gitIssueTools.map((t) => t.name),
 	connectors: connectorTools.map((t) => t.name),
 	cloudAgents: cloudAgentTools.map((t) => t.name),
+	version: versionTools.map((t) => t.name),
 } as const;
 
 // Re-export domain tools for selective imports
@@ -128,4 +131,5 @@ export {
 	gitIssueTools,
 	connectorTools,
 	cloudAgentTools,
+	versionTools,
 };

package/src/tools/version.ts

@@ -0,0 +1,34 @@
+/**
+ * Version management tool definitions
+ */
+
+import type { Tool } from './types.js';
+
+export const versionTools: Tool[] = [
+	{
+		name: 'check_mcp_version',
+		description:
+			'Check if the Vibescope MCP server is up to date. Compares the locally installed version against the latest published version on npm. Call this when starting a session or when the server instructions indicate an update is available.',
+		inputSchema: {
+			type: 'object' as const,
+			properties: {},
+			required: [],
+		},
+	},
+	{
+		name: 'update_mcp_server',
+		description:
+			'Update the Vibescope MCP server to the latest version. Runs npm install to fetch the latest version. After updating, the server must be restarted (the agent should ask the user to restart their MCP client/editor). Only call this when the user agrees to update.',
+		inputSchema: {
+			type: 'object' as const,
+			properties: {
+				global: {
+					type: 'boolean',
+					description:
+						'If true, update the global installation (npm install -g). If false, update locally. Default: true.',
+				},
+			},
+			required: [],
+		},
+	},
+];

package/src/version.ts

@@ -0,0 +1,109 @@
+/**
+ * Version checking utilities
+ *
+ * Compares the locally installed version against the latest published
+ * version on npm to detect available updates.
+ */
+
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const NPM_REGISTRY_URL = 'https://registry.npmjs.org/@vibescope/mcp-server';
+const PACKAGE_NAME = '@vibescope/mcp-server';
+
+export interface VersionInfo {
+	current: string;
+	latest: string | null;
+	updateAvailable: boolean;
+	error?: string;
+}
+
+/**
+ * Get the current locally installed version from package.json
+ */
+export function getLocalVersion(): string {
+	try {
+		const __dirname = dirname(fileURLToPath(import.meta.url));
+		const pkgPath = resolve(__dirname, '..', 'package.json');
+		const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+		return pkg.version;
+	} catch {
+		return 'unknown';
+	}
+}
+
+/**
+ * Fetch the latest published version from npm registry
+ */
+export async function getLatestVersion(): Promise<string | null> {
+	try {
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), 5000);
+
+		const response = await fetch(`${NPM_REGISTRY_URL}/latest`, {
+			signal: controller.signal,
+			headers: { 'Accept': 'application/json' },
+		});
+
+		clearTimeout(timeout);
+
+		if (!response.ok) return null;
+
+		const data = (await response.json()) as { version?: string };
+		return data.version ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Compare semver strings. Returns true if latest > current.
+ */
+function isNewer(current: string, latest: string): boolean {
+	const parse = (v: string) => v.split('.').map(Number);
+	const c = parse(current);
+	const l = parse(latest);
+
+	for (let i = 0; i < 3; i++) {
+		if ((l[i] ?? 0) > (c[i] ?? 0)) return true;
+		if ((l[i] ?? 0) < (c[i] ?? 0)) return false;
+	}
+	return false;
+}
+
+/**
+ * Check if an update is available
+ */
+export async function checkVersion(): Promise<VersionInfo> {
+	const current = getLocalVersion();
+	const latest = await getLatestVersion();
+
+	if (!latest) {
+		return {
+			current,
+			latest: null,
+			updateAvailable: false,
+			error: 'Could not reach npm registry to check for updates',
+		};
+	}
+
+	return {
+		current,
+		latest,
+		updateAvailable: isNewer(current, latest),
+	};
+}
+
+/**
+ * Get the update warning message for server instructions, or null if up to date
+ */
+export async function getUpdateWarning(): Promise<string | null> {
+	const info = await checkVersion();
+
+	if (info.updateAvailable && info.latest) {
+		return `⚠️ UPDATE AVAILABLE: Vibescope MCP server v${info.current} is outdated. Latest version is v${info.latest}. Before starting work, inform the user that an update is available and recommend running the \`check_mcp_version\` tool, or ask them to update with: npm install -g ${PACKAGE_NAME}@latest (or npx @vibescope/mcp-server@latest for auto-update on next run).`;
+	}
+
+	return null;
+}