qiksy-mcp 1.1.0 → 1.2.0

package/AGENT-GUIDE.md

@@ -0,0 +1,111 @@
+# Qiksy bridge — guide for a coding agent
+
+Drop this file into a project (`.claude/qiksy-bridge.md`, `AGENTS.md`, or wherever your
+assistant reads project notes) and the assistant knows what the bridge is, what it can
+do, and — just as important — what it deliberately cannot.
+
+Qiksy connects an agent to **the browser the human already has open**: their real
+profile, their logged-in sessions, the tab they are looking at. It never launches a
+browser, never switches window or tab focus, and never steals the pointer. Work happens
+inside the existing (even backgrounded) tab.
+
+---
+
+## Setup, once
+
+1. **Install the extension** — [Qiksy on the Chrome Web Store](https://chromewebstore.google.com/detail/jcnbcbpndahhblhobhjjkhafmbkleoem).
+2. **Turn the bridge on.** Either the extension popup → *Agent bridge · MCP* → On →
+   *Generate* a token, or — from a Qiksy web app — press **Connect this browser** and
+   confirm on the page the extension opens. Both end the same way: a port (7333 by
+   default) and a shared token.
+3. **Point the agent at it.** Same token, same port:
+
+   ```bash
+   claude mcp add --transport stdio qiksy \
+     --env QIKSY_MCP_TOKEN=YOUR_TOKEN \
+     -- npx qiksy-mcp --port 7333
+   ```
+
+   ```json
+   { "mcpServers": { "qiksy": {
+     "command": "npx",
+     "args": ["qiksy-mcp", "--port", "7333"],
+     "env": { "QIKSY_MCP_TOKEN": "YOUR_TOKEN" }
+   } } }
+   ```
+
+4. **Check it.** `qa_status` should answer with the current page. "Qiksy extension is not
+   connected" means the popup switch is off or the token/port differ — it is not a
+   reason to reach for another browser driver.
+
+---
+
+## The tools
+
+**Read-only — always available.**
+
+| Tool | What it gives you |
+|---|---|
+| `qa_tabs` | Every tab the bridge can see, with `tabId`, URL, title, and which are isolated logins. Start here when several tabs are open. |
+| `qa_status` | Health of one tab: URL, counts of errors, warnings, forms, failed requests. The cheap "did I break something". |
+| `qa_snapshot` | The whole page as an **accessibility tree** — every control, landmark and heading with a role, a name, its state, and a stable `ref` like `[ref=e12]`. This is how you SEE the page. |
+| `qa_findings` | Console errors, failed requests, a11y problems Qiksy has collected, filterable by severity. |
+| `qa_export` | The `qa-export/v1` bundle: findings with selectors, failed requests with server bodies, detected form structure, repro steps. |
+
+**Qiksy's own surfaces — never touches the page under test.**
+
+`qa_open_panel` · `qa_run_audit` · `qa_tour` · `qa_report` · `qa_spotlight`
+(`qa_spotlight` highlights an element so the human can look at the same thing you are.)
+
+**Agent control — acts on the page. Requires Qiksy Pro AND a one-time "Agent control"
+consent in the popup.** A refusal there is the human's to clear; report it in one
+sentence rather than working around it.
+
+`qa_click` · `qa_type` · `qa_type_many` · `qa_press` · `qa_wait_ready` ·
+`qa_navigate` · `qa_open_isolated` · `qa_close_tab`
+
+---
+
+## How to drive it well
+
+- **Target by `ref` from a fresh snapshot.** A `ref` is unique where a CSS selector is
+  ambiguous. After anything that navigates or re-renders, call `qa_wait_ready` and take
+  a **new** snapshot — old refs go stale.
+- **Address a specific tab** with `tabId` from `qa_tabs`; omit it to act on the active
+  one. Tabs from `qa_open_isolated` are separate logins on the same site — that is how
+  you drive several accounts at once.
+- **After a submit**, `qa_wait_ready` before the next call: the old document (and Qiksy
+  inside it) is gone, and the next call would land on a page still being replaced.
+- **Autocomplete fields need a beat.** Suggestion lists arrive asynchronously (~0.4s on
+  travel sites). Type, wait, snapshot, then click the option you want — do not assume
+  the first one committed.
+
+## 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 `<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.
+- **Background tabs are throttled by Chrome.** Native inputs fill fine in the
+  background; custom popovers (Radix/MUI selects, date pickers) only render in the
+  foreground tab.
+- **Navigation stays on the site under test.** `qa_navigate` refuses a different site
+  (`out-of-scope`) — the human opens that tab, then the agent works in it.
+
+When a task genuinely needs pixels, eval or a different site, name the missing
+capability out loud instead of quietly switching to another tool.
+
+## Several agent windows, one browser
+
+Each MCP client starts its own copy of the server, but only one can own the loopback
+port: whoever binds it is the hub and holds the extension socket, the rest relay
+through it automatically. You do not need to know which one you are. If the owning
+window closes, the others take the port over within a second or two — a call that fails
+that way is worth one retry.
+
+If the port is held by something that cannot share it (an older bridge, an unrelated
+process), the tools say so; the fix is that process or a different `--port`, not the
+popup.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "qiksy-mcp",
-  "version": "1.1.0",
+  "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.",
   "type": "module",
   "bin": {
     "qiksy-mcp": "server.mjs"
   },
-  "files": ["server.mjs", "README.md"],
+  "files": ["server.mjs", "README.md", "AGENT-GUIDE.md"],
   "engines": {
     "node": ">=18"
   },

package/server.mjs

@@ -443,7 +443,44 @@ function callHub(tool, args, timeoutMs) {
 }
 
 // ── MCP server + tools (read-only) ─────────────────────────────────────────
-const asText = (v) => ({ content: [{ type: 'text', text: typeof v === 'string' ? v : JSON.stringify(v, null, 2) }] });
+/* The humour used to live only in the stderr log, where nobody looks (owner ask
+ * 2026-07-26: "хотелось бы рожиц"). A client draws the tool row as `Qiksy [qa_tabs]` —
+ * the bracketed part is the tool NAME and MCP names are `[a-zA-Z0-9_-]` only, so a face
+ * cannot go there. The result CAN: it rides as its own leading content block, so the
+ * payload block below it stays byte-identical for anything that parses it.
+ * Failures stay face-free on purpose — a joke on top of an error competes with the one
+ * sentence the human needs to act on. */
+/* The trailing newline is not cosmetic slop: a client concatenates the content blocks with
+ * nothing between them, so without it the payload starts on the same line as the face
+ * (`…undocumented features{` — seen live 2026-07-26). */
+const decor = () => (QUIPS_ON ? [{ type: 'text', text: `qx ${face()}  ${quip()}\n` }] : []);
+/* A LOADER for the calls that take a while (owner ask 2026-07-26). An audit, a report or a
+ * snapshot of a heavy page leaves the tool row sitting dead for seconds, and a human cannot
+ * tell "working" from "hung". MCP has progress notifications, so we send frames while the
+ * extension is busy; a client that ignores them loses nothing. Only when the caller passed a
+ * progressToken — otherwise there is nobody to notify. */
+const BAR = ['[▰▱▱▱▱]', '[▰▰▱▱▱]', '[▰▰▰▱▱]', '[▰▰▰▰▱]', '[▰▰▰▰▰]'];
+function loader(extra, label) {
+  const token = extra?._meta?.progressToken;
+  if (!token || !QUIPS_ON || typeof extra?.sendNotification !== 'function') return { stop() {} };
+  let i = 0;
+  const beat = () => {
+    extra
+      .sendNotification({
+        method: 'notifications/progress',
+        params: { progressToken: token, progress: (i % BAR.length) + 1, total: BAR.length, message: `qx ${BAR[i % BAR.length]}  ${label}` },
+      })
+      .catch(() => {
+        /* the client hung up, or does not implement progress */
+      });
+    i++;
+  };
+  beat();
+  const timer = setInterval(beat, 700);
+  return { stop: () => clearInterval(timer) };
+}
+
+const asText = (v) => ({ content: [...decor(), { type: 'text', text: typeof v === 'string' ? v : JSON.stringify(v, null, 2) }] });
 const asError = (e) => ({ isError: true, content: [{ type: 'text', text: e instanceof Error ? e.message : String(e) }] });
 
 /* The operating manual, handed to the agent at `initialize` — not left in a README
@@ -478,6 +515,10 @@ detect this and relay through it automatically. You do not need to know which on
 the user changes nothing in the popup. If the owning window closes, the rest take the port over
 on their own within a second or two, so a call that fails that way is worth one retry.
 
+Every successful result starts with a short decorative line — \`qx <face> <quip>\` — and the
+actual payload is the block after it. It is cosmetic: ignore it when reading data, and never
+copy it into a finding, a report or a commit message. Set QIKSY_MCP_QUIPS=0 to turn it off.
+
 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
@@ -545,11 +586,14 @@ server.registerTool(
       'Full qa-export/v1 bundle for a page: findings (with selectors), failed requests (with server error bodies), detected form structure, recorded repro steps, env, and isolated-login name. Read this, then fix the underlying issues. Pass tabId (from qa_tabs) to target a specific tab / isolated login.',
     inputSchema: { tabId: z.number().int().optional().describe('Target tab (from qa_tabs); omit for the active tab') },
   },
-  async ({ tabId }) => {
+  async ({ tabId }, extra) => {
+    const bar = loader(extra, 'building the QA bundle');
     try {
       return asText(await callExtension('qa_export', { tabId }, 30_000));
     } catch (e) {
       return asError(e);
+    } finally {
+      bar.stop();
     }
   },
 );
@@ -586,11 +630,14 @@ server.registerTool(
       'Run Qiksy\'s a11y/markup audit on the current DOM (unlabeled controls, missing names, WCAG AA contrast, broken images, duplicate ids, positive tabindex, …) and return the findings. Also refreshes the panel. Static, non-destructive — reads the DOM only.',
     inputSchema: { tabId: tabIdArg },
   },
-  async ({ tabId }) => {
+  async ({ tabId }, extra) => {
+    const bar = loader(extra, 'auditing the page');
     try {
       return asText(await callExtension('qa_run_audit', { tabId }, 30_000));
     } catch (e) {
       return asError(e);
+    } finally {
+      bar.stop();
     }
   },
 );
@@ -606,11 +653,14 @@ server.registerTool(
       '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 }) => {
+  async ({ tabId }, extra) => {
+    const bar = loader(extra, 'reading the whole page');
     try {
       return asText(await callExtension('qa_snapshot', { tabId }, 30_000));
     } catch (e) {
       return asError(e);
+    } finally {
+      bar.stop();
     }
   },
 );