Meilisearch MCP Server

• Ver configurações de conexão atuais
• Alternar entre instâncias do Meilisearch dinamicamente
• Atualizar chaves de API rapidamente

• Criar novos índices com chaves primárias personalizadas
• Listar todos os índices com estatísticas
• Excluir índices e seus dados
• Obter métricas detalhadas do índice

• Adicionar ou atualizar documentos
• Recuperar documentos com paginação
• Importar dados em massa

• Pesquisar com filtros, ordenação e facetas
• Busca multi-índice
• Busca semântica com vetores
• Busca híbrida (palavra-chave + semântica)

• Configurar regras de ranqueamento
• Definir facetamento e filtragem
• Gerenciar atributos pesquisáveis
• Personalizar tolerância a erros de digitação

• Criar e gerenciar chaves de API
• Definir permissões granulares
• Monitorar uso de chaves

⚠️ Nota: Embora você possa adicionar e atualizar hosts e chaves de API diretamente no chat por conveniência, essa abordagem é projetada principalmente para casos de uso de desenvolvimento (como conectar-se a várias instâncias rapidamente). Ela não segue as melhores práticas de segurança do MCP e não deve ser usada em ambientes de produção sem as devidas salvaguardas.

• Verificações de saúde
• Estatísticas do sistema
• Monitoramento de tarefas
• Informações de versão

Ferramentas Disponíveis

Gerenciamento de Conexão

• get-connection-settings: Ver a URL de conexão atual do Meilisearch e o status da chave de API
• update-connection-settings: Atualizar URL e/ou chave de API para conectar a uma instância diferente

Gerenciamento de Índices

• create-index: Criar um novo índice com chave primária opcional
• list-indexes: Listar todos os índices disponíveis
• delete-index: Excluir um índice existente e todos os seus documentos
• get-index-metrics: Obter métricas detalhadas para um índice específico

Operações com Documentos

• get-documents: Recuperar documentos de um índice com paginação
• add-documents: Adicionar ou atualizar documentos em um índice

Busca

• search: Busca flexível em um ou vários índices com opções de filtragem e ordenação

Gerenciamento de Ajustes

• get-settings: Ver os ajustes atuais de um índice
• update-settings: Atualizar ajustes do índice (ranqueamento, facetamento, etc.)

Gerenciamento de Chaves de API

• get-keys: Listar todas as chaves de API
• create-key: Criar nova chave de API com permissões específicas
• delete-key: Excluir uma chave de API existente

Gerenciamento de Tarefas

• get-task: Obter informações sobre uma tarefa específica
• get-tasks: Listar tarefas com filtros opcionais
• cancel-tasks: Cancelar tarefas pendentes ou enfileiradas
• delete-tasks: Excluir tarefas concluídas

Monitoramento do Sistema

• health-check: Verificação básica de saúde
• get-health-status: Status de saúde abrangente
• get-version: Obter informações da versão do Meilisearch
• get-stats: Obter estatísticas do banco de dados
• get-system-info: Obter informações em nível de sistema

Configuração de Desenvolvimento

Pré-requisitos

1. Inicie o servidor 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. Instale ferramentas de desenvolvimento:

   # 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
   

Executando Testes

Este projeto inclui testes de integração abrangentes que verificam a funcionalidade das ferramentas 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/

Importante: Os testes exigem uma instância do Meilisearch em execução em http://localhost:7700.

Qualidade do Código

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

Diretrizes de Contribuição

1. Faça fork e clone o repositório
2. Configure o ambiente de desenvolvimento seguindo a seção Configuração de Desenvolvimento acima
3. Crie um branch de funcionalidade a partir de main
4. Escreva testes primeiro se estiver adicionando nova funcionalidade (Desenvolvimento Orientado a Testes)
5. Execute testes localmente para garantir que todos passem antes de fazer commit
6. Formate o código com Black e garanta a qualidade do código
7. Faça commit das alterações com mensagens de commit descritivas
8. Envie para o seu fork e crie um pull request

Fluxo de Trabalho de Desenvolvimento

# 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

Diretrizes de Teste

• Todas as novas funcionalidades devem incluir testes
• Os testes devem passar antes de enviar PRs
• Use nomes de teste descritivos e asserções claras
• Teste tanto casos de sucesso quanto de erro
• Certifique-se de que o Meilisearch esteja em execução antes de rodar os testes

Processo de Lançamento

Este projeto usa versionamento e publicação automatizados no PyPI. O processo de lançamento é projetado para ser simples e automatizado.

Como os Lançamentos Funcionam

1. Publicação Automatizada: Quando o número da versão em pyproject.toml muda no branch main, uma GitHub Action automaticamente:

   • Constrói o pacote Python
   • Publica-o no PyPI usando publicação confiável
   • Cria um novo lançamento no GitHub

2. Detecção de Versão: O fluxo de trabalho compara a versão atual em pyproject.toml com o commit anterior para detectar mudanças

3. Publicação no PyPI: Usa a ação oficial de publicação do PyPA com publicação confiável (sem necessidade de chaves de API manuais)

Criando um Novo Lançamento

Para criar um novo lançamento, siga estes passos:

1. Determine o Número da Versão

Siga o Versionamento Semântico (MAJOR.MINOR.PATCH):

• PATCH (ex.: 0.4.0 → 0.4.1): Correções de bugs, atualizações de documentação, pequenas melhorias
• MINOR (ex.: 0.4.0 → 0.5.0): Novas funcionalidades, novas ferramentas MCP, melhorias significativas
• MAJOR (ex.: 0.5.0 → 1.0.0): Mudanças que quebram compatibilidade, grandes mudanças na API

2. Atualize a Versão e Crie um 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. Faça Merge para a Main

Assim que o PR for aprovado e mesclado em main, a GitHub Action irá automaticamente:

1. Detectar a mudança de versão
2. Construir o pacote
3. Publicar no PyPI em https://pypi.org/p/meilisearch-mcp
4. Disponibilizar a nova versão via pip install meilisearch-mcp

4. Verifique o Lançamento

Após o merge, verifique o lançamento:

# 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

Arquivo de Fluxo de Trabalho de Lançamento

O lançamento automatizado é gerenciado por .github/workflows/publish.yml, que:

• É acionado em pushes para o branch main
• Verifica se a versão em pyproject.toml mudou
• Usa Python 3.10 e ferramentas oficiais de build
• Publica usando publicação confiável (sem necessidade de chaves de API)
• Fornece saída detalhada para depuração

Solução de Problemas de Lançamentos

O lançamento não foi acionado: Verifique se a versão em pyproject.toml realmente mudou entre os commits

A build falhou: Verifique os logs do GitHub Actions para erros de build do pacote Python

A publicação no PyPI falhou: Verifique o nome do pacote e se a publicação confiável está configurada corretamente Conflitos de versão: Certifique-se de que o novo número de versão não tenha sido usado antes no PyPI

Versões de Desenvolvimento vs Produção

• Desenvolvimento: Instale a partir do código-fonte usando pip install -e .
• Produção: Instale a partir do PyPI usando pip install meilisearch-mcp
• Versão específica: Instale usando pip install meilisearch-mcp==0.5.0