Update repo docs and .github/** for ql-mcp-client

Author: data-douser

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

@@ -32,7 +32,7 @@ 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 integration-tests --mode stdio --tools <tool_name> --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

@@ -1,32 +1,36 @@
 ---
-applyTo: 'client/src/**/*.js'
-description: 'Instructions for MCP client JavaScript source code files.'
+applyTo: 'client/**/*.go'
+description: 'Instructions for MCP client Go source code files.'
 ---
 
-# Copilot Instructions for `client/src/**/*.js` code files
+# Copilot Instructions for `client/**/*.go` code files
 
 ## PURPOSE
 
-The purpose of the entire `client/**` implementation is to provide integration tests for the MCP `server/**` implementation. Accordingly, the client is implemented in JavaScript (only) and is not intended to be a production-quality MCP client library.
+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 JavaScript syntax and features.
-- ALWAYS follow best practices for implementing secure JavaScript code.
-- ALWAYS order imports, definitions, static lists, and similar constructs alphabetically.
+- 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 errors by running `npm run lint:fix` from the repo root directory before committing changes.
-- **ALWAYS run `npm test` from the `client/` directory and ensure all integration tests pass before committing changes to client code.**
+- 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.
 
-## PREFERNCES
+## PREFERENCES
 
-- PREFER keeping the `client/src/ql-mcp-client.js` entrypoint simple and focused on high-level logic.
-- PREFER creating client helper modules with `client/src/<module>/*.js` files that are focused on a single concern.
-- PREFER simple integration tests with "before" and "after" states over complex programmatic setup.
-- PREFER building on the existing integration test approach and framework rather than implementing a new approach.
+- 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.
 
-## CONTRAINTS
+## CONSTRAINTS
 
 - NEVER leave any trailing whitespace on any line.
-- NEVER guess at what an MCP server primitive is supposed do; instead, look up its source code in `server/src/**/*.ts` files.
+- 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/prompts/ql-mcp-server-fix-build-and-test.prompt.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.