JIRA Zephyr

Integra com o sistema de gerenciamento de testes Zephyr do JIRA.

GitHub
11
Experimente este MCPPatrocinado

Documentação

Servidor MCP JIRA Zephyr

Um servidor Model Context Protocol (MCP) que fornece integração abrangente com o sistema de gerenciamento de testes Zephyr do JIRA. Este servidor permite operações contínuas de gerenciamento de testes, incluindo criação de planos de teste, gerenciamento de ciclos de teste, execução de testes e leitura de issues do JIRA.

Recursos

Capacidades Principais

  • Gerenciamento de Planos de Teste: Crie e liste planos de teste no Zephyr
  • Gerenciamento de Ciclos de Teste: Crie e gerencie ciclos de execução de testes
  • Integração com JIRA: Leia detalhes e metadados de issues do JIRA
  • Execução de Testes: Atualize resultados e status de execução de testes
  • Acompanhamento de Progresso: Monitore o progresso e estatísticas de execução de testes
  • Vinculação de Issues: Associe casos de teste a issues do JIRA
  • Relatórios: Gere relatórios abrangentes de execução de testes

Ferramentas Disponíveis

  1. read_jira_issue - Recupera informações de issues do JIRA
  2. create_test_plan - Cria novos planos de teste no Zephyr
  3. list_test_plans - Navega pelos planos de teste existentes
  4. create_test_cycle - Cria ciclos de execução de testes
  5. list_test_cycles - Visualiza ciclos de teste com status de execução
  6. execute_test - Atualiza resultados de execução de testes
  7. get_test_execution_status - Verifica o progresso da execução de testes
  8. link_tests_to_issues - Associa testes a issues do JIRA
  9. generate_test_report - Cria relatórios de execução de testes

Pré-requisitos

  • Node.js 18.0.0 ou superior
  • Instância do JIRA com Zephyr Scale ou Zephyr Squad
  • Credenciais válidas da API do JIRA
  • Token de acesso à API do Zephyr

Integração com Cursor

Clone o projeto e adicione o seguinte à sua configuração do 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, você pode configurar o Cursor para executar o servidor MCP em Docker (certifique-se de que a imagem foi construída primeiro):

{
  "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"
      }
    }
  }
}

Instalação (para desenvolvimento)

  1. Clone o repositório:
git clone https://github.com/your-username/jira-zephyr-mcp.git
cd jira-zephyr-mcp
  1. Instale as dependências:
npm install
  1. Compile o projeto:
npm run build

Configuração

  1. Copie o arquivo de ambiente de exemplo:
cp .env.example .env
  1. Configure suas credenciais do JIRA e Zephyr em .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

Obtendo Tokens de API

Token da API do JIRA

  1. Acesse Configurações da Conta Atlassian
  2. Navegue até Segurança → Tokens de API
  3. Crie um novo token de API
  4. Copie o token para o seu arquivo .env

Token da API do Zephyr

  1. No JIRA, acesse Apps → Zephyr Scale → Tokens de Acesso à API
  2. Gere um novo token
  3. Copie o token para o seu arquivo .env

Uso

Desenvolvimento

npm run dev

Produção

npm start

Executando com Docker

Você pode containerizar e executar o servidor MCP usando Docker.

Pré-requisitos

  • Docker instalado no seu sistema
  • O projeto clonado localmente

Construindo a Imagem Docker

  1. Navegue até o diretório do projeto:
cd /path/to/jira-zephyr-mcp
  1. Construa a imagem Docker:
docker build -t jira-zephyr-mcp:latest .

Você pode especificar uma tag diferente, se desejar, por exemplo, -t jira-zephyr-mcp:v1.0.0.

Executando o Container

  1. Execute o container com as variáveis de ambiente necessárias:
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 integração com sistemas como o Cursor, use a configuração Docker mostrada na seção 'Integração com Cursor' acima. Certifique-se de que a imagem foi construída com a tag desejada que corresponda à sua configuração do Cursor. O servidor se comunica via stdio, então certifique-se de que sua configuração suporte isso ao executar em um container.

Exemplos de Uso das Ferramentas

Lendo Issues do JIRA

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

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

Criando Planos de Teste

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"
});

Gerenciando Ciclos de Teste

// 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
});

Execução de Testes

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

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

Gerando Relatórios

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

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

Tratamento de Erros

O servidor implementa tratamento abrangente de erros:

  • Validação de entrada usando esquemas Zod
  • Mapeamento de erros de API e mensagens amigáveis ao usuário
  • Tratamento de timeout de rede
  • Detecção de erros de autenticação

Desenvolvimento

Scripts

  • npm run build - Compila o projeto TypeScript
  • npm run dev - Executa em modo de desenvolvimento com monitoramento de arquivos
  • npm run lint - Executa ESLint
  • npm run typecheck - Executa verificação de tipos TypeScript

Estrutura do Projeto

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

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça suas alterações
  4. Adicione testes para novas funcionalidades
  5. Envie um pull request

Segurança

  • Nunca envie tokens de API ou credenciais para o repositório
  • Use variáveis de ambiente para toda configuração sensível
  • Rotacione os tokens de API regularmente
  • Implemente controles de acesso adequados na sua instância do JIRA

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes

Suporte

Para problemas e perguntas:

  1. Verifique as issues existentes no GitHub
  2. Crie uma nova issue com informações detalhadas
  3. Inclua logs de erro e configuração (sem dados sensíveis)

Roadmap

  • Suporte para Zephyr Squad (além do Zephyr Scale)
  • Operações de execução de testes em lote
  • Relatórios avançados com gráficos e métricas
  • Criação e gerenciamento de casos de teste
  • Integração com pipelines de CI/CD
  • Suporte a campos personalizados para gerenciamento de testes