# Personal Semantic Search MCP

A Model Context Protocol (MCP) server that enables semantic search over your local notes and documents. Built for use with Claude Code and other MCP-compatible clients.

## Features

- **Semantic Search**: Find notes by meaning, not just keywords
- **Multiple File Types**: Supports Markdown, Python, HTML, JSON, CSV, and plain text
- **Smart Chunking**: Preserves document structure with header hierarchy
- **Fast Local Embeddings**: Uses `all-MiniLM-L6-v2` (384 dimensions, runs on CPU)
- **ChromaDB Storage**: Persistent vector database with incremental indexing
- **File Watching**: Optional real-time re-indexing on file changes

## Architecture

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Claude Code    │────▶│   MCP Server     │────▶│   ChromaDB      │
│  (MCP Client)   │     │   (FastMCP)      │     │   (Vectors)     │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │ Sentence-        │
                        │ Transformers     │
                        │ (Embeddings)     │
                        └──────────────────┘
```

## Installation

```bash
# Clone the repository
git clone https://github.com/Ethan2298/personal-semantic-search-mcp.git
cd personal-semantic-search-mcp

# Create virtual environment
python -m venv .venv

# Activate (Windows)
.venv\Scripts\activate

# Activate (Unix/macOS)
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

## Configuration

### Claude Code Setup

Add to your `~/.claude/.mcp.json`:

```json
{
  "mcpServers": {
    "semantic-search": {
      "command": "/path/to/your/.venv/Scripts/python.exe",
      "args": ["/path/to/your/mcp_server.py"]
    }
  }
}
```

Then enable in `~/.claude/settings.json`:

```json
{
  "enabledMcpjsonServers": ["semantic-search"]
}
```

## Usage

### MCP Tools (via Claude Code)

Once configured, Claude Code can use these tools:

| Tool | Description |
|------|-------------|
| `search_notes` | Semantic search with natural language queries |
| `index_notes` | Index or re-index your vault |
| `get_index_stats` | Show indexing statistics |

### CLI Usage

```bash
# Index a folder
python search.py index ~/Desktop/Notes

# Search
python search.py query "how to implement authentication"

# Watch for changes (real-time indexing)
python search.py watch ~/Desktop/Notes

# Show statistics
python search.py stats
```

## Module Overview

| File | Purpose |
|------|---------|
| `mcp_server.py` | FastMCP server exposing tools via stdio |
| `search.py` | High-level search and indexing API |
| `embedding_engine.py` | Sentence-transformer embeddings |
| `vector_store.py` | ChromaDB storage and retrieval |
| `text_chunker.py` | Document chunking with overlap |
| `file_reader.py` | Multi-format text extraction |
| `folder_watcher.py` | File system change detection |

## How It Works

1. **File Reading**: Extracts text from various formats (Markdown, Python, HTML, etc.)
2. **Chunking**: Splits documents into ~500 token chunks with 50 token overlap, preserving header hierarchy
3. **Embedding**: Converts chunks to 384-dimensional vectors using `all-MiniLM-L6-v2`
4. **Storage**: Stores vectors in ChromaDB with metadata (file path, headers, timestamps)
5. **Search**: Embeds queries and finds nearest neighbors by cosine similarity

## Performance Notes

- **First startup**: ~10 seconds (loading sentence-transformers model)
- **Indexing speed**: ~100 documents/minute (depends on size)
- **Search latency**: <100ms after warmup
- **Model size**: ~80MB (downloaded on first run)

## Requirements

- Python 3.10+
- ~500MB disk space (model + dependencies)
- Works on CPU (no GPU required)

## License

MIT