Meilisearch MCP Server

resmi

Berinteraksi dan melakukan kueri dengan Meilisearch (API pencarian teks lengkap & semantik)

GitHub
192

Dokumentasi

Meilisearch

Server MCP Meilisearch

Meilisearch | Meilisearch Cloud | Dokumentasi | Discord

PyPI version Python Versions Tests License Downloads

āš” Hubungkan LLM apa pun ke Meilisearch dan perkaya AI Anda dengan kemampuan pencarian secepat kilat! šŸ”

šŸ¤” Apa ini?

Server MCP Meilisearch adalah server Model Context Protocol yang memungkinkan klien yang kompatibel dengan MCP (termasuk Claude, agen OpenAI, dan LLM lainnya) untuk berinteraksi dengan Meilisearch. Server berbasis stdio ini memungkinkan asisten AI untuk mengelola indeks pencarian, melakukan pencarian, dan menangani data Anda melalui percakapan alami.

Mengapa menggunakan ini?

  • šŸ¤– Kompatibilitas Universal - Bekerja dengan klien MCP apa pun, bukan hanya Claude
  • šŸ—£ļø Kontrol Bahasa Alami - Kelola Meilisearch melalui percakapan dengan LLM apa pun
  • šŸš€ Tanpa Kurva Pembelajaran - Tidak perlu mempelajari API Meilisearch
  • šŸ”§ Akses Fitur Penuh - Semua kemampuan Meilisearch di ujung jari Anda
  • šŸ”„ Koneksi Dinamis - Beralih antar instans Meilisearch dengan cepat
  • šŸ“” Transport stdio - Saat ini menggunakan stdio; dukungan MCP Meilisearch asli segera hadir!

āœØ Fitur Utama

  • šŸ“Š Manajemen Indeks & Dokumen - Buat, perbarui, dan kelola indeks pencarian
  • šŸ” Pencarian Cerdas - Cari di satu atau beberapa indeks dengan penyaringan lanjutan
  • āš™ļø Konfigurasi Pengaturan - Sempurnakan relevansi dan kinerja pencarian
  • šŸ“ˆ Pemantauan Tugas - Lacak progres pengindeksan dan operasi sistem
  • šŸ” Manajemen Kunci API - Kontrol akses yang aman
  • šŸ„ Pemantauan Kesehatan - Pantau instans Meilisearch Anda
  • šŸ Implementasi Python - Versi TypeScript juga tersedia

šŸš€ Mulai Cepat

Siap digunakan hanya dalam 3 langkah!

1ļøāƒ£ Instal paket

# Using pip
pip install meilisearch-mcp

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

2ļøāƒ£ Konfigurasi Claude Desktop

Tambahkan ini ke claude_desktop_config.json Anda:

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

3ļøāƒ£ Mulai Meilisearch

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

# Or using Homebrew
brew install meilisearch
meilisearch

Selesai! Sekarang Anda dapat meminta asisten AI Anda untuk mencari dan mengelola data Meilisearch Anda! šŸŽ‰

šŸ“š Contoh

šŸ’¬ Bicaralah dengan asisten AI Anda secara alami:

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!

šŸ” Contoh Pencarian Lanjutan:

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

šŸ”§ Instalasi

Prasyarat

  • Python ā‰„ 3.9
  • Instans Meilisearch yang berjalan
  • Klien yang kompatibel dengan MCP (Claude Desktop, agen OpenAI, dll.)

Dari PyPI

pip install meilisearch-mcp

Dari Sumber (untuk pengembangan)

# 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 .

Menggunakan Docker

Sempurna untuk lingkungan terkontainerisasi seperti alur kerja n8n!

Dari Docker Hub

# 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

Bangun dari Sumber

# 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

Integrasi dengan n8n

Untuk alur kerja n8n, Anda dapat menggunakan image Docker langsung di pengaturan Anda:

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

šŸ› ļø Apa yang Dapat Anda Lakukan?

šŸ”— Manajemen Koneksi
  • Lihat pengaturan koneksi saat ini
  • Beralih antar instans Meilisearch secara dinamis
  • Perbarui kunci API dengan cepat
šŸ“ Operasi Indeks
  • Buat indeks baru dengan kunci utama kustom
  • Daftar semua indeks dengan statistik
  • Hapus indeks dan datanya
  • Dapatkan metrik indeks terperinci
šŸ“„ Manajemen Dokumen
  • Tambah atau perbarui dokumen
  • Ambil dokumen dengan paginasi
  • Impor data massal
šŸ” Kemampuan Pencarian
  • Cari dengan filter, pengurutan, dan faset
  • Pencarian multi-indeks
  • Pencarian semantik dengan vektor
  • Pencarian hibrida (kata kunci + semantik)
āš™ļø Pengaturan & Konfigurasi
  • Konfigurasikan aturan peringkat
  • Atur faset dan penyaringan
  • Kelola atribut yang dapat dicari
  • Sesuaikan toleransi kesalahan ketik
šŸ” Keamanan
  • Buat dan kelola kunci API
  • Tetapkan izin terperinci
  • Pantau penggunaan kunci

āš ļø Catatan: Meskipun Anda dapat menambah dan memperbarui host serta kunci API langsung di obrolan untuk kenyamanan, pendekatan ini terutama dirancang untuk kasus penggunaan pengembangan (seperti menghubungkan ke beberapa instans dengan cepat). Ini tidak mengikuti praktik keamanan MCP terbaik dan tidak boleh digunakan di lingkungan produksi tanpa perlindungan yang tepat.

šŸ“Š Pemantauan & Kesehatan
  • Pemeriksaan kesehatan
  • Statistik sistem
  • Pemantauan tugas
  • Informasi versi

šŸŒ Variabel Lingkungan

Konfigurasikan pengaturan koneksi default:

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

šŸ’» Pengembangan

Menyiapkan Lingkungan Pengembangan

  1. Mulai Meilisearch:

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

  2. Instal Dependensi Pengembangan:

    uv pip install -r requirements-dev.txt

  3. Jalankan Tes:

    python -m pytest tests/ -v

  4. Format Kode:

    black src/ tests/

Pengujian dengan Inspektur MCP

npx @modelcontextprotocol/inspector python -m src.meilisearch_mcp

šŸ¤ Komunitas & Dukungan

Kami ingin mendengar dari Anda! Berikut cara mendapatkan bantuan dan terhubung:

šŸ¤— Berkontribusi

Kami menyambut kontribusi! Berikut cara memulai:

  1. Fork repositori
  2. Buat cabang fitur Anda (git checkout -b feature/amazing-feature)
  3. Tulis tes untuk perubahan Anda
  4. Buat perubahan Anda dan jalankan tes
  5. Format kode Anda dengan black
  6. Komit perubahan Anda (git commit -m 'Add amazing feature')
  7. Dorong ke cabang Anda (git push origin feature/amazing-feature)
  8. Buka Pull Request

Lihat Panduan Berkontribusi kami untuk detail lebih lanjut.

šŸ“¦ Proses Rilis

Proyek ini menggunakan versioning dan penerbitan otomatis. Ketika versi di pyproject.toml berubah pada cabang main, paket secara otomatis diterbitkan ke PyPI.

Lihat bagian Proses Rilis untuk instruksi terperinci.

šŸ“„ Lisensi

Proyek ini dilisensikan di bawah Lisensi MIT - lihat file LICENSE untuk detailnya.

Meilisearch adalah mesin pencari sumber terbuka yang menawarkan pengalaman pencarian yang menyenangkan.
Pelajari lebih lanjut tentang Meilisearch di meilisearch.com

šŸ“– Dokumentasi Lengkap

Alat yang Tersedia

Manajemen Koneksi

  • get-connection-settings: Lihat URL koneksi Meilisearch saat ini dan status kunci API
  • update-connection-settings: Perbarui URL dan/atau kunci API untuk terhubung ke instans yang berbeda

Manajemen Indeks

  • create-index: Buat indeks baru dengan kunci utama opsional
  • list-indexes: Daftar semua indeks yang tersedia
  • delete-index: Hapus indeks yang ada dan semua dokumennya
  • get-index-metrics: Dapatkan metrik terperinci untuk indeks tertentu

Operasi Dokumen

  • get-documents: Ambil dokumen dari indeks dengan paginasi
  • add-documents: Tambah atau perbarui dokumen dalam indeks

Pencarian

  • search: Pencarian fleksibel di satu atau beberapa indeks dengan opsi penyaringan dan pengurutan

Manajemen Pengaturan

  • get-settings: Lihat pengaturan saat ini untuk indeks
  • update-settings: Perbarui pengaturan indeks (peringkat, faset, dll.)

Manajemen Kunci API

  • get-keys: Daftar semua kunci API
  • create-key: Buat kunci API baru dengan izin tertentu
  • delete-key: Hapus kunci API yang ada

Manajemen Tugas

  • get-task: Dapatkan informasi tentang tugas tertentu
  • get-tasks: Daftar tugas dengan filter opsional
  • cancel-tasks: Batalkan tugas yang tertunda atau antrean
  • delete-tasks: Hapus tugas yang selesai

Pemantauan Sistem

  • health-check: Pemeriksaan kesehatan dasar
  • get-health-status: Status kesehatan komprehensif
  • get-version: Dapatkan informasi versi Meilisearch
  • get-stats: Dapatkan statistik basis data
  • get-system-info: Dapatkan informasi tingkat sistem

Pengaturan Pengembangan

Prasyarat

  1. Mulai server Meilisearch:

    # 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. Instal alat pengembangan:

    # 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

Menjalankan Tes

Proyek ini mencakup tes integrasi komprehensif yang memverifikasi fungsionalitas alat MCP:

# 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/

Penting: Tes memerlukan instans Meilisearch yang berjalan di http://localhost:7700.

Kualitas Kode

# 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/

Panduan Berkontribusi

  1. Fork dan klon repositori
  2. Siapkan lingkungan pengembangan mengikuti bagian Pengaturan Pengembangan di atas
  3. Buat cabang fitur dari main
  4. Tulis tes terlebih dahulu jika menambahkan fungsionalitas baru (Pengembangan Berbasis Tes)
  5. Jalankan tes secara lokal untuk memastikan semua tes lulus sebelum melakukan komit
  6. Format kode dengan Black dan pastikan kualitas kode
  7. Komit perubahan dengan pesan komit yang deskriptif
  8. Dorong ke fork Anda dan buat pull request

Alur Kerja Pengembangan

# 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

Panduan Pengujian

  • Semua fitur baru harus menyertakan tes
  • Tes harus lulus sebelum mengirimkan PR
  • Gunakan nama tes yang deskriptif dan asersi yang jelas
  • Uji kasus sukses dan error
  • Pastikan Meilisearch berjalan sebelum menjalankan tes

Proses Rilis

Proyek ini menggunakan versioning dan penerbitan otomatis ke PyPI. Proses rilis dirancang agar sederhana dan otomatis.

Cara Kerja Rilis

  1. Penerbitan Otomatis: Ketika nomor versi di pyproject.toml berubah pada cabang main, GitHub Action secara otomatis:

    • Membangun paket Python
    • Menerbitkannya ke PyPI menggunakan penerbitan tepercaya
    • Membuat rilis baru di GitHub

  2. Deteksi Versi: Alur kerja membandingkan versi saat ini di pyproject.toml dengan komit sebelumnya untuk mendeteksi perubahan

  3. Penerbitan PyPI: Menggunakan aksi penerbitan resmi PyPA dengan penerbitan tepercaya (tidak perlu kunci API manual)

Membuat Rilis Baru

Untuk membuat rilis baru, ikuti langkah-langkah berikut:

1. Tentukan Nomor Versi

Ikuti Versioning Semantik (MAJOR.MINOR.PATCH):

  • PATCH (mis., 0.4.0 ā†’ 0.4.1): Perbaikan bug, pembaruan dokumentasi, peningkatan kecil
  • MINOR (mis., 0.4.0 ā†’ 0.5.0): Fitur baru, alat MCP baru, peningkatan signifikan
  • MAJOR (mis., 0.5.0 ā†’ 1.0.0): Perubahan yang melanggar, perubahan API besar
2. Perbarui Versi dan Buat PR
# 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. Gabungkan ke Main

Setelah PR disetujui dan digabungkan ke main, GitHub Action akan secara otomatis:

  1. Mendeteksi perubahan versi
  2. Membangun paket
  3. Menerbitkan ke PyPI di https://pypi.org/p/meilisearch-mcp
  4. Membuat versi baru tersedia melalui pip install meilisearch-mcp
4. Verifikasi Rilis

Setelah penggabungan, verifikasi rilis:

# 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

File Alur Kerja Rilis

Rilis otomatis ditangani oleh .github/workflows/publish.yml, yang:

  • Dipicu pada dorongan ke cabang main
  • Memeriksa apakah versi pyproject.toml berubah
  • Menggunakan Python 3.10 dan alat build resmi
  • Menerbitkan menggunakan penerbitan tepercaya (tidak perlu kunci API)
  • Menyediakan output verbose untuk debugging

Pemecahan Masalah Rilis

Rilis tidak terpicu: Periksa apakah versi di pyproject.toml benar-benar berubah antar komit

Build gagal: Periksa log GitHub Actions untuk kesalahan build paket Python

Penerbitan PyPI gagal: Verifikasi nama paket dan apakah penerbitan tepercaya dikonfigurasi dengan benar Konflik versi: Pastikan nomor versi baru belum pernah digunakan sebelumnya di PyPI

Versi Pengembangan vs Produksi

  • Pengembangan: Instal dari sumber menggunakan pip install -e .
  • Produksi: Instal dari PyPI menggunakan pip install meilisearch-mcp
  • Versi spesifik: Instal menggunakan pip install meilisearch-mcp==0.5.0