@askqa/mcp 1.2.3 → 1.2.6

package/.claude-plugin/marketplace.json

@@ -0,0 +1,9 @@
+{
+  "plugins": [
+    {
+      "name": "askqa",
+      "version": "1.2.3",
+      "description": "AskQA skills — set up notifications and monitoring for your websites"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "askqa",
-  "version": "1.2.3",
+  "version": "1.2.6",
   "description": "AskQA skills — set up notifications and monitoring for your websites",
   "mcpServers": {
     "askqa": {

package/README.md

@@ -54,6 +54,9 @@ Get your API key from [askqa.ai](https://askqa.ai) after signing in.
 | `list_notification_channels`  | List notification channels                              |
 | `remove_notification_channel` | Remove a notification channel                           |
 | `test_notification_channel`   | Send a test notification                                |
+| `share_test_run`              | Make a test run publicly shareable, returns a share URL |
+| `unshare_test_run`            | Revoke public sharing for a test run                    |
+| `get_shared_run`              | Fetch a shared run by URL or token (no API key needed); includes test code to recreate it |
 
 ## Example Conversations
 
@@ -75,6 +78,18 @@ The AI will use `screenshot_url` to inspect the page, write custom Playwright co
 
 The AI will call `get_test_results` and `get_test_screenshots` to analyze the failure.
 
+**Share a test run:**
+
+> "Share my latest checkout run with the client"
+
+The AI will call `get_test_results` to find the run, then `share_test_run` to generate a public link. Use `unshare_test_run` to revoke access later.
+
+**Copy a shared test into your account:**
+
+> "I got this link — can you set up the same test for my site? https://askqa.ai/r/..."
+
+The AI will call `get_shared_run` to read the test code from the shared link (no API key needed), then `create_test` to add it to your account.
+
 ## Privacy Policy
 
 This extension only makes HTTPS requests to the AskQA API. It does not access files on your computer or collect analytics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askqa/mcp",
-  "version": "1.2.3",
+  "version": "1.2.6",
   "description": "MCP server for AskQA — monitor websites with automated tests by chatting with AI",
   "type": "module",
   "license": "MIT",

package/server.js

@@ -84,6 +84,17 @@ async function pollTestRun(testRunId, maxWaitMs = 300000) {
   throw new Error(`Test run ${testRunId} did not finish within ${maxWaitMs / 1000}s`);
 }
 
+async function pollJob(jobId, maxWaitMs = 300000) {
+  const start = Date.now();
+  while (Date.now() - start < maxWaitMs) {
+    const job = await apiGet(`/api/jobs/${jobId}`);
+    if (job.status === "done") return job.result;
+    if (job.status === "failed") throw new Error(job.error || "Job failed");
+    await sleep(2000);
+  }
+  throw new Error(`Job ${jobId} did not finish within ${maxWaitMs / 1000}s`);
+}
+
 async function fetchScreenshot(url) {
   try {
     const res = await fetch(url, {
@@ -176,16 +187,13 @@ const server = new McpServer(
       "If the latest run passed, confirm it's working. If it failed, report what failed.",
       "Only call run_test if the user explicitly asks to run a new test — checking status should use existing results.",
       "",
-      "When the user asks to monitor a site, use list_templates to see available templates.",
-      "There are two kinds of templates:",
+      "When the user asks to monitor a site or set up tests, use detect_tests first.",
+      "detect_tests screenshots the site and asks AI to suggest 2-3 meaningful e2e tests.",
+      "The user then picks which tests to add. You write the code, validate with validate_test,",
+      "iterate until all steps pass, then save with create_test.",
       "",
-      "1. Universal templates (e.g. 'quick-checks') — work on any website with no configuration.",
-      "   Just call create_test with template_id and you're done.",
-      "",
-      "2. Site-specific templates (e.g. 'shopify-cart') — need to discover CSS selectors for the target site.",
-      "   Call detect_template first to probe the site and generate standalone Playwright code,",
-      "   then call create_test with that generated code (not the template_id).",
-      "   Templates that support detection have supportsDetection: true in list_templates output.",
+      "For universal templates (e.g. 'quick-checks') that work on any site with no config,",
+      "you can call create_test with template_id directly without detect_tests.",
     ].join("\n"),
   }
 );
@@ -193,7 +201,7 @@ const server = new McpServer(
 server.registerTool(
   "list_templates",
   {
-    description: "List available test templates with usage hints. Some templates work directly with create_test (universal), others need detect_template first to discover site-specific selectors (site-specific).",
+    description: "List available universal test templates (e.g. 'quick-checks') that work on any site with no configuration. For custom site-specific tests, use detect_tests instead.",
     readOnlyHint: true,
   },
   async () => {
@@ -205,12 +213,7 @@ server.registerTool(
         lines.push(`  Name: ${t.name}`);
         lines.push(`  Description: ${t.description}`);
         lines.push(`  Steps: ${t.steps.join(", ")}`);
-        if (t.supportsCodeGeneration) {
-          lines.push(`  supportsDetection: true`);
-          lines.push(`  Usage: call detect_template → get generated code → create_test with code`);
-        } else {
-          lines.push(`  Usage: call create_test with template_id="${t.id}" directly`);
-        }
+        lines.push(`  Usage: call create_test with template_id="${t.id}" directly`);
         lines.push("");
       }
       return { content: [{ type: "text", text: lines.join("\n") }] };
@@ -221,66 +224,53 @@ server.registerTool(
 );
 
 server.registerTool(
-  "detect_template",
+  "detect_tests",
   {
-    description: "Run template detection against a URL to discover selectors and generate custom test code. This is the fastest way to create a custom test — detection runs the template flow against the site, discovers which CSS selectors work, and generates standalone Playwright test code with those selectors baked in. Use the generated code with create_test to save it.",
+    description: "Start here when a user wants to monitor a new site. Screenshots the URL and uses AI to suggest 2-3 meaningful e2e tests tailored to that specific site (e.g. checkout flow, login, add to cart). Returns a page_summary and a list of suggestions with names, descriptions, and step sketches. After calling this: present the suggestions to the user, let them pick which ones to add, then YOU write the Playwright test code for each chosen test, validate with validate_test, iterate until it passes, then save with create_test.",
     readOnlyHint: true,
     inputSchema: {
-      template_id: z.string().describe("Template ID from list_templates (e.g. 'shopify-cart')"),
-      url: z.string().describe("The target URL to detect against (e.g. 'https://my-store.myshopify.com')"),
+      url: z.string().describe("The website URL to analyze (e.g. 'https://my-store.com')"),
     },
   },
-  async ({ template_id, url }) => {
+  async ({ url }) => {
     try {
-      const result = await apiPost(`/api/tests/templates/${template_id}/detect`, { url });
-      const content = [];
+      const { job_id } = await apiPost("/api/tests/suggest", { url });
+      const result = await pollJob(job_id);
       const lines = [];
 
-      const statusLabel = result.status === "passed" ? "PASSED" : "FAILED";
-      lines.push(`Detection: ${statusLabel}`);
-      lines.push("");
-
-      if (result.steps) {
-        lines.push("Steps:");
-        for (const step of result.steps) {
-          const icon = step.status === "passed" ? "+" : "x";
-          lines.push(`  ${icon} ${step.name} — ${step.status}`);
-          if (step.error) lines.push(`    Error: ${step.error}`);
-        }
+      if (result.page_summary) {
+        lines.push(`Site: ${result.page_summary}`);
         lines.push("");
       }
 
-      if (result.selectors) {
-        lines.push("Discovered selectors:");
-        for (const [key, value] of Object.entries(result.selectors)) {
-          lines.push(`  ${key}: ${value}`);
-        }
+      const suggestions = result.suggestions || [];
+      if (suggestions.length === 0) {
+        lines.push("No suggestions available. You can still write a custom test using screenshot_url to inspect the page.");
+      } else {
+        lines.push(`Suggested tests (${suggestions.length}):`);
         lines.push("");
-      }
-
-      if (result.code) {
-        lines.push("Generated test code (use with create_test):");
-        lines.push("```");
-        lines.push(result.code);
-        lines.push("```");
-      }
-
-      content.push({ type: "text", text: lines.join("\n") });
-
-      // Fetch screenshots for each step
-      if (result.steps) {
-        for (const step of result.steps) {
-          if (!step.screenshot) continue;
-          const screenshotUrl = `${API_URL}/api/screenshots/${result.executionId}/${step.screenshot}`;
-          const base64 = await fetchScreenshot(screenshotUrl);
-          if (base64) {
-            content.push({ type: "text", text: `Screenshot: ${step.name}` });
-            content.push({ type: "image", data: base64, mimeType: "image/png" });
+        for (let i = 0; i < suggestions.length; i++) {
+          const s = suggestions[i];
+          lines.push(`${i + 1}. ${s.name}`);
+          lines.push(`   What it tests: ${s.description}`);
+          lines.push(`   Why it matters: ${s.why}`);
+          if (s.steps && s.steps.length > 0) {
+            lines.push(`   Steps:`);
+            for (const step of s.steps) {
+              lines.push(`     - ${step}`);
+            }
           }
+          lines.push("");
         }
+        lines.push("Next steps:");
+        lines.push("1. Ask the user which test(s) they want to add");
+        lines.push("2. Use screenshot_url to inspect the page and discover selectors");
+        lines.push("3. Write the Playwright test code");
+        lines.push("4. Validate with validate_test — iterate until ALL steps pass");
+        lines.push("5. Save with create_test");
       }
 
-      return { content };
+      return { content: [{ type: "text", text: lines.join("\n") }] };
     } catch (err) {
       return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
     }
@@ -290,7 +280,7 @@ server.registerTool(
 server.registerTool(
   "create_test",
   {
-    description: "Create a saved test. Use template_id for universal templates (e.g. 'quick-checks') that work on any site. Use code for custom tests or for site-specific templates after running detect_template. Provide template_id or code, not both.",
+    description: "Save a validated test. IMPORTANT: For code-based tests, only call this AFTER validate_test confirms the test passes — never save untested code. Use template_id for universal templates (e.g. 'quick-checks') that work on any site without validation. Use code for custom tests after running detect_tests → write code → validate_test. Provide template_id or code, not both.",
     destructiveHint: true,
     inputSchema: {
       name: z.string().describe("A name for this test (e.g. 'Homepage health check')"),
@@ -331,7 +321,8 @@ server.registerTool(
   },
   async ({ url }) => {
     try {
-      const result = await apiPost("/api/tests/screenshot", { url });
+      const { job_id } = await apiPost("/api/tests/screenshot", { url });
+      const result = await pollJob(job_id);
       const content = [];
 
       // Page info as structured text
@@ -384,7 +375,7 @@ server.registerTool(
 server.registerTool(
   "validate_test",
   {
-    description: "Start here when writing a new test. Dry-runs Playwright code against a URL without saving it — returns step results, screenshots, and page structure. Steps continue even on failure for maximum debug signal. Iterate here until the test passes, then call create_test to save it.",
+    description: "REQUIRED before create_test for any code-based test. Dry-runs Playwright code against a URL without saving it — returns step results, screenshots, and page structure. Steps continue even on failure for maximum debug signal. Iterate here until ALL steps pass, then call create_test to save it.",
     readOnlyHint: true,
     inputSchema: {
       code: z.string().describe("Custom Playwright test code. Must define an async function test({ page, step, log })."),
@@ -1077,6 +1068,111 @@ server.registerTool(
   }
 );
 
+server.registerTool(
+  "get_shared_run",
+  {
+    description:
+      "Fetch a publicly shared test run by its share URL or token. No API key required — anyone with the link can call this. " +
+      "Returns run results, step details, and the original test config (test_code, test_template_id, test_params, test_url) " +
+      "so you can recreate the test in your own account using create_test.",
+    readOnlyHint: true,
+    inputSchema: {
+      share_url_or_token: z.string().describe("The share URL (https://askqa.ai/r/TOKEN) or just the token"),
+    },
+  },
+  async ({ share_url_or_token }) => {
+    try {
+      const token = share_url_or_token.includes("/")
+        ? share_url_or_token.split("/").pop()
+        : share_url_or_token;
+
+      const res = await fetch(`${API_URL}/api/test-runs/shared/${encodeURIComponent(token)}`);
+      if (res.status === 404) {
+        return { content: [{ type: "text", text: "Shared run not found. The link may be invalid or sharing may have been revoked." }], isError: true };
+      }
+      if (!res.ok) {
+        throw new Error(`API ${res.status}: ${await res.text()}`);
+      }
+      const run = await res.json();
+
+      const lines = [
+        `Run #${run.id} — ${run.test_name || "Unnamed test"} | ${run.status}`,
+        `URL: ${run.test_url || "unknown"}`,
+        `Duration: ${run.result?.durationMs ? (run.result.durationMs / 1000).toFixed(1) + "s" : "N/A"}`,
+        "",
+      ];
+
+      if (run.result?.steps?.length) {
+        lines.push("Steps:");
+        for (const s of run.result.steps) {
+          lines.push(`  ${s.status === "passed" ? "✓" : "✗"} ${s.name}${s.error ? " — " + s.error : ""}`);
+        }
+        lines.push("");
+      }
+
+      if (run.test_code) {
+        lines.push("Test code (validate with validate_test first, then create_test to save):");
+        lines.push("```javascript");
+        lines.push(run.test_code);
+        lines.push("```");
+      } else if (run.test_template_id) {
+        lines.push(`Template: ${run.test_template_id}`);
+        if (run.test_params && Object.keys(run.test_params).length) {
+          lines.push(`Params: ${JSON.stringify(run.test_params)}`);
+        }
+      }
+
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+server.registerTool(
+  "share_test_run",
+  {
+    description: "Make a test run publicly shareable. Returns a share_url that anyone can open without logging in. Calling again on an already-shared run returns the same URL. Use unshare_test_run to revoke access.",
+    inputSchema: {
+      test_run_id: z.coerce.number().describe("The test run ID to share"),
+    },
+  },
+  async ({ test_run_id }) => {
+    try {
+      const data = await apiPost(`/api/test-runs/${test_run_id}/share`, {});
+      return { content: [{ type: "text", text: `Share URL: ${data.share_url}\n\nAnyone with this link can view the test run results without logging in.` }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+server.registerTool(
+  "unshare_test_run",
+  {
+    description: "Revoke public sharing for a test run. The share URL will stop working immediately.",
+    destructiveHint: true,
+    inputSchema: {
+      test_run_id: z.coerce.number().describe("The test run ID to stop sharing"),
+    },
+  },
+  async ({ test_run_id }) => {
+    try {
+      const res = await fetch(`${API_URL}/api/test-runs/${test_run_id}/share`, {
+        method: "DELETE",
+        headers: { Authorization: `Bearer ${API_KEY}` },
+      });
+      if (!res.ok && res.status !== 204) {
+        const text = await res.text();
+        throw new Error(`API ${res.status}: ${text}`);
+      }
+      return { content: [{ type: "text", text: `Sharing disabled for run #${test_run_id}. The public link no longer works.` }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);
 console.error("AskQA MCP server running on stdio");