@softerist/heuristic-mcp 3.0.15 → 3.0.16

package/lib/vector-store-sqlite.js

@@ -224,18 +224,18 @@ export class SqliteVectorStore {
         view.content = row.content;
       }
 
-      if (includeVector && row.vector) {
-        const expectedBytes = this.dim * Float32Array.BYTES_PER_ELEMENT;
-        if (row.vector.byteLength >= expectedBytes) {
-          // Copy the buffer to avoid issues with SQLite reusing internal buffers
-          const bufferView = new Float32Array(
-            row.vector.buffer,
-            row.vector.byteOffset,
-            this.dim
-          );
-          view.vector = new Float32Array(bufferView);
-        }
-      }
+      if (includeVector && row.vector) {
+        const expectedBytes = this.dim * Float32Array.BYTES_PER_ELEMENT;
+        if (row.vector.byteLength >= expectedBytes) {
+          // Copy the buffer to avoid issues with SQLite reusing internal buffers
+          const bufferView = new Float32Array(
+            row.vector.buffer,
+            row.vector.byteOffset,
+            this.dim
+          );
+          view.vector = new Float32Array(bufferView);
+        }
+      }
 
       views.push(view);
     }
@@ -264,7 +264,7 @@ export class SqliteVectorStore {
    * @param {Array} chunks - Array of chunk objects with vector, file, startLine, endLine, content
    * @param {Object} options - { getContent, preRename }
    */
-  static async write(cacheDir, chunks, { getContent, getVector, preRename } = {}) {
+  static async write(cacheDir, chunks, { getContent, getVector, preRename } = {}) {
     if (!chunks || chunks.length === 0) {
       return null;
     }
@@ -286,10 +286,10 @@ export class SqliteVectorStore {
       denseSourceIndices.push(i);
     }
 
-    const resolveContent = async (chunk, sourceIndex) => {
-      if (chunk.content !== undefined && chunk.content !== null) {
-        return chunk.content;
-      }
+    const resolveContent = async (chunk, sourceIndex) => {
+      if (chunk.content !== undefined && chunk.content !== null) {
+        return chunk.content;
+      }
       if (typeof getContent === 'function') {
         const value = getContent(chunk, sourceIndex);
         if (value && typeof value.then === 'function') {
@@ -297,39 +297,39 @@ export class SqliteVectorStore {
         }
         return value;
       }
-      return null;
-    };
-
-    const resolveVector = async (chunk, sourceIndex) => {
-      let vectorSource = chunk.vector;
-      if (
-        (vectorSource === undefined || vectorSource === null) &&
-        typeof getVector === 'function'
-      ) {
-        vectorSource = getVector(chunk, sourceIndex);
-        if (vectorSource && typeof vectorSource.then === 'function') {
-          vectorSource = await vectorSource;
-        }
-      }
-      if (vectorSource === undefined || vectorSource === null) {
-        throw new Error(`Missing vector data for sqlite cache write at index ${sourceIndex}`);
-      }
-      const vector =
-        vectorSource instanceof Float32Array
-          ? vectorSource
-          : ArrayBuffer.isView(vectorSource)
-            ? Float32Array.from(vectorSource)
-            : Float32Array.from(vectorSource);
-      if (!vector || vector.length === 0) {
-        throw new Error(`Empty vector data for sqlite cache write at index ${sourceIndex}`);
-      }
-      return vector;
-    };
-
-    const dim =
-      denseChunks.length > 0
-        ? (await resolveVector(denseChunks[0], denseSourceIndices[0])).length
-        : 0;
+      return null;
+    };
+
+    const resolveVector = async (chunk, sourceIndex) => {
+      let vectorSource = chunk.vector;
+      if (
+        (vectorSource === undefined || vectorSource === null) &&
+        typeof getVector === 'function'
+      ) {
+        vectorSource = getVector(chunk, sourceIndex);
+        if (vectorSource && typeof vectorSource.then === 'function') {
+          vectorSource = await vectorSource;
+        }
+      }
+      if (vectorSource === undefined || vectorSource === null) {
+        throw new Error(`Missing vector data for sqlite cache write at index ${sourceIndex}`);
+      }
+      const vector =
+        vectorSource instanceof Float32Array
+          ? vectorSource
+          : ArrayBuffer.isView(vectorSource)
+            ? Float32Array.from(vectorSource)
+            : Float32Array.from(vectorSource);
+      if (!vector || vector.length === 0) {
+        throw new Error(`Empty vector data for sqlite cache write at index ${sourceIndex}`);
+      }
+      return vector;
+    };
+
+    const dim =
+      denseChunks.length > 0
+        ? (await resolveVector(denseChunks[0], denseSourceIndices[0])).length
+        : 0;
 
     // Create new database
     const db = new Database(writePath);
@@ -364,51 +364,51 @@ export class SqliteVectorStore {
       CREATE INDEX idx_chunks_file ON chunks(file);
     `);
 
-    // Insert metadata
-    const insertMeta = db.prepare(`INSERT INTO metadata (key, value) VALUES (?, ?)`);
-    insertMeta.run('version', String(STORE_VERSION));
-    insertMeta.run('dim', String(dim));
-    insertMeta.run('count', String(denseChunks.length));
-    insertMeta.run('createdAt', new Date().toISOString());
-
-    // Insert chunks in a transaction for speed without pre-materializing all vectors/content.
-    const insertChunk = db.prepare(`
-      INSERT INTO chunks (id, file, startLine, endLine, content, vector)
-      VALUES (?, ?, ?, ?, ?, ?)
-    `);
-
-    db.exec('BEGIN');
-    try {
-      for (let i = 0; i < denseChunks.length; i += 1) {
-        const chunk = denseChunks[i];
-        const sourceIndex = denseSourceIndices[i];
-        const vector = await resolveVector(chunk, sourceIndex);
-        if (vector.length !== dim) {
-          throw new Error('Vector dimension mismatch in sqlite cache write');
-        }
-        let content = await resolveContent(chunk, sourceIndex);
-        if (content === undefined) content = null;
-        if (content !== null && typeof content !== 'string') {
-          content = String(content);
-        }
-        insertChunk.run(
-          i,
-          chunk.file,
-          chunk.startLine ?? 0,
-          chunk.endLine ?? 0,
-          content,
-          Buffer.from(vector.buffer, vector.byteOffset, vector.byteLength)
-        );
-      }
-      db.exec('COMMIT');
-    } catch (error) {
-      try {
-        db.exec('ROLLBACK');
-      } catch {
-        // ignore rollback errors
-      }
-      throw error;
-    }
+    // Insert metadata
+    const insertMeta = db.prepare(`INSERT INTO metadata (key, value) VALUES (?, ?)`);
+    insertMeta.run('version', String(STORE_VERSION));
+    insertMeta.run('dim', String(dim));
+    insertMeta.run('count', String(denseChunks.length));
+    insertMeta.run('createdAt', new Date().toISOString());
+
+    // Insert chunks in a transaction for speed without pre-materializing all vectors/content.
+    const insertChunk = db.prepare(`
+      INSERT INTO chunks (id, file, startLine, endLine, content, vector)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `);
+
+    db.exec('BEGIN');
+    try {
+      for (let i = 0; i < denseChunks.length; i += 1) {
+        const chunk = denseChunks[i];
+        const sourceIndex = denseSourceIndices[i];
+        const vector = await resolveVector(chunk, sourceIndex);
+        if (vector.length !== dim) {
+          throw new Error('Vector dimension mismatch in sqlite cache write');
+        }
+        let content = await resolveContent(chunk, sourceIndex);
+        if (content === undefined) content = null;
+        if (content !== null && typeof content !== 'string') {
+          content = String(content);
+        }
+        insertChunk.run(
+          i,
+          chunk.file,
+          chunk.startLine ?? 0,
+          chunk.endLine ?? 0,
+          content,
+          Buffer.from(vector.buffer, vector.byteOffset, vector.byteLength)
+        );
+      }
+      db.exec('COMMIT');
+    } catch (error) {
+      try {
+        db.exec('ROLLBACK');
+      } catch {
+        // ignore rollback errors
+      }
+      throw error;
+    }
 
     // Optimize the database
     db.exec('ANALYZE');

package/lib/workspace-env.js

@@ -1,28 +1,28 @@
-import {
-  DYNAMIC_WORKSPACE_ENV_PREFIX,
-  WORKSPACE_ENV_KEY_PATTERN,
-  WORKSPACE_ENV_VARS,
-} from './constants.js';
-
-export function scoreWorkspaceEnvKey(key) {
-  const upper = String(key || '').toUpperCase();
-  let score = 0;
-  if (upper.includes('WORKSPACE')) score += 8;
-  if (upper.includes('PROJECT')) score += 4;
-  if (upper.includes('ROOT')) score += 3;
-  if (upper.includes('CWD')) score += 2;
-  if (upper.includes('DIR')) score += 1;
-  return score;
-}
-
-export function getDynamicWorkspaceEnvKeys(env = process.env) {
-  return Object.keys(env)
-    .filter((key) => key.startsWith(DYNAMIC_WORKSPACE_ENV_PREFIX))
-    .filter((key) => WORKSPACE_ENV_KEY_PATTERN.test(key))
-    .filter((key) => !WORKSPACE_ENV_VARS.includes(key))
-    .sort((a, b) => scoreWorkspaceEnvKey(b) - scoreWorkspaceEnvKey(a));
-}
-
-export function getWorkspaceEnvKeys(env = process.env) {
-  return [...WORKSPACE_ENV_VARS, ...getDynamicWorkspaceEnvKeys(env)];
-}
+import {
+  DYNAMIC_WORKSPACE_ENV_PREFIX,
+  WORKSPACE_ENV_KEY_PATTERN,
+  WORKSPACE_ENV_VARS,
+} from './constants.js';
+
+export function scoreWorkspaceEnvKey(key) {
+  const upper = String(key || '').toUpperCase();
+  let score = 0;
+  if (upper.includes('WORKSPACE')) score += 8;
+  if (upper.includes('PROJECT')) score += 4;
+  if (upper.includes('ROOT')) score += 3;
+  if (upper.includes('CWD')) score += 2;
+  if (upper.includes('DIR')) score += 1;
+  return score;
+}
+
+export function getDynamicWorkspaceEnvKeys(env = process.env) {
+  return Object.keys(env)
+    .filter((key) => key.startsWith(DYNAMIC_WORKSPACE_ENV_PREFIX))
+    .filter((key) => WORKSPACE_ENV_KEY_PATTERN.test(key))
+    .filter((key) => !WORKSPACE_ENV_VARS.includes(key))
+    .sort((a, b) => scoreWorkspaceEnvKey(b) - scoreWorkspaceEnvKey(a));
+}
+
+export function getWorkspaceEnvKeys(env = process.env) {
+  return [...WORKSPACE_ENV_VARS, ...getDynamicWorkspaceEnvKeys(env)];
+}

package/mcp_config.json

@@ -1,9 +1,9 @@
-{
-  "mcpServers": {
-    "heuristic-mcp": {
-      "command": "node",
-      "args": ["scripts\\mcp-launcher.js"],
-      "disabled": false
-    }
-  }
-}
+{
+  "mcpServers": {
+    "heuristic-mcp": {
+      "command": "node",
+      "args": ["scripts\\mcp-launcher.js"],
+      "disabled": false
+    }
+  }
+}

package/package.json

@@ -1,75 +1,86 @@
-{
-  "name": "@softerist/heuristic-mcp",
-  "version": "3.0.15",
-  "description": "An enhanced MCP server providing intelligent semantic code search with find-similar-code, recency ranking, and improved chunking. Fork of smart-coding-mcp.",
-  "type": "module",
-  "main": "index.js",
-  "bin": {
-    "heuristic-mcp": "index.js"
-  },
-  "scripts": {
-    "start": "node --expose-gc index.js",
-    "dev": "node --expose-gc --watch index.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "clean": "node scripts/clear-cache.js",
-    "lint": "eslint .",
-    "format": "prettier --write .",
-    "postinstall": "node scripts/postinstall.js && node scripts/download-model.js"
-  },
-  "keywords": [
-    "mcp",
-    "semantic-search",
-    "code-search",
-    "embeddings",
-    "ai",
-    "model-context-protocol",
-    "hybrid-search",
-    "code-intelligence",
-    "cursor",
-    "vscode",
-    "claude",
-    "codex",
-    "openai",
-    "gemini",
-    "anthropic",
-    "antigravity",
-    "heuristic"
-  ],
-  "author": {
-    "name": "Softerist",
-    "url": "https://github.com/softerist"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/softerist/heuristic-mcp.git"
-  },
-  "homepage": "https://github.com/softerist/heuristic-mcp#readme",
-  "license": "MIT",
-  "dependencies": {
-    "@huggingface/transformers": "^3.8.1",
-    "@modelcontextprotocol/sdk": "^1.0.4",
-    "better-sqlite3": "^12.6.2",
-    "chokidar": "^3.5.3",
-    "fdir": "^6.5.0",
-    "ignore": "^7.0.5",
-    "punycode": "^2.3.1"
-  },
-  "optionalDependencies": {
-    "hnswlib-node": "^3.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "overrides": {
-    "punycode": "^2.3.1"
-  },
-  "devDependencies": {
-    "@eslint/js": "^9.39.2",
-    "@vitest/coverage-v8": "^4.0.18",
-    "eslint": "^9.39.2",
-    "globals": "^17.1.0",
-    "prettier": "^3.8.1",
-    "vitest": "^4.0.16"
-  }
-}
+{
+  "name": "@softerist/heuristic-mcp",
+  "version": "3.0.16",
+  "description": "An enhanced MCP server providing intelligent semantic code search with find-similar-code, recency ranking, and improved chunking. Fork of smart-coding-mcp.",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "heuristic-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "config.jsonc",
+    "mcp_config.json",
+    "search-configs.js",
+    "lib/",
+    "features/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node --expose-gc index.js",
+    "dev": "node --expose-gc --watch index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "node scripts/clear-cache.js",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "postinstall": "node scripts/postinstall.js && node scripts/download-model.js"
+  },
+  "keywords": [
+    "mcp",
+    "semantic-search",
+    "code-search",
+    "embeddings",
+    "ai",
+    "model-context-protocol",
+    "hybrid-search",
+    "code-intelligence",
+    "cursor",
+    "vscode",
+    "claude",
+    "codex",
+    "openai",
+    "gemini",
+    "anthropic",
+    "antigravity",
+    "heuristic"
+  ],
+  "author": {
+    "name": "Softerist",
+    "url": "https://github.com/softerist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/softerist/heuristic-mcp.git"
+  },
+  "homepage": "https://github.com/softerist/heuristic-mcp#readme",
+  "license": "MIT",
+  "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "better-sqlite3": "^12.6.2",
+    "chokidar": "^3.5.3",
+    "fdir": "^6.5.0",
+    "ignore": "^7.0.5",
+    "punycode": "^2.3.1"
+  },
+  "optionalDependencies": {
+    "hnswlib-node": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "overrides": {
+    "punycode": "^2.3.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.39.2",
+    "globals": "^17.1.0",
+    "prettier": "^3.8.1",
+    "vitest": "^4.0.16"
+  }
+}

package/scripts/clear-cache.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import fs from 'fs/promises';
+import { loadConfig } from '../lib/config.js';
+
+async function clearCache() {
+  try {
+    const config = await loadConfig(process.cwd());
+    const cacheDir = config.cacheDirectory;
+
+    // Remove cache directory
+    await fs.rm(cacheDir, { recursive: true, force: true });
+    console.info(`Cache cleared successfully: ${cacheDir}`);
+    console.info('Next startup will perform a full reindex.');
+  } catch (error) {
+    console.error(`Error clearing cache: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+clearCache();

package/scripts/download-model.js

@@ -0,0 +1,43 @@
+import path from 'path';
+
+import { getGlobalCacheDir } from '../lib/config.js';
+
+async function downloadModel() {
+  const globalCacheDir = path.join(getGlobalCacheDir(), 'xenova');
+
+  try {
+    const transformers = await import('@huggingface/transformers');
+    const { pipeline, env } = transformers;
+
+    // Force cache directory to global location
+    env.cacheDir = globalCacheDir;
+
+    console.info(`[Model Setup] Pre-caching model to: ${globalCacheDir}`);
+    // Check if network is available by pinging HF (simple check)
+    // Actually, pipeline() will fail fast if network is down
+    console.info(`[Model Setup] Downloading 'jinaai/jina-embeddings-v2-base-code'...`);
+
+    // This will download the model to the cache directory
+    await pipeline('feature-extraction', 'jinaai/jina-embeddings-v2-base-code');
+
+    console.info(`[Model Setup] ✅ Model cached successfully!`);
+  } catch (error) {
+    if (error && error.code === 'ERR_MODULE_NOT_FOUND') {
+      console.warn(
+        '[Model Setup] ⚠️  Transformers not available yet; skipping model pre-download.'
+      );
+      console.warn(
+        '[Model Setup] This is okay! The server will attempt to download it when started.'
+      );
+      return;
+    }
+    console.warn(`[Model Setup] ⚠️  Constructive warning: Failed to pre-download model.`);
+    console.warn(
+      '[Model Setup] This is okay! The server will attempt to download it when started.'
+    );
+    console.warn(`[Model Setup] Error details: ${error.message}`);
+    // Don't fail the install, just warn
+  }
+}
+
+downloadModel();

package/scripts/mcp-launcher.js

@@ -0,0 +1,49 @@
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { getWorkspaceEnvKeys } from '../lib/workspace-env.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, '..');
+const indexPath = path.join(repoRoot, 'index.js');
+
+let workspace;
+const passthrough = [];
+
+function readWorkspaceFromEnv() {
+  for (const key of getWorkspaceEnvKeys()) {
+    const value = process.env[key];
+    if (!value || value.includes('${')) continue;
+    return value;
+  }
+  return null;
+}
+
+for (let i = 2; i < process.argv.length; i += 1) {
+  const arg = process.argv[i];
+  if (arg === '--workspace' && i + 1 < process.argv.length) {
+    workspace = process.argv[i + 1];
+    i += 1;
+    continue;
+  }
+  passthrough.push(arg);
+}
+
+if (!workspace) {
+  workspace = readWorkspaceFromEnv();
+}
+
+if (!workspace) {
+  workspace = process.cwd();
+}
+
+const args = ['--expose-gc', indexPath, '--workspace', workspace, ...passthrough];
+const child = spawn(process.execPath, args, { stdio: 'inherit' });
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 1);
+});

package/scripts/postinstall.js

@@ -0,0 +1,12 @@
+import { register } from '../features/register.js';
+
+// Run the registration process - MUST await to ensure file writes complete
+console.info('[PostInstall] Running Heuristic MCP registration...');
+
+try {
+  await register();
+  console.info('[PostInstall] Registration complete.');
+} catch (err) {
+  console.error('[PostInstall] Registration failed:', err.message);
+  // Don't fail the install if registration fails, just warn
+}

package/search-configs.js

@@ -1,36 +1,36 @@
-import { loadConfig } from './lib/config.js';
-import { EmbeddingsCache } from './lib/cache.js';
-import { HybridSearch } from './features/hybrid-search.js';
-import { pipeline, env } from '@huggingface/transformers';
-
-// Force same thread config as server
-if (env?.backends?.onnx) {
-  env.backends.onnx.numThreads = 2;
-  if (env.backends.onnx.wasm) {
-    env.backends.onnx.wasm.numThreads = 2;
-  }
-}
-
-async function searchConfigs() {
-  const config = await loadConfig(process.cwd());
-  const cache = new EmbeddingsCache(config);
-  await cache.load();
-
-  const embedder = async (text) => {
-    const pipe = await pipeline('feature-extraction', config.embeddingModel, {
-      session_options: { numThreads: 2 },
-      dtype: 'fp32',
-    });
-    return pipe(text, { pooling: 'mean', normalize: true });
-  };
-
-  const searcher = new HybridSearch(embedder, cache, config);
-  const { results } = await searcher.search('configuration files, config, settings');
-
-  console.info(JSON.stringify(results, null, 2));
-}
-
-searchConfigs().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
+import { loadConfig } from './lib/config.js';
+import { EmbeddingsCache } from './lib/cache.js';
+import { HybridSearch } from './features/hybrid-search.js';
+import { pipeline, env } from '@huggingface/transformers';
+
+// Force same thread config as server
+if (env?.backends?.onnx) {
+  env.backends.onnx.numThreads = 2;
+  if (env.backends.onnx.wasm) {
+    env.backends.onnx.wasm.numThreads = 2;
+  }
+}
+
+async function searchConfigs() {
+  const config = await loadConfig(process.cwd());
+  const cache = new EmbeddingsCache(config);
+  await cache.load();
+
+  const embedder = async (text) => {
+    const pipe = await pipeline('feature-extraction', config.embeddingModel, {
+      session_options: { numThreads: 2 },
+      dtype: 'fp32',
+    });
+    return pipe(text, { pooling: 'mean', normalize: true });
+  };
+
+  const searcher = new HybridSearch(embedder, cache, config);
+  const { results } = await searcher.search('configuration files, config, settings');
+
+  console.info(JSON.stringify(results, null, 2));
+}
+
+searchConfigs().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});