Claude Context

Claude Context is an MCP (Model Context Protocol) plugin designed to provide semantic code search capabilities to Claude Code and other AI coding agents.

Key benefits include:

• Full Codebase Context: Uses semantic search to retrieve relevant code snippets from large codebases, eliminating the need for manual multi-round discovery.
• Cost Efficiency: Instead of feeding entire directories into the LLM context (which is expensive), it stores the codebase in a vector database and only injects the most relevant code segments into the context window.
• Integration: Works via the Model Context Protocol (MCP) to connect with AI assistants like Claude Code.

The Claude Context MCP server provides several key capabilities for AI-assisted coding:

• Hybrid Code Search: Combines BM25 and dense vector search for natural language queries.
• Codebase Indexing: Indexes entire codebases for high-scale search.
• Incremental Indexing: Uses Merkle trees to re-index only changed files.
• Intelligent Chunking: Uses AST-based analysis for syntax-aware code chunking.
• Scalability: Integrates with Zilliz Cloud for large-scale vector search.
• MCP Compliance: Fully compatible with any MCP-enabled assistant using stdio transport.

Claude Context is a monorepo designed to provide codebase context to AI agents and developers. It consists of three primary pillars:

1. @zilliz/claude-context-core: The engine responsible for indexing (using AST-based chunking and Merkle trees for incremental updates) and semantic search (hybrid BM25 + dense vector).
2. VSCode Extension: A user interface for semantic code search within the IDE.
3. @zilliz/claude-context-mcp: A Model Context Protocol (MCP) server that allows AI agents (like Claude Code) to interact with your codebase via semantic search.

Supported Technologies:

• Embedding Providers: OpenAI, VoyageAI, Ollama, Gemini.
• Vector Databases: Milvus or Zilliz Cloud.
• Languages: TypeScript, JavaScript, Python, Java, C++, C#, Go, Rust, PHP, Ruby, Swift, Kotlin, Scala, Markdown.

Claude Context is composed of several key packages depending on your integration needs:

• MCP Server (@zilliz/claude-context-mcp): The Model Context Protocol server that enables Claude and other MCP-compatible clients to access semantic search.
• VSCode Extension (semanticcodesearch): A VSCode extension that provides semantic code search directly within the editor.
• Core Package (@zilliz/claude-context-core): The foundational logic and core functionality of the project.

Claude Context MCP uses an asynchronous background process for codebase indexing. When you trigger an indexing task, the server returns an immediate response, allowing the agent to continue working while the actual heavy lifting (scanning, chunking, and embedding) happens in the background. This non-blocking approach allows you to perform searches and monitor progress without waiting for the entire process to complete.

Key characteristics:

• Non-blocking: The agent receives an immediate response upon starting indexing.
• Progressive Search: You can use search_code to find results even while indexing is still in progress (though results may be partial).
• Persistence: Progress is periodically saved to a local snapshot file at ~/.context/mcp-codebase-snapshot.json.

Claude Context identifies and tracks codebases using their resolved absolute path.

Important considerations:

• Path Resolution: All MCP tools (index_codebase, search_code, clear_index, get_indexing_status) resolve relative paths to absolute paths before performing operations.
• Identity: Collection identity is derived from the normalized absolute path.
• Avoid Duplicates: If you access the same repository via different paths (e.g., through a symlink, a different clone, or a different mount point), Claude Context will treat them as separate, distinct codebases.

Tip: To ensure consistent behavior, always use the same absolute path for all indexing and search operations.

Claude Context determines which files to index using an additive rule system. The final set of files is calculated as:

Final Files = (All Supported Extensions) - (All Ignore Patterns)

Extensions

Extensions are additive, combining:

• Default extensions
• MCP custom extensions
• Extensions defined via environment variables

Ignore Patterns

Ignore patterns are also additive, combining:

• Default patterns
• MCP custom patterns
• Patterns defined via environment variables
• .gitignore files
• .xxxignore files
• Global .contextignore files

Claude Context supports multiple codebases by leveraging MCP client workspace awareness.

Key Behaviors

• Automatic Path Detection: In MCP mode, it identifies the current working directory automatically.
• Seamless Switching: It detects when you switch between different codebases without manual path input.
• Background Sync: It monitors for changes and re-indexes modified parts automatically.
• Path-Based Indexing: Claude Context keys each codebase by its absolute path.

Warning: If you access the same repository via different paths (e.g., a symlink, a different clone, or a mounted path), Claude Context will treat them as separate, isolated indexed codebases.

The get_indexing_status tool reports a coarse, phase-based percentage rather than an exact count of files completed. It is normal to see large jumps in percentage (e.g., jumping from 5% to 10% quickly).

Progress Phases:

• 0%: Preparing the target collection and validating prerequisites.
• ~5%: Scanning the codebase and building the file list.
• 10% → 100%: Processing files, chunking code, generating embeddings, and writing batches to the vector database.
• 100%: Indexing finished successfully.