ql-mcp-client rewrite: Phases 1 & 2 — Replace ql-mcp-client.js with Go implementation (#223)

* Initial plan

* Phase 1: Update documentation and GitHub config for Go-based client

Update all .github config files, documentation, workflows, and package.json
to reflect the intended Go-based ql-mcp-client architecture. No Go source
code is introduced — only documentation, config, and a stub Makefile.

- Create .github/instructions/client_go.instructions.md for Go conventions
- Update client_src_js.instructions.md to Go guidance
- Update client_integration_tests.instructions.md for Go test runner
- Update agent files to reference Go client instead of JS client
- Update ql-mcp-server-fix-build-and-test.prompt.md with make commands
- Add actions/setup-go to CI workflows
- Rewrite client/README.md and CLI-USAGE.md for gh-ql-mcp-client
- Update client/integration-tests/README.md for Go test runner
- Update docs/testing.md to describe Go MCP client
- Update package.json to use make -C client targets, remove client workspace
- Add stub client/Makefile with go.mod-conditional targets

Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/f5595942-48af-4847-8d28-fba34a17ba76

Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>

* Update client/.gitignore for go ql-mcp-client

* Replace JavaScript client with Go binary and integration test runner (#221)

* Initial plan

* Replace JavaScript client with Go binary and integration test runner

- Remove client/src/ directory with all JS files (ql-mcp-client.js and 14 library modules)
- Remove client/package.json and client/eslint.config.mjs
- Add Go module (go.mod, go.sum) with cobra and mcp-go dependencies
- Add CLI entry point (main.go) and root Cobra command (cmd/root.go)
- Add CLI helpers (cmd/helpers.go) and integration test command (cmd/integration_tests.go)
- Add MCP client library (internal/mcp/client.go) with stdio and HTTP transport
- Add integration test runner (internal/testing/runner.go, params.go)
- Add comprehensive unit tests for all packages (16 tests, all passing)
- Update Makefile to remove go.mod guards (Go source now available)
- Update run-integration-tests.sh to build and use Go binary
- Update test-config.json logDir paths for custom_log_directory tests

Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/8c006672-cf7e-4045-9488-f6d97fafe2f2

Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>

* Final validation complete

Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/8c006672-cf7e-4045-9488-f6d97fafe2f2

Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>

* Revert unrelated go.mod changes in server/ql/go/tools/test/

Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/8c006672-cf7e-4045-9488-f6d97fafe2f2

Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>

* Replace actual repo reference with placeholder in helpers_test.go

Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/86c1cb26-2977-409f-ace0-aabc4fc9cee7

Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: Nathan Randall <70299490+data-douser@users.noreply.github.com>

* Remove client_src_js.instructions.md

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: Nathan Randall <70299490+data-douser@users.noreply.github.com>

* Address PR review feedback

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: Nathan Randall <70299490+data-douser@users.noreply.github.com>

* Improve ql-mcp-client from PR feedback

* Fix "--no-install-packs" in client integration test runner

* Fixes for failing client integration tests

* Fix extension mcp-tool-e2e.integration.test.ts

* More fixes for PR review feedback

* Fix client-integration-tests.yml Windows job

* More fixes for PR review feedback

* Updates for compatibility with main-merged PRs

* Fix client-integration-tests for extract dbs

* Address PR review feedback: fix Close() kill, remove enableAnnotationTools setting, record skipped results, fix schema default, clarify changelog

Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/a90a53a5-b2ad-4775-8b61-f11d16b33749

Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>

* Revert test-integration to skip pack install by default, add test-integration-with-packs for explicit pack setup

Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/a90a53a5-b2ad-4775-8b61-f11d16b33749

Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>

* Address review thread 4071470992: path check, changelog, timeout help, error message, cross-platform test, output path sandboxing

Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/0666a5dd-b460-4e6e-9749-f729c46f0b62

Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>

---------

Signed-off-by: Nathan Randall <70299490+data-douser@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

.github/agents/ql-agent-skills-developer.md

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

.github/agents/ql-mcp-tool-developer.md

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

.github/agents/ql-mcp-tool-tester.md

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

.github/instructions/client_go.instructions.md

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

.github/instructions/client_integration_tests.instructions.md

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

.github/instructions/client_src_js.instructions.md

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

.github/prompts/ql-mcp-server-fix-build-and-test.prompt.md

@@ -52,6 +52,12 @@ jobs:
           cache: 'npm'
           node-version-file: '.node-version'
 
+      - name: MCP Integration Tests - Setup Go environment
+        uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+        with:
+          go-version-file: 'client/go.mod'
+          cache-dependency-path: 'client/go.sum'
+
       - name: MCP Integration Tests - Install OS dependencies (Ubuntu)
         if: runner.os == 'Linux'
         run: sudo apt-get install -y jq
@@ -60,8 +66,8 @@ jobs:
         if: runner.os == 'Windows'
         run: choco install jq -y
 
-      - name: MCP Integration Tests - Install node dependencies for client and server workspaces
-        run: npm ci --workspace=client && npm ci --workspace=server
+      - name: MCP Integration Tests - Install node dependencies for server workspace
+        run: npm ci --workspace=server
 
       - name: MCP Integration Tests - Setup CodeQL environment
         uses: ./.github/actions/setup-codeql-environment
@@ -93,7 +99,7 @@ jobs:
         run: ./server/scripts/install-packs.sh
 
       ## Extract test databases used in the integration tests.
-      ## Defaults to integration scope (javascript/examples only).
+      ## Defaults to integration scope (javascript/examples + all tools databases).
       ## Query unit tests auto-extract their own databases via `codeql test run`.
       - name: MCP Integration Tests - Extract test databases
         shell: bash
@@ -109,9 +115,14 @@ jobs:
       ## Run integration tests. This script builds the server bundle and runs tests.
       ## We do NOT use 'npm run build-and-test' as it runs query unit tests which
       ## have a dedicated workflow (query-unit-tests.yml).
+      ##
+      ## On Windows, GNU Make's SHELL := bash resolves to WSL's bash.exe
+      ## (C:\Windows\System32\bash.exe) instead of Git Bash, causing
+      ## "Windows Subsystem for Linux has no installed distributions" errors.
+      ## We override SHELL with the full Git Bash path to avoid this.
       - name: MCP Integration Tests - Run integration tests
         shell: bash
-        run: npm run test:integration --workspace=client
+        run: make -C client test-integration SHELL="$(which bash)"
 
       - name: MCP Integration Tests - Stop the background MCP server process
         if: always() && matrix.mcp-mode == 'http'

.github/workflows/client-integration-tests.yml

@@ -25,6 +25,12 @@ jobs:
           cache: 'npm'
           node-version-file: '.node-version'
 
+      - name: Lint and Format - Setup Go
+        uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+        with:
+          go-version-file: 'client/go.mod'
+          cache-dependency-path: 'client/go.sum'
+
       - name: Lint and Format - Install node dependencies for all workspaces
         run: npm ci