使用说明

项目简介

CodeQL MCP Server 是一个 MCP (Model Context Protocol) 服务器，它包装了 CodeQL 查询服务器的功能，使得像 Cursor 这样的 LLM 代码编辑器或 AI Agent 能够通过 MCP 协议与 CodeQL 进行结构化的交互。该服务器提供了一系列工具，允许 LLM 客户端注册 CodeQL 数据库，执行 CodeQL 查询，解码查询结果，以及定位代码符号等，从而为 LLM 应用提供强大的代码分析能力。

主要功能点

注册 CodeQL 数据库: 允许 LLM 客户端注册一个或多个 CodeQL 数据库，以便后续的查询和分析操作。
执行 CodeQL 查询: 支持执行完整的 CodeQL 查询，用于代码缺陷检测、安全漏洞分析等。
快速评估代码片段: 允许快速评估代码中的符号（类或谓词），例如在编辑器中选中一段代码后，快速查看其 CodeQL 分析结果。
解码 BQRS 结果文件: 支持将 CodeQL 查询结果 '.bqrs' 文件解码为 JSON 或 CSV 格式，方便 LLM 客户端解析和展示。
定位代码符号位置: 能够查找类或谓词在代码文件中的位置，为代码导航和理解提供便利。

安装步骤

安装依赖: 推荐使用 'uv' 或 'pip' 安装项目依赖。

使用 'uv':

uv pip install -r requirements.txt

使用 'pip':

pip install fastmcp httpx

安装 CodeQL CLI: 确保你的系统 'PATH' 环境变量中包含 'codeql' 可执行文件。或者，你可能需要在 'codeqlclient.py' 文件中硬编码 'codeql' 的路径。
准备 CodeQL 数据库: 你需要预先创建好 CodeQL 数据库，并获取数据库的路径。

服务器配置

为了让 MCP 客户端（例如 Cursor）连接到 CodeQL MCP Server，你需要在客户端中配置服务器信息。以下是一个典型的 JSON 格式配置，你需要将其添加到 MCP 客户端的配置文件中。

例如，对于 Cursor，你需要编辑 '.cursor/config.json' 文件，添加如下 'mcpServers' 配置：

{
  "mcpServers": {
    "CodeQL": {
      "url": "http://localhost:8000/sse"
    }
  }
}

配置参数说明:

server name: 'CodeQL' - 服务器名称，在客户端中用于标识该服务器。
command: 'uv run mcp run server.py' - 启动 CodeQL MCP Server 的命令。确保你的环境中可以执行 'uv' 命令，并且 'server.py' 文件路径正确。如果你没有使用 'uv'，可以使用 'python server.py' 命令，但可能需要调整依赖安装方式。
args: '["-t", "sse"]' - 传递给启动命令的参数。 '-t sse' 指定使用 SSE (Server-Sent Events) 传输协议，这是 Cursor 等客户端常用的协议。

注意:

确保 CodeQL MCP Server 启动后监听的 URL (例如 'http://localhost:8000/sse') 与客户端配置的 'url' 一致。
你可能需要根据实际情况调整启动命令和参数，例如指定不同的端口或传输协议。

基本使用方法

启动服务器: 在终端中运行以下命令启动 CodeQL MCP Server：
```
uv run mcp run server.py -t sse
```
服务器默认监听 'http://localhost:8000/sse' 地址。
配置客户端: 按照 "服务器配置" 章节的说明，配置你的 MCP 客户端（例如 Cursor），使其连接到运行中的 CodeQL MCP Server。
在客户端中使用: 连接成功后，你就可以在 MCP 客户端中通过自然语言指令或图形界面来调用 CodeQL MCP Server 提供的工具，例如注册数据库、执行查询等。具体的调用方式取决于 MCP 客户端的功能和界面。例如，在 Cursor 中，你可能可以直接在聊天框中输入自然语言指令，Cursor 会解析指令并调用相应的 MCP 工具。

重要提示:

为了正常使用 CodeQL MCP Server，你需要确保已经安装了 CodeQL CLI 工具，并且 CodeQL 数据库已经正确创建和准备好。
根据你的 CodeQL 查询和数据库的大小，查询执行时间可能会有所不同。

关键词