[UPDATE PRIMITIVE] Fix bugs 1–5 and implement design improvements 1–3, 5 from v2.25.1-next.2 evaluation

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/src/lib/integration-test-runner.js

@@ -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}`);
       }

client/src/lib/monitoring-integration-test-runner.js

@@ -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}`);
         }

extensions/vscode/README.md

@@ -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.                 |

extensions/vscode/package.json

@@ -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": {

extensions/vscode/src/bridge/environment-builder.ts

@@ -147,7 +147,17 @@ 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.
+    const enableAnnotations = config.get<boolean>('enableAnnotationTools', true);
+    env.ENABLE_ANNOTATION_TOOLS = enableAnnotations ? 'true' : 'false';
+    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;

extensions/vscode/test/bridge/environment-builder.test.ts

@@ -272,4 +272,79 @@ 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 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;
+    }
+  });
 });