Milvus için MCP Sunucusu

Model Context Protocol (MCP), LLM uygulamalarıyla dış veri kaynakları ve araçlar arasında sorunsuz entegrasyon sağlayan açık bir protokoldür. AI destekli bir IDE oluşturuyor olsanız, sohbet arayüzünü geliştiriyor olsanız veya özel AI iş akışları oluşturuyor olsanız, MCP LLM'leri ihtiyaç duydukları bağlam ile bağlamak için standartlaştırılmış bir yol sağlar.

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

MCP with Milvus

Ön Koşullar

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

Python 3.10 veya daha yüksek sürüm
Çalışan bir Milvus instance'ı (yerel veya uzak)
uv yüklü (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. Bu, aşağıdaki örneklerde hem Claude Desktop hem de Cursor'un nasıl yapılandırıldığıdır.

Depoyu klonlamak istiyorsanız:

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

Daha sonra sunucuyu doğrudan çalıştırabilirsiniz:

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

Alternatif olarak, src/mcp_server_milvus/ dizinindeki .env dosyasını değiştirerek ortam değişkenlerini ayarlayabilir 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ıştırma Modları

Sunucu iki çalıştırma modunu destekler: stdio (varsayılan) ve SSE (Server-Sent Events).

Stdio Modu (Varsayılan)

Açıklama: İstemci ile standart giriş/çıkış aracılığıyla iletişim kurar. Mode belirtilmemişse bu varsayılan moddur.

Kullanım:

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

SSE Modu

Açıklama: HTTP Server-Sent Events kullanarak iletişim kurar. Bu mod, birden fazla istemcinin HTTP aracılığıyla bağlanmasına izin verir 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 portu 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ı şöyle görünecektir:
```
% 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 🚀
```
Daha sonra http://127.0.0.1:6274 adresinde MCP Inspector'a erişebilirsiniz.

Streamable HTTP Modu

Açıklama: İletişim için akış desteğine sahip HTTP kullanır. Bu, üretim dağıtımları için önerilen transport'tur ve hem stateful hem de stateless işlemi destekler.
Kullanım:
```
uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://localhost:19530 --port 8000
```
- --streamable-http: Streamable HTTP modunu etkinleştirir.
- --port: Sunucu için portu belirtir (varsayılan: 8000).
- --stateless: Stateless mod için isteğe bağlı bayrak (oturum kalıcılığı yok).

Stateless Modu:

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 desteğine sahip AI destekli kod editörü
Custom MCP clients: MCP client 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:

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

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

Streamable HTTP Modu Yapılandırması

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

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:

Claude Desktop'ı https://claude.ai/download adresinden yükleyin.
Claude Desktop yapılandırma dosyasını açın:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
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"
      ]
    }
  }
}

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

Cursor ile Kullanım

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

Entegrasyon Adımları

Cursor Settings > MCP açın
Add new global MCP server (Yeni global MCP sunucusu ekle) seçeneğini tıklayın
Tıkladıktan sonra, otomatik olarak mcp.json dosyasına yönlendirileceksiniz; 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 değiştirin:

{
  "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:

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 host adresinizi ve port yerine kullandığınız port numarasını yazın.

Hizmet çalışmaya başladıktan sonra, mcp.json dosyasını aşağıdaki içerikle değiştirin:

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

Streamable HTTP Modu İçin:

Hizmeti başlatın:

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

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'u yeniden başlatın veya pencereyi yenileyin.

Entegrasyonu Doğrulama

Cursor'un Milvus MCP sunucusu ile başarılı bir şekilde entegre olduğunu doğrulamak için:

Cursor Settings > MCP açın
Listede "milvus", "milvus-sse" veya "milvus-streamable-http" adının görünüp görünmediğini kontrol edin (seçtiğiniz moda bağlı olarak)
İlgili araçların listelendiğini doğrulayın (örn. milvus_list_collections, milvus_vector_search, vb.)
Sunucu etkinse ancak hata gösteriyorsa, aşağıdaki Sorun Giderme bölümünü kontrol edin

Kullanılabilir Araçlar

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

Arama ve Sorgu İşlemleri

milvus_text_search: Tam metin araması kullanarak belgeleri ara
- Parametreler:
  - collection_name: Araştırılacak 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 frekans terimlerinin oranı (0.0-1.0) (varsayılan: 0.2)
milvus_vector_search: Bir koleksiyonda vektör benzerliği araması gerçekleştir
- Parametreler:
  - collection_name: Araştırılacak 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: None)
  - range_filter: Aralık araması için isteğe bağlı üst sınır (varsayılan: None)
milvus_hybrid_search: Bir koleksiyonda hibrit arama gerçekleştir
- Parametreler:
  - collection_name: Araştırılacak 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: None)
  - sparse_range_filter: Seyrek aralık araması için isteğe bağlı üst sınır (varsayılan: None)
  - dense_radius: Yoğun aralık araması için isteğe bağlı alt sınır (varsayılan: None)
  - dense_range_filter: Yoğun aralık araması için isteğe bağlı üst sınır (varsayılan: None)
milvus_text_similarity_search: Bir koleksiyonda metin benzerliği araması gerçekleştir

Not: Bu araç yalnızca Milvus 2.6.0 ve sonraki sürümlerde desteklenir. Ve Milvus sunucusunda embedding işlevini ayarlamanız gerekir. Daha fazla bilgi için Embedding Function bölümüne bakın.
- Parametreler:
  - collection_name: Araştırılacak 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: None)
  - range_filter: Aralık araması için isteğe bağlı üst sınır (varsayılan: None)
milvus_query: Filtre ifadelerini kullanarak koleksiyonu sorgula
- 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 koleksiyon oluştur
- Parametreler:
  - collection_name: Yeni koleksiyonun adı
  - auto_id: İD'nin otomatik olarak oluşturulup oluşturulmayacağı, varsayılan True
  - dimension: Vektör boyutu, varsayılan 768; hızlı kurulum için ve field_schema sağlanırsa göz ardı edilecek
  - primary_field_name: Ana alan adı, varsayılan "id"; hızlı kurulum için ve field_schema sağlanırsa göz ardı edilecek
  - vector_field_name: Vektör alan adı, varsayılan "vector"; hızlı kurulum için ve field_schema sağlanırsa göz ardı edilecek
  - metric_type: Metrik tipi, varsayılan "COSINE"; hızlı kurulum için ve field_schema sağlanırsa göz ardı edilecek
  - field_schema: Alan şemasının listesi, her öğe aşağıdaki anahtarlarla bir sözlüktür:
    - name: Alanın adı
    - type: Alanın tipi
  - index_params: İsteğe bağlı indeks parametreleri listesi, her öğe aşağıdaki anahtarlarla bir sözlüktür:
    - field_name: İndekslenmesi gereken alanın adı
    - index_type: İndeks tipi
    - **kwargs: Diğer isteğe bağlı indeks parametreleri
  - other_kwargs: Koleksiyon oluşturması için ek anahtar sözcük argümanları
milvus_load_collection: Bir koleksiyonu arama ve sorgu için belleğe yükle
- Parametreler:
  - collection_name: Yüklenecek koleksiyonun adı
  - replica_number: Replika sayısı (varsayılan: 1)
milvus_release_collection: Bir koleksiyonu bellekten serbest bırak
- Parametreler:
  - collection_name: Serbest bırakılacak koleksiyonun adı
milvus_get_collection_info: Şema, özellikler, koleksiyon ID'si ve belirli bir koleksiyonun diğer metadata'sı gibi ayrıntılı bilgileri listele.
- Parametreler:
  - collection_name: Ayrıntılı bilgi almak istediğiniz koleksiyonun adı

Veri İşlemleri

milvus_insert_data: Bir koleksiyona veri ekle
- Parametreler:
  - collection_name: Koleksiyonun adı
  - data: Alan adlarını değer listelerine eşleyen sözlük
milvus_delete_entities: Filtre ifadesine bağlı olarak bir koleksiyondan varlıkları sil
- Parametreler:
  - collection_name: Koleksiyonun adı
  - filter_expr: Silinecek varlıkları seçmek için filtre ifadesi

Ortam Değişkenleri

MILVUS_URI: Milvus sunucusu URI'ı (--milvus-uri yerine ayarlanabilir)
MILVUS_TOKEN: İsteğe bağlı kimlik doğrulama tokeni
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'ı Kullanma

Ö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: Belge Arama

Find documents in my text_collection that mention "machine learning"

Claude, makine öğrenmesini içeren ilgili belgeleri bulmak için Milvus'un tam metin arama özelliklerini 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'u Kullanma

Örnek: Koleksiyon Oluşturma

Cursor'da şunları 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ı

"Failed to connect to Milvus server" gibi hatalar görüyorsanız:

Milvus instance'ınızın çalışıp çalışmadığını doğrulayın: docker ps (Docker kullanıyorsanız)
Yapılandırmanızdaki URI'nin doğru olduğunu kontrol edin
Bağlantıyı engelleyen güvenlik duvarı kuralları olmadığından emin olun
URI'de localhost yerine 127.0.0.1 kullanmayı deneyin

Kimlik Doğrulama Hataları

Kimlik doğrulama hataları görüyorsanız:

MILVUS_TOKEN değerinin doğru olduğunu doğrulayın
Milvus instance'ınızın kimlik doğrulama gerektirip gerektirmediğini kontrol edin
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:

Uygulamayı yeniden başlatın
Sunucu günlüklerinde hataları kontrol edin
MCP sunucusunun doğru şekilde çalışıp çalışmadığını doğrulayın
MCP ayarlarındaki yenile düğmesine basın (Cursor için)

Yardım Almak

Sorunları yaşamaya devam ediyorsanız:

Benzer sorunlar için GitHub Issues bölümünü kontrol edin
Destek için Milvus Community Discord kanalına katılın
Sorununuz hakkında ayrıntılı bilgi ile yeni bir issue açın

zilliztech/mcp-server-milvus

Bu MCP sunucusu hakkında