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

# Run unit tests
npm run test:unit

# Run integration tests (requires credentials)
npm run test:integration

# Run all tests
npm test

For detailed testing documentation, see TESTING.md

Installazione

1. Clona o scarica questo repository
2. Installa le dipendenze:

npm install

3. Compila il progetto:

npm run build

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):

{
  "mcpServers": {
    "xray": {
      "command": "node",
      "args": ["/path/to/xray-mcp/dist/index.js"],
      "env": {
        "XRAY_CLIENT_ID": "your_client_id",
        "XRAY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

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:

# Imposta le variabili d'ambiente
export XRAY_CLIENT_ID="your_client_id"
export XRAY_CLIENT_SECRET="your_client_secret"

# Esegui il server
npm run dev

Esempi di utilizzo

Test Cases

Creare un test case

{
  "projectKey": "ABC",
  "summary": "Verify login functionality",
  "description": "Test that users can log in with valid credentials",
  "testType": "Manual",
  "labels": ["login", "authentication"],
  "priority": "High"
}

Cercare test cases

{
  "jql": "project = ABC AND labels = automation",
  "maxResults": 20
}

Recuperare test cases di un progetto

{
  "projectKey": "ABC",
  "maxResults": 50
}

Test Executions

Creare una test execution

{
  "projectKey": "ABC",
  "summary": "Sprint 23 Regression Tests",
  "description": "Regression testing for sprint 23",
  "testIssueIds": ["10001", "10002", "10003"],
  "testEnvironments": ["Chrome", "Firefox"]
}

Recuperare una test execution

{
  "testExecutionKey": "ABC-456"
}

Aggiornare lo stato di un test run

{
  "testRunId": "5acc7ab0a3fe1b6fcdc3c737",
  "status": "PASS"
}

Cercare test executions recenti

{
  "jql": "project = ABC AND created >= -7d",
  "maxResults": 20
}

Struttura del progetto

xray-mcp/
├── src/
│   ├── index.ts           # Server MCP principale
│   └── xray-client.ts     # Client per le API di Xray Cloud
├── dist/                  # File compilati (generati dopo build)
├── .env.example           # Template per le variabili d'ambiente
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

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:

• [x] Gestione Test Executions ✅ (implementato)
• [x] 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/