bug(mcp): rvlite_cypher tool reports 'not installed' — CJS require() on ESM-only package

[dmoellenbeck]

Bug Description

The rvlite_cypher MCP tool always returns {"success": false, "error": "rvlite package not installed"}, even when rvlite is correctly installed. The MCP server handler uses require('rvlite') (CJS), but rvlite v0.2.x is ESM-only — the CJS entry point returns an empty object.

Environment

• rvlite npm: v0.2.6 (ESM-only since v0.2.x)
• ruvector npm: v0.2.18
• Node.js: v25.7.0
• Platform: macOS (Apple Silicon)
• Usage: via MCP server (npx ruvector mcp start) + rvlite_cypher tool

Steps to Reproduce

# 1. Start MCP server
npx ruvector mcp start

# 2. Call rvlite_cypher via MCP
# → Always returns: {"success": false, "error": "rvlite package not installed"}

# 3. But rvlite IS installed and works directly:
node --input-type=module -e "
import { readFileSync } from 'fs';
const rvlite = await import('rvlite/wasm');
rvlite.initSync(readFileSync('node_modules/rvlite/dist/wasm/rvlite_bg.wasm'));
const cypher = new rvlite.CypherEngine();
cypher.execute('CREATE (:Test {name: \"Alice\"})');
console.log(cypher.execute('MATCH (t:Test) RETURN t.name'));
// → Works perfectly: { columns: ['t.name'], rows: [{ 't.name': {Value:{String:'Alice'}} }] }
"

Root Cause

Located in bin/mcp-server.js, the rvlite_cypher handler uses CJS require():

// Current implementation (CJS)
const rvlite = require('rvlite');
// → Returns {} (empty object) because rvlite v0.2.x only exports via ESM

Since rvlite v0.2.x removed its CJS entry point, require('rvlite') resolves to an empty object. The handler then checks for rvlite.CypherEngine, finds undefined, and reports "not installed".

Suggested Fix

Switch from CJS require() to ESM dynamic import() with WASM initialization:

// Proposed fix
async function getCypherEngine() {
    const rvlite = await import('rvlite/wasm');
    const { readFileSync } = await import('fs');
    const { createRequire } = await import('module');
    const require = createRequire(import.meta.url);
    const wasmPath = require.resolve('rvlite/dist/wasm/rvlite_bg.wasm');
    rvlite.initSync(readFileSync(wasmPath));
    return new rvlite.CypherEngine();
}

Key changes:

1. require('rvlite') → await import('rvlite/wasm') (ESM dynamic import)
2. Add initSync() with WASM buffer — required for the WASM build path
3. Cache the engine instance to avoid re-initializing on every call

Impact

• All rvlite_cypher MCP tool calls fail silently — the tool is completely non-functional
• Affects any application using the ruvector MCP server for Cypher graph queries
• Our coaching system uses rvlite_cypher for knowledge graph pattern analysis (~850 nodes, ~1580 edges). Currently falling back to direct Node.js calls outside the MCP server
• The rvlite_sql and rvlite_sparql tools are likely affected by the same CJS/ESM issue

Workaround

Call rvlite directly via Node.js ESM instead of the MCP tool:

// Direct usage (works)
const rvlite = await import('rvlite/wasm');
rvlite.initSync(readFileSync('node_modules/rvlite/dist/wasm/rvlite_bg.wasm'));
const cypher = new rvlite.CypherEngine();
const result = cypher.execute('MATCH (n:Day) RETURN n.date LIMIT 5');

Or use hooks_recall (vector search) and hooks_learn (Q-learning) as alternatives — these work correctly via the MCP server and don't depend on rvlite.

Related

• Issue CypherEngine: MATCH RETURN produces single row — context.bind() overwrites previous bindings #269 — CypherEngine multi-row fix (shipped in rvlite@0.2.5, works when loaded correctly via ESM)
• The fix in CypherEngine: MATCH RETURN produces single row — context.bind() overwrites previous bindings #269 is validated but unreachable through the MCP server due to this CJS/ESM import issue