Qdrant

resmi

Qdrant vektör arama motorunun üzerinde anlamsal bellek katmanı uygulayın

GitHub

1.5k

Qdrant MCP ile neler yapabilirsiniz?

Anıları sakla — Asistanınızdan qdrant-store ile bilgi kaydetmesini isteyin, isteğe bağlı olarak meta veri ekleyin ve belirli bir koleksiyonu hedefleyin.
Anlamsal arama — qdrant-find kullanarak doğal dil sorgusuyla ilgili saklanan bilgileri alın, sonuçlar QDRANT_SEARCH_LIMIT ile sınırlandırılır.
Kod parçacığı yönetimi — Araç açıklamalarını, kodu meta verilerle saklayacak ve Cursor veya Claude Code'da yeniden kullanım için anlamsal arama yoluyla alacak şekilde yapılandırın.
Salt okunur mod — QDRANT_READ_ONLY etkinleştirerek qdrant-store devre dışı bırakın ve yalnızca arama işlemlerine izin verin.

Dokümantasyon

mcp-server-qdrant: Bir Qdrant 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 oluşturuyor, ister bir sohbet arayüzünü geliştiriyor veya özel yapay zeka iş akışları oluşturuyor olun, MCP, LLM'leri ihtiyaç duydukları bağlama bağlamak için standart bir yol sağlar.

Bu depo, bir vektör arama motoru olan Qdrant için bir MCP sunucusunun nasıl oluşturulacağına dair bir örnektir.

Genel Bakış

Qdrant vektör arama motorunda anıları saklamak ve almak için resmi bir Model Context Protocol sunucusu. Qdrant veritabanının üzerinde anlamsal bir bellek katmanı olarak çalışır.

Bileşenler

Araçlar

qdrant-store
- Qdrant veritabanında bazı bilgileri sakla
- Girdi:
  - information (string): Saklanacak bilgi
  - metadata (JSON): Saklanacak isteğe bağlı meta veriler
  - collection_name (string): Bilginin saklanacağı koleksiyonun adı. Varsayılan koleksiyon adı yoksa bu alan zorunludur. Varsayılan bir koleksiyon adı varsa, bu alan etkin değildir.
- Döndürür: Onay mesajı
qdrant-find
- Qdrant veritabanından ilgili bilgileri al
- Girdi:
  - query (string): Arama için kullanılacak sorgu
  - collection_name (string): Bilginin saklanacağı koleksiyonun adı. Varsayılan koleksiyon adı yoksa bu alan zorunludur. Varsayılan bir koleksiyon adı varsa, bu alan etkin değildir.
- Döndürür: Qdrant veritabanında ayrı mesajlar olarak saklanan bilgiler

Ortam Değişkenleri

Yapılandırma ortam değişkenleri aracılığıyla yapılır. Tek komut satırı bağımsız değişkeni, taşıma protokolünü seçmek için kullanılan --transport'dir.

[!NOTE] QDRANT_URL ve QDRANT_LOCAL_PATH aynı anda sağlanamaz.

Ad	Açıklama	Varsayılan Değer
`QDRANT_URL`	Qdrant sunucusunun URL'si	Yok
`QDRANT_API_KEY`	Qdrant sunucusu için API anahtarı	Yok
`COLLECTION_NAME`	Kullanılacak varsayılan koleksiyonun adı.	Yok
`QDRANT_LOCAL_PATH`	Yerel Qdrant veritabanının yolu (`QDRANT_URL` alternatifi)	Yok
`EMBEDDING_PROVIDER`	Kullanılacak embedding sağlayıcısı (şu anda yalnızca "fastembed" desteklenmektedir)	`fastembed`
`EMBEDDING_MODEL`	Kullanılacak embedding modelinin adı	`sentence-transformers/all-MiniLM-L6-v2`
`TOOL_STORE_DESCRIPTION`	Store aracı için özel açıklama	Varsayılanı `settings.py` içinde görün
`TOOL_FIND_DESCRIPTION`	Find aracı için özel açıklama	Varsayılanı `settings.py` içinde görün
`QDRANT_SEARCH_LIMIT`	Aramadan döndürülecek maksimum sonuç sayısı	`10`
`QDRANT_READ_ONLY`	Salt okunur modu etkinleştir (`qdrant-store` aracını devre dışı bırakır)	`false`

FastMCP Ortam Değişkenleri

mcp-server-qdrant FastMCP tabanlı olduğundan, tüm FastMCP ortam değişkenlerini de destekler. En önemlileri aşağıda listelenmiştir:

Ortam Değişkeni	Açıklama	Varsayılan Değer
`FASTMCP_LOG_LEVEL`	Günlük düzeyini ayarlayın (DEBUG, INFO, WARNING, ERROR, CRITICAL)	`INFO`
`FASTMCP_SERVER_DEBUG`	Hata ayıklama modunu etkinleştir	`false`
`FASTMCP_SERVER_HOST`	Sunucuyu bağlamak için ana bilgisayar adresi	`127.0.0.1`
`FASTMCP_SERVER_PORT`	Sunucunun çalışacağı bağlantı noktası	`8000`
`FASTMCP_SERVER_ON_DUPLICATE_RESOURCES`	Yinelenen kaynaklar için davranış (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_TOOLS`	Yinelenen araçlar için davranış (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_PROMPTS`	Yinelenen istemler için davranış (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_DEPENDENCIES`	Sunucu ortamına kurulacak bağımlılıkların listesi	`[]`

[!NOTE] Sunucuya özel ayarlar FASTMCP_SERVER_ önekini kullanır. Bu, gelecek sürümlerde değişebilir.

Kurulum

uvx Kullanımı

uvx kullanıldığında mcp-server-qdrant'ı doğrudan çalıştırmak için belirli bir kurulum gerekmez.

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
uvx mcp-server-qdrant

Taşıma Protokolleri

Sunucu, --transport bayrağı kullanılarak belirtilebilen farklı taşıma protokollerini destekler:

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
uvx mcp-server-qdrant --transport sse

Desteklenen taşıma protokolleri:

stdio (varsayılan): Standart giriş/çıkış taşıması, yalnızca yerel MCP istemcileri tarafından kullanılabilir
sse: Sunucu Tarafından Gönderilen Olaylar taşıması, uzak istemciler için mükemmeldir
streamable-http: Akışkan HTTP taşıması, uzak istemciler için mükemmeldir, SSE'den daha yenidir

Belirtilmezse varsayılan taşıma stdio'dir.

SSE taşıması kullanıldığında, sunucu belirtilen bağlantı noktasını dinler ve gelen bağlantıları bekler. Varsayılan bağlantı noktası 8000'dir, ancak FASTMCP_SERVER_PORT ortam değişkeni kullanılarak değiştirilebilir.

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_SERVER_PORT=1234 \
uvx mcp-server-qdrant --transport sse

Docker Kullanımı

MCP sunucusunu oluşturmak ve çalıştırmak için bir Dockerfile mevcuttur:

# Build the container
docker build -t mcp-server-qdrant .

# Run the container
docker run -p 8000:8000 \
  -e FASTMCP_SERVER_HOST="0.0.0.0" \
  -e QDRANT_URL="http://your-qdrant-server:6333" \
  -e QDRANT_API_KEY="your-api-key" \
  -e COLLECTION_NAME="your-collection" \
  mcp-server-qdrant

[!TIP] Sunucunun tüm ağ arayüzlerini dinlemesini sağlamak için FASTMCP_SERVER_HOST="0.0.0.0" ayarladığımızı lütfen unutmayın. Bu, sunucuyu bir Docker kapsayıcısında çalıştırırken gereklidir.

Smithery ile Kurulum

Qdrant MCP Sunucusunu Claude Desktop için Smithery aracılığıyla otomatik olarak kurmak için:

npx @smithery/cli install mcp-server-qdrant --client claude

Claude Desktop'un Manuel Yapılandırması

Bu sunucuyu Claude Desktop uygulamasıyla kullanmak için, claude_desktop_config.json dosyanızın "mcpServers" bölümüne aşağıdaki yapılandırmayı ekleyin:

{
  "qdrant": {
    "command": "uvx",
    "args": ["mcp-server-qdrant"],
    "env": {
      "QDRANT_URL": "https://xyz-example.eu-central.aws.cloud.qdrant.io:6333",
      "QDRANT_API_KEY": "your_api_key",
      "COLLECTION_NAME": "your-collection-name",
      "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
    }
  }
}

Yerel Qdrant modu için:

{
  "qdrant": {
    "command": "uvx",
    "args": ["mcp-server-qdrant"],
    "env": {
      "QDRANT_LOCAL_PATH": "/path/to/qdrant/database",
      "COLLECTION_NAME": "your-collection-name",
      "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
    }
  }
}

Bu MCP sunucusu, belirtilen ada sahip bir koleksiyon yoksa otomatik olarak oluşturacaktır.

Varsayılan olarak, sunucu anıları kodlamak için sentence-transformers/all-MiniLM-L6-v2 embedding modelini kullanacaktır. Şimdilik yalnızca FastEmbed modelleri desteklenmektedir.

Diğer Araçlar için Destek

Bu MCP sunucusu, MCP uyumlu herhangi bir istemciyle kullanılabilir. Örneğin, Model Context Protocol için yerleşik destek sağlayan Cursor ve VS Code ile kullanabilirsiniz.

Cursor/Windsurf ile Kullanım

Araç açıklamalarını özelleştirerek bu MCP sunucusunu Cursor veya Windsurf için bir kod arama aracı olarak çalışacak şekilde yapılandırabilirsiniz:

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="code-snippets" \
TOOL_STORE_DESCRIPTION="Store reusable code snippets for later retrieval. \
The 'information' parameter should contain a natural language description of what the code does, \
while the actual code should be included in the 'metadata' parameter as a 'code' property. \
The value of 'metadata' is a Python dictionary with strings as keys. \
Use this whenever you generate some code snippet." \
TOOL_FIND_DESCRIPTION="Search for relevant code snippets based on natural language descriptions. \
The 'query' parameter should describe what you're looking for, \
and the tool will return the most relevant code snippets. \
Use this when you need to find existing code snippets for reuse or reference." \
uvx mcp-server-qdrant --transport sse # Enable SSE transport

Cursor/Windsurf'te, SSE taşıma protokolünü kullanarak bu çalışan sunucuyu işaret ederek MCP sunucusunu ayarlarınızda yapılandırabilirsiniz. Cursor'a MCP sunucusu ekleme açıklaması https://docs.cursor.com/context/model-context-protocol#adding-an-mcp-server-to-cursor bulunabilir. Cursor/Windsurf'ü yerel olarak çalıştırıyorsanız, aşağıdaki URL'yi kullanabilirsiniz:

http://localhost:8000/sse

[!TIP] Cursor/Windsurf'ü MCP sunucusuna bağlamak için tercih edilen yol olarak SSE taşımasını öneriyoruz, çünkü uzak bağlantıları destekleyebilir. Bu, sunucuyu ekibinizle paylaşmayı veya bulut ortamında kullanmayı kolaylaştırır.

Bu yapılandırma, Qdrant MCP sunucusunu şunları yapabilen özel bir kod arama aracına dönüştürür:

Kod parçacıklarını, belgeleri ve uygulama ayrıntılarını saklayın
Anlamsal aramaya dayalı ilgili kod örneklerini alın
Geliştiricilerin belirli uygulamaları veya kullanım desenlerini bulmasına yardımcı olun

Veritabanını, kod parçacıklarının doğal dil açıklamalarını (information parametresinde) gerçek kodla birlikte (metadata.code özelliğinde) saklayarak doldurabilir ve ardından ne aradığınızı açıklayan doğal dil sorgularıyla arayabilirsiniz.

[!NOTE] Yukarıda sağlanan araç açıklamaları örnektir ve özel kullanım durumunuz için özelleştirilmesi gerekebilir. Açıklamaları, ekibinizin iş akışına ve saklamak ve almak istediğiniz belirli kod parçacığı türlerine daha iyi uyacak şekilde ayarlamayı düşünün.

mcp-server-qdrant'u başarıyla kurduysanız ancak yine de Cursor ile çalıştıramıyorsanız, aracı yeni bir kod parçacığı ürettiğinde MCP araçlarının her zaman kullanılması için Cursor kurallarını oluşturmayı düşünün. Kuralları yalnızca belirli dosya türleri için çalışacak şekilde kısıtlayabilir, MCP sunucusunu belgeler veya diğer içerik türleri için kullanmaktan kaçınabilirsiniz.

Claude Code ile Kullanım

Claude Code'u bu MCP sunucusuna bağlayarak yeteneklerini geliştirebilir, mevcut kod tabanınız üzerinde anlamsal arama yapabilirsiniz.

mcp-server-qdrant'ı Kurma

MCP sunucusunu Claude Code'a ekleyin:

# Add mcp-server-qdrant configured for code search
claude mcp add code-search \
-e QDRANT_URL="http://localhost:6333" \
-e COLLECTION_NAME="code-repository" \
-e EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
-e TOOL_STORE_DESCRIPTION="Store code snippets with descriptions. The 'information' parameter should contain a natural language description of what the code does, while the actual code should be included in the 'metadata' parameter as a 'code' property." \
-e TOOL_FIND_DESCRIPTION="Search for relevant code snippets using natural language. The 'query' parameter should describe the functionality you're looking for." \
-- uvx mcp-server-qdrant

Sunucunun eklendiğini doğrulayın:
```
claude mcp list
```

Claude Code'da Anlamsal Kod Arama Kullanımı

TOOL_STORE_DESCRIPTION ve TOOL_FIND_DESCRIPTION içinde belirtilen araç açıklamaları, Claude Code'a MCP sunucusunun nasıl kullanılacağı konusunda rehberlik eder. Yukarıda sağlananlar örnektir ve özel kullanım durumunuz için özelleştirilmesi gerekebilir. Ancak Claude Code zaten şunları yapabilmelidir:

Kod parçacıklarını açıklamalarla saklamak için qdrant-store aracını kullanın.
İlgili kod parçacıklarını doğal dil kullanarak aramak için qdrant-find aracını kullanın.

MCP Sunucusunu Geliştirme Modunda Çalıştırma

MCP sunucusu, mcp dev komutu kullanılarak geliştirme modunda çalıştırılabilir. Bu, sunucuyu başlatır ve tarayıcınızda MCP denetçisini açar.

COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py

VS Code ile Kullanım

Tek tıkla kurulum için aşağıdaki kurulum düğmelerinden birine tıklayın:

Manuel Kurulum

VS Code'daki Kullanıcı Ayarları (JSON) dosyanıza aşağıdaki JSON bloğunu ekleyin. Bunu Ctrl + Shift + P tuşuna basarak ve Preferences: Open User Settings (JSON) yazarak yapabilirsiniz.

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "qdrantUrl",
        "description": "Qdrant URL"
      },
      {
        "type": "promptString",
        "id": "qdrantApiKey",
        "description": "Qdrant API Key",
        "password": true
      },
      {
        "type": "promptString",
        "id": "collectionName",
        "description": "Collection Name"
      }
    ],
    "servers": {
      "qdrant": {
        "command": "uvx",
        "args": ["mcp-server-qdrant"],
        "env": {
          "QDRANT_URL": "${input:qdrantUrl}",
          "QDRANT_API_KEY": "${input:qdrantApiKey}",
          "COLLECTION_NAME": "${input:collectionName}"
        }
      }
    }
  }
}

Veya Docker kullanmayı tercih ederseniz, bunun yerine şu yapılandırmayı ekleyin:

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "qdrantUrl",
        "description": "Qdrant URL"
      },
      {
        "type": "promptString",
        "id": "qdrantApiKey",
        "description": "Qdrant API Key",
        "password": true
      },
      {
        "type": "promptString",
        "id": "collectionName",
        "description": "Collection Name"
      }
    ],
    "servers": {
      "qdrant": {
        "command": "docker",
        "args": [
          "run",
          "-p", "8000:8000",
          "-i",
          "--rm",
          "-e", "QDRANT_URL",
          "-e", "QDRANT_API_KEY",
          "-e", "COLLECTION_NAME",
          "mcp-server-qdrant"
        ],
        "env": {
          "QDRANT_URL": "${input:qdrantUrl}",
          "QDRANT_API_KEY": "${input:qdrantApiKey}",
          "COLLECTION_NAME": "${input:collectionName}"
        }
      }
    }
  }
}

Alternatif olarak, çalışma alanınızda aşağıdaki içerikle bir .vscode/mcp.json dosyası oluşturabilirsiniz:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "qdrantUrl",
      "description": "Qdrant URL"
    },
    {
      "type": "promptString",
      "id": "qdrantApiKey",
      "description": "Qdrant API Key",
      "password": true
    },
    {
      "type": "promptString",
      "id": "collectionName",
      "description": "Collection Name"
    }
  ],
  "servers": {
    "qdrant": {
      "command": "uvx",
      "args": ["mcp-server-qdrant"],
      "env": {
        "QDRANT_URL": "${input:qdrantUrl}",
        "QDRANT_API_KEY": "${input:qdrantApiKey}",
        "COLLECTION_NAME": "${input:collectionName}"
      }
    }
  }
}

Docker ile çalışma alanı yapılandırması için bunu .vscode/mcp.json içinde kullanın:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "qdrantUrl",
      "description": "Qdrant URL"
    },
    {
      "type": "promptString",
      "id": "qdrantApiKey",
      "description": "Qdrant API Key",
      "password": true
    },
    {
      "type": "promptString",
      "id": "collectionName",
      "description": "Collection Name"
    }
  ],
  "servers": {
    "qdrant": {
      "command": "docker",
      "args": [
        "run",
        "-p", "8000:8000",
        "-i",
        "--rm",
        "-e", "QDRANT_URL",
        "-e", "QDRANT_API_KEY",
        "-e", "COLLECTION_NAME",
        "mcp-server-qdrant"
      ],
      "env": {
        "QDRANT_URL": "${input:qdrantUrl}",
        "QDRANT_API_KEY": "${input:qdrantApiKey}",
        "COLLECTION_NAME": "${input:collectionName}"
      }
    }
  }
}

Katkıda Bulunma

mcp-server-qdrant'ın nasıl geliştirilebileceğine dair önerileriniz varsa veya bir hata bildirmek istiyorsanız, bir sorun açın! Tüm katkıları memnuniyetle karşılıyoruz.

`mcp-server-qdrant`'u Yerel Olarak Test Etme

MCP denetçisi, MCP sunucularını test etmek ve hata ayıklamak için bir geliştirici aracıdır. Hem bir istemci arayüzü (varsayılan bağlantı noktası 5173) hem de bir MCP proxy sunucusu (varsayılan bağlantı noktası 3000) çalıştırır. Denetçiyi kullanmak için istemci arayüzünü tarayıcınızda açın.

QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py

Başlatıldıktan sonra, denetçi arayüzüne erişmek için tarayıcınızı http://localhost:5173 adresine açın.

Lisans

Bu MCP sunucusu, Apache License 2.0 kapsamında lisanslanmıştır. Bu, yazılımı Apache License 2.0'ın hüküm ve koşullarına tabi olarak kullanmakta, değiştirmekte ve dağıtmakta özgür olduğunuz anlamına gelir. Daha fazla ayrıntı için lütfen proje deposundaki LICENSE dosyasına bakın.