qiksy-mcp 1.41.0 → 1.43.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.41.0`** — the current build, with all sixty-one tools
+**npm carries `qiksy-mcp@1.43.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,
@@ -241,6 +241,33 @@ Qiksy runs several logins on one domain at once — one per tab, each with its o
 
 ## Setup
 
+### The short way: one command
+
+```bash
+npx qiksy-mcp connect
+```
+
+Run it **in the project you work in**. It picks a free port, mints a token, writes the `qiksy`
+server into every agent config it finds on the machine — Claude Code (`.mcp.json`), Cursor
+(`~/.cursor/mcp.json`), VS Code (`.vscode/mcp.json`, which uses its own `servers` key), Windsurf,
+Claude Desktop — and puts the token on your clipboard. Then: **popup → Agent bridge → On → paste**,
+restart the agent, ask it to call `qa_status`.
+
+`npx qiksy-mcp init` does the same **and** writes the agent guide into the project, which is what
+stops your agent proposing Playwright on the first unfamiliar field. Use `init` the first time.
+
+What it will not do: it writes a config **only where that client's own folder already exists**, so
+you never get a Windsurf config for an editor you do not have; it keeps every other server already
+in those files; it refuses to touch a config it cannot parse rather than overwriting it; and on a
+second run it **keeps the token that is already there**, so a browser you have already paired stays
+paired. On Windows the entry is written as `cmd /c npx …`, which is the form that actually starts —
+a bare `npx` fails in about half the clients there.
+
+Flags: `--dir <path>` (which project), `--port <n>`, `--token <value>`, and `--no-connect` on
+`init` if you want the guide without the wiring.
+
+### The manual way
+
 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).

package/connect.mjs

@@ -0,0 +1,203 @@
+/**
+ * `npx qiksy-mcp connect` — THE SIX STEPS BECOME ONE.
+ *
+ * Owner, 20.09.2026: «QA ленивые, технически многие вообще не шарят — как к блютузу бы».
+ * Measured against the old path, a person had to: switch the bridge on, accept, press Generate,
+ * press Copy, FIND their agent's config file, paste JSON into it without breaking the JSON, and
+ * restart the agent. Two of those steps are ours and five are theirs — and the file one is where
+ * they stop, because «~/.cursor/mcp.json» means nothing to somebody who tests web shops for a
+ * living.
+ *
+ * This process is the one thing that already lives on their machine AND is allowed to write
+ * files, so it does the whole middle: picks a free port, mints the token, finds every agent that
+ * is actually installed, writes the entry into each config it found, and leaves the token on the
+ * clipboard so the popup is one ⌘V away. The extension cannot do any of that — no filesystem, no
+ * processes — which is why this belongs here and not in the popup.
+ *
+ * Three rules it does not break:
+ *   · nothing is invented. A config is written ONLY where that client's own folder already
+ *     exists, so nobody ends up with a Windsurf config for an editor they never installed.
+ *   · nothing of theirs is lost. The file is read, our one entry is set, everything else is
+ *     written back untouched — and a run on a file we cannot parse stops rather than overwrites.
+ *   · the pairing survives. A second run keeps the token that is already in their config, or the
+ *     browser they already paired would be locked out by a fresh secret.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir, platform as osPlatform } from 'node:os';
+import { join } from 'node:path';
+import { createServer } from 'node:net';
+import { spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+
+/**
+ * WHERE EACH AGENT KEEPS ITS SERVER LIST.
+ *
+ * `home` and `platform` are arguments rather than reads so a test can ask for the Windows answer
+ * on a Mac — the paths are the part that goes wrong silently, and they are unreachable otherwise.
+ *
+ * `key` differs by client and is NOT cosmetic: VS Code reads `servers`, everyone else reads
+ * `mcpServers`, and a file written with the wrong key is valid JSON that the agent ignores — the
+ * worst possible failure, because it looks installed.
+ *
+ * `needs` is the folder whose existence means the client is installed. Missing → skipped, which
+ * is how «wrote 4 configs» stops being a lie on a machine with one editor.
+ */
+export function agentTargets({ home = homedir(), platform = osPlatform(), dir = process.cwd() } = {}) {
+  const appData = process.env.APPDATA || join(home, 'AppData', 'Roaming');
+  const claudeDesktop =
+    platform === 'win32'
+      ? join(appData, 'Claude', 'claude_desktop_config.json')
+      : platform === 'darwin'
+        ? join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')
+        : join(home, '.config', 'Claude', 'claude_desktop_config.json');
+
+  return [
+    /* Claude Code reads a project-scoped .mcp.json — the file belongs to the repo the person is
+       standing in, which is also the repo their agent is working on. */
+    { id: 'claude-code', label: 'Claude Code', file: join(dir, '.mcp.json'), key: 'mcpServers', needs: dir, scope: 'project' },
+    { id: 'cursor', label: 'Cursor', file: join(home, '.cursor', 'mcp.json'), key: 'mcpServers', needs: join(home, '.cursor'), scope: 'user' },
+    { id: 'vscode', label: 'VS Code', file: join(dir, '.vscode', 'mcp.json'), key: 'servers', needs: join(dir, '.vscode'), scope: 'project' },
+    { id: 'windsurf', label: 'Windsurf', file: join(home, '.codeium', 'windsurf', 'mcp_config.json'), key: 'mcpServers', needs: join(home, '.codeium', 'windsurf'), scope: 'user' },
+    { id: 'claude-desktop', label: 'Claude Desktop', file: claudeDesktop, key: 'mcpServers', needs: join(claudeDesktop, '..'), scope: 'user' },
+  ];
+}
+
+/**
+ * THE ENTRY ITSELF — and on Windows it is not the obvious one.
+ *
+ * `command: "npx"` is what every example shows and what fails on Windows for a good half of the
+ * clients: `npx` there is `npx.cmd`, and a spawn without a shell does not find it. The result is
+ * an agent that reports the server as failed to start with no explanation a tester can act on.
+ * So Windows gets the `cmd /c` form, which works in both the clients that need it and those that
+ * would have coped anyway.
+ */
+export function serverEntry({ port, token, platform = osPlatform() }) {
+  const base = platform === 'win32'
+    ? { command: 'cmd', args: ['/c', 'npx', 'qiksy-mcp', '--port', String(port)] }
+    : { command: 'npx', args: ['qiksy-mcp', '--port', String(port)] };
+  return { ...base, env: { QIKSY_MCP_TOKEN: token } };
+}
+
+/** Read a config we are about to edit. Unreadable JSON is an error, never something to overwrite. */
+export function readConfig(file) {
+  if (!existsSync(file)) return { json: {}, existed: false };
+  const raw = readFileSync(file, 'utf8').trim();
+  if (!raw) return { json: {}, existed: true };
+  try {
+    return { json: JSON.parse(raw), existed: true };
+  } catch (e) {
+    throw new Error(`${file} is not valid JSON (${e.message}) — fix or move it, I will not overwrite it`);
+  }
+}
+
+/** The token already wired into one of their configs, if any: a second run must not break the pair. */
+export function tokenInPlace(targets) {
+  for (const t of targets) {
+    try {
+      if (!existsSync(t.file)) continue;
+      const { json } = readConfig(t.file);
+      const tok = json?.[t.key]?.qiksy?.env?.QIKSY_MCP_TOKEN;
+      if (typeof tok === 'string' && tok.length >= 16) return tok;
+    } catch {
+      /* a broken file is reported later by the write; it must not stop the search */
+    }
+  }
+  return '';
+}
+
+/** The port already wired in, for the same reason: re-running must not move the browser's target. */
+export function portInPlace(targets) {
+  for (const t of targets) {
+    try {
+      if (!existsSync(t.file)) continue;
+      const { json } = readConfig(t.file);
+      const args = json?.[t.key]?.qiksy?.args;
+      const i = Array.isArray(args) ? args.indexOf('--port') : -1;
+      const p = i !== -1 ? Number(args[i + 1]) : NaN;
+      if (Number.isInteger(p) && p > 0) return p;
+    } catch {
+      /* same */
+    }
+  }
+  return 0;
+}
+
+/** Write our one entry, keep everything else in the file exactly as it was. */
+export function writeEntry(target, entry) {
+  const { json, existed } = readConfig(target.file);
+  const next = { ...json, [target.key]: { ...(json[target.key] || {}), qiksy: entry } };
+  mkdirSync(join(target.file, '..'), { recursive: true });
+  writeFileSync(target.file, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+  return existed ? 'updated' : 'created';
+}
+
+/** A port nothing is listening on, starting where the docs say and walking up a short way. */
+export async function freePort(from = 7333, tries = 12) {
+  for (let p = from; p < from + tries; p++) {
+    const ok = await new Promise((res) => {
+      const s = createServer();
+      s.once('error', () => res(false));
+      s.once('listening', () => s.close(() => res(true)));
+      s.listen(p, '127.0.0.1');
+    });
+    if (ok) return p;
+  }
+  return from;
+}
+
+/**
+ * THE TOKEN GOES TO THE CLIPBOARD, because the last step is a paste into the popup.
+ * Best effort by design: a headless Linux box has no clipboard, and that is not a failure of the
+ * setup — the token is printed as well, and the report says which of the two happened.
+ */
+export function toClipboard(text, platform = osPlatform()) {
+  const runners = platform === 'darwin'
+    ? [['pbcopy', []]]
+    : platform === 'win32'
+      ? [['clip', []]]
+      : [['wl-copy', []], ['xclip', ['-selection', 'clipboard']], ['xsel', ['--clipboard', '--input']]];
+  for (const [cmd, args] of runners) {
+    try {
+      const r = spawnSync(cmd, args, { input: text, shell: platform === 'win32' });
+      if (!r.error && r.status === 0) return cmd;
+    } catch {
+      /* try the next one */
+    }
+  }
+  return '';
+}
+
+export const mintToken = () => randomBytes(18).toString('base64url');
+
+/**
+ * Do the whole thing and report what happened. No printing here — the caller owns the voice, and
+ * a function that both decides and narrates cannot be tested without reading its output.
+ */
+export async function connectAgents({ dir = process.cwd(), home = homedir(), platform = osPlatform(), port, token } = {}) {
+  const targets = agentTargets({ home, platform, dir });
+  const installed = targets.filter((t) => existsSync(t.needs));
+  const keptToken = token || tokenInPlace(targets);
+  const keptPort = port || portInPlace(targets);
+  const usePort = keptPort || (await freePort());
+  const useToken = keptToken || mintToken();
+  const entry = serverEntry({ port: usePort, token: useToken, platform });
+
+  const wrote = [];
+  const failed = [];
+  for (const t of installed) {
+    try {
+      wrote.push({ ...t, action: writeEntry(t, entry) });
+    } catch (e) {
+      failed.push({ ...t, error: e.message });
+    }
+  }
+  return {
+    port: usePort,
+    token: useToken,
+    reusedToken: !!keptToken,
+    entry,
+    wrote,
+    failed,
+    skipped: targets.filter((t) => !installed.includes(t)),
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qiksy-mcp",
-  "version": "1.41.0",
+  "version": "1.43.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",
@@ -35,6 +35,7 @@
     "gaps.mjs",
     "gallery.mjs",
     "svg-shot.mjs",
+    "connect.mjs",
     "diff.mjs",
     "README.md",
     "AGENT-GUIDE.md"

package/server.mjs

@@ -35,6 +35,7 @@ import { project } from './project.mjs';
 import { recordGap, listGaps, gapInvite, GAPS_FILE } from './gaps.mjs';
 import { STATES, STATE_KEYS, renderGallery } from './gallery.mjs';
 import { renderSearchableSvg } from './svg-shot.mjs';
+import { connectAgents, toClipboard } from './connect.mjs';
 
 const log = (...a) => console.error('[qiksy-mcp]', ...a);
 
@@ -669,7 +670,7 @@ function installDocs({ dir, out, withClaude = true }) {
   return report;
 }
 
-function runInit(argv) {
+async function runInit(argv) {
   const flag = (name) => {
     const i = argv.indexOf(name);
     return i !== -1 ? argv[i + 1] : undefined;
@@ -695,15 +696,60 @@ function runInit(argv) {
   for (const t of report.touched) say(`✓ ${t.action} the Qiksy block in ${t.file}`);
   for (const f of report.failed) console.error(`  could not write ${f.file} — ${f.error}`);
 
+  if (!argv.includes('--no-connect')) await runConnect(argv, { after: true });
+}
+
+/**
+ * THE WIRING, DONE BY THE THING THAT IS ALLOWED TO WRITE FILES.
+ *
+ * What used to be printed here was three steps in a terminal and a JSON file to edit by hand, and
+ * that file is where people stop (owner, 20.09.2026: «технически многие вообще не шарят»). The
+ * extension cannot do it — no filesystem, no processes — and the person should not have to, so
+ * this process does: free port, token, every installed agent's config written, token on the
+ * clipboard for the one paste that is left.
+ *
+ * It says what it TOUCHED and what it skipped, because a setup tool that writes into somebody's
+ * machine and reports only success is the kind you uninstall.
+ */
+async function runConnect(argv, { after = false } = {}) {
+  const flag = (name) => {
+    const i = argv.indexOf(name);
+    return i !== -1 ? argv[i + 1] : undefined;
+  };
+  const say = (...a) => console.log(...a);
+  let r;
+  try {
+    r = await connectAgents({
+      dir: resolve(flag('--dir') || process.cwd()),
+      port: Number(flag('--port')) || 0,
+      token: flag('--token') || '',
+    });
+  } catch (e) {
+    console.error(`qiksy-mcp connect: ${e.message}`);
+    process.exit(1);
+  }
+
+  say(after ? '' : '');
+  if (!r.wrote.length) {
+    say('No agent config found to write into. Looked for:');
+    for (const s of r.skipped) say(`  · ${s.label} → ${s.file}`);
+    say('\nOpen the project you work in and run this there, or paste the block from');
+    say('https://qiksy.app/qa-copilot/ into your agent yourself.');
+  }
+  for (const w of r.wrote) say(`✓ ${w.action} the qiksy server in ${w.label} → ${w.file}`);
+  for (const f of r.failed) console.error(`  could not write ${f.label} → ${f.file}: ${f.error}`);
+
+  const clip = toClipboard(r.token);
   say(`
-Next, if you have not already:
-  1. Qiksy popup → "Agent bridge · MCP" → On → Generate a token.
-  2. claude mcp add --transport stdio qiksy --env QIKSY_MCP_TOKEN=<token> -- npx qiksy-mcp --port ${PORT}
-     (or the .mcp.json / VS Code / Zed block from https://qiksy.app/qa-copilot/)
-  3. Restart the agent and call qa_status. It should answer with the page you are looking at.
-
-"Qiksy extension is not connected" means the popup toggle is off or the token/port differ —
-it never means you should reach for another browser driver.`);
+Port ${r.port}${r.reusedToken ? ' · kept the token already in your config' : ' · new token'}.
+
+One step left, in the browser:
+  Qiksy popup → "Agent bridge · MCP" → On → paste the token${clip ? ' (it is on your clipboard)' : ''}.${clip ? '' : `\n  Token: ${r.token}`}
+  Then restart your agent and ask it to call qa_status.
+
+The token never leaves this machine: it is what stops another local program from pretending to be
+your browser. "Qiksy extension is not connected" means the popup toggle is off or the token and
+port differ — it never means you should reach for another browser driver.`);
 }
 
 /**
@@ -763,8 +809,20 @@ function autoInstallDocs() {
   }
 }
 
+/* BOTH SUBCOMMANDS END THE PROCESS, AND THE AWAIT IS THE POINT.
+ *
+ * Everything below this line boots a stdio MCP server. The first cut fired the async connect and
+ * carried on, so `connect` wired the configs AND announced «MCP stdio server ready» — a setup
+ * command turning itself into a bridge nobody asked for (seen in the first live run). Top-level
+ * await holds the module here until the work is done, and then the process leaves. */
 if (process.argv[2] === 'init') {
-  runInit(process.argv.slice(3));
+  await runInit(process.argv.slice(3));
+  process.exit(0);
+}
+if (process.argv[2] === 'connect') {
+  /* The wiring on its own, for somebody who already has the guide and just wants the link up
+     (or is redoing it after changing editors). `init` runs both. */
+  await runConnect(process.argv.slice(3));
   process.exit(0);
 }
 
@@ -5808,6 +5866,44 @@ server.registerTool(
   },
 );
 
+/**
+ * HOVER — the state every other verb here passes through and none of them stays in.
+ *
+ * Asked for by the owner on 17.09.2026 while testing with the bridge, and the gap was real: the
+ * only verb that sent a `mouseover` was `qa_click`, which sends a `mousedown` a millisecond
+ * later. So a menu that opens on hover was opened and closed by the same call, and a tooltip
+ * could not be read at all. Hover is not a weaker click — it is a different state, and a large
+ * part of what a tester checks lives only inside it.
+ */
+server.registerTool(
+  'qa_hover',
+  {
+    title: 'Hover over an element and hold (Pro)',
+    description:
+      'Put the pointer on an element AND LEAVE IT THERE, then report what that revealed: a menu that opens on hover, a tooltip, the actions a row only shows under the pointer, the value a chart reads out beneath it. qa_click cannot answer any of those — it presses a millisecond after it hovers, and the press closes what the hover opened. ' +
+      'It holds for `holdMs` (500 by default) before measuring, because tooltips wait — measuring at once reports "no tooltip" about one that was always going to appear. The reply carries the usual `changed` diff plus `tooltip` (role=tooltip, aria-describedby or title, whichever exists) and `expanded` when the control changed its aria-expanded. ' +
+      'ONE FACT TO READ CAREFULLY: `cssHover` says whether the browser\'s own `:hover` matched. Dispatched events run the page\'s JavaScript handlers — every menu and tooltip library — but they do not move the real cursor, so an effect written PURELY in CSS does not appear and `cssHover` comes back false. That is the tool being honest, not the page being broken. With trusted input switched on the real pointer moves, `cssHover` is true, and CSS-only hovers light up too. ' +
+      'Call it again with `off: true` to take the pointer away — "the tooltip disappears" is the other half of the check, and it needs its own call.' +
+      DRIVE_NOTE,
+    inputSchema: {
+      tabId: tabIdArg,
+      selector: z.string().optional().describe('CSS selector of the element to hover'),
+      ref: z.string().optional().describe('A ref from qa_snapshot (e.g. "e12") — preferred over selector'),
+      x: z.number().optional().describe('Without ref/selector: CSS pixels from the LEFT of the viewport. WITH one: an offset inside the element, for a chart or a split control where the middle is the wrong place.'),
+      y: z.number().optional().describe('Without ref/selector: CSS pixels from the TOP of the viewport. WITH one: an offset inside the element.'),
+      holdMs: z.number().optional().describe('How long to hold the pointer there before measuring (0–10000, default 500)'),
+      off: z.boolean().optional().describe('Take the pointer AWAY from whatever it is on, and report what was left. No target needed.'),
+    },
+  },
+  async ({ tabId, selector, ref, x, y, holdMs, off }) => {
+    try {
+      return asText(await callExtension('qa_hover', { tabId, selector, ref, x, y, holdMs, off }, 30_000));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
 server.registerTool(
   'qa_click',
   {