This README provides documentation for the server subproject of the advanced-security/codeql-development-mcp-server repository. The server subproject implements the actual Model Context Protocol (MCP) server for CodeQL development and is the main component of the repository.

If you're using the distributed release package (downloaded from GitHub Releases), the server is ready to use. See the Getting Started Guide for setup instructions.

The server can run in two modes:

STDIO Mode (recommended for VS Code):

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

HTTP Mode (for debugging):

TRANSPORT_MODE=http node dist/codeql-development-mcp-server.js

Configure the server using environment variables:

The server subproject is structured as follows:

server/
├── dist/                    # Base directory for compiled output
│   ├── codeql-development-mcp-server.js     # Compiled, bundled MCP server entry point
│   └── codeql-development-mcp-server.js.map # Source map for the bundled MCP server
├── src/                     # TypeScript source library code
│   ├── codeql-development-mcp-server.ts     # MCP server entry point
│   ├── lib/                 # Core library code
│   ├── tools/               # Implementation of MCP tools
├── test/                    # Base directory for tests
│   ├── src/                 # Base directory for test source files
│   │   ├── lib/             # Test files for core library code
│   │   ├── tools/           # Test files for MCP tools
├── eslint.config.mjs        # ESLint configuration
├── esbuild.config.js        # esbuild configuration for bundling
├── package.json             # NPM package configuration
├── tsconfig.json            # TypeScript configuration
└── README.md                # This README file

1. Check Node.js version: The server requires Node.js v24.13.0 or later

   node --version

2. Verify the entry point exists:

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

3. Check for missing dependencies: If using the distributed package, ensure node_modules is present

1. Verify CodeQL CLI is installed:

   codeql --version

2. Check CodeQL is in PATH: The server expects codeql to be available in the system PATH, or set CODEQL_PATH to the absolute path of the CodeQL CLI binary

3. Ensure you have a valid database: Most query tools require a CodeQL database

1. Check if port is in use:

   lsof -i :3000

2. Try a different port:

   TRANSPORT_MODE=http HTTP_PORT=8080 node dist/codeql-development-mcp-server.js

See the Getting Started Guide for troubleshooting steps.

• MCP Architecture
• Getting Started Guide
• Tools Reference