Lucius MCP for Allure TestOps

Un servidor MCP con muchas funciones y CLI para el sistema de gestión de pruebas Allure TestOps.

Documentación

PyPI Downloads

Servidor MCP de Allure TestOps

Lucius es un servidor especializado del Protocolo de Contexto de Modelo (MCP) para Allure TestOps, construido con FastMCP y Starlette.

🎯 Motivación

Allure TestOps es una herramienta potente con una API enorme. Cuando usas un agente de IA para gestionar tus pruebas, puede perderse fácilmente en los detalles o fallar debido a un pequeño error técnico.

Lucius facilita esto al proporcionar a tu IA herramientas que son simples de usar y difíciles de romper:

Herramientas Claras: Cada herramienta está diseñada para una tarea específica, como "encontrar un caso de prueba" o "actualizar un lanzamiento".
Errores Útiles: Si una IA comete un error, Lucius no solo devuelve un código—proporciona una "Pista para el Agente" que explica exactamente qué salió mal y cómo solucionarlo.
Base Sólida: Seguimos una estructura limpia de "Herramienta Delgada", lo que significa que la lógica es consistente y fácil de seguir tanto para humanos como para IA.

🛠️ Herramientas Compatibles

Consulta la referencia completa en Referencia de Herramientas.

Categoría de Herramienta	Descripción	Todas las Herramientas
Gestión de Casos de Prueba	Ciclo de vida completo para la documentación de pruebas.	`create_test_case`, `update_test_case`, `delete_test_case`, `delete_archived_test_cases`, `get_test_case_details`, `get_test_case_custom_fields`
Generación de Automatización	Genera código específico del framework a partir de casos de prueba existentes.	`generate_test_code`
Búsqueda y Descubrimiento	Búsqueda avanzada y descubrimiento de metadatos del proyecto.	`list_test_cases`, `search_test_cases`, `get_custom_fields`, `list_integrations`, `get_project`
Pasos Compartidos	Crea y gestiona secuencias de pasos reutilizables.	`create_shared_step`, `list_shared_steps`, `update_shared_step`, `delete_shared_step`, `delete_archived_shared_steps`, `link_shared_step`, `unlink_shared_step`
Capas de Prueba	Gestiona la taxonomía de pruebas y los esquemas de mapeo 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`
Jerarquía de Pruebas	Organiza suites y asigna pruebas en rutas de árbol.	`create_test_suite`, `list_test_suites`, `assign_test_cases_to_suite`, `delete_test_suite`
Campos Personalizados	Gestión a nivel de proyecto 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`
Gestión de Lanzamientos	Gestiona lanzamientos, cargas de resultados, ejecución manual, repeticiones y adjuntos.	`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`
Gestión de Resultados de Prueba	Inspecciona un resultado exacto de TestOps y prepara descargas de evidencia verificadas.	`get_test_result`, `prepare_attachment_download`
Planes de Prueba	Gestiona planes de prueba y su contenido.	`create_test_plan`, `update_test_plan`, `delete_test_plan`, `list_test_plans`, `manage_test_plan_content`, `run_test_plan`
Gestión de Defectos	Rastrea defectos, vinculación y reglas de automatización.	`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`

🚀 Inicio Rápido

Instala uv: curl -LsSf https://astral.sh/uv/install.sh | sh
Configura las Credenciales: Crea un archivo .env con las variables a continuación, o guarda la autenticación CLI con lucius auth.
Ejecuta el Servidor: uv run start

`.env` Básico para Inicio Rápido

Variable	Descripción	Ejemplo
`ALLURE_ENDPOINT`	URL base de Allure TestOps	`https://example.testops.cloud`
`ALLURE_PROJECT_ID`	ID de proyecto Allure predeterminado (opcional para `get_project`; requerido por herramientas con ámbito de proyecto)	`123`
`ALLURE_API_TOKEN`	Token de API de Allure	`<your_api_token>`
`MCP_MODE`	Modo de transporte MCP para el runtime de Lucius	`stdio`

🔌 Integración con Claude Desktop

La forma más fácil de usar Lucius en Claude Desktop es mediante el paquete .mcpb:

Descarga el lucius-mcp.mcpb más reciente desde Releases.
Ábrelo con Claude Desktop.
Configura tus credenciales de Allure en la interfaz.

💻 Integración con Claude Code

Para añadir Lucius a Claude Code, usa el siguiente comando desde el directorio de tu proyecto:

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

Ejemplo de configuración de texto con ámbito de proyecto (.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"
      }
    }
  }
}

🧠 Integración con Codex

Para añadir Lucius a Codex (CLI o extensión de IDE), usa:

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

Ejemplo de configuración de texto (~/.codex/config.toml o proyecto .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 una configuración detallada, incluida la integración con Claude Desktop (MCPB), consulta la Guía de Configuración.

🐍 Versiones de Python compatibles

Lucius admite Python 3.10 hasta 3.14 para uso en runtime. Los manifiestos MCPB generados y la matriz representativa del compilador CLI Nuitka validan el mismo rango. Python 3.9 no es compatible porque el starlette==1.3.1 fijado requiere Python 3.10 o superior; Python 3.15 se difiere porque el conjunto actual de dependencias nativas no se compila para esa versión.

💻 Interfaz de Línea de Comandos (CLI)

Lucius también proporciona un punto de entrada CLI universal para la ejecución directa de herramientas desde la línea de comandos:

# 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

Características de la CLI:

🎯 Invocación de entidades/acciones con seguridad de tipos y validación
🔐 Autenticación CLI persistente opcional con almacenamiento de configuración nativo por usuario
📊 Múltiples formatos de salida (JSON, tabla, csv, texto plano)
🔍 Ayuda por acción con parámetros y ejemplos
🛡️ Mensajes de error claros con orientación
📦 Binarios independientes para Linux, macOS y Windows

La precedencia de autenticación CLI es:

Argumentos explícitos de herramientas como api_token o project_id
Variables de entorno
Configuración de autenticación CLI guardada desde uv run lucius auth
Valores predeterminados

La autenticación CLI guardada usa ubicaciones de configuración nativas:

Linux/Unix: $XDG_CONFIG_HOME/lucius/auth.json o ~/.config/lucius/auth.json
macOS: ~/Library/Application Support/lucius/auth.json a menos que se establezcan explícitamente anulaciones XDG
Windows: %LOCALAPPDATA%\lucius\auth.json

Para la documentación completa de la CLI y las instrucciones de instalación, consulta la Guía CLI.

📡 Telemetría

Lucius recopila telemetría de uso que preserva la privacidad para mejorar la calidad de las herramientas. La telemetría está habilitada por defecto y envía metadatos a https://stats.ostanin.me, un endpoint operado por el propietario del proyecto (ningún tercero tiene acceso a este endpoint).

Si esto es aceptable en tu entorno, permanecer suscrito ayuda a mejorar Lucius con el tiempo. Si deseas optar por no participar, establece TELEMETRY_ENABLED=false en tu entorno.

No se envían tokens de API, contenido de pruebas ni argumentos de herramientas.

Consulta Telemetría y Privacidad para conocer el diccionario de datos completo y los detalles del comportamiento de la telemetría.

📂 Documentación

La documentación completa está disponible en la carpeta docs/:

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Consulta las Pautas de Contribución y la Guía de Desarrollo para más detalles.