Meilisearch

официальный

Взаимодействие и запросы к Meilisearch (API полнотекстового и семантического поиска)

GitHub
193

Что можно делать с Meilisearch MCP?

  • Create and manage search indices — Ask your AI to create a new index with a custom primary key, list all existing indexes, or delete an index via create-index, list-indexes, and delete-index.
  • Add and retrieve documents — Use add-documents to bulk import or update documents, and get-documents to fetch them with pagination.
  • Search with filters and sorting — Perform single or multi-index searches with advanced filtering, sorting, and faceting through the search tool.
  • Configure index settings — Adjust ranking rules, faceting, searchable attributes, and typo tolerance using get-settings and update-settings.
  • Monitor tasks and system health — Track indexing progress with get-tasks and cancel-tasks, or check instance status via health-check and get-stats.

Документация

Meilisearch

Meilisearch MCP Server

Meilisearch | Meilisearch Cloud | Документация | Discord

PyPI version Python Versions Tests License Downloads

⚡ Подключите любую LLM к Meilisearch и наделите свой ИИ молниеносными поисковыми возможностями! 🔍

🤔 Что это?

Meilisearch MCP Server — это сервер Model Context Protocol, который позволяет любому MCP-совместимому клиенту (включая Claude, агентов OpenAI и другие LLM) взаимодействовать с Meilisearch. Этот сервер на основе stdio позволяет AI-ассистентам управлять поисковыми индексами, выполнять поиск и обрабатывать ваши данные через естественный диалог.

Зачем это нужно?

  • 🤖 Универсальная совместимость — работает с любым MCP-клиентом, а не только с Claude
  • 🗣️ Управление на естественном языке — управляйте Meilisearch через общение с любой LLM
  • 🚀 Без порога вхождения — не нужно изучать API Meilisearch
  • 🔧 Полный доступ к функциям — все возможности Meilisearch у вас под рукой
  • 🔄 Динамические подключения — переключайтесь между экземплярами Meilisearch на лету
  • 📡 Транспорт stdio — в настоящее время используется stdio; скоро появится нативная поддержка MCP в Meilisearch!

✨ Ключевые возможности

  • 📊 Управление индексами и документами — создание, обновление и управление поисковыми индексами
  • 🔍 Умный поиск — поиск по одному или нескольким индексам с расширенной фильтрацией
  • ⚙️ Настройка конфигурации — тонкая настройка релевантности и производительности поиска
  • 📈 Мониторинг задач — отслеживание прогресса индексации и системных операций
  • 🔐 Управление API-ключами — безопасный контроль доступа
  • 🏥 Мониторинг состояния — следите за своим экземпляром Meilisearch
  • 🐍 Реализация на Python — также доступна версия на TypeScript

🚀 Быстрый старт

Начните работу всего за 3 шага!

1️⃣ Установите пакет

# Using pip
pip install meilisearch-mcp

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

2️⃣ Настройте Claude Desktop

Добавьте это в ваш claude_desktop_config.json:

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

3️⃣ Запустите Meilisearch

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

# Or using Homebrew
brew install meilisearch
meilisearch

Вот и всё! Теперь вы можете попросить своего AI-ассистента искать и управлять данными в Meilisearch! 🎉

📚 Примеры

💬 Общайтесь со своим AI-ассистентом естественно:

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!

🔍 Пример расширенного поиска:

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

🔧 Установка

Предварительные требования

  • Python ≥ 3.9
  • Запущенный экземпляр Meilisearch
  • MCP-совместимый клиент (Claude Desktop, агенты OpenAI и т. д.)

Из PyPI

pip install meilisearch-mcp

Из исходников (для разработки)

# 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

Идеально подходит для контейнеризованных сред, таких как рабочие процессы n8n!

Из 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

Сборка из исходников

# 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

Для рабочих процессов n8n вы можете использовать образ Docker непосредственно в своей настройке:

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

🛠️ Что вы можете делать?

🔗 Управление подключениями
  • Просмотр текущих настроек подключения
  • Динамическое переключение между экземплярами Meilisearch
  • Обновление API-ключей на лету
📁 Операции с индексами
  • Создание новых индексов с пользовательскими первичными ключами
  • Список всех индексов со статистикой
  • Удаление индексов и их данных
  • Получение подробных метрик индекса
📄 Управление документами
  • Добавление или обновление документов
  • Получение документов с постраничной навигацией
  • Массовый импорт данных
🔍 Поисковые возможности
  • Поиск с фильтрами, сортировкой и фасетами
  • Поиск по нескольким индексам
  • Семантический поиск с векторами
  • Гибридный поиск (ключевые слова + семантика)
⚙️ Настройки и конфигурация
  • Настройка правил ранжирования
  • Настройка фасетов и фильтрации
  • Управление атрибутами для поиска
  • Настройка устойчивости к опечаткам
🔐 Безопасность
  • Создание и управление API-ключами
  • Установка детальных разрешений
  • Мониторинг использования ключей

⚠️ Примечание: Хотя вы можете добавлять и обновлять хосты и API-ключи непосредственно в чате для удобства, этот подход в первую очередь предназначен для сценариев разработки (например, подключение к нескольким экземплярам на лету). Он не соответствует лучшим практикам безопасности MCP и не должен использоваться в производственных средах без надлежащих мер защиты.

📊 Мониторинг и состояние
  • Проверки работоспособности
  • Системная статистика
  • Мониторинг задач
  • Информация о версии

🌍 Переменные окружения

Настройка параметров подключения по умолчанию:

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

💻 Разработка

Настройка среды разработки

  1. Запустите Meilisearch:

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

  2. Установите зависимости для разработки:

    uv pip install -r requirements-dev.txt

  3. Запустите тесты:

    python -m pytest tests/ -v

  4. Форматирование кода:

    black src/ tests/

Тестирование с MCP Inspector

npx @modelcontextprotocol/inspector python -m src.meilisearch_mcp

🤝 Сообщество и поддержка

Мы будем рады вас слышать! Вот как получить помощь и связаться:

🤗 Участие в разработке

Мы приветствуем вклад! Вот как начать:

  1. Сделайте форк репозитория
  2. Создайте ветку для своей функции (git checkout -b feature/amazing-feature)
  3. Напишите тесты для своих изменений
  4. Внесите изменения и запустите тесты
  5. Отформатируйте код с помощью black
  6. Зафиксируйте изменения (git commit -m 'Add amazing feature')
  7. Отправьте ветку (git push origin feature/amazing-feature)
  8. Откройте Pull Request

Подробнее см. в нашем Руководстве по участию.

📦 Процесс выпуска

В этом проекте используется автоматическое управление версиями и публикация. Когда версия в pyproject.toml изменяется в ветке main, пакет автоматически публикуется в PyPI.

Подробные инструкции см. в разделе Процесс выпуска.

📄 Лицензия

Этот проект лицензирован под лицензией MIT — подробности см. в файле LICENSE.

Meilisearch — это поисковый движок с открытым исходным кодом, который предлагает превосходный опыт поиска.
Узнайте больше о Meilisearch на meilisearch.com

📖 Полная документация

Доступные инструменты

Управление подключениями

  • get-connection-settings: Просмотр текущего URL подключения Meilisearch и статуса API-ключа
  • update-connection-settings: Обновление URL и/или API-ключа для подключения к другому экземпляру

Управление индексами

  • create-index: Создание нового индекса с опциональным первичным ключом
  • list-indexes: Список всех доступных индексов
  • delete-index: Удаление существующего индекса и всех его документов
  • get-index-metrics: Получение подробных метрик для конкретного индекса

Операции с документами

  • get-documents: Получение документов из индекса с постраничной навигацией
  • add-documents: Добавление или обновление документов в индексе

Поиск

  • search: Гибкий поиск по одному или нескольким индексам с возможностями фильтрации и сортировки

Управление настройками

  • get-settings: Просмотр текущих настроек индекса
  • update-settings: Обновление настроек индекса (ранжирование, фасеты и т. д.)

Управление API-ключами

  • get-keys: Список всех API-ключей
  • create-key: Создание нового API-ключа с определенными разрешениями
  • delete-key: Удаление существующего API-ключа

Управление задачами

  • get-task: Получение информации о конкретной задаче
  • get-tasks: Список задач с опциональными фильтрами
  • cancel-tasks: Отмена ожидающих или поставленных в очередь задач
  • delete-tasks: Удаление завершенных задач

Мониторинг системы

  • health-check: Базовая проверка работоспособности
  • get-health-status: Комплексный статус работоспособности
  • get-version: Получение информации о версии Meilisearch
  • get-stats: Получение статистики базы данных
  • get-system-info: Получение информации на уровне системы

Настройка разработки

Предварительные требования

  1. Запустите сервер 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. Установите инструменты разработки:

    # 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

Запуск тестов

Этот проект включает комплексные интеграционные тесты, которые проверяют функциональность инструментов 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/

Важно: Для тестов требуется запущенный экземпляр Meilisearch на http://localhost:7700.

Качество кода

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

Руководство по участию

  1. Сделайте форк и клонируйте репозиторий
  2. Настройте среду разработки, следуя разделу «Настройка разработки» выше
  3. Создайте ветку функции от main
  4. Сначала напишите тесты, если добавляете новую функциональность (разработка через тестирование)
  5. Запустите тесты локально, чтобы убедиться, что все тесты проходят перед фиксацией
  6. Отформатируйте код с помощью Black и обеспечьте качество кода
  7. Зафиксируйте изменения с описательными сообщениями коммитов
  8. Отправьте в свой форк и создайте pull request

Рабочий процесс разработки

# 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

Руководство по тестированию

  • Все новые функции должны включать тесты
  • Тесты должны проходить перед отправкой PR
  • Используйте описательные имена тестов и четкие утверждения
  • Тестируйте как успешные, так и ошибочные сценарии
  • Перед запуском тестов убедитесь, что Meilisearch запущен

Процесс выпуска

В этом проекте используется автоматическое управление версиями и публикация в PyPI. Процесс выпуска спроектирован так, чтобы быть простым и автоматизированным.

Как работают выпуски

  1. Автоматическая публикация: Когда номер версии в pyproject.toml изменяется в ветке main, GitHub Action автоматически:

    • Собирает пакет Python
    • Публикует его в PyPI с использованием доверенной публикации
    • Создает новый релиз на GitHub

  2. Обнаружение версии: Рабочий процесс сравнивает текущую версию в pyproject.toml с предыдущим коммитом для обнаружения изменений

  3. Публикация в PyPI: Использует официальное действие публикации PyPA с доверенной публикацией (ручные API-ключи не требуются)

Создание нового выпуска

Чтобы создать новый выпуск, выполните следующие шаги:

1. Определите номер версии

Следуйте Семантическому версионированию (МАЖОР.МИНОР.ПАТЧ):

  • ПАТЧ (например, 0.4.0 → 0.4.1): Исправления ошибок, обновления документации, незначительные улучшения
  • МИНОР (например, 0.4.0 → 0.5.0): Новые функции, новые инструменты MCP, значительные улучшения
  • МАЖОР (например, 0.5.0 → 1.0.0): Критические изменения, серьезные изменения API
2. Обновите версию и создайте 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. Слияние в Main

Как только PR одобрен и слит в main, GitHub Action автоматически:

  1. Обнаружит изменение версии
  2. Соберет пакет
  3. Опубликует в PyPI по адресу https://pypi.org/p/meilisearch-mcp
  4. Сделает новую версию доступной через pip install meilisearch-mcp
4. Проверьте выпуск

После слияния проверьте выпуск:

# 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

Файл рабочего процесса выпуска

Автоматический выпуск обрабатывается .github/workflows/publish.yml, который:

  • Запускается при пушах в ветку main
  • Проверяет, изменилась ли версия pyproject.toml
  • Использует Python 3.10 и официальные инструменты сборки
  • Публикует с использованием доверенной публикации (API-ключи не требуются)
  • Предоставляет подробный вывод для отладки

Устранение неполадок при выпусках

Выпуск не запустился: Проверьте, действительно ли версия в pyproject.toml изменилась между коммитами

Сборка не удалась: Проверьте журналы GitHub Actions на наличие ошибок сборки пакета Python

Публикация в PyPI не удалась: Проверьте имя пакета и правильность настройки доверенной публикации Конфликты версий: Убедитесь, что новый номер версии ранее не использовался на PyPI

Версии для разработки и продакшена

  • Разработка: Установка из исходного кода с помощью pip install -e .
  • Продакшен: Установка из PyPI с помощью pip install meilisearch-mcp
  • Определённая версия: Установка с помощью pip install meilisearch-mcp==0.5.0