Milvus

Milvus için MCP Sunucusu

Model Context Protocol (MCP), LLM uygulamaları ile harici veri kaynakları ve araçlar arasında sorunsuz entegrasyon sağlayan açık bir protokoldür. İster yapay zeka destekli bir IDE geliştiriyor olun, ister bir sohbet arayüzünü geliştiriyor olun, isterse özel yapay zeka iş akışları oluşturuyor olun, MCP, LLM'leri ihtiyaç duydukları bağlamla bağlamak için standart bir yol sunar.

Bu depo, Milvus vektör veritabanı işlevselliğine erişim sağlayan bir MCP sunucusu içerir.

Ön Koşullar

Bu MCP sunucusunu kullanmadan önce aşağıdakilere sahip olduğunuzdan emin olun:

• Python 3.10 veya üstü
• Çalışan bir Milvus örneği (yerel veya uzak)
• uv kurulu (sunucuyu çalıştırmak için önerilir)

Kullanım

Bu MCP sunucusunu kullanmanın önerilen yolu, kurulum yapmadan doğrudan uv ile çalıştırmaktır. Aşağıdaki örneklerde hem Claude Desktop hem de Cursor bu şekilde kullanılmak üzere yapılandırılmıştır.

Depoyu klonlamak isterseniz:

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

Ardından sunucuyu doğrudan çalıştırabilirsiniz:

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

Alternatif olarak, ortam değişkenlerini ayarlamak için src/mcp_server_milvus/ dizinindeki .env dosyasını değiştirebilir ve sunucuyu aşağıdaki komutla çalıştırabilirsiniz:

uv run src/mcp_server_milvus/server.py

Önemli: .env dosyası, komut satırı argümanlarından daha yüksek önceliğe sahip olacaktır.

Çalışma Modları

Sunucu iki çalışma modunu destekler: stdio (varsayılan) ve SSE (Sunucu Tarafından Gönderilen Olaylar).

Stdio Modu (Varsayılan)

• Açıklama: İstemciyle standart giriş/çıkış üzerinden iletişim kurar. Herhangi bir mod belirtilmezse varsayılan mod budur.

• Kullanım:

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

SSE Modu

• Açıklama: İletişim için HTTP Sunucu Tarafından Gönderilen Olaylar'ı kullanır. Bu mod, birden fazla istemcinin HTTP üzerinden bağlanmasına olanak tanır ve web tabanlı uygulamalar için uygundur.

• Kullanım:

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

  • --sse: SSE modunu etkinleştirir.
  • --port: SSE sunucusu için bağlantı noktasını belirtir (varsayılan: 8000).

• SSE Modunda Hata Ayıklama:

  SSE modunda hata ayıklamak istiyorsanız, SSE hizmetini başlattıktan sonra aşağıdaki komutu girin:

  mcp dev src/mcp_server_milvus/server.py
  

  Çıktı aşağıdakine benzer olacaktır:

  % 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 🚀
  

  Ardından test için http://127.0.0.1:6274 adresinden MCP Inspector'a erişebilirsiniz.

Akışlı HTTP Modu

• Açıklama: İletişim için akış desteğine sahip HTTP kullanır. Bu, üretim dağıtımları için önerilen aktarım modudur ve hem durum bilgisi olan hem de olmayan çalışmayı destekler.

• Kullanım:

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

  • --streamable-http: Akışlı HTTP modunu etkinleştirir.
  • --port: Sunucu için bağlantı noktasını belirtir (varsayılan: 8000).
  • --stateless: Durum bilgisi olmayan mod için isteğe bağlı bayrak (oturum kalıcılığı yok).

• Durum Bilgisi Olmayan Mod:

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

Desteklenen Uygulamalar

Bu MCP sunucusu, Model Context Protocol'ü destekleyen çeşitli LLM uygulamalarıyla kullanılabilir:

• Claude Desktop: Anthropic'in Claude için masaüstü uygulaması
• Cursor: MCP destekli yapay zeka destekli kod düzenleyici
• Özel MCP istemcileri: MCP istemci belirtimini uygulayan herhangi bir uygulama

Claude Desktop ile Kullanım

Farklı Modlar için Yapılandırma

SSE Modu Yapılandırması

Claude Desktop'ı SSE modu için yapılandırmak üzere şu adımları izleyin:

1. Claude Desktop'ı https://claude.ai/download. adresinden yükleyin
2. Claude Desktop yapılandırma dosyanızı açın:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
3. SSE modu için aşağıdaki yapılandırmayı ekleyin:

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

Akışlı HTTP Modu Yapılandırması

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

4. Değişiklikleri uygulamak için Claude Desktop'ı yeniden başlatın.

Stdio Modu Yapılandırması

Stdio modu için şu adımları izleyin:

1. Claude Desktop'ı https://claude.ai/download. adresinden yükleyin
2. Claude Desktop yapılandırma dosyanızı açın:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
3. Stdio modu için aşağıdaki yapılandırmayı ekleyin:

{
  "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. Değişiklikleri uygulamak için Claude Desktop'ı yeniden başlatın.

Cursor ile Kullanım

Cursor ayrıca MCP'yi destekler araçlar. Milvus MCP sunucunuzu Cursor ile aşağıdaki adımları izleyerek entegre edebilirsiniz:

Entegrasyon Adımları

1. Cursor Settings > MCP öğesini açın
2. Add new global MCP server üzerine tıklayın
3. Tıkladıktan sonra, sizi otomatik olarak mcp.json dosyasına yönlendirecektir; bu dosya mevcut değilse oluşturulacaktır

mcp.json Dosyasını Yapılandırma

Stdio Modu İçin:

mcp.json dosyasını aşağıdaki içerikle üzerine yazın:

{
  "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 Modu İçin:

1. Aşağıdaki komutu çalıştırarak hizmeti başlatın:

   uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://your_sse_host --port port
   

   Not: http://your_sse_host yerine gerçek SSE ana bilgisayar adresinizi ve port yerine kullandığınız belirli bağlantı noktası numarasını yazın.

2. Hizmet çalışmaya başladıktan sonra, mcp.json dosyasını aşağıdaki içerikle üzerine yazın:

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

Akışlı HTTP Modu İçin:

1. Hizmeti başlatın:

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

2. mcp.json dosyasını güncelleyin:

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

Entegrasyonu Tamamlama

Yukarıdaki adımları tamamladıktan sonra, yapılandırmanın etkili olmasını sağlamak için Cursor'ı yeniden başlatın veya pencereyi yeniden yükleyin.

Entegrasyonu Doğrulama

Cursor'ın Milvus MCP sunucunuzla başarıyla entegre olduğunu doğrulamak için:

1. Cursor Settings > MCP öğesini açın
2. Listede "milvus", "milvus-sse" veya "milvus-streamable-http" öğelerinin görünüp görünmediğini kontrol edin (seçtiğiniz moda bağlı olarak)
3. İlgili araçların listelendiğini onaylayın (örn. milvus_list_collections, milvus_vector_search, vb.)
4. Sunucu etkin ancak bir hata gösteriyorsa, aşağıdaki Sorun Giderme bölümüne bakın

Kullanılabilir Araçlar

Sunucu aşağıdaki araçları sağlar:

Arama ve Sorgu İşlemleri

• milvus_text_search: Tam metin araması kullanarak belgeleri arayın

  • Parametreler:
    • collection_name: Aranacak koleksiyonun adı
    • query_text: Aranacak metin
    • limit: Döndürülecek maksimum sonuç sayısı (varsayılan: 5)
    • output_fields: Sonuçlara dahil edilecek alanlar
    • drop_ratio: Göz ardı edilecek düşük frekanslı terimlerin oranı (0.0-1.0) (varsayılan: 0.2)

• milvus_vector_search: Bir koleksiyonda vektör benzerlik araması yapın

  • Parametreler:
    • collection_name: Aranacak koleksiyonun adı
    • vector: Sorgu vektörü
    • vector_field: Vektör araması için alan adı (varsayılan: "vector")
    • limit: Döndürülecek maksimum sonuç sayısı (varsayılan: 5)
    • output_fields: Sonuçlara dahil edilecek alanlar
    • filter_expr: Filtre ifadesi
    • metric_type: Mesafe metriği (COSINE, L2, IP) (varsayılan: "COSINE")
    • radius: Aralık araması için isteğe bağlı alt sınır (varsayılan: Yok)
    • range_filter: Aralık araması için isteğe bağlı üst sınır (varsayılan: Yok)

• milvus_hybrid_search: Bir koleksiyonda hibrit arama yapın

  • Parametreler:
    • collection_name: Aranacak koleksiyonun adı
    • query_text: Arama için metin sorgusu
    • text_field: Metin araması için alan adı
    • vector: Metin sorgusunun vektörü
    • vector_field: Vektör araması için alan adı
    • limit: Döndürülecek maksimum sonuç sayısı (varsayılan: 5)
    • output_fields: Sonuçlara dahil edilecek alanlar
    • filter_expr: Filtre ifadesi
    • sparse_radius: Seyrek aralık araması için isteğe bağlı alt sınır (varsayılan: Yok)
    • sparse_range_filter: Seyrek aralık araması için isteğe bağlı üst sınır (varsayılan: Yok)
    • dense_radius: Yoğun aralık araması için isteğe bağlı alt sınır (varsayılan: Yok)
    • dense_range_filter: Yoğun aralık araması için isteğe bağlı üst sınır (varsayılan: Yok)

• milvus_text_similarity_search: Bir koleksiyonda metin benzerlik araması yapın

  Not: Bu araç yalnızca Milvus 2.6.0 ve üstü sürümlerde desteklenir. Ayrıca, gömme işlevini Milvus sunucusunda ayarlamanız gerekir. Daha fazla ayrıntı için Gömme İşlevi belgesine bakın.

  • Parametreler:
    • collection_name: Aranacak koleksiyonun adı
    • query_text: Benzerlik araması için metin sorgusu
    • anns_field: Metin araması için alan adı
    • limit: Döndürülecek maksimum sonuç sayısı (varsayılan: 5)
    • output_fields: Sonuçlara dahil edilecek alanlar
    • metric_type: Mesafe metriği (COSINE, L2, IP) (varsayılan: "COSINE")
    • filter_expr: İsteğe bağlı filtre ifadesi
    • radius: Aralık araması için isteğe bağlı alt sınır (varsayılan: Yok)
    • range_filter: Aralık araması için isteğe bağlı üst sınır (varsayılan: Yok)

• milvus_query: Filtre ifadeleri kullanarak koleksiyonu sorgulayın

  • Parametreler:
    • collection_name: Sorgulanacak koleksiyonun adı
    • filter_expr: Filtre ifadesi (örn. 'age > 20')
    • output_fields: Sonuçlara dahil edilecek alanlar
    • limit: Döndürülecek maksimum sonuç sayısı (varsayılan: 10)

Koleksiyon Yönetimi

• milvus_list_collections: Veritabanındaki tüm koleksiyonları listele

• milvus_create_collection: Hızlı kurulum veya özelleştirilmiş şema ile yeni bir koleksiyon oluştur

  • Parametreler:
    • collection_name: Yeni koleksiyon için ad
    • auto_id: Kimliğin otomatik oluşturulup oluşturulmayacağı, varsayılan True
    • dimension: Vektör boyutu, varsayılan 768; hızlı kurulum içindir ve field_schema sağlanırsa göz ardı edilir
    • primary_field_name: Birincil alanın adı, varsayılan "id"; hızlı kurulum içindir ve field_schema sağlanırsa göz ardı edilir
    • vector_field_name: Vektör alanının adı, varsayılan "vector"; hızlı kurulum içindir ve field_schema sağlanırsa göz ardı edilir
    • metric_type: Metrik türü, varsayılan "COSINE"; hızlı kurulum içindir ve field_schema sağlanırsa göz ardı edilir
    • field_schema: Alan şeması listesi, her öğe aşağıdaki anahtarlara sahip bir sözlüktür:
      • name: Alanın adı
      • type: Alanın türü
    • index_params: İsteğe bağlı dizin parametreleri listesi, her öğe aşağıdaki anahtarlara sahip bir sözlüktür:
      • field_name: Dizinlenecek alanın adı
      • index_type: Dizin türü
      • **kwargs: Diğer isteğe bağlı dizin parametreleri
    • other_kwargs: Koleksiyon oluşturma için ek anahtar kelime argümanları

• milvus_load_collection: Arama ve sorgu için bir koleksiyonu belleğe yükleyin

  • Parametreler:
    • collection_name: Yüklenecek koleksiyonun adı
    • replica_number: Çoğaltma sayısı (varsayılan: 1)

• milvus_release_collection: Bir koleksiyonu bellekten serbest bırakın

  • Parametreler:
    • collection_name: Serbest bırakılacak koleksiyonun adı

• milvus_get_collection_info: Belirli bir koleksiyonun şema, özellikler, koleksiyon kimliği ve diğer meta verileri gibi ayrıntılı bilgilerini listeler.

  • Parametreler:
    • collection_name: Hakkında ayrıntılı bilgi alınacak koleksiyonun adı

Veri İşlemleri

• milvus_insert_data: Bir koleksiyona veri ekleyin

  • Parametreler:
    • collection_name: Koleksiyonun adı
    • data: Alan adlarını değer listelerine eşleyen sözlük

• milvus_delete_entities: Filtre ifadesine dayalı olarak bir koleksiyondan varlıkları silin

  • Parametreler:
    • collection_name: Koleksiyonun adı
    • filter_expr: Silinecek varlıkları seçmek için filtre ifadesi

Ortam Değişkenleri

• MILVUS_URI: Milvus sunucu URI'si (--milvus-uri yerine ayarlanabilir)
• MILVUS_TOKEN: İsteğe bağlı kimlik doğrulama belirteci
• MILVUS_DB: Veritabanı adı (varsayılan "default")

Geliştirme

Sunucuyu doğrudan çalıştırmak için:

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

Örnekler

Claude Desktop Kullanımı

Örnek 1: Koleksiyonları Listeleme

What are the collections I have in my Milvus DB?

Claude daha sonra Milvus veritabanınızdaki bu bilgileri kontrol etmek için MCP'yi kullanacaktır.

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

Örnek 2: Belgeleri Arama

Find documents in my text_collection that mention "machine learning"

Claude, ilgili belgeleri bulmak için Milvus'un tam metin arama yeteneklerini kullanacaktır:

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 Kullanımı

Örnek: Bir Koleksiyon Oluşturma

Cursor'da şunu sorabilirsiniz:

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

Cursor bu işlemi yürütmek için MCP sunucusunu kullanacaktır:

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]

Sorun Giderme

Yaygın Sorunlar

Bağlantı Hataları

"Milvus sunucusuna bağlanılamadı" gibi hatalar görürseniz:

1. Milvus örneğinizin çalıştığını doğrulayın: docker ps (Docker kullanıyorsanız)
2. Yapılandırmanızdaki URI'nin doğru olduğundan emin olun
3. Bağlantıyı engelleyen güvenlik duvarı kuralları olmadığından emin olun
4. URI'de localhost yerine 127.0.0.1 kullanmayı deneyin

Kimlik Doğrulama Sorunları

Kimlik doğrulama hataları görürseniz:

1. MILVUS_TOKEN değerinizin doğru olduğunu doğrulayın
2. Milvus örneğinizin kimlik doğrulama gerektirip gerektirmediğini kontrol edin
3. Gerçekleştirmeye çalıştığınız işlemler için doğru izinlere sahip olduğunuzdan emin olun

Araç Bulunamadı

MCP araçları Claude Desktop veya Cursor'da görünmüyorsa:

1. Uygulamayı yeniden başlatın
2. Sunucu günlüklerinde hata olup olmadığını kontrol edin
3. MCP sunucusunun doğru şekilde çalıştığını doğrulayın
4. MCP ayarlarındaki yenile düğmesine basın (Cursor için)

Yardım Alma

Sorun yaşamaya devam ederseniz:

1. Benzer sorunlar için GitHub Issues sayfasını kontrol edin
2. Destek için Milvus Topluluk Discord sunucusuna katılın
3. Sorununuzla ilgili ayrıntılı bilgi içeren yeni bir konu açın