# CodeQL LSP MCP Server (Python)

[![CI](https://github.com/flyfei-cmd/codeql-lsp-mcp-python/actions/workflows/ci.yml/badge.svg)](https://github.com/flyfei-cmd/codeql-lsp-mcp-python/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A local [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes
CodeQL language intelligence to AI coding agents. It starts the language server bundled
with the CodeQL CLI and provides MCP tools for completion, hover, definitions, references,
diagnostics, formatting, and in-memory file updates.

This is an independent, unofficial project. It is not affiliated with or endorsed by
GitHub. The CodeQL CLI is distributed separately under GitHub's own terms.

## Why this exists

LLMs can generate plausible QL that does not compile. This bridge gives an agent the same
kind of syntax and semantic feedback an editor gets, without turning the MCP server into a
general shell wrapper around the CodeQL CLI.

## Tools

| Tool | Purpose |
| --- | --- |
| `codeql_complete` | Get paginated completions at a position |
| `codeql_hover` | Retrieve documentation and type information |
| `codeql_definition` | Navigate to a symbol definition |
| `codeql_references` | Find references to a symbol |
| `codeql_diagnostics` | Collect syntax and semantic diagnostics |
| `codeql_format` | Request full-document or range formatting |
| `codeql_update_file` | Update an open document in memory |

Positions are zero-based, following the Language Server Protocol.

## Requirements

- Python 3.10-3.12
- CodeQL CLI on `PATH`, or an absolute path in `CODEQL_PATH`
- A workspace containing the QL files and packs you want to inspect

Download the complete CodeQL bundle so the CLI has compatible queries and libraries. Use
of CodeQL is subject to the [GitHub CodeQL terms and conditions](https://securitylab.github.com/tools/codeql/license/).

## Install

From a checkout:

```bash
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
```

Verify the prerequisites:

```bash
codeql version
codeql execute language-server --help
```

## Configure an MCP client

The server uses stdio by default. Replace the example paths with absolute paths on your
machine:

```json
{
  "mcpServers": {
    "codeql": {
      "command": "/absolute/path/to/codeql-lsp-mcp-python/.venv/bin/codeql-lsp-mcp",
      "env": {
        "CODEQL_PATH": "/absolute/path/to/codeql/codeql",
        "WORKSPACE_PATH": "/absolute/path/to/your/ql-workspace"
      }
    }
  }
}
```

You can also run it directly:

```bash
CODEQL_PATH=codeql WORKSPACE_PATH=/path/to/ql-workspace codeql-lsp-mcp
```

Set `CODEQL_LSP_TRACE=1` to enable verbose LSP protocol tracing while debugging.

## Example tool call

```json
{
  "name": "codeql_diagnostics",
  "arguments": {
    "file_uri": "file:///absolute/path/to/ql-workspace/query.ql"
  }
}
```

For unsaved content, call `codeql_update_file` before requesting completions, hover, or
diagnostics. Files must be inside `WORKSPACE_PATH`.

## Development

```bash
python -m pip install -e '.[dev]'
ruff check .
pytest
python -m build
```

Unit tests do not require CodeQL. A local smoke test can be run with:

```bash
CODEQL_PATH=codeql WORKSPACE_PATH=/path/to/ql-workspace \
  pytest -m integration
```

## Design notes

`multilspy` does not natively expose CodeQL, so this project contains a small adapter for
the CodeQL language server. The adapter is intentionally isolated under
`language_servers/` and pins the known-compatible `multilspy` release.

The tool interface was inspired by the CodeQL LSP interface described in the FineNib /
QLCoder research. See [QLCoder: A Query Synthesizer for Static Analysis of Security
Vulnerabilities](https://arxiv.org/abs/2511.08462). A separate TypeScript implementation
from that research team is available at
[`neuralprogram/codeql-lsp-mcp`](https://github.com/neuralprogram/codeql-lsp-mcp).

## License

[MIT](LICENSE). CodeQL itself is not included in this repository and has separate license
terms.