|
1 | | -# VS Code Extension for `codeql-development-mcp-server` |
| 1 | +# CodeQL Development MCP Server — VS Code Extension |
2 | 2 |
|
3 | | -TODO |
| 3 | +A VS Code extension that automatically installs, configures, and manages the [CodeQL Development MCP Server](https://github.com/advanced-security/codeql-development-mcp-server). It bridges the [`GitHub.vscode-codeql`](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-codeql) extension with AI assistants by exposing CodeQL databases, query results, and MRVA results to the MCP server. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +- **VS Code** `^1.109.0` |
| 8 | +- **Node.js** `>=24.13.0` |
| 9 | +- **[CodeQL for VS Code](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-codeql)** — declared as an `extensionDependency` and must be installed first. |
| 10 | + |
| 11 | +## Installation |
| 12 | + |
| 13 | +### From `.vsix` |
| 14 | + |
| 15 | +```bash |
| 16 | +code --install-extension codeql-development-mcp-server.vsix |
| 17 | +``` |
| 18 | + |
| 19 | +Or in VS Code: **Extensions** sidebar → `⋯` menu → **Install from VSIX…** → select the file. |
| 20 | + |
| 21 | +### From Source |
| 22 | + |
| 23 | +```bash |
| 24 | +cd extensions/vscode |
| 25 | +npm run package |
| 26 | +code --install-extension codeql-development-mcp-server.vsix |
| 27 | +``` |
| 28 | + |
| 29 | +## What It Does |
| 30 | + |
| 31 | +On activation (`onStartupFinished`), the extension: |
| 32 | + |
| 33 | +1. **Auto-installs** the `codeql-development-mcp-server` npm package (unless `codeql-mcp.autoInstall` is `false`). |
| 34 | +2. **Registers an MCP server definition** (`ql-mcp`) so VS Code's Copilot/MCP integration can discover and launch it. |
| 35 | +3. **Watches** the CodeQL extension's storage paths for databases, query results, and MRVA results, passing them to the MCP server as environment variables. |
| 36 | + |
| 37 | +## Configuration |
| 38 | + |
| 39 | +All settings are under the `codeql-mcp` namespace in VS Code settings: |
| 40 | + |
| 41 | +| Setting | Default | Description | |
| 42 | +| ------------------------------------------ | ---------- | ------------------------------------------------------------------- | |
| 43 | +| `codeql-mcp.autoInstall` | `true` | Auto-install/update the MCP server on activation. | |
| 44 | +| `codeql-mcp.serverVersion` | `"latest"` | npm version to install (`"latest"` for most recent). | |
| 45 | +| `codeql-mcp.serverCommand` | `"node"` | Command to launch the server. Override to `"npx"` or a custom path. | |
| 46 | +| `codeql-mcp.serverArgs` | `[]` | Custom args. When empty, the bundled entry point is used. | |
| 47 | +| `codeql-mcp.watchCodeqlExtension` | `true` | Watch for databases and results from the CodeQL extension. | |
| 48 | +| `codeql-mcp.additionalEnv` | `{}` | Extra environment variables passed to the server process. | |
| 49 | +| `codeql-mcp.additionalDatabaseDirs` | `[]` | Additional directories to search for CodeQL databases. | |
| 50 | +| `codeql-mcp.additionalMrvaRunResultsDirs` | `[]` | Additional directories containing MRVA run results. | |
| 51 | +| `codeql-mcp.additionalQueryRunResultsDirs` | `[]` | Additional directories containing query run results. | |
| 52 | + |
| 53 | +## Commands |
| 54 | + |
| 55 | +Available from the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`): |
| 56 | + |
| 57 | +| Command | Description | |
| 58 | +| ------------------------------------------------- | ----------------------------------------------- | |
| 59 | +| **CodeQL MCP: Reinstall MCP Server** | Re-download and install the server package. | |
| 60 | +| **CodeQL MCP: Reinstall CodeQL Tool Query Packs** | Re-install the bundled CodeQL tool query packs. | |
| 61 | +| **CodeQL MCP: Show Status** | Display current server status. | |
| 62 | +| **CodeQL MCP: Show Logs** | Open the server log output. | |
| 63 | + |
| 64 | +## Development |
| 65 | + |
| 66 | +### npm Scripts |
| 67 | + |
| 68 | +| Script | What it does | When to use | |
| 69 | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- | |
| 70 | +| `npm run package` | **Builds everything and produces the `.vsix`**. Internally runs `vscode:prepublish` (clean → lint → bundle → bundle:server) then `vsce package`. | **Building a distributable `.vsix`.** | |
| 71 | +| `npm run build` | `clean` → `lint` → `bundle` (extension only, no server). | Development builds without packaging. | |
| 72 | +| `npm run bundle` | esbuild the extension (no lint, no clean). | Fast iteration during development. | |
| 73 | +| `npm run watch` | Rebuild the extension on file changes. | Active development. | |
| 74 | +| `npm run test` | Run unit tests with Vitest. | Validating changes. | |
| 75 | +| `npm run test:coverage` | Run unit tests with coverage. | CI / pre-merge validation. | |
| 76 | +| `npm run lint` | Run ESLint on `src/` and `test/`. | Checking code style. | |
| 77 | + |
| 78 | +> **Note:** `vscode:prepublish` is a lifecycle hook invoked automatically by `vsce package` — you should not need to run it directly. |
| 79 | +
|
| 80 | +### Project Structure |
| 81 | + |
| 82 | +```text |
| 83 | +extensions/vscode/ |
| 84 | +├── src/ |
| 85 | +│ ├── extension.ts # Extension entry point (activate/deactivate) |
| 86 | +│ ├── bridge/ # Watches CodeQL extension storage paths |
| 87 | +│ ├── codeql/ # CodeQL CLI resolution |
| 88 | +│ ├── common/ # Shared utilities |
| 89 | +│ └── server/ # MCP server lifecycle management |
| 90 | +├── test/ # Vitest unit tests |
| 91 | +├── esbuild.config.js # Extension bundler config |
| 92 | +├── scripts/bundle-server.js # Copies MCP server into the extension |
| 93 | +└── package.json |
| 94 | +``` |
0 commit comments