Milvus MCP Server

Данная программа представляет собой сервис доступа к векторной базе данных Milvus, разработанный для больших языковых моделей и соответствующий протоколу Model Context Protocol (MCP). Он может использоваться в качестве внешнего инструмента взаимодействия с векторной базой данных для больших языковых моделей (например, Antigravity).

Поддерживается векторная база данных Milvus 2.6, встроен сервис эмбеддингов, совместимый с OpenAI (например, Tongyi Qianwen text-embedding-v4), что позволяет большим моделям выполнять семантический поиск напрямую с помощью естественного языка.

💡 Ключевые особенности

1. Векторный поиск: Поддержка семантического поиска по текстовому вводу (автоматическое создание эмбеддингов) и поиск по исходным векторам.

2. Встроенные эмбеддинги: Интеграция с эндпоинтами, совместимыми с OpenAI; текст, передаваемый большой моделью, автоматически преобразуется в векторы, без необходимости во внешних сервисах эмбеддингов.

3. Управление жизненным циклом коллекций: Создание, просмотр и удаление коллекций, автоматическое создание индексов и загрузка при создании.

4. Чтение и запись данных: Поддержка вставки векторных данных и удаления по условию.

5. Управление несколькими подключениями: Определение нескольких именованных подключений через JSON-файл конфигурации; один экземпляр MCP Server может обслуживать несколько экземпляров Milvus.

6. Безопасность: Инструменты drop_collection и delete_entities являются независимыми и могут быть отдельно включены или выключены в MCP-клиенте; для drop_collection дополнительно требуется параметр confirmDrop=true в качестве двойной защиты.

7. Гибридный поиск: Поддержка комбинированных запросов: поиск по векторному сходству + скалярная фильтрация.

Related MCP server: Qdrant MCP Server

⚙️ Системные требования

1. Среда Node.js: Требуется версия Node.js v18 или выше.

2. Экземпляр Milvus: Требуется доступный экземпляр сервиса Milvus 2.6.

3. Embedding API: Требуется эндпоинт сервиса эмбеддингов, совместимый с OpenAI (например, платформа Tongyi Qianwen Bailian).

4. Зависимости: На машине, где выполняется запуск, необходимо выполнить npm install --omit=dev для установки зависимостей.

🛠 Установка и сборка

1. Сборка из исходного кода

npm install
npm run build

Результаты сборки будут размещены в директории ./dist.

2. Глобальная локальная установка

npm link

После выполнения команды можно использовать глобальную команду milvus-mcp-server в любом месте системы для быстрого запуска сервиса.

📝 Файл конфигурации

Используйте JSON-файл для настройки подключений к Milvus и сервиса эмбеддингов.

Пример файла конфигурации

{
  "connections": [
    {
      "name": "my-milvus",
      "address": "localhost:19530",
      "username": "root",
      "password": "Milvus",
      "database": "default",
      "description": "本地开发 Milvus 实例，存储文档和图片的向量索引"
    }
  ],
  "embedding": {
    "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "apiKey": "sk-your-api-key",
    "model": "text-embedding-v4",
    "dimensions": 1024
  }
}

Описание полей подключения

Описание полей Embedding

🚀 Запуск и использование

milvus-mcp-server --config <path-to-config.json>

Список параметров:

• -c, --config <path>: Путь к файлу конфигурации (обязательно).

🧠 Пример конфигурации MCP-клиента

На примере обычного MCP-клиента (например, Antigravity):

{
  "mcpServers": {
    "MilvusMCP": {
      "command": "node",
      "args": [
        "绝对路径/milvus_mcp_server/dist/index.js",
        "--config", "绝对路径/milvus-config.json"
      ]
    }
  }
}

🧰 Инструменты (Tools), доступные для модели

1. list_milvus_connections

• Описание: Выводит список всех настроенных подключений к Milvus (данные десенсибилизированы, пароли не отображаются).

• Параметры: Нет.

2. list_collections

• Описание: Выводит список всех коллекций для указанного подключения.

• Параметры:

  • connectionName (String): Имя целевого подключения.

3. describe_collection

• Описание: Получение подробной информации о схеме коллекции, включая определения полей, индексы и статистику количества строк.

• Параметры:

  • connectionName (String): Имя целевого подключения.

  • collectionName (String): Имя коллекции.

4. create_collection

• Описание: Создание новой коллекции. Автоматически создает индекс AUTOINDEX для векторного поля и загружает коллекцию, делая её доступной для поиска.

• Параметры:

  • connectionName (String): Имя целевого подключения.

  • collectionName (String): Имя новой коллекции.

  • description (String, опционально): Описание коллекции.

  • fields (Array): Массив определений полей, каждый элемент содержит name, dataType, isPrimaryKey?, autoId?, dimension?, maxLength?, description?.

5. drop_collection

• Описание: Безвозвратное удаление коллекции и всех её данных. Необратимая операция.

• Параметры:

  • connectionName (String): Имя целевого подключения.

  • collectionName (String): Имя коллекции для удаления.

  • confirmDrop (Boolean): Должно быть установлено в true для выполнения удаления. Механизм двойного подтверждения безопасности.

• Управление: Этот инструмент можно отдельно включить или отключить в MCP-клиенте.

6. insert_vectors

• Описание: Вставка данных в коллекцию. Каждая запись представляет собой JSON-объект, содержащий значения полей (включая векторное поле).

• Параметры:

  • connectionName (String): Имя целевого подключения.

  • collectionName (String): Имя целевой коллекции.

  • data (Array): Массив данных.

7. delete_entities

• Описание: Удаление сущностей по выражению фильтрации.

• Параметры:

  • connectionName (String): Имя целевого подключения.

  • collectionName (String): Имя целевой коллекции.

  • filter (String): Выражение фильтрации Milvus, например 'id in [1, 2, 3]'.

• Управление: Этот инструмент можно отдельно включить или отключить в MCP-клиенте.

8. vector_search

• Описание: Поиск по векторному сходству. Поддерживает передачу текста (автоматический вызов сервиса эмбеддингов для преобразования в вектор) или исходного вектора.

• Параметры:

  • connectionName (String): Имя целевого подключения.

  • collectionName (String): Имя целевой коллекции.

  • text (String, опционально): Текст для поиска, альтернатива vector.

  • vector (Number[], опционально): Исходный вектор для поиска, альтернатива text.

  • topK (Number, опционально): Количество возвращаемых результатов, по умолчанию 10.

  • filter (String, опционально): Выражение скалярной фильтрации.

  • outputFields (String[], опционально): Список возвращаемых полей.

9. query_entities

• Описание: Запрос сущностей по скалярным условиям, без использования векторного поиска.

• Параметры:

  • connectionName (String): Имя целевого подключения.

  • collectionName (String): Имя целевой коллекции.

  • filter (String): Выражение фильтрации Milvus.

  • outputFields (String[], опционально): Список возвращаемых полей.

  • limit (Number, опционально): Максимальное количество возвращаемых записей, по умолчанию 100.

10. hybrid_search

• Описание: Комбинированный запрос: векторный поиск + скалярная фильтрация. Отличие от vector_search заключается в том, что filter является обязательным параметром.

• Параметры:

  • connectionName (String): Имя целевого подключения.

  • collectionName (String): Имя целевой коллекции.

  • text (String, опционально): Текст для поиска, альтернатива vector.

  • vector (Number[], опционально): Исходный вектор для поиска, альтернатива text.

  • filter (String): Обязательно, выражение скалярной фильтрации.

  • topK (Number, опционально): Количество возвращаемых результатов, по умолчанию 10.

  • outputFields (String[], опционально): Список возвращаемых полей.