io.github.AndyAnh174/vibe-hnindex

vibe-hnindex

Local MCP server — index your repo once, search it in every AI session

Keyword (SQLite FTS5) · Semantic (Qdrant + configurable embeddings) · Hybrid — local or cloud embedding providers

Current release: v0.16.1 · MCP server vibe-hnindex · installer hnindex-cli. Release notes

Docs · Changelog · npm server · npm CLI

What this does

vibe-hnindex is a Model Context Protocol 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 (default), OpenAI, Voyage, Gemini, or an OpenAI-compatible API; see Embedding providers. Cloud providers receive the content being embedded; vectors use Qdrant (Docker, local, or Qdrant Cloud with QDRANT_API_KEY).

Documentation

Source security review: security_audit, security_context and pentest_plan provide live source evidence and validation checks. Optional Voyage/HTTP rerank follows server configuration; rerank:false keeps review local. Results are heuristic review leads with explicit coverage, not confirmed vulnerability reports.

📚 Full docs site: docs.hnindex.cloud — 16 pages covering Getting Started, Configuration, Tools Reference, Guides, and Code Agent.

Also available in-repo: docs/getting-started.md, docs/configuration.md, docs/tools-reference.md.

CLI installer (hnindex)

Optional — writes MCP JSON or Codex TOML for you (merge-safe, same npx -y vibe-hnindex block as in the docs):

npm install -g hnindex-cli

# Setup MCP config
hnindex init --mcp antigravity    # or: claude, cursor, windsurf, vscode, codex
hnindex init --list               # show all targets and paths

# Install AI agent skill (recommended)
hnindex init-skill --target claude    # or: antigravity, cursor, windsurf, vscode
hnindex init-skill --list             # show all skill targets

# Update
hnindex update                    # npm update -g hnindex-cli

See docs.hnindex.cloud for full documentation.

Install in 5 steps

1. Node.js — v22+ (nodejs.org). CI verifies Node 22 and 24. SQLite uses N-API binaries bundled for supported platforms; see Troubleshooting → Windows if npm i vibe-hnindex fails.
2. Embedding provider — choose OpenAI, Voyage, Gemini or a compatible API, or use local Ollama: install from ollama.com, then: ollama pull bge-m3:567m and keep ollama serve running (or set OLLAMA_URL to a remote server).
3. 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.
4. MCP config — add the server to your assistant’s MCP settings. Minimal example (self-hosted Qdrant):

{
  "mcpServers": {
    "vibe-hnindex": {
      "command": "npx",
      "args": ["-y", "vibe-hnindex"],
      "env": {
        "OLLAMA_URL": "http://localhost:11434",
        "OLLAMA_MODEL": "bge-m3:567m",
        "QDRANT_URL": "http://localhost:6333",
        "SEARCH_STREAM_ENABLED": "true",
        "CODE_AGENT_ENABLED": "true",
        "CODE_AGENT_SCOPE": "moderate",
        "CHAT_MEMORY_ENABLED": "true"
      }
    }
  }
}

1. Restart the IDE or assistant, then in chat ask to index a path and search — see First steps.

For Qdrant Cloud, add QDRANT_API_KEY and set QDRANT_URL to your HTTPS cluster URL — details in Getting started.

Agent Workspace

workspace_context identifies the active project purpose, Git/index state and a declared task persisted per project/session. locate_code finds files/symbols then keywords locally, returning line evidence and freshness. Explicit hybrid mode uses configured semantic APIs. MCP startup instructions and knowledge://workspace expose this workflow. Project-scoped CLI installs bind their root automatically; global installs follow client roots unless explicitly configured.

See Workspace and code locations. Refresh stale positions before editing; use filesystem tools for unavailable or excluded code.

Code Graph

Build a multilingual AST symbol graph with index_code_graph(path, project_name) using SQLite alone. index_codebase also builds it; file indexing and watching update relationships automatically. Use find_references, callers, and graph_context to inspect source evidence and bounded relationship context. SQLite remains the graph backend. JS/TS retain compiler resolution; Python, PHP, Go, Java, C/C++, C#, Rust, Ruby, Kotlin, Swift, Scala and Lua use bundled offline Tree-sitter profiles. See the language coverage and resolution limits in the graph guide.

AST chunking preserves function/class boundaries where possible. After upgrading, run index_codebase once to rebuild chunks and vectors. See Code Graph guide for resolution limits, offline usage, token budgets and quality evaluation.

Optional rerank

Hybrid search combines keyword results and embedding vectors using RRF. Optional reranking supports Voyage (RERANK_PROVIDER=voyage, VOYAGE_API_KEY or RERANK_API_KEY) and custom HTTP (RERANK_PROVIDER=http, RERANK_URL). Without a reranker, or if it fails, the original retrieval ranking is preserved. Exact symbol/regex modes skip reranking.

See Configuration.

Timeouts

To prevent hanging when Ollama or Qdrant are unresponsive, vibe-hnindex applies timeouts on all external calls. You can tune these via environment variables:

Set 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).

Google Antigravity

Use the same mcpServers block as above, but save it in Antigravity’s MCP file:

Step-by-step: Integrations → Google Antigravity.

Features (short)

Architecture

flowchart TB
    accTitle: hnindex system architecture
    accDescr: An MCP agent calls a local hnindex server with workspace files and SQLite storage. Semantic retrieval optionally uses embeddings and Qdrant.
    agent_client["AI agent / MCP client<br/>Codex · Claude · Cursor"]
    subgraph local_workspace["Local workspace"]
        hnindex_server["hnindex MCP server<br/>Context · multilingual AST · code lookup"]
        project_files["Source files<br/>README · Git"]
        sqlite_store[("SQLite<br/>FTS · graph · declared tasks")]
        security_review["Security review<br/>Live source · bounded leads · validation plan"]
        hnindex_server --> security_review
        project_files --> security_review
        project_files -->|Read and check freshness| hnindex_server
        hnindex_server <-->|Index and task storage| sqlite_store
    end
    subgraph semantic_services["Optional semantic retrieval"]
        embedding_provider["Embeddings<br/>Ollama local or cloud API"]
        qdrant_store[("Qdrant vectors<br/>Local or hosted")]
    end
    agent_client <-->|MCP / stdio| hnindex_server
    hnindex_server -.->|Code chunks and queries| embedding_provider
    embedding_provider -.->|Vectors| hnindex_server
    hnindex_server <-.->|Store and retrieve vectors| qdrant_store
    security_review -.->|Redacted query and evidence when enabled| reranker["Optional Voyage / HTTP rerank"]

How indexing & search work →

License

MIT — see LICENSE.

Contributing

Issues and PRs: github.com/AndyAnh174/vibe-hnindex.

Contact

Ho Viet Anh (AndyAnh174) · hovietanh147@gmail.com · GitHub

Codex and architecture

Run npx -y hnindex-cli init --mcp codex inside the project, then optionally npx -y hnindex-cli init-skill --target codex. Codex project MCP uses .codex/config.toml (trusted projects only); skills use .agents/skills/use-vibe-hnindex. Restart/reconnect Codex and ask for workspace_context, followed by index_code_graph.

See CLI configuration, system, sequence and user diagrams, and official Codex MCP setup.