# mcplens

> Semantic codebase search for AI coding assistants — 70-85% token reduction, 100% local, zero cloud dependency.

AI coding assistants like Claude Code, Cursor, and Codex are powerful — but they have a fundamental problem: when you ask a question, they read files by guessing which ones are
relevant based on path and filename heuristics. On a medium-sized project, a single query can consume 10,000–20,000 tokens of context just loading files that may not even be
relevant.

`claude-context-optimizer` solves this by giving your AI assistant **semantic search** over your codebase. Instead of reading files blindly, it calls
`search_code("how does payment work?")` and gets back only the 5 most relevant code chunks — indexed locally using embeddings, stored in SQLite, zero data leaving your machine.

---

## How it works

When you open your AI assistant in a project:

1. The MCP server starts automatically (spawned via stdio by the assistant)
2. It compares file hashes against the last index and **re-indexes only what changed** (delta indexing)
3. A file watcher keeps the index in sync as you code
4. Your assistant now has access to 3 semantic search tools instead of reading raw files

```
You ask: "how does the Asaas webhook work?"

Without cco:                          With cco:
  Read AsaasWebhookController.php       search_code("asaas webhook")
  Read AsaasWebhookService.php          → returns 5 relevant chunks
  Read PaymentService.php               → ~800 tokens total
  Read BillingModule.php
  Read ...8 more files
  → ~15,000 tokens total
```

### Under the hood

* **Embeddings:**[Ollama](https://ollama.ai/) with `nomic-embed-text` (768-dim) — 100% local, free, no API key
* **Vector store:** SQLite with cosine similarity computed in-process — no extra infrastructure
* **Chunking:** AST-aware via `tree-sitter` (splits by function/class) with sliding window fallback
* **Transport:** MCP stdio — the assistant spawns the process and communicates via pipe
* **Persistence:** Index lives in `.claude-context/index.db` and survives between sessions

---

## Compatibility

`claude-context-optimizer` works with **any MCP-compatible AI coding assistant**. MCP (Model Context Protocol) is an open standard — the same server works across all clients
without modification.

| Assistant      | Status | Config location                       |
|----------------|--------|---------------------------------------|
| Claude Code    | ✅      | `~/.claude.json`                      |
| Cursor         | ✅      | `.cursor/mcp.json`                    |
| Windsurf       | ✅      | `~/.codeium/windsurf/mcp_config.json` |
| Trae           | ✅      | `.vscode/settings.json`               |
| Codex          | ✅      | MCP config (preview)                  |
| Any MCP client | ✅      | Follows MCP stdio spec                |

The `init` command detects which assistants you use and registers the server automatically in the right place.

---

## Token savings

The index lives locally. The assistant fetches only what's relevant. The numbers speak for themselves:

| Project size | Without cco         | With cco            | Savings   |
|--------------|---------------------|---------------------|-----------|
| \~200 files  | \~5k tokens/query   | \~1.2k tokens/query | **\~75%** |
| \~1000 files | \~10k tokens/query  | \~1.5k tokens/query | **\~85%** |
| \~5000 files | \~20k+ tokens/query | \~2k tokens/query   | **\~90%** |

These are context tokens — the portion you control. Savings scale with project size because larger projects trigger more heuristic file reads by default.

---

## Tools exposed

| Tool                 | When to use                                                                      |
|----------------------|----------------------------------------------------------------------------------|
| `search_code(query)` | Conceptual queries:*"how does billing work"*,*"where is authentication handled"* |
| `get_symbol(name)`   | Exact lookups:*"find PaymentService"*,*"where is handleWebhook defined"*         |
| `index_status`       | Debug: how many files and chunks are currently indexed                           |

Add this to your project's `CLAUDE.md` (or equivalent) to guide the assistant:

```markdown
## Context Search

Always use MCP tools before reading files:

- search_code() — for conceptual or natural language queries
- get_symbol() — for exact class/function/method lookups
  Only read full files if both tools return insufficient context.
```

---

## Installation options

### Option A — npm (requires Ollama)

Zero overhead. Best for developers who already have Ollama installed.

```bash
npm install -g @vmsfigueredo/mcplens
ollama pull nomic-embed-text:latest
cd your-project && mcplens init
```

See [INSTALL.md](INSTALL.md) for full setup instructions.

### Option B — Docker

> **Not available yet.** Docker distribution (bundling Node + Ollama + model) is planned but not implemented. Track progress in the [Roadmap](#roadmap).

---

## Configuration

`.claude-context/config.json` is created automatically by `init`. Edit it to customize behavior:

```json
{
  "embeddings": {
    "provider": "ollama",
    "ollamaUrl": "http://localhost:11434",
    "ollamaModel": "nomic-embed-text:latest"
  },
  "search": {
    "topK": 5,
    "minScore": 0.3
  },
  "ignore": [
    "**/tests/fixtures/**"
  ]
}
```

To use OpenAI embeddings instead:

```json
{
  "embeddings": {
    "provider": "openai",
    "openaiApiKey": "sk-...",
    "openaiModel": "text-embedding-3-small"
  }
}
```

---

## What gets indexed

**Included by default:**`.ts .tsx .js .jsx .mjs .php .svelte .vue .py .rb .go .rs .css .scss .json .yaml .yml .md .sql`

**Ignored by default:**`node_modules`, `.git`, `vendor`, `dist`, `build`, `.next`, `.claude-context`

The `.claude-context/` directory is automatically added to `.gitignore`.

### Index size reference

| Project | Files        | Approx size |
|---------|--------------|-------------|
| Small   | \~200 files  | \~15 MB     |
| Medium  | \~1000 files | \~70 MB     |
| Large   | \~5000 files | \~350 MB    |

---

## Dashboard

A lightweight web dashboard is available at `http://localhost:3000` while the server is running:

* **Overview** — files indexed, chunks, index size, Ollama status
* **Activity** — live feed of re-indexing events
* **Search** — test queries manually and see scores (useful for calibrating `minScore`)
* **Files** — full list of indexed files with chunk counts

The dashboard runs on port `3333` by default. If that port is already taken (e.g. two projects open simultaneously), the port is automatically calculated from the project name. To
open:

```bash
mcplens dashboard
```

To disable: add `--no-dashboard` to the server args in your MCP config.

---

## Privacy

Everything runs on your machine:

* Embeddings are generated locally via Ollama — your code never leaves
* The index is stored in `.claude-context/index.db` in your project
* No telemetry, no analytics, no accounts

> ⚠️ If you use the OpenAI embeddings option, chunks are sent to OpenAI's API.

---

## Why not just use existing tools?

| Tool                         | Language    | Fully local?                     | Install friction                     |
|------------------------------|-------------|----------------------------------|--------------------------------------|
| `claude-context`(Zilliz)     | TypeScript  | ❌ requires Zilliz Cloud + OpenAI | Medium                               |
| `claude-context-local`       | Python      | ✅                                | High (torch, FAISS, pipx)            |
| `cocoindex-code`             | Python      | ✅                                | Medium (pipx, sentence-transformers) |
| `codegraph`                  | Rust        | ✅                                | High (must compile Rust)             |
| **@vmsfigueredo/mcplens**    | **Node.js** | **✅**                            | **Low (`npm install -g`)**           |

The goal is to be the **most accessible option for JS/TS developers** — not the most feature-complete. If you already have Node.js, you're one command away.

---

## Roadmap

* [X]  AST-based chunking via tree-sitter
* [X]  Delta indexing by file hash
* [X]  Real-time file watcher
* [X]  Dashboard
* [X]  Multi-client init (Claude Code, Cursor, Windsurf, Trae)
* [X]  Hybrid search (BM25 + semantic)
* [ ]  Docker option with bundled Ollama
* [ ]  Contextual retrieval (LLM-generated chunk summaries)
* [ ]  Token usage analytics via Claude Code hooks

---

## Contributing

PRs welcome. See [INSTALL.md](INSTALL.md) for local development setup.

## Built with

This project was built using Claude Code — which is exactly why it exists.

## License

MIT