@testdriverai/mcp 7.10.0-canary.0 → 7.10.1-test

package/docs/_data/examples-manifest.json

@@ -2,104 +2,108 @@
   "$schema": "./examples-manifest.schema.json",
   "examples": {
     "assert.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d038058ffe89003c6adc",
-      "lastUpdated": "2026-03-27T00:44:44.009Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b6fea57200d3f72adc69",
+      "lastUpdated": "2026-07-02T00:55:25.864Z"
     },
     "drag-and-drop.test.mjs": {
       "url": "https://console.testdriver.ai/runs/69a62b3aaa712ecd3dea730a/69a62b42fc0ac3cc632a918b",
       "lastUpdated": "2026-03-03T00:32:25.275Z"
     },
     "exec-pwsh.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d026a0a3ef8239de4746",
-      "lastUpdated": "2026-03-27T00:33:58.317Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b6234608e3f6c45ddf76",
+      "lastUpdated": "2026-07-02T00:58:50.738Z"
     },
     "match-image.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d0270201196437256ccf",
-      "lastUpdated": "2026-03-27T00:33:59.709Z"
+      "url": "https://console-test.testdriver.ai/runs/69c8738614b73310c7839412/69c8738c14b73310c783941d",
+      "lastUpdated": "2026-03-29T00:35:43.814Z"
     },
     "scroll-until-text.test.mjs": {
       "url": "https://console.testdriver.ai/runs/69a62b3aaa712ecd3dea730a/69a62b99dc33133fc0da9440",
       "lastUpdated": "2026-03-03T00:32:25.282Z"
     },
     "hover-text-with-description.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d029c2e6e94933886764",
-      "lastUpdated": "2026-03-27T00:32:41.295Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b653a57200d3f72adc5a",
+      "lastUpdated": "2026-07-02T00:59:36.056Z"
     },
     "windows-installer.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d02ce8a04db4b705cbe9",
-      "lastUpdated": "2026-03-27T00:34:04.862Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b656a57200d3f72adc5c",
+      "lastUpdated": "2026-07-02T01:16:50.573Z"
     },
     "exec-output.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d02ee8a04db4b705cbeb",
-      "lastUpdated": "2026-03-27T00:34:06.467Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b6584608e3f6c45ddf8d",
+      "lastUpdated": "2026-07-02T01:06:34.502Z"
     },
     "chrome-extension.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d024c2e6e94933886763",
-      "lastUpdated": "2026-03-27T00:33:19.157Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b6214608e3f6c45ddf74",
+      "lastUpdated": "2026-07-02T00:58:47.331Z"
     },
     "launch-vscode-linux.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d02be8a04db4b705cbe5",
-      "lastUpdated": "2026-03-27T00:38:16.512Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b63ba57200d3f72adc4c",
+      "lastUpdated": "2026-07-02T01:06:05.378Z"
     },
     "hover-image.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d0300201196437256cd3",
-      "lastUpdated": "2026-03-27T00:33:30.129Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b671a57200d3f72adc65",
+      "lastUpdated": "2026-07-02T00:53:05.430Z"
     },
     "installer.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d032c2e6e94933886769",
-      "lastUpdated": "2026-03-27T00:32:50.006Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b69e4608e3f6c45ddf96",
+      "lastUpdated": "2026-07-02T00:53:50.151Z"
     },
     "type.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d034c2e6e9493388676c",
-      "lastUpdated": "2026-03-27T00:33:33.802Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b6cb4608e3f6c45ddf98",
+      "lastUpdated": "2026-07-02T01:08:31.378Z"
     },
     "press-keys.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d036058ffe89003c6ada",
-      "lastUpdated": "2026-03-27T00:43:59.035Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b6e5a57200d3f72adc68",
+      "replayUrl": "https://console-test.testdriver.ai/replay/6a45bd51a57200d3f72adcbd?share=ty93E0byJrJD5eiBxh3nTQ",
+      "embedUrl": "https://console-test.testdriver.ai/replay/6a45bd51a57200d3f72adcbd?share=ty93E0byJrJD5eiBxh3nTQ&embed=true",
+      "lastUpdated": "2026-07-02T01:22:31.522Z"
     },
     "scroll-keyboard.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d03da0a3ef8239de474f",
-      "lastUpdated": "2026-03-27T00:34:18.283Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b72da57200d3f72adc70",
+      "lastUpdated": "2026-07-02T01:10:07.429Z"
     },
     "scroll.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d043058ffe89003c6ae0",
-      "lastUpdated": "2026-03-27T00:48:40.373Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b74ca57200d3f72adc72",
+      "lastUpdated": "2026-07-02T01:03:40.730Z"
     },
     "scroll-until-image.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d03f0201196437256cda",
-      "lastUpdated": "2026-03-27T00:33:03.090Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b72f4608e3f6c45ddf9a",
+      "lastUpdated": "2026-07-02T00:56:16.070Z"
     },
     "prompt.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d040c2e6e9493388676f",
-      "lastUpdated": "2026-03-27T00:34:21.306Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b7314608e3f6c45ddf9b",
+      "lastUpdated": "2026-07-02T01:10:12.253Z"
     },
     "focus-window.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d042e8a04db4b705cbf2",
-      "lastUpdated": "2026-03-27T00:33:06.137Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b733a57200d3f72adc71",
+      "lastUpdated": "2026-07-02T01:10:14.288Z"
     },
     "captcha-api.test.mjs": {
       "url": "https://console.testdriver.ai/runs/698f7df69e27ce1528d7d087/698f7fb0d3b320ad547d9d44",
       "lastUpdated": "2026-02-13T19:55:05.951Z"
     },
     "element-not-found.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d047058ffe89003c6ae4",
-      "lastUpdated": "2026-03-27T00:34:27.452Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b764a57200d3f72adc73",
+      "lastUpdated": "2026-07-02T01:04:04.551Z"
     },
     "formatted-logging.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d045058ffe89003c6ae1",
-      "lastUpdated": "2026-03-27T00:34:25.797Z"
+      "url": "https://console-test.testdriver.ai/runs/69c8738614b73310c7839412/69c873a714b73310c7839450",
+      "lastUpdated": "2026-03-29T00:36:10.628Z"
     },
     "hover-text.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d04b0201196437256ce6",
-      "lastUpdated": "2026-03-27T00:33:15.698Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b7984608e3f6c45ddfa5",
+      "lastUpdated": "2026-07-02T01:04:53.374Z"
     },
     "no-provision.test.mjs": {
       "url": "https://console.testdriver.ai/runs/69a62b3aaa712ecd3dea730a/69a62b7706a177a05bccd1cf",
       "lastUpdated": "2026-03-03T00:32:25.279Z"
     },
     "ai.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d04ac2e6e94933886778",
-      "lastUpdated": "2026-03-27T00:52:24.469Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b77da57200d3f72adc74",
+      "replayUrl": "https://console-test.testdriver.ai/replay/6a45bf434608e3f6c45de01b?share=eQ8yZOqg3UqrJKjELcDm2A",
+      "embedUrl": "https://console-test.testdriver.ai/replay/6a45bf434608e3f6c45de01b?share=eQ8yZOqg3UqrJKjELcDm2A&embed=true",
+      "lastUpdated": "2026-07-02T01:30:50.186Z"
     },
     "popup-loading.test.mjs": {
       "url": "https://console.testdriver.ai/runs/698bc89f7140c3fa7daaca8d/698bca7f7140c3fa7daacbf7",
@@ -134,12 +138,12 @@
       "lastUpdated": "2026-02-13T19:55:05.953Z"
     },
     "findall-coffee-icons.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d03ae8a04db4b705cbf0",
-      "lastUpdated": "2026-03-27T00:33:38.971Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b714a57200d3f72adc6a",
+      "lastUpdated": "2026-07-02T00:55:48.391Z"
     },
     "parse.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69c5d0220201196437256cce/69c5d04d0201196437256ce7",
-      "lastUpdated": "2026-03-27T00:34:32.300Z"
+      "url": "https://console-test.testdriver.ai/runs/6a45b608fa48a35463bd55d8/6a45b7af4608e3f6c45ddfaa",
+      "lastUpdated": "2026-07-02T01:05:15.804Z"
     },
     "flake-diffthreshold-001.test.mjs": {
       "url": "https://console.testdriver.ai/runs/69a62b3aaa712ecd3dea730a/69a62bcafc0ac3cc632a91aa",
@@ -172,6 +176,10 @@
     "flake-diffthreshold-01.test.mjs": {
       "url": "https://console.testdriver.ai/runs/69a62b3aaa712ecd3dea730a/69a62bd0348bcf90ca081079",
       "lastUpdated": "2026-03-03T00:32:25.283Z"
+    },
+    "exec-stream-logs.test.mjs": {
+      "url": "https://console-test.testdriver.ai/runs/69c9c4feffa05350a7d3abc1/69c9c520ffa05350a7d3abd9",
+      "lastUpdated": "2026-03-30T00:35:14.437Z"
     }
   }
 }

package/docs/_data/examples-manifest.schema.json

@@ -14,8 +14,18 @@
         "properties": {
           "url": {
             "type": "string",
-            "description": "Full URL to the test run (without ?embed=true)",
-            "pattern": "^https://console\\.testdriver\\.ai/runs/.+"
+            "description": "Full URL to the test run (legacy source for testcase ID)",
+            "pattern": "^https://console(?:-(?:test|canary))?\\.testdriver\\.ai/runs/.+"
+          },
+          "replayUrl": {
+            "type": "string",
+            "description": "Public replay URL with share key",
+            "pattern": "^https://console(?:-(?:test|canary))?\\.testdriver\\.ai/replay/.+"
+          },
+          "embedUrl": {
+            "type": "string",
+            "description": "Public replay embed URL used by docs iframes",
+            "pattern": "^https://console(?:-(?:test|canary))?\\.testdriver\\.ai/replay/.+"
           },
           "lastUpdated": {
             "type": "string",

package/docs/_scripts/extract-example-urls.js

@@ -15,6 +15,19 @@ const path = require("path");
 
 const MANIFEST_PATH = path.join(__dirname, "../_data/examples-manifest.json");
 
+function deriveEmbedUrlFromReplayUrl(replayUrl) {
+  if (!replayUrl) return null;
+  try {
+    const url = new URL(replayUrl);
+    if (!url.pathname.includes("/replay/")) return null;
+    if (!url.searchParams.get("share")) return null;
+    url.searchParams.set("embed", "true");
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
 // Parse command line arguments
 function parseArgs() {
   const args = process.argv.slice(2);
@@ -81,12 +94,16 @@ function processResultsDir(resultsDir) {
         const result = JSON.parse(content);
         const testFileName = path.basename(result.test?.file || result.testFile || entry.name);
         const url = result.urls?.testRun || result.testRunLink;
+        const replayUrl = result.replay?.url || result.replayUrl || null;
+        const embedUrl = result.replay?.embedUrl || deriveEmbedUrlFromReplayUrl(replayUrl);
 
-        if (!url) continue;
+        if (!url && !embedUrl) continue;
 
         const isNew = !manifest.examples[testFileName];
         manifest.examples[testFileName] = {
-          url: url,
+          url: url || manifest.examples[testFileName]?.url || null,
+          ...(replayUrl ? { replayUrl } : {}),
+          ...(embedUrl ? { embedUrl } : {}),
           lastUpdated: result.date || new Date().toISOString(),
         };
 
@@ -96,7 +113,8 @@ function processResultsDir(resultsDir) {
           stats.updated++;
         }
 
-        console.log(`${isNew ? "➕" : "🔄"} ${testFileName}: ${url}`);
+        const displayUrl = embedUrl || url || "(no URL)";
+        console.log(`${isNew ? "➕" : "🔄"} ${testFileName}: ${displayUrl}`);
       } catch (err) {
         console.warn(`⚠️  Failed to read ${jsonFile}: ${err.message}`);
       }

package/docs/_scripts/generate-examples.js

@@ -21,6 +21,16 @@ const MANIFEST_PATH = path.join(__dirname, "../_data/examples-manifest.json");
 const OUTPUT_DIR = path.join(__dirname, "../v7/examples");
 const DOCS_JSON_PATH = path.join(__dirname, "../docs.json");
 
+// Examples to exclude from docs generation (filenames without path)
+const EXCLUDE_FROM_DOCS = [
+  "exec-output.test.mjs",
+  "exec-pwsh.test.mjs",
+  "focus-window.test.mjs",
+  "prompt.test.mjs",
+  "scroll-until-image.test.mjs",
+  "windows-installer.test.mjs",
+];
+
 // Icon mapping based on test type/content
 const ICON_MAP = {
   ai: "wand-magic-sparkles",
@@ -74,11 +84,11 @@ function saveDocsJson(docsJson) {
   fs.writeFileSync(DOCS_JSON_PATH, JSON.stringify(docsJson, null, 2) + "\n", "utf-8");
 }
 
-// Get all example files
+// Get all example files (excluding ones in EXCLUDE_FROM_DOCS)
 function getExampleFiles() {
   return fs
     .readdirSync(EXAMPLES_DIR)
-    .filter((f) => f.endsWith(".test.mjs"))
+    .filter((f) => f.endsWith(".test.mjs") && !EXCLUDE_FROM_DOCS.includes(f))
     .sort();
 }
 
@@ -279,22 +289,61 @@ function extractTestcaseId(url) {
   return pathParts.length >= 2 ? pathParts[pathParts.length - 1] : null;
 }
 
-// Generate replay URL from testcase ID
-function generateReplayUrl(testcaseId) {
-  // Use the API replay endpoint which handles the redirect with embed=true
-  const apiRoot = process.env.TD_API_ROOT || 'https://api.testdriver.ai';
+// Derive API root from a console URL (e.g. console-test.testdriver.ai → api-test.testdriver.ai)
+function apiRootFromConsoleUrl(sourceUrl) {
+  if (!sourceUrl) return null;
+  try {
+    const url = new URL(sourceUrl);
+    // Map console* hostname to api* hostname
+    const apiHostname = url.hostname.replace(/^console/, 'api');
+    return `${url.protocol}//${apiHostname}`;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeEmbedUrl(rawUrl) {
+  if (!rawUrl) return null;
+  try {
+    const url = new URL(rawUrl);
+    if (!url.pathname.includes('/replay/')) return null;
+    if (!url.searchParams.get('share')) return null;
+    url.searchParams.set('embed', 'true');
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
+// Resolve the best embed URL for docs:
+// 1) explicit embedUrl from manifest (preferred)
+// 2) replayUrl in manifest (converted to embed=true)
+// 3) legacy run URL via testcase replay redirect endpoint
+function resolveReplayEmbedUrl(manifestEntry) {
+  const directEmbed = normalizeEmbedUrl(manifestEntry?.embedUrl);
+  if (directEmbed) return directEmbed;
+
+  const replayEmbed = normalizeEmbedUrl(manifestEntry?.replayUrl);
+  if (replayEmbed) return replayEmbed;
+
+  const testcaseId = manifestEntry?.url ? extractTestcaseId(manifestEntry.url) : null;
+  if (!testcaseId) return null;
+
+  const apiRoot = apiRootFromConsoleUrl(manifestEntry?.url) || process.env.TD_API_ROOT || 'https://api.testdriver.ai';
   return `${apiRoot}/api/v1/testdriver/testcase/${testcaseId}/replay`;
 }
 
 // Update existing MDX file by finding the marker comment and replacing the iframe
-function updateExistingMDX(existingContent, filename, testcaseId) {
+function updateExistingMDX(existingContent, filename, replayEmbedUrl) {
   const marker = `{/* ${filename} output */}`;
   
   if (!existingContent.includes(marker)) {
     return null; // Marker not found, can't update
   }
   
-  const replayUrl = generateReplayUrl(testcaseId);
+  if (!replayEmbedUrl) {
+    return null;
+  }
   
   // Pattern to match the marker followed by the iframe tag
   const escapedFilename = filename.replace(/\./g, '\\.');
@@ -303,7 +352,7 @@ function updateExistingMDX(existingContent, filename, testcaseId) {
     's'
   );
   
-  const replacement = `$1<iframe \n  src="${replayUrl}"$2/>`;
+  const replacement = `$1<iframe \n  src="${replayEmbedUrl}"$2/>`;
   const updated = existingContent.replace(pattern, replacement);
   
   if (updated === existingContent) {
@@ -339,7 +388,7 @@ function generateMDX(testMeta, manifest, description) {
   const sidebarTitle = generateSidebarTitle(testMeta.filename);
   const shortDescription = generateShortDescription(testMeta);
   const manifestEntry = manifest.examples[testMeta.filename];
-  const testcaseId = manifestEntry?.url ? extractTestcaseId(manifestEntry.url) : null;
+  const replayEmbedUrl = resolveReplayEmbedUrl(manifestEntry);
 
   let mdx = `---
 title: "${title}"
@@ -355,15 +404,14 @@ ${description}
 `;
 
   // Add Live Test Run section if URL exists
-  if (testcaseId) {
-    const replayUrl = generateReplayUrl(testcaseId);
+  if (replayEmbedUrl) {
     mdx += `## Live Test Run
 
 Watch this test execute in a real sandbox environment:
 
 {/* ${testMeta.filename} output */}
 <iframe 
-  src="${replayUrl}" 
+  src="${replayEmbedUrl}" 
   width="100%" 
   height="600" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}
@@ -560,9 +608,9 @@ async function main() {
 
         // Update iframe URL if manifest entry exists
         const manifestEntry = manifest.examples[testMeta.filename];
-        const testcaseId = manifestEntry?.url ? extractTestcaseId(manifestEntry.url) : null;
-        if (testcaseId) {
-          const iframeUpdated = updateExistingMDX(content, testMeta.filename, testcaseId);
+        const replayEmbedUrl = resolveReplayEmbedUrl(manifestEntry);
+        if (replayEmbedUrl) {
+          const iframeUpdated = updateExistingMDX(content, testMeta.filename, replayEmbedUrl);
           if (iframeUpdated && iframeUpdated !== content) {
             content = iframeUpdated;
             changed = true;

package/docs/changelog.mdx

@@ -5,6 +5,33 @@ rss: true
 icon: "code-compare"
 ---
 
+<Update label="v7.9.51-canary" description="April 2026" tags={["canary"]}>
+
+🚀 Canary release
+
+This release promotes changes from `v7.9.4-test` through `v7.9.51-test` to canary, rolling up all updates since `v7.9.3`.
+
+✨ New features
+
+- (Internal) **Autoscaling**
+- (Internal) **End-to-end distributed tracing**
+
+🔧 Improvements
+
+- **Faster image matching**
+- **Storage and infra hardening**
+- **Sentry environment consistency**
+- **Chrome extension interaction reliability**
+- **Docs and onboarding refresh** — Updated v7 docs, SDK examples, and VS Code onboarding/init flows.
+
+🐛 Bug fixes
+
+- **Windows AMI build stability** — Fixed `chrome.exe` startup/build failures.
+- **Realtime cleanup reliability** — Fixed connection cleanup leaks in session shutdown paths.
+- **Environment and deployment fixes** 
+
+</Update>
+
 <Update label="v7.8.0-test.22" description="March 2026" tags={["test"]}>
 
 Releases test.11 through test.22 include version bumps and internal CI improvements across all packages. No new user-facing changes — see [v7.8.0-test.10](#v780-test10) for the latest updates in this release stream.
@@ -66,7 +93,7 @@ This release includes all changes from v7.8.0-test.6 with version bumps across a
 
 ✨ New features
 
-- **[GitHub Copilot integration](/v7/copilot/setup)** — Use TestDriver directly from GitHub Copilot in VS Code. The new MCP server lets Copilot launch sandboxes, interact with elements, and run assertions through natural language. Includes guides for [creating tests](/v7/copilot/creating-tests), [running tests](/v7/copilot/running-tests), [GitHub Actions integration](/v7/copilot/github), and [auto-healing](/v7/copilot/auto-healing).
+- **[GitHub Copilot integration](/v7/copilot/running-tests)** — Use TestDriver directly from GitHub Copilot in VS Code. The new MCP server lets Copilot launch sandboxes, interact with elements, and run assertions through natural language. Includes guides for [creating tests](/v7/generating-tests), [running tests](/v7/copilot/running-tests), [GitHub Actions integration](/v7/copilot/auto-healing#use-testdriver-in-github), and [auto-healing](/v7/copilot/auto-healing).
 
 🔧 Improvements
 
@@ -83,7 +110,7 @@ This release includes all changes from v7.8.0-canary.4 with version bumps.
 ✨ New features
 
 - **[Cache API](/v7/cache)** — Speed up repeated test runs with screenshot-based caching. The system compares screenshots to cached results and reuses element positions when the screen hasn't changed, reducing AI calls.
-- **[Custom error classes](/v7/errors)** — New `ElementNotFoundError` and `AIError` classes with rich debugging info including screenshot paths, pixel diffs, and detailed messages.
+- **[Custom error classes](/v7/errors)** — New `ElementNotFoundError` class with rich debugging info including screenshot paths, pixel diffs, and detailed messages.
 - **[Events system](/v7/events)** — Listen to SDK lifecycle events with wildcard support via `testdriver.emitter`. Uses colon-delimited namespaces (e.g., `command:start`, `log:*`).
 - **[Provision API](/v7/provision)** — Launch browsers, desktop apps, VS Code, and Chrome extensions in your sandbox before tests run. Access via `testdriver.provision.*`.
 - **[Redraw detection](/v7/redraw)** — Wait for screens to stabilize after interactions using two-phase detection with pixel comparison and z-score analysis.

package/docs/claude-mcp-plugin.mdx

@@ -2,29 +2,74 @@
 title: Using TestDriver with Claude Code (MCP)
 ---
 
-TestDriver exposes test results and analytics over an **HTTP MCP server**, so Claude Code (or any MCP-compatible client) can inspect your test runs, failures, and filters.
+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.
 
-This guide assumes:
+> 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.
 
-- Your API server is running the MCP endpoint at `POST /api/v1/mcp`
-- You have a **team or user API key** for authentication
-- You are using this repo (`testdriverai`) as the SDK / local tooling
-
-## 1. Configure an API key
-
-Get your API key from the team settings:
+## 1. Get a TestDriver API key
 
 - Visit your team page (e.g. `https://console.testdriver.ai/team`)
 - Create or copy a **Team API Key** (or User API Key)
-- Store it locally as an environment variable, for example:
+- 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
+```
 
-```bash
-export TD_API_KEY="your_api_key_here"
+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 MCP server expects this API key in the `X-Api-Key` header (or `Authorization: Bearer <key>`).
+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).
 
-## 2. HTTP MCP endpoint contract
+## 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.
+
+---
+
+## 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:
 
@@ -32,6 +77,8 @@ 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**
@@ -89,7 +136,7 @@ The MCP server advertises at least these tools in `list_tools`:
 - `get_filter_options`  
   Get branch, suite, repo, filename, commit, status, platform, and test name options for building queries.
 
-## 3. Claude Code MCP server configuration
+### Pointing Claude Code at the HTTP MCP endpoint
 
 You can point Claude Code at the HTTP MCP endpoint using a JSON configuration similar to:
 
@@ -137,12 +184,12 @@ For local development:
 }
 ```
 
-## 4. Skills documentation for Claude
+### Skills documentation for Claude
 
-Claude Code expects a `SKILLs.md` file to explain how to use a server. In this repo:
+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**
-- `SKILLs.md` acts as a short wrapper that points Claude (and other agents) to the agent guide
+- `ai/skills/testdriver-*/SKILL.md` provide task-specific skills (MCP workflow, assertions, provisioning, etc.)
 
 Use these as the primary reference for: