vectorai-mcp-server

Dieses Projekt stellt Actian VectorAI DB als MCP-Server bereit, damit Claude (Desktop oder Code) und Cursor Sammlungen erstellen, Dokumente erfassen und semantische Suche über einfache Tool-Aufrufe in natürlicher Sprache ausführen können – ohne manuelle Vektor-Mathematik, ohne clientseitigen Embedding-Code.

Das gesamte Embedding erfolgt serverseitig mit sentence-transformers (all-MiniLM-L6-v2, 384 Dimensionen). Jedes Werkzeug erwartet und liefert einfache Strings/JSON; rohe Vektoren überschreiten niemals die MCP-Grenze.

Dies ist ein Demo-Projekt für einen Hackathon-Vortrag, bewusst einfach gehalten, ohne Authentifizierung oder Multi-Tenancy.

Voraussetzungen

• Docker (zum Ausführen von VectorAI DB)

• Python 3.10+

Related MCP server: Qdrant MCP Server

1. VectorAI DB starten

Führen Sie im Projektstamm aus:

docker-compose up -d

Dies startet actian/vectorai:latest und stellt Folgendes bereit:

• 6573 - REST-API

• 6574 - gRPC-API (wird vom Python-Client verwendet)

• 6575 - Lokale UI

Die Daten bleiben in ./local_data über Neustarts hinweg erhalten. So prüfen Sie, ob es läuft:

docker ps
docker logs vectorai

2. Abhängigkeiten installieren

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

Kopieren Sie optional .env.example zu .env, wenn Sie die Standard-URL der VectorAI DB überschreiben möchten:

cp .env.example .env

3. Verbindung mit dem Demo-Skript prüfen

Bevor Sie einen MCP-Client anbinden, prüfen Sie, dass VectorAI DB und das Embedding-Modell beide funktionieren:

python examples/demo.py

Dies erstellt eine Sammlung hackathon_demo, embeddet und erfasst sechs Beispiel-FAQ-Dokumente, führt die Abfrage "when do we submit our project" aus und gibt die beste Übereinstimmung aus. Beim ersten Lauf wird das Modell all-MiniLM-L6-v2 (~90 MB) heruntergeladen, daher kann es eine Minute dauern.

Hinweis für Windows: sentence-transformers zieht torch nach sich, das einige sehr tief verschachtelte Lizenzdateien enthält. Wenn pip install mit WinError 206 („Dateiname oder -erweiterung ist zu lang“) fehlschlägt, aktivieren Sie entweder lange Pfade (Settings → System → About → Advanced system settings, oder setzen Sie LongPathsEnabled unter HKLM\SYSTEM\CurrentControlSet\Control\FileSystem auf 1 und starten Sie neu) oder klonen Sie das Projekt näher an Ihrem Laufwerksstamm (z. B. C:\dev\vectorai-mcp-server), um den Pfad zu verkürzen.

4. MCP-Server registrieren

Claude Desktop

Fügen Sie in claude_desktop_config.json (Speicherort variiert je nach Betriebssystem) unter mcpServers einen Eintrag vectorai-db hinzu. Verwenden Sie absolute Pfade zu Ihrer Python-Executable und zu server.py:

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

Unter Windows würde command wie folgt aussehen: C:\\absolute\\path\\to\\vectorai-mcp-server\\.venv\\Scripts\\python.exe.

Starten Sie Claude Desktop nach dem Speichern neu. Sie sollten vectorai-db als verbundenen MCP-Server sehen (suchen Sie nach dem 🔌/Tools-Symbol).

Cursor

Erstellen oder bearbeiten Sie .cursor/mcp.json im Projekt (oder ~/.cursor/mcp.json für eine globale Konfiguration) und fügen Sie denselben Server-Eintrag hinzu:

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

Laden Sie Cursor neu (oder schalten Sie den MCP-Server in Einstellungen → MCP aus und wieder ein), damit die Änderung übernommen wird. Sie sollten vectorai-db und seine sechs Werkzeuge (create_collection, ingest_documents, search, list_collections, get_collection_info, delete_collection) als verfügbar aufgelistet sehen.

5. Ausprobieren

Wenn VectorAI DB läuft und der MCP-Server verbunden ist, geben Sie Prompts wie diese in Claude oder Cursor ein:

• „Erstelle eine Sammlung namens notes."

• „Füge diese drei Fakten über unser Hackathon zu notes hinzu: Das Hackathon beginnt Samstag um 9 Uhr, Abgaben enden Sonntag um 9 Uhr, und der erste Preis beträgt 2.000 $."

• „Was ist die Abgabefrist für den Preis?"

• „Suche in notes nach irgendetwas zu Bewertungskriterien."

• „Liste alle Sammlungen in der Datenbank auf."

• „Wie viele Dokumente sind in notes?"

• „Lösche die Sammlung notes."

Der Assistent ruft create_collection, ingest_documents, search, list_collections, get_collection_info und delete_collection in Ihrem Namen auf und embeddet alles im Hintergrund mit all-MiniLM-L6-v2.

Projektstruktur

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