qiksy-mcp 1.2.0 → 1.2.1

package/AGENT-GUIDE.md

@@ -82,10 +82,18 @@ sentence rather than working around it.
 
 ## What it cannot do — say so, don't substitute
 
-- **No screenshots.** `qa_snapshot` is a tree, not pixels. Judgements about spacing,
-  colour or alignment cannot be made from here.
-- **No arbitrary JavaScript.** No `evaluate`, by design (a Web Store requirement). Which
-  means **no reading or writing localStorage** and **no measuring geometry**.
+- **No screenshots.** `qa_snapshot` is a tree, not pixels. A judgement that genuinely needs
+  to SEE the rendering — is this the right shade, does that shadow look right — cannot be
+  made from here.
+- **No arbitrary JavaScript.** No `evaluate`, by design (a Web Store requirement). Every verb
+  is a closed vocabulary: you name an element, never a program.
+- **Styles, geometry and web storage ARE available** — `qa_styles` (computed styles, the box,
+  and the CSS custom properties in scope), `qa_snapshot({geometry:true})` (every node's box in
+  CSS pixels), `qa_storage` (localStorage / sessionStorage, read free, write behind Agent
+  control). This guide used to list all three as impossible. That was a wrong inference from
+  the no-eval rule, and it cost real capability: an agent told a thing cannot be done does not
+  try it. So: no pixels, but plenty of numbers — "this button renders #3B82F6 at 15px with
+  22px padding, and its box overlaps the one next to it" needs no screenshot at all.
 - **No `<iframe>` contents.** Payment forms (Stripe, 3-D Secure) live in frames the
   content script does not enter. Fill up to them, not inside them.
 - **No captcha.** Stop and hand it back.

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "qiksy-mcp",
-  "version": "1.2.0",
-  "description": "MCP bridge for the Qiksy browser extension — expose live QA findings, forms, network and session to any MCP-capable coding agent.",
+  "version": "1.2.1",
+  "description": "MCP bridge for the Qiksy browser extension \u2014 expose live QA findings, forms, network and session to any MCP-capable coding agent.",
   "type": "module",
   "bin": {
     "qiksy-mcp": "server.mjs"
   },
-  "files": ["server.mjs", "README.md", "AGENT-GUIDE.md"],
+  "files": [
+    "server.mjs",
+    "README.md",
+    "AGENT-GUIDE.md"
+  ],
   "engines": {
     "node": ">=18"
   },

package/server.mjs

@@ -26,7 +26,8 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { WebSocketServer, WebSocket } from 'ws';
 import { z } from 'zod';
 import { randomUUID, timingSafeEqual } from 'node:crypto';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { basename, extname, dirname, isAbsolute, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const log = (...a) => console.error('[qiksy-mcp]', ...a);
@@ -494,20 +495,58 @@ window or tab focus, and never steals the pointer. That is the point of the prod
 happens inside the existing (even backgrounded) tab, so prefer it over anything that would pop
 a new browser up in the user's face.
 
-What it gives you, and what it deliberately does not:
-- qa_snapshot returns an ACCESSIBILITY TREE, not pixels. There are no screenshots on this
-  bridge, no arbitrary JavaScript execution (a Web Store requirement, not an oversight), and
-  therefore no reading or writing localStorage and no measuring geometry. When a task truly
-  needs pixels or eval, say that it is outside the bridge — never silently substitute another
-  browser tool.
-- Read tools — qa_tabs, qa_status, qa_snapshot, qa_findings, qa_export — always work.
-- Tools that act on the app under test — qa_click, qa_type, qa_type_many, qa_press,
-  qa_wait_ready, qa_navigate, qa_open_isolated, qa_close_tab — require Qiksy Pro AND a
-  one-time "Agent control" consent in the extension popup. A refusal there is the user's to
-  clear; report it in one sentence instead of working around it.
-- Address a specific tab with the tabId from qa_tabs; omit it to act on the active tab. Tabs
-  opened by qa_open_isolated are separate logins on the same site — that is how you drive
-  several accounts at once.
+WHAT YOU CAN SEE (all free, none of it needs Agent control):
+- qa_snapshot — the whole page as an accessibility tree with stable refs. Pass geometry:true
+  and every node also carries its box in CSS pixels, which is how you answer "this is cut off
+  / these overlap / that tap target is 28px" without a screenshot.
+- qa_read — the RENDERED text of the page or one element. Reach for it whenever the answer is
+  longer than a label: qa_snapshot caps names at 80 characters, so a one-time code in a mail
+  tab, a full error paragraph or a generated invoice number is invisible to it.
+- qa_styles — computed styles, the element's box, and the CSS custom properties in scope.
+  "color: rgb(37,99,235)" says what is drawn; "--accent: #2563EB" says which token it came
+  from, and only the second one is a bug report. This is how you check a build against a design.
+- qa_storage — read the app's localStorage / sessionStorage. Feature flags, cached state, and
+  usually the session token live there.
+- qa_findings / qa_export / qa_status — what Qiksy itself observed: console and JS errors,
+  failed requests WITH their server error bodies, a11y and markup defects, and a "Speed &
+  stability" group fed by the browser's own measurements (layout shift with the element that
+  moved, slow interactions split into input delay / handler / paint, main-thread blocks with
+  the script responsible).
+
+WHAT YOU CAN DO (Qiksy Pro + the one-time "Agent control" consent in the popup; a refusal
+there is the user's to clear — report it in one sentence instead of working around it):
+- qa_click / qa_press — and they ANSWER with what changed. After the page settles you get the
+  diff: what appeared, disappeared, updated. Do not follow an action with a qa_snapshot just
+  to find out whether it worked; \`changed: null\` means the page did not move, which is itself
+  the answer.
+- qa_type — one field. qa_type_many — a whole form in ONE call. Prefer refs over selectors in
+  the batch: a form built from a repeated component gives several inputs the identical
+  cssPath, and selectors would then pour every value into the first match.
+- qa_upload — attach a file. \`path\` for a file on the machine (THIS process reads it, so the
+  bytes never enter your context), \`fixture\` for a hostile one built in the page at no cost
+  over the wire: empty, oversize 12MB, wrong-type, corrupt, long-name, unicode-name,
+  svg-script, double-ext. Each returns the question it asks, as \`asks\`.
+- qa_storage with op set/remove/clear, qa_navigate, qa_open_isolated, qa_close_tab.
+- qa_report — the session report. ALWAYS pass \`path\`: it is a self-contained HTML document
+  with embedded screenshots, routinely hundreds of kilobytes, and you get back a receipt
+  instead of the bytes. Pass \`spec\` with the ticket's acceptance criteria and your verdict on
+  each, and it becomes a deliverable rather than a log.
+
+WHAT IS GENUINELY NOT HERE: no screenshots over this bridge, and no arbitrary JavaScript
+execution — the second is a Web Store requirement, not an oversight, and it is why every verb
+above is a closed vocabulary: you name an element, never a program. When a task truly needs
+pixels or eval, say it is outside the bridge; never silently substitute another browser tool.
+(Styles, geometry and web storage USED to be listed here as impossible. They were not; that
+was a wrong inference from the no-eval rule, and they have their own tools now.)
+
+TABS: the agent session is a SET the human opts into — the "Agent drives this tab" switch in
+the popup, or right-click → "Qiksy — test this tab". Attached tabs stay in the session while
+the user looks at something else, so work continues in a background tab, and a tab opened BY
+an attached tab joins it automatically (that is how an identity-provider sign-in stays in the
+flow). qa_tabs lists the session; pass a tabId to target one. Tabs from qa_open_isolated are
+separate logins on the same site — that is how you drive several accounts at once. If the set
+is empty it falls back to the active tab; if a tool answers out-of-scope, ask the human to
+attach the tab rather than reaching around it.
 
 Several agent windows, one browser: each MCP client starts its own copy of this server, but
 only one can own the loopback port. The first to bind it holds the extension socket; the others
@@ -642,6 +681,158 @@ server.registerTool(
   },
 );
 
+server.registerTool(
+  'qa_read',
+  {
+    title: 'Read the text of a page (or one element)',
+    description:
+      'Return the RENDERED text of the page under test, or of a single element named by a qa_snapshot ref or a CSS selector. ' +
+      'This is the companion to qa_snapshot: that one maps what you can ACT on (roles, names, refs) and caps every name at 80 characters, ' +
+      'so anything longer — a one-time code in an email, an error paragraph, a generated invoice number — is invisible to it. ' +
+      'Uses innerText, so hidden branches and a mail thread\'s collapsed quoted history stay out. Read-only: it executes nothing and returns text, capped (default 4000 chars, max 20000).',
+    inputSchema: {
+      tabId: tabIdArg,
+      ref: z.string().optional().describe('A ref from qa_snapshot (e.g. "e12") — preferred when you already have one'),
+      selector: z.string().optional().describe('CSS selector; omit both to read the whole page body'),
+      maxChars: z.number().optional().describe('Cap the returned text (default 4000, max 20000)'),
+    },
+  },
+  async ({ tabId, ref, selector, maxChars }, extra) => {
+    const bar = loader(extra, 'reading the page text');
+    try {
+      return asText(await callExtension('qa_read', { tabId, ref, selector, maxChars }, 30_000));
+    } catch (e) {
+      return asError(e);
+    } finally {
+      bar.stop();
+    }
+  },
+);
+
+/** Enough to cover what an upload field actually accepts; anything else falls back to octet-stream. */
+const MIME = {
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+  '.webp': 'image/webp', '.svg': 'image/svg+xml', '.pdf': 'application/pdf',
+  '.csv': 'text/csv', '.txt': 'text/plain', '.json': 'application/json',
+  '.xls': 'application/vnd.ms-excel',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.doc': 'application/msword',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.zip': 'application/zip',
+};
+
+server.registerTool(
+  'qa_upload',
+  {
+    title: 'Attach a file to an upload field (Pro)',
+    description:
+      "Put a file into an <input type=file> — including the hidden ones behind a styled dropzone, which a click can never reach. " +
+      'Three ways to choose what goes in: `fixture` for a hostile edge-case file (the upload counterpart of naughty strings — empty, oversize, wrong-type, corrupt, unicode name, unsanitised SVG…), `path` for a file on this machine, or `content` as base64. ' +
+      'Pass `content` as base64 to attach a file YOU generated (a PDF fixture, a malformed CSV, an oversized image); omit it and Qiksy attaches a neutral test file matched to the field\'s `accept`. ' +
+      'A content script has no filesystem access and the OS file picker is a modal an agent must never open, so bytes over this bridge are the only way a file from outside the browser gets in. ' +
+      'Delivery fires both paths uploaders use — assigning `input.files` + change, and a synthetic drop on the nearest dropzone — because react-dropzone-style components listen only for the second.',
+    inputSchema: {
+      tabId: tabIdArg,
+      ref: z.string().optional().describe('A ref from qa_snapshot'),
+      selector: z.string().optional().describe("CSS selector of the file input or its dropzone; omit to use the page's first file input"),
+      name: z.string().optional().describe("File name, e.g. 'report.pdf'"),
+      mimeType: z.string().optional().describe("MIME type, e.g. 'application/pdf'"),
+      fixture: z
+        .enum(['image', 'pdf', 'csv', 'empty', 'oversize', 'wrong-type', 'corrupt', 'long-name', 'unicode-name', 'svg-script', 'double-ext'])
+        .optional()
+        .describe(
+          'A HOSTILE fixture built in the page, so it costs nothing to send: empty (0 bytes) · oversize (12MB) · ' +
+            'wrong-type (a PNG named .pdf — is content checked or only the extension?) · corrupt (truncated PNG) · ' +
+            'long-name (255 chars) · unicode-name (RTL + emoji + CJK) · svg-script (is an uploaded SVG sanitised?) · ' +
+            'double-ext (invoice.pdf.exe — does the UI show the whole name?). The answer comes back as `asks`.',
+        ),
+      path: z.string().optional().describe('Absolute path to a file ON THIS MACHINE — the server reads and encodes it for you. Use this instead of `content` for anything bigger than a few hundred bytes.'),
+      content: z.string().optional().describe('Base64 file content, for a file you are holding in memory. Prefer `path`.'),
+    },
+  },
+  async ({ tabId, ref, selector, name, mimeType, path, content, fixture }, extra) => {
+    const bar = loader(extra, 'attaching the file');
+    try {
+      /* READING THE FILE HAPPENS HERE, and that is the whole point of the option.
+       *
+       * This process is ordinary Node on the user's machine — it has a filesystem, which the
+       * content script pointedly does not. Passing 15,000 characters of base64 through a tool
+       * call to move a 12KB image is absurd when one side can simply open the file; a modest
+       * PDF or screenshot makes it worse than absurd. So the agent names a path and the bytes
+       * never enter the conversation at all. */
+      let body = content;
+      let fileName = name;
+      let type = mimeType;
+      if (path) {
+        body = readFileSync(path).toString('base64');
+        fileName = fileName || basename(path);
+        type = type || MIME[extname(path).toLowerCase()] || 'application/octet-stream';
+      }
+      return asText(await callExtension('qa_upload', { tabId, ref, selector, name: fileName, mimeType: type, content: body, fixture }, 30_000));
+    } catch (e) {
+      return asError(e);
+    } finally {
+      bar.stop();
+    }
+  },
+);
+
+server.registerTool(
+  'qa_storage',
+  {
+    title: 'Read or set the page\'s web storage',
+    description:
+      "Read and write the app's own localStorage / sessionStorage — flip a feature flag, expire a token to test the re-auth path, or prove what the app actually persisted after a save. " +
+      "Without `op` (or with op:'list'/'get') it READS and is free like every other read on this bridge; op:'set'|'remove'|'clear' WRITES and needs Pro + the Agent control consent, because changing a stored token or flag changes what the app does just as surely as clicking does. " +
+      'Closed vocabulary — it executes nothing you supply, it names a key. Listing truncates long values at 300 chars; ask for one key by name to get it whole.',
+    inputSchema: {
+      tabId: tabIdArg,
+      area: z.enum(['local', 'session']).optional().describe("Which store (default 'local')"),
+      op: z.enum(['list', 'get', 'set', 'remove', 'clear']).optional().describe("Default 'list' (or 'get' when a key is given)"),
+      key: z.string().optional().describe('The key to read, set or remove'),
+      value: z.string().optional().describe("The value, for op:'set'"),
+    },
+  },
+  async ({ tabId, area, op, key, value }, extra) => {
+    const bar = loader(extra, 'reading web storage');
+    try {
+      return asText(await callExtension('qa_storage', { tabId, area, op, key, value }, 30_000));
+    } catch (e) {
+      return asError(e);
+    } finally {
+      bar.stop();
+    }
+  },
+);
+
+server.registerTool(
+  'qa_styles',
+  {
+    title: 'Computed styles and box of an element',
+    description:
+      'The COMPUTED styles of one element — colour, type, spacing, border, shadow, layout — plus its box in CSS pixels, and the CSS custom properties (design tokens) in scope for it. ' +
+      'This is how you check a built page against a design: it answers "this button renders #3B82F6 at 15px with 22px padding" without a screenshot and without measuring anything by eye. ' +
+      'Target it by a qa_snapshot ref (preferred) or a CSS selector. Read-only and executes NOTHING: the property list is fixed in the extension, so you name an element, never a program. ' +
+      'Pair it with a design source (a Figma file, a token JSON) to report the diff, and with qa_spotlight to show the human which element you mean.',
+    inputSchema: {
+      tabId: tabIdArg,
+      ref: z.string().optional().describe('A ref from qa_snapshot (e.g. "e12") — preferred over selector'),
+      selector: z.string().optional().describe('CSS selector of the element'),
+      tokens: z.boolean().optional().describe('Include the CSS custom properties in scope (default true)'),
+    },
+  },
+  async ({ tabId, ref, selector, tokens }, extra) => {
+    const bar = loader(extra, 'reading the computed styles');
+    try {
+      return asText(await callExtension('qa_styles', { tabId, ref, selector, tokens }, 30_000));
+    } catch (e) {
+      return asError(e);
+    } finally {
+      bar.stop();
+    }
+  },
+);
+
 server.registerTool(
   'qa_snapshot',
   {
@@ -651,12 +842,15 @@ server.registerTool(
       '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 },
+    inputSchema: {
+      tabId: tabIdArg,
+      geometry: z.boolean().optional().describe('Add each node\'s box as "x,y,w,h" in CSS pixels — for overlap, clipping, off-screen and tap-target-size checks. Off by default: it is bulk on every node.'),
+    },
   },
-  async ({ tabId }, extra) => {
+  async ({ tabId, geometry }, extra) => {
     const bar = loader(extra, 'reading the whole page');
     try {
-      return asText(await callExtension('qa_snapshot', { tabId }, 30_000));
+      return asText(await callExtension('qa_snapshot', { tabId, geometry }, 30_000));
     } catch (e) {
       return asError(e);
     } finally {
@@ -694,6 +888,14 @@ server.registerTool(
       'Requires History recording to have captured steps; otherwise returns a note.',
     inputSchema: {
       tabId: tabIdArg,
+      path: z
+        .string()
+        .optional()
+        .describe(
+          'Write the report HERE instead of returning it. An absolute path, or one relative to where the bridge process runs. ' +
+            'STRONGLY PREFERRED: the report is a self-contained HTML document with embedded screenshots and routinely runs to hundreds of kilobytes — returning it inline spends your context on bytes you were going to save to a file anyway. ' +
+            'You get back the path, the size and the report title.',
+        ),
       spec: z
         .object({
           title: z.string().optional().describe('Report heading, e.g. the ticket key + name'),
@@ -714,9 +916,29 @@ server.registerTool(
         .describe('Acceptance criteria + verdicts to lead the report with'),
     },
   },
-  async ({ tabId, spec }) => {
+  async ({ tabId, path: outPath, spec }) => {
     try {
-      return asText(await callExtension('qa_report', { tabId, spec }, 45_000));
+      const res = await callExtension('qa_report', { tabId, spec }, 45_000);
+      /* WRITING HAPPENS HERE, on the same reasoning as qa_upload's `path`, inverted.
+       *
+       * This process is ordinary Node on the user's machine and has a filesystem; the
+       * extension does not. A session report is a self-contained HTML document with base64
+       * screenshots inside it — hundreds of kilobytes — and handing that back through a tool
+       * result burns the agent's context on bytes whose destination is a file. So the agent
+       * names a path and only the receipt comes back. */
+      if (outPath && res && typeof res.html === 'string') {
+        const abs = isAbsolute(outPath) ? outPath : resolve(process.cwd(), outPath);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, res.html, 'utf8');
+        return asText({
+          ok: true,
+          path: abs,
+          bytes: Buffer.byteLength(res.html, 'utf8'),
+          title: spec?.title ?? null,
+          note: 'Self-contained HTML — screenshots are embedded, so it opens anywhere and can be attached to a ticket as one file.',
+        });
+      }
+      return asText(res);
     } catch (e) {
       return asError(e);
     }
@@ -764,7 +986,7 @@ server.registerTool(
   {
     title: 'Click an element (Pro)',
     description:
-      '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.' +
+      '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. Returns what the click CHANGED — what appeared, disappeared or updated once the page settled — so you do not need a follow-up qa_snapshot to find out whether it did anything. `changed: null` means the page did not move, which is itself the answer.' +
       DRIVE_NOTE,
     inputSchema: {
       tabId: tabIdArg,
@@ -809,14 +1031,18 @@ server.registerTool(
   {
     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.' +
+      'Fill a WHOLE form in ONE call instead of a round-trip per field: pass an array of { ref | selector, value, action? }. ' +
+      'PREFER `ref` from qa_snapshot: a form built from a repeated component gives several inputs the identical cssPath, and a batch of selectors would then pour every value into the first match. ' +
+      'action defaults to type (which also handles select, checkbox and radio from the value), or click for buttons and 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'),
+            ref: z.string().optional().describe('A ref from qa_snapshot — REQUIRED when several fields share one cssPath, which is common on forms built from a repeated component'),
+            selector: z.string().optional().describe('CSS selector of the field — use `ref` instead when the selector is not unique'),
             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'),
           }),
@@ -838,7 +1064,7 @@ server.registerTool(
   {
     title: 'Press a key (Pro)',
     description:
-      'Dispatch a keyboard key (keydown/keypress/keyup) — Enter to submit, Escape to close, Tab to move focus. Without a selector it goes to whatever currently has focus, like a real keyboard.' +
+      'Dispatch a keyboard key (keydown/keypress/keyup) — Enter to submit, Escape to close, Tab to move focus. Without a selector it goes to whatever currently has focus, like a real keyboard. Like qa_click, it returns what changed once the page settled.' +
       DRIVE_NOTE,
     inputSchema: {
       tabId: tabIdArg,