Zephyr Scale

Gerencie casos de teste do Zephyr Scale através da API REST do Atlassian.

Documentação

Servidor MCP Zephyr Scale

Servidor Model Context Protocol para gerenciamento de testes Zephyr Scale, com suporte para Jira Cloud e Data Center. Crie, leia e gerencie casos de teste através da API REST da Atlassian com esquemas oficiais compatíveis com a API. Acesse dados de casos de teste em tempo real, exemplos de payloads e recursos de arquivos através de um sistema de recursos unificado.

Recursos

✅ Suporte a Jira Cloud e Data Center: Conecta-se perfeitamente tanto ao Jira Cloud (usando API v2) quanto a instâncias Data Center auto-hospedadas (usando API v1) com detecção automática de configuração.
✅ Esquemas Oficiais Compatíveis com a API: Ferramentas e estruturas de dados correspondem à API REST oficial do Zephyr Scale, garantindo compatibilidade e confiabilidade.
✅ Criação Unificada de Casos de Teste: Uma única ferramenta create_test_case lida com todos os tipos de script (BDD, Passo a Passo, Texto Simples) para um fluxo de trabalho simplificado.
✅ Gerenciamento Completo do Ciclo de Vida de Testes: Ferramentas abrangentes para criar, ler, excluir casos de teste e gerenciar execuções de teste, execuções e pastas.
✅ Sistema de Modelos ao Vivo: Use casos de teste reais da sua instância Zephyr como modelos (zephyr://testcase/KEY) para garantir consistência e campos corretos específicos do projeto.
✅ Sistema de Recursos Unificado: Acesse dados Zephyr ao vivo, arquivos locais (file://) e exemplos integrados através de um sistema consistente baseado em URI.

Instalação e Configuração

Você pode executar o servidor usando npx sem instalação, ou instalá-lo globalmente a partir de npm.

Usando npx (Recomendado)

Configure seu cliente MCP com a seguinte estrutura.

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 e JIRA_API_TOKEN são opcionais, mas necessários se você quiser usar o campo issue_links ao criar casos de teste. Sem eles, a vinculação de issues falhará com um aviso 401 (o caso de teste ainda é criado). Gere um token de API do Jira em id.atlassian.com/manage-profile/security/api-tokens.

Jira Cloud (região 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 instalação global via npm

Primeiro, instale o pacote globalmente:

npm install -g zephyr-scale-mcp-server

Em seguida, atualize o command na sua configuração MCP para "command": "zephyr-scale-mcp".

Conceitos Principais

API Unificada

A versão mais recente apresenta uma ferramenta create_test_case unificada que suporta todos os tipos de script de teste (STEP_BY_STEP, PLAIN_TEXT e BDD) através de uma interface única e consistente. Isso corresponde exatamente à estrutura da API REST oficial do Zephyr Scale v1, simplificando o processo de criação de testes.

Jira Cloud vs. Data Center

O servidor detecta automaticamente seu ambiente Jira e usa a versão apropriada da API:

Jira Cloud: Usa a API v2 do Zephyr Scale.
Jira Data Center: Usa a API v1 do Zephyr Scale.

Algumas ferramentas são específicas da plataforma. Por exemplo, add_test_cases_to_run está disponível apenas no Cloud, pois a API do Data Center (v1) não suporta modificar execuções de teste após a criação.

Sistema de Recursos

O servidor fornece acesso a vários recursos através de esquemas de URI:

zephyr://testcase/YOUR-TEST-CASE-KEY: Busque dados reais de casos de teste da sua instância Zephyr para usar como modelos.
file:///absolute/path/to/your/file.json: Leia arquivos fornecidos pelo usuário.
zephyr://examples/...: Acesse exemplos de payloads integrados.

Referência de Ferramentas

Gerenciamento de Casos de Teste

get_test_case: Obtenha informações detalhadas sobre um caso de teste específico.
create_test_case: Crie casos de teste com conteúdo STEP_BY_STEP, PLAIN_TEXT ou BDD.
delete_test_case: Exclua um caso de teste específico.
update_test_case_bdd: Atualize um caso de teste existente com conteúdo BDD (opcionalmente atualize o nome do caso de teste).

Gerenciamento de Execuções de Teste

create_test_run: Crie uma nova execução de teste.
get_test_run: Obtenha informações detalhadas sobre uma execução de teste específica, incluindo o nome do status resolvido.
update_test_run: Atualize um ciclo de teste existente — defina proprietário, nome, descrição, datas ou status. (Somente Cloud)
get_test_run_cases: Obtenha as chaves dos casos de teste de uma execução de teste.
add_test_cases_to_run: Adicione casos de teste a uma execução de teste existente. (Somente Cloud)

Execução de Testes e Pesquisa

get_test_execution: Obtenha resultados detalhados de execuções de teste individuais.
list_executions_by_cycle: Liste todas as execuções de teste para um ciclo de teste específico com status, executor e data. (Somente Cloud)
search_test_cases_by_folder: Pesquise casos de teste em uma pasta específica. Pagina automaticamente por todos os resultados.
search_test_runs: Pesquise execuções de teste por chave de projeto e/ou caminho de pasta.

Organização

create_folder: Crie uma nova pasta no Zephyr Scale.
get_folders: Liste pastas, opcionalmente filtradas por projeto, tipo e caminho. Quando folder_path é fornecido, retorna a pasta correspondente e sua subárvore completa em todas as profundidades.

Exemplos de Uso

Criar um Caso de Teste BDD com Links de Issues

{
  "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 requer que JIRA_USERNAME e JIRA_API_TOKEN estejam definidos (somente Cloud). Falhas de vinculação são relatadas como avisos — o caso de teste ainda é criado.

Usar um Caso de Teste ao Vivo como Modelo

Busque um caso de teste existente: zephyr://testcase/PROJ-T123
Copie sua estrutura (especialmente customFields e folder).
Crie um novo caso de teste usando a mesma configuração específica do projeto.

Criar uma Execução de Teste

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

Atualizar um Caso de Teste 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: O servidor converterá BDD em estilo markdown para Gherkin quando possível e preservará todos os outros campos existentes do caso de teste.

Autenticação

Configuração do Jira Cloud

Variável	Obrigatório	Descrição
`ZEPHYR_BASE_URL`	✅	Sua URL do Jira Cloud, ex.: `https://your-company.atlassian.net`
`ZEPHYR_API_KEY`	✅	Chave da API do Zephyr Scale (JWT). Gere no Jira: foto do perfil (canto inferior esquerdo) → Chaves de API do Zephyr
`JIRA_USERNAME`	⚠️ Opcional*	Seu endereço de e-mail da conta Jira
`JIRA_API_TOKEN`	⚠️ Opcional*	Token da API do Jira. Gere em id.atlassian.com/manage-profile/security/api-tokens
`ZEPHYR_API_BASE_URL`	Opcional	Substitua a URL base da API do Zephyr (ex.: para UE: `https://eu.api.zephyrscale.smartbear.com/v2`). O padrão é o endpoint dos EUA.
`JIRA_TYPE`	Opcional	Force `"cloud"` ou `"datacenter"` — substitui a detecção automática

* JIRA_USERNAME + JIRA_API_TOKEN: Necessários apenas para o recurso issue_links no Cloud. A chave da API do Zephyr não pode autenticar contra a API REST do Jira, portanto, é necessária uma credencial separada do Jira para resolver chaves de issues em IDs numéricos. Sem elas, issue_links falhará com um aviso 401 — o caso de teste ainda é criado com sucesso.

Configuração do Jira Data Center

Variável	Obrigatório	Descrição
`ZEPHYR_BASE_URL`	✅	Sua URL do servidor Jira, ex.: `https://your-jira-server.com`
`ZEPHYR_API_KEY`	✅	Token da API do Zephyr Scale das configurações do seu perfil Jira
`JIRA_TYPE`	Opcional	Defina como `"datacenter"` para substituir a detecção automática

Detecção Automática

O servidor detecta automaticamente seu tipo de Jira com base em ZEPHYR_BASE_URL — URLs contendo .atlassian.net são tratadas como Cloud, todo o resto como Data Center. Substitua com JIRA_TYPE="cloud" ou JIRA_TYPE="datacenter".

Licença

MIT