More prep for initial public release readiness by data-douser · Pull Request #24 · advanced-security/codeql-development-mcp-server

data-douser · 2026-02-08T03:10:53Z

Summary of Changes

This pull request makes several updates to agent configurations, documentation, and skill templates to standardize naming conventions, clarify packaging requirements, and upgrade models/tool references for the QL MCP Server and related CodeQL development workflows. The main themes are: agent/model/tool upgrades, server/tool naming consistency, and improvements to documentation and skill instructions for adding language support and managing npm packaging.

Outline of Changes

Naming and Reference Updates

All references to the main server implementation in agent descriptions, prompts, and checklists are updated from ql-mcp-server to codeql-development-mcp-server [1] [2] [3] [4].
CodeQL pack names are changed to use the advanced-security/ namespace for both source and test packs in skills and documentation [1] [2] [3] [4] [5].

Agent and Prompt Upgrades

All agents and prompts are upgraded to use the Claude Opus 4.6 (1M context) model instead of Claude Opus 4.5, and tool references are updated for consistency (ql-mcp/* instead of codeql-dev-mcp-server/*) [1] [2] [3] [4] [5] [6] [7] [8].

npm Packaging and Documentation Improvements

Documentation clarifies that the npm files field must explicitly list each language directory under ql/*/tools/src/, and .qlx files are excluded via .npmignore.
Skills and checklists now require explicit updates to server/package.json, .github/workflows/release.yml, and docs/public.md when adding new language support [1] [2].

Server Logging and Environment Variable Guidance

Documentation and skills emphasize that server logs must use stderr for all output (never stdout), and provide guidance for using the CODEQL_PATH environment variable for binary resolution [1] [2].

CI/CD and Workflow Adjustments

CI workflows and documentation are updated to reference new pack names and ensure proper inclusion of new languages in release steps [1] [2].
Adds a codeql-path-tests job to the .github/workflows/client-integration-tests.yml actions workflow in order to ensure multi-OS validation of the codeql-development-mcp-server when used with codeql outside of system PATH (i.e. validates functionality of CODEQL_PATH env var on Linux, MacOS, and Windows).

These changes ensure consistency across the codebase, improve packaging reliability, and support easier onboarding for new language packs and server tooling.

This commit makes the following changes as part of the overall effort to prepare this 'advanced-security/codeql-development-mcp-server' to be fully ready for initial public release: - Rename entry point to codeql-development-mcp-server.ts - Scope all codeql-pack.yml with advanced-security/ prefix - Add npm publishConfig for GitHub Packages - Add CODEQL_PATH env var with PATH-prepend strategy - New package-paths.ts module for npm-install-safe path resolution - Logger writes all output to stderr (stdout reserved for MCP protocol) - Fix process.cwd() usages in language-resources, language-server-eval, temp-dir, and session-data-manager - Fix relative cwd/test paths resolved against workspaceRootDir - Language server spawn() honors CODEQL_PATH via PATH prepend - Use path.delimiter for Windows portability - Relax engines to node >=22.0.0 - Fix VERSION constant from 1.0.0 to 2.23.9 - Update server/README.md env vars and file listing - Updates unit tests to cover source code changes - Adds 'docs/public.md' documentation of intended public features

Copilot

Pull request overview

This PR prepares the repository for an initial public release by standardizing server/package naming, improving runtime path resolution (independent of process.cwd()), and tightening packaging/release automation so the server and its CodeQL tool packs can be distributed via GitHub Packages/GHCR.

Changes:

Renames the server entrypoint/artifacts to codeql-development-mcp-server and scopes the npm package to @advanced-security/....
Adds CODEQL_PATH support and enforces stderr-only logging to protect stdio JSON-RPC transport.
Introduces package/workspace root path utilities and updates docs/workflows for publishing npm + CodeQL packs and for public installation.

Reviewed changes

Copilot reviewed 59 out of 64 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
server/test/src/utils/temp-dir.test.ts	Updates expectations to use package-root-based `.tmp` resolution.
server/test/src/utils/package-paths.test.ts	Adds coverage for new package/workspace path resolution helpers.
server/test/src/utils/logger.test.ts	Updates tests to reflect stderr-only logging behavior.
server/test/src/lib/cli-executor.test.ts	Adds unit tests for `CODEQL_PATH` resolution and PATH-prepend behavior.
server/src/utils/temp-dir.ts	Switches `.tmp` base from repo-root heuristics to package-root utility.
server/src/utils/package-paths.ts	Adds utilities for resolving package/workspace roots and tool pack paths.
server/src/utils/logger.ts	Routes all log levels to stderr to avoid MCP protocol corruption.
server/src/tools/codeql/language-server-eval.ts	Uses package-root-relative `ql` search path/workspace URI rather than CWD.
server/src/resources/language-resources.ts	Resolves resource base path via workspace root rather than CWD assumptions.
server/src/lib/session-data-manager.ts	Moves default monitoring storage under package root (not CWD).
server/src/lib/language-server.ts	Prepends resolved CodeQL dir to PATH for language server spawn; updates clientInfo branding/version.
server/src/lib/cli-tool-registry.ts	Uses workspace/package-root pathing for tests/cwd/additional packs; replaces repoRoot heuristics.
server/src/lib/cli-executor.ts	Implements `CODEQL_PATH` validation and PATH prepending for child processes.
server/src/codeql-development-mcp-server.ts	Loads `.env` from package root; resolves CodeQL binary at startup; bumps version branding.
server/ql/swift/tools/test/codeql-pack.yml	Renames pack to `advanced-security/*` and uses `${workspace}` dependency.
server/ql/swift/tools/src/codeql-pack.yml	Renames pack + adds description.
server/ql/ruby/tools/test/codeql-pack.yml	Renames pack to `advanced-security/*` and uses `${workspace}` dependency.
server/ql/ruby/tools/src/codeql-pack.yml	Renames pack + adds description.
server/ql/python/tools/test/codeql-pack.yml	Renames pack to `advanced-security/*` and uses `${workspace}` dependency.
server/ql/python/tools/src/codeql-pack.yml	Renames pack + adds description.
server/ql/javascript/tools/test/codeql-pack.yml	Renames pack to `advanced-security/*` and uses `${workspace}` dependency.
server/ql/javascript/tools/src/codeql-pack.yml	Renames pack + adds description.
server/ql/javascript/examples/test/codeql-pack.yml	Renames examples test pack + uses `${workspace}` dependency.
server/ql/javascript/examples/src/codeql-pack.yml	Renames examples source pack.
server/ql/java/tools/test/codeql-pack.yml	Renames pack to `advanced-security/*` and uses `${workspace}` dependency.
server/ql/java/tools/src/codeql-pack.yml	Renames pack + adds description.
server/ql/go/tools/test/codeql-pack.yml	Renames pack to `advanced-security/*` and uses `${workspace}` dependency.
server/ql/go/tools/src/codeql-pack.yml	Renames pack + adds description.
server/ql/csharp/tools/test/codeql-pack.yml	Renames pack to `advanced-security/*` and uses `${workspace}` dependency.
server/ql/csharp/tools/src/codeql-pack.yml	Renames pack + adds description.
server/ql/cpp/tools/test/codeql-pack.yml	Renames pack to `advanced-security/*` and uses `${workspace}` dependency.
server/ql/cpp/tools/src/codeql-pack.yml	Renames pack + adds description.
server/ql/actions/tools/test/codeql-pack.yml	Renames pack to `advanced-security/*` and uses `${workspace}` dependency.
server/ql/actions/tools/src/codeql-pack.yml	Renames pack + adds description.
server/package.json	Scopes npm package, adds explicit `files` list, publishConfig/repo metadata, updates entrypoints and engines.
server/esbuild.config.js	Updates entry/out file names and bumps build target to node22.
server/dist/codeql-development-mcp-server.js	Updates bundled output to match new entrypoint + behavior changes.
server/README.md	Updates run commands, env var docs, and node minimum version.
server/LICENSE	Adds CodeQL Terms and Conditions license file to server package.
server/.npmignore	Excludes `.qlx` artifacts from npm package.
server/.gitignore	Tracks the renamed bundled server artifacts in `dist/`.
package-lock.json	Updates workspace/package metadata (scoped server package + license fields).
docs/public.md	Adds public install guide for GitHub Packages + GHCR packs and configuration guidance.
docs/getting-started.md	Updates installation paths (npm/npx + tarball) and config naming (`ql-mcp`).
client/src/lib/server-manager.js	Updates integration test harness to start the renamed server bundle.
client/scripts/start-server.sh	Updates script to launch renamed server bundle.
client/LICENSE	Adds CodeQL Terms and Conditions license file to client package.
README.md	Updates quick start to prefer npm/npx and adds link to the public install guide.
.gitignore	Ignores generated stdout/stderr capture files used by new workflow tests.
.github/workflows/release.yml	Adds package publish perms, publishes CodeQL packs + npm package, and packages release as tar.gz.
.github/workflows/client-integration-tests.yml	Adds a cross-OS CODEQL_PATH behavior test job.
.github/skills/validate-ql-mcp-server-tools-queries/SKILL.md	Documents stderr logging + CODEQL_PATH behavior and packaging expectations.
.github/skills/upgrade-codeql-cli-and-packs/SKILL.md	Updates pack naming templates and adds npm packaging constraints/notes.
.github/skills/add-mcp-support-for-new-language/SKILL.md	Extends checklist for npm packaging, release workflow, and docs updates per new language.
.github/prompts/ql-mcp-server-fix-build-and-test.prompt.md	Updates model reference.
.github/agents/ql-mcp-tool-tester.md	Updates model reference.
.github/agents/ql-mcp-tool-developer.md	Updates model reference and server bundle path reference.
.github/agents/ql-agent-skills-developer.md	Updates model reference.
.github/agents/mcp-enabled-ql-workshop-developer.md	Updates tool namespace references and model.
.github/agents/mcp-enabled-ql-query-developer.md	Updates tool namespace references and model.
.github/ISSUE_TEMPLATE/mcp-server-primitive-update.yml	Updates main server implementation path reference.
.github/ISSUE_TEMPLATE/mcp-server-primitive-create.yml	Updates main server implementation path reference.

- Fix codeql-path-tests CI job that timed out (~17min) on all three OSes due to bash pipe PID tracking bug (`$!` captured subshell PID, not server PID). Replace inline workflow steps with portable bash scripts using background watchdog + `wait` pattern (no GNU `timeout`). - Add startup-time validation (`validateCodeQLBinaryReachable`) that runs `codeql version --format=terse` before tool registration. Server now fails fast with actionable error when codeql is not on PATH and CODEQL_PATH is not set. - Add Test 3: verify server fails at startup when codeql is missing from both PATH and CODEQL_PATH. - Address 5 Copilot PR review comments: - Implement caching in `resolveCodeQLBinary()` (short-circuit on repeat calls) - Fix JSDoc in temp-dir.ts (`<repoRoot>` -> `<packageRoot>`) - Gate Windows backslash test to `process.platform === 'win32'` - Use `path.isAbsolute()` for cross-platform database path check - Guard `additionalPacksPath` with `existsSync()` for npm-installed layouts Scripts: server/scripts/test-codeql-path-{invalid,missing,valid}.sh Tests: 375 passed (4 new)

Copilot

Pull request overview

Copilot reviewed 62 out of 67 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

server/src/lib/cli-executor.ts:205

validateCodeQLBinaryReachable() uses resolvedBinaryResult ?? 'codeql' without ensuring resolveCodeQLBinary() has been called, so it can ignore CODEQL_PATH entirely (and it may exec an absolute path that you explicitly note can break shebang launchers). Consider calling resolveCodeQLBinary() at the start of this function and always validating via the bare codeql command with a PATH that includes resolvedCodeQLDir.

Copilot

Pull request overview

Copilot reviewed 62 out of 67 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

server/test/src/utils/logger.test.ts:99

Same env restoration issue here: if originalDebug was undefined, process.env.DEBUG = originalDebug sets it to the string 'undefined'. Use delete process.env.DEBUG when the original value was unset to avoid leaking state across tests.

This commit: - addresses the latest PR review comments for #24 - enforces consistent repo use of node v24.13.0 / node24

Copilot

Pull request overview

Copilot reviewed 67 out of 72 changed files in this pull request and generated 6 comments.

data-douser · 2026-02-08T20:50:13Z

@copilot open a new pull request to apply changes based on the comments in this thread

Copilot · 2026-02-08T20:50:24Z

@data-douser I've opened a new pull request, #26, to work on those changes. Once the pull request is ready, I'll request review from you.

- Replace hardcoded version in language-server.ts with dynamic getPackageVersion() that reads from package.json (cached) - Add getUserWorkspaceDir() for user-relative path resolution that falls back to process.cwd() in npm-installed (non-monorepo) layouts - Honor CODEQL_MCP_TMP_DIR env var in temp-dir.ts for read-only package root scenarios (e.g., npm global installs) - Move session-data-manager default storage from packageRoot to getProjectTmpBase() so it respects CODEQL_MCP_TMP_DIR override - Fix misleading test name: "should accept valid CODEQL_PATH" was actually testing rejection of non-existent paths - Add skipIf(win32) guard on sh-dependent PATH prepend test

data-douser self-assigned this Feb 8, 2026

data-douser requested review from a team and enyil as code owners February 8, 2026 03:10

Copilot AI review requested due to automatic review settings February 8, 2026 03:10

data-douser added documentation Improvements or additions to documentation enhancement New feature or request javascript Pull requests that update javascript code server labels Feb 8, 2026

Copilot started reviewing on behalf of data-douser February 8, 2026 03:11 View session

Copilot AI reviewed Feb 8, 2026

View reviewed changes

Comment thread server/src/lib/cli-executor.ts

Comment thread server/src/utils/temp-dir.ts

Comment thread server/test/src/utils/package-paths.test.ts

Comment thread server/src/lib/cli-tool-registry.ts

Comment thread server/src/lib/cli-tool-registry.ts Outdated

data-douser added 2 commits February 7, 2026 21:43

Attempted fix for cli-executor.test.ts

e8ebe6a

Copilot AI review requested due to automatic review settings February 8, 2026 04:50

Copilot started reviewing on behalf of data-douser February 8, 2026 04:51 View session

Copilot AI reviewed Feb 8, 2026

View reviewed changes

Comment thread server/test/src/lib/cli-executor.test.ts Outdated

Comment thread server/src/utils/package-paths.ts

Comment thread server/src/lib/cli-executor.ts

Comment thread server/package.json Outdated

data-douser added 2 commits February 7, 2026 21:59

Attempted fix for codeql-path-tests on windows-latest

c3abc68

Address more PR review comments

6fa24e9

data-douser requested a review from Copilot February 8, 2026 05:11

Copilot started reviewing on behalf of data-douser February 8, 2026 05:12 View session

Copilot AI reviewed Feb 8, 2026

View reviewed changes

Comment thread .github/workflows/release.yml

Comment thread server/package.json

Comment thread server/test/src/utils/logger.test.ts Outdated

data-douser added 2 commits February 8, 2026 10:48

Standardize on node24 : v24.13.0

6d9c927

This commit: - addresses the latest PR review comments for #24 - enforces consistent repo use of node v24.13.0 / node24

Update package-lock.json

97762c1

Copilot AI review requested due to automatic review settings February 8, 2026 20:07

Copilot started reviewing on behalf of data-douser February 8, 2026 20:07 View session

Attempted fix for build-server.yml workflow

fd9d0cf

Copilot AI reviewed Feb 8, 2026

View reviewed changes

Fix npm optional dependencies not installed from cache in CI (#25)

83f6a62

Copilot AI mentioned this pull request Feb 8, 2026

Fix path resolution and storage locations for npm-installed package scenarios #26

Closed

data-douser added this pull request to the merge queue Feb 8, 2026

Merged via the queue into main with commit 6e2e0e2 Feb 8, 2026
27 checks passed

data-douser deleted the dd/open-source-release-prep/2 branch February 8, 2026 21:09

Copilot AI mentioned this pull request Feb 8, 2026

Address PR #27 review feedback: path normalization, tests, and conventions #28

Merged

59 tasks

Conversation

data-douser commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of Changes

Outline of Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

data-douser commented Feb 8, 2026

Uh oh!

Copilot AI commented Feb 8, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

data-douser commented Feb 8, 2026 •

edited

Loading