Xray MCP Server

Model Context Protocol (MCP) server per integrare le API di Xray Cloud con Claude Code e altri client MCP.

Funzionalità

Questo server MCP espone strumenti per gestire test cases e test executions in Xray Cloud usando l'API GraphQL ufficiale:

Test Cases (Test Management)

• create_test_case: Crea un nuovo test case (usa GraphQL mutation createTest)

• get_test_case: Recupera i dettagli di un test case specifico (usa GraphQL query getTests)

• delete_test_case: Elimina un test case (usa GraphQL mutation deleteTest)

• search_test_cases: Cerca test cases usando JQL (Jira Query Language)

• get_project_test_cases: Recupera tutti i test cases di un progetto

• update_test_case: ⚠️ Non supportato direttamente - usa Jira REST API per aggiornare campi standard

Test Executions (Test Automation & CI/CD)

• create_test_execution: Crea una nuova test execution per eseguire test

• get_test_execution: Recupera dettagli di una test execution con tutti i test runs

• search_test_executions: Cerca test executions usando JQL

• get_project_test_executions: Recupera tutte le test executions di un progetto

• update_test_run_status: Aggiorna lo stato di un test run (PASS, FAIL, ecc.)

Test Plans (Test Organization)

• create_test_plan: Crea un nuovo test plan per organizzare test

• get_test_plan: Recupera dettagli di un test plan specifico con tutti i test

• search_test_plans: Cerca test plans usando JQL

• get_project_test_plans: Recupera tutti i test plans di un progetto

• add_tests_to_test_plan: Aggiungi test a un test plan esistente

• remove_tests_from_test_plan: Rimuovi test da un test plan

Test Sets (Test Grouping)

• create_test_set: Crea un nuovo test set per raggruppare test

• get_test_set: Recupera dettagli di un test set specifico con tutti i test

• search_test_sets: Cerca test sets usando JQL

• get_project_test_sets: Recupera tutti i test sets di un progetto

• add_tests_to_test_set: Aggiungi test a un test set esistente

• remove_tests_from_test_set: Rimuovi test da un test set

Prerequisiti

• Node.js 18 o superiore

• Credenziali API di Xray Cloud (Client ID e Client Secret)

Testing

This project includes comprehensive test coverage:

• Unit Tests: Fast tests with mocked API responses (no credentials needed)

• Integration Tests: End-to-end tests with real Xray Cloud API

For detailed testing documentation, see TESTING.md

Installazione

1. Clona o scarica questo repository

2. Installa le dipendenze:

3. Compila il progetto:

Come ottenere le credenziali API

1. Vai su https://xray.cloud.getxray.app/

2. Naviga in Settings → API Keys

3. Clicca su Create API Key

4. Copia il Client ID e il Client Secret generati

Utilizzo

Configurazione in Claude Code

Per usare questo server MCP con Claude Code, aggiungi la seguente configurazione al tuo file di configurazione MCP (solitamente ~/Library/Application Support/Claude/claude_desktop_config.json su macOS):

Importante: Sostituisci:

• /path/to/xray-mcp con il percorso assoluto del progetto (es. /Users/manuel/repositories/xray-mcp)

• your_client_id e your_client_secret con le tue credenziali Xray Cloud

Test locale

Per testare il server in modalità di sviluppo:

Esempi di utilizzo

Test Cases

Creare un test case

Cercare test cases

Recuperare test cases di un progetto

Test Executions

Creare una test execution

Recuperare una test execution

Aggiornare lo stato di un test run

Cercare test executions recenti

Struttura del progetto

API Xray Cloud

Questo server utilizza le seguenti API di Xray Cloud:

• Authentication: POST /api/v1/authenticate (token valido 24 ore)

• GraphQL Endpoint: POST /api/v2/graphql

  • Test Queries: getTests - Recupera test usando JQL

  • Test Mutations: createTest, deleteTest - Crea/elimina test

  • Test Execution Queries: getTestExecutions - Recupera executions usando JQL

  • Test Execution Mutations: createTestExecution, updateTestRunStatus - Gestisce executions e risultati

  • Test Plan Queries: getTestPlans - Recupera test plans usando JQL

  • Test Plan Mutations: createTestPlan, addTestsToTestPlan, removeTestsFromTestPlan - Gestisce test plans

  • Test Set Queries: getTestSets - Recupera test sets usando JQL

  • Test Set Mutations: createTestSet, addTestsToTestSet, removeTestsFromTestSet - Gestisce test sets

Per la documentazione completa delle API, visita:

• GraphQL API: https://docs.getxray.app/display/XRAYCLOUD/GraphQL+API

• Schema GraphQL: https://us.xray.cloud.getxray.app/doc/graphql/

• REST API: https://docs.getxray.app/display/XRAYCLOUD/REST+API

Sviluppo futuro

Funzionalità pianificate per future versioni:

• Gestione Test Executions ✅ (implementato)

• Gestione Test Plans e Test Sets ✅ (implementato)

• Gestione Test Steps (add/update/remove)

• Gestione Pre-conditions

• Integrazione con Test Repositories (folder management)

• Gestione Requirements e coverage tracking

• Bulk import/export di test results

Use Cases

Integrazione CI/CD

Usa questo server MCP per:

1. Creare test executions automaticamente nelle pipeline CI/CD

2. Aggiornare stati dei test runs in base ai risultati dei test automatici

3. Tracciare l'esecuzione dei test attraverso diversi ambienti

4. Generare report di test execution per sprint reviews

Test Management

Usa questo server MCP per:

1. Creare e organizzare test cases

2. Cercare test usando query JQL complesse

3. Gestire test executions manuali

4. Tracciare lo stato dei test nel tempo

Licenza

ISC

Supporto

Per problemi o domande sulle API di Xray Cloud, consulta la documentazione ufficiale:

• https://docs.getxray.app/

• https://support.getxray.app/