qiksy-mcp 1.1.1 → 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.1",
+  "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"
   },