Contributing to @zilliz/claude-context-mcp

April 24, 2026 · View on GitHub

Thanks for your interest in contributing to the Claude Context MCP server!

📖 First time contributing? Please read the main contributing guide first for general setup and workflow.

MCP Server Development

This guide covers development specific to the MCP server.

Quick Commands

# Build MCP server
pnpm build:mcp

# Watch mode for development
pnpm dev:mcp

# Start server
pnpm start

# Run with environment variables
pnpm start:with-env

Required Environment Variables

See README.md for required environment variables.

Running the MCP Server

  1. Build the server: 
    pnpm build
  2. Run with MCP client or directly: 
    pnpm start
  3. Use the tools:
    • index_codebase - Index a sample codebase with optional custom ignore patterns
    • search_code - Search for code snippets
    • clear_index - Clear the index

Making Changes

  1. Create a new branch for your feature/fix
  2. Edit src/index.ts - Main MCP server implementation
  3. Verify with MCP clients (Claude Desktop, etc.)
  4. Follow commit guidelines in the main guide

MCP Protocol

  • Follow MCP specification
  • Use stdio transport for compatibility
  • Handle errors gracefully with proper MCP responses
  • Redirect logs to stderr (not stdout)

Tool Parameters

index_codebase

  • path (required): Path to the codebase directory
  • force (optional): Force re-indexing even if already indexed (default: false)
  • splitter (optional): Code splitter type - 'ast' or 'langchain' (default: 'ast')
  • ignorePatterns (optional): Additional ignore patterns to add to defaults (default: [])
    • Examples: ["static/**", "*.tmp", "private/**", "docs/generated/**"]
    • Merged with default patterns (node_modules, .git, etc.)

search_code

  • path (required): Path to the indexed codebase
  • query (required): Natural language search query
  • limit (optional): Maximum number of results (default: 10, max: 50)

clear_index

  • path (required): Path to the codebase to clear

Guidelines

  • Keep tool interfaces simple and intuitive
  • Provide clear error messages
  • Validate all user inputs
  • Use TypeScript for type safety

Working with MCP Clients

Cursor/Claude Desktop Development Mode Configuration

You can use the following configuration to configure the MCP server with a development mode.

{
  "mcpServers": {
    "claude-context-local": {
      "command": "node",
      "args": ["PATH_TO_CLAUDECONTEXT/packages/mcp/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-your-openai-api-key",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

Claude Code Development Mode Configuration

claude mcp add claude-context -e OPENAI_API_KEY=sk-your-openai-api-key -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint -e MILVUS_TOKEN=your-zilliz-cloud-api-key -- node PATH_TO_CLAUDECONTEXT/packages/mcp/dist/index.js

And then you can start Claude Code with claude --debug to see the MCP server logs.

Manual Usage

Use all three MCP tools:

  • index_codebase - Index sample repositories with optional custom ignore patterns
    Example with ignore patterns: {"path": "/repo/path", "ignorePatterns": ["static/**", "*.tmp"]}
  • search_code - Search with various queries
  • clear_index - Clear and re-index

Questions?