Xray MCP Server

xray-cloud-mcp

Um servidor MCP para Xray Cloud (gerenciamento de testes para Jira). Ele permite que um cliente MCP (Claude Code, Claude Desktop, etc.) importe resultados de automação e gerencie entidades de teste do Xray — Testes, Execuções de Teste e Conjuntos de Teste — diretamente.

Ferramentas

Ferramenta	API	Leitura/Escrita	Finalidade
import_execution_junit	REST	gravação	Importar resultados JUnit XML em uma Execução de Teste
import_execution_xray	REST	gravação	Importar resultados nativos de execução Xray-JSON
get_tests	GraphQL	leitura	Consultar issues de Teste por JQL
create_test	GraphQL	gravação	Criar um Teste Manual/Cucumber/Genérico (com passos)
update_test	GraphQL	gravação	Alterar o tipo de um Teste e/ou anexar passos
get_test_executions	GraphQL	leitura	Consultar Execuções de Teste por JQL
create_test_execution	GraphQL	gravação	Criar uma Execução de Teste, opcionalmente com testes iniciais
add_tests_to_execution	GraphQL	gravação	Adicionar testes a uma execução existente
add_tests_to_test_set	GraphQL	gravação	Adicionar testes a um Conjunto de Teste existente

As ferramentas de gravação alteram o estado compartilhado do Jira/Xray — revise o destino antes de executá-las.

Credenciais

Crie uma API Key do Xray em Jira → Xray → Configurações Globais → API Keys (para um usuário de serviço). Isso gera um client_id + client_secret. O servidor os resolve na inicialização, nunca de um arquivo em disco, nesta ordem:

1. Variáveis de ambiente diretas XRAY_CLIENT_ID + XRAY_CLIENT_SECRET, se ambas estiverem definidas — o mais simples para uso local e CI.
2. Azure Key Vault — lê do cofre em XRAY_KEY_VAULT_URL via DefaultAzureCredential (az login localmente, identidade gerenciada no Azure). Útil quando você não quer segredos no ambiente.

Configuração

Variável	Obrigatório	Padrão	Finalidade
XRAY_CLIENT_ID / XRAY_CLIENT_SECRET	um dos dois métodos	—	Credenciais diretas
XRAY_KEY_VAULT_URL	(se não usar variáveis diretas)	—	Azure Key Vault para ler segredos
XRAY_CLIENT_ID_SECRET_NAME	não	xray-client-id	Nome do segredo no Key Vault para o client id
XRAY_CLIENT_SECRET_SECRET_NAME	não	xray-client-secret	Nome do segredo no Key Vault para o client secret
XRAY_BASE_URL	não	https://xray.cloud.getxray.app	Endpoint do Xray Cloud

Se você precisa apenas de autenticação por variáveis de ambiente diretas, as dependências de @azure/* ainda são instaladas, mas nunca invocadas. Remova-as e o ramo do Key Vault em src/config.ts se quiser um build mais enxuto.

Build

npm install
npm run build        # -> dist/
npm run auth-check   # resolves credentials + obtains a token (prints no secret)

Uso com um cliente MCP

Adicione ao seu config do cliente MCP (ex.: .mcp.json do Claude Code ou o config do Claude Desktop), apontando para o entrypoint compilado:

{
  "mcpServers": {
    "xray": {
      "command": "node",
      "args": ["/absolute/path/to/xray-cloud-mcp/dist/index.js"],
      "env": {
        "XRAY_CLIENT_ID": "your-client-id",
        "XRAY_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Ou, com Azure Key Vault em vez de segredos inline:

"env": {
  "XRAY_KEY_VAULT_URL": "https://your-vault.vault.azure.net"
}

Notas

• Descrição ao criar: alguns projetos do Jira tornam o campo Descrição obrigatório; create_test o padroniza para o resumo, de modo que a criação nunca falhe por falta dele.
• Importando resultados: aponte import_execution_junit para o JUnit XML que seu executor de testes gera (Playwright, Jest, JUnit, etc.). Use import_execution_xray para o JSON nativo mais rico do Xray.
• Somente stdio: o servidor fala MCP via stdio; diagnósticos vão para stderr (stdout é o canal do protocolo).

Licença

MIT — veja LICENSE.