`ql-mcp-client` Phase 3(B): Code Scanning lifecycle, SARIF enhancements, and `gh` extension packaging

[data-douser]

Context

Sub-issue of #207 — Phase 3(B): Code Scanning lifecycle management, SARIF server enhancements, and gh extension packaging.

Depends on: #217 (Phase 2 — Go binary and integration test runner)

Related: #208 (MCP tool usability improvements — SARIF enhancements from sub-issues feed into this phase)

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

Summary

Complete the remaining ql-mcp-client features from #207 that go beyond the core CLI and test runner delivered in Phase 2. This phase adds Code Scanning API subcommands, SARIF delegation subcommands, GitHub API client integration, and server-side SARIF tool enhancements — reaching (and potentially exceeding) the state of origin/dd/ql-mcp-client/1. CHANGELOG updates target a v2.25.2-next.1 prerelease.

Scope

Go client: Code Scanning subcommands

• client/cmd/code_scanning.go — code-scanning parent subcommand
• client/cmd/code_scanning_list_analyses.go — code-scanning list-analyses subcommand: list SARIF analyses for a repo via GitHub REST API
• client/cmd/code_scanning_list_alerts.go — code-scanning list-alerts subcommand: list alerts with state/severity/tool filters
• client/cmd/code_scanning_download_analysis.go — code-scanning download-analysis subcommand: download SARIF via Accept: application/sarif+json

Go client: SARIF subcommands (MCP tool delegation)

• client/cmd/sarif.go — sarif parent subcommand wiring to MCP server SARIF tools:
  • sarif compare-alerts → sarif_compare_alerts (including fingerprint mode)
  • sarif compare-analyses → sarif_diff_runs
  • Additional subcommands as needed for deduplication and validation workflows

Go client: GitHub API integration

• client/internal/github/client.go — GitHub REST API client using go-gh for authentication:
  • Code Scanning analyses endpoint (GET /repos/{owner}/{repo}/code-scanning/analyses)
  • Code Scanning alerts endpoint (GET /repos/{owner}/{repo}/code-scanning/alerts)
  • SARIF download endpoint (GET /repos/{owner}/{repo}/code-scanning/analyses/{id} with Accept: application/sarif+json)
• client/internal/github/client_test.go — Unit tests for GitHub API client
• client/internal/github/types.go — Go types for Code Scanning API responses (Analysis, Alert, AlertInstance, etc.)

Go client: gh extension packaging

• Cross-compiled binaries for darwin/amd64, darwin/arm64, linux/amd64, windows/amd64
• Makefile targets for cross-compilation
• Support gh extension install from release artifacts

Server: SARIF tool enhancements

These changes enhance existing ql-mcp server SARIF tools to support the client's Code Scanning workflows, and address SARIF-related improvements from #208 sub-issues:

• server/src/lib/sarif-utils.ts — Enhance SARIF utility functions:
  • Fingerprint extraction and comparison helpers
  • Rule-result count aggregation (relates to sarif_list_rules: add per-rule resultCount field #214 — sarif_list_rules per-rule resultCount)
  • Improved SARIF validation and error messages (relates to MCP tool usability improvements: validation errors, parameter naming, and SARIF enhancements #208 area 1 — validation errors)
• server/src/tools/sarif-tools.ts — Enhance SARIF tools:
  • sarif_compare_alerts: add partialFingerprints overlap mode with automatic fallback to full-path mode
  • sarif_list_rules: add resultCount field per rule (sarif_list_rules: add per-rule resultCount field #214)
  • sarif_store: ingest SARIF content into session cache, return cacheKey for downstream tools (Rewrite ql-mcp-client in Go as a gh CLI extension for Code Scanning SARIF management #207)
  • sarif_deduplicate_rules: pairwise rule comparison across SARIF files using fingerprint-first overlap analysis (Rewrite ql-mcp-client in Go as a gh CLI extension for Code Scanning SARIF management #207)
  • Consider sarif_diff_by_commits for git-diff correlation (MCP tool usability improvements: validation errors, parameter naming, and SARIF enhancements #208 area 5)
• server/test/src/lib/sarif-utils.test.ts — Unit tests for enhanced SARIF utilities
• server/test/src/tools/sarif-tools.test.ts — Unit tests for enhanced SARIF tools

Server: Build artifacts

• server/dist/codeql-development-mcp-server.js — Rebuild with SARIF enhancements
• server/dist/codeql-development-mcp-server.js.map — Updated source map

CHANGELOG.md

• Update CHANGELOG.md for v2.25.2-next.1 (prerelease) with Phase 3 changes:
  • Code Scanning subcommands in gh-ql-mcp-client
  • SARIF delegation subcommands
  • GitHub API client integration
  • Server SARIF tool enhancements (fingerprint mode, resultCount, sarif_store, sarif_deduplicate_rules)
  • gh extension packaging support

Acceptance criteria

1. gh-ql-mcp-client code-scanning list-analyses, list-alerts, and download-analysis work against a real GitHub repo with Code Scanning enabled
2. gh-ql-mcp-client sarif compare-alerts and sarif compare-analyses successfully delegate to MCP server tools
3. GitHub API client authenticates via go-gh (respects GH_TOKEN, gh auth session)
4. sarif_compare_alerts supports fingerprint overlap mode with automatic fallback
5. sarif_list_rules includes resultCount per rule
6. All new Go code has unit tests; go test ./... passes
7. All server SARIF changes have unit tests; npm test passes in server/
8. npm run build-and-test passes end-to-end
9. CHANGELOG.md documents Phase 3 changes targeting v2.25.2-next.1

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

Added

client/cmd/code_scanning.go
client/cmd/code_scanning_list_analyses.go
client/cmd/code_scanning_list_alerts.go
client/cmd/code_scanning_download_analysis.go
client/cmd/sarif.go
client/internal/github/client.go
client/internal/github/client_test.go
client/internal/github/types.go
server/test/src/lib/sarif-utils.test.ts (new tests)

Modified

server/src/lib/sarif-utils.ts
server/src/tools/sarif-tools.ts
server/test/src/tools/sarif-tools.test.ts
server/dist/codeql-development-mcp-server.js
server/dist/codeql-development-mcp-server.js.map
CHANGELOG.md