# 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

```bash
pip install -r requirements.txt
```

### 2. Configure environment

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

### 3. Run the MCP server

```bash
python run_mcp_server.py
```

### 4. Connect to Claude Desktop

Add the following to your `claude_desktop_config.json`:

```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](https://cloud.qdrant.io/) account (free tier works)
- OpenAI API key

## Related Projects

- [agent-dev](https://github.com/Abernaughty/agent-dev) — Containerized AI agent dev environment
  that this server is designed to complement