Quick Start Guide
Relevant source files
The following files were used as context for generating this wiki page:
Claude Context is a comprehensive code indexing and semantic search system designed to provide AI agents with deep context from large codebases. It leverages vector embeddings and vector databases (primarily Milvus/Zilliz Cloud) to enable natural language queries across millions of lines of code, significantly reducing token consumption compared to loading full directories into an LLM context.
This guide provides the necessary steps to set up the environment, configure the required services (Embedding providers and Vector Databases), and integrate Claude Context into various workflows, including Claude Code, VS Code, and custom applications via the Model Context Protocol (MCP).
Sources: README.md:16-25, packages/core/README.md:3-8
Prerequisites
Before starting, ensure your environment meets the following requirements:
- Node.js: Version >= 20.0.0 and < 24.0.0.
- Vector Database: Access to a Milvus instance or a Zilliz Cloud account (Cloud API key and Public Endpoint required).
- Embedding Provider: An API key from a supported provider (OpenAI, VoyageAI, Gemini, or a local Ollama setup).
Sources: README.md:73-77, packages/mcp/README.md:20-25
Environment Configuration
Claude Context relies on environment variables for authentication and service discovery.
Vector Database Setup (Zilliz Cloud)
The system requires a Milvus-compatible database to store and retrieve code embeddings. Users can sign up for a free Serverless cluster on Zilliz Cloud.
| Variable | Description | Source |
|---|---|---|
MILVUS_ADDRESS | The public endpoint of your Zilliz Cloud cluster or local Milvus instance. | packages/core/README.md:36 |
MILVUS_TOKEN | The API key or personal key for authentication. | packages/core/README.md:37 |
Sources: README.md:46-52, packages/core/README.md:23-37
Embedding Providers
Multiple providers are supported to generate the vector representations of code segments.
| Provider | Variable | Default Model |
|---|---|---|
| OpenAI | OPENAI_API_KEY | text-embedding-3-small |
| VoyageAI | VOYAGEAI_API_KEY | voyage-code-3 |
| Gemini | GEMINI_API_KEY | gemini-embedding-001 |
| Ollama | OLLAMA_HOST | nomic-embed-text |
Sources: packages/mcp/README.md:36-120, packages/mcp/src/config.ts:57-73
MCP Server Setup
The Model Context Protocol (MCP) server allows AI agents like Claude Code to interact with the indexing engine.
Integration with Claude Code
To add the Claude Context MCP server to Claude Code, use the following CLI command:
claude mcp add claude-context \
-e OPENAI_API_KEY=sk-your-openai-api-key \
-e MILVUS_TOKEN=your-zilliz-cloud-api-key \
-- npx @zilliz/claude-context-mcp@latest
Sources: README.md:79-85, packages/mcp/README.md:139-147
Data Flow Architecture
The following diagram illustrates how an AI Agent utilizes the MCP server to retrieve codebase context:
This diagram shows the flow of a semantic search request from the user interface through the core logic to the external service providers.
Sources: README.md:255-263, packages/mcp/README.md:315-325
Usage Workflows
Manual Indexing and Search
Once the MCP server is configured in a tool like Claude Code, you can manage the index using natural language:
- Index Codebase: "Index this codebase" (Uses
index_codebasetool). - Check Status: "Check the indexing status" (Uses
get_indexing_statustool). - Semantic Search: "Find functions that handle user authentication" (Uses
search_codetool).
Sources: README.md:225-242, packages/mcp/README.md:315-345
Programmatic Usage (@zilliz/claude-context-core)
Developers can integrate the core engine directly into TypeScript applications.
import { Context, MilvusVectorDatabase, OpenAIEmbedding } from '@zilliz/claude-context-core';
const embedding = new OpenAIEmbedding({
apiKey: process.env.OPENAI_API_KEY,
model: 'text-embedding-3-small'
});
const vectorDatabase = new MilvusVectorDatabase({
address: process.env.MILVUS_ADDRESS,
token: process.env.MILVUS_TOKEN
});
const context = new Context({ embedding, vectorDatabase });
// Indexing
const stats = await context.indexCodebase('./path-to-repo');
// Searching
const results = await context.semanticSearch('./path-to-repo', 'authentication logic', 5);
Sources: packages/core/README.md:46-88, examples/basic-usage/index.ts:41-71
Key System Tools
The MCP server exposes several tools for agent interaction:
| Tool | Purpose | Key Parameters |
|---|---|---|
index_codebase | Creates hybrid search index (BM25 + Vector). | path (req), force, splitter, ignorePatterns |
search_code | Executes natural language queries. | path (req), query (req), limit, extensionFilter |
clear_index | Removes existing index for a path. | path (req) |
get_indexing_status | Returns progress percentage. | path (req) |
Sources: README.md:267-281, packages/mcp/README.md:315-353
Conclusion
Claude Context provides a robust infrastructure for bringing codebase intelligence to AI workflows. By utilizing efficient vector storage and smart AST-based chunking, it enables high-accuracy retrieval while minimizing operational costs. Users can get started quickly via the MCP server integration or build custom solutions using the core SDK.