Zephyr Review MCP

A read-only Model Context Protocol server that exposes Zephyr Scale Cloud test data as review-oriented tools, so Claude (e.g. in Cowork) can review a story against its actual test coverage.

It answers: does this story have adequate, well-formed tests, and are they passing?

The story text (description, acceptance criteria) is expected to come from Jira (e.g. the Atlassian Rovo MCP). This server supplies the test-coverage half of the picture from Zephyr.

What it does (and does not)

• Read-only. Every tool issues only GET requests. No tool creates, updates, or deletes Zephyr data. "Draft new tests" is a Claude reasoning activity in the conversation, not a write call.
• Assumes your team links test cases to Jira issues in Zephyr (the issuelinks relationship). If a story has no linked tests, coverage reads as empty.

Tools

| Tool | Purpose | |------|---------| | review_story_coverage(issueKey) | Headline tool. Fans out over the linked test cases, their steps, and executions and returns one digested coverage bundle plus a pass/fail/not-run summary. Heavier — use when assessing coverage/quality/pass-fail. | | list_story_test_cases(issueKey) | Lightweight, story-scoped listing: the test cases linked to a story, each with key, name/title, priority, and status. No steps or executions. Use when you just want the list/titles of a story's tests. | | get_test_case(testCaseKey) | Full detail of one test case, including ordered steps (empty expected-result fields kept visible for quality review). | | list_story_executions(issueKey) | Focused pass/fail view: each linked execution's status, cycle, and date. | | list_test_case_executions(testCaseKey) | Full execution history of one test case, newest-first — every run across all cycles plus ad-hoc runs (not just the latest). Each execution carries status, cycle, date, comment, timing (execution/estimated ms), who ran it, environment, custom fields, and linked Jira issues. Test-case-scoped; use list_story_executions for a whole story. | | search_test_cases(projectKey, query) | Project-wide discovery: test cases in a project whose key/name/objective match query (client-side filter — the Zephyr API has no full-text search). Not story-scoped; use only when you don't have an issue key. | | get_project(projectKey) | Project identifier and metadata. |

Configuration

Set via environment variables (see .env.example):

| Variable | Required | Default | Notes | |----------|----------|---------|-------| | ZEPHYR_API_TOKEN | yes | — | JWT bearer token. Generate in Jira → profile → Zephyr API keys. The server fails fast if unset. | | ZEPHYR_REGION | no | us | One of us, eu, au, de. | | ZEPHYR_BASE_URL | no | derived from region | Full base URL override; takes precedence over ZEPHYR_REGION. |

Regional base URLs:

• us → https://api.zephyrscale.smartbear.com/v2 (default)
• eu → https://eu.api.zephyrscale.smartbear.com/v2
• au → https://au.api.zephyrscale.smartbear.com/v2
• de → https://de.api.zephyrscale.smartbear.com/v2

The token maps to a Jira/Zephyr user; the server sees only what that user can see.

Usage

For using the server in an MCP client. Requires Node.js 18+. No clone or build needed — npx fetches and runs the published package.

Add to your MCP client config (Claude Cowork / Claude Desktop):

{
  "mcpServers": {
    "zephyr": {
      "command": "npx",
      "args": ["-y", "@pabloveintimilla/zephyr-mcp"],
      "env": {
        "ZEPHYR_API_TOKEN": "<your-token>",
        "ZEPHYR_REGION": "us"
      }
    }
  }
}

That's it — the client launches the server on demand.

Development

For working on the server itself: clone the repository and install dependencies.

git clone https://github.com/pabloveintimilla/zephyr-mcp.git
cd zephyr-mcp
npm install
npm run build

Run it:

ZEPHYR_API_TOKEN=<your-token> npm start        # from built dist/
ZEPHYR_API_TOKEN=<your-token> npm run dev       # from source, no build step

Run the tests:

npm test

Point an MCP client at your local build (instead of the published package):

{
  "mcpServers": {
    "zephyr": {
      "command": "node",
      "args": ["/absolute/path/to/zephyr-mcp/dist/index.js"],
      "env": {
        "ZEPHYR_API_TOKEN": "<your-token>",
        "ZEPHYR_REGION": "us"
      }
    }
  }
}

Spec-driven development with OpenSpec

This project uses OpenSpec for spec-driven development. Do not start coding a feature directly — capture the intent as a change first, then implement against it. This keeps openspec/specs/ (the source of truth for current behavior) accurate and makes each change reviewable before code is written.

Layout:

• openspec/specs/ — the current, agreed behavior (one folder per capability).
• openspec/changes/ — active changes in progress (proposal, design, specs delta, tasks).
• openspec/changes/archive/ — completed changes, kept for history.

Workflow (run as slash commands in Claude Code, or with the openspec CLI):

1. Explore — /opsx:explore to think through the problem before committing to a design.
2. Propose — /opsx:propose to create a change with proposal.md, design.md, a spec delta under specs/, and tasks.md.
3. Apply — /opsx:apply to implement the tasks, checking them off as you go.
4. Archive — /opsx:archive once the work is done and verified; this syncs the spec delta into openspec/specs/ and moves the change to archive/.

Useful CLI commands:

openspec list                          # active changes
openspec status --change "<name>"      # artifacts + task progress
openspec instructions <artifact> --change "<name>"

Publishing / Release

Publishing to npm is automated by GitHub Actions (.github/workflows/publish.yml). Publishing a GitHub Release builds the package and runs npm publish --provenance --access public.

One-time setup:

1. Create an npm access token (Automation or Granular, with publish rights for @pabloveintimilla/zephyr-mcp).
2. Add it as a repository secret named NPM_TOKEN (Settings → Secrets and variables → Actions).

Each release:

1. Bump the version: npm version <patch|minor|major> (commits and tags).
2. Push with tags: git push --follow-tags.
3. Create a GitHub Release for that tag — the workflow publishes it.

Verify: npx -y @pabloveintimilla/zephyr-mcp on a clean shell resolves the new version.

Reference

The Zephyr Scale Cloud OpenAPI spec is vendored at docs/zephyr.api.yml.