Skip to content

Commit 8a76f86

Browse files
data-douserdata-douser
committed
Update client and server README.md docs
Updates the user-facing server/README.md to be a useful for external use, where the server/README.md doc is now used as the home paga for published npmjs.com packages for codeql-development-mcp-server.
1 parent 4f5f2ca commit 8a76f86

File tree

2 files changed

+102
-87
lines changed

2 files changed

+102
-87
lines changed

‎client/README.md‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -24,14 +24,6 @@ This is a compatibility issue between the CodeQL CLI version being used and the
2424
- Some pack dependency resolution warnings are expected in test environment
2525
- Exit code 1 for `codeql query format --check-only` indicates "file would change" and is considered success
2626

27-
## Current Status
28-
29-
- ✅ Basic HTTP connectivity testing
30-
- ✅ TypeScript project setup with testing infrastructure
31-
- ✅ Build pipeline with ESBuild
32-
- ✅ GitHub Actions workflow for integration testing
33-
- ⚠️ Full MCP SDK integration pending (SDK import issues being resolved)
34-
3527
## Usage
3628

3729
### CLI Interface

‎server/README.md‎

Lines changed: 102 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,113 +1,136 @@
1-
# advanced-security/codeql-development-mcp-server:server/README.md
1+
# codeql-development-mcp-server
22

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.
54
6-
## For End Users
5+
## Quick Start
76

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
98

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)
1112

12-
The server can run in two modes:
13+
### Install and configure
1314

14-
**STDIO Mode (recommended for VS Code):**
15+
1. Add to your VS Code `mcp.json`:
1516

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` |
1922

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+
```
2134

22-
```bash
23-
TRANSPORT_MODE=http node dist/codeql-development-mcp-server.js
24-
```
35+
2. Install CodeQL pack dependencies:
2536

26-
### Configuration
37+
```bash
38+
npm install -g codeql-development-mcp-server
39+
codeql-development-mcp-server-setup-packs
40+
```
2741

28-
Configure the server using environment variables:
42+
> **Windows:** The setup-packs command requires a Bash-compatible shell (e.g., Git Bash or WSL).
2943
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.
3645

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.
6047

61-
## Troubleshooting
48+
## What's Included
6249

63-
### Server Won't Start
50+
### 34 Tools
6451

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:
6653

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 |
7064

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)
7266

73-
```bash
74-
ls dist/codeql-development-mcp-server.js
75-
```
67+
### 10 Prompts
7668

77-
3. **Check for missing dependencies**: If using the distributed package, ensure `node_modules` is present
69+
Guided workflows for common CodeQL development tasks:
7870

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 |
8083

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)
8285

83-
```bash
84-
codeql --version
85-
```
86+
### Resources
8687

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:
8889

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
9094

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)
9296

93-
1. **Check if port is in use**:
97+
## Supported Languages
9498

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` |
98110

99-
2. **Try a different port**:
111+
## Configuration
100112

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
104126

105-
### VS Code Integration Issues
127+
## Documentation
106128

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)
108133

109-
## References
134+
## License
110135

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).

0 commit comments

Comments
 (0)