{
"markdown": "\n\n# vibe-hnindex\n\n**Local MCP server — index your repo once, search it in every AI session**\n\n*Keyword (SQLite FTS5) · Semantic (Qdrant + Ollama embeddings) · Hybrid — your code stays on disk*\n\n[](https://www.npmjs.com/package/vibe-hnindex)\n[](https://www.npmjs.com/package/hnindex-cli)\n[](LICENSE)\n[](https://modelcontextprotocol.io/)\n[](https://nodejs.org/)\n\n**MCP server (`vibe-hnindex`) latest: v0.12.0** · [`hnindex-cli`](https://www.npmjs.com/package/hnindex-cli) **v0.12.0** — [Docs](https://docs.hnindex.cloud) · [Changelog](https://hnindex.cloud/changelog) · [GitHub Releases](https://github.com/AndyAnh174/vibe-hnindex/releases)\n\n
\n\n---\n\n## What this does\n\n[vibe-hnindex](https://www.npmjs.com/package/vibe-hnindex) is a [Model Context Protocol](https://modelcontextprotocol.io/) server. After you **index** a folder once, assistants (Claude, Cursor, Windsurf, Antigravity, …) can **search** that codebase with paths and line ranges — data is stored locally (SQLite + optional Qdrant). Embeddings use **Ollama**; vectors use **Qdrant** (Docker, local, or [Qdrant Cloud](https://cloud.qdrant.io/) with `QDRANT_API_KEY`).\n\n---\n\n## Documentation\n\n📚 **Full docs site: [docs.hnindex.cloud](https://docs.hnindex.cloud)** — 16 pages covering Getting Started, Configuration, Tools Reference, Guides, and Code Agent.\n\n| Page | What you'll learn |\n|------|-------------------|\n| [Introduction](https://docs.hnindex.cloud) | What vibe-hnindex does, key features, how it works |\n| [Installation](https://docs.hnindex.cloud/getting-started/installation) | Node, Ollama, Qdrant setup + MCP config |\n| [Quick Start](https://docs.hnindex.cloud/getting-started/quick-start) | 5-minute walkthrough with CLI + agent skill |\n| [Configuration](https://docs.hnindex.cloud/configuration) | All 25+ env vars with embedding model comparison |\n| [Search](https://docs.hnindex.cloud/tools/search) | 6 search modes, regex, fuzzy, streaming, cache |\n| [Code Agent](https://docs.hnindex.cloud/tools/code-agent) 🆕 | code_session + code_apply with safety scopes |\n| [Setup MCP](https://docs.hnindex.cloud/guides/setup-mcp) | Per-platform config (Claude, Cursor, Antigravity, VS Code...) |\n\nAlso available in-repo: [docs/getting-started.md](docs/getting-started.md), [docs/configuration.md](docs/configuration.md), [docs/tools-reference.md](docs/tools-reference.md).\n\n---\n\n## CLI installer (`hnindex`)\n\nOptional — writes the MCP JSON for you (merge-safe, same `npx -y vibe-hnindex` block as in the docs):\n\n```bash\nnpm install -g hnindex-cli\n\n# Setup MCP config\nhnindex init --mcp antigravity # or: claude, cursor, windsurf, vscode, codex\nhnindex init --list # show all targets and paths\n\n# Install AI agent skill (recommended)\nhnindex init-skill --target claude # or: antigravity, cursor, windsurf, vscode\nhnindex init-skill --list # show all skill targets\n\n# Update\nhnindex update # npm update -g hnindex-cli\n```\n\nSee **[docs.hnindex.cloud](https://docs.hnindex.cloud)** for full documentation.\n\n---\n\n## Install in 5 steps\n\n1. **Node.js** — v20+ ([nodejs.org](https://nodejs.org/)). On **Windows**, **Node 20 or 22 LTS** is strongly recommended so `npm install` does not need a C++ compiler. See [Troubleshooting → Windows](docs/troubleshooting.md#windows-npm-install) if `npm i vibe-hnindex` fails.\n2. **Ollama** — install from [ollama.com](https://ollama.com/), then: `ollama pull bge-m3:567m` and keep `ollama serve` running (or set `OLLAMA_URL` to a remote server).\n3. **Qdrant** — for semantic/hybrid search: `docker run -d --name qdrant -p 6333:6333 qdrant/qdrant` (or use Qdrant Cloud). Keyword-only search works without Qdrant.\n4. **MCP config** — add the server to your assistant’s MCP settings. Minimal example (self-hosted Qdrant):\n\n```json\n{\n \"mcpServers\": {\n \"vibe-hnindex\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"vibe-hnindex\"],\n \"env\": {\n \"OLLAMA_URL\": \"http://localhost:11434\",\n \"OLLAMA_MODEL\": \"bge-m3:567m\",\n \"QDRANT_URL\": \"http://localhost:6333\",\n \"SEARCH_STREAM_ENABLED\": \"true\",\n \"CODE_AGENT_ENABLED\": \"true\",\n \"CODE_AGENT_SCOPE\": \"moderate\",\n \"CHAT_MEMORY_ENABLED\": \"true\"\n }\n }\n }\n}\n```\n\n5. **Restart** the IDE or assistant, then in chat ask to **index** a path and **search** — see [First steps](docs/getting-started.md#first-steps-in-chat).\n\nFor **Qdrant Cloud**, add `QDRANT_API_KEY` and set `QDRANT_URL` to your HTTPS cluster URL — details in [Getting started](docs/getting-started.md).\n\n### Optional rerank (`RERANK_URL`)\n\nSemantic/hybrid search already uses **Ollama** (`OLLAMA_URL`, `OLLAMA_MODEL` e.g. `bge-m3:567m`) for query vectors and **Qdrant** for retrieval. After that, the server can **reorder** the top pool of hits:\n\n- **Without `RERANK_URL`:** reorder by **Qdrant semantic scores** (no extra network service). This is enough for most setups, including when you only run Ollama + Qdrant.\n- **With `RERANK_URL`:** POST JSON `{ \"query\", \"documents\" }` to your URL; response `{ \"scores\": number[] }` (same length as `documents`). Use a **small HTTP service** you host that wraps your reranker; Ollama does not expose this contract on `:11434` by default.\n\n**Ollama vs rerank:** pulling a reranker model in Ollama (e.g. `qllama/bge-reranker-v2-m3`) does **not** replace `RERANK_URL`—you still need an adapter service unless you only rely on the built-in Qdrant reorder. See [Configuration → Rerank](docs/configuration.md#optional-rerank).\n\n| Env | Role |\n|-----|------|\n| `SEARCH_RERANK` | `false` disables post-retrieval reorder entirely (default: enabled). |\n| `SEARCH_RERANK_POOL` | Max candidates considered before trim (default `50`). |\n| `RERANK_URL` | Full URL of your `{query, documents}` → `{scores}` API (optional). |\n| `RERANK_TIMEOUT_MS` | Timeout for that POST (default `15000`). |\n\n### Timeouts\n\nTo prevent hanging when Ollama or Qdrant are unresponsive, vibe-hnindex applies timeouts on all external calls. You can tune these via environment variables:\n\n| Env | Default | Controls |\n|-----|---------|----------|\n| `OLLAMA_TIMEOUT_MS` | `30000` (30s) | Max wait for Ollama `/api/embed` and `/api/tags` calls |\n| `QDRANT_TIMEOUT_MS` | `15000` (15s) | Max wait for Qdrant API calls (search, upsert, etc.) |\n| `SEARCH_TIMEOUT_MS` | `60000` (60s) | Overall timeout for the entire search operation |\n\nSet any of these to a higher value if you have a slow machine or large dataset. Set to `0` to disable the timeout for that layer (not recommended).\n\n### Google Antigravity\n\nUse the **same** `mcpServers` block as above, but save it in Antigravity’s MCP file:\n\n| | |\n|--|--|\n| **File** | `mcp_config.json` under **`.gemini/antigravity/`** in your user folder |\n| **Windows** | `C:\\Users\\\\.gemini\\antigravity\\mcp_config.json` |\n| **macOS / Linux** | `~/.gemini/antigravity/mcp_config.json` |\n| **UI** | **⋮** menu → **MCP** → **Manage MCP Servers** → **View raw config** |\n\nStep-by-step: [Integrations → Google Antigravity](docs/integrations.md#google-antigravity).\n\n---\n\n## Features (short)\n\n| | |\n|--|--|\n| **Search** | 6 modes: keyword (FTS5+BM25), semantic (Qdrant vectors), hybrid (RRF fusion), regex, symbol, auto |\n| **Code Agent** | `code_session` — 1 call replaces 5-15 searches. `code_apply` — safe code changes with auto test/lint/typecheck |\n| **Chat Memory** 🆕 | Auto-track tool calls, semantic search via Qdrant, persistent AI context across sessions |\n| **Streaming** | Parallel keyword+semantic search (~1.5-2× faster), 4-phase progress notifications |\n| **Fuzzy Search** | Levenshtein distance auto-corrects typos (\"fucntion\" → \"function\") |\n| **Smart Context** | Task-aware context: impact analysis, test file detection, similar code patterns |\n| **Storage** | SQLite on disk + Qdrant for vectors; 100% local, no cloud required |\n| **Indexing** | Incremental (SHA-1 hash), parallel workers (~3-4× faster), watch mode (auto re-index on save), 40+ languages, `.hnindexignore` |\n| **Resilience** | Keyword search works without Qdrant or Ollama; graceful degradation |\n| **Benchmark** | Built-in `benchmark_search` tool — compare streaming vs non-streaming, all search modes |\n| **Multiple Embedding Models** | bge-m3 (default), nomic-embed-text, qwen3-embedding, mxbai-embed-large, and more |\n\n---\n\n## Architecture\n\n```mermaid\ngraph TB\n subgraph Input[\"📂 Input\"]\n A[\"💻 Your Codebase
.ts .py .go .rs ...\"]\n end\n\n subgraph Server[\"⚙️ vibe-hnindex MCP Server\"]\n B[\"🔍 Search Router
keyword | semantic | hybrid\"]\n C[\"🔀 RRF Fusion\"]\n end\n\n subgraph Storage[\"💾 Storage\"]\n D[(\"SQLite
FTS5 + Keyword\")]\n E[(\"Qdrant
Vector Embeddings\")]\n end\n\n subgraph Memory[\"🧠 Chat Memory (v0.12)\"]\n F[(\"SQLite
Chat Context\")]\n G[(\"Qdrant
Chat Vectors\")]\n end\n\n subgraph Infra[\"🏗️ Infrastructure\"]\n H[\"Ollama
Embeddings\"]\n I[\"Qdrant
localhost:6333\"]\n end\n\n subgraph Output[\"🤖 AI Clients\"]\n J[\"Claude · Cursor · Windsurf
Antigravity · VS Code\"]\n end\n\n A -->|\"index_codebase\"| Storage\n A -->|scan| H\n B -->|\"keyword\"| D\n B -->|\"semantic\"| E\n B -->|\"hybrid\"| C\n C --> D\n C --> E\n B -.->|\"auto-track\"| F\n F --> H\n H --> G\n D --> J\n E --> J\n H -.-> I\n\n style F fill:#6366f1,color:#fff\n style G fill:#6366f1,color:#fff\n style B fill:#f59e0b,color:#000\n style J fill:#22c55e,color:#fff\n```\n\n\n How indexing & search work →\n
\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Contributing\n\nIssues and PRs: [github.com/AndyAnh174/vibe-hnindex](https://github.com/AndyAnh174/vibe-hnindex).\n\n## Contact\n\n**Ho Viet Anh (AndyAnh174)** · [hovietanh147@gmail.com](mailto:hovietanh147@gmail.com) · [GitHub](https://github.com/AndyAnh174)\n",
"bytes": 10347,
"sha": "c771b62e0785f3d817733f6374396f39f759479edfe1fcd6cc2b1fd3ba513375",
"repo_slug": "andyanh174/vibe-hnindex",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_andyanh174_vibe_hnindex_df63444d/readme"
}