@softerist/heuristic-mcp 2.1.1 → 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**
 
@@ -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/package.json

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