# Zephyr Review MCP

A **read-only** [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
[Zephyr Scale Cloud](https://smartbear.com/test-management/zephyr-scale/) 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):

```json
{
  "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.

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

Run it:

```bash
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:

```bash
npm test
```

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

```json
{
  "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](https://github.com/Fission-AI/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:

```bash
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`](.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`](docs/zephyr.api.yml).