Appsurify TestMap MCP Server

MCP (Model Context Protocol) server that exposes Appsurify TestMap test-coverage analytics to AI agents: context resolution, ranked coverage gaps, per-element test context, journeys to elements, zero-coverage pages, coverage diffs between runs, and suite efficiency.

Runs as a local stdio CLI (for Claude Code, Claude Desktop, Cursor, etc.) or as a Streamable HTTP service (Docker / remote deployments) from the same codebase.

Tools

| Tool | Backend endpoint | Description | | --- | --- | --- | | testmap_resolve_context | GET /api/v1/agent/context | Resolve project names, page URLs and "the latest run" into the UUIDs the other tools need — call it first | | testmap_list_gaps | GET /api/v1/agent/projects/{id}/gaps | Rank untested / under-tested elements of a run across all pages | | testmap_get_element | GET /api/v1/agent/projects/{id}/elements/{semantic_id} | Everything needed to write a test for one element: locator attributes, metrics, covering tests | | testmap_get_journey | GET /api/v1/agent/projects/{id}/elements/{semantic_id}/journey | Recorded steps an existing test used to reach the element (login, navigation, modals) | | testmap_get_page | GET /api/v1/agent/projects/{id}/pages/{semantic_id} / …/pages?page_href= | Everything about one page: which tests touch it, all its interactive elements (covered included) | | testmap_list_zero_coverage | GET /api/v1/agent/projects/{id}/zero-coverage | Pages with interactive elements no test ever touched | | testmap_get_run_diff | GET /api/v1/agent/projects/{id}/diff | Did anything regress between two runs: verdict, regressions preview, changed pages (paginated) | | testmap_list_diff_entries | GET /api/v1/agent/projects/{id}/diff/entries | The changed elements of that comparison, filtered by type, page or element — confirms a gap closed | | testmap_get_suite_efficiency | GET /api/v1/agent/projects/{id}/efficiency | Test Efficiency Score and per-page coverage rollup — suite health overview |

All tools are read-only (the agent API group contains no non-GET route) and authenticate with a TestMap personal access token (Bearer tmap_...). Responses are capped at 25,000 characters; oversized results are truncated with guidance to narrow the query. In the json format the lists are shortened instead (_truncated names them), so the JSON always parses.

Requirements

• Node.js >= 20
• A TestMap installation and an API key

Quick start (stdio)

Add the server to your MCP client — Claude Code, Claude Desktop, Cursor and similar clients all take the same shape:

{
  "mcpServers": {
    "testmap": {
      "command": "npx",
      "args": ["-y", "@appsurify-testmap/mcp-server"],
      "env": {
        "TESTMAP_URL": "https://example.testmap.cloud",
        "TESTMAP_TOKEN": "<your-api-token>"
      }
    }
  }
}

Per-client setup, demo scenarios and a full walkthrough: USAGE.md.

Streamable HTTP

TESTMAP_URL=... TESTMAP_TOKEN=... npx @appsurify-testmap/mcp-server --transport http --port 3000

The MCP endpoint is POST http://<host>:<port>/mcp; GET /health returns a liveness probe. Stateless mode: no sessions, each request is served by a fresh server instance.

Docker

docker build -t testmap-mcp .
docker run --rm -p 3000:3000 \
  -e TESTMAP_URL=https://example.testmap.cloud \
  -e TESTMAP_TOKEN=<your-api-token> \
  testmap-mcp

The image serves the HTTP transport on 0.0.0.0:3000 and ships a /health Docker health check. Set MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS when the container is reachable from untrusted networks.

Configuration

Configuration is resolved as: CLI flag > environment variable > default.

| Variable | Description | Default | | --- | --- | --- | | TESTMAP_URL | Base URL of the TestMap installation, e.g. https://example.testmap.cloud | — (required for tool calls) | | TESTMAP_TOKEN | TestMap API token | — (required for tool calls) | | TESTMAP_TIMEOUT_MS | Timeout for TestMap API requests | 30000 | | TRANSPORT | stdio or http | stdio | | PORT | HTTP port | 3000 | | HOST | HTTP bind address | 127.0.0.1 | | MCP_ALLOWED_HOSTS | Comma-separated Host allowlist (DNS-rebinding protection) | localhost list when bound to loopback | | MCP_ALLOWED_ORIGINS | Comma-separated Origin allowlist | localhost list when bound to loopback | | LOG_LEVEL | debug, info, warn, error | info |

CLI flags: --transport/-t, --port/-p, --host, --help/-h, --version/-v.

Documentation

• USAGE.md — for building demos: per-client setup and the end-to-end demo scenario (find a gap → write a test → prove it closed).
• DEVELOPMENT.md — for the development team: commands, test tiers, debugging ladder, releasing.
• CHANGELOG.md — release history.

License

MIT © Appsurify, Inc.