Meilisearch

• Visualizar as configurações de conexão atuais
• Alternar entre instâncias do Meilisearch dinamicamente
• Atualizar chaves de API em tempo real

• 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

• Buscar com filtros, ordenação e facetas
• Busca em vários índices
• Busca semântica com vetores
• Busca híbrida (palavras-chave + semântica)

• Configurar regras de classificação
• Configurar facetas e filtros
• Gerenciar atributos pesquisáveis
• Personalizar a tolerância a erros de digitação

• Criar e gerenciar chaves de API
• Definir permissões granulares
• Monitorar o uso das 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 em tempo real). 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: Visualizar 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 filtro e ordenação

Gerenciamento de Ajustes

• get-settings: Visualizar os ajustes atuais de um índice
• update-settings: Atualizar ajustes do índice (classificação, facetas, 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 na fila

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 de nível do 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 as 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 um fork e clone o repositório
2. Configure o ambiente de desenvolvimento seguindo a seção Configuração de Desenvolvimento acima
3. Crie uma branch de recurso a partir de main
4. Escreva testes primeiro se estiver adicionando nova funcionalidade (Desenvolvimento Orientado a Testes)
5. Execute os testes localmente para garantir que todos passem antes do 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 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

• Todos os novos recursos devem incluir testes
• Os testes devem passar antes do envio de PRs
• Use nomes de teste descritivos e asserções claras
• Teste tanto os casos de sucesso quanto os de erro
• Garanta que o Meilisearch esteja em execução antes de executar 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 Funcionam os Lançamentos

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

   • Compila o pacote Python
   • Publica 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 alterações

3. Publicação no PyPI: Usa a ação de publicação oficial 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, melhorias menores
• MINOR (ex.: 0.4.0 → 0.5.0): Novos recursos, novas ferramentas MCP, melhorias significativas
• MAJOR (ex.: 0.5.0 → 1.0.0): Alterações de quebra, mudanças importantes na API

2. Atualize a Versão e Crie o 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. Mescle na Main

Quando o PR for aprovado e mesclado em main, a GitHub Action automaticamente:

1. Detecta a mudança de versão
2. Compila o pacote
3. Publica no PyPI em https://pypi.org/p/meilisearch-mcp
4. Disponibiliza a nova versão via pip install meilisearch-mcp

4. Verifique o Lançamento

Após a mesclagem, 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 do Fluxo de Trabalho de Lançamento

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

• É acionado por pushes na branch main
• Verifica se a versão de pyproject.toml mudou
• Usa Python 3.10 e ferramentas de compilação oficiais
• 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

Release não disparou: Verifique se a versão em pyproject.toml realmente mudou entre os commits

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

Publicação no PyPI falhou: Verifique o nome do pacote e se a publicação confiável está configurada corretamente

Conflitos de versão: Garanta que o novo número de versão não foi usado anteriormente 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