heuristic

Heuristic MCP Server adds smart code search capabilities to your editor or MCP client. It builds an index of your workspace and serves it to IDE AI models and MCP tooling, enabling natural-language style queries to locate relevant code, snippets, or APIs quickly. Once running, you can use the included commands to check status, view logs, or stop the server, and you can rely on the cache and indexing progress to gauge how up-to-date your search results are. The server is designed to run alongside your development environment and update its index as your project changes, improving results over time.

You can start the server using the provided CLI and then connect from your editor or MCP client. Basic commands to interact with the server include status, logs, stop, and cache. The status command helps verify that the server is running and healthy, logs lets you inspect runtime information, and cache reveals index progress and any caching issues. The server surfaces a fast, searchable index that your editor or MCP tools query with plain language queries to find relevant code sections or APIs fast.

Prerequisites:

• Node.js 18 or newer
• npm (for global installation)
• Internet access at least once to download the embedding model (if download is skipped at install time, it will download on first run)
• 64-bit Node.js for native ONNX performance; on Windows, install the Microsoft Visual C++ 2015-2022 Redistributable (x64) if native bindings fail

Install steps:

1. Install the package globally (recommended):

npm install -g @softerist/heuristic-mcp

2. Start the server for use with your MCP client/editor:

heuristic-mcp --start

3. If your editor was open, reload it to pick up the new MCP integration.

Alternate lightweight start (without global install):

npx -y @softerist/heuristic-mcp --start

Basic verification:

heuristic-mcp --status

Tips and common issues:

• Ensure you are on Node.js 18+ and a 64-bit environment for best performance with ONNX.
• If native bindings fail on Windows, install the VC++ 2015-2022 Redistributable (x64).
• The server requires an initial online fetch of the embedding model; if the model download is blocked, the server will download on first run.
• If you frequently reindex or modify large codebases, check the cache status to monitor indexing progress and potential cache misses.
• If you run into permission issues on Unix-like systems, try running with appropriate user permissions or using sudo where applicable.
• Documentation and advanced configuration are available in the docs folder of the project (GUIDE.md and ARCHITECTURE.md).