`ql-mcp-client` Phase 2: Replace JavaScript client with Go binary and integration test runner

[data-douser]

Context

Sub-issue of #207 — Phase 2 of 3: Replace JavaScript client with Go binary.

Depends on: #216 (Phase 1 — documentation updates)

Reference branch: origin/dd/ql-mcp-client/1

Summary

Completely replace the JavaScript-based ql-mcp-client.js and its supporting library (client/src/) with an equivalent Go-based gh-ql-mcp-client binary. This phase focuses on the core CLI framework and integration test runner — no Code Scanning or SARIF-specific features are added until Phase 3.

Scope

Remove JavaScript client

• Delete client/src/ — Remove ql-mcp-client.js and all client/src/lib/*.js modules:
  • aggregate-query-metadata.js, cli-parser.js, command-handler.js, file-utils.js, integration-test-runner.js, mcp-client-utils.js, mcp-test-suite.js, monitoring-integration-test-runner.js, process-query-metadata.js, queries-filter-metadata.js, resolve-all-queries.js, server-manager.js, test-logger.js, validate-source-root.js
  • commands/basic-commands.js, commands/metadata-commands.js, commands/query-commands.js
• Delete client/package.json — Remove npm workspace package for client
• Delete client/eslint.config.mjs — Remove JS-specific linting config
• Update client/.gitignore — Replace JS/npm ignores with Go binary and build artifact ignores
• Update package-lock.json — Regenerate after removing client/ from npm workspaces

Go module and CLI framework

• client/go.mod / client/go.sum — Initialize Go module github.com/advanced-security/codeql-development-mcp-server/client with dependencies:
  • github.com/spf13/cobra — CLI framework
  • github.com/mark3labs/mcp-go — MCP client SDK
• client/main.go — Entry point, invoke cmd.Execute()
• client/cmd/root.go — Root Cobra command with --server-command, --log-directory, --verbose flags, version info
• client/cmd/root_test.go — Unit tests for root command flag parsing and defaults
• client/cmd/helpers.go — Shared CLI helper utilities
• client/cmd/helpers_test.go — Unit tests for helpers
• client/Makefile — Build targets: build, test, lint, clean, integration-test

MCP client library

• client/internal/mcp/client.go — Go MCP client wrapper: connect via stdio transport, call tools, list tools/prompts/resources, handle JSON-RPC
• client/internal/mcp/client_test.go — Unit tests for MCP client

Integration test runner (Go port)

• client/internal/testing/runner.go — Go port of JS integration-test-runner.js:
  • Discover test fixtures in client/integration-tests/primitives/
  • Parse test-config.json to extract tool name, arguments, assertions
  • Connect to MCP server via stdio, call tools, validate responses
  • Tool availability enforcement: non-deprecated tools with fixtures must be registered
  • Support skipIf / requireAnnotationTools config flags
• client/internal/testing/runner_test.go — Unit tests for test runner
• client/internal/testing/params.go — Test parameter parsing and substitution logic
• client/internal/testing/params_test.go — Unit tests for parameter handling
• client/cmd/integration_tests.go — integration-tests run Cobra subcommand wiring

Integration test fixture adjustments

• Update test-config.json files referencing custom_log_directory — adjust paths for Go binary location

Build infrastructure

• client/scripts/run-integration-tests.sh — Update to build Go binary and run ./gh-ql-mcp-client integration-tests run
• Root package.json — Ensure npm run build-and-test invokes make -C client build test

CHANGELOG.md

• Update [Unreleased] section with Phase 1 and Phase 2 changes using the maintain-changelog skill:
  • Document documentation/config updates from Phase 1
  • Document Go client rewrite, JS client removal, integration test runner port

Acceptance criteria

1. client/src/ directory and all JS files are fully removed
2. client/ is no longer an npm workspace — removed from root package.json workspaces array
3. go build ./... succeeds in client/ and produces gh-ql-mcp-client binary
4. go test ./... passes all Go unit tests in client/
5. All 82+ existing integration test fixtures in client/integration-tests/primitives/tools/ pass with the Go test runner
6. npm run build-and-test passes end-to-end (server + extension + client via Make)
7. CHANGELOG.md [Unreleased] section documents Phase 1 and Phase 2 changes

Files changed (reference: origin/dd/ql-mcp-client/1)

Added

client/Makefile
client/go.mod
client/go.sum
client/main.go
client/cmd/root.go
client/cmd/root_test.go
client/cmd/helpers.go
client/cmd/helpers_test.go
client/cmd/integration_tests.go
client/internal/mcp/client.go
client/internal/mcp/client_test.go
client/internal/testing/runner.go
client/internal/testing/runner_test.go
client/internal/testing/params.go
client/internal/testing/params_test.go

Removed

client/package.json
client/eslint.config.mjs
client/src/ql-mcp-client.js
client/src/lib/*.js (all 14 files)
client/src/lib/commands/*.js (3 files)

Modified

client/.gitignore
client/scripts/run-integration-tests.sh
package.json
package-lock.json