code-vector-sync

An MCP (Model Context Protocol) server that provides semantic code search over a local codebase using Qdrant vector embeddings and OpenAI embeddings. Point it at a directory and query it with natural language from any MCP-compatible client (e.g., Claude Desktop).

What It Does

• Watches a local directory for file changes and auto-indexes them
• Embeds code using OpenAI's embedding API
• Stores vectors in a Qdrant cloud collection
• Serves semantic search results via the MCP protocol

Architecture

File Watcher → Embedding Service → Qdrant Manager
                                        ↑
MCP Client (Claude) ←── MCP Server ────┘
                         (code_search)

Setup

1. Install dependencies

pip install -r requirements.txt

2. Configure environment

cp .env.example .env
# Edit .env with your Qdrant URL, Qdrant API key, OpenAI API key, and watch directory

3. Run the MCP server

python run_mcp_server.py

4. Connect to Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "code-vector-search": {
      "command": "python",
      "args": ["/path/to/code-vector-sync/run_mcp_server.py"],
      "env": {
        "QDRANT_URL": "your-qdrant-url",
        "QDRANT_API_KEY": "your-api-key",
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

Project Structure

code-vector-sync/
├── src/
│   ├── mcp_server.py        # MCP server entry point and tool definitions
│   ├── code_search.py       # Search query handling
│   ├── code_sync_service.py # Orchestrates watching, embedding, and indexing
│   ├── embedding_service.py # OpenAI embedding calls
│   ├── file_watcher.py      # Watchdog-based directory monitoring
│   └── qdrant_manager.py    # Qdrant client and collection management
├── run_mcp_server.py        # Launcher script
├── requirements.txt
├── .env.example             # Template — copy to .env and fill in values
└── .gitignore

Requirements

• Python 3.10+
• Qdrant Cloud account (free tier works)
• OpenAI API key

Related Projects

• agent-dev — Containerized AI agent dev environment that this server is designed to complement