Descrição Detalhada do Projeto mcp-server-milvus

Visão Geral do Projeto

mcp-server-milvus é um projeto de código aberto desenvolvido pela Zilliz Tech, que fornece uma implementação de servidor Model Context Protocol (MCP) para o banco de dados vetorial Milvus. Este projeto permite que aplicações LLM se integrem e acessem perfeitamente as funcionalidades do banco de dados vetorial Milvus através de um protocolo padronizado.

Principais Características e Funcionalidades

Ferramentas Operacionais Suportadas

O servidor MCP oferece as seguintes ferramentas principais:

• milvus_text_search: Pesquisa de documentos usando funcionalidade de pesquisa de texto completo

  • Parâmetros: collection_name, query_text, limit, output_fields, drop_ratio

• milvus_vector_search: Executa pesquisa de similaridade vetorial em uma coleção

  • Parâmetros: collection_name, vector, vector_field, limit, output_fields, metric_type

• milvus_query: Consulta uma coleção usando uma expressão de filtro

  • Parâmetros: collection_name, filter_expr, output_fields, limit

• milvus_list_collections: Lista todas as coleções no banco de dados

• milvus_create_collection: Cria uma nova coleção com um esquema especificado

  • Parâmetros: collection_name, collection_schema, index_params

• milvus_load_collection: Carrega uma coleção na memória para pesquisa e consulta

  • Parâmetros: collection_name, replica_number

• milvus_release_collection: Libera uma coleção da memória

  • Parâmetros: collection_name

• milvus_insert_data: Insere dados em uma coleção

  • Parâmetros: collection_name, data

• milvus_delete_entities: Exclui entidades de uma coleção com base em uma expressão de filtro

  • Parâmetros: collection_name, filter_expr

Requisitos do Sistema

• Python 3.10 ou superior
• Uma instância Milvus em execução (local ou remota)
• Ferramenta uv (recomendada para executar o servidor)

Instalação e Configuração

Clonar o Projeto

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

Executar o Servidor Diretamente

A maneira recomendada é usar uv para executar o servidor diretamente, sem instalação:

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

Ou definindo variáveis de ambiente no arquivo .env:

uv run src/mcp_server_milvus/server.py

Aplicações Cliente Suportadas

O servidor MCP pode ser usado com várias aplicações LLM que suportam o Model Context Protocol:

Integração com Claude Desktop

1. Instale o Claude Desktop
2. Configure o arquivo claude_desktop_config.json:

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

Integração com o Editor Cursor

O Cursor suporta duas formas de configuração:

Método 1: Configuração via GUI

1. Vá para Cursor Settings > Features > MCP
2. Clique no botão "+ Add New MCP Server"
3. Preencha o formulário:
   • Type: Selecione stdio
   • Name: milvus
   • Command: /PATH/TO/uv --directory /path/to/mcp-server-milvus/src/mcp_server_milvus run server.py --milvus-uri http://127.0.0.1:19530

Método 2: Arquivo de Configuração

Crie o arquivo .cursor/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"
      ]
    }
  }
}

Configuração de Variáveis de Ambiente

• MILVUS_URI: URI do servidor Milvus (alternativa para o parâmetro --milvus-uri)
• MILVUS_TOKEN: Token de autenticação opcional
• MILVUS_DB: Nome do banco de dados (o padrão é "default")

Exemplos de Uso

Uso no Claude Desktop

Os usuários podem interagir com o banco de dados Milvus usando linguagem natural:

Consultar a lista de coleções:

What are the collections I have in my Milvus DB?

Pesquisar documentos:

Find documents in my text_collection that mention "machine learning"

Uso no Cursor

Criar uma nova coleção:

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

Resolução de Problemas

Problemas de Conexão

• Verifique se a instância Milvus está em execução
• Verifique se a configuração do URI está correta
• Certifique-se de que as regras de firewall não estão bloqueando a conexão
• Tente usar 127.0.0.1 em vez de localhost

Problemas de Autenticação

• Verifique se o MILVUS_TOKEN está correto
• Verifique se a instância Milvus requer autenticação
• Certifique-se de ter as permissões corretas para executar a operação

Arquitetura Técnica

O projeto é desenvolvido em Python e utiliza uma cadeia de ferramentas de desenvolvimento moderna:

• Usa uv como ferramenta de gerenciamento de pacotes e execução
• Segue as especificações do protocolo padrão MCP
• Fornece encapsulamento completo das operações do banco de dados Milvus
• Suporta vários clientes de aplicações de IA

Casos de Uso

Este projeto é adequado principalmente para os seguintes cenários:

• Aprimoramento de editores de código orientados por IA
• Aprimoramento de contexto de interfaces de chat
• Construção de fluxos de trabalho de IA personalizados
• Integração de banco de dados vetorial com LLM
• Pesquisa semântica e aplicações RAG (Retrieval-Augmented Generation)

Através do mcp-server-milvus, os desenvolvedores podem facilmente integrar a poderosa funcionalidade do banco de dados vetorial Milvus em várias aplicações de IA, proporcionando aos usuários uma experiência de interação mais inteligente e precisa.