advanced-security · Copilot · Mar 31, 2026 · Mar 31, 2026 · Mar 31, 2026 · Mar 31, 2026
@@ -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.2 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
 

@@ -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"
   }
 }
@@ -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",

@@ -931,7 +931,7 @@ export class IntegrationTestRunner {
       // Use static BQRS file
       const bqrsFile = path.join(staticPath, "src", "ExampleQuery1", "ExampleQuery1.test.bqrs");
       if (fs.existsSync(bqrsFile)) {
-        params.files = [bqrsFile];
+        params.file = bqrsFile;
       } else {
         throw new Error(`Static BQRS file not found: ${bqrsFile}`);
       }

@@ -361,7 +361,7 @@ export class MonitoringIntegrationTestRunner {
       if (fs.existsSync(beforeDir)) {
         const bqrsFiles = fs.readdirSync(beforeDir).filter((f) => f.endsWith(".bqrs"));
         if (bqrsFiles.length > 0) {
-          params.bqrs = path.join(beforeDir, bqrsFiles[0]);
+          params.file = path.join(beforeDir, bqrsFiles[0]);
         } else {
           throw new Error(`No .bqrs files found in ${beforeDir} for ${toolName}`);
         }

@@ -45,6 +45,7 @@ All settings are under the `codeql-mcp` namespace in VS Code settings:
 | `codeql-mcp.serverCommand`                 | `"node"`   | Command to launch the server. Override to `"npx"` or a custom path. |
 | `codeql-mcp.serverArgs`                    | `[]`       | Custom args. When empty, the bundled entry point is used.           |
 | `codeql-mcp.watchCodeqlExtension`          | `true`     | Watch for databases and results from the CodeQL extension.          |
+| `codeql-mcp.enableAnnotationTools`         | `true`     | Enable annotation, audit, and cache tools.                          |
 | `codeql-mcp.additionalEnv`                 | `{}`       | Extra environment variables passed to the server process.           |
 | `codeql-mcp.additionalDatabaseDirs`        | `[]`       | Additional directories to search for CodeQL databases.              |
 | `codeql-mcp.additionalMrvaRunResultsDirs`  | `[]`       | Additional directories containing MRVA run results.                 |

@@ -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",
@@ -90,6 +90,11 @@
           "default": true,
           "markdownDescription": "Copy CodeQL databases from the `GitHub.vscode-codeql` extension storage into a managed directory, removing query-server lock files so the MCP server CLI can operate without contention. Disable to use databases in-place (may fail when the CodeQL query server is running)."
         },
+        "codeql-mcp.enableAnnotationTools": {
+          "type": "boolean",
+          "default": true,
+          "markdownDescription": "Enable annotation, audit, and query results caching tools. When enabled, the MCP server registers `annotation_*`, `audit_*`, and `query_results_cache_*` tools. Disable to reduce the tool surface if these capabilities are not needed."
+        },
         "codeql-mcp.serverArgs": {
           "type": "array",
           "items": {

@@ -147,7 +147,26 @@ export class EnvironmentBuilder extends DisposableObject {
     queryDirs.push(...userQueryDirs);
     env.CODEQL_QUERY_RUN_RESULTS_DIRS = queryDirs.join(delimiter);
 
-    // User-configured additional environment variables
+    // Annotation, audit, and cache tools — enabled by default (Design 5).
+    // The setting controls ENABLE_ANNOTATION_TOOLS and defaults
+    // MONITORING_STORAGE_LOCATION to the scratch directory so tools work
+    // out-of-the-box without manual env var configuration.
+    // Respect values inherited from the extension host process environment;
+    // only apply defaults when not already defined there. The additionalEnv
+    // block below still overrides everything for advanced users.
+    const enableAnnotations = config.get<boolean>('enableAnnotationTools', true);
+    if (typeof process.env.ENABLE_ANNOTATION_TOOLS === 'string') {
+      env.ENABLE_ANNOTATION_TOOLS = process.env.ENABLE_ANNOTATION_TOOLS;
+    } else {
+      env.ENABLE_ANNOTATION_TOOLS = enableAnnotations ? 'true' : 'false';
+    }
+    if (typeof process.env.MONITORING_STORAGE_LOCATION === 'string') {
+      env.MONITORING_STORAGE_LOCATION = process.env.MONITORING_STORAGE_LOCATION;
+    } else if (enableAnnotations && env.CODEQL_MCP_SCRATCH_DIR) {
+      env.MONITORING_STORAGE_LOCATION = env.CODEQL_MCP_SCRATCH_DIR;
+    }
+
+    // User-configured additional environment variables (overrides above defaults)
     const additionalEnv = config.get<Record<string, string>>('additionalEnv', {});
     for (const [key, value] of Object.entries(additionalEnv)) {
       env[key] = value;

@@ -272,4 +272,124 @@ describe('EnvironmentBuilder', () => {
   it('should be disposable', () => {
     expect(() => builder.dispose()).not.toThrow();
   });
+
+  it('should set ENABLE_ANNOTATION_TOOLS=true by default', async () => {
+    const env = await builder.build();
+    expect(env.ENABLE_ANNOTATION_TOOLS).toBe('true');
+  });
+
+  it('should not overwrite MONITORING_STORAGE_LOCATION if already set in parent env', async () => {
+    const vscode = await import('vscode');
+    const origFolders = vscode.workspace.workspaceFolders;
+    const origMonLoc = process.env.MONITORING_STORAGE_LOCATION;
+
+    try {
+      (vscode.workspace.workspaceFolders as any) = [
+        { uri: { fsPath: '/mock/workspace' }, name: 'ws', index: 0 },
+      ];
+      // Simulate parent process env with MONITORING_STORAGE_LOCATION already set
+      process.env.MONITORING_STORAGE_LOCATION = '/custom/storage/path';
+
+      builder.invalidate();
+      const env = await builder.build();
+      // process.env value should be preserved
+      expect(env.MONITORING_STORAGE_LOCATION).toBe('/custom/storage/path');
+    } finally {
+      (vscode.workspace.workspaceFolders as any) = origFolders;
+      if (origMonLoc === undefined) {
+        delete process.env.MONITORING_STORAGE_LOCATION;
+      } else {
+        process.env.MONITORING_STORAGE_LOCATION = origMonLoc;
+      }
+    }
+  });
+
+  it('should set ENABLE_ANNOTATION_TOOLS=false when setting is disabled', async () => {
+    const vscode = await import('vscode');
+    const originalGetConfig = vscode.workspace.getConfiguration;
+
+    try {
+      vscode.workspace.getConfiguration = () => ({
+        get: (_key: string, defaultVal?: any) => {
+          if (_key === 'enableAnnotationTools') return false;
+          if (_key === 'additionalDatabaseDirs') return [];
+          if (_key === 'additionalQueryRunResultsDirs') return [];
+          if (_key === 'additionalMrvaRunResultsDirs') return [];
+          return defaultVal;
+        },
+        has: () => false,
+        inspect: () => undefined as any,
+        update: () => Promise.resolve(),
+      }) as any;
+
+      builder.invalidate();
+      const env = await builder.build();
+      expect(env.ENABLE_ANNOTATION_TOOLS).toBe('false');
+    } finally {
+      vscode.workspace.getConfiguration = originalGetConfig;
+    }
+  });
+
+  it('should set MONITORING_STORAGE_LOCATION to scratch dir when annotations enabled with workspace', async () => {
+    const vscode = await import('vscode');
+    const origFolders = vscode.workspace.workspaceFolders;
+
+    try {
+      (vscode.workspace.workspaceFolders as any) = [
+        { uri: { fsPath: '/mock/workspace' }, name: 'ws', index: 0 },
+      ];
+
+      builder.invalidate();
+      const env = await builder.build();
+      expect(env.MONITORING_STORAGE_LOCATION).toBe('/mock/workspace/.codeql/ql-mcp');
+    } finally {
+      (vscode.workspace.workspaceFolders as any) = origFolders;
+    }
+  });
+
+  it('should allow additionalEnv to override ENABLE_ANNOTATION_TOOLS', async () => {
+    const vscode = await import('vscode');
+    const originalGetConfig = vscode.workspace.getConfiguration;
+
+    try {
+      vscode.workspace.getConfiguration = () => ({
+        get: (_key: string, defaultVal?: any) => {
+          if (_key === 'additionalEnv') return { ENABLE_ANNOTATION_TOOLS: 'false' };
+          if (_key === 'additionalDatabaseDirs') return [];
+          if (_key === 'additionalQueryRunResultsDirs') return [];
+          if (_key === 'additionalMrvaRunResultsDirs') return [];
+          return defaultVal;
+        },
+        has: () => false,
+        inspect: () => undefined as any,
+        update: () => Promise.resolve(),
+      }) as any;
+
+      builder.invalidate();
+      const env = await builder.build();
+      // additionalEnv comes after the default, so it should override
+      expect(env.ENABLE_ANNOTATION_TOOLS).toBe('false');
+    } finally {
+      vscode.workspace.getConfiguration = originalGetConfig;
+    }
+  });
+
+  it('should preserve ENABLE_ANNOTATION_TOOLS from parent process environment', async () => {
+    const origValue = process.env.ENABLE_ANNOTATION_TOOLS;
+
+    try {
+      process.env.ENABLE_ANNOTATION_TOOLS = 'false';
+
+      builder.invalidate();
+      const env = await builder.build();
+      // Inherited process.env value should be preserved
+      expect(env.ENABLE_ANNOTATION_TOOLS).toBe('false');
+    } finally {
+      if (origValue === undefined) {
+        delete process.env.ENABLE_ANNOTATION_TOOLS;
+      } else {
+        process.env.ENABLE_ANNOTATION_TOOLS = origValue;
+      }
+    }
+  });
 });
@@ -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",