qiksy-mcp 1.43.0 → 1.45.0

package/README.md

@@ -22,7 +22,7 @@ unless the licence (or the 28-day trial) is valid, so once a trial lapses *every
 tool fails — `qa_export` included — with a message saying so. Do not plan a
 free-tier integration around read-only tools.
 
-**npm carries `qiksy-mcp@1.43.0`** — the current build, with all sixty-two tools
+**npm carries `qiksy-mcp@1.44.0`** — the current build, with all sixty-two tools
 including a filterable full-page `qa_snapshot`, `qa_fill_json` (a whole wizard step —
 custom dropdowns, calendars, cascaders, trees, tags and time included — in one call),
 the `qa_pick_*` verbs for the composites, `qa_probe` for the one control that refuses,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qiksy-mcp",
-  "version": "1.43.0",
+  "version": "1.45.0",
   "description": "Browser MCP server for the Chrome tab you already have open — your session, your logins. Gives Claude Code, Cursor, Codex and VS Code the live page: findings, forms, failed requests with server bodies.",
   "keywords": [
     "mcp",

package/server.mjs

@@ -825,6 +825,48 @@ if (process.argv[2] === 'connect') {
   await runConnect(process.argv.slice(3));
   process.exit(0);
 }
+if (process.argv[2] === 'done') {
+  /**
+   * «THE RUN IS OVER» FROM OUTSIDE THE MODEL — for any agent whose client can run a command when
+   * it finishes a turn (Claude Code's Stop hook, and the equivalent in the others).
+   *
+   * The verb `qa_done` is the ordinary route and every MCP client is told about it in the
+   * instructions. This is the route that does not depend on a model remembering: a hook fires
+   * whether or not the agent thought to say anything, so the person in the next room hears the
+   * end of the run either way.
+   *
+   *   npx qiksy-mcp done            → the run ended well
+   *   npx qiksy-mcp done --problem  → it ended badly
+   *
+   * It joins the bridge the SAME WAY a sibling agent window does, as a follower of whoever owns
+   * the port — so it never takes the port, never disturbs a running session, and costs one
+   * socket for under a second. If nothing is listening it says so and exits 0: a hook that fails
+   * loudly because the browser is closed would be a hook people remove.
+   */
+  const bad = process.argv.includes('--problem');
+  const said = await new Promise((res) => {
+    let ws;
+    const give = (msg) => { try { ws?.close(); } catch { /* already gone */ } res(msg); };
+    const timer = setTimeout(() => give('no answer from the bridge'), 6000);
+    try {
+      ws = new WebSocket(`ws://${HOST}:${PORT}`);
+    } catch {
+      clearTimeout(timer);
+      return res('could not reach the bridge');
+    }
+    ws.on('open', () => ws.send(JSON.stringify({ t: 'join', v: PROTOCOL_VERSION, token: TOKEN, pid: process.pid })));
+    ws.on('message', (raw) => {
+      let m;
+      try { m = JSON.parse(raw.toString()); } catch { return; }
+      if (m.t === 'welcome') return ws.send(JSON.stringify({ t: 'req', id: 'done', tool: 'qa_done', args: { verdict: bad ? 'problem' : 'ok' }, timeoutMs: 5000 }));
+      if (m.t === 'res') { clearTimeout(timer); give(m.result?.soundNote || m.error || 'done'); }
+    });
+    ws.on('error', () => { clearTimeout(timer); give('no bridge on this port'); });
+    ws.on('close', () => { clearTimeout(timer); give('the bridge closed the connection'); });
+  });
+  log(said);
+  process.exit(0);
+}
 
 if (!TOKEN) {
   log('WARNING: QIKSY_MCP_TOKEN is not set. Set the same token here and in the Qiksy popup, or connections are refused.');
@@ -4344,6 +4386,16 @@ that rides with it: re-say it in that language rather than translating it word f
 the tone it names. It is rate-limited, so it will not become a tic. QIKSY_MCP_VOICE=nice softens
 it, =off removes it.
 
+SAY WHEN YOU HAVE FINISHED — qa_done, one call, at the end of the run. The person who set you off
+is usually not watching: they are in another window, another screen, another room. That call makes
+the mark on every driven tab they are NOT looking at pulse slowly, and plays a short sound, so the
+end of the work reaches them where they actually are. It stops by itself the moment they look at
+one of those tabs; there is nothing for them to dismiss.
+It is the END, not a progress beat. A full stop after nothing happened is refused and says so, and
+a second one within half a minute stays silent — both on purpose, because a signal that cries wolf
+is one people switch off in a week. Call it once, when the work is actually over, and still write
+what you did in your own words: this is a nudge towards the screen, never the report itself.
+
 Two failures are NOT yours to fix, and each names its own cause: "extension is not connected"
 means the MCP bridge toggle in the popup is off (or its token/port differ) — only the user can
 turn it on. "Port … is held by a process that is not a Qiksy bridge" means something else owns
@@ -4601,7 +4653,9 @@ server.registerTool(
     description:
       'ADD MARKS TO A SHOT ON THE SHELF. They are stored beside the clean image, never burned into it, so the tester can move them, resize them and delete them afterwards — and so you can read them back later. ' +
       'Coordinates are in IMAGE pixels; qa_screenshot returns a map of the page in exactly those pixels, so a box from the map can be passed straight through. ' +
-      'Shapes: `box` round a region, `arrow` from one point to another, `text` for a caption with its own words. Weight is `k`; colour is one of the five the panel offers. ' +
+      'Shapes: `box` round a region, `arrow` from one point to another, `text` for a caption with its own words, `blur` for a pane that makes what is under it unreadable. Weight is `k`; colour is one of the five the panel offers. ' +
+      'A caption carries an optional `to` — the point it is ABOUT — and a leader line is then drawn from the plate to that point, in both the editor and the exported file. Give a box a caption with `to` set to the middle of that box and you get the callout a person would draw by hand; the tester can then drag the words anywhere and the line follows. ' +
+      'A `blur` pane hides an address, a customer name or a staging token. It is applied when the picture is EXPORTED, copied or built into a report — the clean shot stays clean on the shelf, which is what lets the pane be moved and removed afterwards. ' +
       'Adds by default; pass `replace: true` to put your marks in place of everything on the picture — which is the destructive one, and it is opt-in for that reason. ' +
       'The reply is the STATE — how many marks the picture now carries and all of them in full — rather than the word «done».',
     inputSchema: {
@@ -4627,6 +4681,15 @@ server.registerTool(
               x: z.number(), y: z.number(),
               s: z.string().describe('The caption itself'),
               c: z.string(), k: z.number().optional().describe('Type size, 8–96'),
+              to: z
+                .object({ x: z.number(), y: z.number() })
+                .optional()
+                .describe('The point this caption is about — a leader line is drawn from the plate to it, and it follows the words if the tester moves them'),
+            }),
+            z.object({
+              t: z.literal('blur'),
+              x: z.number(), y: z.number(), w: z.number(), h: z.number(),
+              k: z.number().optional().describe('How hard it hides, 4–60 (default 14). No colour: a pane is not a remark about the page, it is a piece of the page taken away.'),
             }),
           ]),
         )
@@ -4731,19 +4794,30 @@ server.registerTool(
     title: 'Assemble a report by naming blocks — no template, no markup',
     description:
       'A SELF-CONTAINED HTML REPORT, built by ENUMERATION. You pass an ordered list of blocks with plain text fields; every scrap of markup, styling, escaping and picture-embedding happens on our side. No template is accepted and none can be — a verb here names an element or a value from a closed list, never a program. ' +
+      'IT IS NOT ONLY A BUG REPORT, and the block set is what makes that true. `finding` says something is wrong; `point` makes the same card with a tone of good · info · warn · bad and NO «expected» line, which is how a check that passed, a design note or a description of how a screen behaves gets written down; `section` gives a long document headings. A sign-off, a walkthrough for a developer, a page of observations for a designer and a defect list are the same paper here. ' +
       'Pictures come from the shelf BY NAME and are flattened on the way in: the marks and the crop have been data up to that moment precisely so they could still be changed. ' +
       'Print the result to get a PDF — the stylesheet is written for paper as well as for screen. ' +
+      'PASS `save` TO KEEP IT IN THE EXTENSION: the panel’s Shots tab then lists it under Reports with Open and Save, and qa_reports / qa_report_get read it back by name later. Without it the document exists only in this reply and in whatever file you write. ' +
       'IT REFUSES, and the refusals are the point. No blocks, a block naming a shot that is not on the shelf, or NOT ONE PICTURE anywhere in the document — each fails the whole build rather than quietly dropping a block: a page of assertions about an application with nothing showing any of it is the artefact this product exists to replace. ' +
       'EXPECTED IS NEVER INVENTED. Leave `expected` out and the field says «not stated — a person fills this in». Filling it from your own guess turns a report into a hypothesis wearing the clothes of a protocol. ' +
-      'The reply is an INVENTORY — blocks, pictures embedded, findings, bytes, warnings — not the word «done».',
+      'The reply is an INVENTORY — blocks, pictures embedded, findings, points, bytes, warnings — not the word «done».',
     inputSchema: {
       tabId: tabIdArg,
       out: z.string().optional().describe('Write the HTML here. Without it the document comes back inline, which for a report with pictures in it is usually the wrong trade.'),
+      save: z
+        .union([z.boolean(), z.string()])
+        .optional()
+        .describe('Keep it in the extension so a person can find it later in the panel. `true` names it after the page; a STRING names it yourself, and building again under the same name REPLACES that document rather than leaving a stale twin above it.'),
+      kind: z
+        .enum(['issues', 'verified', 'notes'])
+        .optional()
+        .describe('What this document IS, for the list in the panel: `issues` (things that are wrong — the default), `verified` (checked and it holds), `notes` (a description, no verdict). It changes no layout — the blocks do that.'),
       blocks: z
         .array(
           z.union([
             z.object({ block: z.literal('title'), text: z.string(), subtitle: z.string().optional() }),
-            z.object({ block: z.literal('summary'), text: z.string().describe('One paragraph of plain words: what is wrong.') }),
+            z.object({ block: z.literal('summary'), text: z.string().describe('One paragraph of plain words: what this document is about.') }),
+            z.object({ block: z.literal('section'), text: z.string().describe('A heading, so a document longer than one thought has a shape'), note: z.string().optional() }),
             z.object({ block: z.literal('shot'), shot: z.string().describe('A name from qa_shot_list'), caption: z.string().optional() }),
             z.object({
               block: z.literal('finding'),
@@ -4754,6 +4828,14 @@ server.registerTool(
               expected: z.string().optional().describe('Only if a PERSON said so. No verb here knows the requirements.'),
               where: z.string().optional().describe('Selector or place'),
             }),
+            z.object({
+              block: z.literal('point'),
+              tone: z.enum(['good', 'info', 'warn', 'bad']).optional().describe('good = it holds · info = a neutral observation · warn · bad. Default info.'),
+              title: z.string().describe('The line somebody will quote'),
+              shot: z.string().optional().describe('The picture that shows it'),
+              what: z.string().optional().describe('What is the case'),
+              where: z.string().optional().describe('Selector or place'),
+            }),
             z.object({ block: z.literal('steps'), items: z.array(z.string()).describe('How to reproduce, short and with real values') }),
             z.object({ block: z.literal('facts'), pairs: z.array(z.object({ name: z.string(), value: z.string() })) }),
             z.object({ block: z.literal('note'), text: z.string(), tone: z.enum(['info', 'warn']).optional() }),
@@ -4762,26 +4844,107 @@ server.registerTool(
         .describe('In document order. The conditions of the run — active mocks, suppressed dialogs — are added automatically and cannot be omitted by the caller.'),
     },
   },
-  async ({ tabId, blocks, out }, extra) => {
+  async ({ tabId, blocks, out, save, kind }, extra) => {
     const bar = loader(extra, 'assembling the report');
     try {
-      const r = await callExtension('qa_report_build', { tabId, blocks }, 120_000);
+      const r = await callExtension('qa_report_build', { tabId, blocks, save, kind }, 120_000);
       if (!r || r.ok === false || typeof r.html !== 'string') return asText(r);
+      const kept = r.saved
+        ? { saved: r.saved, savedNote: 'kept in the extension: the panel’s Shots tab lists it under Reports, and qa_reports reads it back by that name' }
+        : {};
       if (out) {
         const full = resolve(out);
         mkdirSync(dirname(full), { recursive: true });
         writeFileSync(full, r.html, 'utf8');
         /* The funnel's question has been answered by the act itself; it must not ask again. */
         for (const [host, v] of reportFunnel) reportFunnel.set(host, { ...v, built: true });
-        return asText({ ok: true, path: full, blocks: r.blocks, shotsEmbedded: r.shotsEmbedded, findings: r.findings, bytes: r.bytes, warnings: r.warnings, note: 'Open it and print to PDF; the structure is the same on paper.' });
+        return asText({ ok: true, path: full, blocks: r.blocks, shotsEmbedded: r.shotsEmbedded, findings: r.findings, points: r.points, bytes: r.bytes, warnings: r.warnings, ...kept, note: 'Open it and print to PDF; the structure is the same on paper.' });
       }
-      return asText({ ok: true, blocks: r.blocks, shotsEmbedded: r.shotsEmbedded, findings: r.findings, bytes: r.bytes, warnings: r.warnings, html: r.html });
+      return asText({ ok: true, blocks: r.blocks, shotsEmbedded: r.shotsEmbedded, findings: r.findings, points: r.points, bytes: r.bytes, warnings: r.warnings, ...kept, html: r.html });
     } finally {
       bar.stop();
     }
   },
 );
 
+/**
+ * THE REPORTS THE EXTENSION IS HOLDING.
+ *
+ * Three verbs and no fourth: list them, take one back, drop one. Writing is `qa_report_build`'s
+ * `save` — a store with two ways in is a store whose two ways drift.
+ *
+ * The point of them is the hour AFTER the report was written. Until now a document left the
+ * extension the moment it was built and Qiksy knew nothing about it afterwards, so «send me the
+ * one from this morning» had no answer but «look in your Downloads». Now the panel lists it and
+ * so does this, under the same name.
+ */
+server.registerTool(
+  'qa_reports',
+  {
+    title: 'The reports the extension is keeping',
+    description:
+      'EVERY SAVED REPORT, BY NAME, with its title, what kind it is, when it was built, how many blocks and pictures went in and how big it is. ' +
+      'These are the documents `qa_report_build { save }` kept, and they are the same ones the person sees in the panel — so «open the checkout one» means the same thing on both sides. ' +
+      'It deliberately does NOT return the HTML: a report with pictures inside is megabytes, and the question here is which ones exist. Use qa_report_get for one. Read-only.',
+    inputSchema: { tabId: tabIdArg },
+  },
+  async ({ tabId }) => {
+    try {
+      return asText(await callExtension('qa_reports', { tabId }, 20_000));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+server.registerTool(
+  'qa_report_get',
+  {
+    title: 'Take one saved report back out',
+    description:
+      'THE DOCUMENT ITSELF, by the name qa_reports lists. Pass `out` to write it to a file — which is almost always what you want, because a self-contained report carries its pictures as data and spending that through this conversation buys nothing. ' +
+      'Without `out` the HTML comes back inline. Read-only: it takes a copy and leaves the extension’s own untouched.',
+    inputSchema: {
+      tabId: tabIdArg,
+      name: z.string().describe('A name from qa_reports'),
+      out: z.string().optional().describe('Write the HTML here instead of returning it inline'),
+    },
+  },
+  async ({ tabId, name, out }) => {
+    try {
+      const r = await callExtension('qa_report_get', { tabId, name }, 30_000);
+      if (!r || r.ok === false || typeof r.html !== 'string') return asText(r);
+      if (out) {
+        const full = resolve(out);
+        mkdirSync(dirname(full), { recursive: true });
+        writeFileSync(full, r.html, 'utf8');
+        return asText({ ok: true, path: full, name: r.name, title: r.title, kind: r.kind, bytes: r.bytes, note: 'Open it and print to PDF; the structure is the same on paper.' });
+      }
+      return asText(r);
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+server.registerTool(
+  'qa_report_drop',
+  {
+    title: 'Forget one saved report',
+    description:
+      'REMOVES A SAVED REPORT FROM THE EXTENSION — the row and the document together, because an index that forgets an entry while the megabytes stay is a leak nobody finds. ' +
+      'It touches nothing on the page and nothing on disk: a file you already wrote with `out` is yours and stays. The reply lists what is left.',
+    inputSchema: { tabId: tabIdArg, name: z.string().describe('A name from qa_reports') },
+  },
+  async ({ tabId, name }) => {
+    try {
+      return asText(await callExtension('qa_report_drop', { tabId, name }, 20_000));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
 server.registerTool(
   'qa_wiring',
   {
@@ -4894,9 +5057,10 @@ server.registerTool(
       'A MARK THAT KNOWS WHAT IT POINTS AT. Name the element — a CSS selector — and the box is looked up from the page itself at capture time, so the same instruction draws the correct picture today, after a fix, and at another screen width. ' +
       'An arrow drawn on an ordinary screenshot points at a coordinate: right when it was drawn, wrong the moment anything re-renders. That is why annotated screenshots are disposable, and it is the whole difference here. ' +
       'It is also how a picture marks ITSELF: a finding already carries a selector, so «draw the contrast failures» needs no aiming — pass their selectors straight through. ' +
-      'Shapes: `box` (outline it), `pin` (a numbered dot at its corner — for ordered things like a tab route), `arrow` and `line` (from one element to another, which is how you show an error message wired to the wrong field). Colours are named, not free: default · bad · good · info · warn. ' +
+      'Shapes: `box` (outline it), `pin` (a numbered dot at its corner — for ordered things like a tab route), `arrow` and `line` (from one element to another, which is how you show an error message wired to the wrong field), and `blur` (a pane that makes the element unreadable — an address, a customer\'s name, a token in a staging header). Colours are named, not free: default · bad · good · info · warn. ' +
+      'A LABEL IS A CALLOUT, not a sticker: it is placed in free space beside its element, clear of every other mark, and joined to the outline by a leader line ending in a dot. So «outline the payment block and say what is wrong with it» comes back as one readable statement instead of words stamped over the thing they are about. ' +
       'A mark whose element is not on the page is REPORTED in `missed`, never silently dropped — a reader who sees three arrows must be able to trust that there were three things to point at. ' +
-      'Read-only: it photographs and draws, and touches nothing.',
+      'Read-only: it photographs and draws, and touches nothing — a blur hides the data in THIS picture, never on the page, so the next capture shows it again.',
     inputSchema: {
       tabId: tabIdArg,
       fromFindings: z
@@ -4906,13 +5070,15 @@ server.registerTool(
       marks: z
         .array(
           z.object({
-            kind: z.enum(['box', 'pin', 'arrow', 'line']).optional().describe("Default 'box'"),
+            kind: z.enum(['box', 'pin', 'arrow', 'line', 'blur']).optional().describe("Default 'box'"),
             selector: z.string().optional().describe('The element to mark'),
             box: z.object({ x: z.number(), y: z.number(), w: z.number(), h: z.number() }).optional().describe('Or a box in IMAGE pixels, if you already have one from a shot map'),
             toSelector: z.string().optional().describe('For arrow/line: the element at the other end'),
             toBox: z.object({ x: z.number(), y: z.number(), w: z.number(), h: z.number() }).optional(),
-            label: z.string().optional().describe('Short text on the mark (three characters inside a pin, up to sixty beside a box)'),
+            label: z.string().optional().describe('Short text on the mark — three characters inside a pin, up to sixty in a callout placed beside the element and joined to it by a leader line'),
             colour: z.enum(['default', 'bad', 'good', 'info', 'warn']).optional(),
+            strength: z.number().optional().describe("For 'blur': how hard it hides, 4–60 (default 14)"),
+            pad: z.number().optional().describe("For 'blur': extra margin round the element, in CSS pixels (default 2) — a pane flush with the text tends to leave the tops of the letters showing"),
           }),
         )
         .optional()
@@ -4963,12 +5129,12 @@ server.registerTool(
         const { resolve } = await import('node:path');
         const full = resolve(outPath);
         writeFileSync(full, Buffer.from(b64, 'base64'));
-        return asText({ ok: true, path: full, drawn: r.drawn, missed: r.missed, ...(skipped ? { findingsWithoutAPlace: skipped, findingsNote: `${skipped} finding(s) have no selector — a console error or a failed request is not AT a place on the page. They are in qa_findings, not in this picture.` } : {}), width: r.width, height: r.height, note: r.note });
+        return asText({ ok: true, path: full, drawn: r.drawn, ...(r.hidden ? { hidden: r.hidden } : {}), missed: r.missed, ...(skipped ? { findingsWithoutAPlace: skipped, findingsNote: `${skipped} finding(s) have no selector — a console error or a failed request is not AT a place on the page. They are in qa_findings, not in this picture.` } : {}), width: r.width, height: r.height, note: r.note });
       }
       return {
         content: [
           { type: 'image', data: b64, mimeType: 'image/png' },
-          { type: 'text', text: JSON.stringify({ ok: true, drawn: r.drawn, missed: r.missed, ...(skipped ? { findingsWithoutAPlace: skipped } : {}), width: r.width, height: r.height, note: r.note }, null, 2) },
+          { type: 'text', text: JSON.stringify({ ok: true, drawn: r.drawn, ...(r.hidden ? { hidden: r.hidden } : {}), missed: r.missed, ...(skipped ? { findingsWithoutAPlace: skipped } : {}), width: r.width, height: r.height, note: r.note }, null, 2) },
         ],
       };
     } catch (e) {
@@ -6482,6 +6648,53 @@ server.registerTool(
   },
 );
 
+/**
+ * THE FULL STOP — the one thing a browser cannot work out for itself.
+ *
+ * Somebody sets an agent off on a long run and goes to do something else: another tab, another
+ * screen, another room. Until now nothing told them it had ended. «No calls for a while» is not
+ * the answer — a model that stops to think looks exactly like a model that has finished, and a
+ * signal that cries wolf every thirty seconds gets switched off within the hour.
+ *
+ * So the run says so itself, and the browser turns that into something visible from across a
+ * room: the mark on the tab pulses slowly — and stops the moment they look at that tab, because
+ * being looked at IS the acknowledgement. A tab already in front is never pulsed at all.
+ */
+server.registerTool(
+  'qa_done',
+  {
+    title: 'Say the run has finished',
+    description:
+      'CALL THIS WHEN THE WORK IS ACTUALLY OVER — the last check made, the last fix verified, the answer about to be written. The mark on every driven tab the person is NOT looking at then pulses slowly, so somebody who walked away from the screen can see from across the room that it ended. It stops by itself when they look at that tab; there is nothing to dismiss. ' +
+      'It is a nudge, not a report: still say what you did, in your own words. And it is not a progress beat — calling it between steps teaches people to ignore it, which costs the signal its only job. Any further call cancels it, so a run that continues quietly withdraws it. ' +
+      'A short sound plays as well, for somebody who is not looking at the browser at all — the person can switch the sound off in the popup, and the pulse stays either way. ' +
+      'Free, and it touches nothing on the page.',
+    inputSchema: {
+      tabId: tabIdArg,
+      verdict: z
+        .enum(['ok', 'problem'])
+        .optional()
+        .describe('How it ended. `ok` (default) rises; `problem` falls — the same sound in two directions, so the ear tells them apart without being taught. Say what you actually found; a run that discovered a defect ended FINE if you finished the work.'),
+    },
+  },
+  async ({ tabId, verdict }) => {
+    try {
+      return asText(await callExtension('qa_done', { tabId, verdict }, 15_000));
+    } catch (e) {
+      /* The verb lives in the EXTENSION, which updates on the Web Store's clock while this server
+         updates with npx — «unknown tool» is the shape of that gap, and raw it reads as a bug. */
+      if (/Unknown tool/i.test(String(e?.message || e))) {
+        return asText({
+          ok: false,
+          error: 'not-in-this-extension-build',
+          note: 'qa_done needs a newer extension in the browser. Nothing is lost: say you have finished in your own words, which is what the person reads anyway.',
+        });
+      }
+      return asError(e);
+    }
+  },
+);
+
 server.registerTool(
   'qa_close_tab',
   {