cursor-guard 2.1.0 → 4.0.0

package/references/mcp/mcp.test.js

@@ -0,0 +1,374 @@
+'use strict';
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const { execFileSync } = require('child_process');
+
+let passed = 0;
+let failed = 0;
+let serverProcess = null;
+let msgId = 0;
+
+function log(color, sym, msg) {
+  const c = { green: 32, red: 31 }[color] || 0;
+  console.log(`  \x1b[${c}m${sym}\x1b[0m ${msg}`);
+}
+
+function createTempGitRepo() {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-mcp-test-'));
+  execFileSync('git', ['init'], { cwd: tmpDir, stdio: 'pipe' });
+  execFileSync('git', ['config', 'user.email', 'test@test.com'], { cwd: tmpDir, stdio: 'pipe' });
+  execFileSync('git', ['config', 'user.name', 'Test'], { cwd: tmpDir, stdio: 'pipe' });
+  fs.writeFileSync(path.join(tmpDir, 'hello.txt'), 'hello world');
+  fs.mkdirSync(path.join(tmpDir, 'src'));
+  fs.writeFileSync(path.join(tmpDir, 'src', 'app.js'), 'console.log("app");');
+  execFileSync('git', ['add', '-A'], { cwd: tmpDir, stdio: 'pipe' });
+  execFileSync('git', ['commit', '-m', 'initial', '--no-verify'], { cwd: tmpDir, stdio: 'pipe' });
+  return tmpDir;
+}
+
+function startServer() {
+  const serverPath = path.join(__dirname, 'server.js');
+  serverProcess = spawn('node', [serverPath], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  serverProcess.stderr.on('data', () => {});
+}
+
+function sendMessage(msg) {
+  serverProcess.stdin.write(JSON.stringify(msg) + '\n');
+}
+
+function readResponse() {
+  return new Promise((resolve, reject) => {
+    let buffer = '';
+    const timeout = setTimeout(() => {
+      serverProcess.stdout.removeListener('data', onData);
+      reject(new Error('timeout waiting for response'));
+    }, 15000);
+
+    function onData(chunk) {
+      buffer += chunk.toString();
+      const lines = buffer.split('\n');
+      for (let i = 0; i < lines.length - 1; i++) {
+        const line = lines[i].trim();
+        if (!line) continue;
+        try {
+          const parsed = JSON.parse(line);
+          if (parsed.id !== undefined || parsed.result !== undefined) {
+            clearTimeout(timeout);
+            serverProcess.stdout.removeListener('data', onData);
+            resolve(parsed);
+            return;
+          }
+        } catch { /* not valid JSON yet, continue */ }
+      }
+      buffer = lines[lines.length - 1];
+    }
+    serverProcess.stdout.on('data', onData);
+  });
+}
+
+async function rpc(method, params) {
+  const id = ++msgId;
+  sendMessage({ jsonrpc: '2.0', id, method, params });
+  return await readResponse();
+}
+
+async function test(name, fn) {
+  try {
+    await fn();
+    passed++;
+    log('green', '✓', name);
+  } catch (e) {
+    failed++;
+    log('red', '✗', name);
+    console.log(`    ${e.message}`);
+  }
+}
+
+async function run() {
+  const tmpDir = createTempGitRepo();
+
+  console.log('\nMCP Server:');
+
+  startServer();
+
+  // Initialize
+  const initResp = await rpc('initialize', {
+    protocolVersion: '2024-11-05',
+    capabilities: {},
+    clientInfo: { name: 'test-client', version: '1.0' },
+  });
+  sendMessage({ jsonrpc: '2.0', method: 'notifications/initialized' });
+
+  await test('initialize returns server info', () => {
+    if (!initResp.result) throw new Error('no result');
+    if (!initResp.result.serverInfo) throw new Error('no serverInfo');
+    if (initResp.result.serverInfo.name !== 'cursor-guard') throw new Error(`wrong name: ${initResp.result.serverInfo.name}`);
+  });
+
+  // List tools
+  const toolsResp = await rpc('tools/list', {});
+
+  await test('lists 9 tools', () => {
+    const tools = toolsResp.result.tools;
+    if (!tools) throw new Error('no tools');
+    if (tools.length !== 9) throw new Error(`expected 9 tools, got ${tools.length}`);
+    const names = tools.map(t => t.name).sort();
+    const expected = ['alert_status', 'backup_status', 'dashboard', 'doctor', 'doctor_fix', 'list_backups', 'restore_file', 'restore_project', 'snapshot_now'].sort();
+    if (JSON.stringify(names) !== JSON.stringify(expected)) {
+      throw new Error(`tool names mismatch: ${JSON.stringify(names)}`);
+    }
+  });
+
+  // Call doctor
+  const doctorResp = await rpc('tools/call', {
+    name: 'doctor',
+    arguments: { path: tmpDir },
+  });
+
+  await test('doctor returns structured checks', () => {
+    const content = doctorResp.result.content[0].text;
+    const data = JSON.parse(content);
+    if (!data.checks) throw new Error('no checks');
+    if (!data.summary) throw new Error('no summary');
+    if (typeof data.summary.pass !== 'number') throw new Error('summary.pass not a number');
+  });
+
+  // Call snapshot_now
+  const snapResp = await rpc('tools/call', {
+    name: 'snapshot_now',
+    arguments: { path: tmpDir, strategy: 'git' },
+  });
+
+  await test('snapshot_now creates git snapshot', () => {
+    const content = snapResp.result.content[0].text;
+    const data = JSON.parse(content);
+    if (!data.git) throw new Error('no git result');
+    if (data.git.status !== 'created' && data.git.status !== 'skipped') {
+      throw new Error(`unexpected status: ${data.git.status}`);
+    }
+  });
+
+  // Call list_backups
+  const listResp = await rpc('tools/call', {
+    name: 'list_backups',
+    arguments: { path: tmpDir },
+  });
+
+  await test('list_backups returns sources', () => {
+    const content = listResp.result.content[0].text;
+    const data = JSON.parse(content);
+    if (!Array.isArray(data.sources)) throw new Error('sources not an array');
+  });
+
+  // Setup for restore tests
+  const headHash = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: tmpDir, stdio: 'pipe', encoding: 'utf-8' }).trim();
+  fs.writeFileSync(path.join(tmpDir, 'hello.txt'), 'changed');
+  execFileSync('git', ['add', '-A'], { cwd: tmpDir, stdio: 'pipe' });
+  execFileSync('git', ['commit', '-m', 'change', '--no-verify'], { cwd: tmpDir, stdio: 'pipe' });
+
+  // Call restore_project (preview)
+  const previewResp = await rpc('tools/call', {
+    name: 'restore_project',
+    arguments: { path: tmpDir, source: headHash, preview: true },
+  });
+
+  await test('restore_project returns preview', () => {
+    const content = previewResp.result.content[0].text;
+    const data = JSON.parse(content);
+    if (data.status !== 'ok') throw new Error(`status: ${data.status}`);
+    if (!Array.isArray(data.files)) throw new Error('files not an array');
+  });
+
+  // Call restore_project (execute mode)
+  // Re-stage the change so we have something to restore
+  fs.writeFileSync(path.join(tmpDir, 'hello.txt'), 'changed-again');
+  execFileSync('git', ['add', '-A'], { cwd: tmpDir, stdio: 'pipe' });
+  execFileSync('git', ['commit', '-m', 'change again', '--no-verify'], { cwd: tmpDir, stdio: 'pipe' });
+
+  const execResp = await rpc('tools/call', {
+    name: 'restore_project',
+    arguments: { path: tmpDir, source: headHash, preview: false, preserve_current: true },
+  });
+
+  await test('restore_project executes restore', () => {
+    const content = execResp.result.content[0].text;
+    const data = JSON.parse(content);
+    if (data.status !== 'restored') throw new Error(`status: ${data.status}, error: ${data.error}`);
+    if (typeof data.filesRestored !== 'number') throw new Error('filesRestored missing');
+    const actual = fs.readFileSync(path.join(tmpDir, 'hello.txt'), 'utf-8');
+    if (actual !== 'hello world') throw new Error(`content mismatch: "${actual}"`);
+  });
+
+  // Call restore_file
+  fs.writeFileSync(path.join(tmpDir, 'hello.txt'), 'overwritten');
+  execFileSync('git', ['add', '-A'], { cwd: tmpDir, stdio: 'pipe' });
+  execFileSync('git', ['commit', '-m', 'overwrite', '--no-verify'], { cwd: tmpDir, stdio: 'pipe' });
+
+  const restoreResp = await rpc('tools/call', {
+    name: 'restore_file',
+    arguments: { path: tmpDir, file: 'hello.txt', source: headHash, preserve_current: false },
+  });
+
+  await test('restore_file restores successfully', () => {
+    const content = restoreResp.result.content[0].text;
+    const data = JSON.parse(content);
+    if (data.status !== 'restored') throw new Error(`status: ${data.status}, error: ${data.error}`);
+    const actual = fs.readFileSync(path.join(tmpDir, 'hello.txt'), 'utf-8');
+    if (actual !== 'hello world') throw new Error(`content mismatch: "${actual}"`);
+  });
+
+  // Call backup_status
+  const statusResp = await rpc('tools/call', {
+    name: 'backup_status',
+    arguments: { path: tmpDir },
+  });
+
+  await test('backup_status returns structured status', () => {
+    const content = statusResp.result.content[0].text;
+    const data = JSON.parse(content);
+    if (typeof data.watcher !== 'object') throw new Error('no watcher');
+    if (typeof data.config !== 'object') throw new Error('no config');
+    if (typeof data.lastBackup !== 'object') throw new Error('no lastBackup');
+    if (typeof data.refs !== 'object') throw new Error('no refs');
+    if (typeof data.disk !== 'object') throw new Error('no disk');
+  });
+
+  // Call doctor_fix (dry-run)
+  const fixDryResp = await rpc('tools/call', {
+    name: 'doctor_fix',
+    arguments: { path: tmpDir, dry_run: true },
+  });
+
+  await test('doctor_fix dry-run returns actions without fixing', () => {
+    const content = fixDryResp.result.content[0].text;
+    const data = JSON.parse(content);
+    if (!Array.isArray(data.actions)) throw new Error('actions not an array');
+    if (data.totalFixed !== 0) throw new Error(`dry-run should not fix, but fixed ${data.totalFixed}`);
+  });
+
+  // Call doctor_fix (apply)
+  const fixResp = await rpc('tools/call', {
+    name: 'doctor_fix',
+    arguments: { path: tmpDir },
+  });
+
+  await test('doctor_fix returns structured result', () => {
+    const content = fixResp.result.content[0].text;
+    const data = JSON.parse(content);
+    if (!Array.isArray(data.actions)) throw new Error('actions not an array');
+    if (typeof data.totalFixed !== 'number') throw new Error('totalFixed missing');
+  });
+
+  // Call dashboard
+  const dashResp = await rpc('tools/call', {
+    name: 'dashboard',
+    arguments: { path: tmpDir },
+  });
+
+  await test('dashboard returns comprehensive health data', () => {
+    const content = dashResp.result.content[0].text;
+    const data = JSON.parse(content);
+    if (typeof data.strategy !== 'string') throw new Error('no strategy');
+    if (typeof data.counts !== 'object') throw new Error('no counts');
+    if (typeof data.diskUsage !== 'object') throw new Error('no diskUsage');
+    if (typeof data.protectionScope !== 'object') throw new Error('no protectionScope');
+    if (typeof data.health !== 'object') throw new Error('no health');
+    if (!['healthy', 'warning', 'critical'].includes(data.health.status)) throw new Error(`invalid health: ${data.health.status}`);
+    if (typeof data.alerts !== 'object') throw new Error('no alerts');
+    if (typeof data.watcher !== 'object') throw new Error('no watcher');
+  });
+
+  // Call alert_status
+  const alertResp = await rpc('tools/call', {
+    name: 'alert_status',
+    arguments: { path: tmpDir },
+  });
+
+  await test('alert_status returns alert info', () => {
+    const content = alertResp.result.content[0].text;
+    const data = JSON.parse(content);
+    if (typeof data.active !== 'boolean') throw new Error('no active field');
+    if (data.active && !data.alert) throw new Error('active but no alert');
+    if (!data.active && !data.message) throw new Error('inactive but no message');
+  });
+
+  // ── injectAlert verification ──────────────────────────────────
+  // Write an active alert file so all tools should return _activeAlert
+  const gitDir = path.join(tmpDir, '.git');
+  const alertFile = path.join(gitDir, 'cursor-guard-alert.json');
+  const fakeAlert = {
+    type: 'high_change_velocity',
+    detectedAt: Date.now(),
+    timestamp: new Date().toISOString(),
+    fileCount: 30,
+    windowSeconds: 10,
+    threshold: 20,
+    expiresAt: new Date(Date.now() + 300000).toISOString(),
+    recommendation: 'Test alert for injection verification',
+  };
+  fs.writeFileSync(alertFile, JSON.stringify(fakeAlert, null, 2));
+
+  const toolsWithAlert = ['doctor', 'list_backups', 'backup_status', 'dashboard', 'doctor_fix', 'snapshot_now'];
+  for (const toolName of toolsWithAlert) {
+    const resp = await rpc('tools/call', {
+      name: toolName,
+      arguments: { path: tmpDir, ...(toolName === 'doctor_fix' ? { dry_run: true } : {}), ...(toolName === 'snapshot_now' ? { strategy: 'git' } : {}) },
+    });
+    await test(`${toolName} response contains _activeAlert when alert exists`, () => {
+      const content = resp.result.content[0].text;
+      const data = JSON.parse(content);
+      if (!data._activeAlert) throw new Error(`_activeAlert missing from ${toolName} response`);
+      if (data._activeAlert.type !== 'high_change_velocity') throw new Error(`wrong alert type: ${data._activeAlert.type}`);
+    });
+  }
+
+  // Verify restore_file also injects
+  fs.writeFileSync(path.join(tmpDir, 'hello.txt'), 'pre-alert-test');
+  execFileSync('git', ['add', '-A'], { cwd: tmpDir, stdio: 'pipe' });
+  execFileSync('git', ['commit', '-m', 'for alert test', '--no-verify'], { cwd: tmpDir, stdio: 'pipe' });
+  const alertHead = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: tmpDir, stdio: 'pipe', encoding: 'utf-8' }).trim();
+  fs.writeFileSync(path.join(tmpDir, 'hello.txt'), 'post-alert-test');
+  execFileSync('git', ['add', '-A'], { cwd: tmpDir, stdio: 'pipe' });
+  execFileSync('git', ['commit', '-m', 'for alert test 2', '--no-verify'], { cwd: tmpDir, stdio: 'pipe' });
+
+  const restoreAlertResp = await rpc('tools/call', {
+    name: 'restore_file',
+    arguments: { path: tmpDir, file: 'hello.txt', source: alertHead, preserve_current: false },
+  });
+  await test('restore_file response contains _activeAlert', () => {
+    const content = restoreAlertResp.result.content[0].text;
+    const data = JSON.parse(content);
+    if (!data._activeAlert) throw new Error('_activeAlert missing from restore_file');
+  });
+
+  const rpResp = await rpc('tools/call', {
+    name: 'restore_project',
+    arguments: { path: tmpDir, source: alertHead, preview: true },
+  });
+  await test('restore_project response contains _activeAlert', () => {
+    const content = rpResp.result.content[0].text;
+    const data = JSON.parse(content);
+    if (!data._activeAlert) throw new Error('_activeAlert missing from restore_project');
+  });
+
+  // Clean up alert file
+  try { fs.unlinkSync(alertFile); } catch { /* ignore */ }
+
+  // Cleanup
+  serverProcess.kill();
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+
+  console.log(`\n${passed + failed} tests: \x1b[32m${passed} passed\x1b[0m` + (failed ? `, \x1b[31m${failed} failed\x1b[0m` : ''));
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+run().catch(err => {
+  console.error('Test runner error:', err);
+  if (serverProcess) serverProcess.kill();
+  process.exit(1);
+});

package/references/mcp/server.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { z } = require('zod');
+
+const { runDiagnostics } = require('../lib/core/doctor');
+const { createGitSnapshot, createShadowCopy } = require('../lib/core/snapshot');
+const { listBackups } = require('../lib/core/backups');
+const { restoreFile, previewProjectRestore, executeProjectRestore } = require('../lib/core/restore');
+const { runFixes } = require('../lib/core/doctor-fix');
+const { getBackupStatus } = require('../lib/core/status');
+const { getDashboard } = require('../lib/core/dashboard');
+const { loadActiveAlert } = require('../lib/core/anomaly');
+
+const pkg = require('../../package.json');
+
+// ── Alert injection helper ──────────────────────────────────────
+
+function injectAlert(projectPath, result) {
+  const alert = loadActiveAlert(projectPath);
+  if (alert) {
+    result._activeAlert = {
+      type: alert.type,
+      message: alert.recommendation || `${alert.fileCount} files changed in ${alert.windowSeconds}s`,
+      timestamp: alert.timestamp,
+      expiresAt: alert.expiresAt,
+    };
+  }
+  return result;
+}
+
+// ── Server ──────────────────────────────────────────────────────
+
+const server = new McpServer({
+  name: 'cursor-guard',
+  version: pkg.version,
+});
+
+// ── Tool 1: doctor ──────────────────────────────────────────────
+
+server.tool(
+  'doctor',
+  'Run health checks on a project: environment, config, Git, backup refs, shadow copies, disk space. Read-only, safe to call anytime.',
+  {
+    path: z.string().describe('Absolute path to the project directory'),
+  },
+  async ({ path: projectPath }) => {
+    const resolved = path.resolve(projectPath);
+    const result = injectAlert(resolved, runDiagnostics(resolved));
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify(result, null, 2),
+      }],
+    };
+  }
+);
+
+// ── Tool 2: list_backups ────────────────────────────────────────
+
+server.tool(
+  'list_backups',
+  'List available backup/restore points from all sources (git refs, shadow copies). Read-only. Use before restore to find candidate versions.',
+  {
+    path: z.string().describe('Absolute path to the project directory'),
+    file: z.string().optional().describe('Filter to a specific file (relative path)'),
+    before: z.string().optional().describe('Only show backups before this time (e.g. "10 minutes ago", "2026-03-21T14:00:00")'),
+    limit: z.number().optional().describe('Max results per source (default 20)'),
+  },
+  async ({ path: projectPath, file, before, limit }) => {
+    const resolved = path.resolve(projectPath);
+    const result = injectAlert(resolved, listBackups(resolved, { file, before, limit }));
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify(result, null, 2),
+      }],
+    };
+  }
+);
+
+// ── Tool 3: snapshot_now ────────────────────────────────────────
+
+server.tool(
+  'snapshot_now',
+  'Create an immediate backup snapshot of the current project state. Use before risky operations to preserve a restore point.',
+  {
+    path: z.string().describe('Absolute path to the project directory'),
+    strategy: z.enum(['git', 'shadow', 'both']).optional().describe('Backup strategy (default: from config, or "git")'),
+    message: z.string().optional().describe('Custom commit message for git snapshot'),
+  },
+  async ({ path: projectPath, strategy, message }) => {
+    const resolved = path.resolve(projectPath);
+    const { loadConfig } = require('../lib/utils');
+    const { cfg } = loadConfig(resolved);
+
+    const effectiveStrategy = strategy || cfg.backup_strategy || 'git';
+    const results = {};
+
+    if (effectiveStrategy === 'git' || effectiveStrategy === 'both') {
+      results.git = createGitSnapshot(resolved, cfg, {
+        branchRef: 'refs/guard/snapshot',
+        message: message || `guard: manual snapshot ${new Date().toISOString()}`,
+      });
+    }
+
+    if (effectiveStrategy === 'shadow' || effectiveStrategy === 'both') {
+      results.shadow = createShadowCopy(resolved, cfg);
+    }
+
+    injectAlert(resolved, results);
+
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify(results, null, 2),
+      }],
+    };
+  }
+);
+
+// ── Tool 4: restore_file ────────────────────────────────────────
+
+server.tool(
+  'restore_file',
+  'Restore a single file from a backup source (git commit/ref or shadow copy timestamp). By default, preserves the current version in a pre-restore snapshot before restoring.',
+  {
+    path: z.string().describe('Absolute path to the project directory'),
+    file: z.string().describe('Relative path to the file to restore'),
+    source: z.string().describe('Backup source: git commit hash, ref name, or shadow copy timestamp (e.g. "20260321_143205")'),
+    preserve_current: z.boolean().optional().describe('Create pre-restore snapshot before restoring (default true)'),
+  },
+  async ({ path: projectPath, file, source, preserve_current }) => {
+    const resolved = path.resolve(projectPath);
+    const result = injectAlert(resolved, restoreFile(resolved, file, source, {
+      preserveCurrent: preserve_current,
+    }));
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify(result, null, 2),
+      }],
+    };
+  }
+);
+
+// ── Tool 5: restore_project ─────────────────────────────────────
+
+server.tool(
+  'restore_project',
+  'Preview or execute a full project restore to a given backup point. In preview mode (default), shows affected files (including untracked) without changes. In execute mode, creates a pre-restore snapshot then restores all tracked files and cleans untracked files.',
+  {
+    path: z.string().describe('Absolute path to the project directory'),
+    source: z.string().describe('Backup source: git commit hash or ref name'),
+    preview: z.boolean().optional().describe('If true (default), only show what would change. If false, execute the restore.'),
+    preserve_current: z.boolean().optional().describe('Create pre-restore snapshot before executing (default true, only used when preview=false)'),
+    clean_untracked: z.boolean().optional().describe('Remove untracked non-ignored files after restore (default true, only used when preview=false)'),
+  },
+  async ({ path: projectPath, source, preview, preserve_current, clean_untracked }) => {
+    const resolved = path.resolve(projectPath);
+
+    if (preview !== false) {
+      const result = injectAlert(resolved, previewProjectRestore(resolved, source));
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+
+    const result = injectAlert(resolved, executeProjectRestore(resolved, source, {
+      preserveCurrent: preserve_current,
+      cleanUntracked: clean_untracked,
+    }));
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// ── Tool 6: doctor_fix ──────────────────────────────────────────
+
+server.tool(
+  'doctor_fix',
+  'Auto-fix common configuration and environment issues: create missing config, init git repo, add .cursor-guard-backup/ to .gitignore, remove stale lock files, fix strategy mismatch. Each fix is idempotent. Use dry_run=true to preview without changes.',
+  {
+    path: z.string().describe('Absolute path to the project directory'),
+    dry_run: z.boolean().optional().describe('If true, report what would be fixed without modifying anything (default false)'),
+  },
+  async ({ path: projectPath, dry_run }) => {
+    const resolved = path.resolve(projectPath);
+    const result = injectAlert(resolved, runFixes(resolved, { dryRun: !!dry_run }));
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// ── Tool 7: backup_status ───────────────────────────────────────
+
+server.tool(
+  'backup_status',
+  'Get comprehensive backup system status: watcher running/stale, last backup time per strategy, configured strategy and retention, guard ref counts, disk space. Read-only, safe to call anytime.',
+  {
+    path: z.string().describe('Absolute path to the project directory'),
+  },
+  async ({ path: projectPath }) => {
+    const resolved = path.resolve(projectPath);
+    const result = injectAlert(resolved, getBackupStatus(resolved));
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// ── Tool 8: dashboard ───────────────────────────────────────────
+
+server.tool(
+  'dashboard',
+  'Get a comprehensive backup health dashboard: strategy, last backup time, backup counts, disk usage breakdown, protection scope, health assessment, and active alerts. Combines status + analytics in one call.',
+  {
+    path: z.string().describe('Absolute path to the project directory'),
+  },
+  async ({ path: projectPath }) => {
+    const resolved = path.resolve(projectPath);
+    const result = injectAlert(resolved, getDashboard(resolved));
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// ── Tool 9: alert_status ────────────────────────────────────────
+
+server.tool(
+  'alert_status',
+  'Check if there is an active change-velocity alert (V4 proactive detection). Returns the alert details if active, or confirms no alert. Read-only, safe to call anytime.',
+  {
+    path: z.string().describe('Absolute path to the project directory'),
+  },
+  async ({ path: projectPath }) => {
+    const resolved = path.resolve(projectPath);
+    const alert = loadActiveAlert(resolved);
+    const result = alert
+      ? { active: true, alert }
+      : { active: false, message: 'No active alerts' };
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// ── Start ───────────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error('cursor-guard MCP server failed to start:', err);
+  process.exit(1);
+});