advanced-security · data-douser · Apr 7, 2026 · Apr 8, 2026 · Apr 9, 2026 · Apr 11, 2026
@@ -1,5 +1,5 @@
 {
-  "image": "mcr.microsoft.com/devcontainers/typescript-node:24",
+  "image": "mcr.microsoft.com/devcontainers/typescript-node:25",
   "customizations": {
     "vscode": {
       "extensions": [

@@ -29,7 +29,7 @@ inputs:
   go-version:
     description: 'Go version to install'
     required: false
-    default: '1.21'
+    default: '1.25.0'
   dotnet-version:
     description: '.NET version to install'
     required: false

@@ -32,7 +32,23 @@ All command paths are relative to the root of the `advanced-security/codeql-deve
 Get the current list of all tools available in the CodeQL Development MCP Server:
 
 ```sh
-node client/src/ql-mcp-client.js list tools --format json
+gh-ql-mcp-client list tools --format json
+```
+
+### List QL MCP Server Prompts
+
+Get the current list of all prompts available in the CodeQL Development MCP Server:
+
+```sh
+gh-ql-mcp-client list prompts --format json
+```
+
+### List QL MCP Server Resources
+
+Get the current list of all resources available in the CodeQL Development MCP Server:
+
+```sh
+gh-ql-mcp-client list resources --format json
 ```
 
 ## References

@@ -31,13 +31,13 @@ My `ql-mcp-tool-developer` agent:
 
 - Implements new tools in `server/src/` with TypeScript.
 - Creates comprehensive unit tests in `server/test/` for all new/modified tools.
-- Validates tool behavior with integration tests using `client/src/ql-mcp-client.js`.
+- Validates tool behavior with integration tests using the Go client (`make -C client test-integration`).
 - Ensures tools properly handle errors and edge cases.
 - Documents tool parameters, return types, and usage patterns.
 - Tests MCP server functionality:
   - Runs unit tests: `npm test --workspace=server`.
-  - Runs integration tests: `client/scripts/run-integration-tests.sh`.
-  - Manually validates tools using: `client/src/ql-mcp-client.js`.
+  - Runs integration tests: `make -C client test-integration`.
+  - Manually validates tools using: `gh-ql-mcp-client integration-tests --mode stdio --tools <tool_name>`.
   - Verifies server startup/shutdown: `server/dist/codeql-development-mcp-server.js`.
 - Maintains server documentation:
   - Keeps `server/QL-MCP-SERVER.md` synchronized with tool changes.

@@ -15,7 +15,7 @@ My `ql-mcp-tool-tester` agent:
 - Focuses specifically on validating the functionality of the tools/primitives of the latest (developer) version of the CodeQL Development MCP Server, using actual CodeQL packs, queries, and query unit tests.
 - Utilizes the environment provided by `.github/workflows/copilot-setup-steps.yml` with pre-installed `codeql` CLI.
 - Understands how to:
-  - Use the CodeQL Development MCP **Client** located at `client/src/ql-mcp-client.js` to interact with the MCP server (e.g. start/stop the server, list available tools, list available prompts, list available resources, etc.).
+  - Use the Go MCP **Client** (`gh-ql-mcp-client`) to interact with the MCP server (e.g. run integration tests, connect over stdio or HTTP).
   - Use the Agent Skills defined under `.github/skills/**` for creating, updating, and testing custom CodeQL queries using the tools of the CodeQL Development MCP Server.
   - **Validate AST/CFG tools queries** using the [`validate-ql-mcp-server-tools-queries`](../skills/validate-ql-mcp-server-tools-queries/SKILL.md) skill to ensure `PrintAST`, `PrintCFG`, `CallGraphFrom`, and `CallGraphTo` queries return **non-empty, meaningful output**.
   - Serially test the "exercises" and/or "solutions" from a given CodeQL development workshop, as long as the workshop uses a directory and file structure compatible with the [`create-codeql-query-development-workshop`](../skills/create-codeql-query-development-workshop/) skill, with the goal of using a known good (e.g. example) workshop to validate MCP tool functionality in complex development scenarios using real CodeQL packs, queries, and query unit tests.

@@ -0,0 +1,36 @@
+---
+applyTo: 'client/**/*.go'
+description: 'Instructions for MCP client Go source code files.'
+---
+
+# Copilot Instructions for `client/**/*.go` code files
+
+## PURPOSE
+
+The `client/` directory implements `gh-ql-mcp-client`, a Go CLI that combines GitHub Code Scanning REST API operations (via `go-gh`) with the CodeQL Development MCP Server's SARIF analysis tools (via `mcp-go`). It serves as both a standalone CLI / `gh` extension for Code Scanning alert lifecycle management and as an integration test runner for MCP server primitives.
+
+## REQUIREMENTS
+
+- ALWAYS use modern Go idioms and standard library conventions.
+- ALWAYS follow best practices for implementing secure Go code.
+- ALWAYS order imports with standard library first, then external packages, then internal packages.
+- ALWAYS follow a test-driven development (TDD) approach — write Go tests before implementing new functionality.
+- **ALWAYS run `npm run build-and-test` from the repo root directory and ensure it passes completely before committing any changes. This is MANDATORY and must be verified before every commit.**
+- ALWAYS fix lint issues by running `make -C client lint` before committing changes.
+- **ALWAYS run `make -C client test-unit` and ensure all Go unit tests pass before committing changes to client code.**
+- ALWAYS reference the [client_integration_tests.instructions.md](./client_integration_tests.instructions.md) and [client/integration-tests/README.md](../../client/integration-tests/README.md) files when implementing or modifying integration tests for MCP server primitives.
+
+## PREFERENCES
+
+- PREFER using Cobra subcommands for CLI structure (`client/cmd/`).
+- PREFER keeping each command in its own file (e.g., `client/cmd/code_scanning_list_alerts.go`).
+- PREFER the `internal/` package layout for non-exported packages (`github/`, `mcp/`, `testing/`).
+- PREFER table-driven tests with `t.Run` subtests.
+- PREFER simple integration tests with `test-config.json` fixtures over complex programmatic setup.
+- PREFER building on the existing integration test approach rather than implementing a new approach.
+
+## CONSTRAINTS
+
+- NEVER leave any trailing whitespace on any line.
+- NEVER guess at what an MCP server primitive is supposed to do; instead, look up its source code in `server/src/**/*.ts` files.
+- NEVER use `os.TempDir()`, `/tmp`, or any OS-level temporary directory — use the project-local `.tmp/` directory via `{{tmpdir}}` in test fixtures.
@@ -9,14 +9,14 @@ description: 'Instructions for working with client-side integration tests for th
 
 This file contains instructions for working with test files in the `client/integration-tests/` directory of the `codeql-development-mcp-client` repository.
 
-The purpose of the entire `client/**` implementation is to provide integration tests for the MCP server primitives, as implemented in `server/src/**/*.ts` files. The `client/integration-tests/**` directory contains a directory structur that reflects the endpoints of the MCP server primitives under test, where a given parent test directory should contain child/leaf test subdirectories for expected contents of some file(s) "before" versus "after" calling the MCP server primitive (e.g. MCP server tool) under test.
+The purpose of the entire `client/**` implementation is to provide integration tests for the MCP server primitives, as implemented in `server/src/**/*.ts` files, and to serve as a Go CLI (`gh-ql-mcp-client`) for Code Scanning alert lifecycle management. The `client/integration-tests/**` directory contains a directory structure that reflects the endpoints of the MCP server primitives under test, where a given parent test directory should contain child/leaf test subdirectories for expected contents of some file(s) "before" versus "after" calling the MCP server primitive (e.g. MCP server tool) under test.
 
 ## REQUIREMENTS
 
 - **ALWAYS run `npm run build-and-test` from the repo root directory and ensure it passes completely before committing any changes. This is MANDATORY and must be verified before every commit.**
-- **ALWAYS run `npm test` from the `client/` directory and ensure all integration tests pass before committing changes to integration tests.**
+- **ALWAYS run `make -C client test` from the repo root directory and ensure all Go unit tests and integration tests pass before committing changes to integration tests.**
 - ALWAYS fix lint errors by running `npm run lint:fix` from the repo root directory before committing changes.
-- ALWAYS define "before" and "after" files for `monitoring-state.json`, plus any other files used as integration test inputs (before) and outputs (after). If a file is used as an input but is not modified by the MCP server tool under test, then `ex_tool/ex_test/before/example_file.ex` should have identical contents to `ex_tool/ex_test/after/example_file.ex`.
+- ALWAYS define `test-config.json` or `before/monitoring-state.json` (with embedded `parameters`) for each test case to supply tool arguments to the Go test runner.
 - ALWAYS follow the structure for integration tests as described in the [client/integration-tests/README.md](../../client/integration-tests/README.md) file.
 - ALWAYS obey the `Requirements for Integration Tests` as described in the [client/integration-tests/README.md](../../client/integration-tests/README.md) file.
 

@@ -58,49 +58,53 @@ npm run test
 
 #### Starting and Stopping the QL MCP Server for Client Integration Tests
 
-QL MCP Client integration tests require the QL MCP Server to be running. You can start the server in a separate terminal window using:
+For HTTP mode integration tests, the QL MCP Server must be running. You can start the server using the shell scripts:
 
 ```bash
-## From the `client/` directory use `npm run server:start && npm run server:wait`.
-## From the root of the repository use:
-npm run server:start -w client && npm run server:wait -w client
+client/scripts/start-server.sh
+client/scripts/wait-for-server.sh
 ```
 
-To stop the server after running the integration tests, use:
+To stop the server after running the integration tests:
 
 ```bash
-## From the `client/` directory use `npm run server:stop`.
-## From the root of the repository use:
-npm run server:stop -w client
+client/scripts/stop-server.sh
 ```
 
+For stdio mode, the Go client spawns the server automatically — no manual start/stop is needed.
+
 #### Fixing Client Integration Tests for the QL MCP Server
 
-Client integration tests are executed via the `client/src/ql-mcp-client.js` script.
+Client integration tests are executed via the Go binary `gh-ql-mcp-client`.
 
-To get help on using the MCP Client script, including help for the `integration-tests` subcommand, run:
+To get help on using the MCP Client binary, including help for the `integration-tests` subcommand, run:
 
 ```bash
-node src/ql-mcp-client.js --help
+gh-ql-mcp-client --help
 ```
 
-When focusing specifically on fixing client integration tests, it makes more sense to change directories to `cd client/` and then run the integration tests directly using `node src/ql-mcp-client.js integration-tests`.
+When focusing specifically on fixing client integration tests, build the binary and run the integration tests directly:
+
+```bash
+make -C client build
+gh-ql-mcp-client integration-tests --mode stdio --no-install-packs
+```
 
 Because integration tests can be time-consuming, you can run specific tests or tools as needed using the following commands:
 
 ```bash
 # Run all integration tests with default settings
-node src/ql-mcp-client.js integration-tests
+gh-ql-mcp-client integration-tests --mode stdio --no-install-packs
 
 # Run tests for specific tools
-node src/ql-mcp-client.js integration-tests --tools codeql_query_run
+gh-ql-mcp-client integration-tests --mode stdio --tools codeql_query_run --no-install-packs
 
-# Run specific tests for a tool with custom timeout
-node src/ql-mcp-client.js integration-tests --tools codeql_query_run --tests basic_query_run,javascript_tools_print_ast --timeout 600
+# Run specific tests for a tool
+gh-ql-mcp-client integration-tests --mode stdio --tools codeql_query_run --tests basic_query_run --no-install-packs
 ```
 
 ## References
 
-- [`package.json`](../../package.json) - The main `package.json` file that defines the `scripts` for building and testing the MCP Server, with references to the `server/` and `client/` workspaces.
+- [`package.json`](../../package.json) - The main `package.json` file that defines the `scripts` for building and testing the MCP Server, with references to the `server/` workspace and `make -C client` targets.
 - [`server/package.json`](../../server/package.json) - The `package.json` file in the `server/` workspace that defines the build and test scripts specific to the MCP Server.
-- [`client/package.json`](../../client/package.json) - The `package.json` file in the `client/` workspace that defines the integration test scripts for the MCP Client.
+- [`client/Makefile`](../../client/Makefile) - The Makefile in the `client/` directory that defines build, test, lint, and cross-compile targets for the Go CLI.
@@ -329,7 +329,7 @@ All `logger.info/warn/error/debug` methods write to **stderr** (`console.error`)
 
 ### CODEQL_PATH Environment Variable
 
-The MCP server resolves the CodeQL CLI binary at startup via `resolveCodeQLBinary()` in `server/src/lib/cli-executor.ts`. When `CODEQL_PATH` is set to an absolute path pointing to a valid `codeql` binary, the server uses that binary for all CodeQL CLI operations instead of searching `PATH`. This is validated per-OS in `.github/workflows/client-integration-tests.yml` (`codeql-path-tests` job).
+The MCP server resolves the CodeQL CLI binary at startup via `resolveCodeQLBinary()` in `server/src/lib/cli-executor.ts`. When `CODEQL_PATH` is set to an absolute path pointing to a valid `codeql` binary, the server uses that binary for all CodeQL CLI operations instead of searching `PATH`. This is validated per-OS in `.github/workflows/build-and-test-client.yml` (`codeql-path-tests` job).
 
 ### STDIO Transport and stdin EOF