Meilisearch MCP Server

resmi

Meilisearch ile etkileşim kurun ve sorgulama yapın (Tam metin ve anlamsal arama API'si)

GitHub
192

Dokümantasyon

Meilisearch

Meilisearch MCP Sunucusu

Meilisearch | Meilisearch Cloud | Dokümantasyon | Discord

PyPI version Python Versions Tests License Downloads

⚡ Herhangi bir LLM'i Meilisearch'e bağlayın ve yapay zekanızı ışık hızında arama yetenekleriyle güçlendirin! 🔍

🤔 Bu nedir?

Meilisearch MCP Sunucusu, MCP uyumlu herhangi bir istemcinin (Claude, OpenAI ajanları ve diğer LLM'ler dahil) Meilisearch ile etkileşime girmesini sağlayan bir Model Bağlam Protokolü sunucusudur. Bu stdio tabanlı sunucu, yapay zeka asistanlarının doğal konuşma yoluyla arama dizinlerini yönetmesine, aramalar yapmasına ve verilerinizi işlemesine olanak tanır.

Neden kullanmalısınız?

  • 🤖 Evrensel Uyumluluk - Yalnızca Claude değil, herhangi bir MCP istemcisiyle çalışır
  • 🗣️ Doğal Dil Kontrolü - Herhangi bir LLM ile konuşarak Meilisearch'i yönetin
  • 🚀 Sıfır Öğrenme Eğrisi - Meilisearch'ün API'sini öğrenmeye gerek yok
  • 🔧 Tam Özellik Erişimi - Tüm Meilisearch yetenekleri parmaklarınızın ucunda
  • 🔄 Dinamik Bağlantılar - Meilisearch örnekleri arasında anında geçiş yapın
  • 📡 stdio Taşıma - Şu anda stdio kullanır; yakında yerel Meilisearch MCP desteği geliyor!

✨ Temel Özellikler

  • 📊 Dizin & Belge Yönetimi - Arama dizinlerini oluşturun, güncelleyin ve yönetin
  • 🔍 Akıllı Arama - Gelişmiş filtreleme ile tek veya birden çok dizinde arama yapın
  • ⚙️ Ayarlar Yapılandırması - Arama alaka düzeyini ve performansını ince ayarlayın
  • 📈 Görev İzleme - Dizinleme ilerlemesini ve sistem işlemlerini takip edin
  • 🔐 API Anahtarı Yönetimi - Güvenli erişim kontrolü
  • 🏥 Sağlık İzleme - Meilisearch örneğinizi gözlemleyin
  • 🐍 Python Uygulaması - TypeScript sürümü de mevcut

🚀 Hızlı Başlangıç

Sadece 3 adımda çalışmaya başlayın!

1️⃣ Paketi yükleyin

# Using pip
pip install meilisearch-mcp

# Or using uvx (recommended)
uvx -n meilisearch-mcp

2️⃣ Claude Desktop'ı yapılandırın

Bunu claude_desktop_config.json dosyanıza ekleyin:

{
  "mcpServers": {
    "meilisearch": {
      "command": "uvx",
      "args": ["-n", "meilisearch-mcp"]
    }
  }
}

3️⃣ Meilisearch'i başlatın

# Using Docker (recommended)
docker run -d -p 7700:7700 getmeili/meilisearch:v1.28

# Or using Homebrew
brew install meilisearch
meilisearch

Hepsi bu kadar! Artık yapay zeka asistanınızdan Meilisearch verilerinizi aramasını ve yönetmesini isteyebilirsiniz! 🎉

📚 Örnekler

💬 Yapay zeka asistanınızla doğal bir şekilde konuşun:

You: "Create a new index called 'products' with 'id' as the primary key"
AI: I'll create that index for you... ✓ Index 'products' created successfully!

You: "Add some products to the index"
AI: I'll add those products... ✓ Added 5 documents to 'products' index

You: "Search for products under $50 with 'electronics' in the category"
AI: I'll search for those products... Found 12 matching products!

🔍 Gelişmiş Arama Örneği:

You: "Search across all my indices for 'machine learning' and sort by date"
AI: Searching across all indices... Found 47 results from 3 indices:
- 'blog_posts': 23 articles about ML
- 'documentation': 15 technical guides
- 'tutorials': 9 hands-on tutorials

🔧 Kurulum

Ön Koşullar

  • Python ≥ 3.9
  • Çalışan bir Meilisearch örneği
  • MCP uyumlu istemci (Claude Desktop, OpenAI ajanları, vb.)

PyPI'den

pip install meilisearch-mcp

Kaynaktan (geliştirme için)

# Clone repository
git clone https://github.com/meilisearch/meilisearch-mcp.git
cd meilisearch-mcp

# Create virtual environment and install
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

Docker Kullanarak

n8n iş akışları gibi konteynerleştirilmiş ortamlar için mükemmel!

Docker Hub'dan

# Pull the latest image
docker pull getmeili/meilisearch-mcp:latest

# Or a specific version
docker pull getmeili/meilisearch-mcp:0.5.0

# Run the container
docker run -it \
  -e MEILI_HTTP_ADDR=http://your-meilisearch:7700 \
  -e MEILI_MASTER_KEY=your-master-key \
  getmeili/meilisearch-mcp:latest

Kaynaktan Derleme

# Build your own image
docker build -t meilisearch-mcp .
docker run -it \
  -e MEILI_HTTP_ADDR=http://your-meilisearch:7700 \
  -e MEILI_MASTER_KEY=your-master-key \
  meilisearch-mcp

n8n ile Entegrasyon

n8n iş akışları için Docker imajını doğrudan kurulumunuzda kullanabilirsiniz:

meilisearch-mcp:
  image: getmeili/meilisearch-mcp:latest
  environment:
    - MEILI_HTTP_ADDR=http://meilisearch:7700
    - MEILI_MASTER_KEY=masterKey

🛠️ Neler Yapabilirsiniz?

🔗 Bağlantı Yönetimi
  • Mevcut bağlantı ayarlarını görüntüleyin
  • Meilisearch örnekleri arasında dinamik olarak geçiş yapın
  • API anahtarlarını anında güncelleyin
📁 Dizin İşlemleri
  • Özel birincil anahtarlarla yeni dizinler oluşturun
  • Tüm dizinleri istatistiklerle listeleyin
  • Dizinleri ve verilerini silin
  • Ayrıntılı dizin metriklerini alın
📄 Belge Yönetimi
  • Belgeleri ekleyin veya güncelleyin
  • Sayfalama ile belgeleri alın
  • Toplu veri içe aktarımı
🔍 Arama Yetenekleri
  • Filtreler, sıralama ve fasetlerle arama yapın
  • Çoklu dizin araması
  • Vektörlerle anlamsal arama
  • Hibrit arama (anahtar kelime + anlamsal)
⚙️ Ayarlar & Yapılandırma
  • Sıralama kurallarını yapılandırın
  • Fasetleme ve filtrelemeyi ayarlayın
  • Aranabilir öznitelikleri yönetin
  • Yazım hatası toleransını özelleştirin
🔐 Güvenlik
  • API anahtarları oluşturun ve yönetin
  • Ayrıntılı izinler belirleyin
  • Anahtar kullanımını izleyin

⚠️ Not: Kolaylık sağlamak için doğrudan sohbet içinde ana bilgisayarlar ve API anahtarları ekleyip güncelleyebilseniz de, bu yaklaşım öncelikle geliştirme kullanım durumları için tasarlanmıştır (anında birden çok örneğe bağlanmak gibi). En iyi MCP güvenlik uygulamalarını takip etmez ve uygun güvenlik önlemleri olmadan üretim ortamlarında kullanılmamalıdır.

📊 İzleme & Sağlık
  • Sağlık kontrolleri
  • Sistem istatistikleri
  • Görev izleme
  • Sürüm bilgisi

🌍 Ortam Değişkenleri

Varsayılan bağlantı ayarlarını yapılandırın:

MEILI_HTTP_ADDR=http://localhost:7700  # Default Meilisearch URL
MEILI_MASTER_KEY=your_master_key       # Optional: Default API key

💻 Geliştirme

Geliştirme Ortamını Kurma

  1. Meilisearch'i başlatın:

    docker run -d -p 7700:7700 getmeili/meilisearch:v1.28

  2. Geliştirme Bağımlılıklarını Yükleyin:

    uv pip install -r requirements-dev.txt

  3. Testleri Çalıştırın:

    python -m pytest tests/ -v

  4. Kodu Biçimlendirin:

    black src/ tests/

MCP Inspector ile Test Etme

npx @modelcontextprotocol/inspector python -m src.meilisearch_mcp

🤝 Topluluk & Destek

Sizden haber almayı çok isteriz! İşte yardım almanın ve bağlanmanın yolları:

🤗 Katkıda Bulunma

Katkılarınızı bekliyoruz! İşte başlama adımları:

  1. Depoyu çatallayın (fork)
  2. Özellik dalınızı oluşturun (git checkout -b feature/amazing-feature)
  3. Değişiklikleriniz için testler yazın
  4. Değişikliklerinizi yapın ve testleri çalıştırın
  5. Kodunuzu black ile biçimlendirin
  6. Değişikliklerinizi işleyin (git commit -m 'Add amazing feature')
  7. Dalınıza gönderin (git push origin feature/amazing-feature)
  8. Bir Çekme İsteği (Pull Request) açın

Daha fazla ayrıntı için Katkıda Bulunma Yönergelerimize bakın.

📦 Sürüm Süreci

Bu proje otomatik sürüm oluşturma ve yayınlama kullanır. pyproject.toml içindeki sürüm main dalında değiştiğinde, paket otomatik olarak PyPI'ye yayınlanır.

Ayrıntılı talimatlar için Sürüm Süreci bölümüne bakın.

📄 Lisans

Bu proje MIT Lisansı altında lisanslanmıştır - ayrıntılar için LICENSE dosyasına bakın.

Meilisearch, keyifli bir arama deneyimi sunan açık kaynaklı bir arama motorudur.
Meilisearch hakkında daha fazla bilgiyi meilisearch.com adresinde bulabilirsiniz

📖 Tam Dokümantasyon

Mevcut Araçlar

Bağlantı Yönetimi

  • get-connection-settings: Mevcut Meilisearch bağlantı URL'sini ve API anahtarı durumunu görüntüleyin
  • update-connection-settings: Farklı bir örneğe bağlanmak için URL ve/veya API anahtarını güncelleyin

Dizin Yönetimi

  • create-index: İsteğe bağlı birincil anahtarla yeni bir dizin oluşturun
  • list-indexes: Mevcut tüm dizinleri listeleyin
  • delete-index: Mevcut bir dizini ve tüm belgelerini silin
  • get-index-metrics: Belirli bir dizin için ayrıntılı metrikleri alın

Belge İşlemleri

  • get-documents: Sayfalama ile bir dizinden belgeleri alın
  • add-documents: Bir dizine belge ekleyin veya güncelleyin

Arama

  • search: Filtreleme ve sıralama seçenekleriyle tek veya birden çok dizinde esnek arama

Ayarlar Yönetimi

  • get-settings: Bir dizin için mevcut ayarları görüntüleyin
  • update-settings: Dizin ayarlarını güncelleyin (sıralama, fasetleme, vb.)

API Anahtarı Yönetimi

  • get-keys: Tüm API anahtarlarını listeleyin
  • create-key: Belirli izinlerle yeni API anahtarı oluşturun
  • delete-key: Mevcut bir API anahtarını silin

Görev Yönetimi

  • get-task: Belirli bir görev hakkında bilgi alın
  • get-tasks: İsteğe bağlı filtrelerle görevleri listeleyin
  • cancel-tasks: Bekleyen veya sıraya alınmış görevleri iptal edin
  • delete-tasks: Tamamlanmış görevleri silin

Sistem İzleme

  • health-check: Temel sağlık kontrolü
  • get-health-status: Kapsamlı sağlık durumu
  • get-version: Meilisearch sürüm bilgisini alın
  • get-stats: Veritabanı istatistiklerini alın
  • get-system-info: Sistem düzeyinde bilgi alın

Geliştirme Kurulumu

Ön Koşullar

  1. Meilisearch sunucusunu başlatın:

    # Using Docker (recommended for development)
docker run -d -p 7700:7700 getmeili/meilisearch:v1.28

# Or using brew (macOS)
brew install meilisearch
meilisearch

# Or download from https://github.com/meilisearch/meilisearch/releases

  2. Geliştirme araçlarını yükleyin:

    # Install uv for Python package management
pip install uv

# Install Node.js for MCP Inspector testing
# Visit https://nodejs.org/ or use your package manager

Testleri Çalıştırma

Bu proje, MCP aracı işlevselliğini doğrulayan kapsamlı entegrasyon testleri içerir:

# Run all tests
python -m pytest tests/ -v

# Run specific test file
python -m pytest tests/test_mcp_client.py -v

# Run tests with coverage report
python -m pytest --cov=src tests/

# Run tests in watch mode (requires pytest-watch)
pytest-watch tests/

Önemli: Testler, http://localhost:7700 üzerinde çalışan bir Meilisearch örneği gerektirir.

Kod Kalitesi

# Format code with Black
black src/ tests/

# Run type checking (if mypy is configured)
mypy src/

# Lint code (if flake8 is configured)
flake8 src/ tests/

Katkıda Bulunma Yönergeleri

  1. Depoyu çatallayın ve klonlayın
  2. Geliştirme ortamını kurun, yukarıdaki Geliştirme Kurulumu bölümünü takip ederek
  3. Bir özellik dalı oluşturun, main dalından
  4. Yeni işlevsellik ekliyorsanız önce testleri yazın (Test Odaklı Geliştirme)
  5. İşlemeden önce tüm testlerin geçtiğinden emin olmak için testleri yerel olarak çalıştırın
  6. Kodu Black ile biçimlendirin ve kod kalitesini sağlayın
  7. Değişiklikleri açıklayıcı işleme mesajlarıyla işleyin
  8. Çatalınıza gönderin ve bir çekme isteği oluşturun

Geliştirme İş Akışı

# Create feature branch
git checkout -b feature/your-feature-name

# Make your changes, write tests first
# Edit files...

# Run tests to ensure everything works
python -m pytest tests/ -v

# Format code
black src/ tests/

# Commit and push
git add .
git commit -m "Add feature description"
git push origin feature/your-feature-name

Test Yönergeleri

  • Tüm yeni özellikler test içermelidir
  • Testler, PR'lar gönderilmeden önce geçmelidir
  • Açıklayıcı test adları ve net onaylamalar kullanın
  • Hem başarı hem de hata durumlarını test edin
  • Testleri çalıştırmadan önce Meilisearch'ün çalıştığından emin olun

Sürüm Süreci

Bu proje, PyPI'ye otomatik sürüm oluşturma ve yayınlama kullanır. Sürüm süreci basit ve otomatik olacak şekilde tasarlanmıştır.

Sürümler Nasıl Çalışır

  1. Otomatik Yayınlama: pyproject.toml içindeki sürüm numarası main dalında değiştiğinde, bir GitHub Eylemi otomatik olarak:

    • Python paketini oluşturur
    • Güvenilir yayıncılık kullanarak PyPI'ye yayınlar
    • GitHub'da yeni bir sürüm oluşturur

  2. Sürüm Tespiti: İş akışı, değişiklikleri tespit etmek için pyproject.toml içindeki mevcut sürümü önceki işleme ile karşılaştırır

  3. PyPI Yayınlama: Güvenilir yayıncılık ile PyPA'nın resmi yayınlama eylemini kullanır (manuel API anahtarlarına gerek yoktur)

Yeni Bir Sürüm Oluşturma

Yeni bir sürüm oluşturmak için şu adımları izleyin:

1. Sürüm Numarasını Belirleyin

Anlamsal Sürümlemeyi (MAJOR.MINOR.PATCH) takip edin:

  • PATCH (örn., 0.4.0 → 0.4.1): Hata düzeltmeleri, dokümantasyon güncellemeleri, küçük iyileştirmeler
  • MINOR (örn., 0.4.0 → 0.5.0): Yeni özellikler, yeni MCP araçları, önemli geliştirmeler
  • MAJOR (örn., 0.5.0 → 1.0.0): Kırıcı değişiklikler, büyük API değişiklikleri
2. Sürümü Güncelleyin ve PR Oluşturun
# 1. Create a branch from latest main
git checkout main
git pull origin main
git checkout -b release/v0.5.0

# 2. Update version in pyproject.toml
# Edit the version = "0.4.0" line to your new version

# 3. Commit and push
git add pyproject.toml
git commit -m "Bump version to 0.5.0"
git push origin release/v0.5.0

# 4. Create PR and get it reviewed/merged
gh pr create --title "Release v0.5.0" --body "Bump version for release"
3. Ana Dala Birleştirin

PR onaylanıp main dalına birleştirildiğinde, GitHub Eylemi otomatik olarak:

  1. Sürüm değişikliğini tespit eder
  2. Paketi oluşturur
  3. https://pypi.org/p/meilisearch-mcp adresinde PyPI'ye yayınlar
  4. Yeni sürümü pip install meilisearch-mcp aracılığıyla kullanılabilir hale getirir
4. Sürümü Doğrulayın

Birleştirdikten sonra sürümü doğrulayın:

# Check GitHub Action status
gh run list --workflow=publish.yml

# Verify on PyPI (may take a few minutes)
pip index versions meilisearch-mcp

# Test installation of new version
pip install --upgrade meilisearch-mcp

Sürüm İş Akışı Dosyası

Otomatik sürüm, .github/workflows/publish.yml tarafından yönetilir ve şunları yapar:

  • main dalına yapılan göndermelerde tetiklenir
  • pyproject.toml sürümünün değişip değişmediğini kontrol eder
  • Python 3.10 ve resmi derleme araçlarını kullanır
  • Güvenilir yayıncılık kullanarak yayınlar (API anahtarı gerekmez)
  • Hata ayıklama için ayrıntılı çıktı sağlar

Sürüm Sorunlarını Giderme

Sürüm tetiklenmedi: pyproject.toml içindeki sürümün işlemeler arasında gerçekten değiştiğini kontrol edin

Derleme başarısız oldu: Python paketi derleme hataları için GitHub Eylemleri günlüklerini kontrol edin

PyPI yayını başarısız oldu: Paket adını ve güvenilir yayıncılığın düzgün yapılandırıldığını doğrulayın Sürüm çakışmaları: Yeni sürüm numarasının PyPI'da daha önce kullanılmadığından emin olun

Geliştirme ve Üretim Sürümleri

  • Geliştirme: pip install -e . kullanarak kaynaktan yükleyin
  • Üretim: pip install meilisearch-mcp kullanarak PyPI'dan yükleyin
  • Belirli sürüm: pip install meilisearch-mcp==0.5.0 kullanarak yükleyin