# Quant > 🧠 Local-first RAG index that watches your files and serves MCP semantic search - **Type:** MCP server - **Install:** `agentstack add mcp-koltyakov-quant` - **Verified:** Pending review - **Seller:** [koltyakov](https://agentstack.voostack.com/s/koltyakov) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [koltyakov](https://github.com/koltyakov) - **Source:** https://github.com/koltyakov/quant ## Install ```sh agentstack add mcp-koltyakov-quant ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # quant A lightweight, developer-focused RAG index exposed as an MCP server. Point it at a folder and it watches the filesystem, extracts supported files, chunks them with structure awareness, embeds them via Ollama, stores them in SQLite, and serves semantic search over MCP. The index is a projection of the filesystem. Files added, changed, or removed on disk are reflected in the index automatically. In practice, `quant` is usually most useful as a project-scoped MCP - one server per repository, documentation set, or research workspace. See [docs/mcp-clients.md](docs/mcp-clients.md) for recommended deployment patterns and client configs. Zero CGO. Pure Go. ## Runtime requirements - A `quant` binary for your platform, either downloaded from GitHub Releases or built from source - A coding agent or other MCP-capable client of your choice, such as Claude, Codex, OpenCode, or GitHub Copilot - [Ollama](https://ollama.ai) installed locally, or an OpenAI-compatible embedding API at `--embed-url` `quant` handles Ollama setup automatically on first run: - If Ollama is installed but not running, `quant` starts it in the background (`ollama serve`) - If the configured embedding model isn't pulled yet, `quant` pulls it automatically (`ollama pull `) - If the embedding backend is still unavailable after recovery attempts, `quant` starts in keyword-only mode so the MCP server remains usable To set up manually instead: ``` ollama serve # start Ollama ollama pull nomic-embed-text ``` - Optional for scanned PDFs: [ocrmypdf](https://ocrmypdf.readthedocs.io/) installed on your system `PATH`. If present, `quant` will automatically use it as a best-effort OCR sidecar for PDFs that contain no extractable text. ## Install ### macOS and Linux The quickest install path on macOS and Linux is the release installer: ```bash curl -fsSL https://raw.githubusercontent.com/koltyakov/quant/main/scripts/install.sh | sh ``` It installs `quant` to `~/.local/bin`. The installer checks whether `ollama` is on `PATH`; if it is missing, it asks whether to install Ollama with the official shell installer and prints manual setup guidance if skipped. To uninstall the release binary: ```bash curl -fsSL https://raw.githubusercontent.com/koltyakov/quant/main/scripts/uninstall.sh | sh ``` ### Windows On Windows, use the PowerShell installer: ```powershell irm https://raw.githubusercontent.com/koltyakov/quant/main/scripts/install.ps1 | iex ``` It installs `quant.exe` to `%LOCALAPPDATA%\Programs\quant` and adds it to your user `PATH`. The installer also checks for Ollama and offers to install it via `winget`. To uninstall the release binary and remove the install directory from your user `PATH`: ```powershell irm https://raw.githubusercontent.com/koltyakov/quant/main/scripts/uninstall.ps1 | iex ``` ### Alternative: Go install If you already have Go installed, you can also install from source: ```bash go install github.com/koltyakov/quant/cmd/quant@latest ``` After installing: ```bash quant version ``` ## Build from source You only need Go if you are building `quant` yourself instead of using a release binary. - Go 1.26.0+ ``` make install ``` ## Usage ``` quant mcp [--dir ] [options] quant init [client] [options] quant launch [--dir ] [-- ] quant update quant version ``` **Commands:** | Command | Description | |---------|-------------| | `mcp` | Start the MCP server | | `init` | Scaffold a project MCP config and research assistant instructions | | `launch` | Start a supported agent with quant MCP injected for this session | | `update` | Check for and apply the latest GitHub release | | `version` | Print the quant version and exit | | `help` | Show top-level CLI help | **Core MCP flags:** | Flag | Default | Description | |------|---------|-------------| | `--dir` | current working directory | Directory to watch and index | For the full flag reference, environment variables, YAML config, include/exclude patterns, and auto-update settings see [docs/configuration.md](docs/configuration.md). ### Quick examples ```bash # Create a research workspace for Codex quant init codex --dir ./my-research-project # Launch Codex with quant MCP over ./data quant launch codex # Index a folder over stdio quant mcp --dir ./my-project # Update to the latest release quant update ``` For clients with narrow MCP permission controls, `quant init` and `quant launch` also allow all `quant` MCP tools without prompting. ## MCP Tools | Tool | Description | |---|---| | `search` | Semantic search over indexed chunks. Params: `query` (required), `limit`, `threshold`, `path`, `file_type`, `language` | | `list_sources` | List indexed documents. Params: `limit` | | `index_status` | Stats: total docs, chunks, DB size, watch dir, model, embedding status, lifecycle state | | `find_similar` | Find chunks similar to a given chunk by its ID. Params: `chunk_id` (required), `limit` | | `drill_down` | Explore a topic by finding diverse chunks related to a seed chunk from a previous search. Params: `chunk_id` (required), `limit` | | `summarize_matches` | Summarize all matching documents for a query — returns an overview of what the index contains on a topic. Params: `query` (required), `limit` | | `list_collections` | List all named collections with their document and chunk counts | | `delete_collection` | Delete all documents and chunks in a named collection. Params: `collection` (required) | **`search`** embeds the query with the configured embedding model, uses SQLite FTS5 to prefilter candidate chunks, then reranks those candidates with normalized vector similarity. All results use Reciprocal Rank Fusion (RRF) scoring on a common 0-1 scale. If the embedding backend is unavailable, search falls back to keyword-only results automatically. The `embedding_status` field in the response indicates whether results are hybrid or keyword-only. **`find_similar`** takes a chunk ID from a previous search result and returns the nearest neighbors from the HNSW index. Useful for discovering related content without formulating a new query. **`drill_down`** is like `find_similar` but prioritizes diversity across documents — it spreads results across different source files to help explore a topic broadly rather than staying within one file. **`summarize_matches`** runs a search and returns a high-level overview of which documents matched and what they contain, without returning individual chunks. Useful when you want a quick map of what the index knows about a subject. All MCP tools return structured payloads for clients that support `structuredContent`, while still including a readable text fallback. Tool concurrency is bounded by `--max-concurrent-tools` (auto-tuned by CPU by default). ## Supported File Types `quant` indexes common plain-text inputs by default, including source code, markup, config, data, and filename-only project files such as `Dockerfile`, `Makefile`, and similar repo metadata. For document-style content, current support includes: - Jupyter notebooks, with cell markers and captured text outputs - PDF, with page markers like `[Page N]` - Scanned PDF OCR via optional `ocrmypdf` fallback when a PDF has no embedded text - Rich text via RTF - Modern Office/Open XML word-processing, presentation, and spreadsheet files - OpenDocument text, spreadsheet, and presentation files See [docs/file-types.md](docs/file-types.md) for the full list of recognized extensions and special filenames. Unsupported or binary files are skipped. ## Architecture ```mermaid flowchart TD WD([Watched directory]) --> INDEX[Initial scan and watch updates] INDEX --> PROC[Extract, chunk, and embed] PROC --> OLLAMA[/Ollama API/] PROC --> DB[(SQLite index)] CLIENT([MCP client]) --> MCP[MCP server] MCP --> QUERY[Embed query] QUERY --> OLLAMA MCP --> SEARCH[Hybrid search] DB --> SEARCH SEARCH --> MCP ``` - **No CGO** - uses `modernc.org/sqlite` (pure Go SQLite) - **Hybrid retrieval** - SQLite FTS5 prefilter + normalized vector rerank via RRF - **Adaptive query weighting** - identifier-like queries (camelCase, short tokens) upweight keyword signals; longer natural-language queries upweight vector signals. Weights are selected automatically per query. - **HNSW approximate nearest neighbors** - in-memory HNSW graph (M=16, EfSearch=100) built from stored embeddings after initial sync; incremental add/delete during live indexing - **Int8 quantized embeddings** - embeddings are L2-normalized and quantized to 1 byte/dimension (~4x storage savings, `indexing` -> `ready` / `degraded`) is surfaced through readiness checks and `index_status` - **SQLite tuned for concurrency** - WAL + busy timeout + multi-connection pool allow reads during writes - **Transactional indexing** - chunk replacement happens in a single SQLite transaction per document, with incremental HNSW updates deferred until after commit - **Incremental reindexing** - unchanged chunks reuse their stored embeddings, so only new or modified content is sent to the embedding backend - **File watching** via `fsnotify` with 500ms debounce and self-healing resync on overflow - **Embedding caching** - LRU cache with in-flight deduplication and circuit breaker for query-time embedding calls See [docs/architecture.md](docs/architecture.md) for the internal package layout. ## Further reading - [Configuration reference](docs/configuration.md) - all flags, environment variables, YAML config, include/exclude patterns, auto-update - [MCP client integration](docs/mcp-clients.md) - Claude Code, GitHub Copilot, Codex, OpenCode, Cursor, Gemini - [Embedding models](docs/embedding.md) - model choice, quantization, and hardware guidance - [Search and ranking](docs/search.md) - hybrid search pipeline, RRF fusion, and signal weighting - [Supported file types](docs/file-types.md) - extensions, special filenames, and document extractors - [Architecture](docs/architecture.md) - internal package layout and data flow - [Troubleshooting](docs/troubleshooting.md) - common issues and fixes ## Contributing Fork, branch, add tests, submit a pull request. ## License MIT - see [LICENSE](./LICENSE). ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [koltyakov](https://github.com/koltyakov) - **Source:** [koltyakov/quant](https://github.com/koltyakov/quant) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-koltyakov-quant - Seller: https://agentstack.voostack.com/s/koltyakov - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.