feat(mcp): Added file locking mechanism to prevent concurrent snapshot file modification

[Ashish-Abraham]

fixes #216

Solution

This PR introduces a Leader Election pattern using file locks to ensure only one MCP server instance can perform write operations (e.g., indexing, syncing, clearing) at a time. On startup, each server attempts to acquire an exclusive lock on ~/.context/leader.lock. The successful instance becomes the "leader" and handles all modifications. Other instances become "followers" with read-only access (e.g., search operations).
Followers periodically check (every 5 seconds) if the lock is available, allowing automatic failover if the leader crashes. The OS ensures atomicity and reliability: locks are released automatically on process termination (including via signals like SIGINT and SIGTERM), and critical writes use temporary files with atomic renames to prevent partial updates.
This approach resolves the concurrency issues without requiring complex distributed coordination.

Implementation Details

Lock File: Uses ~/.context/leader.lock for exclusive locking via the proper-lockfile library, which employs flock on supported systems (e.g., Linux, BSD) and falls back to compatible mechanisms on others (e.g., Windows).
Leader Role: Only the leader performs index modifications (e.g., in handleIndexCodebase, handleClearIndex, and syncIndexedCodebasesFromCloud). Followers return a user-friendly message indicating they cannot perform writes.
Periodic Checks: Followers poll the lock availability every 5 seconds for automatic recovery.
In-Memory Tracking: Current operations are tracked in process memory to avoid stale on-disk markers from crashed instances.
Compatibility: Works across platforms, with OS-level guarantees for lock release on process exit. The lock is explicitly released on graceful shutdown signals (e.g., process.on('exit'), SIGINT, SIGTERM).
Dependency: Introduces proper-lockfile as a new dependency for robust locking.

No changes to existing APIs or user-facing behavior for single-instance usage.

[tad-hq]

This is definitely the number 1 problem with this MCP right now. Thank you Ashish-Abraham, hoping this gets approved.

[iqbal-rsec]

Apologies if I missed it, but acquireLock is not called

[Ashish-Abraham]

@iqbal-rsec sorry i missed it. Kindly check now.

[zc277584121]

Hi @Ashish-Abraham, thanks for this PR — the Leader Election approach is an interesting solution to the concurrent snapshot modification problem (#216).

For context, we've recently shipped some fixes in v0.1.6 (PR #283) that mitigate the symptoms of concurrent snapshot corruption — specifically, we added VectorDB fallback checks and bidirectional cloud sync recovery so the system can self-heal when the snapshot gets into an inconsistent state. However, these are defensive measures; they don't prevent the concurrent write race itself.

Your approach of designating a single writer (leader) with read-only followers addresses the root cause more directly. A few things we'd want to consider:

• How does the leader/follower model interact with the cloud sync logic? If a follower session indexes a new codebase, it would need to coordinate with the leader to update the snapshot.
• The automatic failover on leader crash is a nice touch — the OS-level lock release gives a clean recovery path.
• How does this perform in practice with the 5-second polling interval for follower promotion?

We'll keep this open for now and review it more thoroughly when we plan the next round of snapshot architecture improvements. Thanks for the detailed implementation and for linking it to #216! 🙏