Zephyr Scale

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

Documentación

Servidor MCP de Zephyr Scale

Servidor del Protocolo de Contexto de Modelo 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 mediante 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 de prueba, ejecuciones y carpetas.
✅ 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 en vivo de Zephyr, 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 necesarios 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 última versión 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 adecuada:

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 modificar ejecuciones de prueba después de su creación.

Sistema de Recursos

El servidor proporciona acceso a varios recursos mediante esquemas de 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)
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.

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 en cada profundidad.

Ejemplos de Uso

Crear un Caso de Prueba BDD con Enlaces de Incidencia

{
  "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 informan como advertencias: el caso de prueba aún se crea.

Usar un Caso de Prueba en Vivo como Plantilla

Obtén un caso de prueba existente: zephyr://testcase/PROJ-T123
Copia su estructura (especialmente customFields y folder).
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 en estilo markdown a Gherkin cuando sea posible y conservará todos los demás campos existentes del caso de prueba.

Autenticación

Configuración de Jira Cloud

Variable	Requerido	Descripción
`ZEPHYR_BASE_URL`	✅	Tu URL de Jira Cloud, p. ej. `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 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_URL`	Opcional	Sobrescribe la URL base de la API de Zephyr (p. ej. para UE: `https://eu.api.zephyrscale.smartbear.com/v2`). Por defecto usa el endpoint de EE. UU.
`JIRA_TYPE`	Opcional	Fuerza `"cloud"` o `"datacenter"`: sobrescribe 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 de Jira separada 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 correctamente.

Configuración de Jira Data Center

Variable	Requerido	Descripción
`ZEPHYR_BASE_URL`	✅	Tu URL del servidor de Jira, p. ej. `https://your-jira-server.com`
`ZEPHYR_API_KEY`	✅	Token de API de Zephyr Scale desde la configuración de tu perfil de Jira
`JIRA_TYPE`	Opcional	Establécelo en `"datacenter"` para sobrescribir 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. Sobrescribe con JIRA_TYPE="cloud" o JIRA_TYPE="datacenter".

Licencia

MIT