truepx-mcp 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# truepx-mcp
+
+Local bridge between MCP-compatible AI agents (Claude Code, Cursor, Windsurf,
+Cline, Continue) and the TruePx browser extension.
+
+```
+agent (MCP stdio) ⇄ truepx-mcp ⇄ ws://127.0.0.1:47830 ⇄ extension
+```
+
+## Connect
+
+1. Add the bridge to your agent. Claude Code:
+
+```sh
+claude mcp add truepx -- npx -y truepx-mcp
+```
+
+Other clients (`mcp.json`):
+
+```json
+{ "mcpServers": { "truepx": { "command": "npx", "args": ["-y", "truepx-mcp"] } } }
+```
+
+2. Restart the AI client, then open TruePx Settings → AI agents → Connect.
+3. Turn TruePx on in the tabs the agent should see, then ask it to list tabs.
+
+Port override (e.g. a second bridge): `TRUEPX_MCP_PORT=18732 npx -y truepx-mcp`.
+From a checkout: `node packages/mcp-bridge/server.mjs`.
+
+Rules: the agent only sees tabs where TruePx is on (`tabs_list`); only one AI
+client drives the extension at a time (extra clients relay through the
+first instead of fighting over the port).
+
+## Protocol
+
+- stdin/stdout: MCP over stdio via `@modelcontextprotocol/sdk`
+  (`initialize`, `tools/list`, `tools/call`).
+- Bridge → extension: `{"id","type","payload"}` (`type` = tool name).
+  First frame per socket is a `hello` (`{id:"__handshake__", type:"handshake",
+  version, client}`) carrying the bridge version + agent identity.
+- Extension → bridge: `{"id","payload"}` where payload is data,
+  `{error}`, or `{success:false,message}`; screenshots arrive as
+  `{ok,dataUrl,note?}` and are re-emitted as MCP image blocks.
+- Tool catalog mirrors `src/mcp/catalog.ts` (48 tools). Every tab-bound
+  tool requires a numeric `tabId` from `tabs_list`; element ids are
+  per-tab/per-viewport strings from the element tools.
+- Multi-client: the first bridge to bind the port becomes leader; later
+  instances join as followers and relay (`relay` / `relay_result`).
+- Security: the port binds `127.0.0.1` and the handshake gates on
+  `Origin` — absent (node followers) or `chrome-extension://` pass;
+  `http(s)` / `file:` / `null` origins are rejected, since WebSocket
+  handshakes ignore CORS and any local page could otherwise reach the
+  port. `css_fetch_stylesheet` additionally blocks non-http(s) URLs and
+  localhost/private IPs.
+
+## Smoke test
+
+```sh
+node packages/mcp-bridge/smoke.mjs   # also wired as tests/e2e/mcp-smoke.mjs
+```

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "truepx-mcp",
+  "version": "0.1.0",
+  "description": "Local MCP stdio bridge for TruePx (connects AI agents to the extension over a localhost WebSocket)",
+  "type": "module",
+  "bin": {
+    "truepx-mcp": "./server.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.20.0",
+    "ws": "8.18.0"
+  },
+  "files": [
+    "server.mjs",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "truepx",
+    "chrome-extension",
+    "css",
+    "ai-agent"
+  ]
+}

package/server.mjs

@@ -0,0 +1,846 @@
+#!/usr/bin/env node
+// truepx-mcp — MCP stdio ↔ extension WebSocket bridge.
+//
+// TruePx MCP protocol (original implementation):
+//
+//   agent (MCP stdio) ⇄ this process ⇄ ws://127.0.0.1:47830 ⇄ extension
+//
+// Wire format bridge → extension:  {"id","type","payload"}  (type = tool)
+// Wire format extension → bridge:  {"id","payload"}          (payload = data
+//   | {error} | {success:false,message}); screenshots: {ok,dataUrl,note?}
+// Control frames: handshake (version + agent identity), agent_info,
+// relay / relay_result (multi-client), __takeover__ / __follower__ (legacy).
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { WebSocketServer, WebSocket } from 'ws';
+
+const BRIDGE_VERSION = '0.1.0';
+const args = process.argv.slice(2);
+const portIdx = args.indexOf('--port');
+const WS_PORT =
+  Number(process.env.TRUEPX_MCP_PORT) ||
+  (portIdx >= 0 ? Number(args[portIdx + 1]) || 47830 : 47830);
+const BIND_HOST = '127.0.0.1';
+
+const FORWARD_TIMEOUT_MS = 15000;
+const FORWARD_TIMEOUT_LONG_MS = 45000;
+const LONG_TIMEOUT_TOOLS = new Set([
+  'capture_screenshot',
+  'viewports_open',
+  'viewports_close',
+  'viewport_update',
+  'viewports_set',
+  'viewport_add',
+  'breakpoints_overlay',
+  'sweep_breakpoints',
+]);
+const HEARTBEAT_MS = 10000;
+const RELAY_SLACK_MS = 5000;
+const RELAY_TIMEOUT_MAX_MS = 120000;
+const HELLO_WAIT_MS = 1500;
+const OPEN_WAIT_MS = 3000;
+const ACQUIRE_RETRY_MS = 500;
+const ACQUIRE_RETRY_MAX_MS = 2000;
+
+// ---------------------------------------------------------------------------
+// Tool catalog. Every tab-bound tool requires a numeric tabId from
+// tabs_list, except css_fetch_stylesheet which takes a stylesheet URL.
+// ---------------------------------------------------------------------------
+const TABID = {
+  tabId: { type: 'number', description: 'Id of a tab where TruePx is on, from tabs_list.' },
+};
+const ELID = {
+  elementId: { type: 'string', description: 'Element id from an earlier element tool.' },
+};
+const VIEWPORT_ID = {
+  viewportId: {
+    type: 'number',
+    description:
+      'Responsive mode only: viewport from viewport_state that should answer. Element ids are per-viewport — only pass ids that came from this viewport.',
+  },
+};
+const RULE_REF = {
+  type: 'object',
+  description:
+    'Rule handle from css_matched_rules or css_create_rule. Pass back exactly as received; hand-built refs are rejected.',
+  properties: {
+    index: { type: 'number' },
+    selector: { type: 'string' },
+    wrappers: { type: 'array', items: { type: 'string' } },
+    stylesheet: { type: 'string' },
+    occ: { type: 'number' },
+    own: { type: 'string' },
+  },
+  additionalProperties: false,
+};
+
+const req = (props, required = ['tabId']) => ({
+  type: 'object',
+  properties: props,
+  required,
+  additionalProperties: false,
+});
+
+const TOOLS = [
+  { name: 'ping', description: 'Health check, forwarded to the extension. Replies with extension + bridge versions.', inputSchema: req({}, []) },
+  { name: 'tabs_list', description: 'Tabs where TruePx is currently on. Returns { tabId, url, title } per tab; other tabs are invisible.', inputSchema: req({}, []) },
+  { name: 'tab_focus', description: 'Bring a tab to the foreground so the user can watch edits happen.', inputSchema: req({ ...TABID }) },
+  { name: 'page_info', description: 'Page metadata: url, title, lang, description, OG tags, h1, viewport meta, page size, scroll, devicePixelRatio.', inputSchema: req({ ...TABID }) },
+  { name: 'selection_get', description: 'The element the user has locked in the TruePx overlay (id, tag, selector, classes, rect, computed subset, text). Starting point for "this element".', inputSchema: req({ ...TABID }) },
+  { name: 'element_inspect', description: 'Uniform summary for one element: id, tag, selector, classes, rect, computed CSS subset, direct text.', inputSchema: req({ ...TABID, ...ELID, ...VIEWPORT_ID }, ['tabId', 'elementId']) },
+  { name: 'elements_inspect', description: 'Batch element_inspect for up to 50 ids; unresolvable ids are reported separately.', inputSchema: req({ tabId: TABID.tabId, elementIds: { type: 'array', items: { type: 'string' } }, ...VIEWPORT_ID }, ['tabId', 'elementIds']) },
+  { name: 'dom_outline', description: 'Depth-limited subtree walk from an element (default body). Keeps layout exploration payloads small.', inputSchema: { type: 'object', properties: { ...TABID, elementId: { type: 'string', description: "Root element id; 'body' targets document.body. Omit for current selection." }, maxDepth: { type: 'number', description: 'Max depth (default 8).' }, maxChildren: { type: 'number', description: 'Max children per node (default 30).' }, ...VIEWPORT_ID }, additionalProperties: false } },
+  { name: 'dom_query', description: 'CSS selector search, up to 200 matches (id, tag, classes, rect, text, attrs). Optional rootId scopes the search.', inputSchema: { type: 'object', properties: { ...TABID, selector: { type: 'string' }, limit: { type: 'number' }, rootId: { type: 'string' }, ...VIEWPORT_ID }, required: ['tabId', 'selector'], additionalProperties: false } },
+  { name: 'css_matched_rules', description: 'Every CSS rule matching an element, highest specificity first, plus inline style text. Each rule carries a ruleHandle for css_set_inline.', inputSchema: req({ ...TABID, ...ELID, ...VIEWPORT_ID }, ['tabId', 'elementId']) },
+  { name: 'edits_list', description: 'All tracked edits on the tab (CSS diffs with revert ids, class/HTML/text edits). Call first to review prior work.', inputSchema: req({ ...TABID }) },
+  { name: 'capture_screenshot', description: 'Viewport PNG with the TruePx highlight overlay (dock excluded), returned as an image block for vision models.', inputSchema: req({ ...TABID }) },
+  { name: 'css_set_inline', description: "Merge declarations into a rule (ruleHandle) or an element's inline style (elementId). Empty value deletes a property; values may carry !important.", inputSchema: { type: 'object', properties: { ...TABID, styles: { type: 'object', description: "CSS prop → value, e.g. { color: 'red' }." }, elementId: { type: 'string', description: 'Required without ruleHandle; ignored with ruleHandle.' }, ruleHandle: RULE_REF }, required: ['tabId', 'styles'], additionalProperties: false } },
+  { name: 'css_create_rule', description: 'Add a real cascade rule (no !important needed). Optional at-rule wrappers outermost-first, optional seed declarations. Returns a ruleHandle.', inputSchema: { type: 'object', properties: { ...TABID, selector: { type: 'string' }, wrappers: { type: 'array', items: { type: 'string' }, description: 'At-rule strings, e.g. ["@media (min-width: 768px)"].' }, styles: { type: 'object' }, elementId: { type: 'string', description: 'Inject into this element\'s shadow root instead of the document.' } }, required: ['tabId', 'selector'], additionalProperties: false } },
+  { name: 'css_set_selector', description: "Retarget a rule's selector. Returns a refreshed ruleHandle; nesting selectors are read-only.", inputSchema: req({ ...TABID, ruleHandle: RULE_REF, selector: { type: 'string', description: 'New selector text.' } }, ['tabId', 'ruleHandle', 'selector']) },
+  { name: 'edits_revert', description: 'Revert one tracked CSS change by its changeId (from an edit response or edits_list).', inputSchema: req({ ...TABID, changeId: { type: 'string' } }, ['tabId', 'changeId']) },
+  { name: 'edits_revert_all', description: "Revert every tracked change on the tab (rules, inline styles, classes, HTML/text). Same coverage as the panel's revert-all.", inputSchema: req({ ...TABID }) },
+  { name: 'dom_set_text', description: "Replace an element's text (drops HTML children). Undoable.", inputSchema: req({ ...TABID, ...ELID, text: { type: 'string', description: 'New plain text.' } }, ['tabId', 'elementId', 'text']) },
+  { name: 'dom_set_html', description: 'Replace inner HTML. Strips script/style/iframe/form/input/link/meta and inline handlers.', inputSchema: req({ ...TABID, ...ELID, html: { type: 'string' } }, ['tabId', 'elementId', 'html']) },
+  { name: 'dom_insert_html', description: "Insert sanitized HTML relative to an element: before | after | prepend | append.", inputSchema: req({ ...TABID, ...ELID, html: { type: 'string' }, position: { type: 'string', enum: ['before', 'after', 'prepend', 'append'] } }, ['tabId', 'elementId', 'html', 'position']) },
+  { name: 'element_set_classes', description: 'Replace the full class list (space-separated; empty clears). Undoable.', inputSchema: req({ ...TABID, ...ELID, classes: { type: 'string' } }, ['tabId', 'elementId', 'classes']) },
+  { name: 'selection_set', description: 'Highlight an element in the TruePx overlay, scroll it into view, update the panel.', inputSchema: req({ ...TABID, ...ELID }, ['tabId', 'elementId']) },
+  { name: 'dom_remove', description: 'Soft-delete (hidden, reported removed, restorable). Undoable.', inputSchema: req({ ...TABID, ...ELID }, ['tabId', 'elementId']) },
+  { name: 'dom_duplicate', description: 'Clone after the original with a fresh id. Undoable.', inputSchema: req({ ...TABID, ...ELID }, ['tabId', 'elementId']) },
+  { name: 'page_breakpoints', description: 'Declared @media breakpoints ascending; em/rem normalized against root font size.', inputSchema: req({ ...TABID }) },
+  { name: 'find_overflow', description: 'Elements pushing the page past the viewport (horizontal-scroll culprits), biggest overflow first with fix hints.', inputSchema: req({ ...TABID }) },
+  { name: 'fix_contrast', description: 'Nudge an element subtree foreground colors to pass a contrast target (default 4.5). Pass preview:true to suggest without applying.', inputSchema: { type: 'object', properties: { ...TABID, ...ELID, target: { type: 'number' }, preview: { type: 'boolean' } }, required: ['tabId', 'elementId'], additionalProperties: false } },
+  { name: 'simulate_vision', description: 'Simulate color-vision deficiency page-wide so designs can be judged as affected users see them. Mode off disables.', inputSchema: { type: 'object', properties: { ...TABID, mode: { type: 'string', enum: ['protanopia', 'deuteranopia', 'tritanopia', 'achromatopsia', 'off'] } }, required: ['tabId', 'mode'], additionalProperties: false } },
+  { name: 'mockup_overlay', description: 'Pin a design mockup over the live page to compare implementation vs design. set takes a data:image URL (+ optional file name; "@2x" in it picks @2x size); config adjusts opacity/blend/position/scale (fit = page width, 1x = actual pixels, 2x = half size for Retina exports; set picks 1x or 2x automatically); difference blend is an onion-skin diff.', inputSchema: { type: 'object', properties: { ...TABID, action: { type: 'string', enum: ['set', 'config', 'clear', 'state'] }, dataUrl: { type: 'string' }, name: { type: 'string' }, opacity: { type: 'number' }, blend: { type: 'string' }, x: { type: 'number' }, y: { type: 'number' }, visible: { type: 'boolean' }, scale: { type: 'string', enum: ['fit', '1x', '2x'] } }, required: ['tabId', 'action'], additionalProperties: false } },
+  { name: 'sweep_breakpoints', description: 'Load the page at probe widths in hidden frames and report where layout breaks or heals. Optional widths array (max 9, 200–3840). Slow — allow up to ~40s.', inputSchema: { type: 'object', properties: { ...TABID, widths: { type: 'array', items: { type: 'number' } } }, required: ['tabId'], additionalProperties: false } },
+  { name: 'find_inconsistencies', description: 'Scan the page for visual drift: button style clusters, heading variation, off-grid spacing, near-miss alignment.', inputSchema: req({ ...TABID }) },
+  { name: 'list_pins', description: 'Designer pins: id, selector, note, status, live rect. Work open pins top to bottom, then resolve each.', inputSchema: req({ ...TABID }) },
+  { name: 'add_pin', description: 'Drop a pin on an element with a note (for batch review comments).', inputSchema: { type: 'object', properties: { ...TABID, ...ELID, selector: { type: 'string' }, note: { type: 'string' } }, required: ['tabId', 'note'], additionalProperties: false } },
+  { name: 'resolve_pin', description: 'Close a pin by id once acted on (resolved:false reopens).', inputSchema: { type: 'object', properties: { ...TABID, pinId: { type: 'string' }, resolved: { type: 'boolean' } }, required: ['tabId', 'pinId'], additionalProperties: false } },
+  { name: 'font_forensics', description: 'Which font in the stack actually rendered, plus faux bold/italic detection.', inputSchema: req({ ...TABID, ...ELID }, ['tabId', 'elementId']) },
+  { name: 'find_heavy_images', description: 'Images costing more than they show: oversized, unsized, eager below the fold, legacy formats.', inputSchema: req({ ...TABID }) },
+  { name: 'capture_states', description: 'Screenshots of one element in default/hover/focus/active states, returned as image blocks. Slow — allow ~30s.', inputSchema: req({ ...TABID, ...ELID }, ['tabId', 'elementId']) },
+  { name: 'viewports_open', description: 'Wrap the page in resizable frames. Discards pending CSS edits — call edits_list first.', inputSchema: req({ ...TABID }) },
+  { name: 'viewports_close', description: 'Reload at natural viewport. Discards edits made inside responsive mode.', inputSchema: req({ ...TABID }) },
+  { name: 'viewport_update', description: 'Resize one viewport (200–3840 × 300–3840). Without viewportId resizes the first.', inputSchema: { type: 'object', properties: { ...TABID, width: { type: 'number' }, height: { type: 'number' }, viewportId: { type: 'number' } }, required: ['tabId', 'width', 'height'], additionalProperties: false } },
+  { name: 'viewport_state', description: 'Canvas state: viewports in on-screen order (id, size, name, color scheme), zoom, breakpointsMode, scroll sync. Empty outside responsive mode.', inputSchema: req({ ...TABID }) },
+  { name: 'viewports_set', description: 'Replace the whole viewport set left-to-right in one rebuild (prefer over repeated viewport_add). Exits breakpoints mode.', inputSchema: { type: 'object', properties: { ...TABID, viewports: { type: 'array', items: { type: 'object', properties: { width: { type: 'number' }, height: { type: 'number' }, name: { type: 'string' } }, required: ['width', 'height'], additionalProperties: false } } }, required: ['tabId', 'viewports'], additionalProperties: false } },
+  { name: 'viewport_add', description: 'Add one frame (inherits current edits for comparison). Omit size to copy the last viewport.', inputSchema: { type: 'object', properties: { ...TABID, width: { type: 'number' }, height: { type: 'number' }, name: { type: 'string' } }, required: ['tabId'], additionalProperties: false } },
+  { name: 'viewport_remove', description: 'Remove one frame by id. Removing the last leaves an empty canvas. Unavailable in breakpoints mode.', inputSchema: req({ ...TABID, viewportId: { type: 'number' } }, ['tabId', 'viewportId']) },
+  { name: 'viewports_zoom', description: 'Canvas scale 0.25–2 (visual only; frames still report declared size, media queries unaffected).', inputSchema: req({ ...TABID, zoom: { type: 'number' } }, ['tabId', 'zoom']) },
+  { name: 'breakpoints_overlay', description: 'One viewport per declared breakpoint. Fails when the page declares none.', inputSchema: req({ ...TABID, enabled: { type: 'boolean' } }, ['tabId', 'enabled']) },
+  { name: 'page_seo_audit', description: 'SEO audit (title, description, h1, robots, alt text, OG tags…) with severity + recommendations.', inputSchema: req({ ...TABID }) },
+  { name: 'page_meta', description: 'Meta values grouped SEO / Open Graph / Twitter. Read before social-card previews.', inputSchema: req({ ...TABID }) },
+  { name: 'page_weight', description: 'Byte breakdown: scripts, stylesheets, images, fonts, fetch, media, other + document size.', inputSchema: req({ ...TABID }) },
+  { name: 'css_variables', description: 'Every --* custom property in the cascade. Read before authoring CSS so agents reuse var(--foo).', inputSchema: req({ ...TABID }) },
+  { name: 'page_typography', description: 'Font family/stack/size/weight/spacing/transform inside a subtree, with using selectors.', inputSchema: req({ ...TABID, ...ELID }, ['tabId', 'elementId']) },
+  { name: 'css_specificity', description: 'Specificity of any selector as tuple + comparable score. Use before writing overrides.', inputSchema: req({ ...TABID, selector: { type: 'string' } }, ['tabId', 'selector']) },
+  { name: 'page_colors', description: 'Distinct text/background/border colors rendered in a subtree (incl. gradients, canvas samples).', inputSchema: req({ ...TABID, ...ELID }, ['tabId', 'elementId']) },
+  { name: 'page_assets', description: 'Images, SVGs, data URLs in a subtree with URL/content + rendered dimensions.', inputSchema: req({ ...TABID, ...ELID }, ['tabId', 'elementId']) },
+  { name: 'element_layout', description: 'Flex/grid breakdown (direction, justify, align, gap, templates). Null when neither.', inputSchema: req({ ...TABID, ...ELID, ...VIEWPORT_ID }, ['tabId', 'elementId']) },
+  { name: 'element_force_state', description: 'Force hover/focus/active/visited/focus-visible/focus-within to preview rendering; empty clears. Not in responsive mode.', inputSchema: req({ ...TABID, ...ELID, state: { type: 'string' } }, ['tabId', 'elementId', 'state']) },
+  { name: 'page_tech_stack', description: 'Frameworks/CMS/analytics with versions. Call first on a new task — the stack shapes suggestions.', inputSchema: req({ ...TABID }) },
+  { name: 'get_a11y_issues', description: 'WCAG text/icon contrast failures (AA+AAA), grouped by selector, worst first.', inputSchema: { type: 'object', properties: { ...TABID, limit: { type: 'number', description: 'Max issues (default 50).' } }, required: ['tabId'], additionalProperties: false } },
+  { name: 'element_tailwind', description: 'Computed styles → Tailwind v4 utilities. Pair with element_set_classes to apply.', inputSchema: req({ ...TABID, ...ELID }, ['tabId', 'elementId']) },
+  { name: 'css_fetch_stylesheet', description: "Raw CSS of an external stylesheet URL, fetched from the extension service worker (cross-origin reachable). HTTP(S) only; localhost/private IPs blocked.", inputSchema: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'], additionalProperties: false } },
+];
+
+function errText(msg) {
+  return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+}
+const needTab = (a, tool) =>
+  typeof a?.tabId !== 'number' ? errText(`${tool} requires a numeric tabId from tabs_list.`) : null;
+
+// ---------------------------------------------------------------------------
+// WebSocket bridge (leader/follower so parallel AI clients all keep working)
+// ---------------------------------------------------------------------------
+let activeSocket = null;
+let mcpClientInfo = null;
+let role = null;
+let acquireStatus = `binding port ${WS_PORT}`;
+const pending = new Map();
+let nextId = 1;
+
+function sendClientInfo() {
+  if (!activeSocket || activeSocket.readyState !== WebSocket.OPEN) return;
+  try {
+    activeSocket.send(
+      JSON.stringify({ id: '__agent_info__', type: 'agent_info', client: mcpClientInfo }),
+    );
+  } catch { /* closing; next hello carries it */ }
+}
+
+function originOf(req) {
+  const entry = Object.entries(req.headers).find(([n]) => n.toLowerCase() === 'origin');
+  const raw = Array.isArray(entry?.[1]) ? entry[1][0] : entry?.[1];
+  const v = typeof raw === 'string' ? raw.trim() : '';
+  return v === '' ? null : v;
+}
+
+function verifyClient(info, cb) {
+  // Binding localhost is not a trust boundary for WebSockets (no CORS), so
+  // gate on Origin, which page script cannot forge: absent (node followers)
+  // or chrome-extension:// (our offscreen/ext pages) pass; http(s)/file/null
+  // origins are web content and are rejected.
+  const origin = originOf(info.req);
+  if (origin === null) return cb(true);
+  if (/^chrome-extension:\/\//.test(origin)) return cb(true);
+  console.error(`[MCP] rejected bridge connection from origin ${origin}`);
+  return cb(false, 403, 'Forbidden: web origins cannot drive the bridge');
+}
+
+async function startWss() {
+  return new Promise((resolve, reject) => {
+    const wss = new WebSocketServer(
+      { host: BIND_HOST, port: WS_PORT, verifyClient },
+      () => resolve(wss),
+    );
+    wss.on('error', reject);
+  });
+}
+
+function becomeLeader(wss) {
+  role = { kind: 'leader', wss };
+  console.error(`[MCP] leader: listening on ${BIND_HOST}:${WS_PORT}`);
+  wss.on('error', (e) => console.error('[MCP] server error:', e.message));
+  const beat = setInterval(() => {
+    for (const sock of wss.clients) {
+      if (sock.isAlive === false) {
+        console.error('[MCP] dropping unresponsive socket');
+        sock.terminate();
+        continue;
+      }
+      sock.isAlive = false;
+      try { sock.ping(); } catch { /* closing */ }
+    }
+  }, HEARTBEAT_MS);
+  beat.unref?.();
+  wss.on('connection', (socket) => {
+    console.error('[MCP] client connected');
+    try {
+      socket.send(
+        JSON.stringify({ id: '__handshake__', type: 'handshake', version: BRIDGE_VERSION, client: mcpClientInfo }),
+      );
+    } catch { /* closing already */ }
+    let promoted = false;
+    let isRelayPeer = false;
+    socket.isAlive = true;
+    socket.on('pong', () => { socket.isAlive = true; });
+    socket.on('message', (raw) => {
+      let msg;
+      try { msg = JSON.parse(String(raw)); } catch {
+        console.error('[MCP] non-JSON frame dropped');
+        return;
+      }
+      if (!msg || typeof msg !== 'object') return;
+      // Tool replies carry no type by design (they answer by id); anything
+      // with neither is noise. Matching still requires the exact socket the
+      // request went out on, so stray peers can't forge results.
+      if (!msg.type && typeof msg.id !== 'string') return;
+      socket.isAlive = true;
+      if (msg.type === '__takeover__') {
+        if (sawStdioTraffic) {
+          console.error('[MCP] legacy takeover refused (live session)');
+        } else {
+          console.error('[MCP] legacy takeover honored, exiting');
+          process.exit(0);
+        }
+        return;
+      }
+      if (msg.type === '__follower__') { isRelayPeer = true; return; }
+      if (msg.type === 'relay') { isRelayPeer = true; handleRelay(socket, msg); return; }
+      // Promotion: the first non-control message marks the extension socket —
+      // including its reply to our hello (silent sockets stay unpromoted, so a
+      // stray page that connected but never speaks can never receive tools).
+      if (!promoted && !isRelayPeer && (msg.type || msg.id === '__handshake__')) {
+        promoted = true;
+        const prev = activeSocket;
+        if (prev && prev !== socket) {
+          for (const [id, p] of pending) {
+            if (p.socket !== prev) continue;
+            clearTimeout(p.timer);
+            p.reject(new Error('Extension reconnected before responding. Retry the call.'));
+            pending.delete(id);
+          }
+          try { prev.terminate(); } catch { /* noop */ }
+        }
+        activeSocket = socket;
+      }
+      if (typeof msg.id !== 'string') return;
+      const p = pending.get(msg.id);
+      if (p && p.socket === socket) {
+        clearTimeout(p.timer);
+        pending.delete(msg.id);
+        p.resolve(msg.payload);
+      }
+    });
+    socket.on('close', () => {
+      if (activeSocket === socket) {
+        activeSocket = null;
+        console.error('[MCP] extension disconnected');
+        for (const [id, p] of pending) {
+          if (p.socket !== socket) continue;
+          clearTimeout(p.timer);
+          p.reject(new Error('Extension disconnected. Retry the call.'));
+          pending.delete(id);
+        }
+      }
+    });
+  });
+}
+
+function handleRelay(sock, msg) {
+  const { id, tool, payload } = msg;
+  if (typeof id !== 'string' || typeof tool !== 'string') return;
+  const t = typeof msg.timeoutMs === 'number' && Number.isFinite(msg.timeoutMs)
+    ? Math.min(Math.max(msg.timeoutMs, 1000), RELAY_TIMEOUT_MAX_MS)
+    : undefined;
+  forwardToExtension(tool, payload, t).then(
+    (result) => { try { sock.send(JSON.stringify({ id, type: 'relay_result', payload: result })); } catch {} },
+    (e) => { try { sock.send(JSON.stringify({ id, type: 'relay_result', error: e instanceof Error ? e.message : String(e) })); } catch {} },
+  );
+}
+
+async function joinAsFollower() {
+  return new Promise((resolve) => {
+    const url = `ws://${BIND_HOST}:${WS_PORT}`;
+    let socket;
+    try {
+      socket = new WebSocket(url);
+    } catch { resolve('connect-failed'); return; }
+    const openTimer = setTimeout(() => {
+      try { socket.terminate(); } catch {}
+      resolve('open-timeout');
+    }, OPEN_WAIT_MS);
+    socket.on('open', () => {
+      clearTimeout(openTimer);
+      try { socket.send(JSON.stringify({ type: '__follower__' })); } catch {}
+      const helloTimer = setTimeout(() => resolve('joined-legacy'), HELLO_WAIT_MS);
+      socket.once('message', (raw) => {
+        let msg;
+        try { msg = JSON.parse(String(raw)); } catch { clearTimeout(helloTimer); resolve('joined-legacy'); return; }
+        if (msg?.type === 'handshake') {
+          clearTimeout(helloTimer);
+          role = { kind: 'follower', socket };
+          console.error('[MCP] follower: relaying through leader');
+          socket.on('message', (raw2) => {
+            let m;
+            try { m = JSON.parse(String(raw2)); } catch { return; }
+            if (!m || typeof m !== 'object' || typeof m.id !== 'string') return;
+            const p = pending.get(m.id);
+            if (!p || p.socket !== socket) return;
+            clearTimeout(p.timer);
+            pending.delete(m.id);
+            if ('error' in m) p.reject(new Error(String(m.error)));
+            else p.resolve(m.payload);
+          });
+          socket.on('close', () => {
+            console.error('[MCP] leader lost; re-acquiring');
+            for (const [id, p] of pending) {
+              clearTimeout(p.timer);
+              p.reject(new Error('Leader MCP instance went away. Retry the call.'));
+              pending.delete(id);
+            }
+            role = null;
+            void acquireRole().catch((e) => {
+              console.error('[MCP] fatal:', e instanceof Error ? e.message : String(e));
+              process.exit(1);
+            });
+          });
+          resolve('joined');
+        } else {
+          clearTimeout(helloTimer);
+          resolve('joined-legacy');
+        }
+      });
+    });
+    socket.on('error', () => {
+      clearTimeout(openTimer);
+      resolve(role ? 'joined' : 'connect-failed');
+    });
+  });
+}
+
+async function acquireRole() {
+  let delay = ACQUIRE_RETRY_MS;
+  for (let attempt = 1; ; attempt++) {
+    try {
+      const wss = await startWss();
+      wss.removeAllListeners('error');
+      becomeLeader(wss);
+      return;
+    } catch (e) {
+      if (e?.code !== 'EADDRINUSE') throw e;
+    }
+    const outcome = await joinAsFollower();
+    if (outcome === 'joined') return;
+    // Pre-relay incumbent: ask it to step aside, then retry.
+    if (outcome === 'joined-legacy') {
+      try {
+        const s = new WebSocket(`ws://${BIND_HOST}:${WS_PORT}`);
+        s.on('open', () => {
+          try { s.send(JSON.stringify({ type: '__takeover__' })); } catch {}
+          setTimeout(() => { try { s.close(); } catch {} }, 300);
+        });
+        s.on('error', () => {});
+      } catch {}
+    }
+    acquireStatus = `port ${WS_PORT} busy (${outcome})`;
+    if (attempt <= 3 || attempt % 10 === 0) {
+      console.error(`[MCP] acquire #${attempt}: ${acquireStatus}; retry in ${delay}ms`);
+    }
+    await new Promise((r) => setTimeout(r, delay));
+    delay = Math.min(delay * 2, ACQUIRE_RETRY_MAX_MS);
+  }
+}
+
+function forwardToExtension(type, payload, timeoutOverrideMs) {
+  return new Promise((resolve, reject) => {
+    const timeoutMs =
+      timeoutOverrideMs ??
+      (LONG_TIMEOUT_TOOLS.has(type) ? FORWARD_TIMEOUT_LONG_MS : FORWARD_TIMEOUT_MS);
+    if (!role) {
+      reject(new Error(`Bridge still connecting: ${acquireStatus}. Retry shortly.`));
+      return;
+    }
+    if (role.kind === 'follower') {
+      const socket = role.socket;
+      if (socket.readyState !== WebSocket.OPEN) {
+        reject(new Error('Not connected to the leader instance. Retry shortly.'));
+        return;
+      }
+      const id = String(nextId++);
+      const wait = timeoutMs + RELAY_SLACK_MS;
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error(`Leader did not respond within ${wait}ms`));
+      }, wait);
+      pending.set(id, { resolve, reject, timer, socket });
+      socket.send(JSON.stringify({ id, type: 'relay', tool: type, payload, timeoutMs }));
+      return;
+    }
+    if (!activeSocket || activeSocket.readyState !== WebSocket.OPEN) {
+      reject(
+        new Error(
+          'Extension is not connected. Load the extension and click Connect in Options → MCP Server.',
+        ),
+      );
+      return;
+    }
+    const socket = activeSocket;
+    const id = String(nextId++);
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      reject(new Error(`Extension did not respond within ${timeoutMs}ms`));
+    }, timeoutMs);
+    pending.set(id, { resolve, reject, timer, socket });
+    socket.send(JSON.stringify({ id, type, payload }));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// MCP server (stdio)
+// ---------------------------------------------------------------------------
+const server = new Server({ name: 'truepx', version: BRIDGE_VERSION }, { capabilities: { tools: {} } });
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+function forwardResult(type, payload) {
+  return forwardToExtension(type, payload).then(
+    (response) => {
+      if (response && typeof response === 'object' && 'error' in response) {
+        return { content: [{ type: 'text', text: String(response.error) }], isError: true };
+      }
+      if (response && typeof response === 'object' && response.success === false) {
+        const m = response;
+        return {
+          content: [{ type: 'text', text: typeof m.message === 'string' && m.message ? m.message : JSON.stringify(response) }],
+          isError: true,
+        };
+      }
+      return {
+        content: [{ type: 'text', text: typeof response === 'string' ? response : JSON.stringify(response) }],
+      };
+    },
+    (e) => ({ content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true }),
+  );
+}
+
+function forwardScreenshots(payload) {
+  // State matrix: {ok, states:[{state,dataUrl}]} → one image block per state.
+  return forwardToExtension('capture_states', payload, FORWARD_TIMEOUT_LONG_MS).then(
+    (response) => {
+      const states = response?.states;
+      if (!response || response.ok !== true || !Array.isArray(states)) {
+        return errText(String(response?.error ?? response?.message ?? 'capture_failed'));
+      }
+      const prefix = 'data:image/png;base64,';
+      const content = [];
+      for (const s of states) {
+        if (!s || typeof s.dataUrl !== 'string') continue;
+        content.push({
+          type: 'image',
+          data: s.dataUrl.startsWith(prefix) ? s.dataUrl.slice(prefix.length) : s.dataUrl,
+          mimeType: 'image/png',
+        });
+        content.push({ type: 'text', text: `state: ${s.state}` });
+      }
+      if (!content.length) return errText(String(response?.error ?? 'all captures failed'));
+      return { content };
+    },
+    (e) => errText(e instanceof Error ? e.message : String(e)),
+  );
+}
+
+function forwardScreenshot(payload) {
+  return forwardToExtension('capture_screenshot', payload).then(
+    (response) => {
+      if (!response || !response.ok || typeof response.dataUrl !== 'string') {
+        return errText(String(response?.reason ?? response?.error ?? 'screenshot_failed'));
+      }
+      const prefix = 'data:image/png;base64,';
+      const data = response.dataUrl.startsWith(prefix) ? response.dataUrl.slice(prefix.length) : response.dataUrl;
+      const content = [{ type: 'image', data, mimeType: 'image/png' }];
+      if (typeof response.note === 'string' && response.note) content.push({ type: 'text', text: response.note });
+      return { content };
+    },
+    (e) => errText(e instanceof Error ? e.message : String(e)),
+  );
+}
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: a } = request.params;
+  const args = a ?? {};
+  switch (name) {
+    case 'ping': {
+      const r = await forwardToExtension('ping', {});
+      if (r && typeof r === 'object' && 'error' in r) return errText(String(r.error));
+      const v = r && typeof r === 'object' && typeof r.extensionVersion === 'string' ? r.extensionVersion : null;
+      return {
+        content: [{
+          type: 'text',
+          text: v ? `pong from extension v${v} (bridge v${BRIDGE_VERSION})` : `${typeof r === 'string' ? r : JSON.stringify(r)} (bridge v${BRIDGE_VERSION})`,
+        }],
+      };
+    }
+    case 'tabs_list': return forwardResult('tabs_list', {});
+    case 'tab_focus': { const e = needTab(args, name); if (e) return e; return forwardResult(name, { tabId: args.tabId }); }
+    case 'page_info': case 'page_seo_audit': case 'page_meta':
+    case 'page_weight': case 'css_variables': case 'page_breakpoints':
+    case 'find_overflow': case 'find_inconsistencies': case 'list_pins':
+    case 'page_tech_stack': {
+      const e = needTab(args, name); if (e) return e;
+      return forwardResult(name, { tabId: args.tabId });
+    }
+    case 'get_a11y_issues': {
+      const e = needTab(args, name); if (e) return e;
+      const p = { tabId: args.tabId };
+      if (typeof args.limit === 'number') p.limit = args.limit;
+      return forwardResult(name, p);
+    }
+    case 'selection_get': case 'edits_list': {
+      const e = needTab(args, name); if (e) return e;
+      return forwardResult(name, { tabId: args.tabId });
+    }
+    case 'element_inspect': case 'css_matched_rules': {
+      if (typeof args.tabId !== 'number' || typeof args.elementId !== 'string') {
+        return errText(`${name} requires tabId (number) and elementId (string).`);
+      }
+      return forwardResult(name, { tabId: args.tabId, elementId: args.elementId, viewportId: args.viewportId });
+    }
+    case 'elements_inspect': {
+      if (typeof args.tabId !== 'number' || !Array.isArray(args.elementIds)) {
+        return errText(`${name} requires tabId (number) and elementIds (string[]).`);
+      }
+      return forwardResult(name, { tabId: args.tabId, elementIds: args.elementIds, viewportId: args.viewportId });
+    }
+    case 'dom_outline': {
+      const e = needTab(args, name); if (e) return e;
+      const p = { tabId: args.tabId };
+      for (const k of ['elementId', 'maxDepth', 'maxChildren', 'viewportId']) {
+        if (args[k] !== undefined) p[k] = args[k];
+      }
+      return forwardResult(name, p);
+    }
+    case 'dom_query': {
+      if (typeof args.tabId !== 'number' || typeof args.selector !== 'string') {
+        return errText(`${name} requires tabId (number) and selector (string).`);
+      }
+      const p = { tabId: args.tabId, selector: args.selector };
+      for (const k of ['limit', 'rootId', 'viewportId']) {
+        if (args[k] !== undefined) p[k] = args[k];
+      }
+      return forwardResult(name, p);
+    }
+    case 'capture_screenshot': {
+      const e = needTab(args, name); if (e) return e;
+      return forwardScreenshot({ tabId: args.tabId });
+    }
+    case 'capture_states': {
+      if (typeof args.tabId !== 'number' || typeof args.elementId !== 'string') {
+        return errText(`${name} requires tabId and elementId.`);
+      }
+      return forwardScreenshots({ tabId: args.tabId, elementId: args.elementId });
+    }
+    case 'font_forensics': {
+      if (typeof args.tabId !== 'number' || typeof args.elementId !== 'string') {
+        return errText(`${name} requires tabId and elementId.`);
+      }
+      return forwardResult(name, { tabId: args.tabId, elementId: args.elementId });
+    }
+    case 'find_heavy_images': {
+      const e = needTab(args, name); if (e) return e;
+      return forwardResult(name, { tabId: args.tabId });
+    }
+    case 'css_set_inline': {
+      if (typeof args.tabId !== 'number' || typeof args.styles !== 'object' || !args.styles) {
+        return errText(`${name} requires tabId (number) and styles (object).`);
+      }
+      if (args.ruleHandle !== undefined) {
+        if (typeof args.ruleHandle !== 'object' || !args.ruleHandle) return errText('ruleHandle must be the object from css_matched_rules or css_create_rule.');
+        return forwardResult(name, { tabId: args.tabId, styles: args.styles, ruleHandle: args.ruleHandle });
+      }
+      if (typeof args.elementId !== 'string' || !args.elementId.trim()) {
+        return errText(`${name} requires a non-empty elementId without ruleHandle.`);
+      }
+      return forwardResult(name, { tabId: args.tabId, elementId: args.elementId, styles: args.styles });
+    }
+    case 'css_create_rule': {
+      if (typeof args.tabId !== 'number' || typeof args.selector !== 'string' || !args.selector.trim()) {
+        return errText(`${name} requires tabId (number) and a non-empty selector.`);
+      }
+      if (args.wrappers !== undefined && (!Array.isArray(args.wrappers) || args.wrappers.some((w) => typeof w !== 'string'))) {
+        return errText('wrappers must be at-rule strings, e.g. ["@media (min-width: 768px)"].');
+      }
+      const p = { tabId: args.tabId, selector: args.selector };
+      for (const k of ['wrappers', 'styles', 'elementId']) {
+        if (args[k] !== undefined) p[k] = args[k];
+      }
+      return forwardResult(name, p);
+    }
+    case 'css_set_selector': {
+      if (typeof args.tabId !== 'number' || typeof args.ruleHandle !== 'object' || !args.ruleHandle || typeof args.selector !== 'string' || !args.selector.trim()) {
+        return errText(`${name} requires tabId, ruleHandle, and a non-empty selector.`);
+      }
+      return forwardResult(name, { tabId: args.tabId, ruleHandle: args.ruleHandle, selector: args.selector });
+    }
+    case 'edits_revert': {
+      if (typeof args.tabId !== 'number' || typeof args.changeId !== 'string' || !args.changeId) {
+        return errText(`${name} requires tabId and changeId.`);
+      }
+      return forwardResult(name, { tabId: args.tabId, changeId: args.changeId });
+    }
+    case 'edits_revert_all': {
+      const e = needTab(args, name); if (e) return e;
+      return forwardResult(name, { tabId: args.tabId });
+    }
+    case 'dom_set_text': case 'dom_set_html': {
+      const field = name === 'dom_set_text' ? 'text' : 'html';
+      if (typeof args.tabId !== 'number' || typeof args.elementId !== 'string' || typeof args[field] !== 'string') {
+        return errText(`${name} requires tabId, elementId, and ${field}.`);
+      }
+      return forwardResult(name, { tabId: args.tabId, elementId: args.elementId, [field]: args[field] });
+    }
+    case 'dom_insert_html': {
+      if (typeof args.tabId !== 'number' || typeof args.elementId !== 'string' || typeof args.html !== 'string' || typeof args.position !== 'string') {
+        return errText(`${name} requires tabId, elementId, html, position (before/after/prepend/append).`);
+      }
+      return forwardResult(name, { tabId: args.tabId, elementId: args.elementId, html: args.html, position: args.position });
+    }
+    case 'element_set_classes': {
+      if (typeof args.tabId !== 'number' || typeof args.elementId !== 'string' || typeof args.classes !== 'string') {
+        return errText(`${name} requires tabId, elementId, classes.`);
+      }
+      return forwardResult(name, { tabId: args.tabId, elementId: args.elementId, classes: args.classes });
+    }
+    case 'selection_set': case 'dom_remove': case 'dom_duplicate': {
+      if (typeof args.tabId !== 'number' || typeof args.elementId !== 'string') {
+        return errText(`${name} requires tabId and elementId.`);
+      }
+      return forwardResult(name, { tabId: args.tabId, elementId: args.elementId });
+    }
+    case 'add_pin': {
+      if (typeof args.tabId !== 'number' || typeof args.note !== 'string' || !args.note.trim()) {
+        return errText(`${name} requires tabId and a non-empty note (plus elementId or selector).`);
+      }
+      if (typeof args.elementId !== 'string' && typeof args.selector !== 'string') {
+        return errText(`${name} requires elementId or selector.`);
+      }
+      const p = { tabId: args.tabId, note: args.note };
+      if (typeof args.elementId === 'string') p.elementId = args.elementId;
+      if (typeof args.selector === 'string') p.selector = args.selector;
+      return forwardResult(name, p);
+    }
+    case 'resolve_pin': {
+      if (typeof args.tabId !== 'number' || typeof args.pinId !== 'string') {
+        return errText(`${name} requires tabId and pinId from list_pins.`);
+      }
+      const p = { tabId: args.tabId, pinId: args.pinId };
+      if (typeof args.resolved === 'boolean') p.resolved = args.resolved;
+      return forwardResult(name, p);
+    }
+    case 'fix_contrast': {
+      if (typeof args.tabId !== 'number' || typeof args.elementId !== 'string') {
+        return errText(`${name} requires tabId and elementId.`);
+      }
+      const p = { tabId: args.tabId, elementId: args.elementId };
+      if (typeof args.target === 'number') p.target = args.target;
+      if (typeof args.preview === 'boolean') p.preview = args.preview;
+      return forwardResult(name, p);
+    }
+    case 'simulate_vision': {
+      if (typeof args.tabId !== 'number' || typeof args.mode !== 'string') {
+        return errText(`${name} requires tabId and mode (protanopia | deuteranopia | tritanopia | achromatopsia | off).`);
+      }
+      return forwardResult(name, { tabId: args.tabId, mode: args.mode });
+    }
+    case 'mockup_overlay': {
+      if (typeof args.tabId !== 'number' || typeof args.action !== 'string') {
+        return errText(`${name} requires tabId and action (set | config | clear | state).`);
+      }
+      if (args.action === 'set' && (typeof args.dataUrl !== 'string' || args.dataUrl.length > 12000000)) {
+        return errText('set requires a dataUrl image (limit ~12MB string).');
+      }
+      const p = { tabId: args.tabId, action: args.action };
+      for (const k of ['dataUrl', 'name', 'opacity', 'blend', 'x', 'y', 'visible', 'scale']) {
+        if (args[k] !== undefined) p[k] = args[k];
+      }
+      return forwardResult(name, p);
+    }
+    case 'viewports_open': case 'viewports_close': case 'viewport_state': {
+      const e = needTab(args, name); if (e) return e;
+      return forwardResult(name, { tabId: args.tabId });
+    }
+    case 'sweep_breakpoints': {
+      const e = needTab(args, name); if (e) return e;
+      const p = { tabId: args.tabId };
+      if (Array.isArray(args.widths)) p.widths = args.widths.filter((w) => typeof w === 'number').slice(0, 9);
+      return forwardResult(name, p);
+    }
+    case 'viewport_update': {
+      if (typeof args.tabId !== 'number' || typeof args.width !== 'number' || typeof args.height !== 'number') {
+        return errText(`${name} requires tabId, width, height (numbers).`);
+      }
+      return forwardResult(name, { tabId: args.tabId, width: args.width, height: args.height, viewportId: args.viewportId });
+    }
+    case 'viewports_set': {
+      if (typeof args.tabId !== 'number' || !Array.isArray(args.viewports) || !args.viewports.length) {
+        return errText(`${name} requires tabId and a non-empty viewports [{width,height}].`);
+      }
+      return forwardResult(name, { tabId: args.tabId, viewports: args.viewports });
+    }
+    case 'viewport_add': {
+      const e = needTab(args, name); if (e) return e;
+      const p = { tabId: args.tabId };
+      for (const k of ['width', 'height', 'name']) {
+        if (args[k] !== undefined) p[k] = args[k];
+      }
+      return forwardResult(name, p);
+    }
+    case 'viewport_remove': {
+      if (typeof args.tabId !== 'number' || typeof args.viewportId !== 'number') {
+        return errText(`${name} requires tabId and viewportId.`);
+      }
+      return forwardResult(name, { tabId: args.tabId, viewportId: args.viewportId });
+    }
+    case 'viewports_zoom': {
+      if (typeof args.tabId !== 'number' || typeof args.zoom !== 'number') {
+        return errText(`${name} requires tabId and zoom.`);
+      }
+      return forwardResult(name, { tabId: args.tabId, zoom: args.zoom });
+    }
+    case 'breakpoints_overlay': {
+      if (typeof args.tabId !== 'number' || typeof args.enabled !== 'boolean') {
+        return errText(`${name} requires tabId and enabled (boolean).`);
+      }
+      return forwardResult(name, { tabId: args.tabId, enabled: args.enabled });
+    }
+    case 'page_typography': case 'page_colors': case 'page_assets': {
+      if (typeof args.tabId !== 'number' || typeof args.elementId !== 'string') {
+        return errText(`${name} requires tabId and elementId.`);
+      }
+      return forwardResult(name, { tabId: args.tabId, elementId: args.elementId });
+    }
+    case 'css_specificity': {
+      if (typeof args.tabId !== 'number' || typeof args.selector !== 'string' || !args.selector.trim()) {
+        return errText(`${name} requires tabId and a non-empty selector.`);
+      }
+      return forwardResult(name, { tabId: args.tabId, selector: args.selector });
+    }
+    case 'element_layout': {
+      if (typeof args.tabId !== 'number' || typeof args.elementId !== 'string') {
+        return errText(`${name} requires tabId and elementId.`);
+      }
+      return forwardResult(name, { tabId: args.tabId, elementId: args.elementId, viewportId: args.viewportId });
+    }
+    case 'element_force_state': {
+      if (typeof args.tabId !== 'number' || typeof args.elementId !== 'string' || typeof args.state !== 'string') {
+        return errText(`${name} requires tabId, elementId, state (empty clears).`);
+      }
+      return forwardResult(name, { tabId: args.tabId, elementId: args.elementId, state: args.state });
+    }
+    case 'element_tailwind': {
+      if (typeof args.tabId !== 'number' || typeof args.elementId !== 'string') {
+        return errText(`${name} requires tabId and elementId.`);
+      }
+      return forwardResult(name, { tabId: args.tabId, elementId: args.elementId });
+    }
+    case 'css_fetch_stylesheet': {
+      if (typeof args.url !== 'string' || !args.url.trim()) {
+        return errText(`${name} requires a non-empty url.`);
+      }
+      return forwardResult(name, { url: args.url });
+    }
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+});
+
+server.oninitialized = () => {
+  try {
+    const info = server.getClientVersion();
+    if (info?.name) {
+      mcpClientInfo = { name: info.name, version: info.version ?? '' };
+      sendClientInfo();
+    }
+  } catch { /* older SDK */ }
+};
+
+const transport = new StdioServerTransport();
+transport.onclose = () => {
+  console.error('[MCP] stdio closed, exiting');
+  process.exit(0);
+};
+
+acquireRole()
+  .then(() => server.connect(transport))
+  .then(() => watchStdin())
+  .catch((e) => {
+    console.error('[MCP] fatal:', e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  });
+
+// Exit when the MCP client goes away, detected as stdin ending after the
+// client has actually spoken. Installed only AFTER server.connect: attaching
+// a 'data' listener earlier puts stdin in flowing mode and would swallow the
+// initialize handshake while a follower is still joining the leader (the
+// transport attaches its own reader at connect and must see every byte).
+// The traffic guard keeps manual launches with stdin from /dev/null alive:
+// they see instant EOF with zero traffic and keep serving the bridge.
+function watchStdin() {
+  let sawStdioTraffic = false;
+  process.stdin.on('data', () => { sawStdioTraffic = true; });
+  const exitOnStdinGone = (event) => {
+    if (!sawStdioTraffic) {
+      console.error(`[MCP] stdin ${event} before traffic, staying up`);
+      return;
+    }
+    console.error(`[MCP] stdin ${event}, exiting`);
+    process.exit(0);
+  };
+  process.stdin.on('end', () => exitOnStdinGone('ended'));
+  process.stdin.on('close', () => exitOnStdinGone('closed'));
+}