qiksy-mcp 0.1.0

package/README.md

@@ -0,0 +1,164 @@
+# qiksy-mcp
+
+An **MCP (Model Context Protocol) bridge** for the [Qiksy](../) browser extension. It lets any MCP-capable coding agent — **Claude Code, Cursor, Cline, Windsurf, Zed, VS Code** — read the live QA state (findings with CSS selectors, detected forms, failed requests with server error bodies, recorded repro steps) straight from the browser, so you can say *"fix what Qiksy found on this page"* and the agent has the full context.
+
+The agent can also **drive Qiksy's own surfaces**: open the panel, run the audit, pull the exploratory-tour checklist, generate the session report, and spotlight an element. What it **never** does is act on the **app under test** — no filling, clicking, submitting, or navigating the page you're testing. Qiksy senses and reports; a human (or a purpose-built driver like [Playwright MCP](#driving-the-browser-pair-with-playwright-mcp)) does the driving. This boundary is deliberate — it's what keeps a QA tool that watches *other people's* apps trustworthy.
+
+## How it works
+
+```
+agent  ⟷ (MCP over stdio, JSON-RPC)  ⟷  qiksy-mcp  ⟷ (WebSocket @ 127.0.0.1)  ⟷  extension service worker
+```
+
+The extension is the WebSocket **client** (a service worker can't listen on a socket); this process is the WebSocket **server**, bound to loopback only. When the agent calls a tool, this process asks the extension for the current tab's `qa-export/v1` bundle and returns it.
+
+## Tools
+
+**Read** — sense the page (all accept an optional `tabId` from `qa_tabs`; default = active tab):
+
+| Tool          | What it returns |
+|---------------|-----------------|
+| `qa_tabs`     | Every browser tab Qiksy can read, incl. which are **isolated multi-login sessions** (`isolatedSession` = the login name). Use a tab's `tabId` with the other tools to read that specific login. |
+| `qa_status`   | URL + error/warning/form counts + isolated-login name. |
+| `qa_findings` | Findings (with selectors + detail); `severity` = `all` \| `error` \| `warning`. |
+| `qa_export`   | The full `qa-export/v1` bundle: findings, failed requests + bodies, form structure, repro steps, env. |
+
+**Command** — drive Qiksy's own UI / analysis (never the app under test; all accept `tabId`):
+
+| Tool            | What it does |
+|-----------------|--------------|
+| `qa_open_panel` | Open/close the Qiksy side panel and optionally jump to a tab (`forms` \| `findings` \| `tour` \| `tools` \| `history` \| `roles`). |
+| `qa_run_audit`  | Run the a11y/markup audit on the current DOM and return the findings (also refreshes the panel). Static, read-only DOM analysis. |
+| `qa_tour`       | Return the generated exploratory-testing checklist (from forms + interactive surfaces), auto-checked from the recorded session — raw material for test cases. Markdown + structured items. |
+| `qa_report`     | Generate Qiksy's self-contained HTML session report and return the HTML (needs History recording to have captured steps). |
+| `qa_spotlight`  | Dim + outline an element by CSS selector so the human can see what the agent means. A non-destructive overlay — no click/focus/mutation. |
+
+Because tools accept a `tabId`, an agent can read **several logins at once**: call `qa_tabs`, then `qa_export` per isolated tab to compare what admin vs. member vs. anon each see.
+
+## Driving the browser: pair with Playwright MCP
+
+Qiksy is the **QA brain** (what happened, what's wrong, coverage, reports). It does **not** click through the app for you. To let an agent also *drive* the browser, run a purpose-built driver alongside it — e.g. [Playwright MCP](https://github.com/microsoft/playwright-mcp) — and register **both** servers in your agent:
+
+```
+your agent
+  ├─ playwright-mcp   → the HANDS: click, fill, navigate the site
+  └─ qiksy-mcp        → the BRAIN: findings, form structure, network, coverage, reports
+```
+
+**Example workflow (Jira story → verified test cases):**
+
+1. Drop a Jira story/acceptance criteria into your agent.
+2. The agent uses **Playwright MCP** to walk the flow in the browser.
+3. After each step it calls **qiksy-mcp** (`qa_export`, `qa_run_audit`, `qa_findings`) to see what *actually* happened — console/JS errors, failed requests **with server bodies**, a11y/markup issues, the detected form structure.
+4. The agent reconciles the story against reality, then writes test cases (using `qa_tour` for coverage) and, if History was recording, pulls a `qa_report` as the artifact.
+
+Why not build driving into Qiksy itself? Playwright is a mature, dedicated driver, and keeping Qiksy read-and-report keeps its trust/permissions story clean. (Embedding Playwright *inside* the extension isn't possible anyway — it's an external Node automation framework, not something an MV3 extension can host.)
+
+### Wiring both servers (Playwright MCP needs a CDP browser)
+
+Playwright MCP drives a browser over the **Chrome DevTools Protocol** — a *normal* Chrome window can't be driven, you must start Chrome with a debugging port so Playwright can attach. Qiksy must be **installed in that same Chrome** (from the Web Store, or loaded unpacked) so its content scripts + bridge run there.
+
+1. **Launch Chrome with the debug port** (quit other Chrome windows first, or use a separate `--user-data-dir`):
+   ```bash
+   # macOS
+   "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222
+   # Windows:  "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
+   # Linux:    google-chrome --remote-debugging-port=9222
+   ```
+2. **In the Qiksy popup** → *MCP bridge*: **On**, **Generate** a token, **Save**.
+3. **Register both MCP servers** in your agent — one config, paste and go. Claude Code `.mcp.json` (project root):
+   ```json
+   {
+     "mcpServers": {
+       "playwright": {
+         "command": "npx",
+         "args": ["@playwright/mcp@latest", "--cdp-endpoint", "http://127.0.0.1:9222"]
+       },
+       "qiksy": {
+         "command": "npx",
+         "args": ["qiksy-mcp", "--port", "7333"],
+         "env": { "QIKSY_MCP_TOKEN": "YOUR_TOKEN" }
+       }
+     }
+   }
+   ```
+   Now the agent has **hands** (Playwright, attached to your real Chrome) and a **QA brain** (Qiksy).
+
+### Multi-login (RBAC) with the agent
+
+Qiksy runs several logins on one domain at once — one per tab, each with its own cookie jar + virtualized storage. The reliable division of labour:
+
+- **You spin up the logins** (a few clicks, one-time): Qiksy panel → **Roles** → **＋ Isolated tab** for a fresh empty session, or **⧉** on a saved role to open it isolated. (There's also an **auto-isolate** toggle per site: new tabs *you* open — Ctrl/Cmd+T — get their own session automatically. Note: tabs opened programmatically by Playwright carry an opener and are deliberately **not** auto-isolated, so they don't hijack OAuth-popup / `target=_blank` flows — create isolated logins from the Roles panel instead.)
+- **The agent reads every login at once**: `qa_tabs` lists them with `isolatedSession` = the login name and a `tabId`; then `qa_findings`/`qa_export` with that `tabId` reads each. So the agent can diff what **admin vs. member vs. anon** each see — permissions leaks, missing guards, role-specific errors — in one pass.
+- **The agent drives within a login** with Playwright MCP (click through as that user); Qiksy senses the result per tab.
+
+## Setup
+
+1. **In the extension popup** → *MCP bridge*: toggle **On**, click **Generate** for a token, pick a port (default `7333`), **Save bridge**.
+2. **Register the server in your agent** (below), using the **same token and port**. The token is passed via the `QIKSY_MCP_TOKEN` env var.
+
+The token is the only thing guarding the bridge — localhost is reachable by any local process/page, so keep it secret and unique.
+
+### Claude Code
+
+```bash
+claude mcp add --transport stdio qiksy --env QIKSY_MCP_TOKEN=YOUR_TOKEN -- npx qiksy-mcp --port 7333
+```
+
+or `.mcp.json` at the project root:
+
+```json
+{ "mcpServers": { "qiksy": {
+  "type": "stdio",
+  "command": "npx", "args": ["qiksy-mcp", "--port", "7333"],
+  "env": { "QIKSY_MCP_TOKEN": "YOUR_TOKEN" }
+} } }
+```
+
+### Cursor (`~/.cursor/mcp.json`), Windsurf (`~/.codeium/windsurf/mcp_config.json`), Cline (`cline_mcp_settings.json`)
+
+Same canonical shape:
+
+```json
+{ "mcpServers": { "qiksy": {
+  "command": "npx", "args": ["qiksy-mcp", "--port", "7333"],
+  "env": { "QIKSY_MCP_TOKEN": "YOUR_TOKEN" }
+} } }
+```
+
+### Zed (`settings.json`) — key is `context_servers`, `source` is required
+
+```json
+{ "context_servers": { "qiksy": {
+  "source": "custom",
+  "command": "npx", "args": ["qiksy-mcp", "--port", "7333"],
+  "env": { "QIKSY_MCP_TOKEN": "YOUR_TOKEN" }
+} } }
+```
+
+### VS Code native (`.vscode/mcp.json`) — top-level `servers`, `type` required
+
+```json
+{
+  "inputs": [{ "type": "promptString", "id": "qac-token", "description": "Qiksy MCP token", "password": true }],
+  "servers": { "qiksy": {
+    "type": "stdio",
+    "command": "npx", "args": ["qiksy-mcp", "--port", "7333"],
+    "env": { "QIKSY_MCP_TOKEN": "${input:qac-token}" }
+  } }
+}
+```
+
+## Local run (dev)
+
+```bash
+QIKSY_MCP_TOKEN=YOUR_TOKEN node server.mjs --port 7333
+```
+
+Logs go to **stderr** (stdout is the JSON-RPC channel). You should see `bridge listening…` and, once Chrome has the extension with the bridge enabled, `extension connected`.
+
+## Notes / limits
+
+- **One tab at a time**: tools read the *active* tab in the last-focused Chrome window. Focus the app under test.
+- **Service-worker sleep**: if Chrome idles the extension's worker, the socket drops and reconnects automatically (≤~30 s). If a tool times out, retry.
+- **Security**: bound to `127.0.0.1` only; connections without the matching token (or from a non-extension origin) are closed before any data is sent.

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "qiksy-mcp",
+  "version": "0.1.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"],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.19.0",
+    "ws": "^8.18.0",
+    "zod": "^3.24.0"
+  }
+}

package/server.mjs

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+/**
+ * qiksy-mcp — a vendor-neutral MCP (Model Context Protocol) server that
+ * bridges any MCP-capable coding agent (Claude Code, Cursor, Cline, Windsurf,
+ * Zed, VS Code) to the Qiksy browser extension.
+ *
+ * Topology:
+ *   agent  ⟷ (MCP over stdio, JSON-RPC)  ⟷  THIS process
+ *   THIS process  ⟷ (WebSocket server @ 127.0.0.1)  ⟷  extension service worker
+ *
+ * The agent calls a tool → we send a `req` frame to the connected extension →
+ * the extension answers with the read-only QA bundle → we return it. The
+ * extension is the WS *client* (a service worker can't listen on a socket);
+ * this process is the WS *server*, bound to loopback only.
+ *
+ * Security: localhost is reachable by any local process AND by web pages
+ * (loopback is "potentially trustworthy", WS has no CORS preflight), so the
+ * only real gate is a shared token — set the same value here (QIKSY_MCP_TOKEN)
+ * and in the extension popup. Bad/missing token → the socket is closed before
+ * any data is sent. We also reject non-extension Origins.
+ *
+ * stdout is the JSON-RPC channel — all logging goes to stderr.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { WebSocketServer, WebSocket } from 'ws';
+import { z } from 'zod';
+import { randomUUID, timingSafeEqual } from 'node:crypto';
+
+const log = (...a) => console.error('[qiksy-mcp]', ...a);
+
+const TOKEN = process.env.QIKSY_MCP_TOKEN || '';
+const portArg = process.argv.indexOf('--port');
+const PORT = portArg !== -1 ? Number(process.argv[portArg + 1]) : Number(process.env.QIKSY_MCP_PORT) || 7333;
+const HOST = '127.0.0.1';
+const PROTOCOL_VERSION = 1;
+
+if (!TOKEN) {
+  log('WARNING: QIKSY_MCP_TOKEN is not set. Set the same token here and in the Qiksy popup, or connections are refused.');
+}
+
+function tokenOk(got) {
+  if (!TOKEN || typeof got !== 'string' || got.length !== TOKEN.length) return false;
+  try {
+    return timingSafeEqual(Buffer.from(got), Buffer.from(TOKEN));
+  } catch {
+    return false;
+  }
+}
+
+// ── WebSocket bridge to the extension ──────────────────────────────────────
+let client = null; // the one authenticated extension socket
+const pending = new Map(); // id → { resolve, reject, timer }
+
+const wss = new WebSocketServer({ host: HOST, port: PORT });
+wss.on('listening', () => log(`bridge listening on ws://${HOST}:${PORT} — token ${TOKEN ? 'set' : 'MISSING'}`));
+wss.on('error', (e) => log('bridge error:', e?.message || e));
+
+wss.on('connection', (ws, req) => {
+  const origin = req.headers.origin || '';
+  // Only the extension should connect; a real web page has an http(s)/null origin.
+  if (origin && !origin.startsWith('chrome-extension://')) {
+    ws.close(4003, 'forbidden origin');
+    return;
+  }
+  let authed = false;
+  const helloTimer = setTimeout(() => {
+    if (!authed) ws.close(4001, 'no hello');
+  }, 2000);
+
+  ws.on('message', (raw) => {
+    let msg;
+    try {
+      msg = JSON.parse(raw.toString());
+    } catch {
+      return;
+    }
+    if (!authed) {
+      if (msg.t !== 'hello' || !tokenOk(msg.token)) {
+        clearTimeout(helloTimer);
+        ws.close(4001, 'auth failed');
+        return;
+      }
+      authed = true;
+      clearTimeout(helloTimer);
+      client = ws;
+      ws.send(JSON.stringify({ t: 'welcome', v: PROTOCOL_VERSION }));
+      log('extension connected');
+      return;
+    }
+    if (msg.t === 'ping') {
+      ws.send(JSON.stringify({ t: 'pong', ts: msg.ts }));
+      return;
+    }
+    if (msg.t === 'res' && msg.id != null) {
+      const p = pending.get(msg.id);
+      if (!p) return;
+      clearTimeout(p.timer);
+      pending.delete(msg.id);
+      if (msg.ok) p.resolve(msg.result);
+      else p.reject(new Error(String(msg.error || 'extension error')));
+    }
+  });
+
+  ws.on('close', () => {
+    if (client === ws) {
+      client = null;
+      log('extension disconnected');
+    }
+  });
+});
+
+function callExtension(tool, args, timeoutMs = 15_000) {
+  return new Promise((resolve, reject) => {
+    if (!client || client.readyState !== WebSocket.OPEN) {
+      reject(new Error('Qiksy extension is not connected. Open Chrome with the extension and enable the MCP bridge in its popup (matching token & port).'));
+      return;
+    }
+    const id = randomUUID();
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      reject(new Error(`Timed out after ${timeoutMs}ms waiting for "${tool}". Is a normal web page focused in Chrome?`));
+    }, timeoutMs);
+    pending.set(id, { resolve, reject, timer });
+    client.send(JSON.stringify({ t: 'req', id, tool, args: args || {} }));
+  });
+}
+
+// ── MCP server + tools (read-only) ─────────────────────────────────────────
+const asText = (v) => ({ content: [{ 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) }] });
+
+const server = new McpServer({ name: 'qiksy', version: '0.1.0' });
+
+server.registerTool(
+  'qa_tabs',
+  {
+    title: 'QA tabs',
+    description:
+      'List the browser tabs Qiksy can read, including which are ISOLATED multi-login sessions (isolatedSession = the login name). Use a tab\'s tabId with the other tools to read that specific login.',
+    inputSchema: {},
+  },
+  async () => {
+    try {
+      return asText(await callExtension('qa_tabs', {}));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+server.registerTool(
+  'qa_status',
+  {
+    title: 'QA status',
+    description: 'Health snapshot of a page Qiksy is watching: URL, error/warning/form counts, and its isolated-login name if any. Defaults to the active tab; pass tabId (from qa_tabs) to target a specific tab.',
+    inputSchema: { tabId: z.number().int().optional().describe('Target tab (from qa_tabs); omit for the active tab') },
+  },
+  async ({ tabId }) => {
+    try {
+      return asText(await callExtension('qa_status', { tabId }));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+server.registerTool(
+  'qa_findings',
+  {
+    title: 'QA findings',
+    description: 'Findings on a page (console/JS/network/a11y/markup/submit) — each with a CSS selector and detail. Filter by severity; pass tabId (from qa_tabs) to read a specific tab / isolated login.',
+    inputSchema: {
+      severity: z.enum(['all', 'error', 'warning']).default('all').describe('Severity filter'),
+      tabId: z.number().int().optional().describe('Target tab (from qa_tabs); omit for the active tab'),
+    },
+  },
+  async ({ severity, tabId }) => {
+    try {
+      return asText(await callExtension('qa_findings', { severity, tabId }));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+server.registerTool(
+  'qa_export',
+  {
+    title: 'QA export',
+    description:
+      '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 }) => {
+    try {
+      return asText(await callExtension('qa_export', { tabId }, 30_000));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+// ── Command tools (drive Qiksy's OWN UI / analysis; never the app under test) ─
+const tabIdArg = z.number().int().optional().describe('Target tab (from qa_tabs); omit for the active tab');
+
+server.registerTool(
+  'qa_open_panel',
+  {
+    title: 'Open Qiksy panel',
+    description:
+      "Open (or close) the Qiksy side panel on a tab and optionally jump to a tab: 'forms' | 'findings' | 'tour' | 'tools' | 'history' | 'roles'. Controls Qiksy's OWN UI only — it does not touch the page under test. Set open:false to close.",
+    inputSchema: {
+      tabId: tabIdArg,
+      open: z.boolean().default(true).describe('true to open, false to close'),
+      tab: z.enum(['forms', 'findings', 'tour', 'tools', 'history', 'roles']).optional().describe('Which panel tab to show'),
+    },
+  },
+  async ({ tabId, open, tab }) => {
+    try {
+      return asText(await callExtension('qa_open_panel', { tabId, open, tab }));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+server.registerTool(
+  'qa_run_audit',
+  {
+    title: 'Run accessibility & markup audit',
+    description:
+      '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 }) => {
+    try {
+      return asText(await callExtension('qa_run_audit', { tabId }, 30_000));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+server.registerTool(
+  'qa_tour',
+  {
+    title: 'Exploratory tour / coverage checklist',
+    description:
+      'Return a generated per-page exploratory-testing checklist (from detected forms + interactive surfaces), with items auto-checked from the recorded session. Great raw material for writing test cases. Returns markdown + structured items.',
+    inputSchema: { tabId: tabIdArg },
+  },
+  async ({ tabId }) => {
+    try {
+      return asText(await callExtension('qa_tour', { tabId }, 20_000));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+server.registerTool(
+  'qa_report',
+  {
+    title: 'Generate session report',
+    description:
+      'Generate Qiksy\'s self-contained HTML session report (coverage stats, per-page table, steps with screenshots, findings) from the recorded session and return the HTML. Requires History recording to have captured steps; otherwise returns a note.',
+    inputSchema: { tabId: tabIdArg },
+  },
+  async ({ tabId }) => {
+    try {
+      return asText(await callExtension('qa_report', { tabId }, 45_000));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+server.registerTool(
+  'qa_spotlight',
+  {
+    title: 'Spotlight an element',
+    description:
+      'Visually highlight (dim + outline) an element on the page by CSS selector, so the human tester can see what the agent is referring to. A non-destructive overlay — it does not click, focus, or modify the element.',
+    inputSchema: {
+      tabId: tabIdArg,
+      selector: z.string().describe('CSS selector of the element to spotlight'),
+      label: z.string().optional().describe('Optional caption shown on the highlight'),
+    },
+  },
+  async ({ tabId, selector, label }) => {
+    try {
+      return asText(await callExtension('qa_spotlight', { tabId, selector, label }));
+    } catch (e) {
+      return asError(e);
+    }
+  },
+);
+
+async function main() {
+  await server.connect(new StdioServerTransport());
+  log('MCP stdio server ready');
+}
+main().catch((e) => {
+  log('fatal', e);
+  process.exit(1);
+});