feat(server): add diff-informed & overlay analysis `ql-mcp` primitives by data-douser · Pull Request #304 · advanced-security/codeql-development-mcp-server

data-douser · 2026-06-20T16:03:54Z

Summary

Adds first-class CodeQL diff-informed analysis and overlay database support to the MCP server, plus fixes surfaced while validating the features end-to-end against the SAP UI5 js/ui5-xss query.

Changes

Tools

codeql_database_create — add overlay-base, overlay-changes, cache-cleanup, and extractorEnv (KEY=VALUE extractor env vars, keys restricted to LGTM_ / CODEQL_EXTRACTOR_) so framework databases such as SAP UI5 (LGTM_INDEX_XML_MODE=ALL) can be built via the tool.
codeql_database_analyze / codeql_query_run — add evaluate-as-overlay and cache-at-frontier.
codeql_database_analyze — default --rerun on when model packs are requested, so model-pack changes are not masked by a stale cached BQRS (pass rerun: false to opt out).
codeql_test_run — add check-diff-informed and evaluate-as-overlay.

Plumbing

executeCodeQLCommand accepts an optional env argument (forces a fresh process).
parseExtractorEnv validates and allowlists extractor keys.

Prompt & Resources

New diff_informed_analysis_workflow prompt.
New resources codeql://learning/diff-informed-analysis and codeql://guides/overlay-databases.
Documents the local diff-range mechanism (restrictAlertsTo data extension activated via --model-packs) and removes the prior incorrect claim that a diff range cannot be supplied locally.

Docs & Tests

Sync server-tools / server-prompts / server-overview resources and docs/ql-mcp/resources.md; update CHANGELOG.md.
Add unit tests for the new tool params, parseExtractorEnv, the analyze auto-rerun behavior, the new prompt, and the new resources.
Update .prettierignore to exclude the perf-reports/ directory from lint.

Testing

Full server build + lint + test green (1550 server tests).
Validated end-to-end against js/ui5-xss on the ui5-juice-shop app: overlay analysis ~13% per-change eval improvement; diff-informed ~0% (query is framework-modeling-bound).

Related Issues

VS Code extension: MCP workflow prompts cannot target queries outside the first workspace folder #299 — extension configuration for extractor env vars
codeql_bqrs_decode: singular file argument is rejected; tool requires files (array) #301 — overlay analysis follow-up

Add first-class CodeQL "diff-informed analysis" and "overlay database" support to the MCP server, plus fixes surfaced while validating the features end-to-end against the SAP UI5 `js/ui5-xss` query. Tools: - codeql_database_create: add overlay-base, overlay-changes, cache-cleanup, and extractorEnv (KEY=VALUE extractor env vars, keys restricted to LGTM_/CODEQL_EXTRACTOR_) so framework databases such as SAP UI5 (LGTM_INDEX_XML_MODE=ALL) can be built via the tool. - codeql_database_analyze / codeql_query_run: add evaluate-as-overlay and cache-at-frontier. - codeql_database_analyze: default --rerun on when model packs are requested so model-pack changes are not masked by a stale cached BQRS (pass rerun: false to opt out). - codeql_test_run: add check-diff-informed and evaluate-as-overlay. Plumbing: - executeCodeQLCommand accepts an optional env argument (forces a fresh process); parseExtractorEnv validates and allowlists extractor keys. Prompt & resources: - New diff_informed_analysis_workflow prompt. - New resources codeql://learning/diff-informed-analysis and codeql://guides/overlay-databases. - Document the local diff-range mechanism (restrictAlertsTo data extension activated via --model-packs) and remove the prior incorrect claim that a diff range cannot be supplied locally. Docs & tests: - Sync server-tools/server-prompts/server-overview resources and docs/ql-mcp/resources.md; update CHANGELOG. - Add unit tests for the new tool params, parseExtractorEnv, the analyze auto-rerun behavior, the new prompt, and the new resources. - Update .prettierignore to ignore "perf-reports/" directory from lint.

Copilot

Pull request overview

Adds diff-informed (incremental) analysis and overlay-database support to the CodeQL Development MCP Server by extending CodeQL CLI tool schemas, plumbing extractor env injection into fresh CLI processes, and publishing new workflow documentation (prompt + resources) with accompanying tests.

Changes:

Extend CodeQL CLI tool definitions (database create/analyze, query run, test run) with overlay/diff-informed related parameters and support extractor-scoped env injection.
Add new workflow prompt diff_informed_analysis_workflow plus new resources for diff-informed analysis and overlay databases, and register them with the server.
Add unit tests covering new schemas/behavior and update docs/changelog to reflect the new capabilities.

Show a summary per file

File	Description
server/test/src/tools/codeql/test-run.test.ts	Adds unit tests for new `codeql_test_run` parameters.
server/test/src/tools/codeql/query-run.test.ts	Adds unit tests for new `codeql_query_run` overlay parameters.
server/test/src/tools/codeql/database-create.test.ts	Adds unit tests for overlay DB + `extractorEnv` params on `codeql_database_create`.
server/test/src/tools/codeql/database-analyze.test.ts	Adds unit tests for overlay evaluation params on `codeql_database_analyze`.
server/test/src/prompts/workflow-prompts.test.ts	Validates new prompt schema + updates prompt-name count expectation.
server/test/src/prompts/prompt-loader.test.ts	Ensures new prompt template is bundled.
server/test/src/lib/resources.test.ts	Tests for new embedded resource getters.
server/test/src/lib/cli-tool-registry.test.ts	Tests `parseExtractorEnv`, extractor env forwarding, and analyze auto-`rerun` behavior.
server/src/tools/codeql/test-run.ts	Adds `check-diff-informed` and `evaluate-as-overlay` tool parameters + example.
server/src/tools/codeql/query-run.ts	Adds `evaluate-as-overlay` and `cache-at-frontier` tool parameters + example.
server/src/tools/codeql/database-create.ts	Adds overlay DB flags + `extractorEnv` parameter + overlay/UI5 examples.
server/src/tools/codeql/database-analyze.ts	Adds overlay-evaluation flags + example.
server/src/tools/codeql-resources.ts	Registers two new MCP resources (diff-informed analysis, overlay DBs).
server/src/resources/server-tools.md	Documents the new tool capabilities and adds related resource links.
server/src/resources/server-prompts.md	Adds the new workflow prompt to the prompts reference and categories.
server/src/resources/server-overview.md	Adds new resources to the overview resource table.
server/src/resources/overlay-databases.md	New guide resource describing overlay database creation/evaluation.
server/src/resources/diff-informed-analysis.md	New guide resource describing diff-informed opt-in, validation, and local diff-range injection.
server/src/prompts/workflow-prompts.ts	Adds prompt schema + prompt registration/handler for diff-informed workflow.
server/src/prompts/prompt-loader.ts	Bundles the new prompt template.
server/src/prompts/diff-informed-analysis-workflow.prompt.md	New workflow prompt content for diff-informed + overlay workflows.
server/src/lib/resources.ts	Adds resource getters for the new embedded markdown resources.
server/src/lib/cli-tool-registry.ts	Adds extractor env parsing/allowlist + model-pack auto-`rerun` behavior + env forwarding.
server/src/lib/cli-executor.ts	Extends `executeCodeQLCommand` with optional env and forces fresh process when env is set.
server/dist/codeql-development-mcp-server.js	Regenerates bundled distribution output with new tools/resources/prompts.
docs/ql-mcp/resources.md	Adds the two new static resources to docs.
CHANGELOG.md	Adds Unreleased entries describing the new diff-informed/overlay functionality.
.prettierignore	Excludes `perf-reports/` from Prettier formatting.

Copilot's findings

Files reviewed: 27/29 changed files
Comments generated: 2

Copilot · 2026-06-20T16:17:17Z


 - **Second supply-chain hardening pass for release workflows** — All release-generating workflows now opt out of every cache step, pin runners, strictly validate version inputs, and refuse mid-publish cancellation. See **Security** below for the full inventory. ([#279](https://github.com/advanced-security/codeql-development-mcp-server/pull/279))
 - **First-class Rust toolchain support in CI** — `setup-codeql-environment` now installs a pinned Rust toolchain (default `1.80.0`, via a pinned `dtolnay/rust-toolchain` action with `rust-src`) for any matrix entry that includes `rust`, so the CodeQL rust extractor can expand `format!` / `println!` / `vec!` macros against the standard library on Linux runners. The `query-unit-tests.yml` workflow now passes `languages: ${{ matrix.language }}` so each matrix entry only installs its own runtime. ([#279](https://github.com/advanced-security/codeql-development-mcp-server/pull/279))
+- **Diff-informed analysis & overlay database support** — New MCP primitives help developers make data-flow queries diff-informed (incremental) and build/evaluate overlay databases. A new `diff_informed_analysis_workflow` prompt and two reference resources walk through the query-side opt-in (`observeDiffInformedIncrementalMode`, `getASelectedSourceLocation`, `getASelectedSinkLocation`) and validation via `codeql test run --check-diff-informed`, while `codeql_database_create`, `codeql_database_analyze`, `codeql_query_run`, and `codeql_test_run` gained the corresponding advanced/experimental CLI parameters.


Added the PR link in commit fix: add PR link to Highlights entry in CHANGELOG (#304).

…-analysis/1 # Conflicts: # server/dist/codeql-development-mcp-server.js.map

github-actions · 2026-06-20T16:10:43Z

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Nathan Randall <70299490+data-douser@users.noreply.github.com>

Copilot

Copilot's findings

Files reviewed: 27/29 changed files
Comments generated: 6


 - **Second supply-chain hardening pass for release workflows** — All release-generating workflows now opt out of every cache step, pin runners, strictly validate version inputs, and refuse mid-publish cancellation. See **Security** below for the full inventory. ([#279](https://github.com/advanced-security/codeql-development-mcp-server/pull/279))
 - **First-class Rust toolchain support in CI** — `setup-codeql-environment` now installs a pinned Rust toolchain (default `1.80.0`, via a pinned `dtolnay/rust-toolchain` action with `rust-src`) for any matrix entry that includes `rust`, so the CodeQL rust extractor can expand `format!` / `println!` / `vec!` macros against the standard library on Linux runners. The `query-unit-tests.yml` workflow now passes `languages: ${{ matrix.language }}` so each matrix entry only installs its own runtime. ([#279](https://github.com/advanced-security/codeql-development-mcp-server/pull/279))
+- **Diff-informed analysis & overlay database support** — New MCP primitives help developers make data-flow queries diff-informed (incremental) and build/evaluate overlay databases. A new `diff_informed_analysis_workflow` prompt and two reference resources walk through the query-side opt-in (`observeDiffInformedIncrementalMode`, `getASelectedSourceLocation`, `getASelectedSinkLocation`) and validation via `codeql test run --check-diff-informed`, while `codeql_database_create`, `codeql_database_analyze`, `codeql_query_run`, and `codeql_test_run` gained the corresponding advanced/experimental CLI parameters.


+
+| Prompt                            | Description                                                                                                                                                                                                                                        |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `diff_informed_analysis_workflow` | End-to-end workflow to make a data-flow query diff-informed, validate it with `codeql test run --check-diff-informed`, and build/evaluate overlay databases for changed files. Requires `language`; optionally accepts `queryPath` and `database`. |


+| `codeql://learning/diff-informed-analysis` | How to make data-flow queries diff-informed (incremental) and validate them locally with `--check-diff-informed`.                |
+| `codeql://guides/overlay-databases`        | How to build and evaluate overlay databases (`overlay-base`, `overlay-changes`, `cache-cleanup=overlay`, `evaluate-as-overlay`). |


+| `codeql_database_create`  | Added overlay-database parameters `overlay-base` (build a database usable as an overlay base), `overlay-changes` (build an overlay from a JSON changes file), and `cache-cleanup` (`clear`/`trim`/`fit`/`overlay`). Added an `extractorEnv` parameter for passing extractor environment variables (keys restricted to `LGTM_`/`CODEQL_EXTRACTOR_`), e.g. `LGTM_INDEX_XML_MODE=ALL` to extract SAP UI5 XML views. |
+| `codeql_database_analyze` | Added overlay-evaluation parameters `evaluate-as-overlay` and `cache-at-frontier`. Now defaults `--rerun` on when model packs are requested, so model-pack changes are not masked by a stale cached BQRS (pass `rerun: false` to opt out).                                                                                                                                                                       |
+| `codeql_query_run`        | Added overlay-evaluation parameters `evaluate-as-overlay` and `cache-at-frontier`.                                                                                                                                                                                                                                                                                                                               |
+| `codeql_test_run`         | Added `check-diff-informed` (validate diff-informed query filtering) and `evaluate-as-overlay`.                                                                                                                                                                                                                                                                                                                  |


+
+#### MCP Server Resources & Prompts
+
+- **Diff-informed analysis docs now describe local diff-range injection** — The `codeql://learning/diff-informed-analysis` resource and the `diff_informed_analysis_workflow` prompt previously stated that a diff range could not be supplied locally. They now document the real mechanism: populate the `restrictAlertsTo` extensible predicate (`codeql/util`) via a data-extension pack and activate it with `--model-packs` (placing it only on `--additional-packs` resolves but does not apply it).


 import learningDataExtensionsContent from '../resources/learning-data-extensions.md';
 import dataflowMigrationContent from '../resources/dataflow-migration-v1-to-v2.md';
+import diffInformedAnalysisContent from '../resources/diff-informed-analysis.md';
 import learningQueryBasicsContent from '../resources/learning-query-basics.md';
+import overlayDatabasesContent from '../resources/overlay-databases.md';


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

Copilot AI review requested due to automatic review settings June 20, 2026 16:03

Copilot started reviewing on behalf of data-douser June 20, 2026 16:04 View session

Sync server/dist/ after rebuild

199f10f

Copilot AI reviewed Jun 20, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into feature/diff-informed…

4e4ea28

…-analysis/1 # Conflicts: # server/dist/codeql-development-mcp-server.js.map

Copilot AI review requested due to automatic review settings June 20, 2026 16:10

Copilot started reviewing on behalf of data-douser June 20, 2026 16:10 View session

Potential fix for pull request finding

14d121d

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Nathan Randall <70299490+data-douser@users.noreply.github.com>

data-douser self-assigned this Jun 20, 2026

data-douser added enhancement New feature or request javascript Pull requests that update javascript code server testing labels Jun 20, 2026

Copilot started work on behalf of data-douser June 20, 2026 16:13 View session

Copilot AI reviewed Jun 20, 2026

View reviewed changes

fix: add PR link to Highlights entry in CHANGELOG (#304)

4ac9589

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

Copilot AI review requested due to automatic review settings June 20, 2026 16:17

data-douser removed the request for review from Copilot June 20, 2026 16:17

Copilot finished work on behalf of data-douser June 20, 2026 16:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(server): add diff-informed & overlay analysis `ql-mcp` primitives#304

feat(server): add diff-informed & overlay analysis `ql-mcp` primitives#304
data-douser wants to merge 5 commits into
mainfrom
feature/diff-informed-analysis/1

data-douser commented Jun 20, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jun 20, 2026

Uh oh!

Uh oh!

github-actions Bot commented Jun 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		\| `codeql://learning/diff-informed-analysis` \| How to make data-flow queries diff-informed (incremental) and validate them locally with `--check-diff-informed`. \|
		\| `codeql://guides/overlay-databases` \| How to build and evaluate overlay databases (`overlay-base`, `overlay-changes`, `cache-cleanup=overlay`, `evaluate-as-overlay`). \|


		#### MCP Server Resources & Prompts

		- Diff-informed analysis docs now describe local diff-range injection — The `codeql://learning/diff-informed-analysis` resource and the `diff_informed_analysis_workflow` prompt previously stated that a diff range could not be supplied locally. They now document the real mechanism: populate the `restrictAlertsTo` extensible predicate (`codeql/util`) via a data-extension pack and activate it with `--model-packs` (placing it only on `--additional-packs` resolves but does not apply it).

Conversation

data-douser commented Jun 20, 2026

Summary

Changes

Tools

Plumbing

Prompt & Resources

Docs & Tests

Testing

Related Issues

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Copilot AI Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Jun 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Dependency Review

Scanned Files

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Jun 20, 2026 •

edited

Loading