Improve ql-mcp VS Code extension UX (#230)

* Initial plan

* feat: add MCP prompt argument completions for VS Code UX

Add completable() wrappers to workflow prompt parameters so VS Code
Copilot Chat shows auto-complete dropdowns for language, query paths,
SARIF files, database paths, and pack roots.

- Create prompt-completions.ts with completion providers for each
  parameter type (language enum, .ql/.qlref files, .sarif files,
  CodeQL databases, codeql-pack.yml directories)
- Update all 14 workflow prompt registrations to use addCompletions()
- Add comprehensive unit tests (35 tests covering all completers
  and the addCompletions utility)

Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/e316ece4-06c5-45d7-8020-062e6ec67e39

Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>

* chore: reset dist files to main to avoid SIGPIPE in validation

Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>

* fix: handle ZodEnum in cloneStringType and add type safety checks

- cloneStringType now accepts both ZodString and ZodEnum (for prompts
  that use raw schema.shape without toPermissiveShape)
- Add runtime type checks that throw clear errors for unexpected types
- Add 2 unit tests for ZodEnum handling in addCompletions

Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/e316ece4-06c5-45d7-8020-062e6ec67e39

Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>

* chore: reset dist files to main for clean PR diff

Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/e316ece4-06c5-45d7-8020-062e6ec67e39

Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>

* fix(UX): improve prompt completions for VS Code slash commands

Addresses three UX issues with MCP prompt argument completions:

1. Database discovery: completeDatabasePath now scans $HOME/codeql/databases/
   as a default search location, and recursively discovers directories
   containing codeql-database.yml (including .testproj dirs) in the workspace.

2. Language auto-derivation: For prompts where queryPath is provided,
   language is now optional and auto-derived from the nearest
   codeql-pack.yml's codeql/<lang>-all or codeql/<lang>-queries dependency.
   Schema field ordering now puts queryPath before language so VS Code
   prompts for the query first. Affected schemas: explainCodeqlQuerySchema,
   documentCodeqlQuerySchema, workshopCreationWorkflowSchema,
   qlLspIterativeDevelopmentSchema.

3. Query path completion filtering: completeQueryPath now skips .github,
   dist, coverage, and build directories in addition to node_modules, .git,
   and .tmp — preventing workshop examples and build artifacts from
   cluttering the VS Code dropdown.

New tests: 19 unit tests covering all three fixes.
Updated tests: 9 existing tests updated to reflect language being optional.

* Improve vscode extension CodeQL pack install

* 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

* Logging fixes for pack installer & rel path

* Server & extension fixes for PR review feedback

* refactor: address review feedback — centralize skip dirs, extract getEffectiveLanguage helper, add Windows env stubs

- Centralize directory skip list into SKIP_DIRS set used by
  findFilesByExtension, findDatabaseDirs, and completePackRoot
  (adds dist/, coverage/, build/, .github/ to completePackRoot)
- Extract getEffectiveLanguage() helper to eliminate duplicated
  language auto-derivation logic across 4 prompt handlers
- Add Windows env var stubs (HOMEDRIVE, HOMEPATH, USERPROFILE)
  to database completion tests for cross-platform compatibility
- Add 5 unit tests for getEffectiveLanguage()

Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/e315dcb4-ed12-428b-8294-14b398746c4c

Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>

* 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

* Add actions workflow triggers for "next" branch

Adds "on.pull_request" and "on.push" triggers for the "next" branch
for actions workflows with equivalent triggers for the "main" branch.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>
Co-authored-by: Nathan Randall <data-douser@github.com>

Author: Copilot

.github/workflows/build-and-test-extension.yml

@@ -2,7 +2,7 @@ name: Build and Test Extension - CodeQL Development MCP Server
 
 on:
   pull_request:
-    branches: ['main']
+    branches: ['main', 'next']
     paths:
       - '.github/workflows/build-and-test-extension.yml'
       - '.node-version'
@@ -11,7 +11,7 @@ on:
       - 'server/ql/*/tools/src/**'
       - 'server/src/**'
   push:
-    branches: ['main']
+    branches: ['main', 'next']
     paths:
       - '.github/workflows/build-and-test-extension.yml'
       - '.node-version'

.github/workflows/build-server.yml

@@ -2,13 +2,13 @@ name: Build Server - CodeQL Development MCP Server
 
 on:
   pull_request:
-    branches: ['main']
+    branches: ['main', 'next']
     paths:
       - '.github/workflows/build-server.yml'
       - '.node-version'
       - 'server/**'
   push:
-    branches: ['main']
+    branches: ['main', 'next']
     paths:
       - '.github/workflows/build-server.yml'
       - '.node-version'

.github/workflows/client-integration-tests.yml

@@ -2,7 +2,7 @@ name: QL MCP Client Integration Tests
 
 on:
   push:
-    branches: [main]
+    branches: [main, next]
     paths:
       - '.github/actions/setup-codeql-environment/action.yml'
       - '.github/workflows/client-integration-tests.yml'
@@ -11,7 +11,7 @@ on:
       - 'client/**'
       - 'server/**'
   pull_request:
-    branches: [main]
+    branches: [main, next]
     paths:
       - '.github/actions/setup-codeql-environment/action.yml'
       - '.github/workflows/client-integration-tests.yml'

.github/workflows/dependency-review.yml

@@ -2,7 +2,7 @@ name: Dependency Review
 
 on:
   pull_request:
-    branches: ['main']
+    branches: ['main', 'next']
 
 permissions:
   contents: read

.github/workflows/lint-and-format.yml

@@ -2,9 +2,9 @@ name: Lint and Format - CodeQL Development MCP Server
 
 on:
   pull_request:
-    branches: ['main']
+    branches: ['main', 'next']
   push:
-    branches: ['main']
+    branches: ['main', 'next']
   workflow_dispatch:
 
 permissions:

.github/workflows/query-unit-tests-swift.yml

@@ -2,7 +2,7 @@ name: Query Unit Tests - Swift (macOS)
 
 on:
   pull_request:
-    branches: ['main']
+    branches: ['main', 'next']
     paths:
       - '.codeql-version'
       - '.github/actions/setup-codeql-environment/**'
@@ -12,7 +12,7 @@ on:
       - 'server/scripts/install-packs.sh'
       - 'server/scripts/run-query-unit-tests.sh'
   push:
-    branches: ['main']
+    branches: ['main', 'next']
     paths:
       - '.codeql-version'
       - '.github/actions/setup-codeql-environment/**'

.github/workflows/query-unit-tests.yml

@@ -2,7 +2,7 @@ name: Query Unit Tests - CodeQL Development MCP Server
 
 on:
   pull_request:
-    branches: ['main']
+    branches: ['main', 'next']
     paths:
       - '.codeql-version'
       - '.gitmodules'
@@ -16,7 +16,7 @@ on:
       - 'server/scripts/install-packs.sh'
       - 'server/scripts/run-query-unit-tests.sh'
   push:
-    branches: ['main']
+    branches: ['main', 'next']
     paths:
       - '.codeql-version'
       - '.gitmodules'

extensions/vscode/__mocks__/vscode.ts

@@ -82,6 +82,11 @@ export const workspace = {
   onDidCreateFiles: noopReturn({ dispose: noop }),
   onDidSaveTextDocument: noopReturn({ dispose: noop }),
   fs: { stat: noop, readFile: noop, readDirectory: noop },
+  asRelativePath: (pathOrUri: any) => {
+    const p = typeof pathOrUri === 'string' ? pathOrUri : pathOrUri?.fsPath ?? String(pathOrUri);
+    return p;
+  },
+  updateWorkspaceFolders: () => true,
 };
 
 export const window = {

extensions/vscode/esbuild.config.js

@@ -37,6 +37,8 @@ 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',
     'test/suite/mcp-server.integration.test.ts',

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,