@softerist/heuristic-mcp 2.0.0 → 2.1.0

package/ARCHITECTURE.md

@@ -1,11 +1,11 @@
-# Project Structure
+# Architecture Overview
 
-This document outlines the modular architecture of Smart Coding MCP.
+This document outlines the modular architecture of Heuristic MCP.
 
 ## Directory Structure
 
 ```
-smart-coding-mcp/
+heuristic-mcp/
 ├── index.js                    # Main entry point, MCP server setup
 ├── package.json                # Package configuration
 ├── config.json                 # User configuration
@@ -49,6 +49,7 @@ smart-coding-mcp/
 - Manages persistence of embedding vectors
 - File hash tracking for change detection
 - Load/save operations for disk cache
+- Optional ANN (HNSW) index build/load/save for fast search
 
 ### lib/utils.js
 
@@ -173,6 +174,8 @@ smartChunk() - split into chunks
 embedder - generate vectors
     ↓
 EmbeddingsCache - store in memory + disk
+    ↓
+ANN index (optional) - build/load from cache
 ```
 
 ### Search Flow
@@ -182,7 +185,9 @@ User query
     ↓
 embedder - query to vector
     ↓
-cosineSimilarity() - score all chunks
+ANN candidate search (optional)
+    ↓
+cosineSimilarity() - score candidates
     ↓
 exact match boost - adjust scores
     ↓

package/CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to Smart Coding MCP
+# Contributing to Heuristic MCP
 
 Thank you for your interest in contributing! This document provides guidelines for contributing to the project.
 
@@ -14,8 +14,8 @@ Thank you for your interest in contributing! This document provides guidelines f
 
 ```bash
 # Fork and clone the repository
-git clone https://github.com/omar-haris/smart-coding-mcp.git
-cd smart-coding-mcp
+git clone https://github.com/softerist/heuristic-mcp.git
+cd heuristic-mcp
 
 # Install dependencies
 npm install
@@ -233,7 +233,7 @@ git push origin feature/your-feature-name
 ```bash
 # Test with a sample project
 cd /path/to/test/project
-node /path/to/smart-coding-mcp/index.js
+node /path/to/heuristic-mcp/index.js
 
 # In another terminal, send MCP requests
 ```
@@ -297,7 +297,7 @@ Looking for ideas? Consider implementing:
 
 - **Issues**: Use GitHub Issues for bugs and feature requests
 - **Discussions**: Use GitHub Discussions for questions
-- **Email**: Contact Omar Haris via LinkedIn
+- **Email**: Contact Softerist via website
 
 ## License
 
@@ -305,4 +305,4 @@ By contributing, you agree that your contributions will be licensed under the MI
 
 ---
 
-Thank you for contributing to Smart Coding MCP!
+Thank you for contributing to Heuristic MCP!

package/README.md

@@ -1,7 +1,7 @@
-# Smart Coding MCP
+# Heuristic MCP
 
-[![npm version](https://img.shields.io/npm/v/smart-coding-mcp.svg)](https://www.npmjs.com/package/smart-coding-mcp)
-[![npm downloads](https://img.shields.io/npm/dm/smart-coding-mcp.svg)](https://www.npmjs.com/package/smart-coding-mcp)
+[![npm version](https://img.shields.io/npm/v/@softerist/heuristic-mcp.svg)](https://www.npmjs.com/package/@softerist/heuristic-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/@softerist/heuristic-mcp.svg)](https://www.npmjs.com/package/@softerist/heuristic-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org/)
 
@@ -28,6 +28,7 @@ This MCP server solves that by indexing your codebase with AI embeddings. Your A
 - 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**
 
@@ -40,13 +41,13 @@ This MCP server solves that by indexing your codebase with AI embeddings. Your A
 Install globally via npm:
 
 ```bash
-npm install -g smart-coding-mcp
+npm install -g @softerist/heuristic-mcp
 ```
 
 To update to the latest version:
 
 ```bash
-npm update -g smart-coding-mcp
+npm update -g @softerist/heuristic-mcp
 ```
 
 ## Configuration
@@ -68,8 +69,8 @@ Add the server configuration to the `mcpServers` object in your config file:
 ```json
 {
   "mcpServers": {
-    "smart-coding-mcp": {
-      "command": "smart-coding-mcp",
+    "heuristic-mcp": {
+      "command": "heuristic-mcp",
       "args": ["--workspace", "/absolute/path/to/your/project"]
     }
   }
@@ -81,12 +82,12 @@ Add the server configuration to the `mcpServers` object in your config file:
 ```json
 {
   "mcpServers": {
-    "smart-coding-mcp-project-a": {
-      "command": "smart-coding-mcp",
+    "heuristic-mcp-project-a": {
+      "command": "heuristic-mcp",
       "args": ["--workspace", "/path/to/project-a"]
     },
-    "smart-coding-mcp-project-b": {
-      "command": "smart-coding-mcp",
+    "heuristic-mcp-project-b": {
+      "command": "heuristic-mcp",
       "args": ["--workspace", "/path/to/project-b"]
     }
   }
@@ -108,21 +109,25 @@ Override configuration settings via environment variables in your MCP config:
 | `SMART_CODING_WATCH_FILES`       | boolean | `false`                   | Enable file watching for auto-reindex |
 | `SMART_CODING_SEMANTIC_WEIGHT`   | number  | `0.7`                     | Weight for semantic similarity (0-1)  |
 | `SMART_CODING_EXACT_MATCH_BOOST` | number  | `1.5`                     | Boost for exact text matches          |
+| `SMART_CODING_RECENCY_BOOST`     | number  | `0.1`                     | Boost for recently modified files     |
+| `SMART_CODING_RECENCY_DECAY_DAYS`| number  | `30`                      | Days until recency boost fades to 0   |
 | `SMART_CODING_EMBEDDING_MODEL`   | string  | `Xenova/all-MiniLM-L6-v2` | AI embedding model to use             |
 | `SMART_CODING_WORKER_THREADS`    | string  | `auto`                    | Worker threads (`auto` or 1-32)       |
+| `SMART_CODING_ANN_ENABLED`       | boolean | `true`                    | Enable ANN search (HNSW)              |
+
+**ANN note**: HNSW support uses optional `hnswlib-node`. If it isn't installed, the server falls back to exact (linear) search automatically.
 
 **Example with environment variables:**
 
 ```json
 {
   "mcpServers": {
-    "smart-coding-mcp": {
-      "command": "smart-coding-mcp",
+    "heuristic-mcp": {
+      "command": "heuristic-mcp",
       "args": ["--workspace", "/path/to/project"],
       "env": {
         "SMART_CODING_VERBOSE": "true",
-        "SMART_CODING_BATCH_SIZE": "200",
-        "SMART_CODING_MAX_FILE_SIZE": "2097152"
+        "SMART_CODING_RECENCY_BOOST": "0.2"
       }
     }
   }
@@ -140,6 +145,13 @@ Query: "Where do we validate user input?"
 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
+Returns: Other code in the project that looks or functions similarly
+```
+
 **index_codebase** - Manually trigger reindexing
 
 ```
@@ -156,12 +168,15 @@ Useful when cache becomes corrupted or outdated
 
 The server indexes your code in four steps:
 
-1. **Discovery**: Scans your project for source files
+1. **Discovery**: Scans your project for source files (smartly ignoring build/vendor folders)
 2. **Chunking**: Breaks code into meaningful pieces (respecting function boundaries)
 3. **Embedding**: Converts each chunk to a vector using a local AI model
 4. **Storage**: Saves embeddings to `.smart-coding-cache/` for fast startup
 
-When you search, your query is converted to the same vector format and compared against all code chunks using cosine similarity. The most relevant matches are returned.
+When you search, your query is converted to the same vector format. We use a **hybrid ranking algorithm** that combines:
+- **Semantic Similarity** (cosine similarity of vectors)
+- **Exact Keyword Matching** (BM25-inspired boost)
+- **Recency Boosting** (favoring files you're actively working on)
 
 ![How It Works](how-its-works.png)
 
@@ -224,11 +239,15 @@ This project builds on research from Cursor showing that semantic search improve
 
 See: https://cursor.com/blog/semsearch
 
+## Acknowledgements
+
+This project is a fork of [smart-coding-mcp](https://github.com/omar-haris/smart-coding-mcp) by [Omar Haris](https://www.linkedin.com/in/omarharis/). We thank him for the original implementation.
+
 ## License
 
 MIT License
 
-Copyright (c) 2025 Omar Haris
+Copyright (c) 2025 Softerist
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/config.json

@@ -62,5 +62,15 @@
   "embeddingModel": "Xenova/all-MiniLM-L6-v2",
   "semanticWeight": 0.7,
   "exactMatchBoost": 1.5,
-  "workerThreads": "auto"
-}
+  "workerThreads": "auto",
+  "annEnabled": true,
+  "annMinChunks": 5000,
+  "annMinCandidates": 50,
+  "annMaxCandidates": 200,
+  "annCandidateMultiplier": 20,
+  "annEfConstruction": 200,
+  "annEfSearch": 64,
+  "annM": 16,
+  "annIndexCache": true,
+  "annMetric": "cosine"
+}

package/features/ann-config.js

@@ -0,0 +1,120 @@
+/**
+ * ANN Config Tool - Runtime tuning of ANN search parameters
+ *
+ * Allows adjusting efSearch on the fly for speed/accuracy tradeoff,
+ * and querying current ANN index statistics.
+ */
+
+export class AnnConfigTool {
+  constructor(cache, config) {
+    this.cache = cache;
+    this.config = config;
+  }
+
+  /**
+   * Adjust efSearch and optionally trigger index rebuild
+   */
+  async execute(args) {
+    const action = args.action || "stats";
+
+    if (action === "stats") {
+      return this.cache.getAnnStats();
+    }
+
+    if (action === "set_ef_search") {
+      const efSearch = args.efSearch;
+      if (efSearch === undefined) {
+        return { success: false, error: "efSearch parameter is required for set_ef_search action" };
+      }
+      return this.cache.setEfSearch(efSearch);
+    }
+
+    if (action === "rebuild") {
+      // Force invalidate and rebuild the ANN index
+      this.cache.invalidateAnnIndex();
+      const index = await this.cache.ensureAnnIndex();
+      return {
+        success: index !== null,
+        message: index ? "ANN index rebuilt successfully" : "ANN index rebuild failed or not available"
+      };
+    }
+
+    return { success: false, error: `Unknown action: ${action}. Valid actions: stats, set_ef_search, rebuild` };
+  }
+
+  formatResults(result) {
+    if (result.success === false) {
+      return `Error: ${result.error}`;
+    }
+
+    if (result.enabled !== undefined) {
+      // Stats response
+      let output = "## ANN Index Statistics\n\n";
+      output += `- **Enabled**: ${result.enabled}\n`;
+      output += `- **Index Loaded**: ${result.indexLoaded}\n`;
+      output += `- **Dirty (needs rebuild)**: ${result.dirty}\n`;
+      output += `- **Vector Count**: ${result.vectorCount}\n`;
+      output += `- **Min Chunks for ANN**: ${result.minChunksForAnn}\n`;
+
+      if (result.config) {
+        output += "\n### Current Config\n\n";
+        output += `- **Metric**: ${result.config.metric}\n`;
+        output += `- **Dimensions**: ${result.config.dim}\n`;
+        output += `- **Indexed Vectors**: ${result.config.count}\n`;
+        output += `- **M (connectivity)**: ${result.config.m}\n`;
+        output += `- **efConstruction**: ${result.config.efConstruction}\n`;
+        output += `- **efSearch**: ${result.config.efSearch}\n`;
+      } else {
+        output += "\n*No active ANN index.*\n";
+      }
+
+      return output;
+    }
+
+    // Other responses (set_ef_search, rebuild)
+    return JSON.stringify(result, null, 2);
+  }
+}
+
+// MCP Tool definition
+export function getToolDefinition() {
+  return {
+    name: "d_ann_config",
+    description: "Configure and monitor the ANN (Approximate Nearest Neighbor) search index. Actions: 'stats' (view current config), 'set_ef_search' (tune search accuracy/speed), 'rebuild' (force index rebuild).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["stats", "set_ef_search", "rebuild"],
+          description: "Action to perform. 'stats' shows current config, 'set_ef_search' changes the search parameter, 'rebuild' forces index rebuild.",
+          default: "stats"
+        },
+        efSearch: {
+          type: "number",
+          description: "New efSearch value (only for set_ef_search action). Higher = more accurate but slower. Typical range: 16-512.",
+          minimum: 1,
+          maximum: 1000
+        }
+      }
+    },
+    annotations: {
+      title: "ANN Index Configuration",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  };
+}
+
+// Tool handler
+export async function handleToolCall(request, annConfigTool) {
+  const args = request.params.arguments || {};
+  const result = await annConfigTool.execute(args);
+  const formattedText = annConfigTool.formatResults(result);
+
+  return {
+    content: [{ type: "text", text: formattedText }]
+  };
+}

package/features/find-similar-code.js

@@ -12,6 +12,15 @@ export class FindSimilarCode {
     this.config = config;
   }
 
+  getAnnCandidateCount(maxResults, totalChunks) {
+    const minCandidates = this.config.annMinCandidates ?? 0;
+    const maxCandidates = this.config.annMaxCandidates ?? totalChunks;
+    const multiplier = this.config.annCandidateMultiplier ?? 1;
+    const desired = Math.max(minCandidates, Math.ceil(maxResults * multiplier));
+    const capped = Math.min(maxCandidates, desired);
+    return Math.min(totalChunks, Math.max(maxResults, capped));
+  }
+
   async execute({ code, maxResults = 5, minSimilarity = 0.3 }) {
     const vectorStore = this.cache.getVectorStore();
 
@@ -25,18 +34,47 @@ export class FindSimilarCode {
     // Generate embedding for the input code
     const codeEmbed = await this.embedder(code, { pooling: "mean", normalize: true });
     const codeVector = Array.from(codeEmbed.data);
+    const codeVectorTyped = codeEmbed.data;
+
+    let candidates = vectorStore;
+    let usedAnn = false;
+    if (this.config.annEnabled) {
+      const candidateCount = this.getAnnCandidateCount(maxResults, vectorStore.length);
+      const annLabels = await this.cache.queryAnn(codeVectorTyped, candidateCount);
+      if (annLabels && annLabels.length >= maxResults) {
+        usedAnn = true;
+        const seen = new Set();
+        candidates = annLabels
+          .map((index) => {
+            if (seen.has(index)) return null;
+            seen.add(index);
+            return vectorStore[index];
+          })
+          .filter(Boolean);
+      }
+    }
 
     // Score all chunks by similarity
-    const scoredChunks = vectorStore.map(chunk => {
+    let scoredChunks = candidates.map(chunk => {
       const similarity = dotSimilarity(codeVector, chunk.vector);
       return { ...chunk, similarity };
     });
 
     // Filter by minimum similarity and sort
-    const filteredResults = scoredChunks
+    let filteredResults = scoredChunks
       .filter(chunk => chunk.similarity >= minSimilarity)
       .sort((a, b) => b.similarity - a.similarity);
 
+    if (usedAnn && filteredResults.length < maxResults) {
+      scoredChunks = vectorStore.map(chunk => {
+        const similarity = dotSimilarity(codeVector, chunk.vector);
+        return { ...chunk, similarity };
+      });
+      filteredResults = scoredChunks
+        .filter(chunk => chunk.similarity >= minSimilarity)
+        .sort((a, b) => b.similarity - a.similarity);
+    }
+
     // Deduplicate: if input code is from indexed file, skip exact matches
     const normalizedInput = code.trim().replace(/\s+/g, ' ');
     const results = filteredResults

package/features/hybrid-search.js

@@ -1,6 +1,7 @@
 import path from "path";
 import fs from "fs/promises";
 import { dotSimilarity } from "../lib/utils.js";
+import { extractSymbolsFromContent } from "../lib/call-graph.js";
 
 export class HybridSearch {
   constructor(embedder, cache, config) {
@@ -10,6 +11,15 @@ export class HybridSearch {
     this.fileModTimes = new Map(); // Cache for file modification times
   }
 
+  getAnnCandidateCount(maxResults, totalChunks) {
+    const minCandidates = this.config.annMinCandidates ?? 0;
+    const maxCandidates = this.config.annMaxCandidates ?? totalChunks;
+    const multiplier = this.config.annCandidateMultiplier ?? 1;
+    const desired = Math.max(minCandidates, Math.ceil(maxResults * multiplier));
+    const capped = Math.min(maxCandidates, desired);
+    return Math.min(totalChunks, Math.max(maxResults, capped));
+  }
+
   async populateFileModTimes(files) {
     const uniqueFiles = new Set(files);
     const missing = [];
@@ -56,13 +66,37 @@ export class HybridSearch {
     // Generate query embedding
     const queryEmbed = await this.embedder(query, { pooling: "mean", normalize: true });
     const queryVector = Array.from(queryEmbed.data);
+    const queryVectorTyped = queryEmbed.data;
+
+    let candidates = vectorStore;
+    let usedAnn = false;
+    if (this.config.annEnabled) {
+      const candidateCount = this.getAnnCandidateCount(maxResults, vectorStore.length);
+      const annLabels = await this.cache.queryAnn(queryVectorTyped, candidateCount);
+      if (annLabels && annLabels.length >= maxResults) {
+        usedAnn = true;
+        const seen = new Set();
+        candidates = annLabels
+          .map((index) => {
+            if (seen.has(index)) return null;
+            seen.add(index);
+            return vectorStore[index];
+          })
+          .filter(Boolean);
+      }
+    }
+
+    if (usedAnn && candidates.length < maxResults) {
+      candidates = vectorStore;
+      usedAnn = false;
+    }
 
     if (this.config.recencyBoost > 0) {
-      await this.populateFileModTimes(vectorStore.map(chunk => chunk.file));
+      await this.populateFileModTimes(candidates.map(chunk => chunk.file));
     }
 
     // Score all chunks (synchronous map now, much faster)
-    const scoredChunks = vectorStore.map(chunk => {
+    const scoredChunks = candidates.map(chunk => {
       // Semantic similarity (vectors are normalized)
       let score = dotSimilarity(queryVector, chunk.vector) * this.config.semanticWeight;
 
@@ -97,10 +131,40 @@ export class HybridSearch {
       return { ...chunk, score };
     });
 
+    // Sort by initial score
+    scoredChunks.sort((a, b) => b.score - a.score);
+
+    // Apply call graph proximity boost if enabled
+    if (this.config.callGraphEnabled && this.config.callGraphBoost > 0) {
+      // Extract symbols from top initial results
+      const topN = Math.min(5, scoredChunks.length);
+      const symbolsFromTop = new Set();
+      for (let i = 0; i < topN; i++) {
+        const symbols = extractSymbolsFromContent(scoredChunks[i].content);
+        for (const sym of symbols) {
+          symbolsFromTop.add(sym);
+        }
+      }
+
+      if (symbolsFromTop.size > 0) {
+        // Get related files from call graph
+        const relatedFiles = await this.cache.getRelatedFiles(Array.from(symbolsFromTop));
+
+        // Apply boost to chunks from related files
+        for (const chunk of scoredChunks) {
+          const proximity = relatedFiles.get(chunk.file);
+          if (proximity) {
+            chunk.score += proximity * this.config.callGraphBoost;
+          }
+        }
+
+        // Re-sort after applying call graph boost
+        scoredChunks.sort((a, b) => b.score - a.score);
+      }
+    }
+
     // Get top results
-    const results = scoredChunks
-      .sort((a, b) => b.score - a.score)
-      .slice(0, maxResults);
+    const results = scoredChunks.slice(0, maxResults);
 
     return { results, message: null };
   }

package/features/index-codebase.js

@@ -6,6 +6,7 @@ import os from "os";
 import { Worker } from "worker_threads";
 import { fileURLToPath } from "url";
 import { smartChunk, hashContent } from "../lib/utils.js";
+import { extractCallData } from "../lib/call-graph.js";
 
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -585,18 +586,30 @@ export class CodebaseIndexer {
     // Step 5: Process files in adaptive batches
     for (let i = 0; i < filesToProcess.length; i += adaptiveBatchSize) {
       const batch = filesToProcess.slice(i, i + adaptiveBatchSize);
-      
+
       // Generate all chunks for this batch
       const allChunks = [];
       const fileStats = new Map();
-      
+
       for (const { file, content, hash } of batch) {
         // Remove old chunks for this file
         this.cache.removeFileFromStore(file);
-        
+
+        // Extract call graph data if enabled
+        if (this.config.callGraphEnabled) {
+          try {
+            const callData = extractCallData(content, file);
+            this.cache.setFileCallData(file, callData);
+          } catch (err) {
+            if (this.config.verbose) {
+              console.error(`[Indexer] Call graph extraction failed for ${path.basename(file)}: ${err.message}`);
+            }
+          }
+        }
+
         const chunks = smartChunk(content, file, this.config);
         fileStats.set(file, { hash, totalChunks: 0, successChunks: 0 });
-        
+
         for (const chunk of chunks) {
           allChunks.push({
             file,
@@ -673,6 +686,17 @@ export class CodebaseIndexer {
 
     await this.cache.save();
 
+    // Rebuild call graph in background
+    if (this.config.callGraphEnabled) {
+      this.cache.rebuildCallGraph();
+    }
+
+    void this.cache.ensureAnnIndex().catch((error) => {
+      if (this.config.verbose) {
+        console.error(`[ANN] Background ANN build failed: ${error.message}`);
+      }
+    });
+
     const vectorStore = this.cache.getVectorStore();
     return {
       skipped: false,

package/index.js

@@ -19,6 +19,7 @@ import * as IndexCodebaseFeature from "./features/index-codebase.js";
 import * as HybridSearchFeature from "./features/hybrid-search.js";
 import * as ClearCacheFeature from "./features/clear-cache.js";
 import * as FindSimilarCodeFeature from "./features/find-similar-code.js";
+import * as AnnConfigFeature from "./features/ann-config.js";
 
 // Parse workspace from command line arguments
 const args = process.argv.slice(2);
@@ -76,6 +77,11 @@ const features = [
     module: FindSimilarCodeFeature,
     instance: null,
     handler: FindSimilarCodeFeature.handleToolCall
+  },
+  {
+    module: AnnConfigFeature,
+    instance: null,
+    handler: AnnConfigFeature.handleToolCall
   }
 ];
 
@@ -105,12 +111,14 @@ async function initialize() {
   hybridSearch = new HybridSearch(embedder, cache, config);
   const cacheClearer = new ClearCacheFeature.CacheClearer(embedder, cache, config, indexer);
   const findSimilarCode = new FindSimilarCodeFeature.FindSimilarCode(embedder, cache, config);
+  const annConfig = new AnnConfigFeature.AnnConfigTool(cache, config);
 
   // Store feature instances (matches features array order)
   features[0].instance = hybridSearch;
   features[1].instance = indexer;
   features[2].instance = cacheClearer;
   features[3].instance = findSimilarCode;
+  features[4].instance = annConfig;
 
   // Attach hybridSearch to server for cross-feature access (e.g. cache invalidation)
   server.hybridSearch = hybridSearch;
@@ -177,7 +185,7 @@ async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
 
-  console.error("[Server] Smart Coding MCP server ready!");
+  console.error("[Server] Heuristic MCP server ready!");
 }
 
 // Graceful shutdown