@everstateai/mcp 1.3.2 → 1.3.3

package/src/setup/auto-update.ts

@@ -0,0 +1,328 @@
+/**
+ * Auto-Update System
+ *
+ * Automatically updates hooks and configuration when the MCP proxy starts.
+ * Runs silently in the background without blocking the MCP server.
+ *
+ * Also checks the Everstate server for available updates (same as the dashboard UI).
+ */
+
+import * as fs from 'fs';
+import {
+  getEverstateDir,
+  getClaudeConfigPath,
+  HOOK_VERSIONS,
+  EVERSTATE_API_URL,
+} from './types.js';
+import {
+  readVersionFile,
+  writeVersionFile,
+  createVersionFile,
+  getMcpProxyVersion,
+} from './version.js';
+import { getSyncTodosHook } from './hooks/templates.js';
+
+const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+interface ServerUpdate {
+  id: string;
+  version: string;
+  category: 'hooks' | 'mcp-proxy' | 'config';
+  title: string;
+  description: string;
+  breaking: boolean;
+}
+
+interface UpdateCheckResult {
+  needsUpdate: boolean;
+  updates: string[];
+  errors: string[];
+}
+
+/**
+ * Check and apply updates silently.
+ * Called on MCP server startup.
+ */
+export async function checkAndApplyUpdates(): Promise<UpdateCheckResult> {
+  const result: UpdateCheckResult = {
+    needsUpdate: false,
+    updates: [],
+    errors: [],
+  };
+
+  try {
+    // Read or create version file
+    let versionFile = readVersionFile();
+    const isFirstRun = !versionFile;
+
+    if (!versionFile) {
+      versionFile = createVersionFile('npx');
+    }
+
+    // Check if we should skip this update check (rate limiting)
+    const lastCheck = versionFile.lastUpdateCheck;
+    if (lastCheck) {
+      const elapsed = Date.now() - new Date(lastCheck).getTime();
+      if (elapsed < UPDATE_CHECK_INTERVAL_MS) {
+        // Skip - checked recently
+        return result;
+      }
+    }
+
+    // Update the check timestamp
+    versionFile.lastUpdateCheck = new Date().toISOString();
+
+    // Check hook versions
+    const hooksDir = `${getEverstateDir()}/hooks`;
+    const syncTodosPath = `${hooksDir}/sync-todos.js`;
+
+    // Update sync-todos.js if needed
+    if (shouldUpdateHook(syncTodosPath, HOOK_VERSIONS.syncTodos, versionFile.components.hooks.syncTodos)) {
+      try {
+        await updateSyncTodosHook(hooksDir, syncTodosPath);
+        versionFile.components.hooks.syncTodos = HOOK_VERSIONS.syncTodos;
+        result.updates.push(`sync-todos.js updated to v${HOOK_VERSIONS.syncTodos}`);
+        result.needsUpdate = true;
+      } catch (error) {
+        result.errors.push(`Failed to update sync-todos.js: ${String(error)}`);
+      }
+    }
+
+    // Update TodoWrite hook registration if needed
+    const hookRegistrationUpdated = await ensureHookRegistration(syncTodosPath);
+    if (hookRegistrationUpdated) {
+      result.updates.push('TodoWrite hook registration updated');
+      result.needsUpdate = true;
+    }
+
+    // Update MCP proxy version in version file
+    const currentVersion = getMcpProxyVersion();
+    if (versionFile.components.mcpProxy !== currentVersion) {
+      versionFile.components.mcpProxy = currentVersion;
+      result.updates.push(`MCP proxy version recorded: ${currentVersion}`);
+    }
+
+    // Write updated version file
+    writeVersionFile(versionFile);
+
+    // Check for server-side updates (same as dashboard UI)
+    const apiKey = loadApiKey();
+    if (apiKey) {
+      try {
+        const serverUpdates = await checkServerUpdates(apiKey, versionFile.components);
+        if (serverUpdates.length > 0) {
+          console.error(`[Everstate] ${serverUpdates.length} update(s) available:`);
+          for (const update of serverUpdates) {
+            console.error(`  - ${update.title} (${update.category} v${update.version})`);
+          }
+          console.error(`  Run 'npx @everstateai/mcp doctor' to see details`);
+        }
+      } catch {
+        // Silently ignore server check failures
+      }
+    }
+
+    // Log updates to stderr (MCP servers use stderr for logging)
+    if (result.updates.length > 0) {
+      console.error(`[Everstate] Auto-updated: ${result.updates.join(', ')}`);
+    }
+
+    if (result.errors.length > 0) {
+      console.error(`[Everstate] Update errors: ${result.errors.join(', ')}`);
+    }
+
+  } catch (error) {
+    result.errors.push(`Auto-update check failed: ${String(error)}`);
+  }
+
+  return result;
+}
+
+/**
+ * Load API key from file
+ */
+function loadApiKey(): string | null {
+  const keyPath = `${getEverstateDir()}/api-key`;
+  try {
+    if (fs.existsSync(keyPath)) {
+      return fs.readFileSync(keyPath, 'utf8').trim();
+    }
+  } catch {}
+  return null;
+}
+
+/**
+ * Check for updates from the Everstate server
+ */
+async function checkServerUpdates(
+  apiKey: string,
+  installedComponents: { mcpProxy: string; hooks: { syncTodos: string } }
+): Promise<ServerUpdate[]> {
+  const response = await fetch(`${EVERSTATE_API_URL}/api/updates/check`, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      installedVersions: {
+        mcpProxy: installedComponents.mcpProxy,
+        syncTodos: installedComponents.hooks.syncTodos,
+      },
+    }),
+  });
+
+  if (!response.ok) {
+    return [];
+  }
+
+  const data = await response.json() as { updates?: ServerUpdate[] };
+  return data.updates || [];
+}
+
+/**
+ * Determine if a hook needs updating
+ */
+function shouldUpdateHook(
+  hookPath: string,
+  expectedVersion: string,
+  installedVersion: string
+): boolean {
+  // If file doesn't exist, needs update
+  if (!fs.existsSync(hookPath)) {
+    return true;
+  }
+
+  // Compare versions
+  if (compareVersions(installedVersion, expectedVersion) < 0) {
+    return true;
+  }
+
+  // Also check the file's embedded version
+  const fileVersion = extractHookVersion(hookPath);
+  if (!fileVersion || compareVersions(fileVersion, expectedVersion) < 0) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Extract version from hook file
+ */
+function extractHookVersion(filePath: string): string | null {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const versionMatch = content.match(/VERSION:\s*(\d+\.\d+\.\d+)/i);
+    if (versionMatch) {
+      return versionMatch[1];
+    }
+    // Legacy format
+    const hookVMatch = content.match(/Hook\s+v(\d+)/i);
+    if (hookVMatch) {
+      return `${hookVMatch[1]}.0.0`;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compare semver versions
+ */
+function compareVersions(a: string, b: string): number {
+  const aParts = a.split('.').map(Number);
+  const bParts = b.split('.').map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    const aNum = aParts[i] || 0;
+    const bNum = bParts[i] || 0;
+    if (aNum < bNum) return -1;
+    if (aNum > bNum) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Update the sync-todos hook
+ */
+async function updateSyncTodosHook(hooksDir: string, hookPath: string): Promise<void> {
+  // Ensure directory exists
+  if (!fs.existsSync(hooksDir)) {
+    fs.mkdirSync(hooksDir, { recursive: true });
+  }
+
+  // Get the new hook content
+  const hookContent = getSyncTodosHook();
+
+  // Backup existing hook if present
+  if (fs.existsSync(hookPath)) {
+    const backupPath = `${hookPath}.backup.${Date.now()}`;
+    fs.copyFileSync(hookPath, backupPath);
+  }
+
+  // Write new hook
+  fs.writeFileSync(hookPath, hookContent, { mode: 0o755 });
+}
+
+/**
+ * Ensure TodoWrite hook is registered in ~/.claude.json
+ */
+async function ensureHookRegistration(syncTodosPath: string): Promise<boolean> {
+  const configPath = getClaudeConfigPath();
+
+  if (!fs.existsSync(configPath)) {
+    return false;
+  }
+
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+
+    if (!config.hooks) {
+      config.hooks = {};
+    }
+    if (!config.hooks.PostToolUse) {
+      config.hooks.PostToolUse = [];
+    }
+
+    const postToolUse = config.hooks.PostToolUse as Array<{
+      matcher: string;
+      hooks: Array<{ type?: string; command?: string; timeout?: number }>;
+    }>;
+
+    // Find or create TodoWrite entry
+    let todoWriteEntry = postToolUse.find((e) => e.matcher === 'TodoWrite');
+    if (!todoWriteEntry) {
+      todoWriteEntry = { matcher: 'TodoWrite', hooks: [] };
+      postToolUse.push(todoWriteEntry);
+    }
+
+    // Check if sync-todos hook is registered with correct path
+    const expectedCommand = `node ${syncTodosPath}`;
+    const existingHook = todoWriteEntry.hooks.find((h) =>
+      h.command?.includes('sync-todos')
+    );
+
+    if (!existingHook) {
+      // Add new hook
+      todoWriteEntry.hooks.push({
+        type: 'command',
+        command: expectedCommand,
+        timeout: 10,
+      });
+      fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+      return true;
+    } else if (existingHook.command !== expectedCommand) {
+      // Update existing hook with correct path
+      existingHook.command = expectedCommand;
+      fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+      return true;
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+}
+

package/src/setup/commands/doctor.ts

@@ -0,0 +1,266 @@
+/**
+ * Doctor Command
+ *
+ * Diagnoses Everstate installation issues.
+ *
+ * Usage:
+ *   npx @everstateai/mcp doctor
+ *   npx @everstateai/mcp doctor --json
+ *   npx @everstateai/mcp doctor --verbose
+ *   npx @everstateai/mcp doctor --component hooks
+ */
+
+import * as fs from 'fs';
+import {
+  ValidationContext,
+  ValidationSummary,
+  ValidationResult,
+  DoctorOptions,
+  c,
+  getEverstateDir,
+} from '../types.js';
+import { validateAll, validateComponent } from '../validators/index.js';
+import { checkForUpdates, checkServerUpdates, ServerUpdate } from '../version.js';
+
+export async function doctor(options: DoctorOptions = {}): Promise<void> {
+  const context = buildContext(options);
+
+  // Run validation
+  let summary: ValidationSummary;
+
+  if (options.component) {
+    summary = await validateComponent(options.component, context);
+  } else {
+    summary = await validateAll(context);
+  }
+
+  // Check for server updates (same as dashboard UI)
+  let serverUpdates: ServerUpdate[] = [];
+  if (context.apiKey) {
+    serverUpdates = await checkServerUpdates(context.apiKey);
+  }
+
+  // Output results
+  if (options.json) {
+    outputJson(summary, serverUpdates);
+  } else {
+    outputPretty(summary, options.verbose, serverUpdates);
+  }
+
+  // Exit code based on results
+  if (summary.failed > 0) {
+    process.exit(1);
+  }
+}
+
+function buildContext(options: DoctorOptions): ValidationContext {
+  const context: ValidationContext = {
+    projectDir: options.projectDir || process.cwd(),
+    verbose: options.verbose,
+  };
+
+  // Try to load API key for authenticated checks
+  const apiKeyPath = `${getEverstateDir()}/api-key`;
+  if (fs.existsSync(apiKeyPath)) {
+    try {
+      context.apiKey = fs.readFileSync(apiKeyPath, 'utf8').trim();
+    } catch {
+      // API key not readable - will be reported by validator
+    }
+  }
+
+  return context;
+}
+
+function outputJson(summary: ValidationSummary, serverUpdates: ServerUpdate[]): void {
+  console.log(JSON.stringify({ ...summary, serverUpdates }, null, 2));
+}
+
+function outputPretty(summary: ValidationSummary, verbose?: boolean, serverUpdates: ServerUpdate[] = []): void {
+  // Header
+  console.log('');
+  console.log(c('bold', '╔═══════════════════════════════════════════════════════════╗'));
+  console.log(c('bold', '║              Everstate Health Check                        ║'));
+  console.log(c('bold', '╚═══════════════════════════════════════════════════════════╝'));
+  console.log('');
+
+  // Group results by component
+  const grouped = new Map<string, ValidationResult[]>();
+  for (const result of summary.results) {
+    if (!grouped.has(result.component)) {
+      grouped.set(result.component, []);
+    }
+    grouped.get(result.component)!.push(result);
+  }
+
+  // Output each component
+  for (const [component, results] of grouped) {
+    console.log(c('bold', component));
+
+    for (const result of results) {
+      const icon = getStatusIcon(result.status);
+      const color = getStatusColor(result.status);
+      const message = result.message;
+
+      console.log(`  ${icon} ${c(color, result.check)}: ${message}`);
+
+      // Show details in verbose mode
+      if (verbose && result.details) {
+        for (const [key, value] of Object.entries(result.details)) {
+          console.log(c('dim', `      ${key}: ${JSON.stringify(value)}`));
+        }
+      }
+
+      // Show repair action hint for failures
+      if (result.status === 'fail' && result.repairAction) {
+        console.log(c('dim', `      → ${result.repairAction.description}`));
+      }
+    }
+
+    console.log('');
+  }
+
+  // Check for available updates (local version checks)
+  const localUpdates = checkForUpdates();
+
+  // Show both local and server updates
+  const hasLocalUpdates = localUpdates.needsUpdate;
+  const hasServerUpdates = serverUpdates.length > 0;
+
+  if (hasLocalUpdates || hasServerUpdates) {
+    console.log(c('yellow', 'Available Updates:'));
+
+    // Local version file updates
+    if (hasLocalUpdates) {
+      for (const outdated of localUpdates.outdated) {
+        console.log(c('yellow', `  ↑ ${outdated}`));
+      }
+    }
+
+    // Server-announced updates (same as dashboard UI)
+    if (hasServerUpdates) {
+      for (const update of serverUpdates) {
+        const breakingFlag = update.breaking ? c('red', ' [BREAKING]') : '';
+        console.log(c('cyan', `  ★ ${update.title}`) + ` (${update.category} v${update.version})${breakingFlag}`);
+        if (verbose) {
+          console.log(c('dim', `      ${update.description}`));
+        }
+      }
+    }
+
+    console.log('');
+  }
+
+  // Summary line
+  const parts: string[] = [];
+
+  if (summary.passed > 0) {
+    parts.push(c('green', `${summary.passed} passed`));
+  }
+  if (summary.warnings > 0) {
+    parts.push(c('yellow', `${summary.warnings} warnings`));
+  }
+  if (summary.failed > 0) {
+    parts.push(c('red', `${summary.failed} failed`));
+  }
+
+  console.log(`Status: ${parts.join(', ')}`);
+
+  // Action hint
+  if (summary.failed > 0) {
+    console.log('');
+    console.log(c('cyan', 'Run `npx @everstateai/mcp repair` to fix issues'));
+  } else if (summary.warnings > 0) {
+    console.log('');
+    console.log(c('dim', 'Run `npx @everstateai/mcp repair --include-warnings` to address warnings'));
+  }
+
+  console.log('');
+}
+
+function getStatusIcon(status: string): string {
+  switch (status) {
+    case 'pass':
+      return c('green', '✓');
+    case 'warn':
+      return c('yellow', '⚠');
+    case 'fail':
+      return c('red', '✗');
+    default:
+      return '?';
+  }
+}
+
+function getStatusColor(status: string): keyof typeof import('../types').COLORS {
+  switch (status) {
+    case 'pass':
+      return 'green';
+    case 'warn':
+      return 'yellow';
+    case 'fail':
+      return 'red';
+    default:
+      return 'reset';
+  }
+}
+
+// CLI entry point
+export async function doctorCli(args: string[]): Promise<void> {
+  const options: DoctorOptions = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    switch (arg) {
+      case '--json':
+        options.json = true;
+        break;
+      case '--verbose':
+      case '-v':
+        options.verbose = true;
+        break;
+      case '--component':
+      case '-c':
+        options.component = args[++i];
+        break;
+      case '--project':
+      case '-p':
+        options.projectDir = args[++i];
+        break;
+      case '--help':
+      case '-h':
+        printHelp();
+        process.exit(0);
+    }
+  }
+
+  await doctor(options);
+}
+
+function printHelp(): void {
+  console.log(`
+Everstate Doctor - Diagnose installation issues
+
+Usage:
+  npx @everstateai/mcp doctor [options]
+
+Options:
+  --json              Output results as JSON
+  --verbose, -v       Show additional details
+  --component, -c     Check only a specific component
+  --project, -p       Specify project directory
+  --help, -h          Show this help
+
+Components:
+  API Key             API key file and format
+  MCP Configuration   Claude Code and Desktop config
+  Hooks               Hook files and registration
+  Project             Project-level .everstate.json
+  Connectivity        API server connectivity
+
+Examples:
+  npx @everstateai/mcp doctor
+  npx @everstateai/mcp doctor --json
+  npx @everstateai/mcp doctor --component hooks --verbose
+`);
+}