CLAUDE.md # CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Overview Claude Context is an MCP plugin that adds semantic code search to AI coding agents. A codebase is split into chunks, embedded, and stored in a Milvus/Zilliz vector database; queries are answered by semantic (hybrid dense + sparse) search instead of loading whole directories into the model's context. ## Monorepo Layout pnpm workspace (`packages/*`, `examples/*`). Requires Node >=20 <24 and pnpm >=10. - `packages/core` (`@zilliz/claude-context-core`) — the indexing engine. All real logic lives here; the other packages are thin frontends over it. - `packages/mcp` (`@zilliz/claude-context-mcp`) — stdio MCP server, the primary product. ESM (`"type": "module"`). - `packages/vscode-extension` (`semanticcodesearch`) — VSCode extension. Bundled with webpack; stubs out Node-only deps (Milvus gRPC, native AST) in `src/stubs/`. - `packages/chrome-extension` — browser build; overrides `@zilliz/milvus2-sdk-node` to `false` (no gRPC in browser). - `examples/basic-usage` — runnable library example. ## Commands ```bash pnpm install pnpm build # build all packages (examples built last) pnpm build:core # build a single package: also build:mcp, build:vscode pnpm dev # watch all; or dev:core / dev:mcp / dev:vscode pnpm lint # eslint across packages; lint:fix to autofix pnpm typecheck # tsc --noEmit across packages pnpm clean # rimraf dist in every package ``` Packages depend on `core` via `workspace:*`, so **rebuild core (`pnpm build:core`) before testing mcp/vscode against core changes** — they consume `core/dist`, not its source. ### Tests - **core** uses Jest + ts-jest. Test files are colocated as `*.test.ts` in `src/`. ```bash pnpm --filter @zilliz/claude-context-core test # all (runs in band) pnpm --filter @zilliz/claude-context-core test -- context.abort # by filename pnpm --filter @zilliz/claude-context-core test -- -t "pattern" # by test name ``` - **mcp** uses the Node built-in test runner via tsx (no Jest): ```bash pnpm --filter @zilliz/claude-context-mcp test # runs src/**/*.test.ts ``` ### Running the MCP server locally ```bash pnpm --filter @zilliz/claude-context-mcp start # tsx src/index.ts ``` Configuration is entirely via environment variables (see `.env.example` and `packages/mcp/src/config.ts`). Key vars: `EMBEDDING_PROVIDER` (OpenAI | VoyageAI | Gemini | Ollama | OpenRouter), provider API key, `EMBEDDING_MODEL`, `MILVUS_ADDRESS` and/or `MILVUS_TOKEN` (address can be auto-resolved from a Zilliz token), `CODE_CHUNKS_COLLECTION_NAME_OVERRIDE`. ## Architecture ### Core: the `Context` orchestrator (`packages/core/src/context.ts`) `Context` ties together three pluggable interfaces injected through its constructor config: - **Embedding** (`src/embedding/`) — `base-embedding.ts` interface with `OpenAIEmbedding`, `VoyageAIEmbedding`, `GeminiEmbedding`, `OllamaEmbedding` implementations. - **VectorDatabase** (`src/vectordb/`) — `MilvusVectorDatabase` (gRPC, Node-only) and `MilvusRestfulVectorDatabase` (HTTP, browser-safe). `zilliz-utils.ts` (`ClusterManager`) can provision a free Zilliz cluster and resolve an address from a token. - **Splitter** (`src/splitter/`) — `AstCodeSplitter` (tree-sitter, the default at 2500/300 chunk/overlap) which falls back to `LangChainCodeSplitter` for unsupported languages or parse failures. The public surface (`indexCodebase`, `reindexByChange`, `semanticSearch`, `clearIndex`, `hasIndex`) is re-exported from `src/index.ts`. Indexing reads files honoring ignore rules, splits them, embeds in batches, and upserts vectors. Collection name is derived from a hash of the absolute codebase path (overridable). Two error types carry control-flow meaning and should be preserved when touching the pipeline: - `IndexAbortError` — cooperative cancellation via `AbortSignal`. - `EmbeddingError` — always re-thrown to halt the whole pipeline, unlike per-file read/parse errors which are logged and skipped. This prevents silent partial indexing (Milvus getting zero vectors while the snapshot marks files done). ### Incremental sync (`packages/core/src/sync/`) `FileSynchronizer` builds a Merkle DAG (`merkle.ts`) of file hashes to compute `{added, removed, modified}` between runs. Snapshots persist to `~/.context/merkle/.json`. `reindexByChange` uses this so re-indexing only touches changed files. The MCP server can also run a background sync loop (`CLAUDE_CONTEXT_BACKGROUND_SYNC`, `CLAUDE_CONTEXT_SYNC_INTERVAL_MS`). ### Ignore patterns Layered: built-in `DEFAULT_IGNORE_PATTERNS` + config + env (`CUSTOM_IGNORE_PATTERNS`) + on-disk ignore files (`.gitignore`, `.contextignore`, `.xxxignore`, and a global `~/.context/.gitignore`). `utils/ignore-matcher.ts` implements matching including gitignore negation (`!`) semantics — covered by `context.ignore-patterns.test.ts`. ### Env resolution (`packages/core/src/utils/env-manager.ts`) `envManager.get(name)` resolves with priority `process.env` > `~/.context/.env` file. Use it instead of reading `process.env` directly so the `.env` file fallback keeps working. ### MCP server (`packages/mcp/src/`) - `index.ts` — entry point. **Critically, it redirects `console.log`/`console.warn` to stderr at the very top**, because stdout is reserved for the MCP JSON protocol. Never write non-protocol output to stdout in this package. - `handlers.ts` (`ToolHandlers`) — implements the tools: `index_codebase`, `search_code`, `clear_index`, `get_indexing_status`. - `snapshot.ts` (`SnapshotManager`) — tracks per-codebase indexing state across server restarts. - `sync.ts` (`SyncManager`) — drives incremental re-indexing. - `config.ts`, `embedding.ts` — build `Context` (embedding provider + Milvus) from environment variables. ## Conventions Commits follow Conventional Commits with these scopes: `core`, `vscode`, `mcp`, `examples`, `docs` (e.g. `fix(core): support gitignore negation patterns`). All code and comments are written in English. # GitHub Code Vector Search Chrome Extension A Chrome extension for indexing and semantically searching GitHub repository code, powered by Claude Context. > 📖 **New to Claude Context?** Check out the [main project README](../../README.md) for an overview and setup instructions. ## Features - 🔍 **Semantic Search**: Intelligent code search on GitHub repositories based on semantic understanding - 📁 **Repository Indexing**: Automatically index GitHub repositories and build semantic vector database - 🎯 **Context Search**: Search related code by selecting code snippets directly on GitHub - 🔧 **Multi-platform Support**: Support for OpenAI and VoyageAI as embedding providers - 💾 **Vector Storage**: Integrated with Milvus vector database for efficient storage and retrieval - 🌐 **GitHub Integration**: Seamlessly integrates with GitHub's interface - 📱 **Cross-Repository**: Search across multiple indexed repositories - ⚡ **Real-time**: Index and search code as you browse GitHub ## Installation ### From Chrome Web Store > **Coming Soon**: Extension will be available on Chrome Web Store ### Manual Installation (Development) 1. **Build the Extension**: ```bash cd packages/chrome-extension pnpm build ``` 2. **Load in Chrome**: - Open Chrome and navigate to `chrome://extensions/` - Enable "Developer mode" in the top right - Click "Load unpacked" and select the `dist` folder - The extension should now appear in your extensions list ## Quick Start 1. **Configure Settings**: - Click the extension icon in Chrome toolbar - Go to Options/Settings - Configure embedding provider and API Key - Set up Milvus connection details 2. **Index a Repository**: - Navigate to any GitHub repository - Click the "Index Repository" button that appears in the sidebar - Wait for indexing to complete 3. **Start Searching**: - Use the search box that appears on GitHub repository pages - Enter natural language queries like "function that handles authentication" - Click on results to navigate to the code ## Configuration The extension can be configured through the options page: - **Embedding Provider**: Choose between OpenAI or VoyageAI - **Embedding Model**: Select specific model (e.g., `text-embedding-3-small`) - **API Key**: Your embedding provider API key - **Milvus Settings**: Vector database connection details - **GitHub Token**: Personal access token for private repositories (optional) ## Permissions The extension requires the following permissions: - **Storage**: To save configuration and index metadata - **Scripting**: To inject search UI into GitHub pages - **Unlimited Storage**: For storing vector embeddings locally - **Host Permissions**: Access to GitHub.com and embedding provider APIs ## File Structure - `src/content.ts` - Main content script that injects UI into GitHub pages - `src/background.ts` - Background service worker for extension lifecycle - `src/options.ts` - Options page for configuration - `src/config/milvusConfig.ts` - Milvus connection configuration - `src/milvus/chromeMilvusAdapter.ts` - Browser-compatible Milvus adapter - `src/storage/indexedRepoManager.ts` - Repository indexing management - `src/stubs/` - Browser compatibility stubs for Node.js modules ## Development Features - **Browser Compatibility**: Node.js modules adapted for browser environment - **WebAssembly Support**: Optimized for browser performance - **Offline Capability**: Local storage for indexed repositories - **Progress Tracking**: Real-time indexing progress indicators - **Error Handling**: Graceful degradation and user feedback ## Usage Examples ### Basic Search 1. Navigate to a GitHub repository 2. Enter query: "error handling middleware" 3. Browse semantic search results ### Context Search 1. Select code snippet on GitHub 2. Right-click and choose "Search Similar Code" 3. View related code across the repository ### Multi-Repository Search 1. Index multiple repositories 2. Use the extension popup to search across all indexed repos 3. Filter results by repository or file type ## Contributing This Chrome extension is part of the Claude Context monorepo. Please see: - [Main Contributing Guide](../../CONTRIBUTING.md) - General contribution guidelines - [Chrome Extension Contributing](CONTRIBUTING.md) - Specific development guide for this extension ## Related Packages - **[@zilliz/claude-context-core](../core)** - Core indexing engine used by this extension - **[@zilliz/claude-context-vscode-extension](../vscode-extension)** - VSCode integration - **[@zilliz/claude-context-mcp](../mcp)** - MCP server integration ## Tech Stack - **TypeScript** - Type-safe development - **Chrome Extension Manifest V3** - Modern extension architecture - **Webpack** - Module bundling and optimization - **Claude Context Core** - Semantic search engine - **Milvus Vector Database** - Vector storage and retrieval - **OpenAI/VoyageAI Embeddings** - Text embedding generation ## Browser Support - Chrome 88+ - Chromium-based browsers (Edge, Brave, etc.) ## License MIT - See [LICENSE](../../LICENSE) for details # @zilliz/claude-context-core ![](../../assets/claude-context.png) The core indexing engine for Claude Context - a powerful tool for semantic search and analysis of codebases using vector embeddings and AI. [![npm version](https://img.shields.io/npm/v/@zilliz/claude-context-core.svg)](https://www.npmjs.com/package/@zilliz/claude-context-core) [![npm downloads](https://img.shields.io/npm/dm/@zilliz/claude-context-core.svg)](https://www.npmjs.com/package/@zilliz/claude-context-core) > 📖 **New to Claude Context?** Check out the [main project README](../../README.md) for an overview and quick start guide. ## Installation ```bash npm install @zilliz/claude-context-core ``` ### Prepare Environment Variables #### OpenAI API key See [OpenAI Documentation](https://platform.openai.com/docs/api-reference) for more details to get your API key. ```bash OPENAI_API_KEY=your-openai-api-key ``` #### Zilliz Cloud configuration Get a free Milvus vector database on Zilliz Cloud. Claude Context needs a vector database. You can [sign up](https://cloud.zilliz.com/signup?utm_source=github&utm_medium=referral&utm_campaign=2507-codecontext-readme) on Zilliz Cloud to get a free Serverless cluster. ![](../../assets/signup_and_create_cluster.jpeg) After creating your cluster, open your Zilliz Cloud console and copy both the **public endpoint** and your **API key**. These will be used as `your-zilliz-cloud-public-endpoint` and `your-zilliz-cloud-api-key` in the configuration examples. ![Zilliz Cloud Dashboard](../../assets/zilliz_cloud_dashboard.jpeg) Keep both values handy for the configuration steps below. If you need help creating your free vector database or finding these values, see the [Zilliz Cloud documentation](https://docs.zilliz.com/docs/create-cluster) for detailed instructions. ```bash MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint MILVUS_TOKEN=your-zilliz-cloud-api-key ``` > 💡 **Tip**: For easier configuration management across different usage scenarios, consider using [global environment variables](../../docs/getting-started/environment-variables.md). ## Quick Start ```typescript import { Context, OpenAIEmbedding, MilvusVectorDatabase } from '@zilliz/claude-context-core'; // Initialize embedding provider const embedding = new OpenAIEmbedding({ apiKey: process.env.OPENAI_API_KEY || 'your-openai-api-key', model: 'text-embedding-3-small' }); // Initialize vector database const vectorDatabase = new MilvusVectorDatabase({ address: process.env.MILVUS_ADDRESS || 'localhost:19530', token: process.env.MILVUS_TOKEN || '' }); // Create context instance const context = new Context({ embedding, vectorDatabase }); // Index a codebase const stats = await context.indexCodebase('./my-project', (progress) => { console.log(`${progress.phase} - ${progress.percentage}%`); }); console.log(`Indexed ${stats.indexedFiles} files with ${stats.totalChunks} chunks`); // Search the codebase const results = await context.semanticSearch( './my-project', 'function that handles user authentication', 5 ); results.forEach(result => { console.log(`${result.relativePath}:${result.startLine}-${result.endLine}`); console.log(`Score: ${result.score}`); console.log(result.content); }); ``` ## Features - **Multi-language Support**: Index TypeScript, JavaScript, Python, Java, C++, and many other programming languages - **Semantic Search**: Find code using natural language queries powered by AI embeddings - **Flexible Architecture**: Pluggable embedding providers and vector databases - **Smart Chunking**: Intelligent code splitting that preserves context and structure - **Batch Processing**: Efficient processing of large codebases with progress tracking - **Pattern Matching**: Built-in ignore patterns for common build artifacts and dependencies - **Incremental File Synchronization**: Efficient change detection using Merkle trees to only re-index modified files ## Embedding Providers - **OpenAI Embeddings** (`text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`) - **VoyageAI Embeddings** - High-quality embeddings optimized for code (`voyage-code-3`, `voyage-3.5`, etc.) - **Gemini Embeddings** - Google's embedding models (`gemini-embedding-001`, `gemini-embedding-2`) - **Ollama Embeddings** - Local embedding models via Ollama ## Vector Database Support - **Milvus/Zilliz Cloud** - High-performance vector database ## Code Splitters - **AST Code Splitter** - AST-based code splitting with automatic fallback (default) - **LangChain Code Splitter** - Character-based code chunking ## Configuration ### ContextConfig ```typescript interface ContextConfig { embedding?: Embedding; // Embedding provider vectorDatabase?: VectorDatabase; // Vector database instance (required) codeSplitter?: Splitter; // Code splitting strategy supportedExtensions?: string[]; // File extensions to index ignorePatterns?: string[]; // Patterns to ignore customExtensions?: string[]; // Custom extensions from MCP customIgnorePatterns?: string[]; // Custom ignore patterns from MCP } ``` ### Supported File Extensions (Default) ```typescript [ // Programming languages '.ts', '.tsx', '.js', '.jsx', '.py', '.java', '.cpp', '.c', '.h', '.hpp', '.cs', '.go', '.rs', '.php', '.rb', '.swift', '.kt', '.scala', '.m', '.mm', '.dart', '.sol', // Text and markup files '.md', '.markdown', '.ipynb' ] ``` ### Default Ignore Patterns - Build and dependency directories: `node_modules/**`, `dist/**`, `build/**`, `out/**`, `target/**` - Version control: `.git/**`, `.svn/**`, `.hg/**` - IDE files: `.vscode/**`, `.idea/**`, `*.swp`, `*.swo` - Cache directories: `.cache/**`, `__pycache__/**`, `.pytest_cache/**`, `coverage/**` - Minified files: `*.min.js`, `*.min.css`, `*.bundle.js`, `*.map` - Log and temp files: `logs/**`, `tmp/**`, `temp/**`, `*.log` - Environment files: `.env`, `.env.*`, `*.local` ## API Reference ### Context #### Methods - `indexCodebase(path, progressCallback?, forceReindex?)` - Index an entire codebase - `reindexByChange(path, progressCallback?)` - Incrementally re-index only changed files - `semanticSearch(path, query, topK?, threshold?, filterExpr?)` - Search indexed code semantically - `hasIndex(path)` - Check if codebase is already indexed - `clearIndex(path, progressCallback?)` - Remove index for a codebase - `updateIgnorePatterns(patterns)` - Update ignore patterns - `addCustomIgnorePatterns(patterns)` - Add custom ignore patterns - `addCustomExtensions(extensions)` - Add custom file extensions - `updateEmbedding(embedding)` - Switch embedding provider - `updateVectorDatabase(vectorDB)` - Switch vector database - `updateSplitter(splitter)` - Switch code splitter ### Search Results ```typescript interface SemanticSearchResult { content: string; // Code content relativePath: string; // File path relative to codebase root startLine: number; // Starting line number endLine: number; // Ending line number language: string; // Programming language score: number; // Similarity score (0-1) } ``` ## Examples ### Using VoyageAI Embeddings ```typescript import { Context, MilvusVectorDatabase, VoyageAIEmbedding } from '@zilliz/claude-context-core'; // Initialize with VoyageAI embedding provider const embedding = new VoyageAIEmbedding({ apiKey: process.env.VOYAGEAI_API_KEY || 'your-voyageai-api-key', model: 'voyage-code-3' }); const vectorDatabase = new MilvusVectorDatabase({ address: process.env.MILVUS_ADDRESS || 'localhost:19530', token: process.env.MILVUS_TOKEN || '' }); const context = new Context({ embedding, vectorDatabase }); ``` ### Custom File Filtering ```typescript const context = new Context({ embedding, vectorDatabase, supportedExtensions: ['.ts', '.js', '.py', '.java'], ignorePatterns: [ 'node_modules/**', 'dist/**', '*.spec.ts', '*.test.js' ] }); ``` ## File Synchronization Architecture Claude Context implements an intelligent file synchronization system that efficiently tracks and processes only the files that have changed since the last indexing operation. This dramatically improves performance when working with large codebases. ![File Synchronization Architecture](../../assets/file_synchronizer.png) ### How It Works The file synchronization system uses a **Merkle tree-based approach** combined with SHA-256 file hashing to detect changes: #### 1. File Hashing - Each file in the codebase is hashed using SHA-256 - File hashes are computed based on file content, not metadata - Hashes are stored with relative file paths for consistency across different environments #### 2. Merkle Tree Construction - All file hashes are organized into a Merkle tree structure - The tree provides a single root hash that represents the entire codebase state - Any change to any file will cause the root hash to change #### 3. Snapshot Management - File synchronization state is persisted to `~/.context/merkle/` directory - Each codebase gets a unique snapshot file based on its absolute path hash - Snapshots contain both file hashes and serialized Merkle tree data #### 4. Change Detection Process 1. **Quick Check**: Compare current Merkle root hash with stored snapshot 2. **Detailed Analysis**: If root hashes differ, perform file-by-file comparison 3. **Change Classification**: Categorize changes into three types: - **Added**: New files that didn't exist before - **Modified**: Existing files with changed content - **Removed**: Files that were deleted from the codebase #### 5. Incremental Updates - Only process files that have actually changed - Update vector database entries only for modified chunks - Remove entries for deleted files - Add entries for new files ## Contributing This package is part of the Claude Context monorepo. Please see: - [Main Contributing Guide](../../CONTRIBUTING.md) - General contribution guidelines - [Core Package Contributing](CONTRIBUTING.md) - Specific development guide for this package ## Related Packages - **[@claude-context/mcp](../mcp)** - MCP server that uses this core engine - **[VSCode Extension](../vscode-extension)** - VSCode extension built on this core ## License MIT - See [LICENSE](../../LICENSE) for details # @zilliz/claude-context-mcp ![](../../assets/claude-context.png) Model Context Protocol (MCP) integration for Claude Context - A powerful MCP server that enables AI assistants and agents to index and search codebases using semantic search. [![npm version](https://img.shields.io/npm/v/@zilliz/claude-context-mcp.svg)](https://www.npmjs.com/package/@zilliz/claude-context-mcp) [![npm downloads](https://img.shields.io/npm/dm/@zilliz/claude-context-mcp.svg)](https://www.npmjs.com/package/@zilliz/claude-context-mcp) > 📖 **New to Claude Context?** Check out the [main project README](../../README.md) for an overview and setup instructions. ## 🚀 Use Claude Context as MCP in Claude Code and others ![img](https://lh7-rt.googleusercontent.com/docsz/AD_4nXf2uIf2c5zowp-iOMOqsefHbY_EwNGiutkxtNXcZVJ8RI6SN9DsCcsc3amXIhOZx9VcKFJQLSAqM-2pjU9zoGs1r8GCTUL3JIsLpLUGAm1VQd5F2o5vpEajx2qrc77iXhBu1zWj?key=qYdFquJrLcfXCUndY-YRBQ) Model Context Protocol (MCP) allows you to integrate Claude Context with your favorite AI coding assistants, e.g. Claude Code. ## Quick Start ### Prerequisites Before using the MCP server, make sure you have: - API key for your chosen embedding provider (OpenAI, VoyageAI, Gemini, or Ollama setup) - Milvus vector database (local or cloud) > 💡 **Setup Help:** See the [main project setup guide](../../README.md#-quick-start) for detailed installation instructions. ### Prepare Environment Variables #### Embedding Provider Configuration Claude Context MCP supports multiple embedding providers. Choose the one that best fits your needs: > 📋 **Quick Reference**: For a complete list of environment variables and their descriptions, see the [Environment Variables Guide](../../docs/getting-started/environment-variables.md). ```bash # Supported providers: OpenAI, VoyageAI, Gemini, Ollama EMBEDDING_PROVIDER=OpenAI ```

1. OpenAI Configuration (Default)

OpenAI provides high-quality embeddings with excellent performance for code understanding. ```bash # Required: Your OpenAI API key OPENAI_API_KEY=sk-your-openai-api-key # Optional: Specify embedding model (default: text-embedding-3-small) EMBEDDING_MODEL=text-embedding-3-small # Optional: Custom API base URL (for Azure OpenAI or other compatible services) OPENAI_BASE_URL=https://api.openai.com/v1 ``` **Available Models:** See `getSupportedModels` in [`openai-embedding.ts`](https://github.com/zilliztech/claude-context/blob/master/packages/core/src/embedding/openai-embedding.ts) for the full list of supported models. **Getting API Key:** 1. Visit [OpenAI Platform](https://platform.openai.com/api-keys) 2. Sign in or create an account 3. Generate a new API key 4. Set up billing if needed

2. VoyageAI Configuration

VoyageAI offers specialized code embeddings optimized for programming languages. ```bash # Required: Your VoyageAI API key VOYAGEAI_API_KEY=pa-your-voyageai-api-key # Optional: Specify embedding model (default: voyage-code-3) EMBEDDING_MODEL=voyage-code-3 ``` **Available Models:** See `getSupportedModels` in [`voyageai-embedding.ts`](https://github.com/zilliztech/claude-context/blob/master/packages/core/src/embedding/voyageai-embedding.ts) for the full list of supported models. **Getting API Key:** 1. Visit [VoyageAI Console](https://dash.voyageai.com/) 2. Sign up for an account 3. Navigate to API Keys section 4. Create a new API key

3. Gemini Configuration

Google's Gemini provides competitive embeddings with good multilingual support. ```bash # Required: Your Gemini API key GEMINI_API_KEY=your-gemini-api-key # Optional: Specify embedding model (default: gemini-embedding-001; supports gemini-embedding-2) EMBEDDING_MODEL=gemini-embedding-001 # Optional: Custom API base URL (for custom endpoints) GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta ``` **Available Models:** See `getSupportedModels` in [`gemini-embedding.ts`](https://github.com/zilliztech/claude-context/blob/master/packages/core/src/embedding/gemini-embedding.ts) for the full list of supported models. **Getting API Key:** 1. Visit [Google AI Studio](https://aistudio.google.com/) 2. Sign in with your Google account 3. Go to "Get API key" section 4. Create a new API key

4. Ollama Configuration (Local/Self-hosted)

Ollama allows you to run embeddings locally without sending data to external services. ```bash # Required: Specify which Ollama model to use EMBEDDING_MODEL=nomic-embed-text # Optional: Specify Ollama host (default: http://127.0.0.1:11434) OLLAMA_HOST=http://127.0.0.1:11434 # Optional: Override embedding dimension to skip runtime dimension detection EMBEDDING_DIMENSION=768 ``` **Setup Instructions:** 1. Install Ollama from [ollama.com](https://ollama.com/) 2. Pull the embedding model: ```bash ollama pull nomic-embed-text ``` 3. Ensure Ollama is running: ```bash ollama serve ```

#### Get a free vector database on Zilliz Cloud Claude Context needs a vector database. You can [sign up](https://cloud.zilliz.com/signup?utm_source=github&utm_medium=referral&utm_campaign=2507-codecontext-readme) on Zilliz Cloud to get an API key. ![](../../assets/signup_and_get_apikey.png) Copy your Personal Key to replace `your-zilliz-cloud-api-key` in the configuration examples. ```bash MILVUS_TOKEN=your-zilliz-cloud-api-key # Optional: increase timeout for Milvus collection-limit pre-check on slow clusters (default: 15000) MILVUS_COLLECTION_LIMIT_CHECK_TIMEOUT_MS=30000 ``` #### Embedding Batch Size You can set the embedding batch size to optimize the performance of the MCP server, depending on your embedding model throughput. The default value is 100. ```bash EMBEDDING_BATCH_SIZE=512 ``` #### Custom File Processing (Optional) You can configure custom file extensions and ignore patterns globally via environment variables: ```bash # Additional file extensions to include beyond defaults CUSTOM_EXTENSIONS=.vue,.svelte,.astro,.twig # Additional ignore patterns to exclude files/directories CUSTOM_IGNORE_PATTERNS=temp/**,*.backup,private/**,uploads/** ``` These settings work in combination with tool parameters - patterns from both sources will be merged together. #### Custom Collection Name (Optional) Use this when you want a human-readable prefix on collection names in Milvus/Zilliz instead of the bare hash: ```bash # Creates code_chunks_my_project_ or hybrid_code_chunks_my_project_ CODE_CHUNKS_COLLECTION_NAME_OVERRIDE=my_project ``` The per-codebase `` suffix is preserved even when the override is set, so the same MCP server can still index multiple repos without collapsing them onto one collection. The override value is sanitized to letters, numbers, and underscores, and truncated to keep the full name within Milvus's 255-char limit. If you unset the variable later, Claude Context switches back to the plain `code_chunks_` naming. #### Trigger File Watcher (Optional) In addition to the periodic background sync, the MCP server watches a sentinel file at `~/.context/.sync-trigger` and starts an immediate re-index whenever the file is modified. This lets external tools (Claude Code `PostToolUse` hooks, editor save hooks, CI scripts, etc.) request a sync on demand instead of waiting for the next polling tick. ```bash # Default: watcher enabled. Set to false to disable filesystem watching entirely # (useful on read-only filesystems or sandboxed environments). CLAUDE_CONTEXT_TRIGGER_WATCHER=true ``` Example — Claude Code hook that re-indexes after every Edit/Write: ```json "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "touch ~/.context/.sync-trigger" } ]} ] } ``` Notes: - The trigger fires a debounced re-index (2 s window) so rapid touches collapse to a single sync. - Triggered syncs go through the same global cross-process lock as background sync, so when multiple MCP processes share `$HOME` only one process performs the work per trigger. - The trigger file's *contents* are ignored — only the modification event matters. #### Background Sync Configuration (Optional) By default, the MCP server runs startup + periodic background sync for compatibility with existing installations. The global cross-process sync lock ensures only one local MCP process performs a sync cycle at a time. You can tune or disable periodic polling with environment variables: ```bash # Default: true. Set to false to disable startup + periodic polling. CLAUDE_CONTEXT_BACKGROUND_SYNC=false # Optional: control how often sync runs (default: 300000 = 5 minutes) CLAUDE_CONTEXT_SYNC_INTERVAL_MS=60000 ``` For multi-instance local stdio setups, set `CLAUDE_CONTEXT_BACKGROUND_SYNC=false` and keep the trigger watcher enabled. That avoids idle polling while still allowing external tools to request immediate re-indexing by touching `~/.context/.sync-trigger`. ## Usage with MCP Clients

Claude Code

Use the command line interface to add the Claude Context MCP server: ```bash # Add the Claude Context MCP server claude mcp add claude-context -e OPENAI_API_KEY=your-openai-api-key -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint -e MILVUS_TOKEN=your-zilliz-cloud-api-key -- npx @zilliz/claude-context-mcp@latest ``` See the [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) for more details about MCP server management.

OpenAI Codex CLI

Codex CLI uses TOML configuration files: 1. Create or edit the `~/.codex/config.toml` file. 2. Add the following configuration: ```toml # IMPORTANT: the top-level key is `mcp_servers` rather than `mcpServers`. [mcp_servers.claude-context] command = "npx" args = ["@zilliz/claude-context-mcp@latest"] env = { "OPENAI_API_KEY" = "your-openai-api-key", "MILVUS_TOKEN" = "your-zilliz-cloud-api-key" } # Optional: override the default 10s startup timeout startup_timeout_ms = 20000 ``` 3. Save the file and restart Codex CLI to apply the changes.

Gemini CLI

Gemini CLI requires manual configuration through a JSON file: 1. Create or edit the `~/.gemini/settings.json` file. 2. Add the following configuration: ```json { "mcpServers": { "claude-context": { "command": "npx", "args": ["@zilliz/claude-context-mcp@latest"], "env": { "OPENAI_API_KEY": "your-openai-api-key", "MILVUS_TOKEN": "your-zilliz-cloud-api-key" } } } } ``` 3. Save the file and restart Gemini CLI to apply the changes.

Qwen Code

Create or edit the `~/.qwen/settings.json` file and add the following configuration: ```json { "mcpServers": { "claude-context": { "command": "npx", "args": ["@zilliz/claude-context-mcp@latest"], "env": { "OPENAI_API_KEY": "your-openai-api-key", "MILVUS_TOKEN": "your-zilliz-cloud-api-key" } } } } ```

Cursor

Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server` Pasting the following configuration into your Cursor `~/.cursor/mcp.json` file is the recommended approach. You may also install in a specific project by creating `.cursor/mcp.json` in your project folder. See [Cursor MCP docs](https://cursor.com/docs/context/mcp) for more info. **OpenAI Configuration (Default):** ```json { "mcpServers": { "claude-context": { "command": "npx", "args": ["-y", "@zilliz/claude-context-mcp@latest"], "env": { "EMBEDDING_PROVIDER": "OpenAI", "OPENAI_API_KEY": "your-openai-api-key", "MILVUS_TOKEN": "your-zilliz-cloud-api-key" } } } } ``` **VoyageAI Configuration:** ```json { "mcpServers": { "claude-context": { "command": "npx", "args": ["-y", "@zilliz/claude-context-mcp@latest"], "env": { "EMBEDDING_PROVIDER": "VoyageAI", "VOYAGEAI_API_KEY": "your-voyageai-api-key", "EMBEDDING_MODEL": "voyage-code-3", "MILVUS_TOKEN": "your-zilliz-cloud-api-key" } } } } ``` **Gemini Configuration:** ```json { "mcpServers": { "claude-context": { "command": "npx", "args": ["-y", "@zilliz/claude-context-mcp@latest"], "env": { "EMBEDDING_PROVIDER": "Gemini", "GEMINI_API_KEY": "your-gemini-api-key", "MILVUS_TOKEN": "your-zilliz-cloud-api-key" } } } } ``` **Ollama Configuration:** ```json { "mcpServers": { "claude-context": { "command": "npx", "args": ["-y", "@zilliz/claude-context-mcp@latest"], "env": { "EMBEDDING_PROVIDER": "Ollama", "EMBEDDING_MODEL": "nomic-embed-text", "OLLAMA_HOST": "http://127.0.0.1:11434", "EMBEDDING_DIMENSION": "768", "MILVUS_TOKEN": "your-zilliz-cloud-api-key" } } } } ```

Void

Go to: `Settings` -> `MCP` -> `Add MCP Server` Add the following configuration to your Void MCP settings: ```json { "mcpServers": { "code-context": { "command": "npx", "args": ["-y", "@zilliz/claude-context-mcp@latest"], "env": { "OPENAI_API_KEY": "your-openai-api-key", "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint", "MILVUS_TOKEN": "your-zilliz-cloud-api-key" } } } } ```

Claude Desktop

Add to your Claude Desktop configuration: ```json { "mcpServers": { "claude-context": { "command": "npx", "args": ["@zilliz/claude-context-mcp@latest"], "env": { "OPENAI_API_KEY": "your-openai-api-key", "MILVUS_TOKEN": "your-zilliz-cloud-api-key" } } } } ```

Windsurf

Windsurf supports MCP configuration through a JSON file. Add the following configuration to your Windsurf MCP settings: ```json { "mcpServers": { "claude-context": { "command": "npx", "args": ["-y", "@zilliz/claude-context-mcp@latest"], "env": { "OPENAI_API_KEY": "your-openai-api-key", "MILVUS_TOKEN": "your-zilliz-cloud-api-key" } } } } ```

VS Code

The Claude Context MCP server can be used with VS Code through MCP-compatible extensions. Add the following configuration to your VS Code MCP settings: ```json { "mcpServers": { "claude-context": { "command": "npx", "args": ["-y", "@zilliz/claude-context-mcp@latest"], "env": { "OPENAI_API_KEY": "your-openai-api-key", "MILVUS_TOKEN": "your-zilliz-cloud-api-key" } } } } ```

Cherry Studio

Cherry Studio allows for visual MCP server configuration through its settings interface. While it doesn't directly support manual JSON configuration, you can add a new server via the GUI: 1. Navigate to **Settings → MCP Servers → Add Server**. 2. Fill in the server details: - **Name**: `claude-context` - **Type**: `STDIO` - **Command**: `npx` - **Arguments**: `["-y", "@zilliz/claude-context-mcp@latest"]` - **Environment Variables**: - `OPENAI_API_KEY`: `your-openai-api-key` - `MILVUS_TOKEN`: `your-zilliz-cloud-api-key` 3. Save the configuration to activate the server.

Cline

Cline uses a JSON configuration file to manage MCP servers. To integrate the provided MCP server configuration: 1. Open Cline and click on the **MCP Servers** icon in the top navigation bar. 2. Select the **Installed** tab, then click **Advanced MCP Settings**. 3. In the `cline_mcp_settings.json` file, add the following configuration: ```json { "mcpServers": { "claude-context": { "command": "npx", "args": ["@zilliz/claude-context-mcp@latest"], "env": { "OPENAI_API_KEY": "your-openai-api-key", "MILVUS_TOKEN": "your-zilliz-cloud-api-key" } } } } ``` 4. Save the file.

Augment

To configure Claude Context MCP in Augment Code, you can use either the graphical interface or manual configuration. #### **A. Using the Augment Code UI** 1. Click the hamburger menu. 2. Select **Settings**. 3. Navigate to the **Tools** section. 4. Click the **+ Add MCP** button. 5. Enter the following command: ``` npx @zilliz/claude-context-mcp@latest ``` 6. Name the MCP: **Claude Context**. 7. Click the **Add** button. ------ #### **B. Manual Configuration** 1. Press Cmd/Ctrl Shift P or go to the hamburger menu in the Augment panel 2. Select Edit Settings 3. Under Advanced, click Edit in settings.json 4. Add the server configuration to the `mcpServers` array in the `augment.advanced` object ```json "augment.advanced": { "mcpServers": [ { "name": "claude-context", "command": "npx", "args": ["-y", "@zilliz/claude-context-mcp@latest"] } ] } ```

Roo Code

Roo Code utilizes a JSON configuration file for MCP servers: 1. Open Roo Code and navigate to **Settings → MCP Servers → Edit Global Config**. 2. In the `mcp_settings.json` file, add the following configuration: ```json { "mcpServers": { "claude-context": { "command": "npx", "args": ["@zilliz/claude-context-mcp@latest"], "env": { "OPENAI_API_KEY": "your-openai-api-key", "MILVUS_TOKEN": "your-zilliz-cloud-api-key" } } } } ``` 3. Save the file to activate the server.

Zencoder

Zencoder offers support for MCP tools and servers in both its JetBrains and VS Code plugin versions. 1. Go to the Zencoder menu (...) 2. From the dropdown menu, select `Tools` 3. Click on the `Add Custom MCP` 4. Add the name (i.e. `Claude Context` and server configuration from below, and make sure to hit the `Install` button ```json { "command": "npx", "args": ["@zilliz/claude-context-mcp@latest"], "env": { "OPENAI_API_KEY": "your-openai-api-key", "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint", "MILVUS_TOKEN": "your-zilliz-cloud-api-key" } } ``` 5. Save the server by hitting the `Install` button.

LangChain/LangGraph

For LangChain/LangGraph integration examples, see [this example](https://github.com/zilliztech/claude-context/blob/643796a0d30e706a2a0dff3d55621c9b5d831807/evaluation/retrieval/custom.py#L88).

Other MCP Clients

The server uses stdio transport and follows the standard MCP protocol. It can be integrated with any MCP-compatible client by running: ```bash npx @zilliz/claude-context-mcp@latest ```

## Features - 🔌 **MCP Protocol Compliance**: Full compatibility with MCP-enabled AI assistants and agents - 🔍 **Hybrid Code Search**: Natural language queries using advanced hybrid search (BM25 + dense vector) to find relevant code snippets - 📁 **Codebase Indexing**: Index entire codebases for fast hybrid search across millions of lines of code - 🔄 **Incremental Indexing**: Efficiently re-index only changed files using Merkle trees for auto-sync - 🧩 **Intelligent Code Chunking**: AST-based code analysis for syntax-aware chunking with automatic fallback - 🗄️ **Scalable**: Integrates with Zilliz Cloud for scalable vector search, no matter how large your codebase is - 🛠️ **Customizable**: Configure file extensions, ignore patterns, and embedding models - ⚡ **Real-time**: Interactive indexing and searching with progress feedback ## Available Tools ### 1. `index_codebase` Index a codebase directory for hybrid search (BM25 + dense vector). **Parameters:** - `path` (required): Absolute path to the codebase directory to index - `force` (optional): Force re-indexing even if already indexed (default: false) - `splitter` (optional): Code splitter to use - 'ast' for syntax-aware splitting with automatic fallback, 'langchain' for character-based splitting (default: "ast") - `customExtensions` (optional): Additional file extensions to include beyond defaults (e.g., ['.vue', '.svelte', '.astro']). Extensions should include the dot prefix or will be automatically added (default: []) - `ignorePatterns` (optional): Additional ignore patterns to exclude specific files/directories beyond defaults (e.g., ['static/**', '*.tmp', 'private/**']) (default: []) ### 2. `search_code` Search the indexed codebase using natural language queries with hybrid search (BM25 + dense vector). **Parameters:** - `path` (required): Absolute path to the codebase directory to search in - `query` (required): Natural language query to search for in the codebase - `limit` (optional): Maximum number of results to return (default: 10, max: 50) - `extensionFilter` (optional): List of file extensions to filter results (e.g., ['.ts', '.py']) (default: []) ### 3. `clear_index` Clear the search index for a specific codebase. **Parameters:** - `path` (required): Absolute path to the codebase directory to clear index for ### 4. `get_indexing_status` Get the current indexing status of a codebase. Shows progress percentage for actively indexing codebases and completion status for indexed codebases. **Parameters:** - `path` (required): Absolute path to the codebase directory to check status for **What the status output means:** - Progress is **phase-based**, not a direct file-count ratio. The MCP server reports coarse milestones for collection preparation, file scanning, and file processing / embedding work. - Because indexing runs in the background and progress is persisted periodically, percentages can jump quickly on large repositories or appear unchanged for a while during long embedding batches. - File and chunk statistics are written when an indexing run finishes successfully. During active indexing, `get_indexing_status` intentionally reports progress rather than live file/chunk totals. - Codebases are keyed by their **absolute path**. Indexing `/repo`, a symlinked path to the same repo, and a second clone will create separate tracked entries. - If a completed entry shows `0 files, 0 chunks`, that usually means the local snapshot metadata is stale rather than the vector database being queried live. Re-indexing, or clearing and re-indexing that exact absolute path, refreshes the stored stats. For a deeper explanation, see the [asynchronous indexing workflow guide](../../docs/dive-deep/asynchronous-indexing-workflow.md) and the [troubleshooting FAQ](../../docs/troubleshooting/faq.md). ## Contributing This package is part of the Claude Context monorepo. Please see: - [Main Contributing Guide](../../CONTRIBUTING.md) - General contribution guidelines - [MCP Package Contributing](CONTRIBUTING.md) - Specific development guide for this package ## Related Projects - **[@zilliz/claude-context-core](../core)** - Core indexing engine used by this MCP server - **[VSCode Extension](../vscode-extension)** - Alternative VSCode integration - [Model Context Protocol](https://modelcontextprotocol.io/) - Official MCP documentation ## License MIT - See [LICENSE](../../LICENSE) for details # Semantic Code Search VSCode Extension [![Visual Studio Marketplace](https://img.shields.io/visual-studio-marketplace/v/zilliz.semanticcodesearch?label=VS%20Code%20Marketplace&logo=visual-studio-code)](https://marketplace.visualstudio.com/items?itemName=zilliz.semanticcodesearch) A code indexing and semantic search VSCode extension powered by [Claude Context](https://github.com/zilliztech/claude-context). > 📖 **New to Claude Context?** Check out the [main project README](https://github.com/zilliztech/claude-context/blob/master/README.md) for an overview and setup instructions. ![img](https://lh7-rt.googleusercontent.com/docsz/AD_4nXdtCtT9Qi6o5mGVoxzX50r8Nb6zDFcjvTQR7WZ-xMbEsHEPPhSYAFVJ7q4-rETzxJ8wy1cyZmU8CmtpNhAU8PGOqVnE2kc2HCn1etDg97Qsh7m89kBjG4ZT7XBgO4Dp7BfFZx7eow?key=qYdFquJrLcfXCUndY-YRBQ) ## Features - 🔍 **Semantic Search**: Intelligent code search based on semantic understanding, not just keyword matching - 📁 **Codebase Indexing**: Automatically index entire codebase and build semantic vector database - 🎯 **Context Search**: Search related code by selecting code snippets - 🔧 **Multi-platform Support**: Support for OpenAI, VoyageAI, Gemini, and Ollama as embedding providers - 💾 **Vector Storage**: Integrated with Milvus vector database for efficient storage and retrieval ## Requirements - **VSCode Version**: 1.74.0 or higher ## Installation ### From VS Code Marketplace 1. **Direct Link**: [Install from VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=zilliz.semanticcodesearch) 2. **Manual Search**: - Open Extensions view in VSCode (Ctrl+Shift+X or Cmd+Shift+X on Mac) - Search for "Semantic Code Search" - Click Install ## Quick Start ### Configuration The first time you open Claude Context, you need to click on Settings icon to configure the relevant options. #### Embedding Configuration Configure your embedding provider to convert code into semantic vectors. **OpenAI Configuration:** - `Embedding Provider`: Select "OpenAI" from the dropdown - `Model name`: Choose the embedding model (e.g., `text-embedding-3-small`, `text-embedding-3-large`) - `OpenAI API key`: Your OpenAI API key for authentication - `Custom API endpoint URL`: Optional custom endpoint (defaults to `https://api.openai.com/v1`) **Other Supported Providers:** - **Gemini**: Google's state-of-the-art embedding model with Matryoshka representation learning - **VoyageAI**: Alternative embedding provider with competitive performance - **Ollama**: For local embedding models #### Code Splitter Configuration Configure how your code is split into chunks for indexing. **Splitter Settings:** - `Splitter Type`: Choose between "AST Splitter" (syntax-aware) or "LangChain Splitter" (character-based) - `Chunk Size`: Maximum size of each code chunk (default: 1000 characters) - `Chunk Overlap`: Number of overlapping characters between chunks (default: 200 characters) > **Recommendation**: Use AST Splitter for better semantic understanding of code structure. #### Zilliz Cloud configuration Get a free Milvus vector database on Zilliz Cloud. Claude Context needs a vector database. You can [sign up](https://cloud.zilliz.com/signup?utm_source=github&utm_medium=referral&utm_campaign=2507-codecontext-readme) on Zilliz Cloud to get a free Serverless cluster. ![](https://raw.githubusercontent.com/zilliztech/claude-context/master/assets/signup_and_create_cluster.jpeg) After creating your cluster, open your Zilliz Cloud console and copy both the **public endpoint** and your **API key**. These will be used as `your-zilliz-cloud-public-endpoint` and `your-zilliz-cloud-api-key` in the configuration examples. ![Zilliz Cloud Dashboard](https://raw.githubusercontent.com/zilliztech/claude-context/master/assets/zilliz_cloud_dashboard.jpeg) Keep both values handy for the configuration steps below. If you need help creating your free vector database or finding these values, see the [Zilliz Cloud documentation](https://docs.zilliz.com/docs/create-cluster) for detailed instructions. ```bash MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint MILVUS_TOKEN=your-zilliz-cloud-api-key ``` ### Usage 1. **Set the Configuration**: - Open VSCode Settings (Ctrl+, or Cmd+, on Mac) - Search for "Semantic Code Search" - Set the configuration 2. **Index Codebase**: - Open Command Palette (Ctrl+Shift+P or Cmd+Shift+P on Mac) - Run "Semantic Code Search: Index Codebase" 3. **Start Searching**: - Open Semantic Code Search panel in sidebar - Enter search query or right-click on selected code to search ## Commands - `Semantic Code Search: Semantic Search` - Perform semantic search - `Semantic Code Search: Index Codebase` - Index current codebase - `Semantic Code Search: Clear Index` - Clear the index ## Configuration - `semanticCodeSearch.embeddingProvider.provider` - Embedding provider (OpenAI/VoyageAI/Gemini/Ollama) - `semanticCodeSearch.embeddingProvider.model` - Embedding model to use - `semanticCodeSearch.embeddingProvider.apiKey` - API key for embedding provider - `semanticCodeSearch.embeddingProvider.baseURL` - Custom API endpoint URL (optional, for OpenAI and Gemini) - `semanticCodeSearch.embeddingProvider.outputDimensionality` - Output dimension for Gemini (supports 3072, 1536, 768, 256) - `semanticCodeSearch.milvus.address` - Milvus server address ## Contributing This VSCode extension is part of the Claude Context monorepo. Please see: - [Main Contributing Guide](https://github.com/zilliztech/claude-context/blob/master/CONTRIBUTING.md) - General contribution guidelines - [VSCode Extension Contributing](https://github.com/zilliztech/claude-context/blob/master/packages/vscode-extension/CONTRIBUTING.md) - Specific development guide for this extension ## Related Packages - **[@zilliz/claude-context-core](https://github.com/zilliztech/claude-context/tree/master/packages/core)** - Core indexing engine used by this extension - **[@zilliz/claude-context-mcp](https://github.com/zilliztech/claude-context/tree/master/packages/mcp)** - Alternative MCP server integration ## Tech Stack - TypeScript - VSCode Extension API - Milvus Vector Database - OpenAI/VoyageAI Embeddings ## License MIT - See [LICENSE](https://github.com/zilliztech/claude-context/blob/master/LICENSE) for details

AI Agent Protocol & Instructions

Explore Related Technologies & Topics