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.

Related MCP server: mcp-zephyr-scale

Tools

Configuration

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

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.