MCP Tools Reference
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Model Context Protocol (MCP) server within the Claude Context project enables AI assistants to perform semantic code search and indexing across entire codebases. By providing a standardized interface, the MCP server allows tools like Claude Code, Cursor, and other coding agents to access deep codebase context through vector-based retrieval rather than loading full directories into the LLM context.
The server operates using stdio transport and implements four primary tools: index_codebase, search_code, clear_index, and get_indexing_status. These tools bridge the AI agent with the @zilliz/claude-context-core engine, which handles the complexities of AST-based code chunking, Merkle tree-based incremental indexing, and Milvus vector database integration.
Sources: README.md:14-20, packages/mcp/README.md:383-393, packages/mcp/src/index.ts:38-60
Architecture and Data Flow
The MCP server acts as a middleware layer between the AI Client (e.g., Claude Desktop) and the Core Indexing Engine. It translates incoming MCP tool requests into operations executed by the Context class from the @zilliz/claude-context-core package.
System Interaction Flow
The following diagram illustrates how a request from a user through an MCP client triggers the indexing or search logic.
The MCP server uses StdioServerTransport for communication, ensuring that standard output is reserved strictly for MCP JSON protocol messages while logs are redirected to standard error.
Sources: packages/mcp/src/index.ts:5-15, packages/mcp/src/index.ts:246-258, packages/core/README.md:143-149
Core Components
| Component | Description |
|---|---|
ContextMcpServer | The main class responsible for setting up the MCP server, defining tools, and handling tool execution. |
Context | The core engine class that coordinates indexing, search, and configuration. |
SnapshotManager | Manages codebase state snapshots for tracking changes. |
SyncManager | Handles background synchronization and incremental updates. |
ToolHandlers | Contains the logic for processing specific tool arguments and returning results. |
Sources: packages/mcp/src/index.ts:38-60, packages/mcp/CONTRIBUTING.md:46-52
Tool Reference
1. index_codebase
Indexes a codebase directory for hybrid search (BM25 + dense vector). It supports both full and incremental indexing.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | Yes | Absolute path to the codebase directory. |
force | boolean | No | Force re-indexing even if already indexed (default: false). |
splitter | string | No | 'ast' (syntax-aware) or 'langchain' (character-based). Default: 'ast'. |
customExtensions | array | No | Additional extensions to include (e.g., ['.vue']). |
ignorePatterns | array | No | Additional glob patterns to exclude files. |
Sources: packages/mcp/src/index.ts:109-152, packages/mcp/README.md:401-412
2. search_code
Performs semantic search using natural language queries. It requires the codebase to be indexed first.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | Yes | Absolute path to the indexed codebase. |
query | string | Yes | Natural language search query. |
limit | number | No | Max results (default: 10, max: 50). |
extensionFilter | array | No | List of extensions to filter results (e.g., ['.ts']). |
Sources: packages/mcp/src/index.ts:162-192, packages/mcp/README.md:414-423
3. clear_index & get_indexing_status
clear_index: Removes the search index for a specific codebase path.get_indexing_status: Returns the current progress (percentage) or completion status of an indexing operation.
Sources: packages/mcp/src/index.ts:194-222, packages/mcp/README.md:425-438
Indexing Sequence
The indexing process involves scanning the filesystem, checking for changes via Merkle trees, and generating embeddings for code chunks.
Configuration and Environment
The MCP server's behavior is heavily influenced by environment variables, which determine the embedding provider and vector database connection.
Environment Variables
# Vector Database
MILVUS_ADDRESS=your-zilliz-endpoint
MILVUS_TOKEN=your-api-token
# Embedding Provider
EMBEDDING_PROVIDER=OpenAI # Options: OpenAI, VoyageAI, Gemini, Ollama
OPENAI_API_KEY=sk-...
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_BATCH_SIZE=100
Sources: packages/mcp/README.md:52-105, packages/mcp/CONTRIBUTING.md:106-120
Implementation Detail: Console Redirection
The MCP server implements a critical safety measure by redirecting console.log and console.warn to process.stderr. This prevents non-protocol messages from polluting the stdout stream, which would break the JSON-RPC communication with MCP clients.
// packages/mcp/src/index.ts:5-13
const originalConsoleLog = console.log;
const originalConsoleWarn = console.warn;
console.log = (...args: any[]) => {
process.stderr.write('[LOG] ' + args.join(' ') + '\n');
};
console.warn = (...args: any[]) => {
process.stderr.write('[WARN] ' + args.join(' ') + '\n');
};
Sources: packages/mcp/src/index.ts:5-13
Conclusion
The MCP Tools Reference defines the primary interface for AI agents to interact with a codebase's semantic representation. Through the four core tools, the server manages the lifecycle of a code index—from initial creation and incremental updates to natural language querying—while ensuring architectural compatibility with the Model Context Protocol standards.