@softerist/heuristic-mcp 2.1.0 → 2.1.2

package/README.md

@@ -13,15 +13,78 @@ AI coding assistants work better when they can find relevant code quickly. Tradi
 
 This MCP server solves that by indexing your codebase with AI embeddings. Your AI assistant can search by meaning instead of exact keywords, finding relevant code even when the terminology differs.
 
-![Example](example.png)
+## Example: Semantic Search in Action
 
-## Why Use This
+**User Query:** "How vector cache working?"
 
-**Better Code Understanding**
+### MCP Tool Call
 
-- Search finds code by concept, not just matching words
-- Works with typos and variations in terminology
-- Natural language queries like "where do we validate user input?"
+```json
+{
+  "maxResults": 5,
+  "query": "vector store embeddings cache save load"
+}
+```
+
+### Output
+
+**Result 1 (Relevance: 72.5%)**
+
+**File:** `lib/cache.js` **Lines:** 42-59
+
+```javascript
+}
+
+    const filtered = rawVectorStore.length - this.vectorStore.length;
+    if (filtered > 0) {
+        console.error(`[Cache] Filtered ${filtered} outdated cache entries`);
+    }
+    console.error(`[Cache] Loaded ${this.vectorStore.length} cached embeddings`);
+```
+
+Here's how the **vector cache** works:
+
+### Overview
+
+The cache system (`lib/cache.js`) stores two things:
+
+1. **Vector embeddings** - AI-generated vectors for each code chunk
+2. **File hashes** - MD5 hashes to detect file changes
+
+## Why Heuristic MCP is Useful
+
+Yes, absolutely. The **Heuristic MCP** is highly effective because it bridges the gap between "having access to files" and "understanding the codebase." Here is why it is useful:
+
+### 1. It Solved the "Needle in a Haystack" Problem
+
+To answer your technical questions, I didn't have to manually browse 15 files or run generic `grep` commands.
+
+- **Without MCP:** I would have listed directories, guessed `lib/utils.js` might be relevant, read the whole file, then checked `index.js`, etc.
+- **With MCP:** I asked *"how does chunking work"* and it instantly returned lines 91-108 of `lib/utils.js`. It acted like a senior engineer pointing me to the exact lines of code.
+
+### 2. It Finds "Concepts," Not Just Words
+
+Standard tools like `grep` only find exact matches.
+
+- If I searched for "authentication" using `grep`, I might miss a function named `verifyUserCredentials`.
+- The **Heuristic MCP** links these concepts. In the test script I analyzed earlier, `authentication` correctly matched with `credentials` because of the vector similarity.
+
+### 3. It Finds "Similar Code"
+
+AI agents have a limited memory (context window).
+
+- Instead of reading **every file** to understand the project (which wastes thousands of tokens), the MCP lets me retrieve **only the 5-10 relevant snippets**. This leaves more room for complex reasoning and generating code.
+
+### 4. It Is Fast & Private
+
+Since it runs the **Local LLM** (Xenova) directly on your machine:
+
+- **Latency is near-zero** (<50ms).
+- **Privacy is 100%**: Your source code never leaves your laptop to be indexed by an external cloud service.
+
+### Verdict
+
+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**
 
@@ -148,7 +211,7 @@ Returns: Relevant validation code with file paths and line numbers
 **find_similar_code** - Find duplicates or patterns
 
 ```
-Input: A snippet of code or a file path
+Input: A code snippet (paste the code directly)
 Returns: Other code in the project that looks or functions similarly
 ```
 
@@ -178,8 +241,6 @@ When you search, your query is converted to the same vector format. We use a **h
 - **Exact Keyword Matching** (BM25-inspired boost)
 - **Recency Boosting** (favoring files you're actively working on)
 
-![How It Works](how-its-works.png)
-
 ## Examples
 
 **Natural language search:**

package/features/index-codebase.js

@@ -547,17 +547,44 @@ export class CodebaseIndexer {
 
     if (filesToProcess.length === 0) {
       console.error("[Indexer] All files unchanged, nothing to index");
-      this.sendProgress(100, 100, "All files up to date");
-      await this.cache.save();
-      const vectorStore = this.cache.getVectorStore();
-      return {
-        skipped: false,
-        filesProcessed: 0,
-        chunksCreated: 0,
-        totalFiles: new Set(vectorStore.map(v => v.file)).size,
-        totalChunks: vectorStore.length,
-        message: "All files up to date"
-      };
+
+      // If we have no call graph data but we have cached files, we should try to rebuild it
+      if (this.config.callGraphEnabled && this.cache.getVectorStore().length > 0) {
+        // Check for files that are in cache but missing from call graph data
+        const cachedFiles = new Set(this.cache.getVectorStore().map(c => c.file));
+        const callDataFiles = new Set(this.cache.fileCallData.keys());
+
+        const missingCallData = [];
+        for (const file of cachedFiles) {
+          if (!callDataFiles.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);
+          }
+        }
+      }
+
+      // If still empty after checking for missing call data, then we are truly done
+      if (filesToProcess.length === 0) {
+        this.sendProgress(100, 100, "All files up to date");
+        await this.cache.save();
+        const vectorStore = this.cache.getVectorStore();
+        return {
+          skipped: false,
+          filesProcessed: 0,
+          chunksCreated: 0,
+          totalFiles: new Set(vectorStore.map(v => v.file)).size,
+          totalChunks: vectorStore.length,
+          message: "All files up to date"
+        };
+      }
     }
 
     // Send progress: filtering complete

package/lib/cache.js

@@ -164,6 +164,19 @@ export class EmbeddingsCache {
         this.annIndex = null;
         this.annMeta = null;
       }
+
+      // Load call-graph data if it exists
+      const callGraphFile = path.join(this.config.cacheDirectory, "call-graph.json");
+      try {
+        const callGraphData = await fs.readFile(callGraphFile, "utf8");
+        const parsed = JSON.parse(callGraphData);
+        this.fileCallData = new Map(Object.entries(parsed));
+        if (this.config.verbose) {
+          console.error(`[Cache] Loaded call-graph data for ${this.fileCallData.size} files`);
+        }
+      } catch {
+        // Call-graph file doesn't exist yet, that's OK
+      }
     } catch (error) {
       console.error("[Cache] Failed to load cache:", error.message);
     }
@@ -189,6 +202,12 @@ export class EmbeddingsCache {
         fs.writeFile(hashFile, JSON.stringify(Object.fromEntries(this.fileHashes), null, 2)),
         fs.writeFile(metaFile, JSON.stringify(this.cacheMeta, null, 2))
       ]);
+
+      // Save call-graph data
+      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));
+      }
     } catch (error) {
       console.error("[Cache] Failed to save cache:", error.message);
     } finally {
@@ -220,6 +239,8 @@ export class EmbeddingsCache {
   removeFileFromStore(file) {
     this.vectorStore = this.vectorStore.filter(chunk => chunk.file !== file);
     this.invalidateAnnIndex();
+    // Also clear call-graph data for this file
+    this.removeFileCallData(file);
   }
 
 
@@ -419,6 +440,9 @@ export class EmbeddingsCache {
       this.vectorStore = [];
       this.fileHashes = new Map();
       this.invalidateAnnIndex();
+      // Clear call-graph data
+      this.fileCallData.clear();
+      this.callGraph = null;
       console.error(`[Cache] Cache cleared successfully: ${this.config.cacheDirectory}`);
     } catch (error) {
       console.error("[Cache] Failed to clear cache:", error.message);

package/lib/call-graph.js

@@ -48,20 +48,20 @@ const DEFINITION_PATTERNS = {
 // Pattern for function calls (language-agnostic, catches most cases)
 const CALL_PATTERN = /\b([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/g;
 
-// Common built-ins to exclude from call detection
+// Common built-ins to exclude from call detection (all lowercase for case-insensitive matching)
 const BUILTIN_EXCLUSIONS = new Set([
   // JavaScript
   "if", "for", "while", "switch", "catch", "function", "async", "await",
   "return", "throw", "new", "typeof", "instanceof", "delete", "void",
   "console", "require", "import", "export", "super", "this",
   // Common functions that aren't meaningful for call graphs
-  "parseInt", "parseFloat", "String", "Number", "Boolean", "Array", "Object",
-  "Map", "Set", "Promise", "Error", "JSON", "Math", "Date", "RegExp",
+  "parseint", "parsefloat", "string", "number", "boolean", "array", "object",
+  "map", "set", "promise", "error", "json", "math", "date", "regexp",
   // Python
   "def", "class", "print", "len", "range", "str", "int", "float", "list", "dict",
-  "tuple", "set", "bool", "type", "isinstance", "hasattr", "getattr", "setattr",
+  "tuple", "bool", "type", "isinstance", "hasattr", "getattr", "setattr",
   // Go
-  "func", "make", "append", "len", "cap", "new", "panic", "recover",
+  "func", "make", "append", "cap", "panic", "recover",
   // Control flow that looks like function calls
   "else", "try", "finally", "with", "assert", "raise", "yield"
 ]);
@@ -103,7 +103,7 @@ export function extractDefinitions(content, file) {
     let match;
     while ((match = pattern.exec(content)) !== null) {
       const name = match[1];
-      if (name && name.length > 1 && !BUILTIN_EXCLUSIONS.has(name)) {
+      if (name && name.length > 1 && !BUILTIN_EXCLUSIONS.has(name.toLowerCase())) {
         definitions.add(name);
       }
     }

package/lib/config.js

@@ -208,6 +208,24 @@ export async function loadConfig(workspaceDir = null) {
     }
   }
 
+  if (process.env.SMART_CODING_RECENCY_BOOST !== undefined) {
+    const value = parseFloat(process.env.SMART_CODING_RECENCY_BOOST);
+    if (!isNaN(value) && value >= 0 && value <= 1) {
+      config.recencyBoost = value;
+    } else {
+      console.error(`[Config] Invalid SMART_CODING_RECENCY_BOOST: ${process.env.SMART_CODING_RECENCY_BOOST}, using default`);
+    }
+  }
+
+  if (process.env.SMART_CODING_RECENCY_DECAY_DAYS !== undefined) {
+    const value = parseInt(process.env.SMART_CODING_RECENCY_DECAY_DAYS, 10);
+    if (!isNaN(value) && value > 0 && value <= 365) {
+      config.recencyDecayDays = value;
+    } else {
+      console.error(`[Config] Invalid SMART_CODING_RECENCY_DECAY_DAYS: ${process.env.SMART_CODING_RECENCY_DECAY_DAYS}, using default`);
+    }
+  }
+
   if (process.env.SMART_CODING_WATCH_FILES !== undefined) {
     const value = process.env.SMART_CODING_WATCH_FILES;
     if (value === 'true' || value === 'false') {

package/package.json

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