build(node.js)!: pf-3843 remove 20 support (#169)

* audit, move dep audit, publishing baselines moved to Node.js 24
* build, engine, moved to Node.js 22 minimum
* cli, Node.js version copy, pin server version to support older Node.js
* docs, references moved to Node.js 22
* package, min engine version, cleaned test scripts
* src, drop Node.js 20 reference
* e2e, cleaned Node.js 20 checks, left itSkip, envNodeVersion

BREAKING CHANGE: Minimum supported Node.js is now 22, previously 20.
MCP clients and integrations running Node.js 20 will fail to start
on `@latest`.

To migrate:
- Either upgrade Node.js to a minimum of 22 LTS.
- Or pin the server configuration to a Node.js 20-compatible release

See usage docs for pinned configuration examples.

Author: cdcabrera

.github/workflows/audit.yml

@@ -1,16 +1,19 @@
-name: Data Audit
+name: Security & Data Audit
 
 on:
   pull_request:
     paths:
       - 'src/docs.json'
       - 'tests/audit/**'
+      - 'package.json'
+      - 'package-lock.json'
   schedule:
     - cron: '0 0 * * *' # Daily at midnight
   workflow_dispatch:
 
 jobs:
-  audit-links:
+  documentation-audit:
+    name: Documentation Audit
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -19,7 +22,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v6.3.0
         with:
-          node-version: 22.x
+          node-version: '24'
           cache: npm
       - name: Install dependencies
         run: npm ci
@@ -30,3 +33,20 @@ jobs:
           DOCS_AUDIT_MAX_TOTAL: ${{ github.event_name == 'schedule' && '0' || '50' }}
         # Advisories are non-blocking for PRs
         continue-on-error: ${{ github.event_name == 'pull_request' }}
+
+  dependency-audit:
+    name: Dependency Audit
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - name: Setup Node.js
+        uses: actions/setup-node@v6.3.0
+        with:
+          node-version: '24'
+          cache: npm
+      - name: Run npm audit
+        run: npm audit --omit=dev --audit-level=critical
+        # Advisories are non-blocking for PRs
+        continue-on-error: ${{ github.event_name == 'pull_request' }}

.github/workflows/integration.yml

@@ -13,30 +13,21 @@ jobs:
       contents: read
     strategy:
       matrix:
-        node-version: [20.x, 22.x, 24.x]
+        node-version: [22.x, 24.x]
     steps:
       - uses: actions/checkout@v6
+
       - name: Setup Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v6.3.0
         with:
           node-version: ${{ matrix.node-version }}
           cache: npm
-      - name: Node.js modules cache
-        uses: actions/cache@v5
-        id: modules-cache
-        with:
-          path: ${{ github.workspace }}/node_modules
-          key: ${{ runner.os }}-${{ matrix.node-version }}-modules-${{ hashFiles('**/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-${{ matrix.node-version }}-modules
+
       - name: Install Node.js packages
-        if: ${{ steps.modules-cache.outputs.cache-hit != 'true' }}
         run: npm ci
-      - name: Audit packages
-        run: npm audit --audit-level=high
-        continue-on-error: true
+
       - name: Lint and test
         run: npm run test:ci
+
       - name: Confirm integration
-        if: ${{ success() }}
         run: npm run test:integration

.github/workflows/publishing.yml

@@ -10,16 +10,12 @@ jobs:
     permissions:
       contents: read
       id-token: write
-    strategy:
-      matrix:
-        node: [22.x]
     steps:
       - uses: actions/checkout@v6
-      - name: Setup Node.js ${{ matrix.node-version }}
+      - name: Setup Node.js
         uses: actions/setup-node@v6.3.0
         with:
-          node-version: ${{ matrix.node-version }}
-          cache: npm
+          node-version: '24'
           registry-url: 'https://registry.npmjs.org'
       - name: Install dependencies
         run: npm ci

README.md

@@ -7,7 +7,7 @@ It is intended to be extensible to meet the needs of different teams and project
 [Read more about our roadmap and how we've structured the server in our architecture docs](./docs/architecture.md).
 
 ## Requirements
-- [Node.js 20+](https://nodejs.org/)
+- [Node.js 22+](https://nodejs.org/)
 - NPM (or equivalent package manager)
 
 ## Quick start
@@ -18,6 +18,8 @@ The PatternFly MCP Server supports multiple configurations; see the [usage docum
 
 #### Set a basic MCP configuration
 
+> Unable to update to the required Node.js version? [See pinned MCP configuration examples for earlier Node.js versions.](./docs/usage.md#pinned-mcp-package-version)
+
 Minimal configuration
 ```json
 {

docs/development.md

@@ -158,8 +158,7 @@ The documentation catalog `src/docs.json` pins remote resources to specific comm
 
 #### Programmatic runtime requirements
 
-- **Node.js 20+**: Required to run the core MCP server.
-- **Node.js 22+**: Required for loading external tool plugins (`--tool`) and for developers working on advanced process isolation features.
+- **Node.js 22+**: Required to run the MCP server, load external tool plugins (`--tool`), and use advanced process isolation features.
 
 **Example: Programmatic test mode**
 ```typescript
@@ -411,7 +410,7 @@ These terms describe **how tools and their related properties are represented**
 
 ### Tool plugins
 
-- **Plugins don't appear**: Verify the Node version (requires Node.js >= 20; >= 22 for tool plugins) and check logs (enable `--log-stderr`).
+- **Plugins don't appear**: Verify the Node version (requires Node.js >= 22 for tool plugins) and check logs (enable `--log-stderr`).
 - **Startup warnings/errors**: Startup `load:ack` warnings/errors from tool plugins are logged when stderr/protocol logging is enabled.
 - **Schema errors**: If `tools/call` rejects with schema errors, ensure `inputSchema` is valid. See [Authoring tools](#authoring-tools) for details.
 - **Network access issues**: If the tool is having network access issues, you may need to configure `--plugin-isolation none`. This is generally discouraged for security reasons but may be necessary in some cases.
@@ -424,7 +423,7 @@ These terms describe **how tools and their related properties are represented**
 
 ### General issues
 
-- **Server won't start**: Check Node.js version (requires Node.js >= 20; >= 22 for tool plugins).
+- **Server won't start**: Check Node.js version (requires Node.js >= 22 to run the server).
 - **Missing tools/resources**: Verify the server started successfully and check logs with `--log-stderr`.
 - **Type errors**: Ensure TypeScript types are installed: `npm install --save-dev @types/node`
 

docs/usage.md

@@ -97,6 +97,33 @@ Access specific component documentation or technical specifications using the fo
 
 Most MCP clients use JSON configuration to specify how the server is started. Below are examples you can adapt for your client.
 
+### Pinned MCP package version
+
+Depending on your environment, you may have to delay updating to the minimum Node.js version required by the server. If you are unable to upgrade your Node.js version and must remain on a previous Node.js version, you can pin your MCP configuration to the last compatible version of the server.
+
+> **Note**: Currently, pinning to an older PatternFly MCP version means you will not receive updated documentation or new features until you "update" your pinned version. In the future, pinning a version may still make an allowance for documentation updates. [See our planned architecture.](./architecture.md#hybrid-documentation-in-progress) 
+
+#### When to choose `@latest` or a pinned version for configuration
+
+| Node.js version | Package spec                        | Feature notes                                                                                                      |
+|-----------------|-------------------------------------|--------------------------------------------------------------------------------------------------------------------|
+| **>=22**        | `@patternfly/patternfly-mcp@latest` | Newest PatternFly features and rules. Includes **enhanced security isolation** for custom tool plugins.            |
+| **>=20**        | `@patternfly/patternfly-mcp@1.1.0`  | Standard features and rules. Lacks **custom tool plugins**; compatible with all default PatternFly configurations. |
+
+##### Node.js 20 compatible pin
+
+```json
+{
+  "mcpServers": {
+    "patternfly-mcp": {
+      "command": "npx",
+      "args": ["-y", "@patternfly/patternfly-mcp@1.1.0"],
+      "description": "PatternFly rules and documentation (Node.js 20 compatible)"
+    }
+  }
+}
+```
+
 ### Minimal client config (stdio)
 
 ```json
@@ -182,14 +209,16 @@ These are **first-step checks** for common setup problems, not full diagnostics.
 
 > **Agents**: PatternFly MCP server information is available internally through the `patternfly://context` MCP resource.
 
-### 1. Verify Node.js Version
-The PatternFly MCP server requires **Node.js 20 or higher**.
+### 1. Verify Node.js version
+The PatternFly MCP server requires **Node.js 22 or higher**.
 
 - **How to check**:
   - **macOS/Linux**: Open **Terminal** and type `node -v`.
   - **Windows**: Open **PowerShell** or **Command Prompt** and type `node -v`.
-- **Requirement**: You should see a version starting with `v20`, `v22`, or higher.
-- **Solution**: If your version is lower than 20, please download and install the latest "LTS" (Long Term Support) version from [nodejs.org](https://nodejs.org/).
+- **Requirement**: You should see a version starting with `v22`, or higher.
+- **Solution**: If your version is lower than 22, please download and install the latest "LTS" (Long Term Support) version from [nodejs.org](https://nodejs.org/).
+
+> **Unable to update your Node.js version?** [See pinned configuration examples for earlier Node.js versions.](#pinned-mcp-package-version)
 
 ### 2. Reset the npx Cache
 If you encounter an `ERR_MODULE_NOT_FOUND` error or don't see the latest features, your system may be using a "stale" or corrupted version in its cache.

guidelines/agent_behaviors.md

@@ -45,7 +45,7 @@ For a detailed overview of the system design and roadmap, see [docs/architecture
 - **Validation Required**: Follow checklists; verify requirements; test thoroughly. Review [pull request warning signs](../CONTRIBUTING.md#pull-requests) to avoid common pitfalls.
 - **Confirmation Required**: Confirm success; summarize changes; explain impact; verify understanding.
 - **Guidance Review Scope**: Unless the user explicitly asks, do not make recommendations on improving guidance if all you're asked to do is review guidance.
-- **Environment Awareness**: 
+- **Environment Awareness**:
   - Server and plugin execution requirements are defined in `package.json`.
   - Always verify environment compatibility by checking `patternfly://context` or `package.json`.
   - Proactively check for environment mismatches (e.g., Node.js version) if tools fail to load.

jest.config.ts

@@ -36,7 +36,7 @@ export default {
   projects: [
     {
       displayName: 'unit',
-      roots: ['src'],
+      roots: ['<rootDir>/src'],
       testMatch: ['<rootDir>/src/**/*.test.ts'],
       setupFilesAfterEnv: ['<rootDir>/jest.setupTests.ts'],
       ...baseConfig,
@@ -64,7 +64,7 @@ export default {
     },
     {
       displayName: 'e2e',
-      roots: ['tests/e2e'],
+      roots: ['<rootDir>/tests/e2e'],
       testMatch: ['<rootDir>/tests/e2e/**/*.test.ts'],
       setupFilesAfterEnv: ['<rootDir>/tests/e2e/jest.setupTests.ts'],
       transformIgnorePatterns: [
@@ -74,7 +74,7 @@ export default {
     },
     {
       displayName: 'audit',
-      roots: ['tests/audit'],
+      roots: ['<rootDir>/tests/audit'],
       testMatch: ['<rootDir>/tests/audit/**/*.test.ts'],
       ...baseConfig
     }

package-lock.json

@@ -31,11 +31,11 @@
     "release": "changelog --non-cc --link-url https://github.com/patternfly/patternfly-mcp.git",
     "start": "node dist/cli.js --log-stderr",
     "start:dev": "tsx watch src/cli.ts --verbose --log-stderr",
-    "test": "npm run test:spell && npm run test:spell-docs && npm run test:lint && npm run test:types && jest --selectProjects unit --roots=src/",
-    "test:audit": "jest --selectProjects audit --roots=tests/audit/",
+    "test": "npm run test:spell && npm run test:spell-docs && npm run test:lint && npm run test:types && jest --selectProjects unit",
+    "test:audit": "jest --selectProjects audit",
     "test:ci": "npm test -- --coverage",
     "test:dev": "npm test -- --watchAll",
-    "test:integration": "npm run build && NODE_OPTIONS='--experimental-vm-modules' jest --selectProjects e2e --roots=tests/e2e/",
+    "test:integration": "npm run build && NODE_OPTIONS='--experimental-vm-modules' jest --selectProjects e2e",
     "test:integration-dev": "npm run test:integration -- --watchAll",
     "test:lint": "eslint .",
     "test:lint-fix": "eslint . --fix",
@@ -84,7 +84,7 @@
     "typescript-eslint": "^8.59.1"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "repository": {
     "type": "git",