fix: Drop Node.js requirement from 22 to 18 and remove cheerio dependency (#572)

* fix: Drop Node.js requirement from 22 to 18 and remove cheerio dependency

Sentry telemetry showed ~20K crash events from users on older Node.js
versions (File is not defined, ReadableStream is not defined) and ~115K
events from corrupted npx caches. This change improves compatibility
by lowering the minimum Node.js version to 18 (matching @modelcontextprotocol/sdk).

- Remove cheerio dependency (required Node >=20.18.1) and the unused
  get-html-skeleton tool, its cache, constants, and tests
- Lower engines.node to >=18 in package.json, manifest.json, docs
- Add Node.js version guard in stdio.ts with a clear error message
- Add Node.js version policy documentation in DEVELOPMENT.md
- Expand README troubleshooting section (npx cache, old Node, log paths)
- CI now tests against Node.js 18, 20, 22, and 24 via matrix strategy

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: Simplify MCP URL assignment and improve README clarity

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jirispilka

.actor/ACTOR.md

@@ -166,7 +166,7 @@ You can run the Apify MCP Server on your local machine by configuring it with Cl
 
 - MacOS or Windows
 - The latest version of Claude Desktop must be installed (or another MCP client)
-- [Node.js](https://nodejs.org/en) (v22 or higher)
+- [Node.js](https://nodejs.org/en) (v18 or higher)
 - [Apify API Token](https://docs.apify.com/platform/integrations/api#api-token) (`APIFY_TOKEN`)
 
 Make sure you have the `node` and `npx` installed properly:
@@ -308,7 +308,7 @@ npx @modelcontextprotocol/inspector npx -y @apify/actors-mcp-server
 
 ## Prerequisites
 
-- [Node.js](https://nodejs.org/en) (v22 or higher)
+- [Node.js](https://nodejs.org/en) (v18 or higher)
 - Python 3.9 or higher
 
 Create an environment file `.env` with the following content:

.github/workflows/_check_code.yaml

@@ -49,15 +49,19 @@ jobs:
                 run: npm run build
 
     test:
-        name: Test
+        name: Test (Node.js ${{ matrix.node-version }})
+        strategy:
+            matrix:
+                node-version: [18, 20, 22, 24]
+            fail-fast: false
         runs-on: ubuntu-latest
 
         steps:
             -   uses: actions/checkout@v6
-            -   name: Use Node.js
+            -   name: Use Node.js ${{ matrix.node-version }}
                 uses: actions/setup-node@v6
                 with:
-                    node-version-file: '.nvmrc'
+                    node-version: ${{ matrix.node-version }}
                     cache: 'npm'
                     cache-dependency-path: 'package-lock.json'
             -   name: Install Dependencies

DEVELOPMENT.md

@@ -34,6 +34,19 @@ Key entry points:
 - `src/main.ts` - Actor entry point (standby server / debugging)
 - `src/input.ts` - Input processing and validation
 
+## Node.js version policy
+
+The minimum supported Node.js version is **18** (`engines.node >= 18` in `package.json`).
+
+**Why Node.js 18 (not higher):**
+The MCP server is installed by end-users via `npx` and must work on the widest reasonable range of Node.js versions. Our key dependency, `@modelcontextprotocol/sdk`, requires Node.js >= 18, and our own source code uses no APIs beyond what Node.js 18 provides. Sentry telemetry showed ~20K crash events from users on older Node versions (`File is not defined`, `ReadableStream is not defined`), confirming that many users run older runtimes.
+
+**Rules for maintaining compatibility:**
+- Do not use Node.js APIs introduced after v18 (e.g., `import.meta.resolve`, `Array.fromAsync`, `Set.union()`).
+- Do not add dependencies that require Node.js > 18 at runtime. Check `engines` field of new dependencies before adding them.
+- CI runs unit tests against Node.js 18, 20, 22, and 24 to catch compatibility regressions.
+- The `.nvmrc` file pins the latest Node.js version for development tooling (lint, type-check, build) — this is intentionally higher than the minimum supported version.
+
 ## How to contribute
 
 Refer to the [CONTRIBUTING.md](./CONTRIBUTING.md) file.

README.md

@@ -235,19 +235,19 @@ All tools include metadata annotations to help MCP clients and LLMs understand t
 
 - **`title`**: Short display name for the tool (e.g., "Search Actors", "Call Actor", "apify/rag-web-browser")
 - **`readOnlyHint`**: `true` for tools that only read data without modifying state (e.g., `get-dataset`, `fetch-actor-details`)
-- **`openWorldHint`**: `true` for tools that access external resources outside the Apify platform (e.g., `call-actor` executes external Actors, `get-html-skeleton` scrapes external websites). Tools that interact only with the Apify platform (like `search-actors` or `fetch-apify-docs`) do not have this hint.
+- **`openWorldHint`**: `true` for tools that access external resources outside the Apify platform (e.g., `call-actor` executes external Actors). Tools that interact only with the Apify platform (like `search-actors` or `fetch-apify-docs`) do not have this hint.
 
 ### Tools configuration
 
-The `tools` configuration parameter is used to specify loaded tools - either categories or specific tools directly, and Apify Actors. For example, `tools=storage,runs` loads two categories; `tools=add-actor` loads just one tool.
+The `tools` configuration parameter is used to specify loaded tools – either categories or specific tools directly, and Apify Actors. For example, `tools=storage,runs` loads two categories; `tools=add-actor` loads just one tool.
 
 When no query parameters are provided, the MCP server loads the following `tools` by default:
 
 - `actors`
 - `docs`
 - `apify/rag-web-browser`
 
-If the tools parameter is specified, only the listed tools or categories will be enabled - no default tools will be included.
+If the tools parameter is specified, only the listed tools or categories will be enabled – no default tools will be included.
 
 > **Easy configuration:**
 >
@@ -390,7 +390,7 @@ For detailed development setup, project structure, and local testing instruction
 
 ## Prerequisites
 
-- [Node.js](https://nodejs.org/en) (v22 or higher)
+- [Node.js](https://nodejs.org/en) (v18 or higher)
 
 Create an environment file, `.env`, with the following content:
 ```text
@@ -446,10 +446,50 @@ The Apify MCP Server is also available on [Docker Hub](https://hub.docker.com/mc
 
 # 🐛 Troubleshooting (local MCP server)
 
-- Make sure you have `node` installed by running `node -v`.
+- Make sure you have `node` (v18 or higher) installed by running `node -v`.
 - Make sure the `APIFY_TOKEN` environment variable is set.
 - Always use the latest version of the MCP server by using `@apify/actors-mcp-server@latest`.
 
+### Common issues
+
+#### "Unable to connect to extension server" or tools not loading
+
+This is most commonly caused by a **corrupted npx cache**. Fix it by clearing the cache and retrying:
+
+```bash
+# Clear the npx cache
+rm -rf ~/.npm/_npx
+
+# Retry
+npx -y @apify/actors-mcp-server@latest
+```
+
+#### Errors like "File is not defined" or "ReadableStream is not defined"
+
+You are running an **outdated version of Node.js**. The Apify MCP server requires Node.js 18 or higher:
+
+```bash
+node -v  # Check your version
+```
+
+If your version is below 18, update Node.js from [nodejs.org](https://nodejs.org).
+
+#### "Cannot find module" errors
+
+This usually indicates a corrupted `npx` cache (see above). Clear it with `rm -rf ~/.npm/_npx` and retry.
+
+#### Server works in Claude Desktop chat but not in cowork mode
+
+This is a known issue we are investigating. As a workaround, try using the hosted server at [mcp.apify.com](https://mcp.apify.com) instead of the local stdio server.
+
+### Checking logs
+
+If you encounter issues, check the Claude Desktop logs for error details:
+
+- **macOS**: `~/Library/Logs/Claude/`
+- **Windows**: `%APPDATA%\Claude\logs\`
+- **Linux**: `~/.config/Claude/logs/`
+
 ### Debugging the NPM package
 
 To debug the server, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) tool:

manifest.json

@@ -88,7 +88,7 @@
       "linux"
     ],
     "runtimes": {
-      "node": ">=22.0.0"
+      "node": ">=18.0.0"
     }
   }
 }

package-lock.json

@@ -5,7 +5,7 @@
   "description": "Apify MCP Server",
   "mcpName": "com.apify/apify-mcp-server",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=18.0.0"
   },
   "main": "dist/index.js",
   "exports": {
@@ -47,13 +47,11 @@
     "@modelcontextprotocol/sdk": "^1.25.2",
     "@segment/analytics-node": "^2.3.0",
     "@sentry/node": "^10.38.0",
-    "@types/cheerio": "^0.22.35",
     "@types/turndown": "^5.0.5",
     "ajv": "^8.17.1",
     "algoliasearch": "^5.31.0",
     "apify": "^3.4.2",
     "apify-client": "^2.22.1",
-    "cheerio": "^1.1.2",
     "dotenv": "^16.4.7",
     "express": "^4.21.2",
     "mcp-client-capabilities": "^0.0.5",

package.json

@@ -46,7 +46,6 @@ export enum HelperTools {
     STORE_SEARCH_INTERNAL = 'search-actors-internal',
     DOCS_SEARCH = 'search-apify-docs',
     DOCS_FETCH = 'fetch-apify-docs',
-    GET_HTML_SKELETON = 'get-html-skeleton',
 }
 
 export const RAG_WEB_BROWSER = 'apify/rag-web-browser';
@@ -101,8 +100,6 @@ export const ACTOR_CACHE_MAX_SIZE = 500;
 export const ACTOR_CACHE_TTL_SECS = 30 * 60; // 30 minutes
 export const APIFY_DOCS_CACHE_MAX_SIZE = 500;
 export const APIFY_DOCS_CACHE_TTL_SECS = 60 * 60; // 1 hour
-export const GET_HTML_SKELETON_CACHE_TTL_SECS = 5 * 60; // 5 minutes
-export const GET_HTML_SKELETON_CACHE_MAX_SIZE = 200;
 export const MCP_SERVER_CACHE_MAX_SIZE = 500;
 export const MCP_SERVER_CACHE_TTL_SECS = 30 * 60; // 30 minutes
 export const USER_CACHE_MAX_SIZE = 200;