codeql-development-mcp-server 2.24.1-rc1 → 2.24.2-rc1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/README.md +102 -79
  2. package/dist/codeql-development-mcp-server.js +61144 -4850
  3. package/dist/codeql-development-mcp-server.js.map +4 -4
  4. package/package.json +8 -6
  5. package/ql/actions/tools/src/codeql-pack.yml +1 -1
  6. package/ql/cpp/tools/src/codeql-pack.yml +1 -1
  7. package/ql/csharp/tools/src/codeql-pack.yml +1 -1
  8. package/ql/go/tools/src/codeql-pack.yml +1 -1
  9. package/ql/java/tools/src/codeql-pack.yml +1 -1
  10. package/ql/javascript/tools/src/codeql-pack.yml +1 -1
  11. package/ql/python/tools/src/codeql-pack.yml +1 -1
  12. package/ql/ruby/tools/src/codeql-pack.yml +1 -1
  13. package/ql/swift/tools/src/codeql-pack.yml +1 -1
package/README.md CHANGED
@@ -1,113 +1,136 @@
1
- # advanced-security/codeql-development-mcp-server:server/README.md
1
+ # codeql-development-mcp-server
2
2
 
3
- This README provides documentation for the `server` subproject of the `advanced-security/codeql-development-mcp-server` repository.
4
- The `server` subproject implements the actual Model Context Protocol (MCP) server for CodeQL development and is the main component of the repository.
3
+ > An [MCP](https://modelcontextprotocol.io/) server for AI-assisted CodeQL query development — providing tools, prompts, and resources for writing, testing, and optimizing CodeQL queries.
5
4
 
6
- ## For End Users
5
+ ## Quick Start
7
6
 
8
- If you're using the distributed release package (downloaded from GitHub Releases), the server is ready to use. See the [Getting Started Guide](../docs/getting-started.md) for setup instructions.
7
+ ### Prerequisites
9
8
 
10
- ### Running the Server
9
+ - **Node.js** v24.13.0+ ([nodejs.org](https://nodejs.org/))
10
+ - **CodeQL CLI** ([github.com/github/codeql-cli-binaries](https://github.com/github/codeql-cli-binaries/releases))
11
+ - **VS Code** with GitHub Copilot extension (only required for this "Quick Start" guide)
11
12
 
12
- The server can run in two modes:
13
+ ### Install and configure
13
14
 
14
- **STDIO Mode (recommended for VS Code):**
15
+ 1. Add to your VS Code `mcp.json`:
15
16
 
16
- ```bash
17
- node dist/codeql-development-mcp-server.js
18
- ```
17
+ | OS | Location |
18
+ | ------- | -------------------------------------------------- |
19
+ | macOS | `~/Library/Application Support/Code/User/mcp.json` |
20
+ | Windows | `%APPDATA%\Code\User\mcp.json` |
21
+ | Linux | `~/.config/Code/User/mcp.json` |
19
22
 
20
- **HTTP Mode (for debugging):**
23
+ ```json
24
+ {
25
+ "servers": {
26
+ "ql-mcp": {
27
+ "command": "npx",
28
+ "args": ["-y", "codeql-development-mcp-server"],
29
+ "type": "stdio"
30
+ }
31
+ }
32
+ }
33
+ ```
21
34
 
22
- ```bash
23
- TRANSPORT_MODE=http node dist/codeql-development-mcp-server.js
24
- ```
35
+ 2. Install CodeQL pack dependencies:
25
36
 
26
- ### Configuration
37
+ ```bash
38
+ npm install -g codeql-development-mcp-server
39
+ codeql-development-mcp-server-setup-packs
40
+ ```
27
41
 
28
- Configure the server using environment variables:
42
+ > **Windows:** The setup-packs command requires a Bash-compatible shell (e.g., Git Bash or WSL).
29
43
 
30
- | Variable | Description | Default |
31
- | ---------------- | -------------------------------------- | -------- |
32
- | `CODEQL_PATH` | Absolute path to the CodeQL CLI binary | `codeql` |
33
- | `TRANSPORT_MODE` | `stdio` or `http` | `stdio` |
34
- | `HTTP_PORT` | HTTP port (when using HTTP mode) | `3000` |
35
- | `DEBUG` | Enable debug logging | `false` |
44
+ 3. Open Command Palette in VS Code → **"MCP: List MCP Servers"** → confirm `ql-mcp` appears. Use the options available via "MCP: List MCP Servers" to start, stop, restart, and/or reconfigure the `ql-mcp` server in VS Code.
36
45
 
37
- ## Subproject Structure
38
-
39
- The `server` subproject is structured as follows:
40
-
41
- ```text
42
- server/
43
- ├── dist/ # Base directory for compiled output
44
- │ ├── codeql-development-mcp-server.js # Compiled, bundled MCP server entry point
45
- │ └── codeql-development-mcp-server.js.map # Source map for the bundled MCP server
46
- ├── src/ # TypeScript source library code
47
- │ ├── codeql-development-mcp-server.ts # MCP server entry point
48
- │ ├── lib/ # Core library code
49
- │ ├── tools/ # Implementation of MCP tools
50
- ├── test/ # Base directory for tests
51
- │ ├── src/ # Base directory for test source files
52
- │ │ ├── lib/ # Test files for core library code
53
- │ │ ├── tools/ # Test files for MCP tools
54
- ├── eslint.config.mjs # ESLint configuration
55
- ├── esbuild.config.js # esbuild configuration for bundling
56
- ├── package.json # NPM package configuration
57
- ├── tsconfig.json # TypeScript configuration
58
- └── README.md # This README file
59
- ```
46
+ See the [Getting Started Guide](https://github.com/advanced-security/codeql-development-mcp-server/blob/main/docs/getting-started.md) for detailed instructions and alternative installation methods.
60
47
 
61
- ## Troubleshooting
48
+ ## What's Included
62
49
 
63
- ### Server Won't Start
50
+ ### 34 Tools
64
51
 
65
- 1. **Check Node.js version**: The server requires Node.js v24.13.0 or later
52
+ Wraps the full CodeQL development lifecycle as MCP tools:
66
53
 
67
- ```bash
68
- node --version
69
- ```
54
+ | Category | Tools |
55
+ | --------------------- | ----------------------------------------------------------------------------------------------------------------- |
56
+ | **Query execution** | `codeql_query_run`, `codeql_query_compile`, `codeql_database_analyze`, `codeql_database_create` |
57
+ | **Testing** | `codeql_test_run`, `codeql_test_extract`, `codeql_test_accept` |
58
+ | **BQRS results** | `codeql_bqrs_decode`, `codeql_bqrs_info`, `codeql_bqrs_interpret` |
59
+ | **Pack management** | `codeql_pack_install`, `codeql_pack_ls` |
60
+ | **Code navigation** | `codeql_lsp_completion`, `codeql_lsp_definition`, `codeql_lsp_diagnostics`, `codeql_lsp_references` |
61
+ | **Query scaffolding** | `create_codeql_query`, `find_codeql_query_files`, `validate_codeql_query`, `quick_evaluate` |
62
+ | **Profiling** | `profile_codeql_query`, `codeql_generate_log-summary` |
63
+ | **Resolution** | `codeql_resolve_database`, `codeql_resolve_languages`, `codeql_resolve_queries`, `codeql_resolve_tests`, and more |
70
64
 
71
- 2. **Verify the entry point exists**:
65
+ Full reference: [Tools](https://github.com/advanced-security/codeql-development-mcp-server/blob/main/docs/ql-mcp/tools.md)
72
66
 
73
- ```bash
74
- ls dist/codeql-development-mcp-server.js
75
- ```
67
+ ### 10 Prompts
76
68
 
77
- 3. **Check for missing dependencies**: If using the distributed package, ensure `node_modules` is present
69
+ Guided workflows for common CodeQL development tasks:
78
70
 
79
- ### CodeQL Tools Return Errors
71
+ | Prompt | Description |
72
+ | ------------------------------ | ------------------------------------------------------------------------------- |
73
+ | `test_driven_development` | End-to-end TDD workflow for CodeQL queries |
74
+ | `ql_tdd_basic` | Write tests first, implement query, iterate until tests pass |
75
+ | `ql_tdd_advanced` | TDD with AST visualization, control flow, and call graph analysis |
76
+ | `tools_query_workflow` | Use PrintAST, PrintCFG, CallGraphFrom, CallGraphTo to understand code structure |
77
+ | `ql_lsp_iterative_development` | Interactive development with LSP completions, navigation, and diagnostics |
78
+ | `sarif_rank_false_positives` | Identify likely false positives in query results |
79
+ | `sarif_rank_true_positives` | Identify likely true positives in query results |
80
+ | `explain_codeql_query` | Generate explanations and Mermaid evaluation diagrams |
81
+ | `document_codeql_query` | Generate standardized markdown documentation for a query |
82
+ | `workshop_creation_workflow` | Create multi-exercise workshops for teaching CodeQL query development |
80
83
 
81
- 1. **Verify CodeQL CLI is installed**:
84
+ Full reference: [Prompts](https://github.com/advanced-security/codeql-development-mcp-server/blob/main/docs/ql-mcp/prompts.md)
82
85
 
83
- ```bash
84
- codeql --version
85
- ```
86
+ ### Resources
86
87
 
87
- 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
88
+ Static learning materials and per-language references served to AI assistants:
88
89
 
89
- 3. **Ensure you have a valid database**: Most query tools require a CodeQL database
90
+ - **CodeQL Getting Started** / **Query Basics** — Introductory guides
91
+ - **Security Templates** / **Performance Patterns** — Ready-to-use templates and best practices
92
+ - **Language AST References** — For actions, cpp, csharp, go, java, javascript, python, ql, ruby
93
+ - **Language Security Patterns** — For cpp, csharp, go, javascript, python
90
94
 
91
- ### HTTP Mode Not Working
95
+ Full reference: [Resources](https://github.com/advanced-security/codeql-development-mcp-server/blob/main/docs/ql-mcp/resources.md)
92
96
 
93
- 1. **Check if port is in use**:
97
+ ## Supported Languages
94
98
 
95
- ```bash
96
- lsof -i :3000
97
- ```
99
+ | Language | CodeQL Identifier |
100
+ | --------------------- | ----------------- |
101
+ | GitHub Actions | `actions` |
102
+ | C/C++ | `cpp` |
103
+ | C# | `csharp` |
104
+ | Go | `go` |
105
+ | Java/Kotlin | `java` |
106
+ | JavaScript/TypeScript | `javascript` |
107
+ | Python | `python` |
108
+ | Ruby | `ruby` |
109
+ | Swift | `swift` |
98
110
 
99
- 2. **Try a different port**:
111
+ ## Configuration
100
112
 
101
- ```bash
102
- TRANSPORT_MODE=http HTTP_PORT=8080 node dist/codeql-development-mcp-server.js
103
- ```
113
+ | Variable | Description | Default |
114
+ | ---------------- | -------------------------------------- | -------- |
115
+ | `CODEQL_PATH` | Absolute path to the CodeQL CLI binary | `codeql` |
116
+ | `TRANSPORT_MODE` | `stdio` or `http` | `stdio` |
117
+ | `HTTP_PORT` | HTTP port (when using HTTP mode) | `3000` |
118
+ | `DEBUG` | Enable debug logging | `false` |
119
+
120
+ ## Troubleshooting
121
+
122
+ - **Tool query errors (e.g., PrintAST fails):** Run `codeql-development-mcp-server-setup-packs` to install CodeQL pack dependencies
123
+ - **Server not listed in VS Code:** Verify `mcp.json` configuration, restart VS Code
124
+ - **CodeQL errors:** Run `codeql --version` to confirm CLI is installed and in PATH
125
+ - **Permission denied:** Check file permissions on the package directory
104
126
 
105
- ### VS Code Integration Issues
127
+ ## Documentation
106
128
 
107
- See the [Getting Started Guide](../docs/getting-started.md#troubleshooting) for troubleshooting steps.
129
+ - [Getting Started Guide](https://github.com/advanced-security/codeql-development-mcp-server/blob/main/docs/getting-started.md)
130
+ - [Tools Reference](https://github.com/advanced-security/codeql-development-mcp-server/blob/main/docs/ql-mcp/tools.md)
131
+ - [Prompts Reference](https://github.com/advanced-security/codeql-development-mcp-server/blob/main/docs/ql-mcp/prompts.md)
132
+ - [Resources Reference](https://github.com/advanced-security/codeql-development-mcp-server/blob/main/docs/ql-mcp/resources.md)
108
133
 
109
- ## References
134
+ ## License
110
135
 
111
- - [MCP Architecture](https://modelcontextprotocol.io/docs/learn/architecture)
112
- - [Getting Started Guide](../docs/getting-started.md)
113
- - [Tools Reference](../docs/tools-reference.md)
136
+ See [LICENSE](https://github.com/advanced-security/codeql-development-mcp-server/blob/main/LICENSE).