Tools Reference

This document provides a comprehensive reference for all tools available in the CodeQL Development MCP Server.

Overview

The MCP server provides tools that wrap CodeQL CLI commands and helper utilities for CodeQL development workflows. Tools are organized into the following categories:

Query Development - Create, compile, and format queries
Query Execution - Run queries and process results
Testing - Run and manage CodeQL tests
Database Operations - Create and analyze databases
Resolution - Resolve paths, dependencies, and metadata
BQRS Processing - Work with query result files
Utility - Helper tools for common workflows

Query Development Tools

codeql_query_compile

Compile CodeQL queries to check for errors.

Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	Path to the query file to compile
`database`	string	No	Database to compile against
`library`	string	No	Additional search paths for libraries

Example:

Compile a query:
- query: /path/to/MyQuery.ql
- database: /path/to/database

codeql_query_format

Format CodeQL queries according to standard conventions.

Parameters:

Parameter	Type	Required	Description
`files`	string[]	Yes	Paths to the query files to format
`in-place`	boolean	No	Whether to modify the query files in place

Example:

Format queries in place:
- files:
  - /path/to/MyQuery.ql
- in-place: true

create_codeql_query

Create a new CodeQL query with proper directory structure and test scaffolding.

Parameters:

Parameter	Type	Required	Description
`queryName`	string	Yes	Name of the query to create
`language`	string	Yes	Target language (e.g., `python`, `javascript`)
`basePath`	string	Yes	Base path for the query
`description`	string	No	Query description

Example:

Create a new query:
- queryName: SqlInjection
- language: python
- basePath: /path/to/queries

Query Execution Tools

codeql_query_run

Execute a CodeQL query against a database.

Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	Path to the query file
`database`	string	Yes	Path to the CodeQL database
`output`	string	No	Output file path for results
`timeout`	number	No	Execution timeout in seconds

Example:

Run a query:
- query: /path/to/MyQuery.ql
- database: /path/to/database
- output: /path/to/results.bqrs

codeql_execute_query_server2

Execute queries using the CodeQL query server for improved performance.

Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	Path to the query file
`database`	string	Yes	Path to the CodeQL database

Example:

Execute with query server:
- query: /path/to/MyQuery.ql
- database: /path/to/database

codeql_database_analyze

Run analysis queries against a CodeQL database.

Parameters:

Parameter	Type	Required	Description
`database`	string	Yes	Path to the CodeQL database
`queries`	string	No	Query suite or pack to run
`format`	string	No	Output format (sarif, csv, etc.)
`output`	string	No	Output file path

Example:

Analyze a database:
- database: /path/to/database
- queries: codeql/python-queries
- format: sarif
- output: /path/to/results.sarif

Testing Tools

codeql_test_run

Run CodeQL unit tests.

Parameters:

Parameter	Type	Required	Description
`path`	string	Yes	Path to test directory or test file
`threads`	number	No	Number of threads to use

Example:

Run tests:
- path: /path/to/tests
- threads: 4

codeql_test_accept

Accept test results as expected output.

Parameters:

Parameter	Type	Required	Description
`path`	string	Yes	Path to test directory

Example:

Accept test results:
- path: /path/to/test

codeql_test_extract

Extract test databases from test source files.

Parameters:

Parameter	Type	Required	Description
`path`	string	Yes	Path to test directory

Example:

Extract test database:
- path: /path/to/test

Database Operations

codeql_database_create

Create a CodeQL database from source code.

Parameters:

Parameter	Type	Required	Description
`source`	string	Yes	Path to source code
`language`	string	Yes	Programming language
`database`	string	Yes	Output database path
`command`	string	No	Build command (if required)

Example:

Create a database:
- source: /path/to/source
- language: python
- database: /path/to/database

Resolution Tools

codeql_resolve_database

Get information about a CodeQL database.

Parameters:

Parameter	Type	Required	Description
`database`	string	Yes	Path to the database

Example:

Resolve database info:
- database: /path/to/database

codeql_resolve_languages

List available CodeQL languages.

Parameters: None

Example:

List supported languages

codeql_resolve_library_path

Resolve library search paths for a query.

Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	Path to the query file

Example:

Resolve library paths:
- query: /path/to/MyQuery.ql

codeql_resolve_metadata

Get metadata for a query.

Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	Path to the query file

Example:

Get query metadata:
- query: /path/to/MyQuery.ql

codeql_resolve_qlref

Resolve a .qlref file to its target query.

Parameters:

Parameter	Type	Required	Description
`qlref`	string	Yes	Path to the `.qlref` file

Example:

Resolve qlref:
- qlref: /path/to/test/MyQuery.qlref

codeql_resolve_queries

Resolve a query suite to individual queries.

Parameters:

Parameter	Type	Required	Description
`suite`	string	Yes	Query suite specification

Example:

Resolve query suite:
- suite: codeql/python-queries

codeql_resolve_tests

Find all tests in a directory.

Parameters:

Parameter	Type	Required	Description
`path`	string	Yes	Path to search for tests

Example:

Find tests:
- path: /path/to/tests

BQRS Processing Tools

codeql_bqrs_decode

Decode a BQRS (Binary Query Result Set) file.

Parameters:

Parameter	Type	Required	Description
`bqrs`	string	Yes	Path to the BQRS file
`format`	string	No	Output format (json, csv, etc.)
`output`	string	No	Output file path

Example:

Decode BQRS file:
- bqrs: /path/to/results.bqrs
- format: json

codeql_bqrs_info

Get information about a BQRS file.

Parameters:

Parameter	Type	Required	Description
`bqrs`	string	Yes	Path to the BQRS file

Example:

Get BQRS info:
- bqrs: /path/to/results.bqrs

codeql_bqrs_interpret

Interpret BQRS results as SARIF or other formats.

Parameters:

Parameter	Type	Required	Description
`bqrs`	string	Yes	Path to the BQRS file
`format`	string	No	Output format
`output`	string	No	Output file path

Example:

Interpret as SARIF:
- bqrs: /path/to/results.bqrs
- format: sarif
- output: /path/to/results.sarif

Utility Tools

find_codeql_query_files

Find all files related to a CodeQL query.

Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	Path to the query file

Example:

Find related files:
- query: /path/to/MyQuery.ql

codeql_pack_install

Install CodeQL pack dependencies.

Parameters:

Parameter	Type	Required	Description
`path`	string	Yes	Path to pack directory

Example:

Install dependencies:
- path: /path/to/pack

codeql_pack_ls

List contents of a CodeQL pack.

Parameters:

Parameter	Type	Required	Description
`path`	string	Yes	Path to pack directory

Example:

List pack contents:
- path: /path/to/pack

codeql_generate_log_summary

Generate a summary of CodeQL evaluator logs.

Parameters:

Parameter	Type	Required	Description
`log`	string	Yes	Path to evaluator log file

Example:

Summarize log:
- log: /path/to/evaluator-log.json

codeql_generate_query_help

Generate documentation for a query.

Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	Path to the query file
`output`	string	No	Output file path

Example:

Generate help:
- query: /path/to/MyQuery.ql
- output: /path/to/MyQuery.md

rank_sarif_results

Rank SARIF results to identify likely true positives and false positives.

Parameters:

Parameter	Type	Required	Description
`sarif`	string	Yes	Path to SARIF file

Example:

Rank results:
- sarif: /path/to/results.sarif

Common Workflows

Creating and Testing a New Query

Use create_codeql_query to scaffold the query structure
Edit the generated query file
Use codeql_query_compile to check for errors
Use codeql_test_run to run tests
Use codeql_test_accept to accept correct results

Running Analysis on a Codebase

Use codeql_database_create to build a database
Use codeql_query_run or codeql_database_analyze to run queries
Use codeql_bqrs_decode or codeql_bqrs_interpret to process results

Debugging Query Issues

Use codeql_resolve_library_path to check library resolution
Use codeql_resolve_metadata to verify query metadata
Use codeql_generate_log_summary to analyze performance

FilesExpand file tree

tools-reference.md

Latest commit

History

tools-reference.md

File metadata and controls

Tools Reference

Overview

Query Development Tools

codeql_query_compile

codeql_query_format

create_codeql_query

Query Execution Tools

codeql_query_run

codeql_execute_query_server2

codeql_database_analyze

Testing Tools

codeql_test_run

codeql_test_accept

codeql_test_extract

Database Operations

codeql_database_create

Resolution Tools

codeql_resolve_database

codeql_resolve_languages

codeql_resolve_library_path

codeql_resolve_metadata

codeql_resolve_qlref

codeql_resolve_queries

codeql_resolve_tests

BQRS Processing Tools

codeql_bqrs_decode

codeql_bqrs_info

codeql_bqrs_interpret

Utility Tools

find_codeql_query_files

codeql_pack_install

codeql_pack_ls

codeql_generate_log_summary

codeql_generate_query_help

rank_sarif_results

Common Workflows

Creating and Testing a New Query

Running Analysis on a Codebase

Debugging Query Issues

Related Documentation