JIRA Zephyr

Se integra con el sistema de gestión de pruebas Zephyr de JIRA.

GitHub
11
Prueba este MCPPatrocinado

Documentación

Servidor MCP de JIRA Zephyr

Un servidor de Model Context Protocol (MCP) que proporciona integración completa con el sistema de gestión de pruebas Zephyr de JIRA. Este servidor permite operaciones de gestión de pruebas sin interrupciones, incluyendo la creación de planes de prueba, la gestión de ciclos de prueba, la ejecución de pruebas y la lectura de incidencias de JIRA.

Características

Capacidades principales

  • Gestión de planes de prueba: Crear y listar planes de prueba en Zephyr
  • Gestión de ciclos de prueba: Crear y gestionar ciclos de ejecución de pruebas
  • Integración con JIRA: Leer detalles y metadatos de incidencias de JIRA
  • Ejecución de pruebas: Actualizar resultados y estado de ejecución de pruebas
  • Seguimiento de progreso: Monitorear el progreso y las estadísticas de ejecución de pruebas
  • Vinculación de incidencias: Asociar casos de prueba con incidencias de JIRA
  • Informes: Generar informes completos de ejecución de pruebas

Herramientas disponibles

  1. read_jira_issue - Recuperar información de incidencias de JIRA
  2. create_test_plan - Crear nuevos planes de prueba en Zephyr
  3. list_test_plans - Explorar planes de prueba existentes
  4. create_test_cycle - Crear ciclos de ejecución de pruebas
  5. list_test_cycles - Ver ciclos de prueba con estado de ejecución
  6. execute_test - Actualizar resultados de ejecución de pruebas
  7. get_test_execution_status - Verificar el progreso de ejecución de pruebas
  8. link_tests_to_issues - Asociar pruebas con incidencias de JIRA
  9. generate_test_report - Crear informes de ejecución de pruebas

Requisitos previos

  • Node.js 18.0.0 o superior
  • Instancia de JIRA con Zephyr Scale o Zephyr Squad
  • Credenciales válidas de la API de JIRA
  • Token de acceso a la API de Zephyr

Integración con Cursor

Clone el proyecto y luego agregue lo siguiente a su configuración de Cursor:

{
  "mcpServers": {
    "jira-zephyr": {
      "command": "node",
      "args": ["/path/to/jira-zephyr-mcp/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-email@company.com",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "ZEPHYR_API_TOKEN": "your-zephyr-api-token"
      }
    }
  }
}

Usando Docker

Alternativamente, puede configurar Cursor para ejecutar el servidor MCP en Docker (asegúrese de que la imagen esté construida primero):

{
  "mcpServers": {
    "jira-zephyr": {
      "command": "docker",
      "args": ["run", "--rm", "-i","-e","JIRA_BASE_URL","-e","JIRA_USERNAME","-e","JIRA_API_TOKEN","-e","ZEPHYR_API_TOKEN", "jira-zephyr-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-email@company.com",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "ZEPHYR_API_TOKEN": "your-zephyr-api-token"
      }
    }
  }
}

Instalación (para desarrollo)

  1. Clone el repositorio:
git clone https://github.com/your-username/jira-zephyr-mcp.git
cd jira-zephyr-mcp
  1. Instale las dependencias:
npm install
  1. Construya el proyecto:
npm run build

Configuración

  1. Copie el archivo de entorno de ejemplo:
cp .env.example .env
  1. Configure sus credenciales de JIRA y Zephyr en .env:
JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_USERNAME=your-email@company.com
JIRA_API_TOKEN=your-jira-api-token
ZEPHYR_API_TOKEN=your-zephyr-api-token

Obtención de tokens de API

Token de API de JIRA

  1. Vaya a Configuración de la cuenta de Atlassian
  2. Navegue a Seguridad → Tokens de API
  3. Cree un nuevo token de API
  4. Copie el token a su archivo .env

Token de API de Zephyr

  1. En JIRA, vaya a Aplicaciones → Zephyr Scale → Tokens de acceso a la API
  2. Genere un nuevo token
  3. Copie el token a su archivo .env

Uso

Desarrollo

npm run dev

Producción

npm start

Ejecución con Docker

Puede contenerizar y ejecutar el servidor MCP usando Docker.

Requisitos previos

  • Docker instalado en su sistema
  • El proyecto clonado localmente

Construcción de la imagen Docker

  1. Navegue al directorio del proyecto:
cd /path/to/jira-zephyr-mcp
  1. Construya la imagen Docker:
docker build -t jira-zephyr-mcp:latest .

Puede especificar una etiqueta diferente si lo desea, por ejemplo, -t jira-zephyr-mcp:v1.0.0.

Ejecución del contenedor

  1. Ejecute el contenedor con las variables de entorno requeridas:
docker run -d --name jira-zephyr-mcp \
  -e JIRA_BASE_URL=https://your-domain.atlassian.net \
  -e JIRA_USERNAME=your-email@company.com \
  -e JIRA_API_TOKEN=your-jira-api-token \
  -e ZEPHYR_API_TOKEN=your-zephyr-api-token \
  jira-zephyr-mcp:latest

Nota: Para la integración con sistemas como Cursor, use la configuración de Docker que se muestra en la sección 'Integración con Cursor' anterior. Asegúrese de que la imagen esté construida con la etiqueta deseada que coincida con su configuración de Cursor. El servidor se comunica a través de stdio, así que asegúrese de que su configuración lo soporte al ejecutarlo en un contenedor.

Ejemplos de uso de herramientas

Lectura de incidencias de JIRA

// Read basic issue information
await readJiraIssue({ issueKey: "ABC-123" });

// Read specific fields
await readJiraIssue({ 
  issueKey: "ABC-123", 
  fields: ["summary", "status", "assignee"] 
});

Creación de planes de prueba

await createTestPlan({
  name: "Release 2.0 Test Plan",
  description: "Comprehensive testing for release 2.0",
  projectKey: "ABC",
  startDate: "2024-01-15",
  endDate: "2024-01-30"
});

Gestión de ciclos de prueba

// Create a test cycle
await createTestCycle({
  name: "Sprint 10 Testing",
  description: "Testing for sprint 10 features",
  projectKey: "ABC",
  versionId: "10001",
  environment: "Production"
});

// List test cycles
await listTestCycles({
  projectKey: "ABC",
  limit: 25
});

Ejecución de pruebas

// Update test execution status
await executeTest({
  executionId: "12345",
  status: "PASS",
  comment: "All tests passed successfully"
});

// Get execution status
await getTestExecutionStatus({ cycleId: "67890" });

Generación de informes

// Generate JSON report
await generateTestReport({
  cycleId: "67890",
  format: "JSON"
});

// Generate HTML report
await generateTestReport({
  cycleId: "67890",
  format: "HTML"
});

Manejo de errores

El servidor implementa un manejo integral de errores:

  • Validación de entrada usando esquemas de Zod
  • Mapeo de errores de API y mensajes fáciles de usar
  • Manejo de tiempos de espera de red
  • Detección de errores de autenticación

Desarrollo

Scripts

  • npm run build - Construir el proyecto TypeScript
  • npm run dev - Ejecutar en modo de desarrollo con monitoreo de archivos
  • npm run lint - Ejecutar ESLint
  • npm run typecheck - Ejecutar verificación de tipos de TypeScript

Estructura del proyecto

src/
├── index.ts              # Main MCP server entry point
├── clients/              # API clients
│   ├── jira-client.ts    # JIRA REST API client
│   └── zephyr-client.ts  # Zephyr API client
├── tools/                # MCP tool implementations
│   ├── jira-issues.ts    # JIRA issue tools
│   ├── test-plans.ts     # Test plan management
│   ├── test-cycles.ts    # Test cycle management
│   └── test-execution.ts # Test execution tools
├── types/                # TypeScript type definitions
│   ├── jira-types.ts     # JIRA API types
│   └── zephyr-types.ts   # Zephyr API types
└── utils/                # Utility functions
    ├── config.ts         # Configuration management
    └── validation.ts     # Input validation schemas

Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Realice sus cambios
  4. Agregue pruebas para la nueva funcionalidad
  5. Envíe una solicitud de extracción (pull request)

Seguridad

  • Nunca comprometa tokens de API o credenciales en el repositorio
  • Use variables de entorno para toda la configuración sensible
  • Rote los tokens de API regularmente
  • Implemente controles de acceso adecuados en su instancia de JIRA

Licencia

Licencia MIT - consulte el archivo LICENSE para más detalles

Soporte

Para problemas y preguntas:

  1. Revise los problemas existentes en GitHub
  2. Cree un nuevo problema con información detallada
  3. Incluya registros de errores y configuración (sin datos sensibles)

Hoja de ruta

  • Soporte para Zephyr Squad (además de Zephyr Scale)
  • Operaciones de ejecución de pruebas en lote
  • Informes avanzados con gráficos y métricas
  • Creación y gestión de casos de prueba
  • Integración con pipelines de CI/CD
  • Soporte de campos personalizados para la gestión de pruebas