Package Exports

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

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (codeql-development-mcp-server) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

codeql-development-mcp-server

An MCP server for AI-assisted CodeQL query development — providing tools, prompts, and resources for writing, testing, and optimizing CodeQL queries.

Quick Start

Prerequisites

Node.js v24.13.0+ (nodejs.org)
CodeQL CLI (github.com/github/codeql-cli-binaries)
VS Code with GitHub Copilot extension (only required for this "Quick Start" guide)

Install and configure

Add to your VS Code mcp.json:

OS	Location
macOS	`~/Library/Application Support/Code/User/mcp.json`
Windows	`%APPDATA%\Code\User\mcp.json`
Linux	`~/.config/Code/User/mcp.json`

{
  "servers": {
    "ql-mcp": {
      "command": "npx",
      "args": ["-y", "codeql-development-mcp-server"],
      "type": "stdio"
    }
  }
}

Install CodeQL pack dependencies:
```
npm install -g codeql-development-mcp-server
codeql-development-mcp-server-setup-packs
```
Windows: The setup-packs command requires a Bash-compatible shell (e.g., Git Bash or WSL).
Open Command Palette in VS Code → "MCP: List MCP Servers" → confirm ql-mcp appears. Use the options available via "MCP: List MCP Servers" to start, stop, restart, and/or reconfigure the ql-mcp server in VS Code.

See the Getting Started Guide for detailed instructions and alternative installation methods.

What's Included

34 Tools

Wraps the full CodeQL development lifecycle as MCP tools:

Category	Tools
Query execution	`codeql_query_run`, `codeql_query_compile`, `codeql_database_analyze`, `codeql_database_create`
Testing	`codeql_test_run`, `codeql_test_extract`, `codeql_test_accept`
BQRS results	`codeql_bqrs_decode`, `codeql_bqrs_info`, `codeql_bqrs_interpret`
Pack management	`codeql_pack_install`, `codeql_pack_ls`
Code navigation	`codeql_lsp_completion`, `codeql_lsp_definition`, `codeql_lsp_diagnostics`, `codeql_lsp_references`
Query scaffolding	`create_codeql_query`, `find_codeql_query_files`, `validate_codeql_query`, `quick_evaluate`
Profiling	`profile_codeql_query`, `codeql_generate_log-summary`
Resolution	`codeql_resolve_database`, `codeql_resolve_languages`, `codeql_resolve_queries`, `codeql_resolve_tests`, and more

Full reference: Tools

10 Prompts

Guided workflows for common CodeQL development tasks:

Prompt	Description
`test_driven_development`	End-to-end TDD workflow for CodeQL queries
`ql_tdd_basic`	Write tests first, implement query, iterate until tests pass
`ql_tdd_advanced`	TDD with AST visualization, control flow, and call graph analysis
`tools_query_workflow`	Use PrintAST, PrintCFG, CallGraphFrom, CallGraphTo to understand code structure
`ql_lsp_iterative_development`	Interactive development with LSP completions, navigation, and diagnostics
`sarif_rank_false_positives`	Identify likely false positives in query results
`sarif_rank_true_positives`	Identify likely true positives in query results
`explain_codeql_query`	Generate explanations and Mermaid evaluation diagrams
`document_codeql_query`	Generate standardized markdown documentation for a query
`workshop_creation_workflow`	Create multi-exercise workshops for teaching CodeQL query development

Full reference: Prompts

Resources

Static reference materials and per-language references served to AI assistants:

Server Overview / Server Queries — MCP server orientation and bundled tools queries reference
Server Tools / Server Prompts — Complete tool and prompt references
Query Basics / Test-Driven Development — QL query writing guide and TDD workflow
Security Templates / Performance Patterns — Multi-language security templates and profiling guidance
Language AST References — For actions, cpp, csharp, go, java, javascript, python, ruby
Language Security Patterns — For cpp, csharp, go, javascript, python

Full reference: Resources

Supported Languages

Language	CodeQL Identifier
GitHub Actions	`actions`
C/C++	`cpp`
C#	`csharp`
Go	`go`
Java/Kotlin	`java`
JavaScript/TypeScript	`javascript`
Python	`python`
Ruby	`ruby`
Swift	`swift`

Configuration

Variable	Description	Default
`CODEQL_PATH`	Absolute path to the CodeQL CLI binary	`codeql`
`TRANSPORT_MODE`	`stdio` or `http`	`stdio`
`HTTP_PORT`	HTTP port (when using HTTP mode)	`3000`
`DEBUG`	Enable debug logging	`false`

Troubleshooting

Tool query errors (e.g., PrintAST fails): Run codeql-development-mcp-server-setup-packs to install CodeQL pack dependencies
Server not listed in VS Code: Verify mcp.json configuration, restart VS Code
CodeQL errors: Run codeql --version to confirm CLI is installed and in PATH
Permission denied: Check file permissions on the package directory

Documentation

License

See LICENSE.