@testdriverai/agent 7.11.229-canary → 7.11.231-test

package/docs/claude-mcp-plugin.mdx

@@ -1,244 +0,0 @@
----
-title: Using TestDriver with Claude Code (MCP)
----
-
-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:
-
-  ```bash
-  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:
-
-```text
-/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:
-
-```text
-@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, …):
-
-```json
-{
-  "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.
-
----
-
-## Remote (hosted URL) install — no CLI, browser login
-
-TestDriver also runs a **hosted MCP server** you can connect to with just a URL. There is no `npx` command and no API key to paste: the server speaks OAuth 2.1, so your client opens a browser, you sign in with TestDriver, and the tools appear. It exposes the **full live tool set** (`session_start`, `find`, `click`, `type`, `assert`, …) plus the read-only data tools, all scoped to your team.
-
-Hosted endpoint:
-
-```text
-https://mcp.testdriver.ai/mcp
-```
-
-The server advertises its authorization server (Auth0) via [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) protected-resource metadata at:
-
-```text
-https://mcp.testdriver.ai/.well-known/oauth-protected-resource
-```
-
-Spec-compliant clients discover and complete the OAuth flow automatically:
-
-- **Claude** — add a custom connector pointing at the URL above; Claude runs the browser login for you.
-- **VS Code / Copilot** — add a remote MCP server entry with the URL; VS Code handles the OAuth handshake.
-- **ChatGPT** — add it as a connector by URL.
-- **Any spec-compliant client** — point it at the URL; it will read the metadata, sign you in, and connect.
-
-```json
-{
-  "mcpServers": {
-    "testdriver": {
-      "url": "https://mcp.testdriver.ai/mcp"
-    }
-  }
-}
-```
-
-Each connection gets its own isolated sandbox, so multiple people (or multiple chats) can run tests at the same time without interfering. The API-key paths above still work for automation and CI.
-
----
-
-## 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:
-
-```text
-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**
-
-```json
-{
-  "kind": "list_tools"
-}
-```
-
-- **Call a tool**
-
-```json
-{
-  "kind": "call_tool",
-  "tool": "list_test_runs",
-  "arguments": {
-    "status": "failed",
-    "page": 1,
-    "limit": 20
-  }
-}
-```
-
-Responses from tool calls follow the MCP content convention:
-
-```json
-{
-  "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:
-
-```json
-{
-  "$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`
-
-```json
-{
-  "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 capture screenshots
-
-The MCP tools described above are **read-only** helpers for:
-
-- Inspecting recent test runs and failures
-- Discovering branches, files, and suites to focus on
-- Pulling detailed test case and replay information into Claude for analysis
-
-Use the SDK (`testdriverai`) for **driving tests**, and the HTTP MCP server (`/api/v1/mcp`) for **observing and debugging** them from Claude Code.
-