Contributing to the MCP Server
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) server is a core component of the Claude Context ecosystem, designed to enable AI assistants and agents (like Claude Code, Cursor, or Claude Desktop) to perform semantic searches and indexing on local codebases. It acts as a bridge between the @zilliz/claude-context-core engine and the MCP ecosystem, utilizing stdio transport for communication.
Contributing to this module involves enhancing its ability to handle codebase indexing, semantic search, and synchronization while maintaining strict compliance with the MCP specification. Developers focus on the packages/mcp directory, which contains the server implementation, configuration management, and tool handlers.
Sources: packages/mcp/README.md:1-10, packages/mcp/src/index.ts:30-60
Architecture Overview
The MCP server is built using the @modelcontextprotocol/sdk. It initializes a core Context object from the @zilliz/claude-context-core package, which manages the embedding provider and the Milvus vector database connection. The server operates as a long-running process that listens for JSON-RPC requests over standard input/output (stdio).
System Components and Data Flow
The following diagram illustrates the relationship between the MCP Server, the Core engine, and external AI clients.
The server redirects all non-protocol logs to stderr to avoid corrupting the MCP JSON-RPC stream on stdout.
Sources: packages/mcp/src/index.ts:4-15, packages/mcp/src/index.ts:44-70, packages/mcp/CONTRIBUTING.md:46-50
Development Workflow
Contributors must follow the monorepo standards. The MCP server requires Node.js (>=20.0.0 and <24.0.0) and pnpm.
Quick Commands for Development
| Action | Command |
|---|---|
| Build MCP Server | pnpm build:mcp |
| Watch Mode (Dev) | pnpm dev:mcp |
| Start Server | pnpm start |
| Run with Env | pnpm start:with-env |
Sources: packages/mcp/CONTRIBUTING.md:14-25, packages/mcp/package.json:11-20
Making Changes
- Create a feature branch.
- Edit
packages/mcp/src/index.tsfor main server logic. - Update
packages/mcp/src/config.tsfor new environment variables or settings. - Verify changes using an MCP client like Claude Desktop or Cursor.
Sources: packages/mcp/CONTRIBUTING.md:38-44
Tool Implementation
The MCP server exposes four primary tools to AI agents. These are defined in src/index.ts using this.server.setRequestHandler(ListToolsRequestSchema, ...) and handled in CallToolRequestSchema.
Available Tools Summary
| Tool Name | Purpose | Required Parameters |
|---|---|---|
index_codebase | Indexes a directory for hybrid search | path |
search_code | Semantic search using natural language | path, query |
clear_index | Removes search index for a path | path |
get_indexing_status | Returns progress of active indexing | path |
Sources: packages/mcp/src/index.ts:98-190, packages/mcp/README.md:148-185
Indexing Flow
When index_codebase is called, the server utilizes the core engine's AST or LangChain splitters to process code.
Configuration and Environment Variables
Configuration is handled in src/config.ts. The server supports multiple embedding providers and vector database configurations via environment variables.
Environment Variable Reference
| Variable | Description | Default / Options |
|---|---|---|
EMBEDDING_PROVIDER | Provider for embeddings | OpenAI (Default), VoyageAI, Gemini, Ollama |
EMBEDDING_MODEL | Specific model to use | e.g., text-embedding-3-small |
MILVUS_TOKEN | Zilliz Cloud API Key | Required for cloud storage |
MILVUS_ADDRESS | Vector DB endpoint | Auto-resolved from token if possible |
EMBEDDING_BATCH_SIZE | Chunks per batch | 100 |
Sources: packages/mcp/README.md:46-80, packages/mcp/src/config.ts:108-140
Coding Guidelines
- TypeScript Usage: Always use TypeScript for type safety. The server uses
zodfor input validation. - Error Handling: Handle errors gracefully and return valid MCP error responses.
- Logging: Never use
console.logfor debugging info that should go to the user; use the redirected loggers that output tostderr. - Merkle Sync: The server uses
SyncManagerandSnapshotManagerto perform incremental indexing. Any changes to how files are detected must maintain compatibility with these managers.
Sources: packages/mcp/src/index.ts:4-15, packages/mcp/CONTRIBUTING.md:46-60
Conclusion
Contributing to the MCP server is critical for maintaining the integration between AI assistants and the Claude Context core. By following the standardized MCP protocol and utilizing the modular structure of handlers, configuration, and sync managers, contributors ensure a reliable and performant semantic search experience for users.
Sources: packages/mcp/README.md:195-205