Publish to npmjs.org with OIDC trusted publishing

- Rename package to unscoped `codeql-development-mcp-server`
- Switch from GitHub Packages to public npmjs.org registry
- Use OIDC trusted publishing (no tokens, auto-provenance)
- Make release.yml the sole dispatch entry point with
  configurable publish_npm, publish_codeql_packs, and
  create_github_release flags
- Remove workflow_dispatch from child workflows (release-npm,
  release-codeql, release-tag) to comply with OIDC validation
- Fix release-tag.yml: wire tag_sha output to final-sha step,
  guard git add -A against staging CodeQL artifacts
- Add setup-packs.sh script (shipped in npm package) to install
  CodeQL pack dependencies from bundled lock files
- Update all docs, tests, and SKILL.md references

Author: data-douser

.github/skills/validate-ql-mcp-server-tools-queries/SKILL.md

@@ -336,7 +336,7 @@ When the STDIO transport receives an immediate EOF on stdin (e.g., via `</dev/nu
 
 ### npm Package Includes Tool Query Source Packs
 
-The published npm package (`@advanced-security/codeql-development-mcp-server`) bundles all tool query source packs under `ql/*/tools/src/`. These are the same `.ql`, `.qll`, `.md`, `codeql-pack.yml`, and `codeql-pack.lock.yml` files — but **never** compiled `.qlx` bytecode (excluded by `server/.npmignore`).
+The published npm package (`codeql-development-mcp-server`) bundles all tool query source packs under `ql/*/tools/src/`. These are the same `.ql`, `.qll`, `.md`, `codeql-pack.yml`, and `codeql-pack.lock.yml` files — but **never** compiled `.qlx` bytecode (excluded by `server/.npmignore`).
 
 ## Success Criteria
 

.github/workflows/release-codeql.yml

@@ -19,17 +19,12 @@ on:
       version:
         description: 'The full version string with "v" prefix (e.g., vX.Y.Z)'
         value: ${{ jobs.publish-codeql-packs.outputs.version }}
-  workflow_dispatch:
-    inputs:
-      publish_codeql_packs:
-        default: true
-        description: 'Publish CodeQL tool query packs to GHCR. Disable for pre-release or re-run scenarios where packs already exist.'
-        required: false
-        type: boolean
-      version:
-        description: 'Release version tag (e.g., vX.Y.Z). Must start with "v". Tag must already exist.'
-        required: true
-        type: string
+
+# Note: This workflow is called exclusively via workflow_call from release.yml.
+# It does NOT have a workflow_dispatch trigger to keep release.yml as the single
+# entry point for all release operations. To re-publish CodeQL packs standalone,
+# use workflow_dispatch on release.yml with publish_npm=false and
+# create_github_release=false.
 
 permissions:
   contents: read

.github/workflows/release-npm.yml

@@ -14,12 +14,14 @@ on:
       version:
         description: 'The full version string with "v" prefix (e.g., vX.Y.Z)'
         value: ${{ jobs.publish-npm.outputs.version }}
-  workflow_dispatch:
-    inputs:
-      version:
-        description: 'Release version tag (e.g., vX.Y.Z). Must start with "v". Tag must already exist.'
-        required: true
-        type: string
+
+# Note: This workflow is called exclusively via workflow_call from release.yml.
+# It does NOT have a workflow_dispatch trigger because npm Trusted Publishing
+# validates the *calling* workflow filename for OIDC. The trusted publisher on
+# npmjs.com is configured with workflow "release.yml" and environment
+# "release-npm". Direct dispatch would present "release-npm.yml" as the workflow
+# name, causing OIDC authentication to fail. To re-publish the npm package
+# standalone, use workflow_dispatch on release.yml instead.
 
 permissions:
   contents: read
@@ -33,7 +35,7 @@ jobs:
 
     permissions:
       contents: read
-      packages: write
+      id-token: write
 
     outputs:
       release_name: ${{ steps.version.outputs.release_name }}
@@ -61,8 +63,7 @@ jobs:
         with:
           cache: 'npm'
           node-version-file: '.node-version'
-          registry-url: 'https://npm.pkg.github.com'
-          scope: '@advanced-security'
+          registry-url: 'https://registry.npmjs.org'
 
       - name: npm - Install dependencies
         run: npm ci --include=optional
@@ -72,12 +73,10 @@ jobs:
 
       - name: npm - Publish npm package
         working-directory: server
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          echo "Publishing @advanced-security/codeql-development-mcp-server to GitHub Packages..."
+          echo "Publishing codeql-development-mcp-server to npmjs.org via OIDC trusted publishing..."
           npm publish
-          echo "✅ Published npm package to GitHub Packages"
+          echo "✅ Published npm package to npmjs.org (with provenance)"
 
       - name: npm - Upload release build artifact
         uses: actions/upload-artifact@v6
@@ -100,7 +99,7 @@ jobs:
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "| Detail | Value |" >> $GITHUB_STEP_SUMMARY
           echo "| ------ | ----- |" >> $GITHUB_STEP_SUMMARY
-          echo "| Package | \`@advanced-security/codeql-development-mcp-server\` |" >> $GITHUB_STEP_SUMMARY
+          echo "| Package | \`codeql-development-mcp-server\` |" >> $GITHUB_STEP_SUMMARY
           echo "| Version | ${RELEASE_NAME} |" >> $GITHUB_STEP_SUMMARY
-          echo "| Registry | GitHub Packages |" >> $GITHUB_STEP_SUMMARY
+          echo "| Registry | npmjs.org |" >> $GITHUB_STEP_SUMMARY
           echo "| Tag | ${VERSION} |" >> $GITHUB_STEP_SUMMARY

.github/workflows/release-tag.yml

@@ -17,12 +17,10 @@ on:
       version:
         description: 'The full version string with "v" prefix (e.g., vX.Y.Z)'
         value: ${{ jobs.create-tag.outputs.version }}
-  workflow_dispatch:
-    inputs:
-      version:
-        description: 'Release version (e.g., vX.Y.Z). Must start with "v".'
-        required: true
-        type: string
+
+# Note: This workflow is called exclusively via workflow_call from release.yml.
+# It does NOT have a workflow_dispatch trigger to keep release.yml as the single
+# entry point for all release operations.
 
 permissions:
   contents: read
@@ -39,7 +37,7 @@ jobs:
 
     outputs:
       release_name: ${{ steps.version.outputs.release_name }}
-      tag_sha: ${{ steps.create-tag.outputs.tag_sha }}
+      tag_sha: ${{ steps.final-sha.outputs.tag_sha }}
       version: ${{ steps.version.outputs.version }}
 
     steps:
@@ -129,6 +127,9 @@ jobs:
 
           # Stage version-bearing files and lockfile changes
           git add -A
+          # Ensure CodeQL-generated artifacts are not staged for commit
+          git restore --staged .codeql || true
+          git restore --staged '*.qlx' || true
 
           # Check if there are changes to commit
           if git diff --cached --quiet; then

.github/workflows/release.yml

@@ -6,11 +6,21 @@ on:
       - 'v*'
   workflow_dispatch:
     inputs:
+      create_github_release:
+        default: true
+        description: 'Create GitHub Release with distribution archive and CodeQL pack bundles. Disable to only publish packages without creating a release.'
+        required: false
+        type: boolean
       publish_codeql_packs:
         default: true
         description: 'Publish CodeQL tool query packs to GHCR. Disable for pre-release or re-run scenarios where packs already exist.'
         required: false
         type: boolean
+      publish_npm:
+        default: true
+        description: 'Publish npm package to npmjs.org via OIDC trusted publishing. Disable for pre-release or re-run scenarios where the npm package already exists.'
+        required: false
+        type: boolean
       version:
         description: 'Release version (e.g., vX.Y.Z). Must start with "v".'
         required: true
@@ -32,7 +42,9 @@ jobs:
     runs-on: ubuntu-latest
 
     outputs:
+      create_github_release: ${{ steps.resolve.outputs.create_github_release }}
       publish_codeql_packs: ${{ steps.resolve.outputs.publish_codeql_packs }}
+      publish_npm: ${{ steps.resolve.outputs.publish_npm }}
       release_name: ${{ steps.resolve.outputs.release_name }}
       version: ${{ steps.resolve.outputs.version }}
 
@@ -52,16 +64,22 @@ jobs:
             exit 1
           fi
 
-          # Resolve publish_codeql_packs (default true for tag pushes)
+          # Resolve publish flags (default true for tag pushes)
           if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
+            CREATE_RELEASE="${{ github.event.inputs.create_github_release }}"
             PUBLISH_PACKS="${{ github.event.inputs.publish_codeql_packs }}"
+            PUBLISH_NPM="${{ github.event.inputs.publish_npm }}"
           else
+            CREATE_RELEASE="true"
             PUBLISH_PACKS="true"
+            PUBLISH_NPM="true"
           fi
 
           echo "version=${VERSION}" >> $GITHUB_OUTPUT
           echo "release_name=${VERSION#v}" >> $GITHUB_OUTPUT
+          echo "create_github_release=${CREATE_RELEASE}" >> $GITHUB_OUTPUT
           echo "publish_codeql_packs=${PUBLISH_PACKS}" >> $GITHUB_OUTPUT
+          echo "publish_npm=${PUBLISH_NPM}" >> $GITHUB_OUTPUT
 
   # ─────────────────────────────────────────────────────────────────────────────
   # Step 2: Ensure the release tag exists
@@ -83,15 +101,20 @@ jobs:
   # Step 3a: Build and publish the npm package
   #
   # Checks out the clean tag (no CodeQL pack artifacts), builds with `npm ci`,
-  # and publishes to GitHub Packages. Runs in parallel with CodeQL pack
-  # publishing since they are independent.
+  # and publishes to npmjs.org via OIDC trusted publishing. Runs in parallel
+  # with CodeQL pack publishing since they are independent.
+  #
+  # The trusted publisher on npmjs.com is configured with workflow "release.yml"
+  # and environment "release-npm". The id-token:write permission is required for
+  # OIDC authentication — no npm tokens are used.
   # ─────────────────────────────────────────────────────────────────────────────
   publish-npm:
     name: Publish npm Package
+    if: needs.resolve-version.outputs.publish_npm == 'true'
     needs: [resolve-version, ensure-tag]
     permissions:
       contents: read
-      packages: write
+      id-token: write
     uses: ./.github/workflows/release-npm.yml
     with:
       version: ${{ needs.resolve-version.outputs.version }}
@@ -104,6 +127,7 @@ jobs:
   # ─────────────────────────────────────────────────────────────────────────────
   publish-codeql:
     name: Publish CodeQL Packs
+    if: needs.resolve-version.outputs.publish_codeql_packs == 'true'
     needs: [resolve-version, ensure-tag]
     permissions:
       contents: read
@@ -118,11 +142,18 @@ jobs:
   #
   # Downloads the clean build artifact (from npm workflow) and pack bundles
   # (from CodeQL workflow), assembles the distribution archive, and creates the
-  # GitHub Release.
+  # GitHub Release. Only runs for full releases (all publish steps enabled and
+  # create_github_release is true). Partial workflows (e.g., re-publishing only
+  # npm or only CodeQL packs) skip this step.
   # ─────────────────────────────────────────────────────────────────────────────
   create-release:
     name: Create GitHub Release
-    needs: [resolve-version, publish-npm, publish-codeql]
+    if: >-
+      always() && !failure() && !cancelled()
+      && needs.resolve-version.outputs.create_github_release == 'true'
+      && needs.resolve-version.outputs.publish_npm == 'true'
+      && needs.resolve-version.outputs.publish_codeql_packs == 'true'
+    needs: [resolve-version, ensure-tag, publish-npm, publish-codeql]
     runs-on: ubuntu-latest
 
     permissions:
@@ -162,11 +193,6 @@ jobs:
           # Remove test and examples directories from ql folders (only keep src)
           find dist-package/server/ql -type d \( -name "test" -o -name "examples" \) -prune -exec rm -rf {} \;
 
-      - name: Release - Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version-file: '.node-version'
-
       - name: Release - Install production dependencies
         working-directory: dist-package/server
         run: npm install --omit=dev --include=optional
@@ -194,22 +220,17 @@ jobs:
         run: |
           VERSION="${{ needs.resolve-version.outputs.version }}"
           RELEASE_NAME="${{ needs.resolve-version.outputs.release_name }}"
-          PUBLISH_PACKS="${{ needs.resolve-version.outputs.publish_codeql_packs }}"
           echo "## Release Summary" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "| Step | Status |" >> $GITHUB_STEP_SUMMARY
           echo "| ---- | ------ |" >> $GITHUB_STEP_SUMMARY
           echo "| Tag | ✅ ${VERSION} |" >> $GITHUB_STEP_SUMMARY
           echo "| Server build | ✅ Success |" >> $GITHUB_STEP_SUMMARY
           echo "| Version validation | ✅ All files match ${RELEASE_NAME} |" >> $GITHUB_STEP_SUMMARY
-          if [ "${PUBLISH_PACKS}" != "true" ]; then
-            echo "| CodeQL pack publish | ⏭️ Skipped (disabled via input) |" >> $GITHUB_STEP_SUMMARY
-          else
-            echo "| CodeQL pack publish | ✅ Published to GHCR |" >> $GITHUB_STEP_SUMMARY
-          fi
-          echo "| npm package | ✅ Published to GitHub Packages |" >> $GITHUB_STEP_SUMMARY
+          echo "| npm publish | ✅ Published to npmjs.org |" >> $GITHUB_STEP_SUMMARY
+          echo "| CodeQL pack publish | ✅ Published to GHCR |" >> $GITHUB_STEP_SUMMARY
           echo "| Distribution archive | ✅ Created |" >> $GITHUB_STEP_SUMMARY
-          echo "| CodeQL pack bundles | ✅ Bundled |" >> $GITHUB_STEP_SUMMARY
+          echo "| GitHub Release | ✅ Created |" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "### Package Contents" >> $GITHUB_STEP_SUMMARY
           echo "- \`server/dist/\` - Bundled JavaScript output" >> $GITHUB_STEP_SUMMARY

README.md

@@ -57,21 +57,17 @@ Please note that this project is released with a [Contributor Code of Conduct](C
 
 ### Install via npm (recommended)
 
-No repository clone needed — install from [GitHub Packages](https://github.com/advanced-security/codeql-development-mcp-server/pkgs/npm/codeql-development-mcp-server):
+No repository clone needed — install from [npmjs.org](https://www.npmjs.com/package/codeql-development-mcp-server):
 
 ```bash
-# One-time: route @advanced-security scope to GitHub Packages and authenticate
-npm config set @advanced-security:registry https://npm.pkg.github.com
-npm login --registry=https://npm.pkg.github.com
-
 # Install globally
-npm install -g @advanced-security/codeql-development-mcp-server
+npm install -g codeql-development-mcp-server
 ```
 
 Or run on-demand without installing globally:
 
 ```bash
-npx -y @advanced-security/codeql-development-mcp-server
+npx -y codeql-development-mcp-server
 ```
 
 ### VS Code Configuration
@@ -89,7 +85,7 @@ Add to your `mcp.json` file:
   "servers": {
     "ql-mcp": {
       "command": "npx",
-      "args": ["-y", "@advanced-security/codeql-development-mcp-server"],
+      "args": ["-y", "codeql-development-mcp-server"],
       "type": "stdio"
     }
   }

docs/getting-started.md

@@ -12,23 +12,24 @@ This guide covers installation, configuration, and usage of the CodeQL Developme
 
 ### From npm (recommended)
 
-The package is published to [GitHub Packages](https://github.com/advanced-security/codeql-development-mcp-server/pkgs/npm/codeql-development-mcp-server). Configure npm once, then install:
+The package is published to the [public npm registry](https://www.npmjs.com/package/codeql-development-mcp-server). No authentication or special configuration is needed:
 
 ```bash
-# One-time: route @advanced-security scope to GitHub Packages and authenticate
-npm config set @advanced-security:registry https://npm.pkg.github.com
-npm login --registry=https://npm.pkg.github.com
-
 # Install globally
-npm install -g @advanced-security/codeql-development-mcp-server
+npm install -g codeql-development-mcp-server
+
+# Install CodeQL pack dependencies (required on first use)
+codeql-development-mcp-server-setup-packs
 ```
 
 Or use `npx` to run without a global install:
 
 ```bash
-npx -y @advanced-security/codeql-development-mcp-server
+npx -y codeql-development-mcp-server
 ```
 
+> **Note:** The npm package bundles the tool query source packs (`.ql` files and lock files), but their CodeQL library dependencies (e.g., `codeql/javascript-all`) must be fetched from GHCR on first use. Run `codeql-development-mcp-server-setup-packs` once after installing to download them (`~/.codeql/packages/`). If you skip this step, the `codeql_pack_install` MCP tool can install dependencies on demand for individual packs.
+
 ### From GitHub Releases
 
 1. Download the latest release from [Releases](https://github.com/advanced-security/codeql-development-mcp-server/releases)
@@ -59,7 +60,7 @@ Add to your `mcp.json` file:
   "servers": {
     "ql-mcp": {
       "command": "npx",
-      "args": ["-y", "@advanced-security/codeql-development-mcp-server"],
+      "args": ["-y", "codeql-development-mcp-server"],
       "type": "stdio"
     }
   }
@@ -98,6 +99,7 @@ Add to your `mcp.json` file:
 
 ## Troubleshooting
 
+- **Tool query errors (e.g., PrintAST fails)**: Run `codeql-development-mcp-server-setup-packs` to install CodeQL pack dependencies
 - **Server not listed**: Verify absolute path in `mcp.json`, restart VS Code
 - **CodeQL errors**: Run `codeql --version` to confirm CLI is installed
 - **Permission denied**: Check file permissions on server directory