Updates for v2.25.1-next.2 prerelease#204
Merged
data-douser merged 23 commits intomainfrom Apr 1, 2026
Merged
Conversation
Bug 1: Improve bqrs_interpret -t parameter docs, add database param Bug 2: Fix query_results_cache_compare to derive resultCount from SARIF Bug 3: Include category field in annotation_search FTS matching Bug 4: Add findingId as primary lookup for audit_add_notes Bug 5: Change bqrs_info files param to single file string Design 2: Serialize concurrent database_analyze on same database Design 3: Already implemented (cacheKey/queryName in cache_lookup) Design 5: Auto-enable annotation tools in VSIX with new setting Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/0d52c27d-21be-49ea-bf90-c8fb6f50a3da Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>
Add cacheDatabaseAnalyzeResults() to auto-cache SARIF output from database_analyze into the query results cache. Update README with new enableAnnotationTools setting documentation. Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/0d52c27d-21be-49ea-bf90-c8fb6f50a3da Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>
- Fix databaseLocks memory leak: clean up map entries on release - Fix bqrs_interpret source-archive: prefer src.zip over src/ - Fix cacheDatabaseAnalyzeResults: use resolved database path - Fix annotation category search: add COLLATE NOCASE - Fix resultCount: use ?? 0 instead of ?? null (two locations) - Fix VS Code tests: wrap mock mutations in try/finally - Fix codeql_bqrs_info integration tests: files → file in test runner, monitoring runner, and test-config.json Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/52936c89-89e6-4b1d-8c0e-12dcb9ad2388 Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>
Prep for the v2.25.1-next.2 release as a hotfix for the v2.25.1-next.1 release.
…se metadata When the `database` parameter is provided to `codeql_bqrs_interpret`, read `codeql-database.yml` and extract `sourceLocationPrefix` to auto-set `--source-location-prefix`. This fixes the "Missing required argument(s): --source-location-prefix" error reported in v2.25.1-next.2 evaluation. TDD: Added 2 handler behavior tests in cli-tool-registry.test.ts and 9 definition tests in bqrs-interpret.test.ts. Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/6ff74bab-c637-4e18-a5dc-92e3065583f4 Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>
…et handling Some MCP clients send the file parameter as a JSON-encoded array string like '["/path/to/file.bqrs"]' or as an actual array instead of a plain string. The handler now defensively detects both cases and extracts the clean file path. TDD: Added 2 regression tests for JSON-encoded array strings and actual array values passed as the file parameter. Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/6ff74bab-c637-4e18-a5dc-92e3065583f4 Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>
…ngId - CHANGELOG: correct 'v2.25.1-next.1' → 'v2.25.1-next.2' evaluation ref - audit-tools: use explicit `!= null` check for findingId clarity Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/6ff74bab-c637-4e18-a5dc-92e3065583f4 Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>
…limit; fix env-builder to not overwrite pre-existing vars TDD tests for Design 3 (query_results_cache_lookup): - Exact cacheKey lookup returns metadata including resultCount - Non-existent cacheKey returns cached:false - Language-only filter correctly returns matching entries - databasePath filter returns matching entries - limit parameter restricts returned entries Environment builder fix (addresses PR review): - Only set ENABLE_ANNOTATION_TOOLS when not already defined in env - Only set MONITORING_STORAGE_LOCATION when not already defined in env - Added test: additionalEnv MONITORING_STORAGE_LOCATION override is preserved Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/97593c7f-7fd2-48f4-9f4c-0e97dfa47902 Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>
…log clarity - BQRS file param: check `file !== undefined` instead of truthiness, validate with `trim()` to catch whitespace-only strings - bqrs_interpret database: always delete key from options regardless of value; fail fast on empty/whitespace-only string with clear error - environment-builder: check `process.env` for inherited values instead of the freshly-constructed `env` object (which is always empty) - result-processor: log "result count unknown" instead of "0 results" when resultCount is null - Added tests: empty string file, whitespace file, empty database param, process.env ENABLE_ANNOTATION_TOOLS preservation Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/f9deedbc-dbc0-4432-9d7b-775d1a9f624f Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>
Add sarif_extract_rule, sarif_rule_to_markdown, and sarif_compare_alerts tools with shared library (sarif-utils.ts, 34 unit tests). Extend cache model with rule_id/run_id columns and ruleId filter on all cache tools. Decompose database_analyze SARIF into per-rule cache entries. Add compare_overlapping_alerts prompt for classifying alert overlap as redundant, complementary, or false. Add extensions to SarifRunSchema. Include 3 client integration tests with shared SARIF fixture and test runner support for SARIF tools. Update e2e assertion (14 → 17 opt-in tools). Update server-tools.md and server-prompts.md documentation.
…odeQL CLI version - Add public getCliVersion() to CliResolver with version parsing - Add version-aware pack download to PackInstaller using codeql pack download - Add CLI_VERSION_TO_PACK_VERSION mapping for backwards compatibility (v2.24.0 - v2.25.1) - Add autoDownloadPacks extension config setting (default: true) - Wire autoDownloadPacks config into extension activation - Add comprehensive unit tests for new functionality - Update extension settings documentation Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/c79f4c66-0204-436a-85bb-014f590878a1 Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>
…st line Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/c79f4c66-0204-436a-85bb-014f590878a1 Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>
data-douser
added
bug
![github-license-compliance[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
Contributor
Dependency ReviewThe following issues were found:
Snapshot WarningsEnsure that dependencies are being submitted on PR branches and consider enabling retry-on-snapshot-warnings. See the documentation for more information and troubleshooting advice. License Issuespackage-lock.json
OpenSSF ScorecardScorecard details
Scanned Files
|
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the v2.25.1-next.2 prerelease with multiple evaluation-driven fixes and feature additions across the MCP server, VS Code extension, and integration tests—most notably improved BQRS tool schemas, query-results caching enhancements (including database_analyze auto-caching + ruleId support), and new SARIF analysis tools/prompts.
Changes:
- Fix/align several CodeQL CLI tool schemas and handlers (
bqrs_interpret,bqrs_info,audit_add_notes) and extend cache tools (ruleId, exactcacheKeylookup, improved compare semantics). - Add SARIF analysis tools + a new workflow prompt (
compare_overlapping_alerts) and wire them into server registration and test coverage. - Improve VS Code extension pack installation for mismatched CLI versions (
autoDownloadPacks) and enable annotation/audit/cache tooling by default via environment builder behavior.
Reviewed changes
Copilot reviewed 107 out of 110 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| server/test/src/tools/codeql/bqrs-interpret.test.ts | Adds schema-focused tests for codeql_bqrs_interpret (file/database/t/output/examples). |
| server/test/src/tools/codeql/bqrs-info.test.ts | Updates tests for codeql_bqrs_info parameter rename files→file. |
| server/test/src/tools/cache-tools.test.ts | Adds coverage for cache lookup by cacheKey, filters, limits, and compare resultCount behavior. |
| server/test/src/tools/audit-tools.test.ts | Adds schema and behavior tests for audit_add_notes supporting findingId and optional composite key. |
| server/test/src/prompts/workflow-prompts.test.ts | Updates prompt count expectation for new workflow prompt registration. |
| server/test/src/lib/sqlite-store.test.ts | Adds tests for annotation category search and new cache metadata fields (ruleId, runId) + filtering/clearing by ruleId. |
| server/test/src/lib/result-processor.test.ts | Adds tests for deterministic cache keys and YAML parsing pattern coverage. |
| server/test/src/lib/database-resolver.test.ts | Adds unit tests for database YAML metadata parsing (primaryLanguage, sourceLocationPrefix, etc.). |
| server/src/types/sarif.ts | Extends SARIF schema to allow tool.extensions metadata. |
| server/src/tools/codeql/list-databases.ts | Switches DB YAML parsing to shared readDatabaseMetadata() helper. |
| server/src/tools/codeql/bqrs-interpret.ts | Adds optional database param and improves -t key/value documentation. |
| server/src/tools/codeql/bqrs-info.ts | Fixes schema to accept a single file string (matches CLI). |
| server/src/tools/cache-tools.ts | Adds ruleId filtering/clearing, cacheKey lookup, and updates compare output semantics. |
| server/src/tools/audit-tools.ts | Implements findingId-based lookup for audit_add_notes with composite-key fallback. |
| server/src/resources/server-tools.md | Documents new SARIF analysis tool suite and a results comparison workflow. |
| server/src/resources/server-queries.md | Documents the additional bundled CallGraphFromTo tools query and updates support matrix. |
| server/src/resources/server-prompts.md | Adds compare_overlapping_alerts prompt to prompt reference and describes updated SARIF workflows. |
| server/src/prompts/workflow-prompts.ts | Registers compare_overlapping_alerts prompt + schema and adds it to WORKFLOW_PROMPT_NAMES. |
| server/src/prompts/sarif-rank-true-positives.prompt.md | Adds recommended SARIF tool usage guidance. |
| server/src/prompts/sarif-rank-false-positives.prompt.md | Adds recommended SARIF tool usage guidance. |
| server/src/prompts/run-query-and-summarize-false-positives.prompt.md | Updates workflow to leverage cache lookup + SARIF rule extraction/markdown tooling. |
| server/src/prompts/prompt-loader.ts | Registers the new compare-overlapping-alerts.prompt.md template. |
| server/src/prompts/compare-overlapping-alerts.prompt.md | Adds new workflow prompt content for SARIF overlap comparison. |
| server/src/lib/sqlite-store.ts | Adds safe migrations for rule_id/run_id, supports ruleId filtering/clearing, and includes category in annotation search. |
| server/src/lib/result-processor.ts | Adds ruleId + resultCount capture at cache time, caches database_analyze SARIF outputs, and decomposes multi-rule SARIF into per-rule entries. |
| server/src/lib/database-resolver.ts | Adds shared DB metadata reader/parser (readDatabaseMetadata, parseDatabaseYmlContent). |
| server/src/lib/cli-tool-registry.ts | Fixes BQRS file coercion, adds bqrs_interpret database→source archive/prefix mapping, serializes concurrent database_analyze, and auto-caches analyze results. |
| server/src/codeql-development-mcp-server.ts | Bumps server version to 2.25.1-next.2 and registers SARIF tools. |
| server/src/tools/sarif-tools.ts | Adds SARIF tools registration and handlers (extract_rule, list_rules, markdown rendering, alert compare, run diff). |
| server/ql//tools//codeql-pack.yml | Bumps tools pack versions from 2.25.1-next.1 to 2.25.1-next.2. |
| server/package.json | Bumps server package version to 2.25.1-next.2. |
| package.json | Bumps repo version to 2.25.1-next.2. |
| package-lock.json | Updates lockfile versions for workspace packages to 2.25.1-next.2. |
| extensions/vscode/vitest.config.ts | Excludes dist/** and node_modules/** from VS Code vitest runs. |
| extensions/vscode/test/suite/mcp-tool-e2e.integration.test.ts | Extends E2E tool registration assertions to include SARIF tools. |
| extensions/vscode/test/server/pack-installer.test.ts | Adds tests for version-aware pack download behavior and baseVersion helpers. |
| extensions/vscode/test/extension.test.ts | Updates mocks to support CLI version + extension version queries. |
| extensions/vscode/test/codeql/cli-resolver.test.ts | Adds tests for CLI version caching and parsing behavior. |
| extensions/vscode/test/bridge/environment-builder.test.ts | Adds tests asserting annotation tools enabled-by-default behavior and env override rules. |
| extensions/vscode/src/server/pack-installer.ts | Implements CLI-version-aware tool pack download via codeql pack download + version mapping utilities. |
| extensions/vscode/src/extension.ts | Wires autoDownloadPacks setting into pack installer behavior. |
| extensions/vscode/src/codeql/cli-resolver.ts | Adds CLI version caching (getCliVersion) and robust version parsing. |
| extensions/vscode/src/bridge/environment-builder.ts | Enables annotation/audit/cache tools by default and sets default monitoring storage location. |
| extensions/vscode/README.md | Documents new enableAnnotationTools setting in extension settings table. |
| extensions/vscode/package.json | Bumps VSIX version and adds autoDownloadPacks + enableAnnotationTools settings. |
| docs/vscode/extension.md | Documents autoDownloadPacks in settings table. |
| client/src/lib/monitoring-integration-test-runner.js | Updates tool param wiring (bqrs→file) and adds SARIF tool argument wiring for integration tests. |
| client/src/lib/integration-test-runner.js | Updates codeql_bqrs_info params (files→file) and adds SARIF tool argument wiring. |
| client/package.json | Bumps client package version to 2.25.1-next.2. |
| client/integration-tests/primitives/tools/sarif_rule_to_markdown/render_path_problem/** | Adds new SARIF→markdown integration test fixture and expected state. |
| client/integration-tests/primitives/tools/sarif_list_rules/list_multi_rule/** | Adds new SARIF rule listing integration test fixture and expected state. |
| client/integration-tests/primitives/tools/sarif_extract_rule/extract_sql_injection/** | Adds new SARIF rule extraction integration test fixture and expected state. |
| client/integration-tests/primitives/tools/sarif_diff_runs/diff_changed_results/** | Adds new SARIF diff integration test fixture and expected state. |
| client/integration-tests/primitives/tools/sarif_compare_alerts/sink_overlap/** | Adds new alert overlap integration test fixture and expected state. |
| client/integration-tests/primitives/tools/codeql_bqrs_info/json_format/test-config.json | Updates codeql_bqrs_info integration test args to use file string. |
| client/integration-tests/primitives/prompts/compare_overlapping_alerts/basic_comparison/** | Adds integration test fixture for the new compare_overlapping_alerts prompt. |
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 107 out of 110 changed files in this pull request and generated 5 comments.
Comments suppressed due to low confidence (1)
extensions/vscode/README.md:52
- The settings table doesn’t list the new
codeql-mcp.autoDownloadPacksoption added in this PR, andenableAnnotationToolsnow also gates SARIF analysis tools (sarif_*). Please update this table to includeautoDownloadPacksand clarify the scope ofenableAnnotationToolsso the README matches the extension’s actual configuration surface.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Nathan Randall <70299490+data-douser@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 107 out of 110 changed files in this pull request and generated 4 comments.
Comments suppressed due to low confidence (2)
CHANGELOG.md:36
- This tools table entry still links to an issue (
.../issues/201) rather than the implementing PR, and the link format doesn’t match the changelog’s PR-link convention. Please update it to reference the PR that added these SARIF tools.
| `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. ([#201](https://github.com/advanced-security/codeql-development-mcp-server/issues/201)) |
CHANGELOG.md:48
- This prompt table entry links to an issue (
.../issues/201) instead of a PR. For consistency with the rest of the changelog and to keep the changelog as a merged-change log, please reference the PR that introducedcompare_overlapping_alertsusing the standard([#NNN](.../pull/NNN))format.
| 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. ([#201](https://github.com/advanced-security/codeql-development-mcp-server/issues/201)) |
.../primitives/prompts/compare_overlapping_alerts/basic_comparison/before/monitoring-state.json
Outdated
Show resolved
Hide resolved
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #198.
Closes #201.
Closes #202.
Summary of Changes
This pull request introduces significant new SARIF analysis capabilities, improves caching and concurrency for key tools, and addresses several bugs and usability issues based on recent evaluations. The main highlights include the addition of new SARIF tools for rule-level extraction and alert comparison, enhancements to the cache model and prompt workflows, and multiple bug fixes to improve reliability and correctness.
Outline of Changes
Major new features and enhancements:
SARIF Analysis Tools and Cache Model:
sarif_list_rules,sarif_extract_rule,sarif_rule_to_markdown,sarif_compare_alerts, andsarif_diff_runsfor advanced SARIF rule extraction, visualization, alert overlap analysis, and behavioral comparison. The cache model now includesrule_idandrun_idcolumns, and all cache tools support aruleIdfilter. SARIF output fromdatabase_analyzeis auto-decomposed into per-rule cache entries. ([CHANGELOG.mdL23-R48])compare_overlapping_alertsprompt for multi-SARIF alert comparison workflows, with test coverage and documentation. [1]], [2]], [3]], [4]])Tool and Workflow Improvements:
codeql_bqrs_interpretwith adatabaseparameter mapped to--source-archive, validating the presence ofsrc.ziporsrc. [1]], [2]])codeql_bqrs_infoto use afile(string) parameter instead offiles(array), matching CLI expectations and preventing errors. [1]], [2]], [3]])codeql_database_analyzeto auto-cache results after SARIF output and serialize concurrent calls to the same database using a normalized per-database mutex. [1]], [2]])annotation_searchnow matches the category field case-insensitively usingCOLLATE NOCASE. [1]], [2]])audit_add_notesnow prefersfindingIdas a lookup key, with other fields as optional fallbacks. [1]], [2]])query_results_cache_compareonly parses SARIF content for SARIF-format cache entries, improving efficiency and correctness. [1]], [2]])VS Code Extension:
codeql-mcp.enableAnnotationToolssetting (default:true), which auto-sets relevant environment variables for annotation tools. ([CHANGELOG.mdL57-R79])Bug fixes:
codeql_bqrs_interpretwas unusable through the MCP interface,query_results_cache_comparereported incorrect result counts,annotation_searchignored thecategoryfield,audit_add_notesignoredfindingId, andcodeql_bqrs_infoparameter mismatch caused CLI errors. Also, the database lock key is now normalized to prevent serialization bypass. ([CHANGELOG.mdR88-R93])Integration and test updates:
References:
[1] [2] [3] [4] [5] [6] [7] [8] [9] [10]