MCP + Milvus: connettere l'intelligenza artificiale con i database vettoriali

Introduzione

Il Model Context Protocol (MCP) è un protocollo aperto che consente alle applicazioni di IA, come Claude e Cursor, di interagire con fonti di dati e strumenti esterni senza soluzione di continuità. Che si tratti di costruire applicazioni AI personalizzate, integrare flussi di lavoro AI o migliorare le interfacce di chat, l'MCP fornisce un modo standardizzato per collegare i modelli linguistici di grandi dimensioni (LLM) con i dati contestuali pertinenti.

Questo tutorial spiega come configurare un server MCP per Milvus, consentendo alle applicazioni di IA di eseguire ricerche vettoriali, gestire collezioni e recuperare dati utilizzando comandi in linguaggio naturale, senza doverscrivere query di database personalizzate.

Prerequisiti

Prima di configurare il server MCP, assicurarsi di disporre di:

• Python 3.10 o superiore
• Un'istanza Milvus funzionante
• uv (consigliato per l'esecuzione del server)

Come iniziare

Il modo consigliato per utilizzare questo server MCP è di eseguirlo direttamente con uv senza installazione. Questo è il modo in cui sia Claude Desktop che Cursor sono configurati per usarlo negli esempi che seguono.

Se si desidera clonare il repository:

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

Allora è possibile eseguire il server direttamente:

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

Applicazioni supportate

Questo server MCP può essere utilizzato con diverse applicazioni AI che supportano il Model Context Protocol, come ad esempio:

• Claude Desktop: L'applicazione desktop di Anthropic per Claude.
• Cursor: Editor di codice alimentato dall'intelligenza artificiale con supporto MCP nella sua funzione Composer.
• Altri client MCP personalizzati Qualsiasi applicazione che implementi le specifiche del client MCP.

Utilizzo di MCP con Claude Desktop

1. Installare Claude Desktop.
2. Aprire il file di configurazione di Claude:
   • Su macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
3. Aggiungere la seguente configurazione:

{
  "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. Riavviare Claude Desktop per applicare le modifiche.

Utilizzo di MCP con Cursor

Cursor supporta anche gli strumenti MCP attraverso la funzione Agent di Composer. È possibile aggiungere il server MCP Milvus a Cursor in due modi:

Opzione 1: Utilizzando l'interfaccia utente delle impostazioni di Cursor.

1. Aprire Cursor Settings → Features → MCP.
2. Fare clic su + Add New MCP Server.
3. Compilare:
   • Tipo: stdio
   • Nome: milvus
   • Comando:

     /PATH/TO/uv --directory /path/to/mcp-server-milvus/src/mcp_server_milvus run server.py --milvus-uri http://127.0.0.1:19530
     

   • ⚠️ Suggerimento: Usare 127.0.0.1 invece di localhost per evitare potenziali problemi di risoluzione DNS.

Opzione 2: Utilizzo della configurazione specifica del progetto (consigliata)

1. Creare un file .cursor/mcp.json nella directory principale del progetto:

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

2. Riavviare Cursor per applicare la configurazione.

Dopo aver aggiunto il server, potrebbe essere necessario premere il pulsante di aggiornamento nelle impostazioni di MCP per popolare l'elenco degli strumenti. L'Agente Composer utilizzerà automaticamente gli strumenti Milvus quando sono rilevanti per le query.

Verifica dell'integrazione

Per verificare che il server MCP sia impostato correttamente:

Per il Cursore

1. Andare su Cursor Settings → Features → MCP.
2. Confermare che "Milvus" appare nell'elenco dei server MCP.
3. Controllare se gli strumenti Milvus (ad esempio, milvus_list_collections, milvus_vector_search) sono elencati.
4. Se compaiono errori, consultare la sezione Risoluzione dei problemi.

Strumenti del server MCP per Milvus

Questo server MCP fornisce diversi strumenti per la ricerca, l'interrogazione e la gestione dei dati vettoriali in Milvus. Per maggiori dettagli, consultare la documentazione di mcp-server-milvus.

🔍 Strumenti di ricerca e interrogazione

• milvus-text-search → Ricerca di documenti utilizzando la ricerca full text.
• milvus-vector-search → Eseguire una ricerca di similarità vettoriale su una raccolta.
• milvus-hybrid-search → Eseguire una ricerca ibrida che combini la similarità vettoriale e il filtraggio degli attributi.
• milvus-multi-vector-search → Eseguire una ricerca per similarità vettoriale con più vettori di query.
• milvus-query → Eseguire una ricerca su un insieme utilizzando espressioni di filtro.
• milvus-count → Contare le entità in una raccolta.

📁 Gestione delle raccolte

• milvus-list-collections → Elenco di tutte le raccolte nel database.
• milvus-collection-info → Ottenere informazioni dettagliate su una raccolta.
• milvus-get-collection-stats → Ottenere statistiche su una raccolta.
• milvus-create-collection → Creare una nuova collezione con lo schema specificato.
• milvus-load-collection → Caricare una collezione in memoria per la ricerca e l'interrogazione.
• milvus-release-collection → Rilasciare una collezione dalla memoria.
• milvus-get-query-segment-info → Ottenere informazioni sui segmenti della query.
• milvus-get-collection-loading-progress → Ottenere l'avanzamento del caricamento di una raccolta.

Operazioni sui dati

• milvus-insert-data → Inserire dati in una collezione.
• milvus-bulk-insert → Inserire i dati in batch per migliorare le prestazioni.
• milvus-upsert-data → Inserire i dati in una raccolta (inserire o aggiornare se esiste).
• milvus-delete-entities → Eliminare entità da una collezione in base a un'espressione di filtro.
• milvus-create-dynamic-field → Aggiungere un campo dinamico a una collezione esistente.

⚙️ Gestione degli indici

• milvus-create-index → Creare un indice su un campo vettoriale.
• milvus-get-index-info → Ottenere informazioni sugli indici in una collezione.

Variabili d'ambiente

• MILVUS_URI → URI del server Milvus (può essere impostato al posto di --milvus-uri).
• MILVUS_TOKEN → Token di autenticazione opzionale.
• MILVUS_DB → Nome del database (predefinito a "default").

Sviluppo

Per eseguire direttamente il server:

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

Esempi

Utilizzo di Claude Desktop

Esempio 1: Elenco delle collezioni

What are the collections I have in my Milvus DB?

Claude utilizzerà poi MCP per verificare queste informazioni sul nostro DB Milvus.

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

> View result from milvus-list-collections from milvus (local)

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

Esempio 2: Ricerca di documenti

Find documents in my text_collection that mention "machine learning"

Claude utilizzerà le funzionalità di ricerca full-text di Milvus per trovare i documenti rilevanti:

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]

Uso del cursore

Esempio: Creare una raccolta

Nel Compositore di Cursor, è possibile chiedere:

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

Cursor utilizzerà il server MCP per eseguire questa operazione:

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

> View result from milvus-create-collection from milvus (local)

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

Risoluzione dei problemi

Problemi comuni

Errori di connessione

Se si verificano errori come "Failed to connect to Milvus server":

1. Verificate che l'istanza di Milvus sia in esecuzione: docker ps (se si usa Docker)
2. Verificare che l'URI sia corretto nella configurazione
3. Assicurarsi che non ci siano regole del firewall che bloccano la connessione.
4. Provare a usare 127.0.0.1 invece di localhost nell'URI.

Problemi di autenticazione

Se si verificano errori di autenticazione:

1. Verificare che MILVUS_TOKEN sia corretto
2. Verificare se l'istanza di Milvus richiede l'autenticazione
3. Assicurarsi di avere i permessi corretti per le operazioni che si sta cercando di eseguire.

Strumento non trovato

Se gli strumenti MCP non appaiono in Claude Desktop o nel Cursore:

1. Riavviare l'applicazione
2. Controllare i log del server per verificare la presenza di eventuali errori
3. Verificare che il server MCP funzioni correttamente
4. Premere il pulsante di aggiornamento nelle impostazioni di MCP (per Cursor).

Aiuto

Se si continuano a riscontrare problemi:

1. Controllare i problemi di GitHub per problemi simili.
2. Unitevi al Discord della comunità Zilliz per ricevere supporto
3. Segnalate un nuovo problema con informazioni dettagliate sul vostro problema.

Conclusione

Seguendo questo tutorial, ora avete un server MCP funzionante, che abilita la ricerca vettoriale AI in Milvus. Sia che usiate Claude Desktop o Cursor, ora potete interrogare, gestire e cercare nel vostro database Milvus usando comandi in linguaggio naturale, senzascrivere codice per il database!