Milvus MCP Server

официальный

Поиск, запрос и взаимодействие с данными в вашей векторной базе данных Milvus.

GitHub
233

Документация

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

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

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

MCP with Milvus

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

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

  • Python 3.10 или выше
  • Запущенный экземпляр Milvus (локальный или удалённый)
  • Установленный uv (рекомендуется для запуска сервера)

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

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

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

git clone https://github.com/zilliztech/mcp-server-milvus.git
cd mcp-server-milvus

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

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

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

uv run src/mcp_server_milvus/server.py

Важно: файл .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 для тестирования.

Режим Streamable HTTP

  • Описание: Использует HTTP с поддержкой потоковой передачи для связи. Это рекомендуемый транспорт для промышленных развёртываний, поддерживающий как stateful, так и stateless режимы работы.

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

    uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://localhost:19530 --port 8000
    • --streamable-http: Включает режим Streamable HTTP.
    • --port: Указывает порт для сервера (по умолчанию: 8000).
    • --stateless: Опциональный флаг для stateless-режима (без сохранения сессии).

  • Stateless-режим:

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

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

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

  • Claude Desktop: Десктопное приложение Anthropic для Claude
  • Cursor: Редактор кода на базе ИИ с поддержкой 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:
{
  "mcpServers": {
    "milvus-sse": {
      "url": "http://your_sse_host:port/sse",
      "disabled": false,
      "autoApprove": []
    }
  }
}

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

{
  "mcpServers": {
    "milvus-streamable-http": {
      "url": "http://your_host:port/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}
  1. Перезапустите 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:
{
  "mcpServers": {
    "milvus": {
      "command": "/PATH/TO/uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-milvus/src/mcp_server_milvus",
        "run",
        "server.py",
        "--milvus-uri",
        "http://localhost:19530"
      ]
    }
  }
}
  1. Перезапустите Claude Desktop, чтобы применить изменения.

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

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

Шаги по интеграции

  1. Откройте Cursor Settings > MCP
  2. Нажмите на Add new global MCP server
  3. После нажатия вы будете автоматически перенаправлены к файлу mcp.json, который будет создан, если он не существует

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

Для режима Stdio:

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

{
  "mcpServers": {
    "milvus": {
      "command": "/PATH/TO/uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-milvus/src/mcp_server_milvus",
        "run",
        "server.py",
        "--milvus-uri",
        "http://127.0.0.1:19530"
      ]
    }
  }
}

Для режима 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": []
      }
    }
}

Для режима Streamable HTTP:

  1. Запустите службу:

    uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://your_host --port port

  2. Обновите mcp.json:

    {
  "mcpServers": {
    "milvus-streamable-http": {
      "url": "http://your_host:port/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

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

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

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

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

  1. Откройте Cursor Settings > MCP
  2. Проверьте, отображаются ли "milvus", "milvus-sse" или "milvus-streamable-http" в списке (в зависимости от выбранного вами режима)
  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) (по умолчанию: 0.2)

  • milvus_vector_search: Выполнить поиск по векторному сходству в коллекции

    • Параметры:
      • collection_name: Имя коллекции для поиска
      • vector: Вектор запроса
      • vector_field: Имя поля для векторного поиска (по умолчанию: "vector")
      • limit: Максимальное количество возвращаемых результатов (по умолчанию: 5)
      • output_fields: Поля, включаемые в результаты
      • filter_expr: Выражение фильтра
      • metric_type: Метрика расстояния (COSINE, L2, IP) (по умолчанию: "COSINE")
      • radius: Опциональная нижняя граница для поиска по диапазону (по умолчанию: None)
      • range_filter: Опциональная верхняя граница для поиска по диапазону (по умолчанию: None)

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

    • Параметры:
      • collection_name: Имя коллекции для поиска
      • query_text: Текстовый запрос для поиска
      • text_field: Имя поля для текстового поиска
      • vector: Вектор текстового запроса
      • vector_field: Имя поля для векторного поиска
      • limit: Максимальное количество возвращаемых результатов (по умолчанию: 5)
      • output_fields: Поля, включаемые в результаты
      • filter_expr: Выражение фильтра
      • sparse_radius: Опциональная нижняя граница для поиска по разреженному диапазону (по умолчанию: None)
      • sparse_range_filter: Опциональная верхняя граница для поиска по разреженному диапазону (по умолчанию: None)
      • dense_radius: Опциональная нижняя граница для поиска по плотному диапазону (по умолчанию: None)
      • dense_range_filter: Опциональная верхняя граница для поиска по плотному диапазону (по умолчанию: None)

  • milvus_text_similarity_search: Выполнить поиск по текстовому сходству в коллекции

    Примечание: Этот инструмент поддерживается только в Milvus 2.6.0 и выше. И вам необходимо настроить функцию эмбеддинга на сервере Milvus. Подробнее см. Embedding Function.

    • Параметры:
      • collection_name: Имя коллекции для поиска
      • query_text: Текстовый запрос для поиска по сходству
      • anns_field: Имя поля для текстового поиска
      • limit: Максимальное количество возвращаемых результатов (по умолчанию: 5)
      • output_fields: Поля, включаемые в результаты
      • metric_type: Метрика расстояния (COSINE, L2, IP) (по умолчанию: "COSINE")
      • filter_expr: Опциональное выражение фильтра
      • radius: Опциональная нижняя граница для поиска по диапазону (по умолчанию: None)
      • range_filter: Опциональная верхняя граница для поиска по диапазону (по умолчанию: None)

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

    • Параметры:
      • collection_name: Имя коллекции для запроса
      • filter_expr: Выражение фильтра (например, 'age > 20')
      • output_fields: Поля, включаемые в результаты
      • limit: Максимальное количество возвращаемых результатов (по умолчанию: 10)

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

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

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

    • Параметры:
      • collection_name: Имя новой коллекции
      • auto_id: автоматически генерировать id, по умолчанию True
      • dimension: размерность вектора, по умолчанию 768; для быстрой настройки, будет проигнорирован, если предоставлен field_schema
      • primary_field_name: имя первичного поля, по умолчанию "id"; для быстрой настройки, будет проигнорирован, если предоставлен field_schema
      • vector_field_name: имя векторного поля, по умолчанию "vector"; для быстрой настройки, будет проигнорирован, если предоставлен field_schema
      • metric_type: тип метрики, по умолчанию "COSINE"; для быстрой настройки, будет проигнорирован, если предоставлен field_schema
      • field_schema: Список схем полей, каждый элемент — словарь со следующими ключами:
        • name: имя поля
        • type: тип поля
      • index_params: Опциональный список параметров индекса, каждый элемент — словарь со следующими ключами:
        • field_name: имя индексируемого поля
        • index_type: тип индекса
        • **kwargs: другие опциональные параметры индекса
      • other_kwargs: Дополнительные именованные аргументы для создания коллекции

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

    • Параметры:
      • collection_name: Имя загружаемой коллекции
      • replica_number: Количество реплик (по умолчанию: 1)

  • milvus_release_collection: Выгрузить коллекцию из памяти

    • Параметры:
      • collection_name: Имя выгружаемой коллекции

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

    • Параметры:
      • 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")

Разработка

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

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

Примеры

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

Пример 1: Вывод списка коллекций

What are the collections I have in my Milvus DB?

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

I'll check what collections are available in your Milvus database.

Here are the collections in your Milvus database:

1. rag_demo
2. test
3. chat_messages
4. text_collection
5. image_collection
6. customized_setup
7. streaming_rag_demo

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

Find documents in my text_collection that mention "machine learning"

Claude будет использовать возможности полнотекстового поиска Milvus для поиска релевантных документов:

I'll search for documents about machine learning in your text_collection.

> View result from milvus-text-search from milvus (local)

Here are the documents I found that mention machine learning:
[Results will appear here based on your actual data]

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

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

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

Create a new collection called 'articles' in Milvus with fields for title (string), content (string), and a vector field (128 dimensions)

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

I'll create a new collection called 'articles' with the specified fields.

Collection 'articles' has been created successfully with the following schema:
- title: string
- content: string
- vector: float vector[128]

Устранение неполадок

Распространённые проблемы

Ошибки подключения

Если вы видите ошибки типа «Не удалось подключиться к серверу 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 (для Cursor)

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

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

  1. Проверьте GitHub Issues на наличие похожих проблем
  2. Присоединитесь к Milvus Community Discord для получения поддержки
  3. Создайте новый issue с подробной информацией о вашей проблеме