Zvec MCP Bridge

This repository contains a local MCP bridge that indexes project source files into a Zvec vector database and exposes semantic search through MCP tools.

What the bridge does

The current implementation is a stdio-based MCP server that:

• creates or opens a local Zvec collection at .zvec/knowledge.db inside the project root;
• embeds text chunks with the Hugging Face Transformers feature-extraction pipeline using Xenova/all-MiniLM-L6-v2;
• walks the project tree once at startup to build the initial index;
• watches for file add/change/delete events and updates the index automatically;
• exposes four MCP tools for search, re-indexing, single-file indexing, and status checks.

Requirements

• Node.js 18 or newer
• npm dependencies from the project package file
• a local model download on first use (the bridge uses the Hugging Face Transformers pipeline)

Installation

From the repository root:

npm install

Running the bridge

Run the bridge directly:

PROJECT_ROOT=/absolute/path/to/your/project node zvec-mcp-bridge.js

If PROJECT_ROOT is not provided, the bridge uses the current working directory.

MCP configuration example

This bridge is not tied to Google Antigravity specifically; it works with any MCP-compatible client that can launch a stdio process.

{
  "mcpServers": {
    "zvec-project-knowledge": {
      "command": "node",
      "args": ["/absolute/path/to/zvec-mcp-bridge.js"],
      "env": {
        "PROJECT_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

Supported files

The bridge indexes these file extensions:

• .js, .jsx, .ts, .tsx
• .kt, .erl, .hrl
• .py, .go, .java, .cs, .rb, .php
• .cpp, .c, .h, .hpp, .rs, .swift, .scala

It skips common config and lock files such as package.json, package-lock.json, tsconfig.json, vite.config.*, and similar files. It also ignores generated or dependency-heavy directories like node_modules, .git, dist, build, .cache, .next, and .vscode.

MCP tools

search_project_knowledge

Searches the local Zvec knowledge base for relevant code snippets.

Input:

• query (required): a natural-language search request
• exclude_paths (optional): path substrings to exclude from results
• include_paths (optional): path substrings that must be present in results

Behavior:

• the bridge creates embeddings for the query;
• it runs a vector search with topk: 15;
• results are filtered and re-ranked in JavaScript using keyword and path heuristics;
• each result includes a short explanation and the matched code chunk.

initialize_project_knowledge

Initializes the knowledge base and indexes the project contents.

Input:

• force_rebuild (optional): if true, clears the existing index before re-indexing

index_file

Indexes or refreshes a single file immediately.

Input:

• file_path (required): relative or absolute path to the file

get_knowledge_status

Returns current database status information such as:

• database path
• whether the database exists
• document count
• initialization state
• project root

Indexing details

• text is chunked into roughly 1000-character pieces with a 200-character overlap;
• the bridge stores each chunk as a document with fields for text_content, file_path, and language;
• the embedding vector field is named code_embedding.

Example prompt

A useful example prompt for the LLM can be taken from AGENTS.md.