MCP Server for Milvus

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. Создайте новый вопрос с подробной информацией о вашей проблеме