mcp-codesearch

mcp-codesearch

MCP server for semantic code search with AST-aware chunking, hybrid vectors, and query syntax.

Prerequisites

• Python 3.12+
• Linux or macOS (uses POSIX file locking via vector-core; not compatible with Windows)
• Qdrant vector database (default: localhost:6333)
• An OpenAI-compatible embedding API (e.g., llama.cpp, Ollama, or any /v1/embeddings endpoint; default: localhost:8080)

Installation

Requires vector-core.

pip install git+https://github.com/michaelkrauty/vector-core.git@v1.4.0
pip install git+https://github.com/michaelkrauty/mcp-codesearch.git

Or clone both repos and install locally:

git clone https://github.com/michaelkrauty/vector-core.git
git clone https://github.com/michaelkrauty/mcp-codesearch.git
pip install -e vector-core/
pip install -e mcp-codesearch/

Quick Start

# Register with Claude Code:
claude mcp add codesearch -- mcp-codesearch

# Or add to your MCP client config (e.g., claude_desktop_config.json):
# {
#   "mcpServers": {
#     "codesearch": {
#       "command": "mcp-codesearch",
#       "env": {
#         "VECTOR_QDRANT_URL": "http://localhost:6333",
#         "VECTOR_EMBEDDING_URL": "http://localhost:8080",
#         "VECTOR_EMBEDDING_MODEL": "your-model-name",
#         "VECTOR_EMBEDDING_DIM": "768"
#       }
#     }
#   }
# }

Features

• Hybrid Search: Dense embeddings + sparse TF-IDF with RRF fusion
• AST-Aware Chunking: Tree-sitter extracts functions, classes, methods with context
• 18 Languages with AST Support: Python, JS/TS, Go, Rust, Java, C/C++, Ruby, PHP, Swift, Kotlin, Scala, C#, SQL, JSON, YAML, TOML (line-based fallback for Bash, HTML, CSS, and other file types)
• Query Syntax: function:name, class:name, file:pattern, path:prefix, -path:exclude
• Incremental Indexing: Change detection via mtime+size before hashing
• Query Preprocessing: Synonym expansion (fn → function, db → database)
• Flexible Ignores: Nested .gitignore, .git/info/exclude, and .codesearchignore (gitignore syntax) honored at every directory level

Tools (11 total)

Search (5)

| Tool | Description | |------|-------------| | code_search | Main search with auto-indexing | | search_multiple | Search across multiple codebases | | search_changed | Search in recently changed files (git-aware) | | find_similar | Find code similar to a snippet | | find_references | Find all usages of a symbol |

Index Management (3)

| Tool | Description | |------|-------------| | index_status | Check indexing status, file count, pending changes | | force_reindex | Force complete re-indexing | | preview_index | Preview what would be indexed |

Collection Management (3)

| Tool | Description | |------|-------------| | list_collections | List all indexed codebases | | delete_collection | Remove index for a codebase | | cleanup_orphans | Remove orphaned collections |

Query Syntax

# Natural language (semantic search)
code_search("websocket reconnection logic")

# Function search
code_search("function:handleRequest")
code_search("fn:handleRequest")  # alias

# Class search
code_search("class:WebSocketClient")
code_search("cls:WebSocketClient")  # alias

# Path filtering
code_search("auth path:src/services")
code_search("test -path:vendor -path:node_modules")

# Filename filtering (glob, case-insensitive, matches filename only)
# Pushed into the retrieval layer when possible, so a match in the named
# file is found even if it would rank below the candidate pool
code_search("connection pooling file:db.py")
code_search("schema migration file:*.sql")

# Struct search (Rust, C, Go)
code_search("struct:Message")

# Combined
code_search("function:process_data path:src -path:test")

# Exact phrase
code_search('"exact function name"')

Synonym Expansion

Common abbreviations automatically expanded:

• fn, func → function
• cls → class
• db → database
• ws → websocket
• auth → authentication, authorization
• req, res → request, response

Additional Query Syntax

# Alternative function search aliases
code_search("def:processData")
code_search("method:handleRequest")

# Type/struct alias
code_search("type:UserConfig")

# Scope filters (restrict to chunk types)
code_search("error scope:function")    # Only function chunks
code_search("model scope:class")       # Only class chunks
code_search("validate scope:test")     # Only test functions
code_search("handler scope:impl")      # Non-test code only
# scope:method is an alias for scope:function; scope:struct, scope:enum,
# scope:interface, scope:type and scope:module are aliases for scope:class

Search Modes

| Mode | Description | |------|-------------| | file | File-level results (overview) | | chunk | Function/class-level results (detailed) | | both | Combined ranking (default) |

AST Chunking

Tree-sitter extracts semantic units:

• Functions (with docstrings)
• Classes (with methods if small, or overview + separate methods if large)
• Methods (with parent class context)
• Modules (imports, top-level statements)

Fallback to line-based chunking for non-code files (JSON, YAML, TOML, Markdown).

Path Boosting

Search results boosted/demoted by path:

| Pattern | Adjustment | |---------|------------| | src/ | +10% | | lib/, core/ | +8% | | test/, tests/ | -10% | | vendor/ | -25% | | generated/ | -30% |

Git Integration

search_changed searches only files changed since a git revision or time. The changed-file set is applied as a retrieval-layer filter, so results are ranked within the changed files rather than intersected against a bounded whole-codebase candidate pool (change sets over 500 files fall back to post-filtering). ``bash search_changed("auth logic", since="HEAD~5") search_changed("database", since="main") search_changed("fix", since="abc123") search_changed("config", since="3.days.ago") ``

Configuration

| Variable | Default | Description | |----------|---------|-------------| | VECTOR_QDRANT_URL | http://localhost:6333 | Qdrant server | | VECTOR_EMBEDDING_URL | http://localhost:8080 | OpenAI-compatible embeddings API | | VECTOR_EMBEDDING_MODEL | (required) | Embedding model name (e.g., nomic-embed-text, text-embedding-3-small) | | VECTOR_EMBEDDING_DIM | (required) | Vector dimension (must match your model, e.g., 768, 1536) |

Changing the embedding model. A codebase's index is tied to the embedding model it was built with. If you switch VECTOR_EMBEDDING_MODEL, the next search or index of that codebase fails fast with a clear error pointing at force_reindex, instead of a cryptic Qdrant dimension error (different-dimension swap) or silently meaningless results from incompatible embedding spaces (same-dimension swap — the model name is recorded in each collection's metadata and checked on reuse). Run force_reindex on the affected codebase to rebuild it with the new model — each codebase is reindexed independently.

Codesearch-specific settings (configured via environment variables with the CODESEARCH_ prefix):

| Variable | Default | Description | |----------|---------|-------------| | CODESEARCH_CLASS_SPLIT_THRESHOLD | 50 | Lines threshold for splitting large classes | | CODESEARCH_CHUNK_MIN_LINES | 10 | Merge chunks smaller than this | | CODESEARCH_CHUNK_MAX_LINES | 500 | Max lines per fallback chunk | | CODESEARCH_CHUNK_OVERLAP_LINES | 25 | Overlap between fallback chunks | | CODESEARCH_SEARCH_CACHE_MAX_SIZE | 100 | Max cached search results | | CODESEARCH_SEARCH_CACHE_TTL_SECONDS | 300 | Search cache TTL (seconds) | | CODESEARCH_SEARCH_CACHE_EVICTION_RATIO | 0.2 | Fraction of cache to evict when full | | CODESEARCH_UPSERT_BATCH_TIMEOUT | 300 | Batch operation timeout (seconds) | | CODESEARCH_UPSERT_CONCURRENCY | 1 | Max concurrent upsert batches | | CODESEARCH_DELETION_CONCURRENCY | 50 | Concurrent Qdrant operations during incremental indexing |

Change Detection

Fast incremental updates:

1. Check mtime + size (skip unchanged files)
2. Hash only modified files
3. Re-index only changed chunks

Avoids full re-embedding on every search.

Ignoring files

File discovery honors gitignore-syntax exclude rules at every directory level:

• .gitignore — nested .gitignore files are respected, matching git semantics (deeper files override shallower, ! negations re-include).
• .git/info/exclude — repo-local excludes that are not committed to git.
• .codesearchignore — exclude paths from indexing without changing git's behavior. Same syntax as .gitignore; useful for vendored code, generated files, or large data you want tracked by git but kept out of the index.

Ignored directories are pruned during traversal, so excluded subtrees cost nothing. The global core.excludesFile is intentionally not consulted, so indexing stays reproducible regardless of per-machine git configuration.

Storage

| Data | Location | |------|----------| | Index | Qdrant collection codesearch_{path_hash} | | Metadata | Stored in Qdrant point payloads |

Each indexed codebase gets a unique collection based on path hash.

Supported Languages

Full tree-sitter AST support (18 languages): Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, Ruby, PHP, Swift, Kotlin, Scala, C#, SQL, JSON, YAML, TOML

Line-based fallback: Bash, HTML, CSS, and all other file types (Markdown, Vue, Svelte, config files, etc.) are indexed with line-based chunking.

Jupyter notebooks (.ipynb): Notebooks are indexed by their code. Code cells are extracted (markdown, raw, and output cells are skipped) and chunked as Python with full AST support, so a notebook's functions and classes are searchable just like any other source file. Code-less or unparseable notebooks are skipped.

Dependencies

Requires vector-core components:

• EmbeddingClient, GlobalVocabulary (embeddings)
• QdrantStorage, HybridSearcher (storage)

External libraries:

• tree-sitter-language-pack (AST parsing)
• pathspec (.gitignore / .codesearchignore support)