# 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:

```bash
npm install
```

## Running the bridge

Run the bridge directly:

```bash
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.

```json
{
  "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](AGENTS.md).