@softerist/heuristic-mcp 3.0.0 → 3.0.2

package/CONTRIBUTING.md

@@ -1,227 +0,0 @@
-# Contributing to Heuristic MCP
-
-Thank you for your interest in contributing. This document provides guidelines for contributing to the project.
-
-## Getting Started
-
-### Prerequisites
-
-- Node.js 18 or higher
-- npm or yarn
-- Git
-
-### Setup Development Environment
-
-```bash
-# Fork and clone the repository
-git clone https://github.com/softerist/heuristic-mcp.git
-cd heuristic-mcp
-
-# Install dependencies
-npm install
-
-# Run in development mode
-npm run dev
-```
-
-## Project Structure
-
-See `ARCHITECTURE.md` for detailed information about the modular architecture.
-
-Key directories:
-
-- `lib/` - Core libraries and utilities
-- `features/` - Pluggable feature modules
-- `scripts/` - Utility scripts
-- `tools/` - Developer-only helpers
-
-## Development Guidelines
-
-### Code Style
-
-- Use ES6+ JavaScript features
-- Follow existing code patterns
-- Use meaningful variable and function names
-- Add comments for complex logic
-- Avoid emojis in code comments and logs unless they are part of user-facing CLI output
-
-### File Organization
-
-```javascript
-// Standard file structure for features:
-
-// 1. Imports
-import { dependency } from 'package';
-
-// 2. Class definition
-export class FeatureName {
-  constructor(embedder, cache, config) {
-    // ...
-  }
-
-  async method() {
-    // ...
-  }
-}
-
-// 3. MCP tool definition
-export function getToolDefinition(config) {
-  return {
-    /* ... */
-  };
-}
-
-// 4. Tool handler
-export async function handleToolCall(request, instance) {
-  // ...
-}
-```
-
-### Error Handling
-
-```javascript
-// Always handle errors gracefully
-try {
-  // operation
-} catch (error) {
-  console.error('[Module] Error description:', error.message);
-  // Continue execution or return default value
-}
-```
-
-### Logging
-
-- Use `console.info()` for normal server lifecycle output (redirected to logs in MCP mode)
-- Use `console.warn()` for non-fatal issues and `console.error()` for errors
-- CLI utilities and install scripts may use `console.info()` for user-friendly output
-
-## Adding New Features
-
-### Step-by-Step Guide
-
-1. **Create Feature File**
-
-Create `features/your-feature.js`:
-
-```javascript
-export class YourFeature {
-  constructor(embedder, cache, config) {
-    this.embedder = embedder;
-    this.cache = cache;
-    this.config = config;
-  }
-
-  async execute(params) {
-    // Implementation
-    return { result: 'data' };
-  }
-}
-
-export function getToolDefinition(config) {
-  return {
-    name: 'your_tool',
-    description: 'Clear description of what the tool does',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        param: {
-          type: 'string',
-          description: 'Parameter description',
-        },
-      },
-      required: ['param'],
-    },
-  };
-}
-
-export async function handleToolCall(request, instance) {
-  const params = request.params.arguments;
-  const result = await instance.execute(params);
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify(result, null, 2),
-      },
-    ],
-  };
-}
-```
-
-2. **Register Feature**
-
-Update `index.js`:
-
-```javascript
-import * as YourFeature from './features/your-feature.js';
-
-// In initialize():
-const yourFeature = new YourFeature.YourFeature(embedder, cache, config);
-
-// Add to features array:
-features.push({
-  module: YourFeature,
-  instance: yourFeature,
-  handler: YourFeature.handleToolCall,
-});
-```
-
-3. **Test Your Feature**
-
-- Test with a sample codebase
-- Verify MCP tool contract
-- Check error handling and output format
-
-4. **Document Your Feature**
-
-- Add to README.md features section
-- Update ARCHITECTURE.md if needed
-
-## Testing
-
-```bash
-npm test
-```
-
-By default, tests use a mock embedder to avoid network/model downloads. To run the real model tests:
-
-```bash
-USE_REAL_EMBEDDER=true npm test
-```
-
-## Pull Request Process
-
-1. **Fork the repository**
-
-2. **Create a feature branch**
-
-```bash
-git checkout -b feature/your-feature-name
-```
-
-3. **Make your changes**
-
-- Follow code style guidelines
-- Add appropriate comments
-- Test thoroughly
-
-4. **Commit your changes**
-
-```bash
-git add .
-git commit -m "Add feature: description"
-```
-
-Follow commit message conventions:
-
-- `Add feature: description` - New features
-- `Fix: description` - Bug fixes
-- `Update: description` - Updates to existing code
-- `Docs: description` - Documentation changes
-
-5. **Push to your fork**
-
-```bash
-git push origin feature/your-feature-name
-```

package/README.md

@@ -98,11 +98,11 @@ Clears the cache for the current working directory (or `--workspace` if provided
 
 ---
 
-## Configuration (`config.json`)
+## Configuration (`config.jsonc`)
 
-Configuration is loaded from your workspace root when the server runs with `--workspace` (this is how IDEs launch it). In server mode, it falls back to the package `config.json` and then your current working directory.
+Configuration is loaded from your workspace root when the server runs with `--workspace` (this is how IDEs launch it). In server mode, it falls back to the package `config.jsonc` (or `config.json`) and then your current working directory.
 
-Example `config.json`:
+Example `config.jsonc`:
 
 ```json
 {
@@ -111,6 +111,9 @@ Example `config.json`:
   "smartIndexing": true,
   "embeddingModel": "jinaai/jina-embeddings-v2-base-code",
   "workerThreads": 0,
+  "embeddingBatchSize": null,
+  "embeddingProcessNumThreads": 8,
+  "enableExplicitGc": false,
   "recencyBoost": 0.1,
   "recencyDecayDays": 30,
   "callGraphEnabled": true,
@@ -128,27 +131,31 @@ Example `config.json`:
 Cache location:
 
 - By default, the cache is stored in a global OS cache directory under `heuristic-mcp/<hash>`.
-- You can override with `cacheDirectory` in `config.json`.
+- You can override with `cacheDirectory` in your config file.
 
 ### Environment Variables
 
 Selected overrides (prefix `SMART_CODING_`):
 
-- `SMART_CODING_VERBOSE=true|false`
-- `SMART_CODING_WORKER_THREADS=auto|0|N`
-- `SMART_CODING_BATCH_SIZE=100`
-- `SMART_CODING_CHUNK_SIZE=25`
-- `SMART_CODING_MAX_RESULTS=5`
-- `SMART_CODING_RECENCY_BOOST=0.1`
-- `SMART_CODING_RECENCY_DECAY_DAYS=30`
-- `SMART_CODING_ANN_ENABLED=true|false`
-- `SMART_CODING_ANN_EF_SEARCH=64`
-- `SMART_CODING_VECTOR_STORE_FORMAT=json|binary`
-- `SMART_CODING_VECTOR_STORE_CONTENT_MODE=external|inline`
-- `SMART_CODING_VECTOR_STORE_LOAD_MODE=memory|disk`
-- `SMART_CODING_CONTENT_CACHE_ENTRIES=256`
-- `SMART_CODING_VECTOR_CACHE_ENTRIES=64`
-- `SMART_CODING_CLEAR_CACHE_AFTER_INDEX=true|false`
+- `SMART_CODING_VERBOSE=true|false` — enable detailed logging.
+- `SMART_CODING_WORKER_THREADS=auto|N` — worker thread count.
+- `SMART_CODING_BATCH_SIZE=100` — files per indexing batch.
+- `SMART_CODING_CHUNK_SIZE=25` — lines per chunk.
+- `SMART_CODING_MAX_RESULTS=5` — max search results.
+- `SMART_CODING_EMBEDDING_BATCH_SIZE=64` — embedding batch size (1–256, overrides auto).
+- `SMART_CODING_EMBEDDING_THREADS=8` — ONNX threads for the embedding child process.
+- `SMART_CODING_RECENCY_BOOST=0.1` — boost for recently edited files.
+- `SMART_CODING_RECENCY_DECAY_DAYS=30` — days until recency boost decays to 0.
+- `SMART_CODING_ANN_ENABLED=true|false` — enable ANN index.
+- `SMART_CODING_ANN_EF_SEARCH=64` — ANN search quality/speed tradeoff.
+- `SMART_CODING_VECTOR_STORE_FORMAT=json|binary` — on-disk vector store format.
+- `SMART_CODING_VECTOR_STORE_CONTENT_MODE=external|inline` — where content is stored for binary format.
+- `SMART_CODING_VECTOR_STORE_LOAD_MODE=memory|disk` — vector loading strategy.
+- `SMART_CODING_CONTENT_CACHE_ENTRIES=256` — LRU entries for decoded content.
+- `SMART_CODING_VECTOR_CACHE_ENTRIES=64` — LRU entries for vectors (disk mode).
+- `SMART_CODING_CLEAR_CACHE_AFTER_INDEX=true|false` — drop in-memory vectors after indexing.
+- `SMART_CODING_EXPLICIT_GC=true|false` — opt-in to explicit GC (requires `--expose-gc`).
+- `SMART_CODING_INCREMENTAL_GC_THRESHOLD_MB=2048` — RSS threshold for running incremental GC after watcher updates (requires explicit GC).
 
 See `lib/config.js` for the full list.
 
@@ -191,6 +198,34 @@ Note: On small repos, disk mode may be slightly slower and show noisy RSS deltas
 1. Run `heuristic-mcp --status` to check config and cache status.
 2. Run `heuristic-mcp --logs` to see startup errors.
 
+**Native ONNX backend unavailable (falls back to WASM)**
+
+If you see log lines like:
+
+```
+Native ONNX backend unavailable: The operating system cannot run %1.
+...onnxruntime_binding.node. Falling back to WASM.
+```
+
+The server will automatically disable workers and force `embeddingProcessPerBatch` to reduce memory spikes, but you
+should fix the native binding to restore stable memory usage:
+
+- Ensure you are running **64-bit Node.js** (`node -p "process.arch"` should be `x64`).
+- Install **Microsoft Visual C++ 2015–2022 Redistributable (x64)**.
+- Reinstall dependencies (clears locked native binaries):
+
+```bash
+Remove-Item -Recurse -Force node_modules\\onnxruntime-node, node_modules\\.onnxruntime-node-* -ErrorAction SilentlyContinue
+npm install
+```
+
+If you see a warning about **version mismatch** (e.g. "onnxruntime-node 1.23.x incompatible with transformers.js
+expectation 1.14.x"), install the matching version:
+
+```bash
+npm install onnxruntime-node@1.14.0
+```
+
 **Search returns no results**
 
 - Check `heuristic-mcp --status` for indexing progress.