# qa-touch-mcp

MCP (Model Context Protocol) server for the [QA Touch](https://www.qatouch.com) test management API. Lets AI assistants like Claude browse projects, manage test cases, drive test runs, record results, and file defects in your QA Touch domain.

## Requirements

- Node.js 18+
- A QA Touch account on a **Professional or Enterprise** plan (the API is gated to those plans)
- An API token: in QA Touch go to **Profile → Edit Profile → Generate API Key**

## Configuration

The server is configured entirely through environment variables:

| Variable | Required | Description |
|---|---|---|
| `QATOUCH_DOMAIN` | yes | Your QA Touch domain name |
| `QATOUCH_API_TOKEN` | yes | Your API token |
| `QATOUCH_BASE_URL` | no | Override the API base URL (default `https://api.qatouch.com/api/v1`) |

> The token grants access to **all** data in your QA Touch domain. Keep it out of version control.

## Install

### Claude Code

```bash
claude mcp add qa-touch --env QATOUCH_DOMAIN=yourdomain --env QATOUCH_API_TOKEN=yourtoken -- npx qa-touch-mcp
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "qa-touch": {
      "command": "npx",
      "args": ["qa-touch-mcp"],
      "env": {
        "QATOUCH_DOMAIN": "yourdomain",
        "QATOUCH_API_TOKEN": "yourtoken"
      }
    }
  }
}
```

### From source

```bash
npm install
npm run build
QATOUCH_DOMAIN=yourdomain QATOUCH_API_TOKEN=yourtoken node dist/index.js
```

## Tools (32)

**Projects** — `list_projects`, `get_project`, `create_project`

**Test cases & modules** — `list_test_cases` (filter by approval status, module, mode, or requirement), `get_test_case`, `get_test_case_steps`, `list_modules`, `create_module`, `create_test_case` (exploratory / text / BDD / step templates), `update_test_case`, `import_test_cases_csv`

**Releases & plans** — `list_releases`, `create_release`, `list_test_plans`, `list_workspaces`

**Test runs & results** — `list_test_runs`, `get_test_run`, `create_test_run` (all cases / specific cases / by module), `clone_test_run`, `list_test_run_results` (by run, release, history, or case), `get_test_run_metadata`, `update_test_result`, `update_test_result_steps`, `bulk_update_test_results`, `update_test_results_multi`, `add_test_result` (with attachments)

**Defects** — `list_defects`, `create_defect` (with attachments), `get_defect_metadata`

**Requirements** — `list_requirements`, `create_requirement_document`, `create_requirement`

## Behavior notes

- **Rate limiting**: QA Touch allows 50 requests/minute. The server throttles client-side and retries once on `429`, honoring `Retry-After`.
- **Pagination**: list tools accept a `page` parameter. The QA Touch API returns `meta.current_page`/`last_page` as `null` on page 1; the server normalizes this and adds a `has_next` flag.
- **Attachments**: png, pdf, jpg, jpeg, gif, xls, xlsx, doc, docx, csv, log, zip, txt — max 2 MB per file, validated before upload.
- **Batch limits**: multi-case status updates are capped at 20 items per call because the API takes parameters in the URL and rejects over-long URIs.

## Development

```bash
npm run build   # compile TypeScript
npm test        # run unit tests (vitest)
```

API reference notes used for this implementation: [docs/qatouch-api-reference.md](docs/qatouch-api-reference.md).