Updates for v2.25.1-next.2 prerelease (#204)

Author: data-douser

CHANGELOG.md

@@ -20,24 +20,32 @@ _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 recent evaluation sessions** — 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))
+- **SARIF analysis tools and cache model improvements** — Added `sarif_list_rules`, `sarif_extract_rule`, `sarif_rule_to_markdown`, `sarif_compare_alerts`, and `sarif_diff_runs` tools for rule-level SARIF extraction, Mermaid dataflow visualization, alert overlap analysis, and cross-run behavioral comparison. Extended cache model with `rule_id` and `run_id` columns; added `ruleId` filter to all cache tools; auto-decompose `database_analyze` SARIF into per-rule cache entries. Added `compare_overlapping_alerts` prompt and updated all SARIF-related prompts with tool recommendations. Extracted shared libraries for database metadata and SARIF rule name resolution. ([#204](https://github.com/advanced-security/codeql-development-mcp-server/pull/204))
 
 ### Added
 
 #### MCP Server Tools
 
-| Tool                                                                                                                     | Description                                                                                                                                                                                            |
-| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `annotation_create`, `annotation_get`, `annotation_list`, `annotation_update`, `annotation_delete`, `annotation_search`  | General-purpose annotation tools for creating, managing, and searching notes and bookmarks on analysis entities. ([#169](https://github.com/advanced-security/codeql-development-mcp-server/pull/169)) |
-| `audit_store_findings`, `audit_list_findings`, `audit_add_notes`, `audit_clear_repo`                                     | Repo-keyed audit tools for MRVA finding management and triage workflows. ([#169](https://github.com/advanced-security/codeql-development-mcp-server/pull/169))                                         |
-| `query_results_cache_lookup`, `query_results_cache_retrieve`, `query_results_cache_clear`, `query_results_cache_compare` | Query result cache tools for lookup, subset retrieval, cache clearing, and cross-database comparison. ([#169](https://github.com/advanced-security/codeql-development-mcp-server/pull/169))            |
+| Tool                                                                                                                     | Description                                                                                                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `annotation_create`, `annotation_get`, `annotation_list`, `annotation_update`, `annotation_delete`, `annotation_search`  | General-purpose annotation tools for creating, managing, and searching notes and bookmarks on analysis entities. ([#169](https://github.com/advanced-security/codeql-development-mcp-server/pull/169))                                          |
+| `audit_store_findings`, `audit_list_findings`, `audit_add_notes`, `audit_clear_repo`                                     | Repo-keyed audit tools for MRVA finding management and triage workflows. ([#169](https://github.com/advanced-security/codeql-development-mcp-server/pull/169))                                                                                  |
+| `query_results_cache_lookup`, `query_results_cache_retrieve`, `query_results_cache_clear`, `query_results_cache_compare` | Query result cache tools for lookup, subset retrieval, cache clearing, and cross-database comparison. ([#169](https://github.com/advanced-security/codeql-development-mcp-server/pull/169))                                                     |
+| `sarif_list_rules`, `sarif_extract_rule`, `sarif_rule_to_markdown`, `sarif_compare_alerts`, `sarif_diff_runs`            | SARIF analysis tools for rule discovery, per-rule extraction, Mermaid dataflow visualization, alert overlap comparison, and cross-run behavioral diffing. ([#204](https://github.com/advanced-security/codeql-development-mcp-server/pull/204)) |
 
 #### MCP Server Resources
 
 | URI                           | Description                                                                                                                                                                       |
 | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `codeql://languages/rust/ast` | Rust AST reference resource with verified accessor predicates for CodeQL query development. ([#195](https://github.com/advanced-security/codeql-development-mcp-server/pull/195)) |
 
+#### MCP Server Prompts
+
+| Prompt                       | Description                                                                                                                                                                                                                                          |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `compare_overlapping_alerts` | Multi-SARIF alert comparison workflow: compares alerts across rules, files, runs, databases, or CodeQL versions with 8-step guided analysis using SARIF tools. ([#204](https://github.com/advanced-security/codeql-development-mcp-server/pull/204)) |
+
 #### CodeQL Query Packs
 
 | Pack            | Description                                                                                                                                                                                 |
@@ -53,15 +61,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 +85,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
 

client/integration-tests/primitives/prompts/compare_overlapping_alerts/basic_comparison/after/monitoring-state.json

@@ -0,0 +1,10 @@
+{
+  "sessions": [
+    {
+      "expectedContentPatterns": [
+        "sarif_list_rules",
+        "sarif_compare_alerts"
+      ]
+    }
+  ]
+}

client/integration-tests/primitives/prompts/compare_overlapping_alerts/basic_comparison/before/monitoring-state.json

@@ -0,0 +1,6 @@
+{
+  "sessions": [],
+  "parameters": {
+    "sarifPathA": "client/integration-tests/primitives/tools/sarif_extract_rule/extract_sql_injection/before/test-input.sarif"
+  }
+}

client/integration-tests/primitives/tools/codeql_bqrs_info/json_format/test-config.json

@@ -1,7 +1,7 @@
 {
   "toolName": "codeql_bqrs_info",
   "arguments": {
-    "files": ["client/integration-tests/primitives/tools/codeql_bqrs_info/json_format/before/results.bqrs"],
+    "file": "client/integration-tests/primitives/tools/codeql_bqrs_info/json_format/before/results.bqrs",
     "format": "json"
   }
 }

client/integration-tests/primitives/tools/sarif_compare_alerts/sink_overlap/README.md

@@ -0,0 +1,21 @@
+# Integration Test: sarif_compare_alerts - sink_overlap
+
+## Purpose
+
+Validates that the `sarif_compare_alerts` tool correctly compares code locations
+between two SARIF alerts from different rules to detect sink-level overlap.
+
+## Inputs
+
+- `test-input.sarif`: A multi-rule SARIF file where `js/sql-injection` result 0
+  and `js/missing-rate-limiting` result 0 both reference `src/routes/users.js`
+  but at different line ranges — so they should NOT have sink overlap.
+
+## Expected Behavior
+
+The tool returns a comparison result with:
+
+- `overlaps`: false (the two alerts are at different lines in the same file)
+- `overlapMode`: "sink"
+- Alert details for both A and B (ruleId, location, message)
+- Empty `sharedLocations` array

client/integration-tests/primitives/tools/sarif_compare_alerts/sink_overlap/after/monitoring-state.json

@@ -0,0 +1,5 @@
+{
+  "toolName": "sarif_compare_alerts",
+  "success": true,
+  "description": "Successfully compared alert locations for sink overlap"
+}