advanced-security · data-douser · Mar 31, 2026 · Mar 31, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,7 +20,7 @@ _Changes on `main` since the latest tagged release that have not yet been includ
 
 - **Persistent MRVA workflow state and caching** — Introduced a new `SqliteStore` backend plus opt-in annotation, audit, and query result cache tools to support the next phase of MCP-assisted CodeQL development and `seclab-taskflow-agent` integration. ([#169](https://github.com/advanced-security/codeql-development-mcp-server/pull/169))
 - **Rust language support** — Added first-class Rust support with `PrintAST`, `PrintCFG`, `CallGraphFrom`, `CallGraphTo`, and `CallGraphFromTo` queries, bringing the total supported languages to 10. ([#195](https://github.com/advanced-security/codeql-development-mcp-server/pull/195))
-- **VS Code workspace change reliability** — Fixed MCP server restart behavior when workspace folders change so the extension now restarts the server with a fresh environment instead of leaving it partially stopped. ([#196](https://github.com/advanced-security/codeql-development-mcp-server/pull/196))
+- **Bug fixes and design improvements from v2.25.1-next.1 evaluation** — Fixed 5 bugs across `bqrs_interpret`, `bqrs_info`, `annotation_search`, `audit_add_notes`, and `query_results_cache_compare`; added `database_analyze` auto-caching and per-database mutex serialization; auto-enabled annotation tools in VS Code extension. ([#199](https://github.com/advanced-security/codeql-development-mcp-server/pull/199))
 
 ### Added
 
@@ -53,15 +53,22 @@ _Changes on `main` since the latest tagged release that have not yet been includ
 
 #### MCP Server Tools
 
-| Tool                                   | Change                                                                                                                                                                                                |
-| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `codeql_query_run`                     | Query results are now auto-cached after SARIF interpretation, enabling later lookup and comparison workflows. ([#169](https://github.com/advanced-security/codeql-development-mcp-server/pull/169))   |
-| query metadata and database resolution | Added in-memory caching with mtime-based invalidation and deduplicated resolution logic for better performance. ([#169](https://github.com/advanced-security/codeql-development-mcp-server/pull/169)) |
+| Tool                                   | Change                                                                                                                                                                                                                                                                                    |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `codeql_query_run`                     | Query results are now auto-cached after SARIF interpretation, enabling later lookup and comparison workflows. ([#169](https://github.com/advanced-security/codeql-development-mcp-server/pull/169))                                                                                       |
+| query metadata and database resolution | Added in-memory caching with mtime-based invalidation and deduplicated resolution logic for better performance. ([#169](https://github.com/advanced-security/codeql-development-mcp-server/pull/169))                                                                                     |
+| `codeql_bqrs_interpret`                | Added optional `database` parameter mapped to `--source-archive` for SARIF source context; validates that `src.zip` or `src` exists. ([#199](https://github.com/advanced-security/codeql-development-mcp-server/pull/199))                                                                |
+| `codeql_bqrs_info`                     | **Breaking**: renamed `files` (array) parameter to `file` (string) to match the CLI which accepts exactly one file. ([#199](https://github.com/advanced-security/codeql-development-mcp-server/pull/199))                                                                                 |
+| `codeql_database_analyze`              | Results are now auto-cached after SARIF output for `query_results_cache_compare` and `query_results_cache_retrieve`; concurrent calls to the same database are serialized via a per-database mutex. ([#199](https://github.com/advanced-security/codeql-development-mcp-server/pull/199)) |
+| `audit_add_notes`                      | Added `findingId` as preferred lookup; `owner`/`repo`/`sourceLocation`/`line` are now optional fallback fields. ([#199](https://github.com/advanced-security/codeql-development-mcp-server/pull/199))                                                                                     |
+| `annotation_search`                    | Category field is now matched with case-insensitive `COLLATE NOCASE` alongside the existing FTS index. ([#199](https://github.com/advanced-security/codeql-development-mcp-server/pull/199))                                                                                              |
+| `query_results_cache_compare`          | SARIF content fallback for result count is now gated on SARIF output format, avoiding unnecessary JSON parsing of non-SARIF cache entries. ([#199](https://github.com/advanced-security/codeql-development-mcp-server/pull/199))                                                          |
 
 #### VS Code Extension
 
 - `McpProvider.requestRestart()` now invalidates the environment cache and bumps a `+rN` revision suffix so VS Code reliably restarts the MCP server after configuration changes. ([#196](https://github.com/advanced-security/codeql-development-mcp-server/pull/196))
 - Cached the extension version in the provider constructor to avoid repeated synchronous reads of `package.json`. ([#196](https://github.com/advanced-security/codeql-development-mcp-server/pull/196))
+- New `codeql-mcp.enableAnnotationTools` setting (default: `true`) auto-sets `ENABLE_ANNOTATION_TOOLS` and `MONITORING_STORAGE_LOCATION` environment variables; `additionalEnv` overrides for advanced users. ([#199](https://github.com/advanced-security/codeql-development-mcp-server/pull/199))
 
 #### Infrastructure & CI/CD
 
@@ -70,6 +77,12 @@ _Changes on `main` since the latest tagged release that have not yet been includ
 ### Fixed
 
 - **Workspace folder changes could leave the MCP server stopped but not restarted** — The VS Code extension now rebuilds the environment and forces a proper restart when workspace folders change. ([#196](https://github.com/advanced-security/codeql-development-mcp-server/pull/196))
+- **`codeql_bqrs_interpret` unusable through MCP interface** — Added `database` parameter mapped to `--source-archive` with `src.zip`/`src` fallback and clear error when neither exists. ([#199](https://github.com/advanced-security/codeql-development-mcp-server/pull/199))
+- **`query_results_cache_compare` reported `totalResultCount: 0`** — Result count is now computed from SARIF `runs[0].results.length` at cache time; compare tool falls back to parsing cached SARIF content only for SARIF-format entries. ([#199](https://github.com/advanced-security/codeql-development-mcp-server/pull/199))
+- **`annotation_search` ignored `category` field** — Extended FTS search condition to also match category with case-insensitive `COLLATE NOCASE`. ([#199](https://github.com/advanced-security/codeql-development-mcp-server/pull/199))
+- **`audit_add_notes` ignored `findingId`** — Added `findingId` as preferred direct-lookup alternative to the composite key fields. ([#199](https://github.com/advanced-security/codeql-development-mcp-server/pull/199))
+- **`codeql_bqrs_info` `files` array caused CLI error** — Changed parameter from `files` (array) to `file` (string) to match the CLI expectation. ([#199](https://github.com/advanced-security/codeql-development-mcp-server/pull/199))
+- **Per-database mutex lock key not normalized** — Database lock key now uses `realpath` to prevent bypassing serialization with relative paths, symlinks, or different casing. ([#199](https://github.com/advanced-security/codeql-development-mcp-server/pull/199))
 
 ### Dependencies
 

diff --git a/client/package.json b/client/package.json
@@ -1,6 +1,6 @@
 {
   "name": "codeql-development-mcp-server_client",
-  "version": "2.25.1-next.1",
+  "version": "2.25.1-next.2",
   "description": "MCP client for integration testing of the CodeQL development MCP server",
   "main": "src/ql-mcp-client.js",
   "type": "module",

diff --git a/extensions/vscode/package.json b/extensions/vscode/package.json
@@ -2,7 +2,7 @@
   "name": "vscode-codeql-development-mcp-server",
   "displayName": "CodeQL Development MCP Server",
   "description": "LLM-assisted development of CodeQL queries, libraries, and tests via #ql-mcp prompts, resources, and tools.",
-  "version": "2.25.1-next.1",
+  "version": "2.25.1-next.2",
   "publisher": "advanced-security",
   "license": "SEE LICENSE IN LICENSE",
   "icon": "media/codeql-icon.png",

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "codeql-development-mcp-server_repo",
-  "version": "2.25.1-next.1",
+  "version": "2.25.1-next.2",
   "description": "An MCP server supporting LLM requests for CodeQL development tools and resources.",
   "private": true,
   "type": "module",

diff --git a/server/dist/codeql-development-mcp-server.js b/server/dist/codeql-development-mcp-server.js
@@ -182798,7 +182798,7 @@ var StreamableHTTPServerTransport = class {
 var import_express = __toESM(require_express2(), 1);
 var import_cors = __toESM(require_lib4(), 1);
 var import_dotenv = __toESM(require_main(), 1);
-import { realpathSync as realpathSync2 } from "fs";
+import { realpathSync as realpathSync3 } from "fs";
 import { resolve as resolve14 } from "path";
 import { pathToFileURL as pathToFileURL5 } from "url";
 
@@ -184635,7 +184635,7 @@ function cacheDatabaseAnalyzeResults(params, logger2) {
 
 // src/lib/cli-tool-registry.ts
 init_package_paths();
-import { writeFileSync as writeFileSync4, rmSync, existsSync as existsSync6, mkdirSync as mkdirSync8 } from "fs";
+import { writeFileSync as writeFileSync4, rmSync, existsSync as existsSync6, mkdirSync as mkdirSync8, realpathSync } from "fs";
 import { delimiter as delimiter5, dirname as dirname5, isAbsolute as isAbsolute4, join as join10, resolve as resolve4 } from "path";
 
 // ../node_modules/js-yaml/dist/js-yaml.mjs
@@ -187490,7 +187490,16 @@ function registerCLITool(server, definition) {
               const dbPath = resolveDatabasePath(options.database);
               const srcZipPath = join10(dbPath, "src.zip");
               const srcDirPath = join10(dbPath, "src");
-              options["source-archive"] = existsSync6(srcZipPath) ? srcZipPath : srcDirPath;
+              if (existsSync6(srcZipPath)) {
+                options["source-archive"] = srcZipPath;
+              } else if (existsSync6(srcDirPath)) {
+                options["source-archive"] = srcDirPath;
+              } else {
+                delete options.database;
+                throw new Error(
+                  `CodeQL database at "${dbPath}" does not contain a source archive (expected "src.zip" file or "src" directory).`
+                );
+              }
               delete options.database;
             }
             break;
@@ -187590,7 +187599,12 @@ function registerCLITool(server, definition) {
           }
           let dbLock;
           if (name === "codeql_database_analyze" && positionalArgs.length > 0) {
-            dbLock = acquireDatabaseLock(positionalArgs[0]);
+            let lockKey = resolve4(positionalArgs[0]);
+            try {
+              lockKey = realpathSync(lockKey);
+            } catch {
+            }
+            dbLock = acquireDatabaseLock(lockKey);
             await dbLock.ready;
           }
           try {
@@ -190377,7 +190391,7 @@ var codeqlResolveTestsTool = {
 };
 
 // src/tools/codeql/search-ql-code.ts
-import { closeSync as closeSync2, createReadStream as createReadStream3, fstatSync as fstatSync2, lstatSync, openSync as openSync2, readdirSync as readdirSync8, readFileSync as readFileSync12, realpathSync } from "fs";
+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";
 init_logger();
@@ -190407,7 +190421,7 @@ function collectFiles(paths, extensions, fileCount) {
       if (SKIP_DIRS2.has(basename8(p))) return;
       let realPath;
       try {
-        realPath = realpathSync(p);
+        realPath = realpathSync2(p);
       } catch {
         return;
       }
@@ -194004,7 +194018,7 @@ function registerQueryResultsCacheCompareTool(server) {
         for (const e of dbEntries) {
           if (e.resultCount != null) {
             totalResultCount += e.resultCount;
-          } else {
+          } else if (e.outputFormat.includes("sarif")) {
             try {
               const content = store.getCacheContent(e.cacheKey);
               if (content) {
@@ -194046,7 +194060,7 @@ init_package_paths();
 init_logger();
 import_dotenv.default.config({ path: resolve14(packageRootDir, ".env"), quiet: true });
 var PACKAGE_NAME = "codeql-development-mcp-server";
-var VERSION = "2.25.1-next.1";
+var VERSION = "2.25.1-next.2";
 async function startServer(mode = "stdio") {
   logger.info(`Starting CodeQL Development MCP McpServer v${VERSION} in ${mode} mode`);
   const codeqlBinary = resolveCodeQLBinary();
@@ -194143,7 +194157,7 @@ async function main() {
     process.exit(1);
   }
 }
-var scriptPath = process.argv[1] ? realpathSync2(resolve14(process.argv[1])) : void 0;
+var scriptPath = process.argv[1] ? realpathSync3(resolve14(process.argv[1])) : void 0;
 if (scriptPath && import.meta.url === pathToFileURL5(scriptPath).href) {
   main();
 }

diff --git a/server/dist/codeql-development-mcp-server.js.map b/server/dist/codeql-development-mcp-server.js.map
diff --git a/server/package.json b/server/package.json
@@ -1,6 +1,6 @@
 {
   "name": "codeql-development-mcp-server",
-  "version": "2.25.1-next.1",
+  "version": "2.25.1-next.2",
   "description": "An MCP server supporting LLM requests for CodeQL development tools and resources.",
   "main": "dist/codeql-development-mcp-server.js",
   "type": "module",

diff --git a/server/ql/actions/tools/src/codeql-pack.yml b/server/ql/actions/tools/src/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-actions-tools-src
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 description: 'Queries for codeql-development-mcp-server tools for actions language'
 library: false
 dependencies:

diff --git a/server/ql/actions/tools/test/codeql-pack.yml b/server/ql/actions/tools/test/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-actions-tools-test
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 dependencies:
   advanced-security/ql-mcp-actions-tools-src: ${workspace}
 extractor: actions
diff --git a/server/ql/cpp/tools/src/codeql-pack.yml b/server/ql/cpp/tools/src/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-cpp-tools-src
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 description: 'Queries for codeql-development-mcp-server tools for cpp language'
 library: false
 dependencies:

diff --git a/server/ql/cpp/tools/test/codeql-pack.yml b/server/ql/cpp/tools/test/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-cpp-tools-test
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 dependencies:
   advanced-security/ql-mcp-cpp-tools-src: ${workspace}
 extractor: cpp

diff --git a/server/ql/csharp/tools/src/codeql-pack.yml b/server/ql/csharp/tools/src/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-csharp-tools-src
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 description: 'Queries for codeql-development-mcp-server tools for csharp language'
 library: false
 dependencies:

diff --git a/server/ql/csharp/tools/test/codeql-pack.yml b/server/ql/csharp/tools/test/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-csharp-tools-test
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 dependencies:
   advanced-security/ql-mcp-csharp-tools-src: ${workspace}
 extractor: csharp

diff --git a/server/ql/go/tools/src/codeql-pack.yml b/server/ql/go/tools/src/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-go-tools-src
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 description: 'Queries for codeql-development-mcp-server tools for go language'
 library: false
 dependencies:

diff --git a/server/ql/go/tools/test/codeql-pack.yml b/server/ql/go/tools/test/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-go-tools-test
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 dependencies:
   advanced-security/ql-mcp-go-tools-src: ${workspace}
 extractor: go

diff --git a/server/ql/java/tools/src/codeql-pack.yml b/server/ql/java/tools/src/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-java-tools-src
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 description: 'Queries for codeql-development-mcp-server tools for java language'
 library: false
 dependencies:

diff --git a/server/ql/java/tools/test/codeql-pack.yml b/server/ql/java/tools/test/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-java-tools-test
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 dependencies:
   advanced-security/ql-mcp-java-tools-src: ${workspace}
 extractor: java

diff --git a/server/ql/javascript/tools/src/codeql-pack.yml b/server/ql/javascript/tools/src/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-javascript-tools-src
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 description: 'Queries for codeql-development-mcp-server tools for javascript language'
 library: false
 dependencies:

diff --git a/server/ql/javascript/tools/test/codeql-pack.yml b/server/ql/javascript/tools/test/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-javascript-tools-test
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 dependencies:
   advanced-security/ql-mcp-javascript-tools-src: ${workspace}
 extractor: javascript

diff --git a/server/ql/python/tools/src/codeql-pack.yml b/server/ql/python/tools/src/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-python-tools-src
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 description: 'Queries for codeql-development-mcp-server tools for python language'
 library: false
 dependencies:

diff --git a/server/ql/python/tools/test/codeql-pack.yml b/server/ql/python/tools/test/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-python-tools-test
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 dependencies:
   advanced-security/ql-mcp-python-tools-src: ${workspace}
 extractor: python

diff --git a/server/ql/ruby/tools/src/codeql-pack.yml b/server/ql/ruby/tools/src/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-ruby-tools-src
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 description: 'Queries for codeql-development-mcp-server tools for ruby language'
 library: false
 dependencies:

diff --git a/server/ql/ruby/tools/test/codeql-pack.yml b/server/ql/ruby/tools/test/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-ruby-tools-test
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 dependencies:
   advanced-security/ql-mcp-ruby-tools-src: ${workspace}
 extractor: ruby

diff --git a/server/ql/rust/tools/src/codeql-pack.yml b/server/ql/rust/tools/src/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-rust-tools-src
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 description: 'Queries for codeql-development-mcp-server tools for rust language'
 library: false
 dependencies:

diff --git a/server/ql/rust/tools/test/codeql-pack.yml b/server/ql/rust/tools/test/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-rust-tools-test
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 dependencies:
   advanced-security/ql-mcp-rust-tools-src: ${workspace}
 extractor: rust

diff --git a/server/ql/swift/tools/src/codeql-pack.yml b/server/ql/swift/tools/src/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-swift-tools-src
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 description: 'Queries for codeql-development-mcp-server tools for swift language'
 library: false
 dependencies:

diff --git a/server/ql/swift/tools/test/codeql-pack.yml b/server/ql/swift/tools/test/codeql-pack.yml
@@ -1,5 +1,5 @@
 name: advanced-security/ql-mcp-swift-tools-test
-version: 2.25.1-next.1
+version: 2.25.1-next.2
 dependencies:
   advanced-security/ql-mcp-swift-tools-src: ${workspace}
 extractor: swift

diff --git a/server/src/codeql-development-mcp-server.ts b/server/src/codeql-development-mcp-server.ts
@@ -34,7 +34,7 @@ import { logger } from './utils/logger';
 dotenv.config({ path: resolve(packageRootDir, '.env'), quiet: true });
 
 const PACKAGE_NAME = 'codeql-development-mcp-server';
-const VERSION = '2.25.1-next.1';
+const VERSION = '2.25.1-next.2';
 
 /**
  * Start the MCP server