Metadata-Version: 2.4
Name: semantic-code-index-mcp
Version: 0.2.2
Summary: MCP server: semantic code search with SQLite + local free embeddings
Requires-Python: >=3.11
Requires-Dist: fastembed>=0.4.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: tiktoken>=0.7.0
Description-Content-Type: text/markdown

# semantic-code-index-mcp

MCP server for Claude Code: semantic code search with SQLite + local embeddings (free, no API key needed).

Instead of reading your entire codebase, Claude searches semantically — finding relevant code by meaning, not just keywords. Saves 80-90% tokens per query.

## Quick Install (npx)

```bash
cd /path/to/your/project
npx semantic-code-index-mcp install
```

This automatically:
- Creates `.claude/mcp.json` and `.mcp.json` (merged with existing config)
- Adds `.claude/rules/semantic-search.md` so Claude prefers semantic search
- Updates `.gitignore`

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/) (`brew install uv` or `pip install uv`).

### Uninstall

```bash
npx semantic-code-index-mcp uninstall
```

Cleanly removes all config. If you have other MCP servers configured, they are preserved.

## Install from source (dev)

```bash
git clone https://github.com/thinhdo/semantic-code-index-mcp
cd semantic-code-index-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Install into a project using local binary
semantic-code-index-mcp install /path/to/your/project

# Or via npx with --local flag
npx semantic-code-index-mcp install /path/to/project --local .venv/bin/semantic-code-index-mcp
```

## Usage

Once installed, open Claude Code in your project. First time, ask Claude:

> Index this project

After that, Claude will automatically use `semantic_search` for code exploration. The index auto-syncs when files change — no manual steps needed.

## Tools

| Tool | Description |
|------|-------------|
| `index_project` | Full re-index of the codebase |
| `sync_index` | Incremental sync (new/changed/deleted files only) |
| `semantic_search` | Hybrid search: semantic vectors + keyword BM25. Auto-syncs before searching |
| `list_indexed_files` | List all indexed files with token count and chunk count |
| `get_file_chunks` | Get full content of a file's indexed chunks |
| `token_usage_stats` | Compare: tokens if reading full repo vs tokens used by searches |
| `search_log` | View recent search history with token usage and savings |

## How it works

1. **Chunking** — source files are split into overlapping chunks (~100 lines, 15-line overlap)
2. **Embedding** — each chunk is vectorized locally using `fastembed` (BAAI/bge-small-en-v1.5, ONNX)
3. **Storage** — vectors + metadata stored in SQLite (at `~/.cache/semantic-code-index/<hash>/`)
4. **Search** — hybrid retrieval: cosine similarity + FTS5 BM25, fused with Reciprocal Rank Fusion
5. **Auto-sync** — on each search, changed files are detected and re-indexed automatically

## Token savings

Each search returns only relevant snippets instead of the full repo. Example on a ~10k token repo:

| Query | Result tokens | Full repo | Saved |
|-------|--------------|-----------|-------|
| "how does embedding work" | 1,569 | 9,577 | **83%** |
| "install setup" | 925 | 9,577 | **90%** |
| "chunking strategy" | 1,331 | 9,577 | **86%** |

On larger repos (100k+ tokens), savings are even more significant.

## Environment variables

- `SEMANTIC_CODE_ROOT` or `WORKSPACE_ROOT`: root directory of the project to index (default: MCP server's working directory)

## Notes

- Token counting uses `tiktoken` encoding `cl100k_base` (approximate for Claude/GPT-4), not actual billing
- First run downloads the ONNX embedding model (~30MB)
- Vector search scans all chunks in SQLite; very large repos may need scaling (sqlite-vec / ANN)
