Zephyr Scale

Gestiona casos de prueba de Zephyr Scale a través de la API REST de Atlassian.

GitHub
6
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Zephyr Scale

Servidor del Protocolo de Contexto de Modelos (MCP) para la gestión de pruebas de Zephyr Scale, compatible con Jira Cloud y Data Center. Crea, lee y gestiona casos de prueba a través de la API REST de Atlassian con esquemas oficiales compatibles con la API. Accede a datos de casos de prueba en vivo, cargas útiles de ejemplo y recursos de archivos a través de un sistema de recursos unificado.

Características

  • ✅ Compatibilidad con Jira Cloud y Data Center: Se conecta sin problemas tanto a Jira Cloud (usando API v2) como a instancias de Data Center autoalojadas (usando API v1) con detección automática de configuración.
  • ✅ Esquemas oficiales compatibles con la API: Las herramientas y estructuras de datos coinciden con la API REST oficial de Zephyr Scale, garantizando compatibilidad y fiabilidad.
  • ✅ Creación unificada de casos de prueba: Una única herramienta create_test_case maneja todos los tipos de script (BDD, Paso a Paso, Texto Plano) para un flujo de trabajo simplificado.
  • ✅ Gestión completa del ciclo de vida de pruebas: Herramientas integrales para crear, leer, eliminar casos de prueba y gestionar ejecuciones, ejecuciones de pruebas y carpetas.
  • ✅ Informes de ejecución e integración con Jira (Cloud): Reporta resultados de ejecución (Aprobado/Reprobado/Bloqueado), adjunta errores como enlaces de incidencias de Jira y descubre el ciclo de prueba de Zephyr vinculado a cualquier historia o épica de Jira — conectando un ticket de Jira directamente con sus ejecuciones.
  • ✅ Sistema de plantillas en vivo: Usa casos de prueba reales de tu instancia de Zephyr como plantillas (zephyr://testcase/KEY) para garantizar consistencia y campos específicos del proyecto correctos.
  • ✅ Sistema de recursos unificado: Accede a datos de Zephyr en vivo, archivos locales (file://) y ejemplos integrados a través de un sistema basado en URI consistente.

Instalación y Configuración

Puedes ejecutar el servidor usando npx sin instalación, o instalarlo globalmente desde npm.

Usando npx (Recomendado)

Configura tu cliente MCP con la siguiente estructura.

Jira Cloud:

{
  "mcpServers": {
    "zephyr-server": {
      "command": "npx",
      "args": ["zephyr-scale-mcp-server@latest"],
      "env": {
        "ZEPHYR_BASE_URL": "https://your-company.atlassian.net",
        "ZEPHYR_API_KEY": "your-zephyr-api-key",
        "JIRA_USERNAME": "your-email@company.com",
        "JIRA_API_TOKEN": "your-jira-api-token"
      }
    }
  }
}

Nota: JIRA_USERNAME y JIRA_API_TOKEN son opcionales pero requeridos si deseas usar el campo issue_links al crear casos de prueba. Sin ellos, el enlace de incidencias fallará con una advertencia 401 (el caso de prueba aún se crea). Genera un token de API de Jira en id.atlassian.com/manage-profile/security/api-tokens.

Jira Cloud (región UE):

{
  "mcpServers": {
    "zephyr-server": {
      "command": "npx",
      "args": ["zephyr-scale-mcp-server@latest"],
      "env": {
        "ZEPHYR_BASE_URL": "https://your-company.atlassian.net",
        "ZEPHYR_API_KEY": "your-zephyr-api-key",
        "JIRA_USERNAME": "your-email@company.com",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "ZEPHYR_API_BASE_URL": "https://eu.api.zephyrscale.smartbear.com/v2"
      }
    }
  }
}

Jira Data Center:

{
  "mcpServers": {
    "zephyr-server": {
      "command": "npx",
      "args": ["zephyr-scale-mcp-server@latest"],
      "env": {
        "ZEPHYR_BASE_URL": "https://your-jira-server.com",
        "ZEPHYR_API_KEY": "your-api-token"
      }
    }
  }
}

Usando instalación global de npm

Primero instala el paquete globalmente:

npm install -g zephyr-scale-mcp-server

Luego, actualiza el command en tu configuración de MCP a "command": "zephyr-scale-mcp".

Conceptos Clave

API Unificada

La versión más reciente presenta una herramienta create_test_case unificada que admite todos los tipos de script de prueba (STEP_BY_STEP, PLAIN_TEXT y BDD) a través de una interfaz única y consistente. Esto coincide exactamente con la estructura de la API REST v1 oficial de Zephyr Scale, simplificando el proceso de creación de pruebas.

Jira Cloud vs. Data Center

El servidor detecta automáticamente tu entorno de Jira y usa la versión de API apropiada:

  • Jira Cloud: Usa la API v2 de Zephyr Scale.
  • Jira Data Center: Usa la API v1 de Zephyr Scale.

Algunas herramientas son específicas de la plataforma. Por ejemplo, add_test_cases_to_run solo está disponible en Cloud, ya que la API de Data Center (v1) no admite la modificación de ejecuciones de prueba después de su creación.

Sistema de Recursos

El servidor proporciona acceso a varios recursos a través de esquemas URI:

  • zephyr://testcase/YOUR-TEST-CASE-KEY: Obtén datos reales de casos de prueba de tu instancia de Zephyr para usarlos como plantillas.
  • file:///absolute/path/to/your/file.json: Lee archivos proporcionados por el usuario.
  • zephyr://examples/...: Accede a cargas útiles de ejemplo integradas.

Referencia de Herramientas

Gestión de Casos de Prueba

  • get_test_case: Obtén información detallada sobre un caso de prueba específico.
  • create_test_case: Crea casos de prueba con contenido STEP_BY_STEP, PLAIN_TEXT o BDD.
  • delete_test_case: Elimina un caso de prueba específico.
  • update_test_case_bdd: Actualiza un caso de prueba existente con contenido BDD (opcionalmente actualiza el nombre del caso de prueba).

Gestión de Ejecuciones de Prueba

  • create_test_run: Crea una nueva ejecución de prueba.
  • get_test_run: Obtén información detallada sobre una ejecución de prueba específica, incluido el nombre de estado resuelto.
  • update_test_run: Actualiza un ciclo de prueba existente — establece propietario, nombre, descripción, fechas o estado. (Solo Cloud)
  • get_test_run_cases: Obtén las claves de casos de prueba de una ejecución de prueba.
  • add_test_cases_to_run: Agrega casos de prueba a una ejecución de prueba existente. (Solo Cloud)

Ejecución de Pruebas y Búsqueda

  • get_test_execution: Obtén resultados detallados de ejecuciones de prueba individuales.
  • list_executions_by_cycle: Lista todas las ejecuciones de prueba para un ciclo de prueba específico con estado, ejecutor y fecha. (Solo Cloud)
  • update_test_execution: Actualiza el estado de la ejecución de un caso de prueba dentro de un ciclo (Aprobado/Reprobado/etc.), agrega un comentario y adjunta errores como enlaces de incidencias de Jira. Identifica la ejecución por execution_id, o por test_cycle_key + test_case_key. (Solo Cloud)
  • search_test_cases_by_folder: Busca casos de prueba en una carpeta específica. Pagina automáticamente a través de todos los resultados.
  • search_test_runs: Busca ejecuciones de prueba por clave de proyecto y/o ruta de carpeta.
  • get_test_cycles_for_issue: Obtén los ciclos de prueba de Zephyr vinculados a una incidencia de Jira (historia/épica). Resuelve cada ID de ciclo a su clave (por ejemplo, PROJ-R123) y nombre para que puedas alimentarlo directamente en list_executions_by_cycle / update_test_execution. (Solo Cloud)

Organización

  • create_folder: Crea una nueva carpeta en Zephyr Scale.
  • get_folders: Lista carpetas, opcionalmente filtradas por proyecto, tipo y ruta. Cuando se proporciona folder_path, devuelve la carpeta coincidente y su subárbol completo a cada profundidad.

Ejemplos de Uso

Crear un Caso de Prueba BDD con Enlaces de Incidencias

{
  "project_key": "PROJ",
  "name": "User Authentication",
  "test_script": {
    "type": "BDD",
    "text": "Given a user with valid credentials\nWhen the user attempts to log in\nThen the user should be authenticated successfully"
  },
  "issue_links": ["PROJ-123", "PROJ-456"]
}

Nota: issue_links requiere que JIRA_USERNAME y JIRA_API_TOKEN estén configurados (solo Cloud). Los fallos de enlace se reportan como advertencias — el caso de prueba aún se crea.

Usar un Caso de Prueba en Vivo como Plantilla

  1. Obtén un caso de prueba existente: zephyr://testcase/PROJ-T123
  2. Copia su estructura (especialmente customFields y folder).
  3. Crea un nuevo caso de prueba usando la misma configuración específica del proyecto.

Crear una Ejecución de Prueba

{
  "project_key": "PROJ",
  "name": "Sprint 1 Test Run",
  "test_case_keys": ["PROJ-T123", "PROJ-T124", "PROJ-T125"]
}

Actualizar un Caso de Prueba BDD Existente

{
  "test_case_key": "PROJ-T123",
  "name": "Ensure the axial-flow pump is enabled",
  "bdd_content": "Feature: Pump Enablement\n\nScenario: Enable the pump\n  Given the system is powered on\n  When the operator enables the axial-flow pump\n  Then the pump should report as enabled"
}

Nota: El servidor convertirá BDD estilo markdown a Gherkin cuando sea posible y preservará todos los demás campos existentes del caso de prueba.

Marcar una Ejecución como Reprobada y Adjuntar un Error

{
  "test_cycle_key": "PROJ-R123",
  "test_case_key": "PROJ-T456",
  "status": "Fail",
  "comment": "Login button unresponsive on submit.",
  "bug_keys": ["PROJ-789"]
}

O apunta a una ejecución directamente por clave:

{
  "execution_id": "PROJ-E123",
  "status": "Pass"
}

Nota: update_test_execution es solo Cloud. bug_keys requiere JIRA_USERNAME y JIRA_API_TOKEN; los fallos de enlace se reportan como advertencias mientras que la actualización de estado aún tiene éxito.

Encontrar el Ciclo de Prueba Vinculado a un Ticket de Jira

{
  "issue_key": "PROJ-6752"
}

Devuelve los ciclos vinculados con claves resueltas, por ejemplo, [{ "id": "110702963", "key": "PROJ-R467", "name": "..." }]. Este es el puente desde un ticket de Jira hasta su ciclo de Zephyr — la asociación se almacena en el lado de Zephyr, no en los campos de incidencia de Jira. Encadénalo: get_test_cycles_for_issue → list_executions_by_cycle → update_test_execution. Pasa "resolve_keys": false para omitir la búsqueda de clave/nombre por ciclo y devolver solo IDs sin procesar. Solo Cloud.

Autenticación

Configuración de Jira Cloud

VariableRequeridaDescripción
ZEPHYR_BASE_URL✅Tu URL de Jira Cloud, por ejemplo, https://your-company.atlassian.net
ZEPHYR_API_KEY✅Clave de API de Zephyr Scale (JWT). Genérala en Jira: foto de perfil (abajo a la izquierda) → Claves de API de Zephyr
JIRA_USERNAME⚠️ Opcional*Tu dirección de correo electrónico de la cuenta de Jira
JIRA_API_TOKEN⚠️ Opcional*Token de API de Jira. Genéralo en id.atlassian.com/manage-profile/security/api-tokens
ZEPHYR_API_BASE_URLOpcionalAnula la URL base de la API de Zephyr (por ejemplo, para UE: https://eu.api.zephyrscale.smartbear.com/v2). El valor predeterminado es el endpoint de EE. UU.
JIRA_TYPEOpcionalFuerza "cloud" o "datacenter" — anula la detección automática

* JIRA_USERNAME + JIRA_API_TOKEN: Requeridos solo para la función issue_links en Cloud. La clave de API de Zephyr no puede autenticarse contra la API REST de Jira, por lo que se necesita una credencial separada de Jira para resolver claves de incidencia a IDs numéricos. Sin estos, issue_links fallará con una advertencia 401 — el caso de prueba aún se crea con éxito.

Configuración de Jira Data Center

VariableRequeridaDescripción
ZEPHYR_BASE_URL✅Tu URL del servidor de Jira, por ejemplo, https://your-jira-server.com
ZEPHYR_API_KEY✅Token de API de Zephyr Scale desde la configuración de tu perfil de Jira
JIRA_TYPEOpcionalEstablécelo en "datacenter" para anular la detección automática

Detección Automática

El servidor detecta automáticamente tu tipo de Jira basándose en ZEPHYR_BASE_URL — las URL que contienen .atlassian.net se tratan como Cloud, todo lo demás como Data Center. Anula con JIRA_TYPE="cloud" o JIRA_TYPE="datacenter".

Licencia

MIT