# vectorai-mcp-server

Expose [Actian VectorAI DB](https://www.actian.com/databases/vectorai-db/) as an MCP server, so Claude (Desktop or Code) and Cursor can create collections, ingest documents, and run semantic search through plain natural-language tool calls - no manual vector math, no client-side embedding code.

All embedding happens server-side with `sentence-transformers` (`all-MiniLM-L6-v2`, 384 dimensions). Every tool takes and returns plain strings/JSON; raw vectors never cross the MCP boundary.

This is a demo project for a hackathon talk, kept intentionally simple, with no auth or multi-tenancy.

## Prerequisites

- [Docker](https://docs.docker.com/get-docker/) (to run VectorAI DB)
- Python 3.10+

## 1. Start VectorAI DB

From the project root:

```bash
docker-compose up -d
```

This starts `actian/vectorai:latest`, exposing:

- `6573` - REST API
- `6574` - gRPC API (used by the Python client)
- `6575` - Local UI

Data persists in `./local_data` across restarts. Check it's running with:

```bash
docker ps
docker logs vectorai
```

## 2. Install dependencies

```bash
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

Optionally copy `.env.example` to `.env` if you want to override the default VectorAI DB URL:

```bash
cp .env.example .env
```

## 3. Verify the connection with the demo script

Before wiring up any MCP client, sanity-check that VectorAI DB and the embedding model both work:

```bash
python examples/demo.py
```

This creates a `hackathon_demo` collection, embeds and ingests six sample FAQ documents, runs the query `"when do we submit our project"`, and prints the top match. The first run downloads the `all-MiniLM-L6-v2` model (~90 MB), so it may take a minute.

> **Windows note:** `sentence-transformers` pulls in `torch`, which ships some deeply nested license files. If `pip install` fails with `WinError 206` ("filename or extension is too long"), either enable long paths (`Settings → System → About → Advanced system settings`, or set `LongPathsEnabled` under `HKLM\SYSTEM\CurrentControlSet\Control\FileSystem` to `1` and reboot) or clone the project closer to your drive root (e.g. `C:\dev\vectorai-mcp-server`) to shorten the path.

## 4. Register the MCP server

### Claude Desktop

Edit your `claude_desktop_config.json` ([location varies by OS](https://modelcontextprotocol.io/quickstart/user)) and add a `vectorai-db` entry under `mcpServers`. Use absolute paths to your Python executable and to `server.py`:

```json
{
  "mcpServers": {
    "vectorai-db": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/vectorai-mcp-server/server.py"],
      "env": {
        "VECTORAI_URL": "localhost:6574"
      }
    }
  }
}
```

On Windows, `command` would look like `C:\\absolute\\path\\to\\vectorai-mcp-server\\.venv\\Scripts\\python.exe`.

Restart Claude Desktop after saving. You should see `vectorai-db` listed as a connected MCP server (look for the 🔌/tools icon).

### Cursor

Create or edit `.cursor/mcp.json` in the project (or `~/.cursor/mcp.json` for a global config) and add the same server entry:

```json
{
  "mcpServers": {
    "vectorai-db": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/vectorai-mcp-server/server.py"],
      "env": {
        "VECTORAI_URL": "localhost:6574"
      }
    }
  }
}
```

Reload Cursor (or toggle the MCP server off/on in Settings → MCP) to pick up the change. You should see `vectorai-db` and its six tools (`create_collection`, `ingest_documents`, `search`, `list_collections`, `get_collection_info`, `delete_collection`) listed as available.

## 5. Try it

With VectorAI DB running and the MCP server connected, type prompts like these into Claude or Cursor:

- "Create a collection called `notes`."
- "Add these three facts about our hackathon to `notes`: the hackathon starts Saturday at 9am, submissions close Sunday at 9am, and first prize is $2,000."
- "What's the prize deadline?"
- "Search `notes` for anything about judging criteria."
- "List all the collections in the database."
- "How many documents are in `notes`?"
- "Delete the `notes` collection."

The assistant will call `create_collection`, `ingest_documents`, `search`, `list_collections`, `get_collection_info`, and `delete_collection` on your behalf, embedding everything with `all-MiniLM-L6-v2` behind the scenes.

## Project structure

```
vectorai-mcp-server/
├── server.py            # The MCP server (FastMCP, stdio transport)
├── requirements.txt
├── docker-compose.yml    # Runs actian/vectorai:latest
├── .env.example
├── examples/
│   └── demo.py           # Standalone connection check, no MCP client needed
└── README.md
```