MCP-сервер для Milvus

Model Context Protocol (MCP) — это открытый протокол, который обеспечивает бесшовную интеграцию между приложениями LLM и внешними источниками данных и инструментами. Независимо от того, создаете ли вы IDE на базе ИИ, улучшаете интерфейс чата или создаете собственные рабочие процессы ИИ, MCP предоставляет стандартизированный способ подключения LLM к необходимому им контексту.

Этот репозиторий содержит сервер MCP, который обеспечивает доступ к функциональным возможностям векторной базы данных Milvus .

Предпосылки

Перед использованием этого сервера MCP убедитесь, что у вас есть:

• Python 3.10 или выше

• Работающий экземпляр Milvus (локальный или удаленный)

• uv установлен (рекомендуется для запуска сервера)

Использование

Рекомендуемый способ использования этого сервера MCP — запустить его напрямую с uv без установки. Вот как Claude Desktop и Cursor настроены для его использования в примерах ниже.

Если вы хотите клонировать репозиторий:

Затем вы можете запустить сервер напрямую:

В качестве альтернативы вы можете изменить файл .env в каталоге src/mcp_server_milvus/ чтобы задать переменные среды и запустить сервер с помощью следующей команды:

Важно: файл .env будет иметь более высокий приоритет, чем аргументы командной строки.

Режимы работы

Сервер поддерживает два режима работы: stdio (по умолчанию) и SSE (Server-Sent Events).

Режим Stdio (по умолчанию)

• Описание : Общается с клиентом через стандартный ввод/вывод. Это режим по умолчанию, если режим не указан.

• Использование:

  uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530

Режим SSE

• Описание : Использует HTTP Server-Sent Events для связи. Этот режим позволяет нескольким клиентам подключаться через HTTP и подходит для веб-приложений.

• Использование:

  uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://localhost:19530 --port 8000

  • --sse : Включает режим SSE.

  • --port : Указывает порт для сервера SSE (по умолчанию: 8000).

• Отладка в режиме SSE:

  Если вы хотите выполнить отладку в режиме SSE, после запуска службы SSE введите следующую команду:

  mcp dev src/mcp_server_milvus/server.py

  Вывод будет примерно таким:

  % mcp dev src/mcp_server_milvus/merged_server.py Starting MCP inspector... ⚙️ Proxy server listening on port 6277 🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀

  Затем вы можете получить доступ к MCP Inspector по адресу http://127.0.0.1:6274 для тестирования.

Поддерживаемые приложения

Этот сервер MCP можно использовать с различными приложениями LLM, которые поддерживают протокол контекста модели:

• Claude Desktop : настольное приложение Anthropic для Claude

• Курсор : редактор кода на базе искусственного интеллекта с поддержкой MCP

• Пользовательские клиенты MCP : любое приложение, реализующее спецификацию клиента MCP.

Использование с Claude Desktop

Конфигурация для разных режимов

Конфигурация режима SSE

Чтобы настроить Claude Desktop для режима SSE, выполните следующие действия:

1. Установите Claude Desktop с https://claude.ai/download .

2. Откройте файл конфигурации Claude Desktop:

   • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json

3. Добавьте следующую конфигурацию для режима SSE:

4. Перезапустите Claude Desktop, чтобы изменения вступили в силу.

Конфигурация режима stdio

Для режима stdio выполните следующие действия:

1. Установите Claude Desktop с https://claude.ai/download .

2. Откройте файл конфигурации Claude Desktop:

   • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json

3. Добавьте следующую конфигурацию для режима stdio:

4. Перезапустите Claude Desktop, чтобы изменения вступили в силу.

Использование с курсором

Cursor также поддерживает инструменты MCP . Вы можете интегрировать свой сервер Milvus MCP с Cursor, выполнив следующие шаги:

Этапы интеграции

1. Откройте Cursor Settings > MCP

2. Нажмите Add new global MCP server

3. После нажатия вы автоматически перейдете к файлу mcp.json , который будет создан, если его не существует.

Настройка файла mcp.json

Для стандартного режима:

Перезапишите файл mcp.json следующим содержимым:

Для режима SSE:

1. Запустите службу, выполнив следующую команду:

   uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://your_sse_host --port port

   Примечание : замените http://your_sse_host на фактический адрес вашего хоста SSE, а port на конкретный номер порта, который вы используете.

2. После запуска и запуска службы перезапишите файл mcp.json следующим содержимым:

   { "mcpServers": { "milvus-sse": { "url": "http://your_sse_host:port/sse", "disabled": false, "autoApprove": [] } } }

Завершение интеграции

После выполнения вышеуказанных шагов перезапустите Cursor или перезагрузите окно, чтобы убедиться, что конфигурация вступила в силу.

Проверка интеграции

Чтобы убедиться, что Cursor успешно интегрировался с вашим сервером Milvus MCP:

1. Откройте Cursor Settings > MCP

2. Проверьте, есть ли в списке «milvus» или «milvus-sse» (в зависимости от выбранного вами режима)

3. Убедитесь, что соответствующие инструменты перечислены (например, milvus_list_collections, milvus_vector_search и т. д.)

4. Если сервер включен, но выдает ошибку, проверьте раздел «Устранение неполадок» ниже.

Доступные инструменты

Сервер предоставляет следующие инструменты:

Операции поиска и запроса

• milvus_text_search : Поиск документов с помощью полнотекстового поиска

  • Параметры:

    • collection_name : Название коллекции для поиска

    • query_text : Текст для поиска

    • limit : максимальное количество возвращаемых результатов (по умолчанию: 5)

    • output_fields : Поля для включения в результаты

    • drop_ratio : доля низкочастотных терминов, которые следует игнорировать (0,0–1,0)

• milvus_vector_search : Выполнение поиска векторного сходства в коллекции

  • Параметры:

    • collection_name : Название коллекции для поиска

    • vector : Вектор запроса

    • vector_field : Имя поля для поиска вектора (по умолчанию: «vector»)

    • limit : максимальное количество возвращаемых результатов (по умолчанию: 5)

    • output_fields : Поля для включения в результаты

    • filter_expr : Выражение фильтра

    • metric_type : Метрика расстояния (КОСИНУС, L2, IP) (по умолчанию: «КОСИНУС»)

• milvus_hybrid_search : Выполнить гибридный поиск по коллекции

  • Параметры:

    • collection_name : Название коллекции для поиска

    • query_text : Текстовый запрос для поиска

    • text_field : Имя поля для текстового поиска

    • vector : Вектор текстового запроса

    • vector_field : Имя поля для поиска вектора

    • limit : максимальное количество возвращаемых результатов

    • output_fields : Поля для включения в результаты

    • filter_expr : Выражение фильтра

• milvus_query : Запрос коллекции с использованием выражений фильтра

  • Параметры:

    • collection_name : Имя коллекции для запроса

    • filter_expr : Выражение фильтра (например, «возраст > 20»)

    • output_fields : Поля для включения в результаты

    • limit : максимальное количество возвращаемых результатов (по умолчанию: 10)

Управление коллекциями

• milvus_list_collections : Список всех коллекций в базе данных

• milvus_create_collection : Создать новую коллекцию с указанной схемой

  • Параметры:

    • collection_name : Название новой коллекции

    • collection_schema : Определение схемы коллекции

    • index_params : Необязательные параметры индекса

• milvus_load_collection : Загрузка коллекции в память для поиска и запроса

  • Параметры:

    • collection_name : Имя коллекции для загрузки

    • replica_number : Количество реплик (по умолчанию: 1)

• milvus_release_collection : Освободить коллекцию из памяти

  • Параметры:

    • collection_name : Название коллекции для выпуска

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

  • Параметры:

    • collection_name : Название коллекции, о которой нужно получить подробную информацию

Операции с данными

• milvus_insert_data : вставить данные в коллекцию.

  • Параметры:

    • collection_name : Название коллекции

    • data : Словарь, сопоставляющий имена полей со списками значений

• milvus_delete_entities : Удаление сущностей из коллекции на основе выражения фильтра

  • Параметры:

    • collection_name : Название коллекции

    • filter_expr : Выражение фильтра для выбора объектов для удаления

Переменные среды

• MILVUS_URI : URI сервера Milvus (можно установить вместо --milvus-uri)

• MILVUS_TOKEN : Необязательный токен аутентификации

• MILVUS_DB : Имя базы данных (по умолчанию «default»)

Разработка

Чтобы запустить сервер напрямую:

Примеры

Использование Claude Desktop

Пример 1: Перечисление коллекций

Затем Клод проверит эту информацию в вашей базе данных Milvus с помощью MCP.

Пример 2: Поиск документов

Клод будет использовать возможности полнотекстового поиска Milvus для поиска соответствующих документов:

Использование курсора

Пример: Создание коллекции

В Курсоре вы можете спросить:

Курсор будет использовать сервер MCP для выполнения этой операции:

Поиск неисправностей

Общие проблемы

Ошибки соединения

Если вы видите ошибки типа «Не удалось подключиться к серверу Milvus»:

1. Убедитесь, что ваш экземпляр Milvus запущен: docker ps (если используется Docker)

2. Проверьте правильность URI в вашей конфигурации.

3. Убедитесь, что нет правил брандмауэра, блокирующих соединение.

4. Попробуйте использовать 127.0.0.1 вместо localhost в URI

Проблемы с аутентификацией

Если вы видите ошибки аутентификации:

1. Проверьте правильность MILVUS_TOKEN

2. Проверьте, требует ли ваш экземпляр Milvus аутентификации.

3. Убедитесь, что у вас есть необходимые разрешения для операций, которые вы пытаетесь выполнить.

Инструмент не найден

Если инструменты MCP не отображаются в Claude Desktop или Cursor:

1. Перезапустите приложение.

2. Проверьте журналы сервера на наличие ошибок.

3. Убедитесь, что сервер MCP работает правильно.

4. Нажмите кнопку обновления в настройках MCP (для курсора)

Получение помощи

Если проблемы продолжаются:

1. Проверьте GitHub Issues на предмет похожих проблем.

2. Присоединяйтесь к сообществу Zilliz в Discord для получения поддержки

3. Создайте новый вопрос с подробной информацией о вашей проблеме