fix(vscode): stable MCP server definition in VS Code

File watcher events (database discovery, query result creation) were
triggering envBuilder.invalidate() + mcpProvider.fireDidChange(), causing
VS Code to re-query provideMcpServerDefinitions() on every workspace
file change. The debounce only coalesced rapid events but did not prevent
the unnecessary re-provision cycle.

The MCP server definition only needs to change when:
- The extension itself changes (update/reinstall)
- Workspace folder registration changes (folders added/removed)
- Configuration changes that affect the server

The running server discovers databases and query results on its own
through filesystem scanning at tool invocation time, so notifying
VS Code of file content changes is unnecessary.

Also includes:
- Prompt completion caching with 5s TTL to avoid repeated filesystem
  scans during rapid completion requests
- Debounce timer cancellation when McpProvider is disposed
- Unit tests verifying watchers do not trigger fireDidChange
- Integration tests verifying file creation does not fire
  onDidChangeMcpServerDefinitions

Author: data-douser

extensions/vscode/esbuild.config.js

@@ -37,6 +37,7 @@ const testSuiteConfig = {
     'test/suite/bridge.integration.test.ts',
     'test/suite/copydb-e2e.integration.test.ts',
     'test/suite/extension.integration.test.ts',
+    'test/suite/file-watcher-stability.integration.test.ts',
     'test/suite/mcp-completion-e2e.integration.test.ts',
     'test/suite/mcp-prompt-e2e.integration.test.ts',
     'test/suite/mcp-resource-e2e.integration.test.ts',

extensions/vscode/src/extension.ts

@@ -48,16 +48,14 @@ export async function activate(
       const queryWatcher = new QueryResultsWatcher(storagePaths, logger);
       disposables.push(dbWatcher, queryWatcher);
 
-      // When databases or query results change, rebuild the environment and
-      // notify the MCP provider that the server definition has changed.
-      dbWatcher.onDidChange(() => {
-        envBuilder.invalidate();
-        mcpProvider.fireDidChange();
-      });
-      queryWatcher.onDidChange(() => {
-        envBuilder.invalidate();
-        mcpProvider.fireDidChange();
-      });
+      // File-content changes (new databases, query results) do NOT require
+      // a new MCP server definition.  The running server discovers files on
+      // its own through filesystem scanning at tool invocation time.  The
+      // definition only needs to change when the server binary, workspace
+      // folder registration, or configuration changes.
+      //
+      // The watchers are still useful: they log file events for debugging
+      // and DatabaseWatcher tracks known databases internally.
     } catch (err) {
       logger.warn(
         `Failed to initialize file watchers: ${err instanceof Error ? err.message : String(err)}`,

extensions/vscode/src/server/mcp-provider.ts

@@ -33,6 +33,12 @@ export class McpProvider
    */
   private readonly _extensionVersion: string;
 
+  /**
+   * Handle for the pending debounced `fireDidChange()` timer.
+   * Used to coalesce rapid file-system events into a single notification.
+   */
+  private _debounceTimer: ReturnType<typeof globalThis.setTimeout> | undefined;
+
   constructor(
     private readonly serverManager: ServerManager,
     private readonly envBuilder: EnvironmentBuilder,
@@ -51,9 +57,18 @@ export class McpProvider
    * will NOT restart the server. Use for lightweight updates (file watcher
    * events, extension changes, background install completion) where the
    * running server can continue with its current environment.
+   *
+   * Debounced: rapid-fire calls (e.g. from file-system watchers during
+   * a build) are coalesced into a single notification after a short delay.
    */
   fireDidChange(): void {
-    this._onDidChange.fire();
+    if (this._debounceTimer !== undefined) {
+      globalThis.clearTimeout(this._debounceTimer);
+    }
+    this._debounceTimer = globalThis.setTimeout(() => {
+      this._debounceTimer = undefined;
+      this._onDidChange.fire();
+    }, 1_000);
   }
 
   /**
@@ -68,6 +83,11 @@ export class McpProvider
    * Use for changes that require a server restart (configuration changes).
    */
   requestRestart(): void {
+    // Cancel any pending debounced fireDidChange — the restart supersedes it.
+    if (this._debounceTimer !== undefined) {
+      globalThis.clearTimeout(this._debounceTimer);
+      this._debounceTimer = undefined;
+    }
     this.envBuilder.invalidate();
     this._revision++;
     this.logger.info(

extensions/vscode/test/extension.test.ts

@@ -77,6 +77,7 @@ vi.mock('../src/bridge/database-watcher', () => ({
     const listeners: Function[] = [];
     return {
       onDidChange: (listener: Function) => { listeners.push(listener); return { dispose: () => {} }; },
+      _fire: () => { for (const fn of listeners) fn(); },
       getKnownDatabases: vi.fn().mockReturnValue(new Set()),
       dispose: vi.fn(),
     };
@@ -88,6 +89,7 @@ vi.mock('../src/bridge/query-results-watcher', () => ({
     const listeners: Function[] = [];
     return {
       onDidChange: (listener: Function) => { listeners.push(listener); return { dispose: () => {} }; },
+      _fire: () => { for (const fn of listeners) fn(); },
       dispose: vi.fn(),
     };
   }),
@@ -107,6 +109,8 @@ import { activate, deactivate } from '../src/extension';
 import * as vscode from 'vscode';
 import { McpProvider } from '../src/server/mcp-provider';
 import { EnvironmentBuilder } from '../src/bridge/environment-builder';
+import { DatabaseWatcher } from '../src/bridge/database-watcher';
+import { QueryResultsWatcher } from '../src/bridge/query-results-watcher';
 
 function createMockContext(): vscode.ExtensionContext {
   return {
@@ -208,4 +212,42 @@ describe('Extension', () => {
       spy.mockRestore();
     }
   });
+
+  it('should NOT call fireDidChange when database watcher fires', async () => {
+    await activate(ctx);
+
+    const dbWatcherInstance = vi.mocked(DatabaseWatcher).mock.results[0]?.value;
+    const mcpProviderInstance = vi.mocked(McpProvider).mock.results[0]?.value;
+    const envBuilderInstance = vi.mocked(EnvironmentBuilder).mock.results[0]?.value;
+
+    mcpProviderInstance.fireDidChange.mockClear();
+    mcpProviderInstance.requestRestart.mockClear();
+    envBuilderInstance.invalidate.mockClear();
+
+    // Simulate a database watcher event (e.g. codeql-database.yml created)
+    dbWatcherInstance._fire();
+
+    expect(mcpProviderInstance.fireDidChange).not.toHaveBeenCalled();
+    expect(mcpProviderInstance.requestRestart).not.toHaveBeenCalled();
+    expect(envBuilderInstance.invalidate).not.toHaveBeenCalled();
+  });
+
+  it('should NOT call fireDidChange when query results watcher fires', async () => {
+    await activate(ctx);
+
+    const queryWatcherInstance = vi.mocked(QueryResultsWatcher).mock.results[0]?.value;
+    const mcpProviderInstance = vi.mocked(McpProvider).mock.results[0]?.value;
+    const envBuilderInstance = vi.mocked(EnvironmentBuilder).mock.results[0]?.value;
+
+    mcpProviderInstance.fireDidChange.mockClear();
+    mcpProviderInstance.requestRestart.mockClear();
+    envBuilderInstance.invalidate.mockClear();
+
+    // Simulate a query results watcher event (e.g. .bqrs file created)
+    queryWatcherInstance._fire();
+
+    expect(mcpProviderInstance.fireDidChange).not.toHaveBeenCalled();
+    expect(mcpProviderInstance.requestRestart).not.toHaveBeenCalled();
+    expect(envBuilderInstance.invalidate).not.toHaveBeenCalled();
+  });
 });

extensions/vscode/test/server/mcp-provider.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 
 
 import { McpProvider } from '../../src/server/mcp-provider';
@@ -236,4 +236,94 @@ describe('McpProvider', () => {
   it('should be disposable', () => {
     expect(() => provider.dispose()).not.toThrow();
   });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // fireDidChange — debouncing
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe('fireDidChange debouncing', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('should debounce rapid calls into a single event', () => {
+      const listener = vi.fn();
+      provider.onDidChangeMcpServerDefinitions(listener);
+
+      // Fire 10 rapid calls
+      for (let i = 0; i < 10; i++) {
+        provider.fireDidChange();
+      }
+
+      // Before timer fires, no events should have been emitted
+      expect(listener).not.toHaveBeenCalled();
+
+      // After debounce period, exactly one event should fire
+      vi.runAllTimers();
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('should coalesce events within the debounce window', () => {
+      const listener = vi.fn();
+      provider.onDidChangeMcpServerDefinitions(listener);
+
+      provider.fireDidChange();
+      vi.advanceTimersByTime(100);
+      provider.fireDidChange();
+      vi.advanceTimersByTime(100);
+      provider.fireDidChange();
+
+      // Still within debounce window — no events yet
+      expect(listener).not.toHaveBeenCalled();
+
+      // Let debounce timer complete
+      vi.runAllTimers();
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('should fire separate events for calls outside debounce window', () => {
+      const listener = vi.fn();
+      provider.onDidChangeMcpServerDefinitions(listener);
+
+      provider.fireDidChange();
+      vi.runAllTimers();
+      expect(listener).toHaveBeenCalledTimes(1);
+
+      // Second call well after first debounce completed
+      provider.fireDidChange();
+      vi.runAllTimers();
+      expect(listener).toHaveBeenCalledTimes(2);
+    });
+
+    it('should not debounce requestRestart (fires immediately)', () => {
+      const listener = vi.fn();
+      provider.onDidChangeMcpServerDefinitions(listener);
+
+      provider.requestRestart();
+
+      // requestRestart should fire immediately without waiting for debounce
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it('should cancel pending debounced fire when requestRestart is called', () => {
+      const listener = vi.fn();
+      provider.onDidChangeMcpServerDefinitions(listener);
+
+      // Start a debounced fireDidChange
+      provider.fireDidChange();
+      expect(listener).not.toHaveBeenCalled();
+
+      // requestRestart should fire immediately and cancel the pending debounce
+      provider.requestRestart();
+      expect(listener).toHaveBeenCalledTimes(1);
+
+      // Running timers should NOT fire the debounced event again
+      vi.runAllTimers();
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+  });
 });

extensions/vscode/test/suite/file-watcher-stability.integration.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Integration tests for file watcher stability.
+ *
+ * Verifies that workspace file changes (database discovery, query result
+ * creation) do NOT trigger redundant MCP server definition change events.
+ *
+ * The MCP server definition should only change when:
+ *  - The extension itself changes (update / reinstall)
+ *  - Workspace folder registration changes (folders added / removed)
+ *  - Configuration changes that affect the server
+ *
+ * File content changes are NOT a reason to re-provide the definition:
+ * the running server discovers files on its own through filesystem
+ * scanning at tool invocation time.
+ */
+
+import * as assert from 'assert';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as vscode from 'vscode';
+
+const EXTENSION_ID = 'advanced-security.vscode-codeql-development-mcp-server';
+
+/** Milliseconds to wait past the 1 s debounce to confirm no event fires. */
+const SETTLE_MS = 2_500;
+
+suite('File Watcher Stability Tests', () => {
+  let api: any;
+  const cleanupPaths: string[] = [];
+
+  suiteSetup(async function () {
+    this.timeout(10_000);
+    const ext = vscode.extensions.getExtension(EXTENSION_ID);
+    assert.ok(ext, `Extension ${EXTENSION_ID} not found`);
+    api = ext.isActive ? ext.exports : await ext.activate();
+
+    if (!vscode.workspace.workspaceFolders?.length) {
+      console.log(
+        '[file-watcher-stability] Skipping — requires workspace with at least one folder',
+      );
+      this.skip();
+    }
+
+    // Let any startup-related events settle before running tests.
+    await new Promise((r) => globalThis.setTimeout(r, SETTLE_MS));
+  });
+
+  suiteTeardown(() => {
+    for (const p of cleanupPaths) {
+      try {
+        fs.rmSync(p, { recursive: true, force: true });
+      } catch {
+        /* best-effort */
+      }
+    }
+  });
+
+  // -----------------------------------------------------------------
+  // Test 1: BQRS file creation must NOT fire definition change event
+  // -----------------------------------------------------------------
+  test('Creating a BQRS file should NOT trigger onDidChangeMcpServerDefinitions', async function () {
+    this.timeout(10_000);
+
+    const mcpProvider = api.mcpProvider;
+    assert.ok(mcpProvider, 'API missing mcpProvider');
+    assert.ok(
+      typeof mcpProvider.onDidChangeMcpServerDefinitions === 'function',
+      'mcpProvider missing onDidChangeMcpServerDefinitions',
+    );
+
+    let changeCount = 0;
+    const disposable = mcpProvider.onDidChangeMcpServerDefinitions(() => {
+      changeCount++;
+    });
+
+    try {
+      const workspaceRoot =
+        vscode.workspace.workspaceFolders![0].uri.fsPath;
+      const bqrsPath = path.join(
+        workspaceRoot,
+        `stability-test-${Date.now()}.bqrs`,
+      );
+      cleanupPaths.push(bqrsPath);
+
+      fs.writeFileSync(bqrsPath, Buffer.from([0x00]));
+
+      // Wait past the debounce period (1 s) plus buffer
+      await new Promise((r) => globalThis.setTimeout(r, SETTLE_MS));
+
+      assert.strictEqual(
+        changeCount,
+        0,
+        `onDidChangeMcpServerDefinitions fired ${changeCount} time(s) after BQRS file creation; ` +
+          'file content changes should NOT trigger MCP server definition updates',
+      );
+    } finally {
+      disposable.dispose();
+    }
+  });
+
+  // -----------------------------------------------------------------
+  // Test 2: codeql-database.yml creation must NOT fire change event
+  // -----------------------------------------------------------------
+  test('Creating a codeql-database.yml should NOT trigger onDidChangeMcpServerDefinitions', async function () {
+    this.timeout(10_000);
+
+    const mcpProvider = api.mcpProvider;
+    assert.ok(mcpProvider, 'API missing mcpProvider');
+
+    let changeCount = 0;
+    const disposable = mcpProvider.onDidChangeMcpServerDefinitions(() => {
+      changeCount++;
+    });
+
+    try {
+      const workspaceRoot =
+        vscode.workspace.workspaceFolders![0].uri.fsPath;
+      const dbDir = path.join(
+        workspaceRoot,
+        `stability-test-db-${Date.now()}`,
+      );
+      fs.mkdirSync(dbDir, { recursive: true });
+      cleanupPaths.push(dbDir);
+
+      const ymlPath = path.join(dbDir, 'codeql-database.yml');
+      fs.writeFileSync(ymlPath, 'primaryLanguage: javascript\n');
+
+      await new Promise((r) => globalThis.setTimeout(r, SETTLE_MS));
+
+      assert.strictEqual(
+        changeCount,
+        0,
+        `onDidChangeMcpServerDefinitions fired ${changeCount} time(s) after codeql-database.yml creation; ` +
+          'file content changes should NOT trigger MCP server definition updates',
+      );
+    } finally {
+      disposable.dispose();
+    }
+  });
+});