# mcp-xray-cloud

[![CI](https://github.com/remynln/mcp-xray-cloud/actions/workflows/ci.yml/badge.svg)](https://github.com/remynln/mcp-xray-cloud/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
[![MCP](https://img.shields.io/badge/MCP-compatible-8A2BE2)](https://modelcontextprotocol.io)

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that connects AI assistants to [Xray Cloud](https://www.getxray.app/) for Jira test management.

Manage tests, test plans, executions, and import CI results — all through natural language via Claude or any MCP-compatible client.

## Features

| Category | Tools |
|---|---|
| **Tests** | `list_tests`, `get_test`, `create_test`, `update_test` |
| **Test Plans** | `list_test_plans`, `get_test_plan`, `create_test_plan`, `add_tests_to_test_plan` |
| **Test Executions** | `list_test_executions`, `get_test_execution`, `create_test_execution` |
| **Test Sets** | `list_test_sets`, `get_test_set` |
| **Test Runs** | `update_test_run_status` |
| **Import Results** | Xray JSON, Cucumber, JUnit, TestNG, NUnit, Robot Framework, Behave |
| **Import Features** | Gherkin `.feature` files |
| **Export** | Cucumber feature files |

## Quick Start

```bash
git clone https://github.com/remynln/mcp-xray-cloud.git
cd mcp-xray-cloud
npm install
npm run build
```

## Prerequisites

- Node.js 18+
- An Xray Cloud API key pair ([how to generate](https://docs.getxray.app/display/XRAYCLOUD/Global+Settings%3A+API+Keys))

## Configuration

Set these environment variables:

| Variable | Required | Description |
|---|---|---|
| `XRAY_CLIENT_ID` | Yes | Xray Cloud API client ID |
| `XRAY_CLIENT_SECRET` | Yes | Xray Cloud API client secret |
| `XRAY_BASE_URL` | No | Override API base URL (default: `https://xray.cloud.getxray.app`) |

## Usage with Claude Desktop

Add to your `claude_desktop_config.json`:

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

## Usage with Claude Code

Add to your `.claude.json`:

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

## Tool Reference

### Tests

- **list_tests** — List tests with JQL filtering by project, labels, and component
- **get_test** — Get full test details including steps and preconditions
- **create_test** — Create Manual, Cucumber, or Generic tests
- **update_test** — Update test type (Jira field updates require Jira REST API credentials)

### Test Plans

- **list_test_plans** — List test plans in a project
- **get_test_plan** — Get test plan details with associated tests
- **create_test_plan** — Create a new test plan
- **add_tests_to_test_plan** — Associate tests with a test plan

### Test Executions

- **list_test_executions** — List test executions in a project
- **get_test_execution** — Get execution details with test run statuses
- **create_test_execution** — Create an execution, optionally linked to a test plan

### Test Runs

- **update_test_run_status** — Set a test run to PASSED, FAILED, TODO, EXECUTING, or ABORTED

### Import Results

- **import_execution_results** — Xray JSON format
- **import_cucumber_results** — Cucumber JSON
- **import_junit_results** — JUnit XML
- **import_testng_results** — TestNG XML
- **import_nunit_results** — NUnit XML
- **import_robot_results** — Robot Framework XML
- **import_behave_results** — Behave JSON
- **import_feature_file** — Gherkin `.feature` file

### Export

- **export_cucumber_features** — Export Cucumber feature files from Xray tests

## Project Structure

```
src/
├── index.ts              # Server entry point
├── client.ts             # Xray Cloud API client (auth + GraphQL + REST)
├── helpers.ts            # Shared formatting utilities
└── tools/
    ├── tests.ts          # Test CRUD tools
    ├── test-plans.ts     # Test plan tools
    ├── test-executions.ts# Test execution tools
    ├── test-sets.ts      # Test set tools
    ├── test-runs.ts      # Test run status updates
    ├── imports.ts        # Result import tools (JSON, XML, Gherkin)
    └── exports.ts        # Feature export tools
```

## Contributing

1. Fork the repo
2. Create a feature branch (`git checkout -b feat/my-feature`)
3. Run tests (`npm test`)
4. Commit your changes
5. Open a pull request

## License

[MIT](LICENSE)