🔍 Code Context

Code Context is an MCP plugin that brings semantic code search to Claude Code, Gemini CLI, or any AI coding agent. By indexing your entire codebase, it gives your assistant deep context awareness for better code generation.

AI coding assistants like Claude Code are limited by their context window and can only see part of your codebase. Code Context uses semantic search with a scalable vector database Zilliz Cloud so your assistant can find and understand relevant code from your whole project using natural language, not just keywords. This gives your AI assistant real context awareness.

---

🚀 Use Code Context as MCP in Claude Code and others

Model Context Protocol (MCP) allows you to integrate Code Context with your favorite AI coding assistants, e.g. Claude Code.

Prerequisites

Get a free vector database on Zilliz Cloud

Code Context needs a vector database. You can sign up on Zilliz Cloud to get a free Serverless cluster.

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.

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 for detailed instructions.

Get OpenAI API Key for embedding model

You need an OpenAI API key for the embedding model. You can get one by signing up at OpenAI.

Your API key will look like this: it always starts with sk-.
Copy your key and use it in the configuration examples below as your-openai-api-key.

Configure MCP for your AI Assistant

Claude Code

Use the command line interface to add the Code Context MCP server:

# Add the Code Context MCP server
claude mcp add code-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/code-context-mcp@latest

See the Claude Code MCP documentation for more details about MCP server management.

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:

{
  "mcpServers": {
    "code-context": {
      "command": "npx",
      "args": ["@zilliz/code-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"
      }
    }
  }
}

3. Save the file and restart Gemini CLI to apply the changes.

Other MCP Client Configurations (Cursor, Windsurf, etc.)

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 for more info.

{
  "mcpServers": {
    "code-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/code-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:

{
  "mcpServers": {
    "code-context": {
      "command": "npx",
      "args": ["@zilliz/code-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"
      }
    }
  }
}

Windsurf

Windsurf supports MCP configuration through a JSON file. Add the following configuration to your Windsurf MCP settings:

{
  "mcpServers": {
    "code-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/code-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"
      }
    }
  }
}

VS Code

The Code Context MCP server can be used with VS Code through MCP-compatible extensions. Add the following configuration to your VS Code MCP settings:

{
  "mcpServers": {
    "code-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/code-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"
      }
    }
  }
}

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: code-context
   • Type: STDIO
   • Command: npx
   • Arguments: ["@zilliz/code-context-mcp@latest"]
   • Environment Variables:
     • OPENAI_API_KEY: your-openai-api-key
     • MILVUS_ADDRESS: your-zilliz-cloud-public-endpoint
     • 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:

{
  "mcpServers": {
    "code-context": {
      "command": "npx",
      "args": ["@zilliz/code-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"
      }
    }
  }
}

4. Save the file.

Augment

To configure Code 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/code-context-mcp@latest
   

6. Name the MCP: Code 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

"augment.advanced": { 
  "mcpServers": [ 
    { 
      "name": "code-context", 
      "command": "npx", 
      "args": ["-y", "@zilliz/code-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"
      }
    }
  ]
}

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:

{
  "mcpServers": {
    "code-context": {
      "command": "npx",
      "args": ["@zilliz/code-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"
      }
    }
  }
}

3. Save the file to activate the server.

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:

npx @zilliz/code-context-mcp@latest

---

✨ Features

• 🔍 Semantic Code Search: Ask questions like "find functions that handle user authentication" and get relevant, context-rich code instantly.
• 🧠 Context-Aware Discovery: Understand how different parts of your codebase relate, even across millions of lines.
• 🤖 AI-Assisted Programming: Generate, refactor, or extend code using natural language prompts.
• ⚡ Incremental File Synchronization: Efficiently re-index only changed files using Merkle trees.
• 🧩 Smart Chunking: AST-based code splitting for context-preserving search and generation.
• 🔌 Pluggable Embedding Providers: Support for OpenAI, VoyageAI, Ollama, and more.
• 🗄️ Vector Storage: Integrates with Zilliz Cloud for scalable vector search, no matter how large your codebase is.
• 🛠️ Customizable: Configure file extensions, ignore patterns, and embedding models.

---

🏗️ Architecture

Code Context is a monorepo containing three main packages:

Core Components

• @zilliz/code-context-core: Core indexing engine with embedding and vector database integration
• VSCode Extension: Semantic Code Search extension for Visual Studio Code
• @zilliz/code-context-mcp: Model Context Protocol server for AI agent integration

Supported Technologies

• Embedding Providers: OpenAI, VoyageAI, Ollama
• Vector Databases: Milvus or Zilliz Cloud(fully managed vector database as a service)
• Code Splitters: AST-based splitter (with automatic fallback), LangChain character-based splitter
• Languages: TypeScript, JavaScript, Python, Java, C++, C#, Go, Rust, PHP, Ruby, Swift, Kotlin, Scala, Markdown
• Development Tools: VSCode, Model Context Protocol

---

📦 Other Ways to Use Code Context

While MCP is the recommended way to use Code Context with AI assistants, you can also use it directly or through the VSCode extension.

Core Package Usage

The @zilliz/code-context-core package provides the fundamental functionality for code indexing and semantic search.

import { CodeContext, MilvusVectorDatabase, OpenAIEmbedding } from '@zilliz/code-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 || 'your-zilliz-cloud-public-endpoint',
    token: process.env.MILVUS_TOKEN || 'your-zilliz-cloud-api-key'
});

// Create context instance
const context = new CodeContext({
    embedding,
    vectorDatabase
});

// Index your codebase with progress tracking
const stats = await context.indexCodebase('./your-project', (progress) => {
    console.log(`${progress.phase} - ${progress.percentage}%`);
});
console.log(`Indexed ${stats.indexedFiles} files, ${stats.totalChunks} chunks`);

// Perform semantic search
const results = await context.semanticSearch('./your-project', 'vector database operations', 5);
results.forEach(result => {
    console.log(`File: ${result.relativePath}:${result.startLine}-${result.endLine}`);
    console.log(`Score: ${(result.score * 100).toFixed(2)}%`);
    console.log(`Content: ${result.content.substring(0, 100)}...`);
});

VSCode Extension

Integrates Code Context directly into your IDE. Provides an intuitive interface for semantic code search and navigation.

1. Direct Link: Install from VS Code Marketplace
2. Manual Search:
   • Open Extensions view in VSCode (Ctrl+Shift+X or Cmd+Shift+X on Mac)
   • Search for "Semantic Code Search"
   • Click Install

---

🛠️ Development

Setup Development Environment

# Clone repository
git clone https://github.com/zilliztech/code-context.git
cd code-context

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Start development mode
pnpm dev

Building

# Build all packages
pnpm build

# Build specific package
pnpm build:core
pnpm build:vscode
pnpm build:mcp

Running Examples

# Development with file watching
cd examples/basic-usage
pnpm dev

Supported File Extensions

By default, Code Context supports:

• Programming languages: .ts, .tsx, .js, .jsx, .py, .java, .cpp, .c, .h, .hpp, .cs, .go, .rs, .php, .rb, .swift, .kt, .scala, .m, .mm
• Documentation: .md, .markdown

Ignore Patterns

Common directories and files are automatically ignored:

• node_modules/**, dist/**, build/**
• .git/**, .vscode/**, .idea/**
• *.log, *.min.js, *.map

---

📖 Examples

Check the /examples directory for complete usage examples:

• Basic Usage: Simple indexing and search example

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.

Package-specific contributing guides:

• Core Package Contributing
• MCP Server Contributing
• VSCode Extension Contributing

---

🗺️ Roadmap

• AST-based code analysis for improved understanding
• Support for additional embedding providers
• Agent-based interactive search mode
• Enhanced code chunking strategies
• Search result ranking optimization
• Robust Chrome Extension

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🔗 Links

• GitHub Repository
• VSCode Marketplace
• Milvus Documentation
• Zilliz Cloud