vectorai-mcp-server

Сделайте Actian VectorAI DB доступным в качестве MCP-сервера, чтобы Claude (Desktop или Code) и Cursor могли создавать коллекции, загружать документы и выполнять семантический поиск через простые вызовы инструментов на естественном языке — без ручных векторных вычислений и клиентского кода для эмбеддингов.

Все эмбеддинги выполняются на стороне сервера с помощью sentence-transformers (all-MiniLM-L6-v2, 384 измерения). Каждый инструмент принимает и возвращает обычные строки/JSON; сырые векторы никогда не пересекают границу MCP.

Это демонстрационный проект для доклада на хакатоне, намеренно упрощённый, без аутентификации и мультитенантности.

Предварительные требования

• Docker (для запуска VectorAI DB)

• Python 3.10+

Related MCP server: Qdrant MCP Server

1. Запустите VectorAI DB

Из корня проекта:

docker-compose up -d

Эта команда запускает actian/vectorai:latest и открывает:

• 6573 - REST API

• 6574 - gRPC API (используется Python-клиентом)

• 6575 - локальный UI

Данные сохраняются в ./local_data между перезапусками. Проверьте, что он работает, с помощью:

docker ps
docker logs vectorai

2. Установите зависимости

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

При необходимости скопируйте .env.example в .env, если хотите переопределить URL VectorAI DB по умолчанию:

cp .env.example .env

3. Проверьте подключение с помощью демонстрационного скрипта

Прежде чем подключать какой-либо MCP-клиент, убедитесь, что VectorAI DB и модель эмбеддингов работают:

python examples/demo.py

Скрипт создаёт коллекцию hackathon_demo, строит эмбеддинги и загружает шесть образцов документов FAQ, выполняет запрос "when do we submit our project" и выводит лучшее совпадение. При первом запуске загружается модель all-MiniLM-L6-v2 (~90 МБ), поэтому это может занять минуту.

Примечание для Windows: sentence-transformers тянет за собой torch, в составе которого есть глубоко вложенные файлы лицензий. Если pip install завершается с ошибкой WinError 206 («имя файла или расширение слишком длинное»), либо включите длинные пути (Параметры → Система → О системе → Дополнительные параметры системы, или установите LongPathsEnabled в 1 в разделе HKLM\SYSTEM\CurrentControlSet\Control\FileSystem и перезагрузитесь), либо склонируйте проект ближе к корню диска (например, C:\dev\vectorai-mcp-server), чтобы сократить путь.

4. Зарегистрируйте MCP-сервер

Claude Desktop

Отредактируйте файл claude_desktop_config.json (расположение зависит от ОС) и добавьте запись vectorai-db в раздел mcpServers. Используйте абсолютные пути к вашему исполняемому файлу Python и к 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"
      }
    }
  }
}

В Windows command будет выглядеть так: C:\\absolute\\path\\to\\vectorai-mcp-server\\.venv\\Scripts\\python.exe.

Перезапустите Claude Desktop после сохранения. Вы должны увидеть vectorai-db в списке подключённых MCP-серверов (найдите значок 🔌/tools).

Cursor

Создайте или отредактируйте .cursor/mcp.json в проекте (или ~/.cursor/mcp.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"
      }
    }
  }
}

Перезагрузите Cursor (или отключите и снова включите MCP-сервер в настройках → MCP), чтобы изменения вступили в силу. Вы должны увидеть vectorai-db и шесть его инструментов (create_collection, ingest_documents, search, list_collections, get_collection_info, delete_collection) в списке доступных.

5. Попробуйте

Когда VectorAI DB запущен и MCP-сервер подключён, введите в Claude или Cursor такие запросы:

• «Создай коллекцию с названием notes».

• «Добавь в notes три факта о нашем хакатоне: хакатон начинается в субботу в 9 утра, приём работ закрывается в воскресенье в 9 утра, а первый приз — $2,000».

• «Какой крайний срок, чтобы получить приз?»

• «Найди в notes что-нибудь о критериях оценки».

• «Перечисли все коллекции в базе данных».

• «Сколько документов в notes?»

• «Удали коллекцию notes».

Ассистент вызовет create_collection, ingest_documents, search, list_collections, get_collection_info и delete_collection от вашего имени, выполняя все эмбеддинги с помощью all-MiniLM-L6-v2 в фоновом режиме.

Структура проекта

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