From d6987a3dc1412d9a58c7dbe72530ecf5fb970e34 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CBeeRad=E2=80=9D?= <bradwmorriswork@gmail.com>
Date: Tue, 10 Feb 2026 15:58:21 +1100
Subject: [PATCH] =?UTF-8?q?fix(mcp):=20v1.4.1=20=E2=80=94=20add=20Node=20v?=
 =?UTF-8?q?ersion=20check=20and=20better-sqlite3=20error=20handling?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Check Node version on startup, exit with clear message if >=24
- Catch better-sqlite3 load failure with actionable error message
- Cap engines to node >=18 <24 in package.json

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 apps/mcp-server-standalone/index.js     | 25 ++++++++++++++++++++++++-
 apps/mcp-server-standalone/package.json |  4 ++--
 2 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/apps/mcp-server-standalone/index.js b/apps/mcp-server-standalone/index.js
index ab8c609..89cfff4 100755
--- a/apps/mcp-server-standalone/index.js
+++ b/apps/mcp-server-standalone/index.js
@@ -1,6 +1,29 @@
 #!/usr/bin/env node
 'use strict';
 
+// Check Node version early — better-sqlite3 native bindings don't support bleeding-edge Node
+const nodeVersion = parseInt(process.versions.node.split('.')[0], 10);
+if (nodeVersion >= 24) {
+  console.error(`[ra-h-mcp-server] ERROR: Node.js v${process.versions.node} is not supported.`);
+  console.error('[ra-h-mcp-server] better-sqlite3 requires Node 18-22 LTS. Install Node 22:');
+  console.error('[ra-h-mcp-server]   nvm install 22 && nvm use 22');
+  console.error('[ra-h-mcp-server]   or: brew install node@22');
+  process.exit(1);
+}
+
+let Database;
+try {
+  Database = require('better-sqlite3');
+} catch (err) {
+  console.error('[ra-h-mcp-server] ERROR: Failed to load better-sqlite3 native module.');
+  console.error(`[ra-h-mcp-server] Node version: ${process.versions.node}`);
+  console.error('[ra-h-mcp-server] This usually means the native bindings need rebuilding:');
+  console.error('[ra-h-mcp-server]   npm rebuild better-sqlite3');
+  console.error('[ra-h-mcp-server] Or your Node version is too new. Use Node 18-22 LTS.');
+  console.error('[ra-h-mcp-server] Original error:', err.message);
+  process.exit(1);
+}
+
 const { z } = require('zod');
 const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
@@ -14,7 +37,7 @@ const guideService = require('./services/guideService');
 // Server info
 const serverInfo = {
   name: 'ra-h-standalone',
-  version: '1.4.0'
+  version: '1.4.1'
 };
 
 const instructions = [
diff --git a/apps/mcp-server-standalone/package.json b/apps/mcp-server-standalone/package.json
index de9540a..62fce37 100644
--- a/apps/mcp-server-standalone/package.json
+++ b/apps/mcp-server-standalone/package.json
@@ -1,6 +1,6 @@
 {
   "name": "ra-h-mcp-server",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Connect Claude Code/Desktop to your RA-H knowledge base. Direct SQLite access - no web app required.",
   "main": "index.js",
   "bin": {
@@ -38,7 +38,7 @@
     "zod": "^3.23.0"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18.0.0 <24.0.0"
   },
   "files": [
     "index.js",