fix(mcp): enforce Node 24 native runtime

Author: DeepWiki Dev

.node-version

@@ -0,0 +1 @@
+24.18.0

packages/mcp/package.json

@@ -34,6 +34,9 @@
   ],
   "author": "abdush",
   "license": "MIT",
+  "engines": {
+    "node": "24.x"
+  },
   "type": "module",
   "bin": {
     "context7-mcp": "dist/index.js"

packages/mcp/src/index.ts

@@ -21,6 +21,7 @@ import { randomUUID } from "node:crypto";
 import { createSessionStore } from "./lib/sessionStore.js";
 import { SERVER_VERSION } from "./lib/constants.js";
 import { localContext7Service } from "./local/service.js";
+import { assertSupportedNodeRuntime } from "./runtime.js";
 
 /** Default HTTP server port */
 const DEFAULT_PORT = 3000;
@@ -538,6 +539,7 @@ function installTransportArgAliasing(transport: Transport): void {
 }
 
 async function main() {
+  assertSupportedNodeRuntime();
   const transportType = TRANSPORT_TYPE;
 
   if (transportType === "http") {

packages/mcp/src/local/service.ts

@@ -1,4 +1,3 @@
-import { initDatabase } from "@neuledge/context";
 import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import type {
@@ -31,6 +30,11 @@ import type {
 
 const MAX_INDEX_CANDIDATES = 5;
 
+async function initializeNativeDatabase(): Promise<void> {
+  const { initDatabase } = await import("@neuledge/context");
+  await initDatabase();
+}
+
 function resultFromManifest(manifest: LibraryManifest): SearchResult {
   const safe = (value: string, limit: number) =>
     value
@@ -82,7 +86,9 @@ export class LocalContext7Service {
     this.store = new LocalLibraryStore(config);
     this.discovery = new LibraryDiscovery(config);
     this.builder = new LocalLibraryBuilder(config, this.store);
-    this.ready = Promise.all([this.store.initialize(), initDatabase()]).then(() => undefined);
+    this.ready = Promise.all([this.store.initialize(), initializeNativeDatabase()]).then(
+      () => undefined
+    );
   }
 
   private async buildOnce(

packages/mcp/src/runtime.ts

@@ -0,0 +1,11 @@
+export const SUPPORTED_NODE_MAJOR = 24;
+
+export function assertSupportedNodeRuntime(nodeVersion: string = process.versions.node): void {
+  const major = Number.parseInt(nodeVersion.split(".", 1)[0] ?? "", 10);
+  if (major === SUPPORTED_NODE_MAJOR) return;
+
+  throw new Error(
+    `Context7 Local requires Node.js ${SUPPORTED_NODE_MAJOR}.x because its local SQLite index uses native modules. ` +
+      `Detected Node.js ${nodeVersion}. Run the MCP server with Node.js ${SUPPORTED_NODE_MAJOR}.x or reinstall dependencies with the selected Node.js runtime.`
+  );
+}

packages/mcp/test/runtime.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, test } from "vitest";
+import { SUPPORTED_NODE_MAJOR, assertSupportedNodeRuntime } from "../src/runtime.js";
+
+describe("MCP native runtime compatibility", () => {
+  test("accepts the Node.js runtime used to install native SQLite dependencies", () => {
+    expect(() => assertSupportedNodeRuntime("24.18.0")).not.toThrow();
+  });
+
+  test("rejects an incompatible runtime before native modules are loaded", () => {
+    expect(() => assertSupportedNodeRuntime("26.5.0")).toThrow(
+      `Context7 Local requires Node.js ${SUPPORTED_NODE_MAJOR}.x`
+    );
+  });
+});