feat: shared configurable scan-exclude dirs

Extract SKIP_DIRS from prompt-completions.ts and
search-ql-code.ts into a shared scan-exclude module
with a comprehensive default list of 20 directories.

The exclusion set is configurable via the env var
CODEQL_MCP_SCAN_EXCLUDE_DIRS (comma-separated).
Entries prefixed with ! remove a default (negation).

Add codeql-mcp.scanExcludeDirs VS Code setting that
the extension passes to the server as the env var.

New files:
- server/src/lib/scan-exclude.ts
- server/test/src/lib/scan-exclude.test.ts

Modified:
- server/src/prompts/prompt-completions.ts
- server/src/tools/codeql/search-ql-code.ts
- extensions/vscode/package.json
- extensions/vscode/src/bridge/environment-builder.ts
- extensions/vscode/test/bridge/environment-builder.test.ts
- server/test/src/prompts/prompt-completions.test.ts

Author: data-douser

extensions/vscode/package.json

@@ -123,6 +123,14 @@
           "default": ".codeql/ql-mcp",
           "markdownDescription": "Workspace-relative path for the ql-mcp scratch directory used for temporary files (query logs, external predicates, etc). The `.codeql/` parent is shared with other CodeQL CLI commands like `codeql pack bundle`. Set to an absolute path to override workspace-relative resolution."
         },
+        "codeql-mcp.scanExcludeDirs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [],
+          "markdownDescription": "Additional directory names to exclude from workspace scanning (prompt completions, QL code search). Entries are merged with the built-in defaults (`.git`, `node_modules`, `dist`, etc.). Prefix an entry with `!` to remove a default (e.g., `!build` re-includes the `build` directory). Passed to the server as `CODEQL_MCP_SCAN_EXCLUDE_DIRS`."
+        },
         "codeql-mcp.watchCodeqlExtension": {
           "type": "boolean",
           "default": true,

extensions/vscode/src/bridge/environment-builder.ts

@@ -166,6 +166,14 @@ export class EnvironmentBuilder extends DisposableObject {
       env.MONITORING_STORAGE_LOCATION = env.CODEQL_MCP_SCRATCH_DIR;
     }
 
+    // Scan exclusion directories for prompt completions and QL code search.
+    // The server reads CODEQL_MCP_SCAN_EXCLUDE_DIRS to merge with built-in
+    // defaults. The setting accepts additions and `!`-prefixed negations.
+    const scanExcludeDirs = config.get<string[]>('scanExcludeDirs', []);
+    if (scanExcludeDirs.length > 0) {
+      env.CODEQL_MCP_SCAN_EXCLUDE_DIRS = scanExcludeDirs.join(',');
+    }
+
     // User-configured additional environment variables (overrides above defaults)
     const additionalEnv = config.get<Record<string, string>>('additionalEnv', {});
     for (const [key, value] of Object.entries(additionalEnv)) {

extensions/vscode/test/bridge/environment-builder.test.ts

@@ -392,4 +392,35 @@ describe('EnvironmentBuilder', () => {
       }
     }
   });
+
+  it('should set CODEQL_MCP_SCAN_EXCLUDE_DIRS when scanExcludeDirs setting is non-empty', async () => {
+    const vscode = await import('vscode');
+    const originalGetConfig = vscode.workspace.getConfiguration;
+
+    try {
+      vscode.workspace.getConfiguration = () => ({
+        get: (_key: string, defaultVal?: any) => {
+          if (_key === 'scanExcludeDirs') return ['custom-build', '!dist'];
+          if (_key === 'additionalDatabaseDirs') return [];
+          if (_key === 'additionalQueryRunResultsDirs') return [];
+          if (_key === 'additionalMrvaRunResultsDirs') return [];
+          return defaultVal;
+        },
+        has: () => false,
+        inspect: () => undefined as any,
+        update: () => Promise.resolve(),
+      }) as any;
+
+      builder.invalidate();
+      const env = await builder.build();
+      expect(env.CODEQL_MCP_SCAN_EXCLUDE_DIRS).toBe('custom-build,!dist');
+    } finally {
+      vscode.workspace.getConfiguration = originalGetConfig;
+    }
+  });
+
+  it('should not set CODEQL_MCP_SCAN_EXCLUDE_DIRS when scanExcludeDirs is empty', async () => {
+    const env = await builder.build();
+    expect(env.CODEQL_MCP_SCAN_EXCLUDE_DIRS).toBeUndefined();
+  });
 });

server/dist/codeql-development-mcp-server.js

@@ -196679,12 +196679,53 @@ var codeqlResolveTestsTool = {
 import { closeSync as closeSync2, createReadStream as createReadStream3, fstatSync as fstatSync2, lstatSync, openSync as openSync2, readdirSync as readdirSync8, readFileSync as readFileSync12, realpathSync as realpathSync2 } from "fs";
 import { basename as basename8, extname as extname2, join as join19, resolve as resolve9 } from "path";
 import { createInterface as createInterface3 } from "readline";
+
+// src/lib/scan-exclude.ts
+var DEFAULT_SCAN_EXCLUDE_DIRS = [
+  ".cache",
+  ".codeql",
+  ".git",
+  ".github",
+  ".idea",
+  ".mypy_cache",
+  ".pytest_cache",
+  ".tmp",
+  ".tox",
+  ".vscode",
+  ".yarn",
+  "__pycache__",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "out",
+  "target",
+  "vendor"
+];
+function getScanExcludeDirs() {
+  const result = new Set(DEFAULT_SCAN_EXCLUDE_DIRS);
+  const envValue = process.env.CODEQL_MCP_SCAN_EXCLUDE_DIRS;
+  if (!envValue) {
+    return result;
+  }
+  const entries = envValue.split(",").map((e) => e.trim()).filter((e) => e.length > 0);
+  for (const entry of entries) {
+    if (entry.startsWith("!")) {
+      result.delete(entry.slice(1).trim());
+    } else {
+      result.add(entry);
+    }
+  }
+  return result;
+}
+
+// src/tools/codeql/search-ql-code.ts
 init_logger();
 var MAX_FILE_SIZE_BYTES = 5 * 1024 * 1024;
 var MAX_FILES_TRAVERSED = 1e4;
 var MAX_CONTEXT_LINES = 50;
 var MAX_MAX_RESULTS = 1e4;
-var SKIP_DIRS2 = /* @__PURE__ */ new Set([".codeql", "node_modules", ".git"]);
+var SKIP_DIRS2 = getScanExcludeDirs();
 function collectFiles(paths, extensions, fileCount) {
   const files = [];
   const visitedDirs = /* @__PURE__ */ new Set();
@@ -198130,15 +198171,7 @@ init_package_paths();
 var MAX_FILE_COMPLETIONS = 50;
 var MAX_SCAN_DEPTH = 8;
 var CACHE_TTL_MS = 5e3;
-var SKIP_DIRS3 = /* @__PURE__ */ new Set([
-  ".git",
-  ".github",
-  ".tmp",
-  "build",
-  "coverage",
-  "dist",
-  "node_modules"
-]);
+var SKIP_DIRS3 = getScanExcludeDirs();
 var scanCache = /* @__PURE__ */ new Map();
 function getCachedResults(cacheKey2) {
   const entry = scanCache.get(cacheKey2);

server/dist/codeql-development-mcp-server.js.map

@@ -0,0 +1,98 @@
+/**
+ * Shared directory exclusion list for workspace scanning operations.
+ *
+ * Provides a comprehensive default set of directory names to skip during
+ * recursive file discovery (prompt completions, QL code search, etc.)
+ * and makes the set configurable via the `CODEQL_MCP_SCAN_EXCLUDE_DIRS`
+ * environment variable.
+ *
+ * The VS Code extension surfaces this as the `codeql-mcp.scanExcludeDirs`
+ * setting, which is passed through to the server as an env var.
+ *
+ * ## Configuration
+ *
+ * The env var accepts a comma-separated list of directory names.
+ * Entries prefixed with `!` remove a default from the set (negation).
+ * All other entries are added to the default set.
+ *
+ * Examples:
+ *   - `CODEQL_MCP_SCAN_EXCLUDE_DIRS="custom-build,tmp-output"` — adds
+ *   - `CODEQL_MCP_SCAN_EXCLUDE_DIRS="!build,!dist"` — removes `build` and `dist` from defaults
+ *   - `CODEQL_MCP_SCAN_EXCLUDE_DIRS="custom-dir,!coverage"` — adds `custom-dir`, removes `coverage`
+ */
+
+/**
+ * Comprehensive default set of directory names to skip during workspace
+ * scanning. Sorted alphabetically.
+ *
+ * This list is the union of directories previously skipped in
+ * `prompt-completions.ts` and `search-ql-code.ts`, plus additional
+ * well-known directories that never contain CodeQL source files and
+ * would slow down scanning.
+ */
+export const DEFAULT_SCAN_EXCLUDE_DIRS: readonly string[] = [
+  '.cache',
+  '.codeql',
+  '.git',
+  '.github',
+  '.idea',
+  '.mypy_cache',
+  '.pytest_cache',
+  '.tmp',
+  '.tox',
+  '.vscode',
+  '.yarn',
+  '__pycache__',
+  'build',
+  'coverage',
+  'dist',
+  'node_modules',
+  'out',
+  'target',
+  'vendor',
+];
+
+/**
+ * Parse the `CODEQL_MCP_SCAN_EXCLUDE_DIRS` environment variable and
+ * merge with defaults.
+ *
+ * @returns A `Set` of directory names to exclude from scanning.
+ */
+export function getScanExcludeDirs(): Set<string> {
+  const result = new Set(DEFAULT_SCAN_EXCLUDE_DIRS);
+
+  const envValue = process.env.CODEQL_MCP_SCAN_EXCLUDE_DIRS;
+  if (!envValue) {
+    return result;
+  }
+
+  const entries = envValue.split(',').map(e => e.trim()).filter(e => e.length > 0);
+
+  for (const entry of entries) {
+    if (entry.startsWith('!')) {
+      // Negation: remove from defaults
+      result.delete(entry.slice(1).trim());
+    } else {
+      // Addition: add to the set
+      result.add(entry);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Check whether a directory name should be excluded from scanning.
+ *
+ * @param dirName  - The directory basename to check.
+ * @param excludeSet - Optional pre-computed exclusion set. When omitted,
+ *                     `getScanExcludeDirs()` is called (reads the env var).
+ * @returns `true` if the directory should be skipped.
+ */
+export function isScanExcluded(
+  dirName: string,
+  excludeSet?: Set<string>,
+): boolean {
+  const set = excludeSet ?? getScanExcludeDirs();
+  return set.has(dirName);
+}

server/src/lib/scan-exclude.ts

@@ -17,6 +17,7 @@ import { dirname, join, relative, sep } from 'path';
 import { completable } from '@modelcontextprotocol/sdk/server/completable.js';
 import { z } from 'zod';
 import { getDatabaseBaseDirs } from '../lib/discovery-config';
+import { getScanExcludeDirs } from '../lib/scan-exclude';
 import { logger } from '../utils/logger';
 import { getUserWorkspaceDir } from '../utils/package-paths';
 import { SUPPORTED_LANGUAGES } from './constants';
@@ -36,17 +37,10 @@ const CACHE_TTL_MS = 5_000;
 
 /**
  * Directories to skip during recursive workspace scans.
- * Centralised so that all completion providers use the same list.
+ * Uses the shared, configurable exclusion list from scan-exclude.ts.
+ * Computed once per module load; the env var is read at that time.
  */
-const SKIP_DIRS = new Set([
-  '.git',
-  '.github',
-  '.tmp',
-  'build',
-  'coverage',
-  'dist',
-  'node_modules',
-]);
+const SKIP_DIRS: Set<string> = getScanExcludeDirs();
 
 /** Cached scan results keyed by a workspace+type identifier. */
 interface CacheEntry {

server/src/prompts/prompt-completions.ts

@@ -12,6 +12,7 @@ import { closeSync, createReadStream, fstatSync, lstatSync, openSync, readdirSyn
 import { basename, extname, join, resolve } from 'path';
 import { createInterface } from 'readline';
 import { z } from 'zod';
+import { getScanExcludeDirs } from '../../lib/scan-exclude';
 import { logger } from '../../utils/logger';
 
 // ---------------------------------------------------------------------------
@@ -30,8 +31,11 @@ const MAX_CONTEXT_LINES = 50;
 /** Maximum allowed value for `maxResults`. */
 const MAX_MAX_RESULTS = 10_000;
 
-/** Directory names to skip during traversal (compiled pack caches, deps). */
-const SKIP_DIRS = new Set(['.codeql', 'node_modules', '.git']);
+/**
+ * Directory names to skip during traversal.
+ * Uses the shared, configurable exclusion list from scan-exclude.ts.
+ */
+const SKIP_DIRS: Set<string> = getScanExcludeDirs();
 
 // ---------------------------------------------------------------------------
 // Types