Lucius MCP for Allure TestOps

Um servidor MCP e CLI repleto de recursos para o sistema de gerenciamento de testes Allure TestOps

Documentação

PyPI Downloads

Servidor MCP Allure TestOps

Lucius é um servidor especializado do Model Context Protocol (MCP) para Allure TestOps, construído com FastMCP e Starlette.

🎯 Motivação

Allure TestOps é uma ferramenta poderosa com uma API enorme. Quando você usa um agente de IA para gerenciar seus testes, ele pode facilmente se perder nos detalhes ou falhar por causa de um pequeno erro técnico.

Lucius facilita isso fornecendo à sua IA ferramentas simples de usar e difíceis de quebrar:

Ferramentas Claras: Cada ferramenta é projetada para uma tarefa específica, como "encontrar um caso de teste" ou "atualizar um launch".
Erros Úteis: Se uma IA cometer um erro, Lucius não retorna apenas um código—ele fornece uma "Dica de Agente" que explica exatamente o que deu errado e como corrigir.
Base Sólida: Seguimos uma estrutura limpa de "Ferramenta Fina", o que significa que a lógica é consistente e fácil de seguir tanto para humanos quanto para IA.

🛠️ Ferramentas Suportadas

Consulte a referência completa em Referência de Ferramentas.

Categoria de Ferramenta	Descrição	Todas as Ferramentas
Gerenciamento de Casos de Teste	Ciclo de vida completo para documentação de testes.	`create_test_case`, `update_test_case`, `delete_test_case`, `delete_archived_test_cases`, `get_test_case_details`, `get_test_case_custom_fields`
Geração de Automação	Gera código específico de framework a partir de casos de teste existentes.	`generate_test_code`
Busca e Descoberta	Busca avançada e descoberta de metadados do projeto.	`list_test_cases`, `search_test_cases`, `get_custom_fields`, `list_integrations`, `get_project`
Passos Compartilhados	Cria e gerencia sequências de passos reutilizáveis.	`create_shared_step`, `list_shared_steps`, `update_shared_step`, `delete_shared_step`, `delete_archived_shared_steps`, `link_shared_step`, `unlink_shared_step`
Camadas de Teste	Gerencia taxonomia de testes e esquemas de mapeamento automático.	`list_test_layers`, `create_test_layer`, `update_test_layer`, `delete_test_layer`, `list_test_layer_schemas`, `create_test_layer_schema`, `update_test_layer_schema`, `delete_test_layer_schema`
Hierarquia de Testes	Organiza suítes e atribui testes em caminhos de árvore.	`create_test_suite`, `list_test_suites`, `assign_test_cases_to_suite`, `delete_test_suite`
Campos Personalizados	Gerenciamento em nível de projeto de valores de campos personalizados.	`list_custom_field_values`, `create_custom_field_value`, `update_custom_field_value`, `delete_custom_field_value`, `delete_unused_custom_fields`
Gerenciamento de Launches	Gerencia launches, uploads de resultados, execução manual, reexecuções e anexos.	`create_launch`, `list_launches`, `get_launch`, `list_launch_test_results`, `upload_test_results`, `attach_file_to_launch`, `rerun_test_results_manually`, `start_manual_test_session`, `submit_manual_test_results`, `add_test_result_attachment`
Gerenciamento de Resultados de Teste	Inspeciona um resultado exato do TestOps e prepara downloads de evidências verificadas.	`get_test_result`, `prepare_attachment_download`
Planos de Teste	Gerencia planos de teste e seu conteúdo.	`create_test_plan`, `update_test_plan`, `delete_test_plan`, `list_test_plans`, `manage_test_plan_content`, `run_test_plan`
Gerenciamento de Defeitos	Rastreia defeitos, vínculos e regras de automação.	`create_defect`, `get_defect`, `update_defect`, `delete_defect`, `list_defects`, `link_defect_to_test_case`, `unlink_issue_from_test_case`, `list_defect_test_cases`, `create_defect_matcher`, `list_defect_matchers`, `update_defect_matcher`, `delete_defect_matcher`

🚀 Início Rápido

Instale o uv: curl -LsSf https://astral.sh/uv/install.sh | sh
Configure as Credenciais: Crie um arquivo .env com as variáveis abaixo, ou salve a autenticação CLI com lucius auth.
Execute o Servidor: uv run start

`.env` Básico para Início Rápido

Variável	Descrição	Exemplo
`ALLURE_ENDPOINT`	URL base do Allure TestOps	`https://example.testops.cloud`
`ALLURE_PROJECT_ID`	ID padrão do projeto Allure (opcional para `get_project`; obrigatório para ferramentas com escopo de projeto)	`123`
`ALLURE_API_TOKEN`	Token da API Allure	`<your_api_token>`
`MCP_MODE`	Modo de transporte MCP para o runtime Lucius	`stdio`

🔌 Integração com Claude Desktop

A maneira mais fácil de usar Lucius no Claude Desktop é através do pacote .mcpb:

Baixe o lucius-mcp.mcpb mais recente dos Releases.
Abra com o Claude Desktop.
Configure suas credenciais Allure na interface.

💻 Integração com Claude Code

Para adicionar Lucius ao Claude Code, use o seguinte comando a partir do diretório do seu projeto:

claude mcp add --transport stdio --scope project \
  --env ALLURE_ENDPOINT=https://example.testops.cloud \
  --env ALLURE_PROJECT_ID=123 \
  --env ALLURE_API_TOKEN=<your_api_token> \
  --env MCP_MODE=stdio \
  testops-mcp -- uvx --from lucius-mcp --refresh start

Exemplo de configuração de texto com escopo de projeto (.mcp.json):

{
  "mcpServers": {
    "testops-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "lucius-mcp",
        "--refresh",
        "start"
      ],
      "env": {
        "ALLURE_ENDPOINT": "https://example.testops.cloud",
        "ALLURE_PROJECT_ID": "123",
        "ALLURE_API_TOKEN": "<your_api_token>",
        "MCP_MODE": "stdio"
      }
    }
  }
}

🧠 Integração com Codex

Para adicionar Lucius ao Codex (CLI ou extensão IDE), use:

codex mcp add testops-mcp \
  --env ALLURE_ENDPOINT=https://example.testops.cloud \
  --env ALLURE_PROJECT_ID=123 \
  --env ALLURE_API_TOKEN=<your_api_token> \
  --env MCP_MODE=stdio \
  -- uvx --from lucius-mcp --refresh start

Exemplo de configuração de texto (~/.codex/config.toml ou projeto .codex/config.toml):

[mcp_servers.testops-mcp]
command = "uvx"
args = ["--from", "lucius-mcp", "--refresh", "start"]

[mcp_servers.testops-mcp.env]
ALLURE_ENDPOINT = "https://example.testops.cloud"
ALLURE_PROJECT_ID = "123"
ALLURE_API_TOKEN = "<your_api_token>"
MCP_MODE = "stdio"

Para configuração detalhada, incluindo integração com Claude Desktop (MCPB), consulte o Guia de Configuração.

🐍 Versões suportadas do Python

Lucius suporta Python 3.10 a 3.14 para uso em runtime. Os manifestos MCPB gerados e a matriz do compilador CLI Nuitka representativa validam o mesmo intervalo. Python 3.9 permanece sem suporte porque o starlette==1.3.1 fixado requer Python 3.10 ou mais recente; Python 3.15 é adiado porque o conjunto atual de dependências nativas não compila para ele.

💻 Interface de Linha de Comando (CLI)

Lucius também fornece um ponto de entrada CLI universal para execução direta de ferramentas a partir da linha de comando:

# List available actions for an entity
uv run lucius test_case

# Execute an action
uv run lucius test_case get --args '{"test_case_id": 1234}'

# Show help for a specific entity/action
uv run lucius test_case get --help

# Save reusable CLI auth
uv run lucius auth --url https://example.testops.cloud --token <your_api_token> --project 123
uv run lucius auth status
uv run lucius auth clear

Recursos da CLI:

🎯 Invocação de entidade/ação com segurança de tipos e validação
🔐 Autenticação CLI persistente opcional com armazenamento de configuração nativo por usuário
📊 Múltiplos formatos de saída (JSON, tabela, csv, texto simples)
🔍 Ajuda por ação com parâmetros e exemplos
🛡️ Mensagens de erro claras com orientação
📦 Binários autônomos para Linux, macOS e Windows

A precedência da autenticação CLI é:

Argumentos explícitos da ferramenta, como api_token ou project_id
Variáveis de ambiente
Configuração de autenticação CLI salva de uv run lucius auth
Padrões

A autenticação CLI salva usa locais de configuração nativos:

Linux/Unix: $XDG_CONFIG_HOME/lucius/auth.json ou ~/.config/lucius/auth.json
macOS: ~/Library/Application Support/lucius/auth.json a menos que substituições XDG sejam definidas explicitamente
Windows: %LOCALAPPDATA%\lucius\auth.json

Para documentação completa da CLI e instruções de instalação, consulte o Guia da CLI.

📡 Telemetria

Lucius coleta telemetria de uso que preserva a privacidade para melhorar a qualidade das ferramentas. A telemetria está habilitada por padrão e envia metadados para https://stats.ostanin.me, um endpoint operado pelo proprietário do projeto (nenhum terceiro tem acesso a este endpoint).

Se isso for aceitável no seu ambiente, permanecer opt-in ajuda a melhorar Lucius ao longo do tempo. Se você quiser opt-out, defina TELEMETRY_ENABLED=false no seu ambiente.

Nenhum token de API, conteúdo de teste ou argumentos de ferramenta são enviados.

Consulte Telemetria e Privacidade para o dicionário de dados completo e detalhes do comportamento da telemetria.

📂 Documentação

A documentação completa está disponível na pasta docs/:

🤝 Contribuindo

Contribuições são bem-vindas! Consulte as Diretrizes de Contribuição e o Guia de Desenvolvimento para mais detalhes.