feat(mcp): make background sync opt-in

Author: d77b10553196ce7fbfcc1c54c46530dab_aondt

packages/mcp/README.md

@@ -197,6 +197,22 @@ CODE_CHUNKS_COLLECTION_NAME_OVERRIDE=my_project
 
 The per-codebase `<pathHash>` suffix is preserved even when the override is set, so the same MCP server can still index multiple repos without collapsing them onto one collection. The override value is sanitized to letters, numbers, and underscores, and truncated to keep the full name within Milvus's 255-char limit. If you unset the variable later, Claude Context switches back to the plain `code_chunks_<pathHash>` naming.
 
+#### 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

@@ -226,6 +226,10 @@ Environment Variables:
                           The per-codebase pathHash is preserved so multiple
                           codebases stay distinct under the same override.
 
+  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
@@ -247,5 +251,8 @@ Examples:
 
   # Start MCP server with a human-readable collection name override
   OPENAI_API_KEY=sk-xxx MILVUS_TOKEN=your-token CODE_CHUNKS_COLLECTION_NAME_OVERRIDE=my_project 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,12 +1,59 @@
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
-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;
 const DEFAULT_SYNC_LOCK_STALE_MS = 10 * 60 * 1000;
 const SYNC_LOCK_STALE_ENV = "CLAUDE_CONTEXT_SYNC_LOCK_STALE_MS";
 
+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;
@@ -212,8 +259,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 {
@@ -227,14 +281,14 @@ export class SyncManager {
                     // Do not re-throw here: this callback runs via setTimeout with no caller to propagate to.
                 }
             }
-        }, 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);
     }