# Xray MCP Server

Model Context Protocol (MCP) server to integrate Xray Cloud APIs with Claude Code and other MCP clients.

## Features

This MCP server exposes tools to manage test cases and test executions in Xray Cloud using the official GraphQL API:

### Test Cases (Test Management)
- **create_test_case**: Create a new test case (uses GraphQL mutation `createTest`)
- **get_test_case**: Retrieve details of a specific test case (uses GraphQL query `getTests`)
- **delete_test_case**: Delete a test case (uses GraphQL mutation `deleteTest`)
- **search_test_cases**: Search test cases using JQL (Jira Query Language)
- **get_project_test_cases**: Retrieve all test cases for a project
- **update_test_case**: ⚠️ Not directly supported - use Jira REST API to update standard fields

### Test Executions (Test Automation & CI/CD)
- **create_test_execution**: Create a new test execution to run tests
- **get_test_execution**: Retrieve details of a test execution with all test runs
- **search_test_executions**: Search test executions using JQL
- **get_project_test_executions**: Retrieve all test executions for a project
- **update_test_run_status**: Update the status of a test run (PASS, FAIL, etc.)

### Test Plans (Test Organization)
- **create_test_plan**: Create a new test plan to organize tests
- **get_test_plan**: Retrieve details of a specific test plan with all tests
- **search_test_plans**: Search test plans using JQL
- **get_project_test_plans**: Retrieve all test plans for a project
- **add_tests_to_test_plan**: Add tests to an existing test plan
- **remove_tests_from_test_plan**: Remove tests from a test plan

### Test Sets (Test Grouping)
- **create_test_set**: Create a new test set to group tests
- **get_test_set**: Retrieve details of a specific test set with all tests
- **search_test_sets**: Search test sets using JQL
- **get_project_test_sets**: Retrieve all test sets for a project
- **add_tests_to_test_set**: Add tests to an existing test set
- **remove_tests_from_test_set**: Remove tests from a test set

## Prerequisites

- Node.js 18 or higher
- Xray Cloud API credentials (Client ID and 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

```bash
# 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](./TESTING.md)

## Installation

1. Clone or download this repository
2. Install dependencies:

```bash
npm install
```

3. Build the project:

```bash
npm run build
```

### How to Obtain API Credentials

1. Go to https://xray.cloud.getxray.app/
2. Navigate to **Settings** → **API Keys**
3. Click on **Create API Key**
4. Copy the generated Client ID and Client Secret

## Usage

### Configuration in Claude Code

To use this MCP server with Claude Code, add the following configuration to your MCP configuration file (typically `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

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

**Important:** Replace:
- `/path/to/xray-mcp` with the absolute path to the project (e.g., `/Users/manuel/repositories/xray-mcp`)
- `your_client_id` and `your_client_secret` with your Xray Cloud credentials

### Local Testing

To test the server in development mode:

```bash
# Set environment variables
export XRAY_CLIENT_ID="your_client_id"
export XRAY_CLIENT_SECRET="your_client_secret"

# Run the server
npm run dev
```

## Usage Examples

### Test Cases

#### Create a Test Case

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

#### Search Test Cases

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

#### Retrieve Project Test Cases

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

### Test Executions

#### Create a Test Execution

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

#### Retrieve a Test Execution

```json
{
  "testExecutionKey": "ABC-456"
}
```

#### Update Test Run Status

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

#### Search Recent Test Executions

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

## Project Structure

```
xray-mcp/
├── src/
│   ├── index.ts           # Main MCP server
│   └── xray-client.ts     # Client for Xray Cloud APIs
├── dist/                  # Compiled files (generated after build)
├── .env.example           # Template for environment variables
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md
```

## Xray Cloud APIs

This server uses the following Xray Cloud APIs:

- **Authentication**: `POST /api/v1/authenticate` (token valid for 24 hours)
- **GraphQL Endpoint**: `POST /api/v2/graphql`
  - **Test Queries**: `getTests` - Retrieve tests using JQL
  - **Test Mutations**: `createTest`, `deleteTest` - Create/delete tests
  - **Test Execution Queries**: `getTestExecutions` - Retrieve executions using JQL
  - **Test Execution Mutations**: `createTestExecution`, `updateTestRunStatus` - Manage executions and results
  - **Test Plan Queries**: `getTestPlans` - Retrieve test plans using JQL
  - **Test Plan Mutations**: `createTestPlan`, `addTestsToTestPlan`, `removeTestsFromTestPlan` - Manage test plans
  - **Test Set Queries**: `getTestSets` - Retrieve test sets using JQL
  - **Test Set Mutations**: `createTestSet`, `addTestsToTestSet`, `removeTestsFromTestSet` - Manage test sets

For complete API documentation, visit:
- GraphQL API: https://docs.getxray.app/display/XRAYCLOUD/GraphQL+API
- GraphQL Schema: https://us.xray.cloud.getxray.app/doc/graphql/
- REST API: https://docs.getxray.app/display/XRAYCLOUD/REST+API

## Use Cases

### CI/CD Integration
Use this MCP server to:
1. Automatically create test executions in CI/CD pipelines
2. Update test run statuses based on automated test results
3. Track test execution across different environments
4. Generate test execution reports for sprint reviews

### Test Management
Use this MCP server to:
1. Create and organize test cases
2. Search tests using complex JQL queries
3. Manage manual test executions
4. Track test status over time

## License

ISC

## Support

For issues or questions about Xray Cloud APIs, consult the official documentation:
- https://docs.getxray.app/
- https://support.getxray.app/