Meilisearch

• Visualizar as configurações atuais de conexão
• Alternar dinamicamente entre instâncias do Meilisearch
• 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 dos índices

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

• Pesquisar com filtros, ordenação e facetas
• Busca em vários índices
• Busca semântica com vetores
• Busca híbrida (por 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

⚠️ Observação: embora seja possível adicionar e atualizar hosts e chaves de API diretamente no chat por conveniência, essa abordagem foi projetada principalmente para casos de uso em 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 proteções.

• Verificações de integridade
• Estatísticas do sistema
• Monitoramento de tarefas
• Informações sobre a versão

Ferramentas disponíveis

Gerenciamento de conexões

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

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 de 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 configurações

• get-settings: Visualizar as configurações atuais de um índice
• update-settings: Atualizar as configurações do índice (classificação, facetas etc.)

Gerenciamento de chaves de API

• get-keys: Listar todas as chaves de API
• create-key: Criar uma 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

Monitoramento do sistema

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

Configuração do ambiente 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
   

Execução dos 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 do ambiente de desenvolvimento acima
3. Crie uma branch de recurso a partir de main
4. Escreva os testes primeiro ao adicionar novas funcionalidades (Desenvolvimento Orientado a Testes)
5. Execute os 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 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 verificações claras
• Teste os casos de sucesso e de erro
• Verifique se o Meilisearch está 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 foi 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-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 a do commit anterior para detectar alterações

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

Criar um novo lançamento

Para criar um novo lançamento, siga estas etapas:

1. Determine o número da versão

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

• PATCH (por exemplo, 0.4.0 → 0.4.1): correções de bugs, atualizações da documentação, pequenas melhorias
• MINOR (por exemplo, 0.4.0 → 0.5.0): novos recursos, novas ferramentas MCP, melhorias significativas
• MAJOR (por exemplo, 0.5.0 → 1.0.0): alterações incompatíveis, 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 na branch principal

Depois que o PR for aprovado e integrado à main, a GitHub Action fará automaticamente:

1. Detecte a alteração da versão
2. Compile o pacote
3. Publique no PyPI em https://pypi.org/p/meilisearch-mcp
4. Disponibilize a nova versão por meio de pip install meilisearch-mcp

4. Verificar a versão

Após a mesclagem, verifique a versão:

# 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 publicação

A publicação automatizada é gerenciada por .github/workflows/publish.yml, que:

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

Solução de problemas de publicação

A publicação não foi acionada: Verifique se a versão em pyproject.toml realmente mudou entre os commits

Falha na compilação: Verifique os logs do GitHub Actions em busca de erros na compilação do pacote Python

Falha na publicação no PyPI: 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 ainda não tenha sido usado no PyPI

Versões de desenvolvimento e produção

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