qiksy-mcp 1.0.6 → 1.0.7

package/README.md

@@ -114,7 +114,7 @@ Playwright MCP drives a browser over the **Chrome DevTools Protocol** — a *nor
    # Windows:  "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
    # Linux:    google-chrome --remote-debugging-port=9222
    ```
-2. **In the Qiksy popup** → *MCP bridge*: **On**, **Generate** a token, **Save**.
+2. **In the Qiksy popup** → *Agent bridge*: **On**, **Generate** a token (it saves as you go), then **📋 Copy agent config**.
 3. **Register both MCP servers** in your agent — one config, paste and go. Claude Code `.mcp.json` (project root):
    ```json
    {
@@ -143,11 +143,37 @@ Qiksy runs several logins on one domain at once — one per tab, each with its o
 
 ## Setup
 
-1. **In the extension popup** → *MCP bridge*: toggle **On**, click **Generate** for a token, pick a port (default `7333`), **Save bridge**.
-2. **Register the server in your agent** (below), using the **same token and port**. The token is passed via the `QIKSY_MCP_TOKEN` env var.
+1. **In the extension popup** → *Agent bridge*: toggle **On**, click **Generate** for a token, keep the default port `7333` (or pick your own). It **saves as you go** — there is no separate Save step.
+2. **Click 📋 Copy agent config** in the popup — it copies the whole `mcpServers` block below with **your port and token already filled in** — and paste it into your agent's MCP config file (below). No hand-editing the token or port.
+3. **Watch the status line** under the toggle. 🟡 *Waiting…* until your agent's `qiksy-mcp` is up, then 🟢 *Agent connected on port 7333*. If it stays yellow or turns red, see [Connection status & troubleshooting](#connection-status--troubleshooting).
 
 The token is the only thing guarding the bridge — localhost is reachable by any local process/page, so keep it secret and unique.
 
+### Connection status & troubleshooting
+
+The popup shows the live link state, so you fix the right thing instead of guessing:
+
+| Status | Means | Fix |
+|--------|-------|-----|
+| 🟢 **Agent connected** | Socket open on that port, token matched. | Nothing — you're live. |
+| 🟡 **Waiting for the agent** | Bridge on, but nothing answering on that port. | Start your agent so `qiksy-mcp` runs, and make sure **its `--port` matches the popup's port**. The #1 snag: docs pin `7333` but the agent was launched on a different port — the numbers must match. |
+| 🔴 **Token rejected** | Something answered, but the shared secret didn't match. | The popup token and the agent's `QIKSY_MCP_TOKEN` must be identical. Re-copy with **📋 Copy agent config** and repaste. |
+| 🔴 **Another browser took over** | A second browser connected on the same port+token and claimed the slot. | Expected when switching browsers. To run **both at once**, give each its own port (see below). To reclaim, toggle the bridge **off then on**. |
+| 🔴 **Qiksy Pro required** | Trial ended; the bridge is a Pro surface. | Activate a license key in the popup. |
+
+### Two browsers at once
+
+One bridge is **one port + one token = one browser**. Pointing a second browser at the **same** port+token doesn't double up — it **takes over the slot** (last writer wins), and the first browser's status flips to *Another browser took over*. That's exactly how you **switch** between browsers. To run **both simultaneously**, give each its own port and register a second server name:
+
+```json
+{ "mcpServers": {
+  "qiksy":   { "command": "npx", "args": ["qiksy-mcp", "--port", "7333"], "env": { "QIKSY_MCP_TOKEN": "TOKEN_A" } },
+  "qiksy-2": { "command": "npx", "args": ["qiksy-mcp", "--port", "7334"], "env": { "QIKSY_MCP_TOKEN": "TOKEN_B" } }
+} }
+```
+
+Set browser A's popup to `7333`/`TOKEN_A` and browser B's to `7334`/`TOKEN_B`. One agent drives one browser per bridge — a single bridge can't fan out to two browsers; different ports are independent links that never fight over the slot.
+
 ### Claude Code
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qiksy-mcp",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "MCP bridge for the Qiksy browser extension — expose live QA findings, forms, network and session to any MCP-capable coding agent.",
   "type": "module",
   "bin": {

package/server.mjs

@@ -31,6 +31,76 @@ import { fileURLToPath } from 'node:url';
 
 const log = (...a) => console.error('[qiksy-mcp]', ...a);
 
+// A little IT/QA humour in the STDERR log (never in tool results — the agent parses
+// those). It rides the connect line and each action, to make a testing session a bit
+// more fun. Set QIKSY_MCP_QUIPS=0 to keep the log strictly business (CI, demos).
+const QUIPS_ON = process.env.QIKSY_MCP_QUIPS !== '0';
+const QUIPS = [
+  'it works on my machine ✨',
+  "it's not a bug, it's a feature",
+  'no bugs — only undocumented features',
+  'have you tried turning it off and on again?',
+  'shipping it 🚀',
+  'passed on the third retry 🟢',
+  'flaky test? must be the network',
+  'reproduced locally, naturally',
+  'works 60% of the time, every time',
+  "trust me, I'm a QA engineer",
+  '0 bugs found (that we know of)',
+  'definitely tested in production',
+  'green tests, clear conscience',
+  'clicking so you don\'t have to',
+  'one does not simply skip QA',
+  'red, green, refactor, repeat',
+  'escalating to the rubber duck 🦆',
+  'edge case #418: I\'m a teapot',
+  'the build is fine, it\'s the vibes that are off',
+  'QA: because prod is not a test environment',
+];
+let lastQuip = -1;
+function quip() {
+  if (!QUIPS_ON) return '';
+  let i;
+  do {
+    i = Math.floor(Math.random() * QUIPS.length);
+  } while (QUIPS.length > 1 && i === lastQuip);
+  lastQuip = i;
+  return QUIPS[i];
+}
+
+// Little ASCII faces / kaomoji to ride along with the quips — sticks, circles, meme
+// faces. Same QIKSY_MCP_QUIPS gate.
+const FACES = [
+  '¯\\_(ツ)_/¯',
+  '(⌐■_■)',
+  '( •_•)>⌐■-■',
+  'ᕕ( ᐛ )ᕗ',
+  '(づ｡◕‿‿◕｡)づ',
+  'ヽ(´▽`)/',
+  '(ノ◕ヮ◕)ノ*:･ﾟ✧',
+  '◉_◉',
+  '(•_•)',
+  '༼ つ ◕_◕ ༽つ',
+  '~(˘▾˘~)',
+  '(☞ﾟヮﾟ)☞',
+  '[▰▰▰▱▱]',
+  'ᕦ(ò_óˇ)ᕤ',
+  '(◕‿◕)',
+];
+// A happier subset for the connect banner (no table-flips when things just worked).
+const HAPPY = ['\\(^o^)/', 'ヽ(´▽`)/', '(ノ◕ヮ◕)ノ*:･ﾟ✧', 'ᕕ( ᐛ )ᕗ', '(づ｡◕‿‿◕｡)づ', '~(˘▾˘~)'];
+let lastFace = -1;
+function face(happy = false) {
+  if (!QUIPS_ON) return '';
+  const pool = happy ? HAPPY : FACES;
+  let i;
+  do {
+    i = Math.floor(Math.random() * pool.length);
+  } while (pool.length > 1 && i === lastFace);
+  lastFace = i;
+  return pool[i];
+}
+
 // Read the version off package.json rather than repeating it here — a hardcoded
 // copy silently rots, and this one is what every MCP client displays.
 const VERSION = (() => {
@@ -110,9 +180,22 @@ wss.on('connection', (ws, req) => {
       }
       authed = true;
       lapsed = false;
+      // Last-writer-wins, but EXPLICITLY. If another browser already holds the one
+      // client slot, close it with a distinct code (4004) instead of silently
+      // orphaning it — so its extension can say "another browser took over" rather
+      // than going dark, and (crucially) so it YIELDS instead of instantly
+      // reconnecting and starting a slot-stealing war. Two browsers at once = two
+      // bridge instances on two ports, not one shared slot.
+      if (client && client !== ws && client.readyState === WebSocket.OPEN) {
+        try {
+          client.close(4004, 'replaced by a newer connection');
+        } catch {
+          /* already gone */
+        }
+      }
       client = ws;
       ws.send(JSON.stringify({ t: 'welcome', v: PROTOCOL_VERSION }));
-      log('extension connected');
+      log(QUIPS_ON ? `${face(true)}  extension connected — ${quip()}` : 'extension connected');
       return;
     }
     if (msg.t === 'ping') {
@@ -157,6 +240,7 @@ function callExtension(tool, args, timeoutMs = 15_000) {
       reject(new Error(`Timed out after ${timeoutMs}ms waiting for "${tool}". Is a normal web page focused in Chrome?`));
     }, timeoutMs);
     pending.set(id, { resolve, reject, timer });
+    if (QUIPS_ON) log(`▸ ${tool}  ${face()}  ${quip()}`);
     client.send(JSON.stringify({ t: 'req', id, tool, args: args || {} }));
   });
 }
@@ -277,6 +361,26 @@ server.registerTool(
   },
 );
 
+server.registerTool(
+  'qa_snapshot',
+  {
+    title: 'Full page snapshot (accessibility tree)',
+    description:
+      'A compact accessibility / interaction snapshot of the WHOLE page: every interactive control, landmark and heading with a role, an accessible name, its state, and a STABLE ref like [ref=e12]. ' +
+      'Unlike qa_export — which lists only the FORM fields Qiksy detects and can miss inputs, file uploads, date pickers, selects and buttons — this "sees everything". ' +
+      'Pass a ref straight back to qa_click / qa_type / qa_spotlight: a ref is unique and unambiguous, so it works where a CSS selector is duplicated across fields. ' +
+      'Built in the live, already-authenticated page in ~milliseconds — no browser launch, no CDP. Re-run it after the page changes to refresh the refs (a ref goes stale when its element is re-rendered).',
+    inputSchema: { tabId: tabIdArg },
+  },
+  async ({ tabId }) => {
+    try {
+      return asText(await callExtension('qa_snapshot', { tabId }, 30_000));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
 server.registerTool(
   'qa_tour',
   {
@@ -340,16 +444,17 @@ server.registerTool(
   {
     title: 'Spotlight an element',
     description:
-      'Visually highlight (dim + outline) an element on the page by CSS selector, so the human tester can see what the agent is referring to. A non-destructive overlay — it does not click, focus, or modify the element.',
+      'Visually highlight (dim + outline) an element on the page — target it by a qa_snapshot ref (preferred) or a CSS selector — so the human tester can see what the agent is referring to. A non-destructive overlay — it does not click, focus, or modify the element.',
     inputSchema: {
       tabId: tabIdArg,
-      selector: z.string().describe('CSS selector of the element to spotlight'),
+      selector: z.string().optional().describe('CSS selector of the element to spotlight'),
+      ref: z.string().optional().describe('A ref from qa_snapshot (e.g. "e12") — preferred over selector'),
       label: z.string().optional().describe('Optional caption shown on the highlight'),
     },
   },
-  async ({ tabId, selector, label }) => {
+  async ({ tabId, selector, ref, label }) => {
     try {
-      return asText(await callExtension('qa_spotlight', { tabId, selector, label }));
+      return asText(await callExtension('qa_spotlight', { tabId, selector, ref, label }));
     } catch (e) {
       return asError(e);
     }
@@ -375,16 +480,17 @@ server.registerTool(
   {
     title: 'Click an element (Pro)',
     description:
-      'Click an element on the page under test by CSS selector. Sends the full pointer sequence (pointerdown → mouseup → click), so component libraries that listen for pointerdown — Radix, shadcn, MUI — react to it like a real click. Scrolls the element into view first, and refuses a selector that matches nothing or has zero size rather than silently doing nothing.' +
+      'Click an element on the page under test, by a qa_snapshot ref (preferred) or a CSS selector. Sends the full pointer sequence (pointerdown → mouseup → click), so component libraries that listen for pointerdown — Radix, shadcn, MUI — react to it like a real click. Scrolls the element into view first, and refuses a target that matches nothing or has zero size rather than silently doing nothing.' +
       DRIVE_NOTE,
     inputSchema: {
       tabId: tabIdArg,
-      selector: z.string().describe('CSS selector of the element to click'),
+      selector: z.string().optional().describe('CSS selector of the element to click'),
+      ref: z.string().optional().describe('A ref from qa_snapshot (e.g. "e12") — preferred over selector; unique where a selector is ambiguous'),
     },
   },
-  async ({ tabId, selector }) => {
+  async ({ tabId, selector, ref }) => {
     try {
-      return asText(await callExtension('qa_click', { tabId, selector }));
+      return asText(await callExtension('qa_click', { tabId, selector, ref }));
     } catch (e) {
       return asError(e);
     }
@@ -396,17 +502,47 @@ server.registerTool(
   {
     title: 'Type into a field (Pro)',
     description:
-      'Set the value of an input, textarea or contenteditable by CSS selector. Uses the native value setter plus InputEvent, so React/Vue controlled inputs actually keep the value — a plain assignment is swallowed by them. Reports back whether the value stuck, so a masked or read-only field is visible to you rather than silently ignored.' +
+      'Set the value of an input, textarea, select or contenteditable — target it by a qa_snapshot ref (preferred) or a CSS selector. Uses the native value setter plus InputEvent, so React/Vue controlled inputs actually keep the value — a plain assignment is swallowed by them. For a <select>, matches your text against the option labels. Reports back whether the value stuck, so a masked or read-only field is visible to you rather than silently ignored.' +
       DRIVE_NOTE,
     inputSchema: {
       tabId: tabIdArg,
-      selector: z.string().describe('CSS selector of the field'),
+      selector: z.string().optional().describe('CSS selector of the field'),
+      ref: z.string().optional().describe('A ref from qa_snapshot (e.g. "e12") — preferred over selector; unique where a selector is ambiguous'),
       value: z.string().describe('Text to put in the field'),
     },
   },
-  async ({ tabId, selector, value }) => {
+  async ({ tabId, selector, ref, value }) => {
+    try {
+      return asText(await callExtension('qa_type', { tabId, selector, ref, value }));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+server.registerTool(
+  'qa_type_many',
+  {
+    title: 'Fill many fields at once (Pro)',
+    description:
+      'Fill a WHOLE form in ONE call instead of a round-trip per field: pass an array of { selector, value, action? }. `action` defaults to "type" (which also handles <select>, checkbox and radio from the value), or "click" for buttons / toggles. Returns a per-field result list plus filled/total — far faster than one qa_type per field on a big form.' +
+      DRIVE_NOTE,
+    inputSchema: {
+      tabId: tabIdArg,
+      fields: z
+        .array(
+          z.object({
+            selector: z.string().describe('CSS selector of the field'),
+            value: z.string().optional().describe('Value to set (text input / <select> / checkbox / radio)'),
+            action: z.enum(['type', 'click']).optional().describe('Default "type"; use "click" for buttons and toggles'),
+          }),
+        )
+        .describe('The fields to fill, in order'),
+    },
+  },
+  async ({ tabId, fields }) => {
     try {
-      return asText(await callExtension('qa_type', { tabId, selector, value }));
+      return asText(await callExtension('qa_type_many', { tabId, fields }, 45_000));
     } catch (e) {
       return asError(e);
     }
@@ -423,12 +559,13 @@ server.registerTool(
     inputSchema: {
       tabId: tabIdArg,
       key: z.string().describe('Key value, e.g. "Enter", "Escape", "Tab", "a"'),
-      selector: z.string().optional().describe('Optional target; defaults to the focused element'),
+      selector: z.string().optional().describe('Optional target (CSS); defaults to the focused element'),
+      ref: z.string().optional().describe('Optional target (a qa_snapshot ref); defaults to the focused element'),
     },
   },
-  async ({ tabId, key, selector }) => {
+  async ({ tabId, key, selector, ref }) => {
     try {
-      return asText(await callExtension('qa_press', { tabId, key, selector }));
+      return asText(await callExtension('qa_press', { tabId, key, selector, ref }));
     } catch (e) {
       return asError(e);
     }