# @testmaze/mcp

Thin stdio wrapper for the **Test Maze MCP verifier**. Connects Claude Code, Cursor, Cline, and any other MCP-compatible coding agent to a hosted Test Maze instance with a one-line `claude mcp add`.

> **Status:** `v0.1.0` — first public release on npm under the `@testmaze` scope (MIT). The stdio↔HTTP proxy is implemented and field-tested against the live HTTP transport. As an early **0.x** release the API may still shift.

## What it does

1. Reads your space-scoped MCP token (`tmt_*`) and the Test Maze backend URL from env vars or CLI flags.
2. Exchanges the token against `${url}/api/v1/mcp/tokens/exchange` → resolves your `spaceId + userId`.
3. Opens an MCP-over-HTTP connection to `${url}/api/v1/mcp`.
4. Pipes stdio frames between your coding agent and the remote MCP server.

The verifier you connect to has:

- **43 tools** across 13 families (pdlc, testcase, testrun, product, feature, testplan, release, product-metrics, media, workflow, coverage, regression, activity) — including the marquee `pdlc.verify` (deterministic verdict envelope).
- **11 resources** under the `testmaze://` URI scheme (product, feature, case, testrun, release, …).
- **4 prompts** that drive the PDLC loop client-side (`product-init`, `feature-spec`, `ac-to-testcase`, `find-coverage-gaps`).

What this lets your agent do: [docs/functionality.md](./docs/functionality.md).

## Install

```sh
claude mcp add testmaze \
  --env TESTMAZE_MCP_TOKEN=tmt_xxx \
  --env TESTMAZE_MCP_URL=https://testmaze.com \
  -- npx -y @testmaze/mcp
```

The same shape works with Cursor / Cline / any MCP client — substitute the client's MCP-add equivalent.

## CLI

```
testmaze-mcp [--token tmt_xxx] [--url https://testmaze.com]

Flags:
  --token, -t    Per-space MCP token. Env fallback: TESTMAZE_MCP_TOKEN.
  --url, -u      Backend URL. Env fallback: TESTMAZE_MCP_URL. Default: https://testmaze.com.
  --version, -v  Print version and exit.
  --help, -h     Print this help and exit.
```

## Versioning

The wrapper's major version tracks the MCP protocol version it supports, **not** the Test Maze app version. A wrapper at `1.x` will work against any backend that speaks MCP-protocol-1.x, regardless of the backend's Test Maze version.

## License

MIT — see [LICENSE](./LICENSE).

## Documentation

- [docs/usage.md](./docs/usage.md) — setup for Claude Code / Cursor / Cline, tokens, CLI, self-hosting, troubleshooting.
- [docs/functionality.md](./docs/functionality.md) — what the verifier lets your agent do: the verify loop, capabilities, resources, and prompts.

For the product and to issue a token, see [testmaze.com](https://testmaze.com).