GitHubnpm
Getting Started

Installation

Follow this guide to install all the required components and get vibe-hnindex running.

Prerequisites

1. Node.js ≥ 20

vibe-hnindex requires Node.js 20 or later. Check your version:

node -v

Download from nodejs.org or use nvm-windows.

Windows users: Use Node 20 or 22 LTS. Avoid very new versions (e.g., Node 24) if installs fail without build tools. See the Troubleshooting guide for details.

2. Ollama (Embedding Server)

Ollama provides the embedding model used for semantic search. Install it from ollama.com, then pull your model:

# Default: bge-m3 (multilingual, 1024-dim)
ollama pull bge-m3:567m

# Lightweight alternative (recommended for CPU-only)
ollama pull nomic-embed-text

# Best quality (needs GPU)
ollama pull qwen3-embedding:4b

ollama serve

Which model? bge-m3 is the default. If you have limited RAM or no GPU, nomic-embed-text (274 MB) is the best choice. See Configuration → Embedding Models for a full comparison.

Remote Ollama: If Ollama runs on another machine, you'll set OLLAMA_URL in your MCP config to point to it.

3. Qdrant (Vector Database)

Qdrant stores vector embeddings for semantic search. It's optional — keyword search works without it.

Self-hosted (Docker)

docker run -d --name qdrant -p 6333:6333 -v qdrant_storage:/qdrant/storage qdrant/qdrant

Qdrant Cloud

Sign up at cloud.qdrant.io, create a cluster, and get your API key and URL.

Install vibe-hnindex

You don't need to install vibe-hnindex globally — it runs via npx in your MCP config.

However, you can install the CLI helper for easier configuration:

npm install -g hnindex-cli

MCP Configuration

Add vibe-hnindex to your AI tool's MCP configuration. Here's a minimal example for 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"
      }
    }
  }
}

Qdrant Cloud Configuration

For Qdrant Cloud, add your API key:

{
  "mcpServers": {
    "vibe-hnindex": {
      "command": "npx",
      "args": ["-y", "vibe-hnindex"],
      "env": {
        "OLLAMA_URL": "http://localhost:11434",
        "OLLAMA_MODEL": "bge-m3:567m",
        "QDRANT_URL": "https://xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.us-east-1-0.aws.cloud.qdrant.io:6333",
        "QDRANT_API_KEY": "your-qdrant-api-key"
      }
    }
  }
}

Verify Installation

Restart your AI tool after adding the MCP config. Then try these commands in chat:

Index the codebase at /path/to/project, name it my-project
Search my-project for authentication middleware
List all indexed projects

Next Steps