codeql-development-mcp-server 2.24.1-rc1

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "codeql-development-mcp-server",
+  "version": "2.24.1-rc1",
+  "description": "An MCP server supporting LLM requests for CodeQL development tools and resources.",
+  "main": "dist/codeql-development-mcp-server.js",
+  "type": "module",
+  "bin": {
+    "codeql-development-mcp-server": "dist/codeql-development-mcp-server.js",
+    "codeql-development-mcp-server-setup-packs": "scripts/setup-packs.sh"
+  },
+  "files": [
+    "dist/",
+    "ql/actions/tools/src/",
+    "ql/cpp/tools/src/",
+    "ql/csharp/tools/src/",
+    "ql/go/tools/src/",
+    "ql/java/tools/src/",
+    "ql/javascript/tools/src/",
+    "ql/python/tools/src/",
+    "ql/ruby/tools/src/",
+    "ql/swift/tools/src/",
+    "scripts/setup-packs.sh",
+    "package.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": [
+    "codeql",
+    "development",
+    "llm",
+    "mcp",
+    "model-context-protocol",
+    "ql",
+    "sast",
+    "security",
+    "static-analysis",
+    "typescript"
+  ],
+  "author": "@github/ps-codeql",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/advanced-security/codeql-development-mcp-server.git",
+    "directory": "server"
+  },
+  "homepage": "https://github.com/advanced-security/codeql-development-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/advanced-security/codeql-development-mcp-server/issues"
+  },
+  "engines": {
+    "node": ">=24.13.0",
+    "npm": ">=11.6.2"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "cors": "^2.8.6",
+    "dotenv": "^17.2.4",
+    "express": "^5.2.1",
+    "js-yaml": "^4.1.1",
+    "lowdb": "^7.0.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.2.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "esbuild": "^0.27.3",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "npm run clean && npm run lint && npm run bundle",
+    "build:all": "npm run build && npm run test:ql:fail-fast",
+    "bundle": "node esbuild.config.js",
+    "clean": "rm -rf dist .tmp",
+    "dev:stdio": "npm run build && TRANSPORT_MODE=stdio node dist/codeql-development-mcp-server.js",
+    "dev:http": "npm run build && TRANSPORT_MODE=http node dist/codeql-development-mcp-server.js",
+    "format": "prettier --write 'src/**/*.ts'",
+    "lint": "eslint src test --ext .ts",
+    "lint:fix": "eslint src test --ext .ts --fix",
+    "start": "npm run build && node dist/codeql-development-mcp-server.js",
+    "test": "npm run build && npm run test:ts:coverage",
+    "test:coverage": "npm run test:ts:coverage",
+    "test:ql": "./scripts/run-query-unit-tests.sh",
+    "test:ql:fail-fast": "./scripts/run-query-unit-tests.sh --fail-fast",
+    "test:ts": "vitest --run",
+    "test:ts:coverage": "vitest --run --coverage",
+    "test:watch": "vitest --watch"
+  }
+}

package/ql/README.md

@@ -0,0 +1,57 @@
+# CodeQL Language Query Structure
+
+This directory contains language-specific CodeQL queries -- organized by programming `<language>` -- used in the implementation and/or testing of (CodeQL) MCP server tools.
+
+Each `<language>` subdirectory is expected to follow a standardized structure to ensure consistency and maintainability, though there is flexibility to accommodate different subsets of queries and/or tests for each code `<language>`.
+
+## Directory Structure
+
+Each subdirectory of the `server/ql/<language>/` must implement the following structure:
+
+```text
+server/ql/<language>/
+├── tools/
+│   ├── src/
+│   │   └── <query-name>.ql          # Query implementation files
+│   └── test/
+│       ├── codeql-pack.yml          # Test pack configuration
+│       ├── codeql-pack.lock.yml     # Lock file for dependencies
+│       └── <query-name>/            # Test directory for each query
+│           ├── <query-name>.qlref   # Reference to the query being tested
+│           ├── <query-name>.expected # Expected test output
+│           ├── <test-files>         # Test source code files
+│           └── <query-name>.testproj/ # Optional test project directory
+```
+
+## Language Support
+
+Currently supported languages:
+
+- `actions/` - GitHub Actions workflows
+- `cpp/` - C/C++
+- `csharp/` - C#
+- `go/` - Go
+- `java/` - Java
+- `javascript/` - JavaScript/TypeScript
+- `python/` - Python
+- `ruby/` - Ruby
+- `swift/` - Swift
+
+## Testing
+
+The `server/scripts/run-query-unit-tests.sh` script automatically discovers and tests all language directories that follow this structure. It will:
+
+- Iterate through all subdirectories in `server/ql/`
+- Look for a `tools/` directory in each language
+- Run `codeql test run` on the `tools/test/` directory
+- Count and report the number of `.qlref` files found
+
+No manual configuration is required when adding new languages - the test script will automatically include them.
+
+## Best Practices
+
+- **Consistent naming**: Use descriptive names for queries that reflect their purpose
+- **Comprehensive testing**: Each query should have corresponding test cases
+- **Documentation**: Include comments in query files explaining their purpose and usage
+- **Test coverage**: Ensure test cases cover edge cases and expected behaviors
+- **Pack configuration**: Maintain proper `codeql-pack.yml` files for dependency management

package/ql/actions/tools/src/PrintAST/PrintAST.ql

@@ -0,0 +1,40 @@
+/**
+ * @name Print AST for actions
+ * @description Outputs a representation of the Abstract Syntax Tree for specified source files.
+ * @id actions/tools/print-ast
+ * @kind graph
+ * @tags ast
+ */
+
+private import codeql.actions.ideContextual.IDEContextual
+import codeql.actions.ideContextual.printAst
+private import codeql.actions.Ast
+
+/**
+ * Configuration for PrintAST that uses test directory structure (maintains original behavior for unit tests).
+ */
+class Cfg extends PrintAstConfiguration {
+  override predicate shouldPrintNode(PrintAstNode n) {
+    super.shouldPrintNode(n) and
+    // Only include source files with a `test` directory structure
+    (
+      // For a file located under some `test/*/.github/workflows` directory structure
+      n.getLocation()
+          .getFile()
+          .getParentContainer()
+          .getParentContainer()
+          .getParentContainer()
+          .getParentContainer()
+          .getBaseName() = "test"
+      or
+      // For a file located under some `test/*/*/action.yml` directory structure
+      n.getLocation()
+          .getFile()
+          .getParentContainer()
+          .getParentContainer()
+          .getParentContainer()
+          .getBaseName() = "test" and
+      n.getLocation().getFile().getBaseName() = "action.yml"
+    )
+  }
+}

package/ql/actions/tools/src/PrintCFG/PrintCFG.md

@@ -0,0 +1,53 @@
+# Print CFG for GitHub Actions
+
+Produces a representation of a file's Control Flow Graph (CFG) for GitHub Actions workflows and composite actions.
+
+## Overview
+
+The Control Flow Graph represents the order in which steps and jobs are executed in a GitHub Actions workflow. Each node in the graph represents a control-flow element (job, step, or action component), and edges represent possible execution paths between them.
+
+This query outputs all CFG nodes and their successor relationships for GitHub Actions YAML files, which is useful for understanding workflow execution flow and analyzing action dependencies.
+
+## Use Cases
+
+This query is primarily used for:
+
+- Visualizing workflow execution flow
+- Understanding job and step dependencies
+- Debugging workflow execution issues
+- Analysis of action execution paths
+- IDE integration for workflow visualization
+
+## Example
+
+The following GitHub Actions workflow demonstrates control flow through jobs and steps:
+
+```yaml
+name: Example Workflow
+on: [push]
+jobs:
+  test: # COMPLIANT - Job creates CFG node
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2 # COMPLIANT - Step creates CFG node
+      - name: Run tests # COMPLIANT - Steps execute sequentially
+        run: echo "Testing"
+```
+
+In the resulting CFG:
+
+- Each job creates a CFG scope
+- Steps within a job execute sequentially
+- Actions and run commands create control flow nodes
+
+## Output Format
+
+The query produces two relations:
+
+- `nodes(Node, string, string)`: Each CFG node with its label
+- `edges(Node, Node)`: Successor relationships between nodes
+
+## References
+
+- [GitHub Actions Workflow Syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)
+- [CodeQL Control Flow Graph](https://codeql.github.com/docs/writing-codeql-queries/about-control-flow-in-codeql/)

package/ql/actions/tools/src/PrintCFG/PrintCFG.ql

@@ -0,0 +1,23 @@
+/**
+ * @name Print CFG for actions
+ * @description Produces a representation of a file's Control Flow Graph for specified source files.
+ * @id actions/tools/print-cfg
+ * @kind graph
+ * @tags cfg
+ */
+
+import codeql.actions.Ast
+private import codeql.actions.Cfg
+import codeql.actions.controlflow.BasicBlocks
+
+/**
+ * Configuration for PrintCFG that outputs all CFG nodes and edges.
+ */
+query predicate nodes(Node node, string property, string value) {
+  property = "semmle.label" and
+  value = node.toString()
+}
+
+query predicate edges(Node pred, Node succ) {
+  pred.getASuccessor() = succ
+}

package/ql/actions/tools/src/codeql-pack.lock.yml

@@ -0,0 +1,32 @@
+---
+lockVersion: 1.0.0
+dependencies:
+  codeql/actions-all:
+    version: 0.4.27
+  codeql/concepts:
+    version: 0.0.15
+  codeql/controlflow:
+    version: 2.0.25
+  codeql/dataflow:
+    version: 2.0.25
+  codeql/javascript-all:
+    version: 2.6.21
+  codeql/mad:
+    version: 1.0.41
+  codeql/regex:
+    version: 1.0.41
+  codeql/ssa:
+    version: 2.0.17
+  codeql/threat-models:
+    version: 1.0.41
+  codeql/tutorial:
+    version: 1.0.41
+  codeql/typetracking:
+    version: 2.0.25
+  codeql/util:
+    version: 2.0.28
+  codeql/xml:
+    version: 1.0.41
+  codeql/yaml:
+    version: 1.0.41
+compiled: false

package/ql/actions/tools/src/codeql-pack.yml

@@ -0,0 +1,6 @@
+name: advanced-security/ql-mcp-actions-tools-src
+version: 2.24.1-rc1
+description: 'Queries for codeql-development-mcp-server tools for actions language'
+library: false
+dependencies:
+  codeql/actions-all: 0.4.27

package/ql/cpp/tools/src/CallGraphFrom/CallGraphFrom.ql

@@ -0,0 +1,55 @@
+/**
+ * @name Call Graph From for cpp
+ * @description Displays calls made from a specified function, showing the call graph outbound from the source function.
+ * @id cpp/tools/call-graph-from
+ * @kind problem
+ * @problem.severity recommendation
+ * @tags call-graph
+ */
+
+import cpp
+
+/**
+ * Gets the source function name for which to generate the call graph.
+ * Can be a single function name or comma-separated list of function names.
+ */
+external string sourceFunction();
+
+/**
+ * Gets a single source function name from the comma-separated list.
+ */
+string getSourceFunctionName() {
+  result = sourceFunction().splitAt(",").trim()
+}
+
+/**
+ * Gets a function by matching against the selected source function names.
+ */
+Function getSourceFunction() {
+  exists(string selectedFunc |
+    selectedFunc = getSourceFunctionName() and
+    (
+      // Match by exact function name
+      result.getName() = selectedFunc or
+      // Match by qualified name
+      result.getQualifiedName() = selectedFunc
+    )
+  )
+}
+
+from FunctionCall call, Function source, Function callee
+where
+  call.getTarget() = callee and
+  call.getEnclosingFunction() = source and
+  (
+    // Use external predicate if available
+    source = getSourceFunction()
+    or
+    // Fallback for unit tests: include test files
+    (
+      not exists(getSourceFunction()) and
+      source.getFile().getParentContainer().getParentContainer().getBaseName() = "test"
+    )
+  )
+select call,
+  "Call from `" + source.getQualifiedName() + "` to `" + callee.getQualifiedName() + "`"

package/ql/cpp/tools/src/CallGraphTo/CallGraphTo.ql

@@ -0,0 +1,55 @@
+/**
+ * @name Call Graph To for cpp
+ * @description Displays calls made to a specified function, showing the call graph inbound to the target function.
+ * @id cpp/tools/call-graph-to
+ * @kind problem
+ * @problem.severity recommendation
+ * @tags call-graph
+ */
+
+import cpp
+
+/**
+ * Gets the target function name for which to generate the call graph.
+ * Can be a single function name or comma-separated list of function names.
+ */
+external string targetFunction();
+
+/**
+ * Gets a single target function name from the comma-separated list.
+ */
+string getTargetFunctionName() {
+  result = targetFunction().splitAt(",").trim()
+}
+
+/**
+ * Gets a function by matching against the selected target function names.
+ */
+Function getTargetFunction() {
+  exists(string selectedFunc |
+    selectedFunc = getTargetFunctionName() and
+    (
+      // Match by exact function name
+      result.getName() = selectedFunc or
+      // Match by qualified name
+      result.getQualifiedName() = selectedFunc
+    )
+  )
+}
+
+from FunctionCall call, Function target, Function caller
+where
+  call.getTarget() = target and
+  call.getEnclosingFunction() = caller and
+  (
+    // Use external predicate if available
+    target = getTargetFunction()
+    or
+    // Fallback for unit tests: include test files
+    (
+      not exists(getTargetFunction()) and
+      target.getFile().getParentContainer().getParentContainer().getBaseName() = "test"
+    )
+  )
+select call,
+  "Call to `" + target.getQualifiedName() + "` from `" + caller.getQualifiedName() + "`"

package/ql/cpp/tools/src/PrintAST/PrintAST.ql

@@ -0,0 +1,57 @@
+/**
+ * @name Print AST for cpp
+ * @description Outputs a representation of the Abstract Syntax Tree for specified source files.
+ * @id cpp/tools/print-ast
+ * @kind graph
+ * @tags ast
+ */
+
+import cpp
+import semmle.code.cpp.PrintAST
+
+/**
+ * Gets the source files to generate AST from.
+ * Can be a single file path or comma-separated list of file paths.
+ */
+external string selectedSourceFiles();
+
+/**
+ * Gets a single source file from the comma-separated list.
+ */
+string getSelectedSourceFile() {
+  result = selectedSourceFiles().splitAt(",").trim()
+}
+
+/**
+ * Gets a file by matching against the selected source file paths.
+ */
+File getSelectedFile() {
+  exists(string selectedFile |
+    selectedFile = getSelectedSourceFile() and
+    (
+      // Match by exact relative path from source root
+      result.getRelativePath() = selectedFile or
+      // Match by file name if no path separators
+      (not selectedFile.matches("%/%") and result.getBaseName() = selectedFile) or
+      // Match by ending path component
+      result.getAbsolutePath().suffix(result.getAbsolutePath().length() - selectedFile.length()) = selectedFile
+    )
+  )
+}
+
+/**
+ * Configuration for PrintAST that uses external predicates to specify source files.
+ * Falls back to test directory structure when external predicates are not available.
+ */
+class Cfg extends PrintAstConfiguration {
+  override predicate shouldPrintDeclaration(Declaration decl) {
+    // Use external predicate if available
+    decl.getFile() = getSelectedFile()
+    or
+    // Fallback for unit tests: include test files
+    (
+      not exists(getSelectedFile()) and
+      decl.getFile().getParentContainer().getParentContainer().getBaseName() = "test"
+    )
+  }
+}

package/ql/cpp/tools/src/PrintCFG/PrintCFG.md

@@ -0,0 +1,56 @@
+# Print CFG for C++
+
+Produces a representation of a file's Control Flow Graph (CFG) for specified source files.
+
+## Overview
+
+The Control Flow Graph represents the order in which statements and expressions are executed in a program. Each node in the graph represents a control-flow element (statement or expression), and edges represent possible execution paths between them.
+
+This query outputs all CFG nodes and their successor relationships for C++ code, which is useful for understanding program execution flow, debugging control flow issues, and analyzing code paths.
+
+## Use Cases
+
+This query is primarily used for:
+
+- Visualizing program execution flow
+- Understanding complex branching logic
+- Debugging control flow issues
+- Analysis of code paths and reachability
+- IDE integration for control flow visualization
+
+## Example
+
+The following C++ code demonstrates control flow through conditional statements and loops:
+
+```cpp
+void example(int x) {
+    int result = 0;
+    if (x > 0) {                     // COMPLIANT - Branching creates CFG edges
+        result = 1;
+    } else {
+        result = -1;
+    }
+
+    for (int i = 0; i < 3; i++) {    // COMPLIANT - Loop creates cyclic CFG
+        result = result + i;
+    }
+}
+```
+
+In the resulting CFG:
+
+- The `if` condition creates two outgoing edges (true/false branches)
+- The `for` loop creates a cycle back to the condition check
+- Each statement and expression connects to its successor in evaluation order
+
+## Output Format
+
+The query produces two relations:
+
+- `nodes(ControlFlowNode, string, string)`: Each CFG node with its label
+- `edges(ControlFlowNode, ControlFlowNode)`: Successor relationships between nodes
+
+## References
+
+- [C++ Control Structures](https://en.cppreference.com/w/cpp/language/statements)
+- [CodeQL Control Flow Graph](https://codeql.github.com/docs/writing-codeql-queries/about-control-flow-in-codeql/)

package/ql/cpp/tools/src/PrintCFG/PrintCFG.ql

@@ -0,0 +1,22 @@
+/**
+ * @name Print CFG for cpp
+ * @description Produces a representation of a file's Control Flow Graph for specified source files.
+ * @id cpp/tools/print-cfg
+ * @kind graph
+ * @tags cfg
+ */
+
+import cpp
+import semmle.code.cpp.controlflow.ControlFlowGraph
+
+/**
+ * Configuration for PrintCFG that outputs all CFG nodes and edges.
+ */
+query predicate nodes(ControlFlowNode node, string property, string value) {
+  property = "semmle.label" and
+  value = node.toString()
+}
+
+query predicate edges(ControlFlowNode pred, ControlFlowNode succ) {
+  pred.getASuccessor() = succ
+}

package/ql/cpp/tools/src/codeql-pack.lock.yml

@@ -0,0 +1,28 @@
+---
+lockVersion: 1.0.0
+dependencies:
+  codeql/controlflow:
+    version: 2.0.25
+  codeql/cpp-all:
+    version: 7.1.0
+  codeql/dataflow:
+    version: 2.0.25
+  codeql/mad:
+    version: 1.0.41
+  codeql/quantum:
+    version: 0.0.19
+  codeql/rangeanalysis:
+    version: 1.0.41
+  codeql/ssa:
+    version: 2.0.17
+  codeql/tutorial:
+    version: 1.0.41
+  codeql/typeflow:
+    version: 1.0.41
+  codeql/typetracking:
+    version: 2.0.25
+  codeql/util:
+    version: 2.0.28
+  codeql/xml:
+    version: 1.0.41
+compiled: false

package/ql/cpp/tools/src/codeql-pack.yml

@@ -0,0 +1,6 @@
+name: advanced-security/ql-mcp-cpp-tools-src
+version: 2.24.1-rc1
+description: 'Queries for codeql-development-mcp-server tools for cpp language'
+library: false
+dependencies:
+  codeql/cpp-all: 7.1.0

package/ql/csharp/tools/src/CallGraphFrom/CallGraphFrom.ql

@@ -0,0 +1,50 @@
+/**
+ * @name Call Graph From for csharp
+ * @description Displays calls made from a specified method, showing the call graph outbound from the source method.
+ * @id csharp/tools/call-graph-from
+ * @kind problem
+ * @problem.severity recommendation
+ * @tags call-graph
+ */
+
+import csharp
+
+/**
+ * Gets the source method name for which to generate the call graph.
+ * Can be a single method name or comma-separated list of method names.
+ */
+external string sourceFunction();
+
+/**
+ * Gets a single source method name from the comma-separated list.
+ */
+string getSourceFunctionName() {
+  result = sourceFunction().splitAt(",").trim()
+}
+
+/**
+ * Gets a method by matching against the selected source method names.
+ */
+Callable getSourceFunction() {
+  exists(string selectedFunc |
+    selectedFunc = getSourceFunctionName() and
+    result.getName() = selectedFunc
+  )
+}
+
+from Call call, Callable source, Callable callee
+where
+  call.getEnclosingCallable() = source and
+  call.getTarget() = callee and
+  (
+    // Use external predicate if available
+    source = getSourceFunction()
+    or
+    // Fallback for unit tests: include test files
+    (
+      not exists(getSourceFunction()) and
+      source.getFile().getParentContainer().getParentContainer().getBaseName() = "test"
+    )
+  )
+select call,
+  "Call from `" + source.getName() + "` to `" + callee.getName() + "`"