{"id":43315896,"url":"https://github.com/g4-api/g4-xray-mcp","last_synced_at":"2026-02-01T22:01:01.107Z","repository":{"id":335350507,"uuid":"1106893840","full_name":"g4-api/g4-xray-mcp","owner":"g4-api","description":"MCP for XRay Test Management cloud/on-prem","archived":false,"fork":false,"pushed_at":"2026-01-29T19:29:19.000Z","size":269,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-30T07:54:58.730Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/g4-api.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-30T06:46:30.000Z","updated_at":"2026-01-29T19:28:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/g4-api/g4-xray-mcp","commit_stats":null,"previous_names":["g4-api/g4-xray-mcp"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/g4-api/g4-xray-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g4-api%2Fg4-xray-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g4-api%2Fg4-xray-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g4-api%2Fg4-xray-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g4-api%2Fg4-xray-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/g4-api","download_url":"https://codeload.github.com/g4-api/g4-xray-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g4-api%2Fg4-xray-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28992629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T20:57:35.821Z","status":"ssl_error","status_checked_at":"2026-02-01T20:57:29.580Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-01T22:01:00.159Z","updated_at":"2026-02-01T22:01:01.092Z","avatar_url":"https://github.com/g4-api.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# G4 Jira \u0026 Xray MCP Service\n\n![.NET](https://img.shields.io/badge/.NET-10-512BD4?logo=.net\u0026logoColor=white)  \n[![Build, Test \u0026 Release G4� Jira-XRay MCP](https://github.com/g4-api/g4-xray-mcp/actions/workflows/release-pipline.yml/badge.svg)](https://github.com/g4-api/g4-xray-mcp/actions/workflows/release-pipline.yml)\n\nA cross-platform **ASP.NET Core MCP service** that integrates with **Jira** (Cloud \u0026 On-Prem) and **Xray** (Cloud \u0026 On-Prem via Raven API).  \nIt exposes an MCP-compatible **HTTP endpoint** for test-management automation.\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Supported Platforms](#supported-platforms)\n- [Prerequisites](#prerequisites)\n  - [.NET 10 (LTS)](#net-10-lts)\n  - [Docker](#docker)\n- [Install](#install)\n  - [Option A: Run Native (Recommended)](#option-a-run-native-recommended)\n  - [Option B: Run with Docker](#option-b-run-with-docker)\n- [Configuration](#configuration)\n  - [Environment Variables](#environment-variables)\n  - [MCP Client Configuration](#mcp-client-configuration)\n- [Available Tools](#available-tools)\n- [Security Notes](#security-notes)\n- [Troubleshooting](#troubleshooting)\n\n---\n\n## Overview\n\nThis service provides MCP tools for working with:\n- **Jira Cloud / Jira On-Prem**\n- **Xray Cloud**\n- **Xray On-Prem (via Raven API)**\n\nDefault MCP endpoint:\n- `http://localhost:9988/api/v4/mcp`\n\n---\n\n## Supported Platforms\n\nRun natively on:\n- Windows\n- macOS\n- Linux\n\nOr run as a container using Docker.\n\n---\n\n## Prerequisites\n\n### .NET 10 (LTS)\n\nInstall .NET using the official Microsoft docs:\n- Windows: see Microsoft Learn �Install .NET on Windows�. :contentReference[oaicite:0]{index=0}\n- macOS: see Microsoft Learn �Install .NET on macOS�. :contentReference[oaicite:1]{index=1}\n- Linux: see Microsoft Learn �Install .NET on Linux�. :contentReference[oaicite:2]{index=2}\n\nYou can also use the official .NET download page:\n- �Download .NET� landing page. :contentReference[oaicite:3]{index=3}\n- �Download .NET 10.0� page. :contentReference[oaicite:4]{index=4}\n\n### Docker\n\nOfficial Docker installation guides:\n- Windows (Docker Desktop): :contentReference[oaicite:5]{index=5}\n- macOS (Docker Desktop): :contentReference[oaicite:6]{index=6}\n- Linux (Docker Desktop): :contentReference[oaicite:7]{index=7}\n- Docker Engine install overview (Linux-focused): :contentReference[oaicite:8]{index=8}\n\n---\n\n## Install\n\n### Option A: Run Native (Recommended)\n\n1. Download the **latest production release** from your GitHub Releases page (choose the ZIP for your OS/architecture):\n   - Example:\n     ```text\n     https://github.com/\u003corg\u003e/\u003crepo\u003e/releases/latest\n     ```\n\n2. Unzip the release package to a folder (example):\n   - Windows: `C:\\apps\\g4-jira-xray-mcp\\`\n   - Linux/macOS: `/opt/g4-jira-xray-mcp/`\n\n3. Configure environment variables (see [Environment Variables](#environment-variables)).\n\n4. Run the service from the unzipped folder:\n   ```bash\n   dotnet Mcp.Xray.dll\n   ```\n\n\u003e Tip: If your release contains an `appsettings.json` (or similar), keep the README aligned with the release package behavior.\n\u003e This README assumes the primary entrypoint is **`dotnet Mcp.Xray.dll`**.\n\n---\n\n### Option B: Run with Docker\n\nIf you publish a Docker image, run it like this (example):\n\n```bash\ndocker run -d --name g4-jira-xray-mcp \\\n  -p 9988:9988 \\\n  -e JIRA_API_KEY=\"...\" \\\n  -e JIRA_BASE_URL=\"...\" \\\n  -e JIRA_API_VERSION=\"...\" \\\n  -e JIRA_IS_CLOUD=\"true\" \\\n  -e XRAY_CLOUD_BASE_URL=\"https://xray.cloud.getxray.app\" \\\n  \u003cyour-image\u003e:\u003ctag\u003e\n```\n\n---\n\n## Configuration\n\n### Environment Variables\n\n| Name                         | Description                                                                                                 |\n| ---------------------------- | ----------------------------------------------------------------------------------------------------------- |\n| `JIRA_API_KEY`               | Jira API key / token used for authentication.                                                               |\n| `JIRA_API_VERSION`           | Jira REST API version to target (depends on your Jira deployment).                                          |\n| `JIRA_BASE_URL`              | Base URL of the Jira instance (Cloud or On-Prem).                                                           |\n| `JIRA_BUCKET_SIZE`           | Batch size for list/bulk operations.                                                                        |\n| `JIRA_DELAY_MILLISECONDS`    | Delay (ms) between retry attempts.                                                                          |\n| `JIRA_IS_CLOUD`              | Switch implementation: `true` = Cloud, `false` = On-Prem.                                                   |\n| `JIRA_MAX_ATTEMPTS`          | Max retry attempts before failing.                                                                          |\n| `JIRA_RESOLVE_CUSTOM_FIELDS` | If enabled, resolves Jira custom fields via Jira API; otherwise uses provided names/keys without resolving. |\n| `JIRA_USERNAME`              | Jira username (commonly required for some On-Prem auth flows).                                              |\n| `XRAY_CLOUD_BASE_URL`        | Xray Cloud base URL (default: `https://xray.cloud.getxray.app`).                                            |\n\n#### Example (Linux/macOS)\n\n```bash\nexport JIRA_BASE_URL=\"https://your-jira\"\nexport JIRA_API_VERSION=\"3\"\nexport JIRA_IS_CLOUD=\"true\"\nexport JIRA_USERNAME=\"your-user@company.com\"\nexport JIRA_API_KEY=\"***\"\nexport XRAY_CLOUD_BASE_URL=\"https://xray.cloud.getxray.app\"\n\ndotnet Mcp.Xray.dll\n```\n\n#### Example (Windows PowerShell)\n\n```powershell\n$env:JIRA_BASE_URL = \"https://your-jira\"\n$env:JIRA_API_VERSION = \"3\"\n$env:JIRA_IS_CLOUD = \"true\"\n$env:JIRA_USERNAME = \"your-user@company.com\"\n$env:JIRA_API_KEY = \"***\"\n$env:XRAY_CLOUD_BASE_URL = \"https://xray.cloud.getxray.app\"\n\ndotnet .\\Mcp.Xray.dll\n```\n\n---\n\n### MCP Client Configuration\n\nAdd this to your `mcp.json`:\n\n```json\n{\n    \"servers\": {\n        \"g4-jira-xray\": {\n            \"type\": \"http\",\n            \"url\": \"http://localhost:9988/api/v4/mcp\"\n        }\n    },\n    \"inputs\": []\n}\n```\n\n---\n\n## Available Tools\n\nThese are the currently exposed MCP tools:\n\n| Tool Name                             | Purpose                                                   | When to Use                                                        | Key Capabilities                                                                                                                                                                                                                                                                |\n| ------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **`add_xray_tests_to_folder`**        | Add multiple tests to a Test Repository folder using JQL. | Use to bulk-organize tests into repository folders.                | Executes a JQL query to select tests and adds them to the specified repository folder. Returns added and skipped test keys, the folder ID, resolved path, and a direct link (if available).                                                                                     |\n| **`add_xray_tests_to_plan`**          | Add tests to an existing Xray Test Plan using JQL.        | Use when organizing or bulk-assigning tests to a plan.             | Resolves test cases using a JQL query and adds them to the specified Test Plan. Returns confirmation of the operation.                                                                                                                                                          |\n| **`get_xray_test`**                   | Retrieve an existing Xray test case.                      | Use when you need to inspect or reason about an existing test.     | Fetches the full Xray test model including scenario, specifications, setup/teardown, ordered steps with expected results, priority, severity, tolerance, categories, custom fields, and metadata. Returns the complete test object.                                             |\n| **`get_xray_tool_metadata`**          | Retrieve MCP metadata for an Xray tool.                   | Use for introspection, validation, or agent planning.              | Returns the full MCP tool definition (name, description, input schema, and output schema) for a given tool. Useful for dynamic agents and pre-flight validation.                                                                                                                |\n| **`new_xray_test`**                   | Create a new Xray test case.                              | Use when authoring new manual or automated test cases.             | Creates a full Xray test with scenario/title, specifications, setup and teardown steps, ordered test steps with expected results, priority, severity, tolerance, categories (tags), and custom fields. Returns the created test key, internal ID, and a direct Jira/Xray link.  |\n| **`new_xray_test_plan`**              | Create a new Xray Test Plan.                              | Use when defining a new test execution scope or campaign.          | Creates a Test Plan with summary, description, optional JQL-based test selection, optional context key-value data, and custom fields. Returns the created plan key, internal ID, and a direct Jira/Xray link.                                                                   |\n| **`new_xray_test_repository_folder`** | Create a folder in the Xray Test Repository.              | Use when structuring or extending repository hierarchy.            | Creates a new repository folder under an optional parent path (or root). Supports hierarchical organization. Returns the folder ID, resolved path, and a direct link (if available).                                                                                            |\n| **`resolve_xray_folder_path`**        | Resolve a repository folder path to its internal ID.      | Use when another operation requires a folder ID instead of a path. | Converts a human-readable hierarchical path into the internal Xray folder identifier. Returns the normalized path and ID.                                                                                                                                                       |\n| **`update_xray_test`**                | Update an existing Xray test case.                        | Use when test logic, steps, or metadata need to change.            | Supports partial updates. You can update scenario/title, specifications, setup, teardown, steps, categories, priority, severity, tolerance, and custom fields. Returns the updated test key, internal ID, and link.                                                             |\n\n---\n\n## Security Notes\n\n* Do not commit secrets (`JIRA_API_KEY`) to source control.\n* Prefer secret managers (GitHub Actions secrets, Azure Key Vault, etc.).\n* Restrict network access to the MCP endpoint if used outside localhost.\n\n---\n\n## Troubleshooting\n\n**`dotnet: command not found`**\n\n* Install .NET 10 using the platform instructions above. ([Microsoft Learn][1])\n\n**Port already in use / cannot connect**\n\n* Ensure nothing else is listening on `9988`.\n* Verify the MCP endpoint is reachable:\n\n  * `http://localhost:9988/api/v4/mcp`\n\n**Auth failures**\n\n* Re-check `JIRA_IS_CLOUD` matches your deployment type.\n* Validate `JIRA_BASE_URL`, `JIRA_USERNAME`, and `JIRA_API_KEY`.\n\n[1]: https://learn.microsoft.com/en-us/dotnet/core/install/?utm_source=chatgpt.com \"Install .NET on Windows, Linux, and macOS\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fg4-api%2Fg4-xray-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fg4-api%2Fg4-xray-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fg4-api%2Fg4-xray-mcp/lists"}