/testdriver-claude-mcp-plugin

name: testdriver:claude-mcp-plugin
description: claude-mcp-plugin

<!-- Generated from claude-mcp-plugin.mdx. DO NOT EDIT. -->

TestDriver ships as a native [Claude Code plugin](https://docs.claude.com/en/docs/claude-code/plugins) that bundles the **TestDriver MCP server**, the **`testdriver` expert sub-agent**, and all **TestDriver skills**. You get everything you need to drive TestDriver from Claude Code with a single install.

> The plugin lives inside the `testdriverai` npm package at `ai/.claude-plugin/plugin.json`, and the marketplace entry lives at `.claude-plugin/marketplace.json` in this repo.

1. Get a TestDriver API key

• Visit your team page (e.g. `https://console.testdriver.ai/settings`)
• Create or copy a **Team API Key** (or User API Key)
• Export it in your shell so Claude Code can pass it to the MCP server:

  export TD_API_KEY="your_api_key_here"

2. Install the plugin in Claude Code

From inside Claude Code, add this repo as a plugin marketplace and install the `testdriver` plugin:

/plugin marketplace add testdriverai/testdriverai
/plugin install testdriver@testdriver

That registers three things:

• **`testdriver` MCP server** — spawned via `npx -p testdriverai testdriverai-mcp`, with `TD_API_KEY` forwarded from your environment.
• **`testdriver` sub-agent** — the TestDriver expert agent from `ai/agents/testdriver.md`. Invoke it with `@testdriver ...`.
• **TestDriver skills** — every `ai/skills/testdriver-*` skill, auto-loaded by Claude Code.

3. Write tests with the agent

In a Claude Code session, delegate to the agent:

@testdriver Write a test that signs into https://example.com and adds an item to the cart.

The agent will use the TestDriver MCP tools (`session_start`, `find`, `click`, `type`, `assert`, …) to interactively build a Vitest test, append generated code to your test file after every action, and run it with `vitest run` until it passes.

For the full agent guide, see the [`testdriver` agent definition](https://github.com/testdriverai/testdriverai/blob/main/ai/agents/testdriver.md) and the [MCP workflow skill](https://github.com/testdriverai/testdriverai/blob/main/ai/skills/testdriver-mcp-workflow/SKILL.md).

Manual MCP configuration (no plugin)

If you prefer not to use the plugin, you can register the MCP server manually in any MCP-compatible client (Claude Desktop, Cursor, VS Code, …):

{
  "mcpServers": {
    "testdriver": {
      "command": "npx",
      "args": ["-p", "testdriverai", "testdriverai-mcp"],
      "env": {
        "TD_API_KEY": "${TD_API_KEY}"
      }
    }
  }
}

This is the same config the plugin wires up for you — the plugin just bundles it alongside the agent and skills.

---

Observing test runs via HTTP MCP

TestDriver also exposes **test results and analytics** over an HTTP MCP endpoint, so Claude Code (or any MCP-compatible client) can inspect your test runs, failures, and filters without provisioning a sandbox.

HTTP MCP endpoint contract

The HTTP endpoint lives at:

POST /api/v1/mcp

It expects the TestDriver API key in the `X-Api-Key` header (or `Authorization: Bearer <key>`).

Common request shapes:

• **List tools**

{
  "kind": "list_tools"
}

• **Call a tool**

{
  "kind": "call_tool",
  "tool": "list_test_runs",
  "arguments": {
    "status": "failed",
    "page": 1,
    "limit": 20
  }
}

Responses from tool calls follow the MCP content convention:

{
  "content": [
    {
      "type": "json",
      "json": {
        "testRuns": [],
        "totalCount": 0,
        "hasMore": false
      }
    }
  ]
}

Available tools

The MCP server advertises at least these tools in `list_tools`:

• `list_test_runs`

List recent TestDriver test runs for the current team, with filters and pagination.

• `get_test_run_detail`

Get a single test run and its test cases (including replay IDs / share keys when available).

• `list_test_cases`

List individual test cases for the team with status, duration, error messages, and replay info.

• `get_filter_options`

Get branch, suite, repo, filename, commit, status, platform, and test name options for building queries.

Pointing Claude Code at the HTTP MCP endpoint

You can point Claude Code at the HTTP MCP endpoint using a JSON configuration similar to:

{
  "$schema": "https://schema.anthropic.com/mcp/servers.json",
  "mcpServers": {
    "testdriver-cloud": {
      "type": "sse",
      "url": "https://your-api-host.example.com/api/v1/mcp",
      "requestHeaders": {
        "X-Api-Key": "${TD_API_KEY}"
      },
      "description": "Query TestDriver test runs, test cases, and filters for your team using an API key."
    }
  }
}

You can find this exact snippet in the repo at:

• `claude-mcp-config.example.json`

Replace `https://your-api-host.example.com` with your actual API origin (e.g. `https://api.testdriver.ai` or `http://localhost:1337` in development).

Local development

For local development:

• Run your API server on `http://localhost:1337`
• Point `baseUrl` at `http://localhost:1337/api/v1/mcp`
• Use a local team or user API key in `TD_API_KEY`

{
  "mcpServers": {
    "testdriver-cloud-local": {
      "type": "sse",
      "url": "http://localhost:1337/api/v1/mcp",
      "requestHeaders": {
        "X-Api-Key": "${TD_API_KEY}"
      }
    }
  }
}

Skills documentation for Claude

Claude Code loads the agent and skills automatically when you install the plugin (see step 2). The underlying sources are:

• `ai/agents/testdriver.md` contains the **full TestDriver Agent Guide**
• `ai/skills/testdriver-*/SKILL.md` provide task-specific skills (MCP workflow, assertions, provisioning, etc.)

Use these as the primary reference for:

• How to initialize the `TestDriver` SDK in Vitest
• The MCP workflow for building tests interactively with visual feedback
• How to find elements, click, type, scroll, assert, and ca