@softerist/heuristic-mcp 2.1.2 → 2.1.3

package/README.md

@@ -86,14 +86,33 @@ Since it runs the **Local LLM** (Xenova) directly on your machine:
 
 For a developer (or an AI agent) working on a confusing or large project, this tool is a massive productivity booster. It essentially turns the entire codebase into a searchable database of knowledge.
 
-**Performance**
+## How This is Different
+
+Most MCP servers and RAG tools are "naive"—they just embed code chunks and run a vector search. **Heuristic MCP** is different because it adds **deterministic intelligence** on top of AI:
+
+| Feature | Generic MCP / RAG Tool | Heuristic MCP |
+| :- | :- | :- |
+| **Ranking** | Pure similarity score | Similarity + **Call Graph Proximity** + **Recency Boost** |
+| **Logic** | "Is this text similar?" | "Is this similar, AND used by this function, AND active?" |
+| **Refactoring** | N/A | **`find_similar_code`** tool to detect duplicates |
+| **Tuning** | Static (hardcoded) | **Runtime Config** (adjust ANN parameters on the fly) |
+
+### Comparison to Cursor
+
+[Cursor](https://cursor.sh) is an excellent AI editor with built-in codebase indexing.
+
+- **Cursor** is an *Editor*: You must use their IDE to get the features.
+- **Heuristic MCP** is a *Protocol*: It brings Cursor-like intelligence to **any** tool (Claude Desktop, multiple IDEs, agentic workflows) without locking you into a specific editor.
+- **Transparency**: This is open-source. You know exactly how your code is indexed and where the data lives (locally).
+
+## Performance
 
 - Pre-indexed embeddings are faster than scanning files at runtime
 - Smart project detection skips dependencies automatically (node_modules, vendor, etc.)
 - Incremental updates - only re-processes changed files
 - Optional ANN search (HNSW) for faster queries on large codebases
 
-**Privacy**
+## Privacy
 
 - Everything runs locally on your machine
 - Your code never leaves your system
@@ -269,13 +288,6 @@ Query: "error handling and exceptions"
 
 Finds all try/catch blocks and error handling patterns.
 
-## Privacy
-
-- AI model runs entirely on your machine
-- No network requests to external services
-- No telemetry or analytics
-- Cache stored locally in `.smart-coding-cache/`
-
 ## Technical Details
 
 **Embedding Model**: all-MiniLM-L6-v2 via transformers.js

package/features/index-codebase.js

@@ -503,6 +503,7 @@ export class CodebaseIndexer {
         console.error("[Indexer] Force reindex requested: clearing cache");
         this.cache.setVectorStore([]);
         this.cache.fileHashes = new Map();
+        await this.cache.clearCallGraphData({ removeFile: true });
       }
 
       const totalStartTime = Date.now();
@@ -520,9 +521,10 @@ export class CodebaseIndexer {
     // Send progress: discovery complete
     this.sendProgress(5, 100, `Discovered ${files.length} files`);
 
+    const currentFilesSet = new Set(files);
+
     // Step 1.5: Prune deleted or excluded files from cache
     if (!force) {
-      const currentFilesSet = new Set(files);
       const cachedFiles = Array.from(this.cache.fileHashes.keys());
       let prunedCount = 0;
 
@@ -540,10 +542,16 @@ export class CodebaseIndexer {
         }
         // If we pruned files, we should save these changes even if no other files changed
       }
+
+      const prunedCallGraph = this.cache.pruneCallGraphData(currentFilesSet);
+      if (prunedCallGraph > 0 && this.config.verbose) {
+        console.error(`[Indexer] Pruned ${prunedCallGraph} call-graph entries`);
+      }
     }
 
     // Step 2: Pre-filter unchanged files (early hash check)
     const filesToProcess = await this.preFilterFiles(files);
+    const filesToProcessSet = new Set(filesToProcess.map(entry => entry.file));
 
     if (filesToProcess.length === 0) {
       console.error("[Indexer] All files unchanged, nothing to index");
@@ -556,17 +564,37 @@ export class CodebaseIndexer {
 
         const missingCallData = [];
         for (const file of cachedFiles) {
-          if (!callDataFiles.has(file)) {
+          if (!callDataFiles.has(file) && currentFilesSet.has(file)) {
             missingCallData.push(file);
           }
         }
 
         if (missingCallData.length > 0) {
           console.error(`[Indexer] Found ${missingCallData.length} files missing call graph data, re-indexing...`);
-          // Add these files to filesToProcess so they get re-read and re-indexed
-          // We need to filter them to ensure they still exist on disk
-          for (const file of missingCallData) {
-            filesToProcess.push(file);
+          const BATCH_SIZE = 100;
+          for (let i = 0; i < missingCallData.length; i += BATCH_SIZE) {
+            const batch = missingCallData.slice(i, i + BATCH_SIZE);
+            const results = await Promise.all(
+              batch.map(async (file) => {
+                try {
+                  const stats = await fs.stat(file);
+                  if (stats.isDirectory()) return null;
+                  if (stats.size > this.config.maxFileSize) return null;
+                  const content = await fs.readFile(file, "utf-8");
+                  const hash = hashContent(content);
+                  return { file, content, hash };
+                } catch {
+                  return null;
+                }
+              })
+            );
+
+            for (const result of results) {
+              if (!result) continue;
+              if (filesToProcessSet.has(result.file)) continue;
+              filesToProcess.push(result);
+              filesToProcessSet.add(result.file);
+            }
           }
         }
       }

package/lib/cache.js

@@ -6,6 +6,7 @@ const CACHE_META_FILE = "meta.json";
 const ANN_META_VERSION = 1;
 const ANN_INDEX_FILE = "ann-index.bin";
 const ANN_META_FILE = "ann-meta.json";
+const CALL_GRAPH_FILE = "call-graph.json";
 
 let hnswlibPromise = null;
 let hnswlibLoadError = null;
@@ -166,7 +167,7 @@ export class EmbeddingsCache {
       }
 
       // Load call-graph data if it exists
-      const callGraphFile = path.join(this.config.cacheDirectory, "call-graph.json");
+      const callGraphFile = path.join(this.config.cacheDirectory, CALL_GRAPH_FILE);
       try {
         const callGraphData = await fs.readFile(callGraphFile, "utf8");
         const parsed = JSON.parse(callGraphData);
@@ -203,10 +204,12 @@ export class EmbeddingsCache {
         fs.writeFile(metaFile, JSON.stringify(this.cacheMeta, null, 2))
       ]);
 
-      // Save call-graph data
+      // Save call-graph data (or remove stale cache if empty)
+      const callGraphFile = path.join(this.config.cacheDirectory, CALL_GRAPH_FILE);
       if (this.fileCallData.size > 0) {
-        const callGraphFile = path.join(this.config.cacheDirectory, "call-graph.json");
         await fs.writeFile(callGraphFile, JSON.stringify(Object.fromEntries(this.fileCallData), null, 2));
+      } else {
+        await fs.rm(callGraphFile, { force: true });
       }
     } catch (error) {
       console.error("[Cache] Failed to save cache:", error.message);
@@ -440,9 +443,7 @@ export class EmbeddingsCache {
       this.vectorStore = [];
       this.fileHashes = new Map();
       this.invalidateAnnIndex();
-      // Clear call-graph data
-      this.fileCallData.clear();
-      this.callGraph = null;
+      await this.clearCallGraphData();
       console.error(`[Cache] Cache cleared successfully: ${this.config.cacheDirectory}`);
     } catch (error) {
       console.error("[Cache] Failed to clear cache:", error.message);
@@ -497,6 +498,46 @@ export class EmbeddingsCache {
 
   // ========== Call Graph Methods ==========
 
+  /**
+   * Clear all call-graph data (optionally remove persisted cache file)
+   */
+  async clearCallGraphData({ removeFile = false } = {}) {
+    this.fileCallData.clear();
+    this.callGraph = null;
+
+    if (removeFile && this.config.enableCache) {
+      const callGraphFile = path.join(this.config.cacheDirectory, CALL_GRAPH_FILE);
+      try {
+        await fs.rm(callGraphFile, { force: true });
+      } catch (error) {
+        if (this.config.verbose) {
+          console.error(`[Cache] Failed to remove call-graph cache: ${error.message}`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Remove call-graph entries for files no longer in the codebase
+   */
+  pruneCallGraphData(validFiles) {
+    if (!validFiles || this.fileCallData.size === 0) return 0;
+
+    let pruned = 0;
+    for (const file of Array.from(this.fileCallData.keys())) {
+      if (!validFiles.has(file)) {
+        this.fileCallData.delete(file);
+        pruned++;
+      }
+    }
+
+    if (pruned > 0) {
+      this.callGraph = null;
+    }
+
+    return pruned;
+  }
+
   /**
    * Store call data for a file
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softerist/heuristic-mcp",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "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",