@testmaze/mcp

Thin stdio wrapper for the Test Maze MCP server — spec-driven delivery for AI coding agents. Test Maze holds your user stories and acceptance tests (spec first), keeps the agent inside them with hooks and commit traces (every change traced), has a separate verifier grade the work with fixed rules (verified independently) and gates the release on results (shipped on evidence). This package connects Claude Code, Cursor, Cline, and any other MCP-compatible coding agent to a hosted Test Maze instance — init once, then a one-line claude mcp add with no secret in it.

Status: v0.5.0 (MIT). 0.5.0 pins a repo to its workspace: the committed MCP config carries TESTMAZE_SPACE_ID (the settings page puts it there), the proxy sends it on every call and the server refuses a token from any other workspace — so two repos cannot write into one workspace and a stale token cannot drag a repo into the wrong one; init and whoami check the same thing and say which is which. The proxy also reports the clone's remote.origin.url (the server refuses a call from a repository that is not the workspace's product) and its git branch (Test Maze accepts product KPIs and metric values only from the workspace's default branch). The SessionStart hook also prints the workspace's agent guidance (standing instructions an architect or product owner set in Settings → Workspace → Agent guidance), with or without spec enforcement; the same text reaches every client in the server's initialize instructions, and per-prompt guidance is appended to prompts/get results. 0.4.0 has init also install the spec-based development hooks (Claude Code PreToolUse / SessionStart / SubagentStart, git commit-msg / post-commit; --no-hooks skips them) and adds the spec CLI (status, start, finish, trace, check-range for CI). Every hook is a no-op until the workspace enables Settings → Workspace → General → Spec-based development. 0.3.0 has init also install a verifier agent: when a feature is ready to grade, your agent hands it to that agent, which runs the acceptance tests in its own context without editing tools, records results as recordedBy: "verifier" and returns only the verdict, so the agent that wrote the code does not grade it. .claude/agents/testmaze-verifier.md covers Claude Code, Cursor (readonly: true) and VS Code Copilot Chat; Codex (.codex/agents/*.toml + an AGENTS.md block), Copilot CLI (.github/agents/*.agent.md) and Gemini CLI (.gemini/agents/*.md) get their own file when the project uses them. Commit the files; --agents/--no-agents choose, and a copy you have edited (marker line removed) is never overwritten. Per-tool details: usage.md. 0.2.2 stamps each run with an id (X-TestMaze-Run) and names the coding agent it bridges (X-TestMaze-Agent), so a workspace's Agent Sessions page and the server logs can show exactly which agent process made which call — quote the run_… id from the wrapper's first stderr line when reporting a problem. 0.2 adds init / whoami / token, .env.testmaze credential resolution so no token ever lands in a committed MCP config (a project's file outranks a stray env var), and live pickup of a rewritten .env.testmaze — no reconnect after re-running init. Upgrading from 0.1.x: npx can keep serving a cached 0.1.x, so refresh it once with npx -y @testmaze/mcp@latest --version (should print 0.2.1 or later). Then remove TESTMAZE_MCP_TOKEN from your MCP client config, run npx -y @testmaze/mcp@latest init <token> in the project, and re-register without --env (e.g. claude mcp remove testmaze then the step 2 command below). As a 0.x release the API may still shift.

What it does

1. Resolves your space-scoped MCP token (tmt_*) and the Test Maze backend URL — from CLI flags, a gitignored .env.testmaze, env vars, or .env (in that order).
2. Opens an MCP-over-HTTP connection to ${url}/api/v1/mcp with the token as a Bearer credential.
3. Pipes stdio frames between your coding agent and the remote MCP server.

init (one-time, per clone) verifies the token against ${url}/api/v1/mcp/tokens/exchange, prints the workspace and user it maps to, and writes .env.testmaze for you.

The hosted verifier currently exposes (the live list is always tools/list, or Settings → MCP Tools in the app):

• 70 tools across 17 families — test management (cases, plans, runs, releases with their ship gate, defects, features and user stories with Definition of Ready / Done, metrics, media), the marquee pdlc.verify (deterministic verdict envelope), coverage and regression baselines, spec-based development (spec.status / start_work / finish_work / trace / check_commit), project.whoami (which workspace/user this connection is), code quality (quality.smell_check, architecture.advise, kb.search, kb.get) and exploratory testing with your agent's own browser (exploration.start / observe / finish / to_cases).
• 14 resources under the testmaze:// URI scheme — product, features, cases, runs, releases, metrics, engineering investment, media, exploration sessions, and a design-pattern / code-smell / refactoring knowledge base.
• 12 prompts — the product loop (product-strategy: strategy docs in the repo, assessment in Test Maze), the PDLC loop (product-init, feature-spec, ac-to-testcase, find-coverage-gaps, verify-feature), spec-based development (spec-driven-change, story-plan), reviews (code-smell-review, architecture-review) and exploration (explore-feature, exploration-to-cases).

In Claude Code, with the server registered as tm, prompts are slash commands (/mcp__tm__explore-feature), resources are @tm:testmaze://… mentions, and tools show as mcp__tm__<tool>.

What this lets your agent do: docs/functionality.md.

Install

Requires Node.js 20+ (for npx). Two steps, run from your project root — the editor launches the server from there and it reads .env.testmaze from that directory. The token never goes into the editor config.

# 0. No token yet? Prints the exact steps (sign in → workspace → Settings → MCP Tokens)
npx -y @testmaze/mcp token

# 1. Verify + store the token (writes .env.testmaze, adds it to .gitignore)
npx -y @testmaze/mcp init tmt_xxx

# 2. Register the server — no secret in .mcp.json, only the workspace pin; commit it freely
claude mcp add tm --scope project --env TESTMAZE_SPACE_ID=<workspace-id> -- npx -y @testmaze/mcp

init prints the exact step-2 command with your workspace id filled in; Settings → MCP Tokens shows it too.

Check it: npx -y @testmaze/mcp whoami prints the workspace and user this folder is connected to. In Claude Code, /mcp should show tm as connected.

Cursor / Cline / Gemini CLI (.cursor/mcp.json, Cline MCP settings, .gemini/settings.json):

{ "mcpServers": { "tm": { "command": "npx", "args": ["-y", "@testmaze/mcp"], "env": { "TESTMAZE_SPACE_ID": "<workspace-id>" } } } }

Codex CLI (.codex/config.toml):

[mcp_servers.tm]
command = "npx"
args = ["-y", "@testmaze/mcp"]

[mcp_servers.tm.env]
TESTMAZE_SPACE_ID = "<workspace-id>"

The only thing in the env block is the workspace pin — init already stored the token. The pin is not a secret: it says which workspace this repository is, and the server refuses any token from another workspace. Self-hosted Test Maze? Add --url https://your-host to init (it is stored alongside the token). Every repo gets its own .env.testmaze, so different projects can point at different workspaces from the same machine.

CLI

testmaze-mcp init <tmt_xxx> [--url https://testmaze.com] [--agents LIST | --no-agents] [--no-hooks]
testmaze-mcp [--token tmt_xxx] [--url https://testmaze.com]
testmaze-mcp spec <status | start <id> [--summary "…"] | finish | trace <id|sha> | check-range <a>..<b>>
testmaze-mcp docs manifest [--dir docs/product] [--root <repo>]

Commands:
  token          Step-by-step guide to creating a token in the Test Maze web app.
  init <token>   Verify the token, print the workspace + user it maps to,
                 write .env.testmaze (mode 600), add it to .gitignore if present.
                 Installs the verifier agent and the spec-enforcement hooks
                 (.claude/settings.json PreToolUse + SessionStart + SubagentStart, git
                 commit-msg + post-commit). The hooks do nothing unless the
                 workspace enables Settings → General → Spec-based development.
  spec           Spec-based development: show the policy and your active work
                 item, declare / close the story or test case you work on,
                 look up traceability, and in CI fail on untraceable commits:
                   npx -y @testmaze/mcp spec check-range origin/main..HEAD
  hook           Entry points for the installed hooks (not for direct use).
  docs           Provenance for strategy documents. `docs manifest` prints a JSON
                 manifest of every document under --dir (default docs/product):
                 path, MD5 of the file's content, bytes, and one manifestMd5 over
                 all of them. Agents run it after writing strategy docs and cite
                 files by path + md5 in product.assess; product.status compares
                 it with the last assessment to say whether it is stale. Local
                 only; nothing is sent anywhere.
  whoami         Resolve credentials for the current directory the way the proxy
                 does and print the workspace, user, token and where it came from.
  (none)         Run the stdio↔HTTP proxy (what your MCP client launches).

Flags:
  --token, -t    Per-space MCP token. Overrides every other source.
  --url, -u      Backend URL. Default: https://testmaze.com.
  --version, -v  Print version and exit.
  --help, -h     Print this help and exit.

Credential resolution (first hit wins):
  1. --token / --url     2. .env.testmaze (what init writes; cwd or any parent)
  3. TESTMAZE_MCP_TOKEN / TESTMAZE_MCP_URL env vars
  4. .env (cwd or any parent)
A project's .env.testmaze outranks an env var so `init` always takes effect per repo.

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.

Documentation

Both ship inside the package (node_modules/@testmaze/mcp/docs/):

• docs/usage.md — setup for Claude Code / Cursor / Cline / Gemini CLI / Codex, tokens, init / whoami, credential resolution, exploring with your own browser, self-hosting, troubleshooting.
• 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.