Xray云测试管理MCP服务器

@triparc/xray-mcp

A production-grade MCP server for Xray Cloud Test Management — 90 tools covering the complete API surface with token-optimized TOON responses.

Features

• 90 tools across 10 domains — tests, test runs, executions, test plans, test sets, preconditions, folders, evidence, imports, and administration
• Token-Optimized Object Notation (TOON) — default response format reduces LLM token consumption; switch to json or summary per call
• Two transport modes — stdio for local IDE use, Streamable HTTP for server deployments
• Docker and Helm ready — multi-stage Alpine image and production Helm chart included
• Three credential modes — strict (personal), shared-reads (team reads), fully-shared (internal server)
• Four regional endpoints — global, us, eu, au — select via XRAY_REGION
• Per-request credential isolation in HTTP mode — each POST /mcp resolves its own credentials from request headers
• Org-wide connector mode — built-in OAuth sign-in lets Claude.ai, ChatGPT and Copilot users connect with their own Xray API key; nothing stored server-side
• Zero extra dependencies — native Node.js 22 fetch for all HTTP; no graphql-request, no axios

Prerequisites

• Node.js >= 22
• Xray Cloud API credentials — generate at Xray Cloud > API Keys (see Xray authentication docs)

Quickstart

export XRAY_CLIENT_ID=your-client-id
export XRAY_CLIENT_SECRET=your-client-secret
npx -y @triparc/xray-mcp

The server starts in stdio mode, ready for an MCP-capable IDE to connect.

IDE Setup

Claude Desktop

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

stdio (recommended for personal use)

{
  "mcpServers": {
    "xray": {
      "command": "npx",
      "args": ["-y", "@triparc/xray-mcp"],
      "env": {
        "XRAY_CLIENT_ID": "your-client-id",
        "XRAY_CLIENT_SECRET": "your-client-secret"
      },
      "autoApprove": ["xray_get_*", "xray_list_*"]
    }
  }
}

Tip: autoApprove skips the per-tool confirmation dialog for read-only tools. Remove it if you prefer manual approval for every call.

HTTP (connect to a running server)

{
  "mcpServers": {
    "xray": {
      "transport": "http",
      "url": "http://your-server:3000/mcp",
      "headers": {
        "X-Xray-Client-Id": "your-client-id",
        "X-Xray-Client-Secret": "your-client-secret"
      }
    }
  }
}

Cursor

Config file: .cursor/mcp.json in your project root, or ~/.cursor/mcp.json for global config.

stdio

{
  "mcpServers": {
    "xray": {
      "command": "npx",
      "args": ["-y", "@triparc/xray-mcp"],
      "env": {
        "XRAY_CLIENT_ID": "your-client-id",
        "XRAY_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

HTTP

{
  "mcpServers": {
    "xray": {
      "transport": "http",
      "url": "http://your-server:3000/mcp",
      "headers": {
        "X-Xray-Client-Id": "your-client-id",
        "X-Xray-Client-Secret": "your-client-secret"
      }
    }
  }
}

VS Code

Config file: .vscode/mcp.json in your workspace root.

stdio

{
  "servers": {
    "xray": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@triparc/xray-mcp"],
      "env": {
        "XRAY_CLIENT_ID": "your-client-id",
        "XRAY_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

HTTP

{
  "servers": {
    "xray": {
      "type": "http",
      "url": "http://your-server:3000/mcp",
      "headers": {
        "X-Xray-Client-Id": "your-client-id",
        "X-Xray-Client-Secret": "your-client-secret"
      }
    }
  }
}

Note on config key differences: Claude Desktop and Cursor use "mcpServers" with "transport": "http". VS Code uses "servers" with "type": "http". These differences are enforced by each IDE's MCP client implementation.

Docker Deployment

The Docker image runs in HTTP mode only (TRANSPORT=http is set in the image). Pass credentials via environment variables:

docker run -d \
  -e XRAY_CLIENT_ID=your-client-id \
  -e XRAY_CLIENT_SECRET=your-client-secret \
  -e XRAY_CREDENTIAL_MODE=fully-shared \
  -p 3000:3000 \
  ghcr.io/traveledge/xray-mcp:latest

Health and readiness endpoints:

Docker Compose

services:
  xray-mcp:
    image: ghcr.io/traveledge/xray-mcp:latest
    ports:
      - "3000:3000"
    environment:
      XRAY_CLIENT_ID: your-client-id
      XRAY_CLIENT_SECRET: your-client-secret
      XRAY_CREDENTIAL_MODE: fully-shared
    restart: unless-stopped

Building from source

docker build -t xray-mcp:local .

# Run local build
docker run -d \
  -e XRAY_CLIENT_ID=your-client-id \
  -e XRAY_CLIENT_SECRET=your-client-secret \
  -e XRAY_CREDENTIAL_MODE=fully-shared \
  -p 3000:3000 \
  xray-mcp:local

The Dockerfile uses a multi-stage build: node:24-alpine builder stage compiles TypeScript; the runtime stage copies only dist/ and production node_modules for a minimal image (~50MB). Runs as non-root node user with tini as PID 1 for proper signal handling.

Kubernetes / Helm Deployment

helm install xray-mcp ./helm \
  --set credentials.clientId=your-client-id \
  --set credentials.clientSecret=your-client-secret \
  --set xray.credentialMode=shared-reads

Key Helm values

Using an external secret (CSI Secret Store / External Secrets Operator)

Set existingSecret to the name of your pre-existing Secret. The chart will mount it rather than creating its own:

helm install xray-mcp ./helm \
  --set existingSecret=my-xray-credentials \
  --set xray.credentialMode=shared-reads

The Secret must contain keys XRAY_CLIENT_ID and XRAY_CLIENT_SECRET, plus OAUTH_ENCRYPTION_KEY when oauth.enabled=true.

Production deployment with Ingress and TLS

helm install xray-mcp ./helm \
  --set existingSecret=my-xray-credentials \
  --set xray.credentialMode=shared-reads \
  --set xray.region=us \
  --set ingress.enabled=true \
  --set ingress.className=nginx \
  --set ingress.hosts[0].host=xray-mcp.yourcompany.com \
  --set ingress.hosts[0].paths[0].path=/ \
  --set ingress.hosts[0].paths[0].pathType=Prefix \
  --set ingress.tls[0].secretName=xray-mcp-tls \
  --set ingress.tls[0].hosts[0]=xray-mcp.yourcompany.com \
  --set autoscaling.enabled=true \
  --set autoscaling.maxReplicas=3

Connecting MCP clients to Helm deployment

Once deployed, configure your MCP client to use the HTTP transport pointing to the Ingress URL:

{
  "mcpServers": {
    "xray": {
      "transport": "http",
      "url": "https://xray-mcp.yourcompany.com/mcp",
      "headers": {
        "X-Xray-Client-Id": "your-client-id",
        "X-Xray-Client-Secret": "your-client-secret"
      },
      "autoApprove": ["xray_get_*", "xray_list_*"]
    }
  }
}

In fully-shared mode, the headers are optional — the server uses its own credentials for all operations.

Connector mode (Claude.ai, ChatGPT, Copilot)

Hosted assistants add MCP servers as connectors and cannot send custom headers — they only speak OAuth. Connector mode makes the server its own OAuth 2.1 provider: the sign-in page asks each user for their personal Xray API key pair, validates it against Xray, and issues a token. Every Xray action is then attributed to that user.

Nothing is stored server-side: tokens are AES-256-GCM sealed blobs containing the user's credentials, so any replica can serve any token and restarts lose nothing. Dynamic client registration and PKCE are supported, so no per-client setup is needed.

Enable it with two settings:

helm upgrade --install xray-mcp ./helm \
  --set existingSecret=my-xray-credentials \
  --set oauth.enabled=true \
  --set oauth.publicUrl=https://xray-mcp.yourcompany.com

Then, in Claude (Owner/Admin → Settings → Connectors → Add custom connector), enter https://xray-mcp.yourcompany.com/mcp and enable it for the organization. Each user clicks Connect, enters their Xray Client ID/Secret once (a Jira admin generates these under Jira Settings → Apps → Xray → API Keys), and is done.

Header-based clients (Claude Code, Cursor, VS Code) keep working unchanged when connector mode is on.

Revocation: delete the user's Xray API key (their token stops working immediately) or rotate OAUTH_ENCRYPTION_KEY (everyone signs in again).

Environment Variables

Server configuration

HTTP request headers (HTTP mode only)

In strict and shared-reads modes, HTTP callers provide their Xray credentials per request:

* One of: the header pair, a bearer token, or — in fully-shared mode only — nothing (the server's own XRAY_CLIENT_ID / XRAY_CLIENT_SECRET are used). Requests with none of these get 401.

Credential Modes

stdio mode: credentials come from XRAY_CLIENT_ID / XRAY_CLIENT_SECRET environment variables.

HTTP mode: credentials come from X-Xray-Client-Id / X-Xray-Client-Secret request headers (unless fully-shared, where server env vars are used).

Tools

90 tools across 10 domains. All tools accept an optional format parameter:

• format: "toon" (default) — Token-Optimized Object Notation, minimal token usage
• format: "json" — raw JSON response from Xray API
• format: "summary" — single-line human-readable summary

See TOOLS.md for the complete tool reference with parameters, examples, and response formats.

TOON Format

Token-Optimized Object Notation (TOON) is the default response format. It strips verbose JSON keys, compresses nested structures, and uses concise status icons — reducing token consumption by 40-70% compared to raw Xray API responses.

Example: a test execution with 50 runs returns ~800 tokens in TOON vs ~3,500 tokens in raw JSON.

Switching formats per call:

Use the listTestRuns tool with format: "json" to get full JSON output

Use the getTestDetails tool with format: "summary" for a one-line summary

TOON is opinionated for LLM consumption. If you need to pass Xray responses to other systems, use format: "json" for spec-compliant output.

Development

Local setup

# Requires Node.js >= 22 and pnpm
npm install -g pnpm
pnpm install
pnpm build
pnpm test

Run in stdio mode

XRAY_CLIENT_ID=your-id XRAY_CLIENT_SECRET=your-secret node dist/index.js

Run in HTTP mode

TRANSPORT=http XRAY_CLIENT_ID=your-id XRAY_CLIENT_SECRET=your-secret node dist/index.js

Available scripts

Schema Verification

The project includes an introspection script that validates all GraphQL queries against the live Xray Cloud API schema. This catches field renames, removed arguments, and type mismatches before they reach production.

# Requires XRAY_CLIENT_ID and XRAY_CLIENT_SECRET
export XRAY_CLIENT_ID=your-id
export XRAY_CLIENT_SECRET=your-secret

# Introspect schema and save to schema/ directory
pnpm introspect

# Audit all tools against the live schema
pnpm introspect:audit

The audit checks every query and mutation for:

• Root field existence (e.g., getTest exists on Query type)
• Argument names and types match the schema
• Deprecated fields

Results are written to schema/audit-report.md. The schema/ directory is gitignored — each developer runs against their own Xray instance.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for development workflow, commit conventions, and pull request guidelines before opening an issue or PR.

License

Apache License 2.0