Skip to content

Commit 39f1d49

Browse files
data-douserCopilotCopilot
authored
feat(server): add diff-informed & overlay analysis ql-mcp primitives (#304)
* feat(server): add diff-informed & overlay analysis MCP primitives 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. * Sync server/dist/ after rebuild * Potential fix for pull request finding 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> * fix: add PR link to Highlights entry in CHANGELOG (#304) Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com> * harden parseExtractorEnv and add multi-root workspace path resolution Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com> --------- Signed-off-by: Nathan Randall <70299490+data-douser@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
1 parent 27fee42 commit 39f1d49

31 files changed

Lines changed: 1860 additions & 149 deletions

‎.prettierignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ coverage
1717
extensions/vscode/.vscode-test
1818
extensions/vscode/test/fixtures/
1919
node_modules
20+
perf-reports/
2021
query-results*
2122
server/dist/
2223
server/ql/*/tools/src/*.md

‎CHANGELOG.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,23 @@ _Changes on `main` since the latest tagged release that have not yet been includ
1818

1919
- **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))
2020
- **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))
21+
- **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. ([#304](https://github.com/advanced-security/codeql-development-mcp-server/pull/304))
2122

2223
### Added
2324

25+
#### MCP Server Prompts
26+
27+
| Prompt | Description |
28+
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
29+
| `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`. |
30+
31+
#### MCP Server Resources
32+
33+
| Resource | Description |
34+
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
35+
| `codeql://learning/diff-informed-analysis` | How to make data-flow queries diff-informed (incremental) and validate them locally with `--check-diff-informed`. |
36+
| `codeql://guides/overlay-databases` | How to build and evaluate overlay databases (`overlay-base`, `overlay-changes`, `cache-cleanup=overlay`, `evaluate-as-overlay`). |
37+
2438
#### VS Code Extension
2539

2640
- **Built-in portable custom agents** — The extension now ships two `.agent.md` custom agents (`ql-mcp-ext-query-developer`, `ql-mcp-ext-workshop-author`) bundled inside the VSIX and contributed declaratively via `contributes.chatAgents`, so both agents are discoverable in VS Code Copilot Chat without any manual configuration. The `ql-mcp-ext-` prefix distinguishes extension-shipped customizations from repo-native `.github/agents/` definitions. No specific model is required — users choose their own. To add personal or team agents, set [`chat.agentFilesLocations`](https://code.visualstudio.com/docs/copilot/customization/custom-agents) to a workspace-relative path directly (VS Code rejects absolute paths there, so the extension does not write to that setting). ([#281](https://github.com/advanced-security/codeql-development-mcp-server/pull/281))
@@ -30,6 +44,19 @@ _Changes on `main` since the latest tagged release that have not yet been includ
3044

3145
### Changed
3246

47+
#### MCP Server Tools
48+
49+
| Tool | Change |
50+
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
51+
| `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. |
52+
| `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). |
53+
| `codeql_query_run` | Added overlay-evaluation parameters `evaluate-as-overlay` and `cache-at-frontier`. |
54+
| `codeql_test_run` | Added `check-diff-informed` (validate diff-informed query filtering) and `evaluate-as-overlay`. |
55+
56+
#### MCP Server Resources & Prompts
57+
58+
- **Diff-informed analysis docs now describe local diff-range injection** — The `codeql://learning/diff-informed-analysis` resource and the `diff_informed_analysis_workflow` prompt document the local mechanism used by Code Scanning: 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).
59+
3360
#### VS Code Extension
3461

3562
- **Workflow prompts now come exclusively from the `ql-mcp` MCP server** — Previously the extension also bundled four `.prompt.md` files (`ql-mcp-ext-tdd-basic`, `ql-mcp-ext-tdd-advanced`, `ql-mcp-ext-tools-query-workflow`, `ql-mcp-ext-workshop-creation-workflow`) as `contributes.chatPromptFiles`. Those were byte-for-byte renamed copies of prompts the MCP server already serves via `prompts/list`, which Copilot Chat surfaces as slash commands (`/ql_tdd_basic`, etc.). The duplicate `chatPromptFiles` contributions have been removed; the two shipped agents now reference an expanded set of canonical MCP slash IDs (`/ql_tdd_basic`, `/ql_tdd_advanced`, `/ql_lsp_iterative_development`, `/tools_query_workflow`, `/explain_codeql_query`, `/document_codeql_query`, `/data_extension_development`, `/workshop_creation_workflow`) so users get a richer workflow palette without the duplicate-slash-command UX. ([#281](https://github.com/advanced-security/codeql-development-mcp-server/pull/281))

‎docs/ql-mcp/resources.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ The server exposes **11 static resources** and a set of **dynamic per-language r
2121
| CodeQL Security Templates | `codeql://templates/security` | Security query templates for multiple languages and vulnerability classes |
2222
| CodeQL Query Unit Testing | `codeql://guides/query-unit-testing` | Guide for creating and running unit tests for CodeQL queries |
2323
| CodeQL Dataflow Migration | `codeql://guides/dataflow-migration-v1-to-v2` | Guide for migrating from legacy v1 dataflow API to modern v2 module-based API |
24+
| CodeQL Diff-Informed Analysis | `codeql://learning/diff-informed-analysis` | Make data-flow queries diff-informed and validate with `--check-diff-informed` |
25+
| CodeQL Overlay Databases | `codeql://guides/overlay-databases` | Build and evaluate overlay databases for incremental analysis |
2426

2527
## Language-Specific Resources
2628

0 commit comments

Comments
 (0)