Fix bqrs_interpret: auto-resolve --source-location-prefix from database 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>

Author: Copilot

server/dist/codeql-development-mcp-server.js

@@ -184635,7 +184635,7 @@ function cacheDatabaseAnalyzeResults(params, logger2) {
 
 // src/lib/cli-tool-registry.ts
 init_package_paths();
-import { writeFileSync as writeFileSync4, rmSync, existsSync as existsSync6, mkdirSync as mkdirSync8, realpathSync } from "fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync8, readFileSync as readFileSync7, realpathSync, rmSync, writeFileSync as writeFileSync4 } from "fs";
 import { delimiter as delimiter5, dirname as dirname5, isAbsolute as isAbsolute4, join as join10, resolve as resolve4 } from "path";
 
 // ../node_modules/js-yaml/dist/js-yaml.mjs
@@ -187500,6 +187500,15 @@ function registerCLITool(server, definition) {
                   `CodeQL database at "${dbPath}" does not contain a source archive (expected "src.zip" file or "src" directory).`
                 );
               }
+              const dbYmlPath = join10(dbPath, "codeql-database.yml");
+              try {
+                const dbYml = readFileSync7(dbYmlPath, "utf8");
+                const dbMeta = load(dbYml);
+                if (dbMeta?.sourceLocationPrefix && typeof dbMeta.sourceLocationPrefix === "string") {
+                  options["source-location-prefix"] = dbMeta.sourceLocationPrefix;
+                }
+              } catch {
+              }
               delete options.database;
             }
             break;
@@ -187793,7 +187802,7 @@ var codeqlBqrsInterpretTool = {
     file: external_exports.string().describe("The BQRS file to interpret"),
     format: external_exports.enum(["csv", "sarif-latest", "sarifv2.1.0", "graphtext", "dgml", "dot"]).describe("Output format: csv (comma-separated), sarif-latest/sarifv2.1.0 (SARIF), graphtext/dgml/dot (graph formats, only for @kind graph queries)"),
     output: createCodeQLSchemas.output(),
-    database: external_exports.string().optional().describe("Path to the CodeQL database, used to resolve source archive context for SARIF interpretation (provides file contents and snippets)"),
+    database: external_exports.string().optional().describe("Path to the CodeQL database. When provided, auto-resolves --source-archive (for file contents/snippets) and --source-location-prefix (from codeql-database.yml metadata) so SARIF results include full source context"),
     t: external_exports.array(external_exports.string()).describe('Query metadata key=value pairs in KEY=VALUE format. At least "kind" and "id" must be specified. Example: ["kind=problem", "id=js/sql-injection"]. Common keys: kind (problem|path-problem|graph|metric|diagnostic), id (query identifier like js/xss)'),
     "max-paths": external_exports.number().optional().describe("Maximum number of paths to produce for each alert with paths (default: 4)"),
     "sarif-add-file-contents": external_exports.boolean().optional().describe("[SARIF only] Include full file contents for all files referenced in results"),
@@ -188351,7 +188360,7 @@ var codeqlGenerateQueryHelpTool = {
 };
 
 // src/tools/codeql/list-databases.ts
-import { existsSync as existsSync8, readdirSync as readdirSync4, readFileSync as readFileSync8, statSync as statSync4 } from "fs";
+import { existsSync as existsSync8, readdirSync as readdirSync4, readFileSync as readFileSync9, statSync as statSync4 } from "fs";
 import { join as join12 } from "path";
 
 // src/lib/discovery-config.ts
@@ -188376,7 +188385,7 @@ function getQueryRunResultsDirs() {
 init_logger();
 function parseDatabaseYml(ymlPath) {
   try {
-    const content = readFileSync8(ymlPath, "utf-8");
+    const content = readFileSync9(ymlPath, "utf-8");
     const info = {};
     for (const line of content.split("\n")) {
       const trimmed = line.trim();
@@ -188505,7 +188514,7 @@ function registerListDatabasesTool(server) {
 }
 
 // src/tools/codeql/list-mrva-run-results.ts
-import { existsSync as existsSync9, readdirSync as readdirSync5, readFileSync as readFileSync9, statSync as statSync5 } from "fs";
+import { existsSync as existsSync9, readdirSync as readdirSync5, readFileSync as readFileSync10, statSync as statSync5 } from "fs";
 import { join as join13 } from "path";
 init_logger();
 var NUMERIC_DIR_PATTERN = /^\d+$/;
@@ -188541,7 +188550,7 @@ async function discoverMrvaRunResults(resultsDirs, runId) {
       const timestampPath = join13(entryPath, "timestamp");
       if (existsSync9(timestampPath)) {
         try {
-          timestamp2 = readFileSync9(timestampPath, "utf-8").trim();
+          timestamp2 = readFileSync10(timestampPath, "utf-8").trim();
         } catch {
         }
       }
@@ -188597,7 +188606,7 @@ function discoverRepoResults(runPath) {
       const repoTaskPath = join13(repoPath, "repo_task.json");
       if (existsSync9(repoTaskPath)) {
         try {
-          const raw = readFileSync9(repoTaskPath, "utf-8");
+          const raw = readFileSync10(repoTaskPath, "utf-8");
           const task = JSON.parse(raw);
           if (typeof task.analysisStatus === "string") {
             analysisStatus = task.analysisStatus;
@@ -188692,7 +188701,7 @@ function registerListMrvaRunResultsTool(server) {
 }
 
 // src/tools/codeql/list-query-run-results.ts
-import { existsSync as existsSync10, readdirSync as readdirSync6, readFileSync as readFileSync10, statSync as statSync6 } from "fs";
+import { existsSync as existsSync10, readdirSync as readdirSync6, readFileSync as readFileSync11, statSync as statSync6 } from "fs";
 import { join as join14 } from "path";
 init_logger();
 var QUERY_RUN_DIR_PATTERN = /^(.+\.ql)-(.+)$/;
@@ -188764,14 +188773,14 @@ async function discoverQueryRunResults(resultsDirs, filter) {
       const timestampPath = join14(entryPath, "timestamp");
       if (existsSync10(timestampPath)) {
         try {
-          timestamp2 = readFileSync10(timestampPath, "utf-8").trim();
+          timestamp2 = readFileSync11(timestampPath, "utf-8").trim();
         } catch {
         }
       }
       let metadata = {};
       if (hasQueryLog) {
         try {
-          const logContent = readFileSync10(join14(entryPath, "query.log"), "utf-8");
+          const logContent = readFileSync11(join14(entryPath, "query.log"), "utf-8");
           metadata = parseQueryLogMetadata(logContent);
         } catch {
         }
@@ -189881,7 +189890,7 @@ function registerQuickEvaluateTool(server) {
 
 // src/tools/codeql/read-database-source.ts
 var import_adm_zip = __toESM(require_adm_zip(), 1);
-import { existsSync as existsSync13, readdirSync as readdirSync7, readFileSync as readFileSync11, statSync as statSync7 } from "fs";
+import { existsSync as existsSync13, readdirSync as readdirSync7, readFileSync as readFileSync12, statSync as statSync7 } from "fs";
 import { join as join18, resolve as resolve7 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 init_logger();
@@ -190043,7 +190052,7 @@ Directory contains ${availableEntries.length} entries. Use read_database_source
       );
     }
     const fullPath = join18(srcDirPath, matchedRelative);
-    const rawContent = readFileSync11(fullPath, "utf-8");
+    const rawContent = readFileSync12(fullPath, "utf-8");
     const { content, effectiveEnd, effectiveStart, totalLines } = applyLineRange(
       rawContent,
       startLine,
@@ -190391,7 +190400,7 @@ var codeqlResolveTestsTool = {
 };
 
 // src/tools/codeql/search-ql-code.ts
-import { closeSync as closeSync2, createReadStream as createReadStream3, fstatSync as fstatSync2, lstatSync, openSync as openSync2, readdirSync as readdirSync8, readFileSync as readFileSync12, realpathSync as realpathSync2 } from "fs";
+import { closeSync as closeSync2, createReadStream as createReadStream3, fstatSync as fstatSync2, lstatSync, openSync as openSync2, readdirSync as readdirSync8, readFileSync as readFileSync13, realpathSync as realpathSync2 } from "fs";
 import { basename as basename8, extname as extname2, join as join19, resolve as resolve9 } from "path";
 import { createInterface as createInterface3 } from "readline";
 init_logger();
@@ -190467,7 +190476,7 @@ async function searchFile(filePath, regex, contextLines, maxCollect) {
   }
   let content;
   try {
-    content = readFileSync12(fd, "utf-8");
+    content = readFileSync13(fd, "utf-8");
   } catch {
     try {
       closeSync2(fd);

server/dist/codeql-development-mcp-server.js.map

@@ -11,7 +11,7 @@ import { getOrCreateLogDirectory } from './log-directory-manager';
 import { resolveQueryPath } from './query-resolver';
 import { cacheDatabaseAnalyzeResults, processQueryRunResults } from './result-processor';
 import { getUserWorkspaceDir, packageRootDir } from '../utils/package-paths';
-import { writeFileSync, rmSync, existsSync, mkdirSync, realpathSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'fs';
 import { delimiter, dirname, isAbsolute, join, resolve } from 'path';
 import * as yaml from 'js-yaml';
 import { createProjectTempDir } from '../utils/temp-dir';
@@ -384,7 +384,8 @@ export function registerCLITool(server: McpServer, definition: CLIToolDefinition
           }
 
           case 'codeql_bqrs_interpret':
-            // Map 'database' to '--source-archive' for codeql bqrs interpret
+            // Map 'database' to '--source-archive' and '--source-location-prefix'
+            // for codeql bqrs interpret
             if (options.database) {
               const dbPath = resolveDatabasePath(options.database as string);
               const srcZipPath = join(dbPath, 'src.zip');
@@ -399,6 +400,17 @@ export function registerCLITool(server: McpServer, definition: CLIToolDefinition
                   `CodeQL database at "${dbPath}" does not contain a source archive (expected "src.zip" file or "src" directory).`,
                 );
               }
+              // Auto-resolve --source-location-prefix from codeql-database.yml
+              const dbYmlPath = join(dbPath, 'codeql-database.yml');
+              try {
+                const dbYml = readFileSync(dbYmlPath, 'utf8');
+                const dbMeta = yaml.load(dbYml) as Record<string, unknown> | undefined;
+                if (dbMeta?.sourceLocationPrefix && typeof dbMeta.sourceLocationPrefix === 'string') {
+                  options['source-location-prefix'] = dbMeta.sourceLocationPrefix;
+                }
+              } catch {
+                // codeql-database.yml missing or unparseable — skip prefix resolution
+              }
               delete options.database;
             }
             break;

server/src/lib/cli-tool-registry.ts

@@ -16,7 +16,7 @@ export const codeqlBqrsInterpretTool: CLIToolDefinition = {
       .describe('Output format: csv (comma-separated), sarif-latest/sarifv2.1.0 (SARIF), graphtext/dgml/dot (graph formats, only for @kind graph queries)'),
     output: createCodeQLSchemas.output(),
     database: z.string().optional()
-      .describe('Path to the CodeQL database, used to resolve source archive context for SARIF interpretation (provides file contents and snippets)'),
+      .describe('Path to the CodeQL database. When provided, auto-resolves --source-archive (for file contents/snippets) and --source-location-prefix (from codeql-database.yml metadata) so SARIF results include full source context'),
     t: z.array(z.string())
       .describe('Query metadata key=value pairs in KEY=VALUE format. At least "kind" and "id" must be specified. Example: ["kind=problem", "id=js/sql-injection"]. Common keys: kind (problem|path-problem|graph|metric|diagnostic), id (query identifier like js/xss)'),
     'max-paths': z.number().optional()

server/src/tools/codeql/bqrs-interpret.ts

@@ -549,6 +549,107 @@ describe('registerCLITool handler behavior', () => {
     );
   });
 
+  it('should auto-resolve source-location-prefix from codeql-database.yml for bqrs_interpret with database', async () => {
+    // Create a temp database directory with codeql-database.yml containing sourceLocationPrefix
+    const tmpDir = createTestTempDir('bqrs-interpret-slp');
+    const dbDir = join(tmpDir, 'test-db');
+    mkdirSync(dbDir, { recursive: true });
+    writeFileSync(join(dbDir, 'codeql-database.yml'), [
+      'primaryLanguage: javascript',
+      'sourceLocationPrefix: /Users/dev/my-project',
+      'creationMetadata:',
+      '  cliVersion: 2.25.1',
+    ].join('\n'), 'utf8');
+    // Create src.zip so source-archive resolution succeeds
+    writeFileSync(join(dbDir, 'src.zip'), '', 'utf8');
+
+    const definition: CLIToolDefinition = {
+      name: 'codeql_bqrs_interpret',
+      description: 'Interpret BQRS',
+      command: 'codeql',
+      subcommand: 'bqrs interpret',
+      inputSchema: {
+        file: z.string(),
+        database: z.string().optional(),
+        format: z.string().optional()
+      }
+    };
+
+    registerCLITool(mockServer, definition);
+
+    const handler = (mockServer.tool as ReturnType<typeof vi.fn>).mock.calls[0][3];
+
+    executeCodeQLCommand.mockResolvedValueOnce({
+      stdout: 'Interpreted',
+      stderr: '',
+      success: true
+    });
+
+    try {
+      await handler({ file: '/path/to/results.bqrs', database: dbDir, format: 'sarif-latest' });
+
+      const callArgs = executeCodeQLCommand.mock.calls[0];
+      const options = callArgs[1] as Record<string, unknown>;
+      // source-location-prefix should be auto-resolved from codeql-database.yml
+      expect(options['source-location-prefix']).toBe('/Users/dev/my-project');
+      // source-archive should point to src.zip
+      expect(options['source-archive']).toBe(join(dbDir, 'src.zip'));
+      // database should be removed from options (not passed to CLI)
+      expect(options).not.toHaveProperty('database');
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it('should not set source-location-prefix when codeql-database.yml has no sourceLocationPrefix for bqrs_interpret', async () => {
+    // Create a temp database directory with codeql-database.yml WITHOUT sourceLocationPrefix
+    const tmpDir = createTestTempDir('bqrs-interpret-no-slp');
+    const dbDir = join(tmpDir, 'test-db');
+    mkdirSync(dbDir, { recursive: true });
+    writeFileSync(join(dbDir, 'codeql-database.yml'), [
+      'primaryLanguage: javascript',
+      'creationMetadata:',
+      '  cliVersion: 2.25.1',
+    ].join('\n'), 'utf8');
+    // Create src directory as fallback source archive
+    mkdirSync(join(dbDir, 'src'), { recursive: true });
+
+    const definition: CLIToolDefinition = {
+      name: 'codeql_bqrs_interpret',
+      description: 'Interpret BQRS',
+      command: 'codeql',
+      subcommand: 'bqrs interpret',
+      inputSchema: {
+        file: z.string(),
+        database: z.string().optional(),
+        format: z.string().optional()
+      }
+    };
+
+    registerCLITool(mockServer, definition);
+
+    const handler = (mockServer.tool as ReturnType<typeof vi.fn>).mock.calls[0][3];
+
+    executeCodeQLCommand.mockResolvedValueOnce({
+      stdout: 'Interpreted',
+      stderr: '',
+      success: true
+    });
+
+    try {
+      await handler({ file: '/path/to/results.bqrs', database: dbDir, format: 'sarif-latest' });
+
+      const callArgs = executeCodeQLCommand.mock.calls[0];
+      const options = callArgs[1] as Record<string, unknown>;
+      // source-location-prefix should NOT be set when not in codeql-database.yml
+      expect(options).not.toHaveProperty('source-location-prefix');
+      // source-archive should fall back to src directory
+      expect(options['source-archive']).toBe(join(dbDir, 'src'));
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
   it('should NOT pass format to CLI options for tools where format should not be on CLI', async () => {
     const definition: CLIToolDefinition = {
       name: 'codeql_query_run',

server/test/src/lib/cli-tool-registry.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Tests for codeql_bqrs_interpret tool definition
+ *
+ * Validates the tool schema, including the database parameter for
+ * source archive context and source-location-prefix auto-resolution.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { codeqlBqrsInterpretTool } from '../../../../src/tools/codeql/bqrs-interpret';
+
+describe('codeql_bqrs_interpret tool definition', () => {
+  it('should have correct tool name', () => {
+    expect(codeqlBqrsInterpretTool.name).toBe('codeql_bqrs_interpret');
+  });
+
+  it('should use codeql bqrs interpret subcommand', () => {
+    expect(codeqlBqrsInterpretTool.command).toBe('codeql');
+    expect(codeqlBqrsInterpretTool.subcommand).toBe('bqrs interpret');
+  });
+
+  it('should have file as required positional input (string, not array)', () => {
+    expect(codeqlBqrsInterpretTool.inputSchema).toHaveProperty('file');
+    // Verify it's a string schema, not an array schema
+    const fileSchema = codeqlBqrsInterpretTool.inputSchema.file;
+    // Parse should accept a string
+    expect(fileSchema.parse('/path/to/results.bqrs')).toBe('/path/to/results.bqrs');
+    // Parse should reject an array
+    expect(() => fileSchema.parse(['/path/to/results.bqrs'])).toThrow();
+  });
+
+  it('should support format parameter', () => {
+    expect(codeqlBqrsInterpretTool.inputSchema).toHaveProperty('format');
+  });
+
+  it('should support database parameter (optional, for source archive context)', () => {
+    expect(codeqlBqrsInterpretTool.inputSchema).toHaveProperty('database');
+  });
+
+  it('should support t parameter (query metadata key=value pairs)', () => {
+    expect(codeqlBqrsInterpretTool.inputSchema).toHaveProperty('t');
+  });
+
+  it('should support output parameter', () => {
+    expect(codeqlBqrsInterpretTool.inputSchema).toHaveProperty('output');
+  });
+
+  it('should have examples', () => {
+    expect(codeqlBqrsInterpretTool.examples).toBeDefined();
+    expect(codeqlBqrsInterpretTool.examples!.length).toBeGreaterThan(0);
+  });
+
+  it('should have a custom result processor', () => {
+    expect(codeqlBqrsInterpretTool.resultProcessor).toBeDefined();
+  });
+});