Database lock contention between `ql-mcp` server and `GitHub.vscode-codeql` extension

[data-douser]

Problem

When ql-mcp MCP server tools such as codeql_query_run and codeql_database_analyze are invoked against CodeQL databases that are registered by the GitHub.vscode-codeql extension, the operations can fail due to lock contention on the database's cache directory.

Root cause

The GitHub.vscode-codeql extension's query server creates a .lock file within the <db-language>/default/cache/ directory of every CodeQL database that is registered with that extension — not just the "active" database. This lock is created when the query server registers the database via the evaluation/registerDatabases JSON-RPC method, and persists for the lifetime of the query server process.

When the ql-mcp server (via the advanced-security.vscode-codeql-development-mcp-server VS Code extension) discovers these same databases through the CODEQL_DATABASES_BASE_DIRS environment variable and attempts to run CodeQL CLI operations against them, the CLI encounters the existing .lock file and fails because it cannot acquire exclusive access to the database cache.

Example

A typical .lock file path:

${HOME}/Library/Application Support/Code/User/workspaceStorage/<workspace-id>/GitHub.vscode-codeql/<db-name>/<language>/db-<language>/default/cache/.lock

The lock file is an empty file (0 bytes) created by the CodeQL CLI's query server process. It uses OS-level file locking (e.g. flock/fcntl) to enforce mutual exclusion on the database cache directory.

Impact

Any ql-mcp tool that needs to evaluate queries against a CodeQL database registered by GitHub.vscode-codeql — including codeql_query_run, codeql_database_analyze, and others — is affected. This makes the database bridge functionality introduced in #61 unreliable when the GitHub.vscode-codeql extension has an active query server.

Possible approaches

1. Copy databases to a separate managed directory — The advanced-security.vscode-codeql-development-mcp-server extension could maintain its own database storage directory, copying databases from GitHub.vscode-codeql's storage and removing the .lock file in the copy. The CODEQL_DATABASES_BASE_DIRS env var would point to this managed directory.

2. Route queries through GitHub.vscode-codeql's query server — Instead of invoking the CodeQL CLI directly, delegate query execution to the GitHub.vscode-codeql extension's existing query server, which already holds the locks and can run queries without contention.

3. Hybrid approach — Support both direct CLI execution (with database copying) and delegated execution through the vscode-codeql query server, allowing users to choose based on their workflow.

Related

• Follow-up to Add vscode-codeql-development-mcp-server.vsix extension for "bridge" to GitHub.vscode-codeql extension's databases, query results, and MRVA results #61 (VS Code extension bridge for GitHub.vscode-codeql databases)