qiksy-mcp 1.45.0 → 1.47.0

package/connect.mjs

@@ -122,6 +122,68 @@ export function portInPlace(targets) {
   return 0;
 }
 
+/**
+ * THE PAIRING, FOR A COMMAND THAT HAS NO ENVIRONMENT — i.e. the finish hook.
+ *
+ * The server proper is started BY the agent, which hands it the token in the entry's `env` block.
+ * A Stop hook is not started that way: it is a bare command in a bare shell, so QIKSY_MCP_TOKEN is
+ * empty, the hub closes the unauthenticated join — correctly — and the hook then fails in the one
+ * way nobody notices: silently, once per run, into a log no one reads. Measured on a real setup
+ * (21.09.2026): `npx qiksy-mcp done` answered «the bridge closed the connection» and the browser
+ * never heard a thing, while the same command with the token in front of it rang through.
+ *
+ * So the hook reads the same pairing the agent itself uses. `~/.claude.json` is in the search
+ * because that is where `claude mcp add` puts an entry — top level, or under projects/<cwd> — and
+ * it is READ ONLY here: connect writes `.mcp.json` instead, and a command that fires on every stop
+ * must never rewrite the file that holds every project's servers.
+ */
+export function pairingInPlace({ dir = process.cwd(), home = homedir(), platform = osPlatform() } = {}) {
+  const targets = agentTargets({ dir, home, platform });
+  const found = { token: tokenInPlace(targets), port: portInPlace(targets) };
+  if (found.token && found.port) return found;
+
+  for (const entry of claudeJsonEntries(join(home, '.claude.json'), dir)) {
+    const tok = entry?.env?.QIKSY_MCP_TOKEN;
+    if (!found.token && typeof tok === 'string' && tok.length >= 16) found.token = tok;
+    if (!found.port) {
+      const args = Array.isArray(entry?.args) ? entry.args : [];
+      const i = args.indexOf('--port');
+      const p = i !== -1 ? Number(args[i + 1]) : NaN;
+      if (Number.isInteger(p) && p > 0) found.port = p;
+    }
+    if (found.token && found.port) break;
+  }
+  return found;
+}
+
+/**
+ * Every qiksy entry in `~/.claude.json`, THE ONE FOR THIS FOLDER FIRST.
+ *
+ * Order is the whole point: the token is the same everywhere (the popup has one field), but the
+ * PORT is per project, and a hook that picks a neighbouring project's port rings a bridge that
+ * belongs to somebody else's run. Deepest matching project path wins, then the global entry, then
+ * whatever else is there — the last one so a folder that was never connected still finds the
+ * pairing instead of going silent.
+ */
+function claudeJsonEntries(file, dir) {
+  let json;
+  try {
+    json = JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return []; // missing or hand-broken: not our file to fix, and not a reason to fail
+  }
+  const projects = json?.projects && typeof json.projects === 'object' ? json.projects : {};
+  const mine = Object.keys(projects)
+    .filter((p) => dir === p || dir.startsWith(`${p}/`))
+    .sort((a, b) => b.length - a.length);
+  const rest = Object.keys(projects).filter((p) => !mine.includes(p));
+  const out = [];
+  for (const p of mine) if (projects[p]?.mcpServers?.qiksy) out.push(projects[p].mcpServers.qiksy);
+  if (json?.mcpServers?.qiksy) out.push(json.mcpServers.qiksy);
+  for (const p of rest) if (projects[p]?.mcpServers?.qiksy) out.push(projects[p].mcpServers.qiksy);
+  return out;
+}
+
 /** 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);
@@ -131,6 +193,43 @@ export function writeEntry(target, entry) {
   return existed ? 'updated' : 'created';
 }
 
+/**
+ * THE EXACT FINISH SIGNAL, for the one client that can give it.
+ *
+ * `qa_done` makes the tab pulse and the sound play, and the agent is asked to call it. The server
+ * also says it by itself after a long enough silence — but silence is an estimate, and Claude Code
+ * knows the real thing: it fires a `Stop` hook the moment the agent actually stops. One line in
+ * the project's settings turns the estimate into a fact.
+ *
+ * THREE RULES, and they are what makes writing into somebody's settings acceptable at all:
+ *   · everything already in the file survives, including other Stop hooks;
+ *   · running it twice adds nothing — the same command is recognised and left alone;
+ *   · it is reported out loud by the caller, because a command that will run on every stop is not
+ *     something to install quietly.
+ */
+export const STOP_COMMAND = 'npx qiksy-mcp done';
+
+export function stopHookFile(dir) {
+  return join(dir, '.claude', 'settings.json');
+}
+
+export function writeStopHook(file, command = STOP_COMMAND) {
+  const { json, existed } = readConfig(file);
+  const hooks = { ...(json.hooks || {}) };
+  const stop = Array.isArray(hooks.Stop) ? [...hooks.Stop] : [];
+  /* Already there — from a previous run, or written by hand. Adding a second copy would make the
+     browser say «done» twice for one stop. */
+  const has = stop.some((g) =>
+    Array.isArray(g?.hooks) && g.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('qiksy-mcp done')),
+  );
+  if (has) return 'already there';
+  stop.push({ hooks: [{ type: 'command', command }] });
+  hooks.Stop = stop;
+  mkdirSync(join(file, '..'), { recursive: true });
+  writeFileSync(file, `${JSON.stringify({ ...json, hooks }, 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++) {
@@ -173,11 +272,18 @@ 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 } = {}) {
+export async function connectAgents({ dir = process.cwd(), home = homedir(), platform = osPlatform(), port, token, hook = true } = {}) {
   const targets = agentTargets({ home, platform, dir });
   const installed = targets.filter((t) => existsSync(t.needs));
-  const keptToken = token || tokenInPlace(targets);
-  const keptPort = port || portInPlace(targets);
+  /* THE SEARCH FOR AN EXISTING PAIRING IS WIDER THAN THE LIST WE WRITE INTO, and that is the whole
+     point of it. `claude mcp add` puts the entry in ~/.claude.json, which is not a file connect
+     writes; looking only at its own targets, a re-run found nothing, minted a FRESH token and wrote
+     it everywhere — leaving the browser paired with a secret nobody holds any more. It costs the
+     person a «Token rejected» on the next restart and a trip to the popup, for a command they ran
+     to fix something else. Seen live on the owner's own machine, 21.09.2026. */
+  const inPlace = pairingInPlace({ dir, home, platform });
+  const keptToken = token || inPlace.token;
+  const keptPort = port || inPlace.port;
   const usePort = keptPort || (await freePort());
   const useToken = keptToken || mintToken();
   const entry = serverEntry({ port: usePort, token: useToken, platform });
@@ -191,6 +297,18 @@ export async function connectAgents({ dir = process.cwd(), home = homedir(), pla
       failed.push({ ...t, error: e.message });
     }
   }
+  /* Only where Claude Code actually is: the hook lives in the same project this just wrote a
+     `.mcp.json` into, and writing one into a folder with no agent in it is litter. */
+  let stopHook = null;
+  if (hook && installed.some((t) => t.id === 'claude-code')) {
+    const file = stopHookFile(dir);
+    try {
+      stopHook = { file, action: writeStopHook(file), command: STOP_COMMAND };
+    } catch (e) {
+      stopHook = { file, error: e.message };
+    }
+  }
+
   return {
     port: usePort,
     token: useToken,
@@ -198,6 +316,7 @@ export async function connectAgents({ dir = process.cwd(), home = homedir(), pla
     entry,
     wrote,
     failed,
+    stopHook,
     skipped: targets.filter((t) => !installed.includes(t)),
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qiksy-mcp",
-  "version": "1.45.0",
+  "version": "1.47.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

@@ -35,7 +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';
+import { connectAgents, toClipboard, pairingInPlace } from './connect.mjs';
 
 const log = (...a) => console.error('[qiksy-mcp]', ...a);
 
@@ -723,6 +723,9 @@ async function runConnect(argv, { after = false } = {}) {
       dir: resolve(flag('--dir') || process.cwd()),
       port: Number(flag('--port')) || 0,
       token: flag('--token') || '',
+      /* A hook RUNS A COMMAND every time the agent stops, which is more than an MCP entry does —
+         so there is a way to say no without giving up the rest of the setup. */
+      hook: !argv.includes('--no-hook'),
     });
   } catch (e) {
     console.error(`qiksy-mcp connect: ${e.message}`);
@@ -738,6 +741,14 @@ async function runConnect(argv, { after = false } = {}) {
   }
   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}`);
+  /* SAID OUT LOUD, ALWAYS. This one installs a command that will run on every stop — quietly
+     doing that is how a helpful tool becomes one people distrust. */
+  if (r.stopHook?.error) console.error(`  could not add the finish hook → ${r.stopHook.file}: ${r.stopHook.error}`);
+  else if (r.stopHook) {
+    say(`✓ ${r.stopHook.action} a finish hook in Claude Code → ${r.stopHook.file}`);
+    say(`  It runs \`${r.stopHook.command}\` when the agent stops, so the tab pulses and the sound`);
+    say('  plays the moment a run really ends. Remove that line, or re-run with --no-hook, to skip it.');
+  }
 
   const clip = toClipboard(r.token);
   say(`
@@ -844,17 +855,26 @@ if (process.argv[2] === 'done') {
    * loudly because the browser is closed would be a hook people remove.
    */
   const bad = process.argv.includes('--problem');
-  const said = await new Promise((res) => {
+
+  /* ONE ATTEMPT WITH ONE PAIRING. Resolves to the sentence to print, plus `refused` when the hub
+     shut the door on us — which is the only failure worth trying a second key on. */
+  const ring = (token, port) => new Promise((res) => {
     let ws;
-    const give = (msg) => { try { ws?.close(); } catch { /* already gone */ } res(msg); };
+    let answered = false;
+    const give = (said, refused = false) => {
+      if (answered) return;
+      answered = true;
+      try { ws?.close(); } catch { /* already gone */ }
+      res({ said, refused });
+    };
     const timer = setTimeout(() => give('no answer from the bridge'), 6000);
     try {
-      ws = new WebSocket(`ws://${HOST}:${PORT}`);
+      ws = new WebSocket(`ws://${HOST}:${port}`);
     } catch {
       clearTimeout(timer);
-      return res('could not reach the bridge');
+      return give('could not reach the bridge');
     }
-    ws.on('open', () => ws.send(JSON.stringify({ t: 'join', v: PROTOCOL_VERSION, token: TOKEN, pid: process.pid })));
+    ws.on('open', () => ws.send(JSON.stringify({ t: 'join', v: PROTOCOL_VERSION, token, pid: process.pid })));
     ws.on('message', (raw) => {
       let m;
       try { m = JSON.parse(raw.toString()); } catch { return; }
@@ -862,9 +882,45 @@ if (process.argv[2] === 'done') {
       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'); });
+    /* Closed before an answer = the token was refused. The hub says nothing more, by design: it
+       is an authentication gate, and a gate that explains itself is a gate that helps a stranger. */
+    ws.on('close', () => { clearTimeout(timer); give('the bridge closed the connection — the token it holds is a different one', true); });
   });
-  log(said);
+
+  /* TWO PLACES A TOKEN CAN COME FROM, AND THE ENVIRONMENT IS NOT THE TRUSTWORTHY ONE.
+   *
+   * A hook runs in a bare shell: no `env` block from the agent, so usually nothing — and sometimes
+   * WORSE than nothing, because an old QIKSY_MCP_TOKEN left in a .zshenv from a previous setup is
+   * exported into every shell on the machine and looks exactly like configuration. Found on the
+   * owner's own machine 21.09.2026: the shell carried a token three generations old, the hub
+   * refused it, and the command reported «the bridge closed the connection» — which reads as a
+   * browser problem, so the search starts in the popup, which was never wrong.
+   *
+   * So the environment is tried FIRST (an explicit export must still win when it is right), and a
+   * refusal falls through to the pairing the agent itself is using. Two attempts, never more. */
+  const tries = [];
+  if (TOKEN) tries.push({ token: TOKEN, port: PORT, from: 'the environment' });
+  const p = pairingInPlace({ dir: process.cwd() });
+  if (p.token && p.token !== TOKEN) {
+    const own = portArg === -1 && !process.env.QIKSY_MCP_PORT && p.port ? p.port : PORT;
+    tries.push({ token: p.token, port: own, from: 'your agent config' });
+  }
+  if (!tries.length) {
+    /* Naming the missing half, because «the bridge closed the connection» sent the last person
+       looking at the browser — the one part that was working. */
+    log('no token: set QIKSY_MCP_TOKEN, or run `npx qiksy-mcp connect` in this project first');
+    process.exit(0);
+  }
+
+  let last = '';
+  for (const t of tries) {
+    const r = await ring(t.token, t.port);
+    last = r.said;
+    if (!r.refused) break;
+    /* Said out loud only when there IS a second key to try — otherwise it is noise on every stop. */
+    if (t !== tries[tries.length - 1]) log(`the token in ${t.from} was refused — trying the one in your agent config`);
+  }
+  log(last);
   process.exit(0);
 }
 
@@ -1158,6 +1214,65 @@ function onConnection(ws, req) {
 /** What the person set the panel to — filled in by the first reply that carries it. */
 let uiLanguage = '';
 
+/**
+ * THE END OF A RUN, WITHOUT ANYBODY HAVING TO REMEMBER IT.
+ *
+ * `qa_done` is the verb that makes the tab pulse and the sound play, and the agent is asked to
+ * call it in the instructions handed over at connect. An instruction is a request, though, not a
+ * mechanism: some clients follow it, some do not, and every agent already installed has the old
+ * habit. So the person updates, everything is switched on by default — and hears nothing. That is
+ * the state this exists to prevent (owner, 21.09.2026).
+ *
+ * What this process CAN observe is the same thing the voice already watches: it timestamps every
+ * call and knows when the last one finished. A run that did real work and then went quiet past a
+ * threshold is over in every sense that matters to somebody in the next room.
+ *
+ * IT IS AN ESTIMATE, AND IT IS BUILT TO BE WRONG SAFELY. Three things make a premature signal
+ * cheap rather than annoying, and none of them are new — they all shipped with the verb:
+ *   · the extension refuses to sound when no work has been recorded;
+ *   · it refuses to sound twice within half a minute;
+ *   · ANY later call stops the pulse, so an agent that was merely thinking cancels the signal by
+ *     carrying on — the mistake undoes itself without anybody touching anything.
+ * The exact path — a Stop hook running `npx qiksy-mcp done` — stays available for clients that
+ * have one, and is what `init` writes. This is the floor under it, not a replacement.
+ */
+const DONE_AFTER_MS = (() => {
+  const raw = process.env.QIKSY_MCP_DONE_AFTER;
+  if (raw === '0' || /^(off|no|false)$/i.test(raw || '')) return 0;
+  const n = Number(raw);
+  /* Below twenty seconds this would fire inside an ordinary pause for thought, so a smaller
+     number is read as a mistake and the default is used instead. */
+  return Number.isFinite(n) && n >= 20 ? n * 1000 : 90_000;
+})();
+let doneTimer = null;
+let workSinceDone = false;
+
+function fireDone() {
+  doneTimer = null;
+  if (!workSinceDone) return;
+  workSinceDone = false;
+  log(`▸ quiet for ${Math.round(DONE_AFTER_MS / 1000)}s after a run — saying it has finished`);
+  /* Failure here is nothing: the browser may have gone, the tab may have closed. The pulse is a
+     courtesy, and a courtesy that throws is worse than one that does not happen. */
+  callExtension('qa_done', { verdict: 'ok' }, 8_000).catch(() => {});
+}
+
+/** Called when a call FINISHES, not when it starts: a slow verb must not look like silence. */
+function armDone(tool) {
+  if (!DONE_AFTER_MS) return;
+  if (doneTimer) clearTimeout(doneTimer);
+  doneTimer = null;
+  if (tool === 'qa_done') {
+    /* Said out loud already — nothing left to announce until there is new work. */
+    workSinceDone = false;
+    return;
+  }
+  workSinceDone = true;
+  doneTimer = setTimeout(fireDone, DONE_AFTER_MS);
+  /* A pending timer must never be the reason this process stays alive. */
+  doneTimer.unref?.();
+}
+
 function callExtension(tool, args, timeoutMs = 15_000) {
   // The same choke point is where the voice watches the session: one place, both roles.
   noticedCall(tool);
@@ -1165,6 +1280,7 @@ function callExtension(tool, args, timeoutMs = 15_000) {
     p.then(
       (r) => {
         noticedResult(tool, r);
+        armDone(tool);
         /* THE HUMAN'S LANGUAGE, learned rather than guessed. This process never sees the
            conversation, so it cannot know what language they write in — but they told the panel
            directly by choosing one, and the extension sends that along with every bundle. One
@@ -1175,6 +1291,9 @@ function callExtension(tool, args, timeoutMs = 15_000) {
       },
       (e) => {
         noticedResult(tool, null);
+        /* A call that FAILED is still the agent having been here — the run is just as over when
+           the last thing it did did not work. */
+        armDone(tool);
         throw e;
       },
     );