# Code Context MCP

A **multi-provider embedding MCP server** with local Milvus for semantic code search. Works with Claude Code, Cursor, Windsurf, and other MCP-compatible IDEs.

## Features

- **Multi-provider embeddings**: Local Qwen (free), OpenAI, or DeepSeek
- **Dimension mismatch detection**: Warns before indexing if dimensions don't match
- **Zero cloud dependency**: Use local Qwen for completely offline operation
- **Dual deployment**: Docker or local with pnpm

## Architecture

```
┌─────────────────┐     ┌────────────────────┐     ┌─────────────────┐
│  Your Codebase  │────▶│  Embedding Provider │────▶│  Local Milvus   │
│                 │     │  (Qwen/OpenAI/etc) │     │  (Vector Store) │
└─────────────────┘     └────────────────────┘     └─────────────────┘
         │                                                  │
         │         ┌────────────────────────────┐          │
         └────────▶│     code-context-mcp       │◀─────────┘
                   │       (MCP Server)         │
                   └────────────────────────────┘
                            │
              ┌─────────────┴─────────────┐
              ▼             ▼             ▼
        Claude Code      Cursor      Windsurf
```

## Quick Start

### Option A: Docker (Recommended)

```bash
# 1. Configure
cp .env.example .env
# Edit .env with your settings

# 2. Start all services
docker-compose up -d

# 3. Verify (~60 seconds to initialize)
curl http://localhost:9091/healthz   # Milvus
curl http://localhost:3100/health    # MCP Server
```

**IDE Configuration (Docker):**
```json
{
  "mcpServers": {
    "code-context": {
      "url": "http://localhost:3100/sse"
    }
  }
}
```

### Option B: Local Development

```bash
# 1. Start only Milvus in Docker
docker-compose up -d milvus

# 2. Install and build
pnpm install
pnpm build

# 3. Configure IDE (see below)
```

**IDE Configuration (Local):**
```json
{
  "mcpServers": {
    "code-context": {
      "command": "node",
      "args": ["/path/to/code-context-mcp/dist/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "qwen-local",
        "QWEN_LOCAL_BASE_URL": "http://172.18.35.123:8001/v1",
        "QWEN_LOCAL_MODEL": "Qwen3-Embedding-4B",
        "MILVUS_ADDRESS": "127.0.0.1:19530"
      }
    }
  }
}
```

## MCP Tools

| Tool | Description |
|------|-------------|
| `index_codebase` | Index a directory into Milvus |
| `search_code` | Semantic search across indexed code |
| `check_dimensions` | Check provider/collection dimension compatibility |
| `drop_collection` | Delete a collection (for re-indexing) |
| `get_provider_info` | Show current provider configuration |

**Usage:**
```
index_codebase /path/to/your/project
search_code "authentication logic"
check_dimensions
```

## Embedding Providers

| Provider | Model | Dimensions | Cost |
|----------|-------|------------|------|
| `qwen-local` | Qwen3-Embedding-4B | 2560 | Free |
| `openai` | text-embedding-3-small | 1536 | $0.02/1M tokens |
| `openai` | text-embedding-3-large | 3072 | $0.13/1M tokens |
| `deepseek` | deepseek-embedding-v2 | 768 | Paid |

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `EMBEDDING_PROVIDER` | `openai`, `qwen-local`, `deepseek` | `openai` |
| `MILVUS_ADDRESS` | Milvus server address | `127.0.0.1:19530` |
| `DIMENSION_CHECK_ENABLED` | Check dimensions before indexing | `true` |
| `MCP_TRANSPORT` | `stdio` or `http` | `stdio` |
| `MCP_PORT` | HTTP port (http mode) | `3100` |

**Provider-specific:**

| Provider | Variables |
|----------|-----------|
| Local Qwen | `QWEN_LOCAL_BASE_URL`, `QWEN_LOCAL_MODEL` |
| OpenAI | `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_EMBEDDING_MODEL` |
| DeepSeek | `DEEPSEEK_API_KEY`, `DEEPSEEK_BASE_URL`, `DEEPSEEK_EMBEDDING_MODEL` |

## Dimension Mismatch Handling

Different providers produce different dimensions. Switching providers requires re-indexing:

```
drop_collection code_context confirm=true
index_codebase /path/to/project
```

## Docker Commands

```bash
docker-compose up -d              # Start all
docker-compose up -d milvus       # Start only Milvus
docker-compose logs -f            # View logs
docker-compose down               # Stop all
docker-compose down -v            # Reset (delete data)
docker-compose build --no-cache   # Rebuild
```

## Local Development

```bash
pnpm install    # Install dependencies
pnpm build      # Build TypeScript
pnpm dev        # Run in dev mode
pnpm start      # Run production build
```

## Project Structure

```
code-context-mcp/
├── docker-compose.yml      # Milvus + MCP server
├── Dockerfile
├── package.json
├── tsconfig.json
├── .env.example
└── src/
    ├── index.ts            # Entry point (stdio + HTTP)
    ├── config.ts           # Configuration
    ├── providers/          # Embedding providers
    │   ├── base.ts
    │   ├── openai.ts
    │   ├── qwen-local.ts
    │   └── deepseek.ts
    ├── milvus/             # Milvus integration
    │   ├── client.ts
    │   └── dimension-checker.ts
    └── tools/              # MCP tools
        ├── index-codebase.ts
        ├── search-code.ts
        └── check-dimensions.ts
```

## License

MIT