@askqa/mcp 1.0.8 → 1.1.0

package/.claude-plugin/plugin.json

@@ -1,5 +1,17 @@
 {
   "name": "askqa",
-  "version": "1.0.8",
-  "description": "AskQA skills — set up notifications and monitoring for your websites"
+  "version": "1.1.0",
+  "description": "AskQA skills — set up notifications and monitoring for your websites",
+  "mcpServers": {
+    "askqa": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/server.js"
+      ],
+      "env": {
+        "AUTOQA_API_URL": "",
+        "AUTOQA_API_KEY": ""
+      }
+    }
+  }
 }

package/README.md

@@ -73,3 +73,19 @@ The AI will use `screenshot_url` to inspect the page, write custom Playwright co
 > "Why is my checkout test failing?"
 
 The AI will call `get_test_results` and `get_test_screenshots` to analyze the failure.
+
+## Privacy Policy
+
+This extension only makes HTTPS requests to the AskQA API. It does not access files on your computer or collect analytics.
+
+For full details, see the [Privacy Policy](https://askqa.ai/privacy).
+
+## Support
+
+- **Website**: [askqa.ai](https://askqa.ai)
+- **Issues**: [GitHub Issues](https://github.com/askqa-ai/askqa-plugins/issues)
+- **Email**: support@askqa.ai
+
+## License
+
+MIT

package/package.json

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

package/server.js

@@ -97,10 +97,11 @@ async function fetchScreenshot(url) {
   }
 }
 
-function buildTestRunText(testRun) {
+function buildTestRunText(testRun, testName) {
   const icon = testRun.status === "completed" ? "✓" : testRun.status === "failed" ? "✗" : "…";
+  const testLabel = testName ? `${testName} (#${testRun.test_id})` : `${testRun.test_id}`;
   const lines = [
-    `${icon} Run #${testRun.id} | Test: ${testRun.test_id} | ${testRun.trigger_type} | ${testRun.status}`,
+    `${icon} Run #${testRun.id} | ${testLabel} | ${testRun.trigger_type} | ${testRun.status}`,
   ];
 
   if (testRun.result?.durationMs) {
@@ -179,6 +180,7 @@ server.registerTool(
   "list_templates",
   {
     description: "List available test templates. Returns template IDs, names, descriptions, and steps.",
+    readOnlyHint: true,
   },
   async () => {
     try {
@@ -194,20 +196,25 @@ server.registerTool(
   "create_test",
   {
     description: "Create a saved test. Use template_id for built-in templates, or code for custom Playwright tests. Provide one or the other, not both.",
+    destructiveHint: true,
     inputSchema: {
       name: z.string().describe("A name for this test (e.g. 'Homepage health check')"),
       url: z.string().describe("The target URL to test (e.g. 'https://example.com')"),
       template_id: z.string().optional().describe("Template ID from list_templates (e.g. 'quick-checks'). Omit if using code."),
       params: z.record(z.string()).optional().describe("Optional template parameters"),
-      code: z.string().optional().describe("Custom Playwright test code. Must define an async function test({ page, step, log }). Omit if using template_id."),
+      code: z.string().optional().describe("Custom Playwright test code. Must define an async function test({ page, step, log, secrets }). Omit if using template_id."),
+      secrets: z.record(z.string()).optional().describe("Optional key-value secrets (e.g. { email: '...', password: '...' } or { api_key: '...' }). Encrypted at rest, never returned in API responses."),
+      headers: z.record(z.string()).optional().describe("Optional HTTP headers injected into requests to the target domain (e.g. { 'X-Test-Secret': 'abc' })"),
     },
   },
-  async ({ name, url, template_id, params, code }) => {
+  async ({ name, url, template_id, params, code, secrets, headers }) => {
     try {
       const body = { name, url };
       if (template_id) body.template_id = template_id;
       if (params) body.params = params;
       if (code) body.code = code;
+      if (secrets) body.secrets = secrets;
+      if (headers) body.headers = headers;
       const test = await apiPost("/api/tests/create", body);
       return { content: [{ type: "text", text: JSON.stringify(test, null, 2) }] };
     } catch (err) {
@@ -220,6 +227,7 @@ server.registerTool(
   "screenshot_url",
   {
     description: "Take a screenshot of a URL and extract page structure (links, buttons, inputs, headings with selectors). Use this BEFORE writing custom test code to see the page layout and discover available selectors.",
+    readOnlyHint: true,
     inputSchema: {
       url: z.string().describe("The URL to screenshot (e.g. 'https://example.com')"),
     },
@@ -280,6 +288,7 @@ server.registerTool(
   "validate_test",
   {
     description: "Dry-run custom Playwright test code against a URL. Returns execution results, screenshots, and page structure for debugging. Steps continue even on failure to maximize debug signal. Use this to iterate on code before calling create_test.",
+    readOnlyHint: true,
     inputSchema: {
       code: z.string().describe("Custom Playwright test code. Must define an async function test({ page, step, log })."),
       url: z.string().describe("The target URL to test against (e.g. 'https://example.com')"),
@@ -349,6 +358,7 @@ server.registerTool(
   "list_tests",
   {
     description: "List all saved tests for the current organization. Returns id, name, url, template_id, status, and last_run summary (id, status, completed_at). This is the best starting point when checking if a feature or site is working — find the relevant test, then use get_test_results to see details.",
+    readOnlyHint: true,
   },
   async () => {
     try {
@@ -364,6 +374,7 @@ server.registerTool(
   "get_test",
   {
     description: "Get full details of a test by ID, including code for custom tests. Use list_tests to find the test ID first.",
+    readOnlyHint: true,
     inputSchema: {
       test_id: z.coerce.number().describe("The test ID (from list_tests or create_test)"),
     },
@@ -382,6 +393,7 @@ server.registerTool(
   "update_test",
   {
     description: "Update an existing test's name, URL, code, or other properties. Only provided fields are changed.",
+    destructiveHint: true,
     inputSchema: {
       test_id: z.coerce.number().describe("The test ID to update (from list_tests or get_test)"),
       name: z.string().optional().describe("New test name"),
@@ -389,9 +401,11 @@ server.registerTool(
       code: z.string().optional().describe("Updated custom Playwright test code"),
       template_id: z.string().optional().describe("Updated template ID"),
       params: z.record(z.string()).optional().describe("Updated template parameters"),
+      secrets: z.record(z.string()).nullable().optional().describe("Updated secrets (pass null to clear)"),
+      headers: z.record(z.string()).nullable().optional().describe("Updated HTTP headers (pass null to clear)"),
     },
   },
-  async ({ test_id, name, url, code, template_id, params }) => {
+  async ({ test_id, name, url, code, template_id, params, secrets, headers }) => {
     try {
       const body = {};
       if (name !== undefined) body.name = name;
@@ -399,6 +413,8 @@ server.registerTool(
       if (code !== undefined) body.code = code;
       if (template_id !== undefined) body.template_id = template_id;
       if (params !== undefined) body.params = params;
+      if (secrets !== undefined) body.secrets = secrets;
+      if (headers !== undefined) body.headers = headers;
       const test = await apiPatch(`/api/tests/${test_id}`, body);
       return { content: [{ type: "text", text: JSON.stringify(test, null, 2) }] };
     } catch (err) {
@@ -411,6 +427,7 @@ server.registerTool(
   "delete_test",
   {
     description: "Permanently delete a test and its associated schedules. IMPORTANT: Always call this first WITHOUT confirm to see what will be deleted, show that to the user, and only call again with confirm=true after the user explicitly agrees.",
+    destructiveHint: true,
     inputSchema: {
       test_id: z.coerce.number().describe("The test ID to delete (from list_tests)"),
       confirm: z.boolean().optional().describe("Set to true to actually delete. Omit or false to preview what will be deleted."),
@@ -461,16 +478,18 @@ server.registerTool(
   "run_test",
   {
     description: "Run a saved test by ID. Waits for the test to finish and returns full results with step details.",
+    destructiveHint: true,
     inputSchema: {
       test_id: z.coerce.number().describe("The test ID to run (from create_test or list_tests)"),
     },
   },
   async ({ test_id }) => {
     try {
+      const test = await apiGet(`/api/tests/${test_id}`);
       const { test_run_id } = await apiPost(`/api/tests/${test_id}/run`, {});
       console.error(`Started test run ${test_run_id} for test ${test_id}`);
       const testRun = await pollTestRun(test_run_id);
-      const text = buildTestRunText(testRun);
+      const text = buildTestRunText(testRun, test.name);
       return { content: [{ type: "text", text }] };
     } catch (err) {
       return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
@@ -482,6 +501,7 @@ server.registerTool(
   "get_test_screenshots",
   {
     description: "Get screenshots from a test run. Returns only images. Use after run_test or get_test_results to view screenshots.",
+    readOnlyHint: true,
     inputSchema: {
       test_run_id: z.coerce.number().describe("The test run ID (from run_test or get_test_results)"),
     },
@@ -507,6 +527,7 @@ server.registerTool(
   "schedule_test",
   {
     description: "Create a recurring schedule for a saved test. The test will run automatically at the specified interval.",
+    destructiveHint: true,
     inputSchema: {
       test_id: z.coerce.number().describe("The test ID to schedule (from create_test or list_tests)"),
       interval: z.enum(["every_minute", "hourly", "every_6_hours", "every_12_hours", "daily", "weekly"])
@@ -534,6 +555,7 @@ server.registerTool(
   "list_schedules",
   {
     description: "List all test schedules for the current organization, including last run status and next run time.",
+    readOnlyHint: true,
   },
   async () => {
     try {
@@ -563,6 +585,7 @@ server.registerTool(
   "update_schedule",
   {
     description: "Pause or resume a test schedule.",
+    destructiveHint: true,
     inputSchema: {
       schedule_id: z.coerce.number().describe("The schedule ID (from list_schedules)"),
       enabled: z.boolean().describe("true to resume, false to pause"),
@@ -588,6 +611,7 @@ server.registerTool(
   "delete_schedule",
   {
     description: "Permanently delete a test schedule. Historical run results are preserved.",
+    destructiveHint: true,
     inputSchema: {
       schedule_id: z.coerce.number().describe("The schedule ID to delete (from list_schedules)"),
     },
@@ -606,6 +630,7 @@ server.registerTool(
   "get_test_results",
   {
     description: "Get recent test run results with step-by-step details. Use this to answer questions like 'is X working?' — filter by test_id to see the latest runs for a specific test. Shows status, timing, step pass/fail, errors, and screenshot links.",
+    readOnlyHint: true,
     inputSchema: {
       test_id: z.coerce.number().optional().describe("Filter by test ID (optional — omit to see all runs)"),
       limit: z.coerce.number().optional().describe("Max results to return (default: 10)"),
@@ -620,9 +645,18 @@ server.registerTool(
       if (!data.test_runs.length) {
         return { content: [{ type: "text", text: "No test runs found." }] };
       }
+
+      // Build test name map
+      const testIds = [...new Set(data.test_runs.map((r) => r.test_id))];
+      const nameMap = {};
+      const testsData = await apiGet("/api/tests/list");
+      for (const t of testsData.tests) {
+        if (testIds.includes(t.id)) nameMap[t.id] = t.name;
+      }
+
       const lines = [];
       for (const run of data.test_runs) {
-        lines.push(buildTestRunText(run));
+        lines.push(buildTestRunText(run, nameMap[run.test_id]));
         lines.push("");
       }
       return { content: [{ type: "text", text: lines.join("\n") }] };
@@ -638,6 +672,7 @@ server.registerTool(
   "add_notification_channel",
   {
     description: "Add a notification channel to receive alerts when scheduled tests fail. Supports email, Telegram, and Slack. For Telegram, get a chat ID from https://t.me/userinfobot. For Slack, create an Incoming Webhook in your Slack workspace settings.",
+    destructiveHint: true,
     inputSchema: {
       channel_type: z.enum(["email", "telegram", "slack"]).describe("The notification channel type"),
       email_address: z.string().optional().describe("Email address for email channels (required when channel_type is email)"),
@@ -696,6 +731,7 @@ server.registerTool(
   "list_notification_channels",
   {
     description: "List all notification channels configured for the current organization.",
+    readOnlyHint: true,
   },
   async () => {
     try {
@@ -727,6 +763,7 @@ server.registerTool(
   "remove_notification_channel",
   {
     description: "Remove a notification channel. Use list_notification_channels to find the channel ID.",
+    destructiveHint: true,
     inputSchema: {
       channel_id: z.coerce.number().describe("The channel ID to remove (from list_notification_channels)"),
     },
@@ -745,6 +782,7 @@ server.registerTool(
   "test_notification_channel",
   {
     description: "Send a test notification to verify a channel is working correctly.",
+    destructiveHint: true,
     inputSchema: {
       channel_id: z.coerce.number().describe("The channel ID to test (from list_notification_channels)"),
     },
@@ -759,6 +797,38 @@ server.registerTool(
   }
 );
 
+server.registerTool(
+  "get_org_secret",
+  {
+    description: "Get the org's X-AskQA-Secret header value. This token is automatically sent with every test request so your backend can detect monitoring traffic and enable test mode (e.g. Stripe sandbox).",
+    readOnlyHint: true,
+  },
+  async () => {
+    try {
+      const data = await apiGet("/api/org/secret");
+      return { content: [{ type: "text", text: `Your X-AskQA-Secret header value: ${data.askqa_secret}\n\nThis is sent automatically with every test request to your target domain. Configure your backend to check for this header to enable test mode.` }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+server.registerTool(
+  "rotate_org_secret",
+  {
+    description: "Generate a new X-AskQA-Secret header value. The old value will stop working immediately — update your backend configuration.",
+    destructiveHint: true,
+  },
+  async () => {
+    try {
+      const data = await apiPost("/api/org/secret/rotate", {});
+      return { content: [{ type: "text", text: `New X-AskQA-Secret header value: ${data.askqa_secret}\n\nUpdate your backend configuration to use this new value. The old value 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");

package/skills/setup-mcp/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: setup-mcp
+description: Configure AskQA MCP server with API key
+---
+
+# Set Up AskQA MCP Server
+
+Use this skill to automatically configure the AskQA MCP server in your Claude settings.
+
+## Step 1: Get API Key
+
+Ask the user if they already have an AskQA API key. If not, direct them to:
+- Sign up at https://askqa.ai
+- Get their API key from https://askqa.ai/account
+
+Once they have the key, ask them to provide it.
+
+## Step 2: Detect Environment
+
+Check if the user is in a git repository by looking for a `.git` directory in the current working directory or parent directories.
+
+Use the Bash tool:
+```bash
+git rev-parse --git-dir 2>/dev/null
+```
+
+If this succeeds, we're in a git repo. If it fails, we're in Desktop/global mode.
+
+## Step 3: Determine Config Location
+
+**If in a git repository:**
+- Config location: `.mcp.json` in the project root (project-specific)
+- This configuration will only apply when working in this repository
+
+**If not in a git repository (Desktop mode):**
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+- This configuration will apply globally for the user
+
+Tell the user which location will be used.
+
+## Step 4: Read Existing Config
+
+Use the Read tool to check if the config file exists and read its contents.
+
+If the file doesn't exist, start with an empty config:
+```json
+{
+  "mcpServers": {}
+}
+```
+
+If the file exists, parse it as JSON.
+
+## Step 5: Update Config
+
+Add or update the `askqa` MCP server entry:
+
+```json
+{
+  "mcpServers": {
+    "askqa": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/askqa/server.js"],
+      "env": {
+        "AUTOQA_API_URL": "https://api.askqa.ai",
+        "AUTOQA_API_KEY": "aq_..."
+      }
+    }
+  }
+}
+```
+
+**Important notes:**
+- Use `${CLAUDE_PLUGIN_ROOT}` variable - it resolves to the plugin installation directory
+- Replace `"aq_..."` with the actual API key the user provided
+- Preserve any other MCP servers already configured
+- If `askqa` already exists, update it with the new API key
+
+## Step 6: Write Config
+
+Use the Write tool to save the updated config back to the file.
+
+**For project config (`.mcp.json`):**
+- Write the config file to the project root
+
+**For Desktop config:**
+- Write directly to the Desktop config file location
+
+## Step 7: Confirm
+
+After writing the config, confirm with the user:
+
+**If project config:**
+```
+✓ AskQA MCP server configured in .mcp.json
+
+The MCP server is now available in this repository. Restart Claude Code to load it.
+
+Try these commands:
+- list_tests - List your saved tests
+- create_test - Create a new test
+```
+
+**If Desktop config:**
+```
+✓ AskQA MCP server configured globally
+
+The MCP server is now available in Claude Desktop. Restart Claude Desktop to load it.
+
+You can now use AskQA tools in any conversation.
+```
+
+## Error Handling
+
+If any step fails:
+- **Permission error**: Tell user they may need to run with appropriate permissions
+- **Invalid API key format**: Check that it starts with `aq_`
+- **Invalid JSON**: If existing config is malformed, warn user and ask if they want to replace it
+
+## Additional Tips
+
+After successful setup, remind the user:
+- They can verify the setup by restarting and running `list_tests`
+- They can update the API key anytime by running this skill again
+- Project configs (`.mcp.json`) can be committed to git for team sharing (but shouldn't include the API key - use environment variables instead for team setups)

package/skills/setup-slack/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: setup-slack
+description: Configure Slack notifications for AskQA test failures
+---
+
 # Set Up Slack Notifications
 
 Use this skill to configure Slack notifications for AskQA test failures. When a scheduled test fails, AskQA will post a message to your Slack channel with the test name, failed steps, and a link to the full results.

package/skills/shopify-add-to-cart/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: shopify-add-to-cart
+description: Set up automated monitoring for a Shopify store's add-to-cart flow
+---
+
 # Monitor Shopify Add to Cart
 
 Use this skill to set up automated monitoring for a Shopify store's add-to-cart flow. When the button breaks — due to an app update, theme change, or platform rollout — AskQA catches it within minutes and sends an alert with a screenshot.