Improve MCP server integrations with `codeql execute *-server` servers by data-douser · Pull Request #29 · advanced-security/codeql-development-mcp-server

data-douser · 2026-02-09T02:32:35Z

This PR:

Resolves Extended support for CodeQL Language Server (LSP) features #1
Resolves MCP Server CodeQL Background Server Integration #17

Summary

Adds four LSP-based MCP tools powered by the CodeQL Language Server, introduces a background server lifecycle manager for codeql execute *-server processes, and improves test infrastructure.

New LSP Tools

Tool	Description
`codeql_lsp_completion`	Code completions at a cursor position in a `.ql`/`.qll` file
`codeql_lsp_definition`	Go-to-definition for CodeQL symbols
`codeql_lsp_references`	Find all references to a CodeQL symbol
`codeql_lsp_diagnostics`	Authoritative QL validation via LSP (renamed from `codeql_language_server_eval`)

Background Server Manager

New CodeQLServerManager (server/src/lib/server-manager.ts) manages the lifecycle of three CodeQL background server types:

language-server — LSP-based QL validation (JSON-RPC over stdio)
query-server2 — Query evaluation (custom protocol over stdio)
cli-server — JVM reuse for CLI commands (NUL-delimited protocol)

Key behaviors:

Config-hash-keyed caching: servers are reused when configuration matches, restarted when it changes
Session-isolated cache directories under .tmp/codeql-cache/<sessionId>/
waitForProcessReady utility replaces hard-coded setTimeout(2000) delays with event-based JVM readiness detection
Centralized graceful shutdown via setupGracefulShutdown in the MCP server entry point

Reliability Fixes

CI timeout fix: LSP tools added to longRunningTools list (300s timeout) in integration test runner — prevents failures during JVM cold-start on CI
Relative workspace_uri handling: LSP handlers convert relative paths and bare directory paths to file:// URIs before passing to the language server
Async file I/O: Replaced synchronous readFileSync with readFile from fs/promises in lsp-handlers.ts
isRunning() guards: LSP feature methods (getCompletions, getDefinition, getReferences) now check if the server process is alive before sending requests
Shutdown race fix: exit notification in language-server.ts shutdown() is guarded to prevent "not running" errors when the process exits before the notification is sent
semantic_validation integration test fix: Uses UndefinedType (resolvable without imports) instead of DataFlow::Configuration (requires pack imports that inline QL can't resolve)

Test Infrastructure

Global logger mock: New server/test/setup.ts registered via vitest.config.ts setupFiles — suppresses all logger stderr output during tests. Removed 16 per-file vi.mock('…/logger') blocks. logger.test.ts uses vi.unmock() to opt out.
New unit tests: cli-server.test.ts, query-server.test.ts, server-config.test.ts, server-manager.test.ts, process-ready.test.ts, lsp-diagnostics.test.ts, lsp-handlers.test.ts, lsp-tools.test.ts, lsp/index.test.ts
Enhanced existing tests: language-server.test.ts expanded from 1 placeholder to 19 tests; workflow-prompts.test.ts expanded with schema validation and registration consistency tests; server-config.test.ts verifies --debug/--tuple-counting ordering

Other Changes

New ql_lsp_iterative_development workflow prompt with .prompt.md template
LSP tool references added to ql-tdd-basic, ql-tdd-advanced, and tools-query-workflow prompts
docs/tools-reference.md updated with Validation & LSP Tools section
Integration test READMEs added for all new LSP tool test directories
server/package.json clean script now also removes .tmp/
Extracted and exported Zod schemas for all workflow prompts (enables independent unit testing)

Outline of Changes

Test Coverage Improvements:

Added new integration tests for codeql_lsp_completion covering member access completions and keyword completions, with corresponding test documentation and monitoring state files. [1] [2] [3] [4] [5]
Introduced tests for codeql_lsp_definition to verify resolution of types and library modules, with before/after monitoring state and comprehensive README documentation. [1] [2] [3] [4] [5]

Diagnostics Testing Enhancements:

Added semantic and syntax validation tests for codeql_lsp_diagnostics, including test cases for undefined types and syntax errors, with updated monitoring state and documentation. [1] [2] [3]

Test Structure and Naming Updates:

Renamed and reorganized the codeql_language_server_eval test directory to codeql_lsp_diagnostics to better reflect the tool being tested, and updated references in documentation and monitoring state files accordingly. [1] [2] [3]

Cleanup:

Removed obsolete monitoring state files for deprecated or renamed tests.

Implements CodeQLServerManager for config-aware lifecycle management of CodeQL's three background servers (language-server, query-server2, cli-server) with session-isolated cache directories and automatic restart on configuration changes. Adds four LSP-based MCP tools: - codeql_lsp_diagnostics (renamed from codeql_language_server_eval) - codeql_lsp_completion - codeql_lsp_definition - codeql_lsp_references Resolves #17 (server manager with config hashing, session isolation, graceful shutdown) and #1 (LSP completion/definition/references tools).

- Fix duplicate --tuple-counting flag when both debug and tupleCounting are set in buildQueryServerArgs - Fix non-awaited force-kill timers in query-server and language-server shutdown methods (process could outlive caller) - Remove redundant process.on SIGINT/SIGTERM handlers from lsp-diagnostics (already handled by shutdownServerManager) - Replace hard-coded setTimeout delays (1.5-2s) in server start() methods with waitForProcessReady utility that resolves on first stderr/stdout output or rejects on spawn failure - Add comprehensive tests for process-ready utility

- Add LSP tools to longRunningTools (300s timeout) in integration test runner to prevent CI timeouts during JVM startup - Convert relative workspace_uri to file:// URIs in lsp-handlers - Replace synchronous readFileSync with async readFile - Add isRunning() guards to LSP feature methods - Guard exit notification in shutdown to prevent "not running" error - Fix semantic_validation test to use resolvable QL code - Centralize logger mock in test/setup.ts (removes 16 per-file mocks) - Add server-manager getLanguageServer/getQueryServer/getCLIServer tests - Clarify --debug/--tuple-counting arg ordering in server-config - Add missing README.md files to integration test directories

Copilot

Pull request overview

This PR expands the MCP server’s CodeQL integrations by introducing a lifecycle-managed set of CodeQL background servers (language-server/query-server2/cli-server) and exposing new LSP-powered MCP tools (completion/definition/references/diagnostics), with substantial test and documentation updates to support the new capabilities.

Changes:

Added CodeQLServerManager + config hashing + per-session cache layout, and introduced clients for cli-server and query-server2.
Added 4 LSP-backed MCP tools (codeql_lsp_*) and updated prompts/docs/tests to use codeql_lsp_diagnostics (renamed from codeql_language_server_eval).
Improved test infrastructure (global logger mock, expanded unit tests, new integration test fixtures, and longer timeouts for LSP tools in CI).

Reviewed changes

Copilot reviewed 76 out of 82 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
server/vitest.config.ts	Registers a global Vitest setup file for shared test mocking.
server/test/setup.ts	Globally mocks the server logger to reduce noisy test output.
server/test/src/utils/process-ready.test.ts	Adds unit tests for the new `waitForProcessReady` utility.
server/test/src/utils/logger.test.ts	Unmocks the global logger mock to test the real logger implementation.
server/test/src/tools/monitoring-tools.test.ts	Removes per-file logger mocking in favor of global setup.
server/test/src/tools/lsp/lsp-tools.test.ts	Adds unit tests for LSP tool registration and handlers’ return shape.
server/test/src/tools/lsp/lsp-handlers.test.ts	Adds unit tests for MCP→LSP handler behavior (URI handling, file content, close-on-error).
server/test/src/tools/lsp/lsp-diagnostics.test.ts	Adds unit tests for `codeql_lsp_diagnostics` behavior and tool registration.
server/test/src/tools/lsp/index.test.ts	Verifies LSP barrel exports are stable/complete.
server/test/src/tools/codeql/register-database.test.ts	Removes per-file logger mocking in favor of global setup.
server/test/src/tools/codeql/quick-evaluate.test.ts	Removes per-file logger mocking in favor of global setup.
server/test/src/tools/codeql/profile-codeql-query.test.ts	Removes per-file logger mocking in favor of global setup.
server/test/src/tools/codeql/language-server-eval.test.ts	Deletes tests for deprecated `codeql_language_server_eval`.
server/test/src/tools/codeql-tools.test.ts	Updates expected tool registration count after moving diagnostics tool to LSP module.
server/test/src/prompts/workflow-prompts.test.ts	Expands prompt schema + registration consistency tests with prompt-loader mocked.
server/test/src/lib/server-manager.test.ts	Adds unit tests for server-manager lifecycle/caching semantics.
server/test/src/lib/server-config.test.ts	Adds unit tests for CLI arg building + config hashing determinism.
server/test/src/lib/query-server.test.ts	Adds unit tests for query-server JSON-RPC framing and request lifecycle.
server/test/src/lib/query-results-evaluator.test.ts	Removes per-file logger mocking in favor of global setup.
server/test/src/lib/metadata-resolver.test.ts	Removes per-file logger mocking in favor of global setup.
server/test/src/lib/language-server.test.ts	Replaces placeholder with comprehensive language-server behavior tests.
server/test/src/lib/cli-server.test.ts	Adds unit tests for cli-server NUL-delimited protocol and command queueing.
server/test/src/lib/cli-executor.test.ts	Removes per-file logger mocking in favor of global setup.
server/src/utils/process-ready.ts	Adds `waitForProcessReady` to replace fixed startup sleeps with event/timeout based readiness.
server/src/lib/server-config.ts	Introduces typed configs + arg builders + SHA-256 config hashing.
server/src/lib/server-manager.ts	Adds a manager to start/reuse/restart/shutdown CodeQL background servers per session/config.
server/src/lib/query-server.ts	Adds a query-server2 client using JSON-RPC (Content-Length framing).
server/src/lib/cli-server.ts	Adds a cli-server client using NUL-delimited request/response protocol.
server/src/lib/language-server.ts	Adds readiness waiting, workspace updates, and new LSP feature methods (completion/definition/references).
server/src/tools/lsp/lsp-handlers.ts	Implements MCP handlers that open/close documents and issue LSP requests.
server/src/tools/lsp/lsp-tools.ts	Registers completion/definition/references tools and delegates diagnostics registration.
server/src/tools/lsp/lsp-diagnostics.ts	Renames/rewires diagnostics tool to use the server manager and updated naming (`codeql_lsp_diagnostics`).
server/src/tools/lsp/index.ts	Adds barrel exports for LSP tools module.
server/src/tools/codeql/index.ts	Removes export of the deprecated language-server-eval tool.
server/src/tools/codeql-tools.ts	Updates references to the renamed authoritative validation tool.
server/src/codeql-development-mcp-server.ts	Registers LSP tools and adds graceful shutdown of background servers.
server/src/prompts/workflow-prompts.ts	Extracts and exports schemas for workflow prompts; adds new LSP iterative dev prompt registration.
server/src/prompts/tools-query-workflow.prompt.md	Adds references to the new LSP navigation tools.
server/src/prompts/ql-tdd-basic.prompt.md	Adds guidance to use LSP tools during query development.
server/src/prompts/ql-tdd-advanced.prompt.md	Adds an “LSP-powered navigation” section and examples.
server/src/prompts/ql-lsp-iterative-development.prompt.md	Adds a new prompt template for iterative development with LSP tools.
server/package.json	Extends `clean` script to remove `.tmp/`.
docs/tools-reference.md	Adds a “Validation & LSP Tools” section documenting the new tools.
client/src/lib/integration-test-runner.js	Updates special-case tool name + adds LSP tools to long-running timeout list.
client/src/lib/monitoring-integration-test-runner.js	Updates tool name mapping for monitoring tests (but currently passes wrong args for `codeql_lsp_diagnostics`).
client/integration-tests/README.md	Updates example paths to reflect `codeql_lsp_diagnostics` rename.
client/integration-tests/primitives/tools/codeql_lsp_completion/basic_completion/README.md	Adds integration test README for completion tool.
client/integration-tests/primitives/tools/codeql_lsp_completion/basic_completion/before/monitoring-state.json	Adds before monitoring-state fixture for completion tool.
client/integration-tests/primitives/tools/codeql_lsp_completion/basic_completion/after/monitoring-state.json	Adds after monitoring-state fixture for completion tool.
client/integration-tests/primitives/tools/codeql_lsp_completion/from_clause_completion/README.md	Adds integration test README for from-clause completion scenario.
client/integration-tests/primitives/tools/codeql_lsp_completion/from_clause_completion/before/monitoring-state.json	Adds before monitoring-state fixture for from-clause completion scenario.
client/integration-tests/primitives/tools/codeql_lsp_completion/from_clause_completion/after/monitoring-state.json	Adds after monitoring-state fixture for from-clause completion scenario.
client/integration-tests/primitives/tools/codeql_lsp_definition/basic_definition/README.md	Adds integration test README for definition tool.
client/integration-tests/primitives/tools/codeql_lsp_definition/basic_definition/before/monitoring-state.json	Adds before monitoring-state fixture for definition tool.
client/integration-tests/primitives/tools/codeql_lsp_definition/basic_definition/after/monitoring-state.json	Adds after monitoring-state fixture for definition tool.
client/integration-tests/primitives/tools/codeql_lsp_definition/class_definition/README.md	Adds integration test README for class-definition scenario.
client/integration-tests/primitives/tools/codeql_lsp_definition/class_definition/before/monitoring-state.json	Adds before monitoring-state fixture for class-definition scenario.
client/integration-tests/primitives/tools/codeql_lsp_definition/class_definition/after/monitoring-state.json	Adds after monitoring-state fixture for class-definition scenario.
client/integration-tests/primitives/tools/codeql_lsp_references/basic_references/README.md	Adds integration test README for references tool.
client/integration-tests/primitives/tools/codeql_lsp_references/basic_references/before/monitoring-state.json	Adds before monitoring-state fixture for references tool.
client/integration-tests/primitives/tools/codeql_lsp_references/basic_references/after/monitoring-state.json	Adds after monitoring-state fixture for references tool.
client/integration-tests/primitives/tools/codeql_lsp_references/predicate_references/README.md	Adds integration test README for predicate references scenario.
client/integration-tests/primitives/tools/codeql_lsp_references/predicate_references/before/monitoring-state.json	Adds before monitoring-state fixture for predicate references scenario.
client/integration-tests/primitives/tools/codeql_lsp_references/predicate_references/after/monitoring-state.json	Adds after monitoring-state fixture for predicate references scenario.
client/integration-tests/primitives/tools/codeql_lsp_diagnostics/valid_query_no_errors/README.md	Adds integration test README for diagnostics “valid” scenario.
client/integration-tests/primitives/tools/codeql_lsp_diagnostics/valid_query_no_errors/before/monitoring-state.json	Adds before monitoring-state fixture for diagnostics “valid” scenario.
client/integration-tests/primitives/tools/codeql_lsp_diagnostics/valid_query_no_errors/after/monitoring-state.json	Adds after monitoring-state fixture for diagnostics “valid” scenario.
client/integration-tests/primitives/tools/codeql_lsp_diagnostics/valid_query_no_errors/before/valid_query.ql	Adds file-based fixture for diagnostics “valid” scenario.
client/integration-tests/primitives/tools/codeql_lsp_diagnostics/valid_query_no_errors/after/valid_query.ql	Adds file-based fixture for diagnostics “valid” scenario.
client/integration-tests/primitives/tools/codeql_lsp_diagnostics/syntax_validation/README.md	Adds integration test README for diagnostics “syntax error” scenario.
client/integration-tests/primitives/tools/codeql_lsp_diagnostics/syntax_validation/before/monitoring-state.json	Adds before monitoring-state fixture for diagnostics “syntax error” scenario.
client/integration-tests/primitives/tools/codeql_lsp_diagnostics/syntax_validation/after/monitoring-state.json	Adds after monitoring-state fixture for diagnostics “syntax error” scenario.
client/integration-tests/primitives/tools/codeql_lsp_diagnostics/syntax_validation/before/test_query.ql	Adds file-based fixture for diagnostics “syntax error” scenario.
client/integration-tests/primitives/tools/codeql_lsp_diagnostics/syntax_validation/after/test_query.ql	Adds file-based fixture for diagnostics “syntax error” scenario.
client/integration-tests/primitives/tools/codeql_lsp_diagnostics/semantic_validation/README.md	Adds integration test README for diagnostics “semantic error” scenario.
client/integration-tests/primitives/tools/codeql_lsp_diagnostics/semantic_validation/before/monitoring-state.json	Adds before monitoring-state fixture for diagnostics “semantic error” scenario.
client/integration-tests/primitives/tools/codeql_lsp_diagnostics/semantic_validation/after/monitoring-state.json	Updates monitoring-state fixture to reflect tool rename/description changes.
client/integration-tests/primitives/tools/codeql_lsp_diagnostics/semantic_validation/before/semantic_query.ql	Adds file-based fixture for diagnostics “semantic error” scenario.
client/integration-tests/primitives/tools/codeql_lsp_diagnostics/semantic_validation/after/semantic_query.ql	Adds/updates file-based fixture for diagnostics “semantic error” scenario.
client/integration-tests/primitives/tools/codeql_language_server_eval/semantic_validation/before/monitoring-state.json	Removes obsolete monitoring-state fixture for deprecated tool name.

Comments suppressed due to low confidence (2)

server/src/tools/lsp/lsp-diagnostics.ts:113

workspace_uri is passed through to initialize() without normalization. If callers provide a relative path or a bare directory path (as supported elsewhere), the language server will receive a non-URI root. Consider normalizing workspaceUri to a file:// URL (and resolving relative paths against the configured user workspace dir) before calling initialize().
server/src/tools/lsp/lsp-handlers.ts:77
filePath is documented as absolute but is also resolved against process.cwd(). To keep relative-path resolution consistent with the rest of the server, resolve against getUserWorkspaceDir() (supports CODEQL_MCP_WORKSPACE) and/or update the interface/schema docs to match actual behavior.

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

docs/tools-reference.md

server/src/tools/lsp/lsp-handlers.ts

server/test/src/tools/lsp/lsp-handlers.test.ts

server/src/tools/lsp/lsp-tools.ts

server/src/tools/lsp/lsp-handlers.ts

server/src/lib/query-server.ts

Copilot

Pull request overview

Copilot reviewed 80 out of 86 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (2)

client/integration-tests/primitives/tools/codeql_lsp_diagnostics/syntax_validation/README.md:16

The README claims the .ql file remains unchanged (identical in before/ and after/), but the current fixture has different before/after query contents. Update the fixture or adjust the README so the expected behavior matches the actual test structure.


- `isValid` is `false` with one or more error diagnostics.
- The `test_query.ql` file remains unchanged (identical in before/ and after/).
- Monitoring state updated to record a successful `codeql_lsp_diagnostics` call.

client/integration-tests/primitives/tools/codeql_lsp_diagnostics/semantic_validation/after/monitoring-state.json:25

This monitoring-state.json still records the old parameter shape (query, language, etc.) even though the toolName is now codeql_lsp_diagnostics (which expects ql_code, workspace_uri, search_path, log_level). Update the recorded parameters so the fixture reflects the current tool contract.

server/src/lib/server-manager.ts

server/src/tools/lsp/lsp-handlers.ts

server/src/prompts/ql-lsp-iterative-development.prompt.md

client/integration-tests/primitives/tools/codeql_lsp_diagnostics/semantic_validation/README.md

- Fix race condition in server-manager getOrRestart: serialize concurrent calls per server type using pendingStarts map with async/await pattern - Fix lsp-handlers filePath docstring: document that relative paths are accepted and resolved against getUserWorkspaceDir() - Fix semantic_validation/syntax_validation READMEs: clarify that before/ after .ql files differ (not identical as previously stated) - Fix semantic_validation/after/monitoring-state.json: update parameter shape to use ql_code matching the codeql_lsp_diagnostics tool contract - Add concurrent access serialization test for server-manager

server/src/lib/server-manager.ts

Copilot

Pull request overview

Copilot reviewed 81 out of 87 changed files in this pull request and generated 2 comments.

server/src/lib/query-server.ts

server/src/lib/server-manager.ts

data-douser added 2 commits February 8, 2026 18:00

data-douser self-assigned this Feb 9, 2026

data-douser added documentation Improvements or additions to documentation enhancement New feature or request javascript Pull requests that update javascript code server labels Feb 9, 2026

data-douser marked this pull request as ready for review February 9, 2026 03:28

data-douser requested review from a team and enyil as code owners February 9, 2026 03:28

Copilot AI review requested due to automatic review settings February 9, 2026 03:28

Copilot started reviewing on behalf of data-douser February 9, 2026 03:28 View session

Copilot AI reviewed Feb 9, 2026

View reviewed changes

data-douser added 2 commits February 8, 2026 21:13

Address PR review comments & fix integration tests

e561fa4

Fixes for codeql_lsp_* tool integration tests

d375e41

Copilot AI review requested due to automatic review settings February 9, 2026 13:19

Copilot started reviewing on behalf of data-douser February 9, 2026 13:20 View session

Copilot AI reviewed Feb 9, 2026

View reviewed changes

github-code-quality bot found potential problems Feb 9, 2026

View reviewed changes

server/src/lib/server-manager.ts Fixed Show fixed Hide fixed

Address code-quality PR review feedback

a58953d

Copilot AI review requested due to automatic review settings February 9, 2026 14:35

Copilot started reviewing on behalf of data-douser February 9, 2026 14:35 View session

github-code-quality bot found potential problems Feb 9, 2026

View reviewed changes

server/src/lib/server-manager.ts Dismissed Show dismissed Hide dismissed

Copilot AI reviewed Feb 9, 2026

View reviewed changes

server/src/lib/query-server.ts Show resolved Hide resolved

server/src/lib/server-manager.ts Show resolved Hide resolved

data-douser added this pull request to the merge queue Feb 9, 2026

Merged via the queue into main with commit 7093a4e Feb 9, 2026
23 checks passed

data-douser deleted the dd/mcp-lsp-integration/1 branch February 9, 2026 14:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve MCP server integrations with `codeql execute *-server` servers#29

Improve MCP server integrations with `codeql execute *-server` servers#29
data-douser merged 7 commits intomainfrom
dd/mcp-lsp-integration/1

data-douser commented Feb 9, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

data-douser commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

New LSP Tools

Background Server Manager

Reliability Fixes

Test Infrastructure

Other Changes

Outline of Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

data-douser commented Feb 9, 2026 •

edited

Loading