feat(mcp): make background sync opt-in

Author: d77b10553196ce7fbfcc1c54c46530dab_aondt

packages/mcp/README.md

@@ -183,6 +183,22 @@ CUSTOM_IGNORE_PATTERNS=temp/**,*.backup,private/**,uploads/**
 
 These settings work in combination with tool parameters - patterns from both sources will be merged together.
 
+#### Background Sync Configuration (Optional)
+
+By default, the MCP server does **not** run background sync. This avoids duplicated rescans when multiple local MCP sessions are open at the same time.
+
+If you want automatic reindexing, enable it explicitly:
+
+```bash
+# Opt in to startup + periodic background sync
+CLAUDE_CONTEXT_BACKGROUND_SYNC=true
+
+# Optional: control how often sync runs (default: 300000 = 5 minutes)
+CLAUDE_CONTEXT_SYNC_INTERVAL_MS=60000
+```
+
+This is most useful when you run Claude Context as a single long-lived MCP server. For per-session local stdio setups, leaving background sync disabled usually avoids unnecessary CPU churn.
+
 ## Usage with MCP Clients
 
 <details>

packages/mcp/src/config.ts

@@ -203,6 +203,10 @@ Environment Variables:
   MILVUS_ADDRESS          Milvus address (optional, can be auto-resolved from token)
   MILVUS_TOKEN            Milvus token (optional, used for authentication and address resolution)
 
+  MCP Sync Configuration:
+  CLAUDE_CONTEXT_BACKGROUND_SYNC   Enable background sync for indexed codebases (default: false)
+  CLAUDE_CONTEXT_SYNC_INTERVAL_MS  Background sync interval in milliseconds when enabled (default: 300000)
+
 Examples:
   # Start MCP server with OpenAI (default) and explicit Milvus address
   OPENAI_API_KEY=sk-xxx MILVUS_ADDRESS=localhost:19530 npx @zilliz/claude-context-mcp@latest
@@ -221,5 +225,8 @@ Examples:
   
   # Start MCP server with Ollama and specific model (using EMBEDDING_MODEL)
   EMBEDDING_PROVIDER=Ollama EMBEDDING_MODEL=nomic-embed-text MILVUS_TOKEN=your-token npx @zilliz/claude-context-mcp@latest
+
+  # Start MCP server with background sync enabled every minute
+  OPENAI_API_KEY=sk-xxx MILVUS_TOKEN=your-token CLAUDE_CONTEXT_BACKGROUND_SYNC=true CLAUDE_CONTEXT_SYNC_INTERVAL_MS=60000 npx @zilliz/claude-context-mcp@latest
         `);
-} 
+}

packages/mcp/src/sync.ts

@@ -1,7 +1,55 @@
 import * as fs from "fs";
-import { Context, FileSynchronizer } from "@zilliz/claude-context-core";
+import { Context, FileSynchronizer, envManager } from "@zilliz/claude-context-core";
 import { SnapshotManager } from "./snapshot.js";
 
+const DEFAULT_INITIAL_SYNC_DELAY_MS = 5_000;
+const DEFAULT_SYNC_INTERVAL_MS = 5 * 60 * 1000;
+const MIN_SYNC_INTERVAL_MS = 1_000;
+
+function isBackgroundSyncEnabled(): boolean {
+    const value = envManager.get("CLAUDE_CONTEXT_BACKGROUND_SYNC");
+    if (!value) {
+        return false;
+    }
+
+    switch (value.trim().toLowerCase()) {
+        case "1":
+        case "true":
+        case "yes":
+        case "on":
+            return true;
+        case "0":
+        case "false":
+        case "no":
+        case "off":
+            return false;
+        default:
+            console.warn(
+                `[SYNC-DEBUG] Invalid CLAUDE_CONTEXT_BACKGROUND_SYNC value '${value}'. ` +
+                "Expected true/false. Background sync will remain disabled."
+            );
+            return false;
+    }
+}
+
+function getBackgroundSyncIntervalMs(): number {
+    const value = envManager.get("CLAUDE_CONTEXT_SYNC_INTERVAL_MS");
+    if (!value) {
+        return DEFAULT_SYNC_INTERVAL_MS;
+    }
+
+    const intervalMs = Number.parseInt(value, 10);
+    if (!Number.isFinite(intervalMs) || intervalMs < MIN_SYNC_INTERVAL_MS) {
+        console.warn(
+            `[SYNC-DEBUG] Invalid CLAUDE_CONTEXT_SYNC_INTERVAL_MS value '${value}'. ` +
+            `Falling back to ${DEFAULT_SYNC_INTERVAL_MS}ms.`
+        );
+        return DEFAULT_SYNC_INTERVAL_MS;
+    }
+
+    return intervalMs;
+}
+
 export class SyncManager {
     private context: Context;
     private snapshotManager: SnapshotManager;
@@ -114,8 +162,15 @@ export class SyncManager {
     public startBackgroundSync(): void {
         console.log('[SYNC-DEBUG] startBackgroundSync() called');
 
+        if (!isBackgroundSyncEnabled()) {
+            console.log('[SYNC-DEBUG] Background sync is disabled. Set CLAUDE_CONTEXT_BACKGROUND_SYNC=true to enable it.');
+            return;
+        }
+
+        const syncIntervalMs = getBackgroundSyncIntervalMs();
+
         // Execute initial sync immediately after a short delay to let server initialize
-        console.log('[SYNC-DEBUG] Scheduling initial sync in 5 seconds...');
+        console.log(`[SYNC-DEBUG] Scheduling initial sync in ${DEFAULT_INITIAL_SYNC_DELAY_MS}ms...`);
         setTimeout(async () => {
             console.log('[SYNC-DEBUG] Executing initial sync after server startup');
             try {
@@ -129,15 +184,15 @@ export class SyncManager {
                     throw error;
                 }
             }
-        }, 5000); // Initial sync after 5 seconds
+        }, DEFAULT_INITIAL_SYNC_DELAY_MS);
 
         // Periodically check for file changes and update the index
-        console.log('[SYNC-DEBUG] Setting up periodic sync every 5 minutes (300000ms)');
+        console.log(`[SYNC-DEBUG] Setting up periodic sync every ${syncIntervalMs}ms`);
         const syncInterval = setInterval(() => {
             console.log('[SYNC-DEBUG] Executing scheduled periodic sync');
             this.handleSyncIndex();
-        }, 5 * 60 * 1000); // every 5 minutes
+        }, syncIntervalMs);
 
         console.log('[SYNC-DEBUG] Background sync setup complete. Interval ID:', syncInterval);
     }
-} 
+}