Skip to main content
Glama
deenesjakoruzh
genautkin

code-search-mcp

by genautkin
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

🔍 code-search-mcp

Zero-daemon local semantic code search MCP server and CLI powered by LanceDB and in-process ONNX embeddings.
Stop grepping for exact words. Give your AI coding assistant the power to search your codebase by meaning.

Works out-of-the-box with Claude Code, Gemini CLI, Antigravity (agy), and Cursor on macOS, Windows, and Linux.

⚡️ Quick Start (30-Second Setup)

1. Install Globally

npm install -g github:genautkin/code-search-mcp

2. Connect to Your AI Assistant (One-Time)

  • Claude Code:

    claude mcp add code-search -s user -- code-search-mcp

  • Antigravity CLI (agy):

    mkdir -p ~/.gemini/config/plugins/code-search && cat << 'EOF' > ~/.gemini/config/plugins/code-search/mcp_config.json
{
  "mcpServers": {
    "code-search": {
      "command": "code-search-mcp"
    }
  }
}
EOF

  • Cursor / Claude Desktop / Gemini CLI: Add "code-search": { "command": "code-search-mcp" } to your MCP configuration file.

3. Initialize in Any Project

Navigate to any repository and run:

code-search-mcp init

(Or run code-search-mcp init -y for 1-second automated setup with smart defaults)

Now you and your AI coding assistant can search your codebase by meaning! 🚀

Related MCP server: claude-context-local

📖 Detailed Guide

📦 1. Installation

You can install code-search-mcp globally or run it on demand:

  • Global Installation (Recommended):

    npm install -g github:genautkin/code-search-mcp

    Places the fast code-search-mcp binary into your system PATH.

  • On-Demand Execution (No global install):

    npx github:genautkin/code-search-mcp init

🔌 2. Connecting to MCP Clients

code-search-mcp operates as a high-speed stdio MCP server. When registered globally, it works across all your projects without draining battery or running background daemons on uninitialized repos.

🧠 Claude Code

# Available globally across all projects:
claude mcp add code-search -s user -- code-search-mcp

# Or scoped to a single specific project directory:
claude mcp add code-search -- code-search-mcp --path /path/to/your/project

🤖 Antigravity CLI (agy)

Register the plugin in your user settings:

mkdir -p ~/.gemini/config/plugins/code-search && cat << 'EOF' > ~/.gemini/config/plugins/code-search/plugin.json
{ "name": "code-search" }
EOF
cat << 'EOF' > ~/.gemini/config/plugins/code-search/mcp_config.json
{
  "mcpServers": {
    "code-search": {
      "command": "code-search-mcp"
    }
  }
}
EOF

🪄 Gemini CLI

Add to ~/.gemini/settings.json (or workspace .gemini/settings.json):

{
  "mcpServers": {
    "code-search": {
      "command": "code-search-mcp",
      "trust": true
    }
  }
}

💻 Cursor / Claude Desktop / Windsurf

Add to .cursor/mcp.json or claude_desktop_config.json:

{
  "mcpServers": {
    "code-search": {
      "command": "code-search-mcp",
      "args": ["--path", "${workspaceFolder}"]
    }
  }
}

🪄 3. Initializing a Project (init)

To activate semantic search for a repository, run the interactive setup wizard:

code-search-mcp init

Interactive Wizard Features:

  1. 📁 Index Storage Location:

    • node_modules/.cache/code-search/lancedb (Default for JavaScript/TypeScript projects — Zero Git Noise)

    • .code-search/lancedb (Automatically added to .gitignore to keep your repo clean)

    • Custom path

  2. 🛡 Respect .gitignore: Automatically skips build outputs, bundles, and vendor folders already in your .gitignore.

  3. 📝 Search Ignore File (.codesearchignore): Automatically skips asking if .codesearchignore already exists. If missing, offers recommended exclude patterns for test fixtures and mock snapshots.

  4. 🔍 File Extension Auto-detection: Scans repository contents to detect active extensions (e.g. .ts, .tsx, .py, .go, .json, .md), with the option to customize.

  5. 🚀 Initial Indexing: Builds initial vector index immediately with live progress and status summary.

Non-Interactive / CI Setup:

Pass -y to skip questions and apply smart defaults:

code-search-mcp init -y

Tip: You can change your configuration anytime by editing .codesearchrc.json or .codesearchignore.

💻 4. CLI Command Reference

code-search-mcp is both an MCP server and a fast terminal utility:

Command

Description

code-search-mcp init [path]

Interactive setup wizard (use -y for non-interactive)

code-search-mcp uninit [path]

Remove configuration and clean vector database index

code-search-mcp status [path]

Check index health, total indexed files, chunk counts, and database path

code-search-mcp index [path]

Rebuild or update the vector index with live progress (use -f for full clean rebuild)

code-search-mcp search <query>

Run semantic search directly from your terminal with syntax highlighting

☕️ Imagine a Coffee Shop App

Imagine you are building software for a busy local coffee shop.

In your codebase, you have a file that handles what happens when a customer orders an extra oat milk latte and gets a morning discount:

// Apply a 15% promotional deduction if the customer visits before 9 AM
export function calculateEarlyBirdReward(bill: OrderSummary): number {
  if (bill.orderHour < 9) {
    return bill.subtotal * 0.85;
  }
  return bill.subtotal;
}

Now imagine you open your AI coding assistant (like Claude Code, Cursor, or Gemini CLI) and ask:

"Where is the morning drink discount calculated?"

If your tool relies only on traditional text search (like grep), it searches for the exact word "discount".

  • Did it find calculateEarlyBirdReward? No.

  • Why? Because the code used the words promotional deduction and EarlyBirdReward, but never the exact word "discount".

This is where Semantic Search changes everything.

🧠 What is Semantic Search (In Plain English)?

Traditional search looks for exact letters and words.

Semantic search looks for the meaning behind your words.

How It Works: The Map of Meaning

  1. Numbers instead of letters: An AI model takes a piece of text (or code) and translates it into a list of numbers called an embedding (or vector).

  2. Coordinates on a map: Think of these numbers like GPS coordinates on a giant map of human concepts.

    • "discount" and "promotional deduction" end up sitting right next to each other on the map.

    • "espresso shot" and "latte" sit together.

    • "database migration" sits far away on the other side of the map.

  3. Finding nearest neighbors: When you ask a question in plain English, the search engine turns your question into coordinates and simply finds the pieces of code sitting closest to it on the map.

                  [ Map of Meaning ]

   ☕️ "morning drink discount"   📍 (Your Question)
              │ (Close match!)
              ▼
   🏷 "calculateEarlyBirdReward" 📍 (Your Code)
   
   ─────────────────────────────────────────────
   
   🗄 "sql database migration"   📍 (Far Away - Ignored)

🚀 Why Semantic Search is a Game-Changer for AI Coding

When AI coding assistants work on large repositories with thousands of files, they cannot read every single file on every prompt — it is too slow and costs too many tokens.

Instead, the AI needs to find the exact 2 or 3 relevant files instantly.

In real-world projects, our codebases are full of rich context:

  • Markdown documentation (.md): Architecture decision records, API guides, onboarding docs.

  • Code comments: Explaining why a business rule exists (e.g. // Deduct beans from bean hopper inventory).

  • Function and variable names: Naming patterns that may differ across libraries.

Semantic search connects your natural language thoughts directly to those markdown docs, comments, and code snippets — even when you do not remember the exact function names.

🛠 Architecture & Dormant MCP Mode

Many existing semantic search tools for developers require heavy setups (Python, virtual environments, external background daemons).

code-search-mcp is designed around Explicit Opt-In & Zero Resource Waste:

  • Dormant by Default: If a repository does not have .codesearchrc.json, the MCP server connects instantly in <10ms and stays dormant — zero background workers, zero file watchers, and zero CPU usage until initialized.

  • On-Demand AI Initialization: If an AI assistant calls code_search in an uninitialized repo, it receives clear instructions or can call code_search_init directly.

  • In-Process ONNX Embeddings: Runs @huggingface/transformers in-process with all-MiniLM-L6-v2. 100% private, zero network calls.

  • Embedded LanceDB: Serverless, embedded vector database.

┌─────────────────────────────────────────────────────────────┐
│                       AI Client                             │
│       (Claude Code / Gemini CLI / Antigravity / Cursor)     │
└──────────────────────────────┬──────────────────────────────┘
                               │ MCP Protocol (JSON-RPC over stdio)
┌──────────────────────────────▼──────────────────────────────┐
│                      code-search-mcp                        │
│                                                             │
│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────┐  │
│  │   Scanner &      │  │  EmbeddingEngine │  │  Watcher  │  │
│  │ Layered Ignores  │  │  (all-MiniLM-L6) │  │(chokidar) │  │
│  └────────┬─────────┘  └────────┬─────────┘  └─────┬─────┘  │
│           │                     │                  │        │
│           └───────────┬─────────┴──────────────────┘        │
│                       ▼                                     │
│              VectorStore (LanceDB)                          │
│        node_modules/.cache/code-search/                     │
└─────────────────────────────────────────────────────────────┘

⚙️ Configuration Reference

.codesearchrc.json

Full repository configuration with JSON Schema support:

{
  "$schema": "https://raw.githubusercontent.com/genautkin/code-search-mcp/main/schema.json",
  "version": 1,
  "indexPath": "node_modules/.cache/code-search/lancedb",
  "respectGitignore": true,
  "supportedExtensions": [".ts", ".tsx", ".js", ".vue", ".py", ".md"],
  "customExcludes": [
    "legacy_vendor/**",
    "docs/archive/**"
  ],
  "maxFileSizeKb": 500,
  "embeddingModel": "Xenova/all-MiniLM-L6-v2"
}

.codesearchignore

Standard .gitignore style glob file for search exclusions:

# Test fixtures and mocks
**/fixtures/**
**/mocks/**
*.snap

# Auto-generated code
*.generated.*
locales/**

🤖 AI Agent Guide & Tool Reference

If you are an AI assistant (Claude Code, Gemini CLI, Cursor, Antigravity, or Windsurf) reading this repository:

🛠️ Available MCP Tools

Tool Name

Arguments

Description

When to Call

code_search

query (required)limit (optional, default 10)pathFilter (optional string)language (optional string)codeOnly (optional boolean)

Performs hybrid semantic + lexical search across indexed repository files. Returns line-numbered code chunks with similarity scores.

Primary tool for natural language & conceptual queries: Call whenever locating concepts, business logic, workflows, UI components, or features described in natural language, before attempting blind greps.

code_search_init

indexPath (optional)respectGitignore (optional)supportedExtensions (optional)

Initializes semantic search for the repository and builds initial index.

When repository is not yet initialized.

code_search_status

(none)

Returns current indexing progress (READY, INDEXING, UNINITIALIZED), percentage, total files, and chunk count in LanceDB.

Check indexing progress.

code_search_reindex

forceFull (optional boolean)

Triggers a background re-index or complete database rebuild.

After massive merges or when user requests rebuild.

code_search_guide

(none)

Returns inline agent usage best practices and tips.

Call to self-discover best practices during tool invocation.

💡 Strongly Recommended Scenarios for code_search:

  • Natural Language & Conceptual Questions: When searching for concepts, domain rules, business workflows, UI components, or features (e.g. "where are authentication tokens refreshed", "how is discount calculated", "dark mode toggle component").

  • Exploring Unfamiliar Codebases: When you do not know the exact file names, functions, or variable names.

  • Finding Meaning Behind Code: When exact keyword search / grep returns too many noisy results or misses synonyms.

🧪 Verification & Testing

To run the automated test suite:

npm test

All 45 unit & integration tests verify the MCP protocol handshake, ONNX vector generation, LanceDB storage, watcher lifecycle, word stemming, typo correction, init wizard, and dormant server mode.

💡 Summary

  • ✅ Explicit Opt-in: Dormant until initialized, saving battery and CPU.

  • ✅ Interactive init Wizard: Discovers file types and configures settings with smart defaults.

  • ✅ No background daemons: Zero external background services or Python dependencies.

  • ✅ Zero Git noise: Default storage in node_modules/.cache.

  • ✅ Handles typos & word variations automatically.

  • ✅ Instant search by meaning, connecting natural language questions to the exact code you need.

Happy coding! ☕️🚀

Available Tools

4 tools
code_search_guideA

Get best practices and usage instructions for AI agents on how and when to use code_search.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the behavioral burden. It clearly implies a read-only retrieval of guidance, but does not disclose output format, size, or any side effects. For a simple guide tool, the lack of explicit behavioral detail is acceptable but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that states the action and the target resource with zero redundancy. Every word contributes to clarity, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless guide with no output schema, the description sufficiently conveys the tool's purpose and content. It could explicitly state that the returned instructions should be followed before using code_search, but the sibling context and the description's phrasing make this largely self-evident, so the gap is minimal.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, and schema coverage is 100% (vacuously). Since the tool takes no inputs, the description need not add parameter-specific meaning; the baseline of 4 for no-parameter tools applies without deduction.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('get') and a clear resource ('best practices and usage instructions for AI agents on code_search'). It distinguishes itself from sibling tools like code_search (which performs the search), code_search_status, and code_search_reindex, making its purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states it provides guidance on how and when to use code_search, which implicitly tells an agent to use this tool when needing to decide on code_search usage. However, it does not explicitly contrast with sibling tools or state 'use this before calling code_search', leaving that inference to the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

code_search_reindexA

Trigger a background re-index of the repository. Can be used to force a full reindex.

ParametersJSON Schema
NameRequiredDescriptionDefault
forceFullNoIf true, clears existing vector database and rebuilds index from scratch

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of disclosing behavior. It mentions 'background' indicating asynchronicity and 'force a full reindex' implying destructive potential, but it omits details like whether an incremental reindex is available, idempotency, or cancellation behavior. It provides some useful context but is not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short, focused sentences with no filler. It front-loads the core action ('Trigger a background re-index') and adds the optional force behavior succinctly. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a single optional parameter and no output schema, the description covers the essentials but leaves gaps: it does not clarify what happens when forceFull is false (e.g., incremental indexing) nor mention the sibling code_search_status for checking reindex progress. These are minor gaps given the simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the forceFull parameter is fully documented in the schema ('clears existing vector database and rebuilds index from scratch'). The description's mention of 'force a full reindex' adds minimal value beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Trigger a background re-index of the repository') with a specific verb and resource. It also hints at the forceFull parameter. This distinguishes it from siblings like code_search, code_search_status, and code_search_guide, which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives. It implies usage through the tool's purpose but lacks explicit context such as 'use after schema changes' or 'when index is stale'. No exclusions or alternative routing are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

code_search_statusA

Get the current indexing status, progress percentage, total files, and indexed chunk count.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It correctly implies a read-only operation via 'Get' and enumerates the output fields. It does not mention side effects, authentication, or rate limits, but for a simple status check these are not critical. It does not contradict any annotations (there are none) and gives sufficient behavioral context for expectation setting.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that lists the key outputs without any fluff. It is front-loaded with the verb and resource, making it instantly scannable. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters, no annotations, and no output schema, the description is fully sufficient. It states exactly what information will be retrieved. An agent can call it without needing additional context or clarification.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema coverage is trivially 100%. Baseline for 0 parameters is 4. The description adds no parameter-specific details (none needed), and it correctly explains what the tool returns, which is sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get') and the resource ('current indexing status'), and lists specific fields (progress percentage, total files, indexed chunk count). The verb and resource differentiate it from siblings like code_search, code_search_reindex, and code_search_guide. It unambiguously describes what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies its use for checking indexing status but provides no explicit guidance on when to choose this over the sibling tools (e.g., 'use this to check, not to trigger reindexing'). No exclusions or alternative references are given. While the purpose is clear, the tool lacks explicit routing compared to the high-standard examples.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updatesv0.1.0
    • First observedcode_search
    • First observedcode_search_guide
    • First observedcode_search_reindex
    • First observedcode_search_status
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

Each tool has a unique, clearly defined purpose: search, status, reindex, and guide. There is no overlap or ambiguity between them, and the descriptions make it obvious which tool to use for each task.

Naming Consistency5/5

All tool names follow the same convention: 'code_search_' followed by a simple action verb (search, status, reindex, guide). This is perfectly consistent and makes the tool set easy to predict and use.

Tool Count5/5

With 4 tools, the set is tightly scoped and every tool serves a necessary function for a code search server. This is an ideal count—not too thin or over-bloated—for the domain.

Completeness5/5

The tool surface covers the full lifecycle of a code search server: performing searches, checking index status, triggering reindexes, and providing usage guidance. There are no obvious gaps in functionality.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/genautkin/code-search-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server