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

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

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

Предпосылки

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

• Python 3.10 или выше

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

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

Related MCP server: MCP Database Server

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

Рекомендуемый способ использования этого сервера 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 для тестирования.

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

Этот сервер 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:

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

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:

{
  "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"
      ]
    }
  }
}

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 следующим содержимым:

{
  "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": []
         }
       }
   }

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

После выполнения вышеуказанных шагов перезапустите 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»)

Разработка

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

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

Примеры

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

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

What are the collections I have in my Milvus DB?

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

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"

Клод будет использовать возможности полнотекстового поиска 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]

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

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

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

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

Курсор будет использовать сервер 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 (для курсора)

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

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

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

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

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