Skip to main content
Glama
Sign In
heuristic-mcp

heuristic-mcp

by softerist
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

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

Related MCP server: Acemcp

Install

npm install -g @softerist/heuristic-mcp

Then enable it for your client:

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

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:

License: MIT

Available Tools

7 tools
a_semantic_searchA
Read-onlyIdempotent

Performs intelligent hybrid code search combining semantic understanding with exact text matching. Ideal for finding code by meaning (e.g., 'authentication logic', 'database queries') even with typos or variations. Returns the most relevant code snippets with file locations and line numbers.

Inputs: query (required), maxResults.

b_index_codebaseA
Idempotent

Manually trigger a full reindex of the codebase. This will scan all files and update the embeddings cache. Useful after large code changes or if the index seems out of date.

Inputs: force.

c_clear_cacheA
DestructiveIdempotent

Clears the embeddings cache, forcing a complete reindex on next search or manual index operation. Useful when encountering cache corruption or after major codebase changes.

Inputs: no named parameters.

d_ann_configA
Idempotent

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).

Inputs: action, efSearch.

d_find_similar_codeA
Read-onlyIdempotent

Find similar code patterns in the codebase. Given a code snippet, returns other code chunks that are semantically similar. Useful for finding duplicate code, understanding patterns, and refactoring opportunities.

Inputs: code (required), maxResults, minSimilarity.

e_check_package_versionA
Read-onlyIdempotent

Fetches the latest version of a package from its official registry. Supports npm, PyPI, crates.io, Maven, Go, RubyGems, NuGet, Packagist, Hex, pub.dev, Homebrew, and Conda. Use prefix like "pip:requests" for non-npm packages.

Inputs: package (required).

f_set_workspaceA
Idempotent

Changes the current workspace path at runtime. This updates the search directory and cache, and optionally triggers a full reindex. Useful for multi-project workflows.

Inputs: workspacePath (required), reindex.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.9/5.0

    Scored across 7 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • MCP Indexer

      gkatechis
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables semantic code search across multiple repositories using natural language queries. Provides intelligent code discovery, symbol lookups, and cross-repo dependency analysis for AI coding agents.
      MIT

    • Acemcp

      qy527145
      A
      license
      A
      quality
      D
      maintenance
      Enables semantic code search across codebases with automatic incremental indexing. Searches return relevant code snippets with file paths and line numbers based on natural language queries.
      1
      805
      Apache 2.0

    • Smart Coding MCP

      omar-haris
      A
      license
      A
      quality
      D
      maintenance
      Provides intelligent semantic code search using local AI embeddings, enabling natural language queries to find relevant code by meaning rather than exact keywords. Indexes codebases in the background with smart project detection and privacy-first local processing.
      6
      24 npm
      200
      MIT