heuristic-mcp
# Heuristic MCP Server
Heuristic MCP adds smart code search to your editor or MCP client.
## Requirements
- Node.js `18+`
- npm (for global install)
- Internet access at least once to download the embedding model (if install-time download is skipped, it downloads on first run)
- 64-bit Node.js recommended for native ONNX performance; on Windows, install Microsoft Visual C++ 2015-2022 Redistributable (x64) if native bindings fail
## Install
```bash
npm install -g @softerist/heuristic-mcp
```
Then enable it for your client:
```bash
heuristic-mcp --start
```
If your editor was already open, reload it once.
## How It Works
1. The server scans your workspace and builds a searchable index of your code.
2. IDE AI models/MCP tools query that index using plain language so you can find relevant code quickly.
3. Results improve as your index stays up to date with project changes.
## Basic Commands
```bash
heuristic-mcp --status
heuristic-mcp --logs
heuristic-mcp --stop
```
Use `heuristic-mcp --status` first if something looks off.
Use `heuristic-mcp --cache` to see the cache status or file index progress.
## Advanced Docs
Detailed configuration, tool reference, troubleshooting, and release notes are in:
- [`docs/GUIDE.md`](docs/GUIDE.md)
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
License: MIT
TDQS
Scored across 7 tools
Most tools have distinct purposes, but a_semantic_search and d_find_similar_code both deal with semantic code search, potentially causing confusion. However, descriptions clarify different use cases (query vs. snippet input). The two d-prefixed tools are clearly different.
All tool names follow a consistent pattern of a letter prefix followed by an underscore and a descriptive name (e.g., a_semantic_search, b_index_codebase). The pattern is uniform, though the letters themselves have no semantic meaning.
7 tools is a reasonable number for a code search server. The count feels appropriate, covering core functionality without being overly sparse or bloated. The inclusion of e_check_package_version seems slightly out of scope but doesn't harm coherence.
The tool set covers essential operations: search, indexing, cache management, configuration, similarity search, and workspace switching. A minor gap is the lack of a tool to inspect or delete specific indexed files, but overall the surface is sufficient for the domain.