@softerist/heuristic-mcp 3.0.1 → 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

@@ -111,6 +111,8 @@ Example `config.jsonc`:
   "smartIndexing": true,
   "embeddingModel": "jinaai/jina-embeddings-v2-base-code",
   "workerThreads": 0,
+  "embeddingBatchSize": null,
+  "embeddingProcessNumThreads": 8,
   "enableExplicitGc": false,
   "recencyBoost": 0.1,
   "recencyDecayDays": 30,
@@ -136,10 +138,12 @@ Cache location:
 Selected overrides (prefix `SMART_CODING_`):
 
 - `SMART_CODING_VERBOSE=true|false` — enable detailed logging.
-- `SMART_CODING_WORKER_THREADS=auto|0|N` — worker thread count (`0` disables workers).
+- `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.

package/package.json

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

package/GEMINI.md

@@ -1,73 +0,0 @@
-# Heuristic MCP
-
-## Project Overview
-
-**@softerist/heuristic-mcp** is an enhanced Model Context Protocol (MCP) server designed to provide intelligent semantic code search capabilities. It integrates features like find-similar-code, recency-aware ranking, call-graph proximity boosts, and smart chunking to improve code retrieval accuracy for AI assistants (Antigravity, Cursor, Claude Desktop, VS Code).
-
-**Key Features:**
-*   **Semantic Search:** Finds code by meaning using embeddings.
-*   **Smart Indexing:** Automatically detects project types and applies ignores.
-*   **Recency & Proximity:** Boosts results based on file modification time and call graph relationships.
-*   **ANN Index:** Optional Approximate Nearest Neighbor index for performance on large codebases.
-*   **Zero-touch Setup:** Auto-registers with supported IDEs.
-
-## Architecture
-
-The project follows a modular architecture:
-
-*   **`index.js`**: Main entry point. Initializes the MCP server, loads configuration, and registers features.
-*   **`lib/`**: Core libraries.
-    *   `config.js`: Configuration loader and environment variable handling.
-    *   `cache.js`: Manages embedding vectors persistence and ANN index.
-    *   `cache-utils.js`: Stale cache detection/cleanup.
-    *   `utils.js`: Shared utilities (hashing, similarity, smart chunking).
-    *   `call-graph.js`: Extracts symbols and builds a lightweight call graph.
-    *   `tokenizer.js`: Token estimation.
-    *   `embedding-worker.js`: Worker-thread embedder runner.
-    *   `embedding-process.js`: Child-process embedder runner (isolation).
-    *   `ignore-patterns.js`: Smart ignore patterns by detected project type.
-    *   `json-worker.js` / `json-writer.js`: Streaming JSON helpers.
-    *   `logging.js`: Log file helpers.
-*   **`features/`**: Pluggable feature modules. Each module exports a class, tool definition, and handler.
-    *   `hybrid-search.js`: Semantic search logic.
-    *   `index-codebase.js`: File discovery and indexing.
-    *   `find-similar-code.js`: Logic for finding similar snippets.
-    *   `lifecycle.js` & `register.js`: CLI and IDE registration helpers.
-*   **`scripts/`**: Utility scripts (postinstall, model download, cache clearing).
-*   **`tools/`**: Developer-only helpers (manual search script).
-
-## Building and Running
-
-### Prerequisites
-*   Node.js >= 18.0.0
-
-### Key Commands
-
-| Command | Description |
-| :--- | :--- |
-| `npm start` | Runs the server (production mode). |
-| `npm run dev` | Runs the server in development mode (watch mode). |
-| `npm test` | Runs the test suite using Vitest. |
-| `npm run clean` | Clears the cache directory. |
-| `npm run lint` | Runs ESLint. |
-| `npm run format` | Runs Prettier. |
-
-**Note on Testing:** Tests are configured to run sequentially (`fileParallelism: false`) to manage memory usage of the embedding models. Use `USE_REAL_EMBEDDER=true npm test` to test with the actual model instead of mocks.
-
-## Development Conventions
-
-*   **Style:** Modern ES6+ JavaScript.
-*   **Modularity:** New features should be added as separate modules in `features/` following the pattern:
-    1.  **Class:** `export class FeatureName { ... }`
-    2.  **Tool Def:** `export function getToolDefinition(config) { ... }`
-    3.  **Handler:** `export async function handleToolCall(request, instance) { ... }`
-*   **Logging:** Use `console.info()` for normal server lifecycle output (redirected to logs when running in MCP mode). Use `console.warn()` for non-fatal issues and `console.error()` for errors. CLI utilities may also use `console.info()` for user-facing output.
-*   **Configuration:** All features should accept a `config` object. Environment variables (prefix `SMART_CODING_`) override `config.json` values.
-
-## Key Files
-
-*   **`package.json`**: Dependencies and scripts.
-*   **`config.json`**: Default/example configuration.
-*   **`ARCHITECTURE.md`**: Detailed architectural documentation.
-*   **`CONTRIBUTING.md`**: Guidelines for contributors.
-*   **`vitest.config.js`**: Test runner configuration.