vectorai-mcp-server

Exponer Actian VectorAI DB como un servidor MCP, para que Claude (Desktop o Code) y Cursor puedan crear colecciones, ingerir documentos y realizar búsquedas semánticas mediante llamadas a herramientas en lenguaje natural: sin cálculos vectoriales manuales ni código de incrustación en el cliente.

Todas las incrustaciones se generan en el servidor con sentence-transformers (all-MiniLM-L6-v2, 384 dimensiones). Cada herramienta recibe y devuelve cadenas/JSON simples; los vectores sin procesar nunca cruzan el límite de MCP.

Este es un proyecto demo para una charla de hackathon, mantenido a propósito simple, sin autenticación ni multitenencia.

Requisitos previos

• Docker (para ejecutar VectorAI DB)

• Python 3.10+

Related MCP server: Qdrant MCP Server

1. Iniciar VectorAI DB

Desde la raíz del proyecto:

docker-compose up -d

Esto inicia actian/vectorai:latest, exponiendo:

• 6573 - API REST

• 6574 - API gRPC (utilizada por el cliente de Python)

• 6575 - Interfaz de usuario local

Los datos persisten en ./local_data entre reinicios. Comprueba que está ejecutándose con:

docker ps
docker logs vectorai

2. Instalar dependencias

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

Opcionalmente, copia .env.example a .env si quieres sobrescribir la URL predeterminada de VectorAI DB:

cp .env.example .env

3. Verificar la conexión con el script de demostración

Antes de conectar cualquier cliente MCP, comprueba que VectorAI DB y el modelo de incrustaciones funcionan correctamente:

python examples/demo.py

Esto crea una colección hackathon_demo, incrusta e ingiere seis documentos de ejemplo de preguntas frecuentes, ejecuta la consulta "when do we submit our project" e imprime la mejor coincidencia. La primera ejecución descarga el modelo all-MiniLM-L6-v2 (~90 MB), por lo que puede tardar un minuto.

Nota para Windows: sentence-transformers incorpora torch, que incluye algunos archivos de licencia profundamente anidados. Si pip install falla con WinError 206 ("filename or extension is too long"), habilita las rutas largas (Configuración → Sistema → Acerca de → Configuración avanzada del sistema, o establece LongPathsEnabled en HKLM\SYSTEM\CurrentControlSet\Control\FileSystem a 1 y reinicia) o clona el proyecto más cerca de la raíz de tu unidad (p. ej. C:\dev\vectorai-mcp-server) para acortar la ruta.

4. Registrar el servidor MCP

Claude Desktop

Edita tu claude_desktop_config.json (la ubicación varía según el sistema operativo) y añade una entrada vectorai-db bajo mcpServers. Usa rutas absolutas a tu ejecutable de Python y a 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"
      }
    }
  }
}

En Windows, command tendría este aspecto: C:\\absolute\\path\\to\\vectorai-mcp-server\\.venv\\Scripts\\python.exe.

Reinicia Claude Desktop después de guardar. Deberías ver vectorai-db listado como un servidor MCP conectado (busca el icono 🔌/tools).

Cursor

Crea o edita .cursor/mcp.json en el proyecto (o ~/.cursor/mcp.json para una configuración global) y añade la misma entrada de servidor:

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

Recarga Cursor (o activa/desactiva el servidor MCP en Configuración → MCP) para aplicar el cambio. Deberías ver vectorai-db y sus seis herramientas (create_collection, ingest_documents, search, list_collections, get_collection_info, delete_collection) disponibles.

5. Pruébalo

Con VectorAI DB ejecutándose y el servidor MCP conectado, escribe mensajes como estos en Claude o Cursor:

• "Crea una colección llamada notes."

• "Añade estos tres datos sobre nuestro hackathon a notes: el hackathon comienza el sábado a las 9 a. m., las inscripciones cierran el domingo a las 9 a. m. y el primer premio es de $2,000."

• "¿Cuál es la fecha límite del premio?"

• "Busca en notes cualquier cosa sobre los criterios de evaluación."

• "Lista todas las colecciones de la base de datos."

• "¿Cuántos documentos hay en notes?"

• "Elimina la colección notes."

El asistente llamará a create_collection, ingest_documents, search, list_collections, get_collection_info y delete_collection en tu nombre, incrustando todo con all-MiniLM-L6-v2 en segundo plano.

Estructura del proyecto

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