2manytabs-mcp-host 2.0.0

package/bridge.js

@@ -0,0 +1,356 @@
+// 2ManyTabs MCP – Extension Bridge (self-organizing, multi-host)
+//
+// Why this exists
+// ----------------
+// MCP-over-stdio is 1:1 by design: every client (each Hermes instance, the
+// mcpjam inspector) spawns its OWN host.js and owns that process's stdio pipes.
+// That part is correct. The catch is one layer down — all those independent
+// hosts reach for a SINGLE shared resource: there is one browser, one extension,
+// one port (9876), one set of tabs. N MCP servers, a rank-1 resource.
+//
+// Previously the first host to start bound 9876 and every other host's tab tools
+// failed with "extension not connected". Worse, the winner was often a stale
+// session's host, so the session you were actually using couldn't see the tabs.
+//
+// Fix: the hosts self-organize onto the shared resource instead of fighting over it.
+//   • Exactly one host binds 9876 and owns the extension socket  → the OWNER.
+//   • Every other host connects to the owner and proxies its calls → a FOLLOWER.
+//   • If the owner dies, followers race to re-bind; one becomes the new owner and
+//     the extension reconnects to it. No external daemon, no config, and the
+//     extension never knows the difference.
+//
+//   Hermes A ─stdio▶ host(OWNER)    ─ws:9876──────▶ extension ─▶ browser tabs
+//   Hermes B ─stdio▶ host(FOLLOWER) ─ws:9876/peer─▶ OWNER ─────┘
+//
+// Public API is unchanged: startBridge(), callExtension(), isExtensionConnected().
+
+import http                         from 'http';
+import { WebSocketServer, WebSocket } from 'ws';
+
+const WS_PORT         = Number(process.env.MANYTABS_BRIDGE_PORT) || 9876; // env override is a test seam; the extension uses 9876
+const PEER_PATH       = '/peer';        // followers connect here; the extension connects to '/'
+const CALL_TIMEOUT_MS = 10_000;
+const ROUTE_GRACE_MS  = 3_500;          // absorb brief owner↔follower failover before erroring
+
+const EXT_NOT_CONNECTED_MSG =
+  'Chrome extension is not connected. Load the 2ManyTabs MCP extension in your browser ' +
+  'and confirm its popup shows "Connected".';
+
+const PNA_HEADERS = {
+  'Access-Control-Allow-Origin':          '*',
+  'Access-Control-Allow-Private-Network': 'true',
+  'Access-Control-Allow-Headers':         'content-type',
+  'Access-Control-Allow-Methods':         'GET, OPTIONS',
+};
+
+// ---------------------------------------------------------------------------
+// Module state
+// ---------------------------------------------------------------------------
+
+let role            = 'starting';   // 'starting' | 'owner' | 'follower'
+let bindInProgress  = false;
+
+// OWNER state -------------------------------------------------------
+let extensionSocket = null;         // the browser extension's socket
+const peerClients   = new Set();    // connected follower sockets
+let wireId          = 0;            // id for requests we send to the extension
+const inflight      = new Map();    // wireId → delivery descriptor (local or peer)
+
+// FOLLOWER state ----------------------------------------------------
+let peerSocket      = null;         // our client connection to the owner
+let proxyId         = 0;            // id for requests we send to the owner
+const proxyPending  = new Map();    // proxyId → { resolve, reject, timer }
+
+// Calls parked until a usable route appears (covers cold start / failover).
+const readyWaiters  = [];
+
+function log(msg) {
+  // stderr only — stdout is reserved for the MCP stdio transport.
+  process.stderr.write(`[2manytabs-mcp] ${msg}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+export function startBridge() {
+  attemptBind();
+}
+
+// ---------------------------------------------------------------------------
+// OWNER: try to bind 9876. Win → own the extension. Lose (EADDRINUSE) → follow.
+// ---------------------------------------------------------------------------
+
+function attemptBind() {
+  if (bindInProgress || role === 'owner') return;
+  bindInProgress = true;
+
+  const httpServer = http.createServer((req, res) => {
+    if (req.method === 'OPTIONS') {            // PNA preflight before the WS upgrade
+      res.writeHead(204, PNA_HEADERS);
+      res.end();
+      return;
+    }
+    res.writeHead(200, { 'Content-Type': 'text/plain' });
+    res.end('2ManyTabs MCP host running\n');
+  });
+
+  httpServer.on('error', (err) => {
+    bindInProgress = false;
+    if (err.code === 'EADDRINUSE') {
+      // Another host already owns the bridge — expected with multiple sessions. Follow it.
+      log(`Port ${WS_PORT} already owned by another host — joining as a follower.`);
+      becomeFollower();
+    } else {
+      log(`HTTP server error: ${err.message}`);
+    }
+  });
+
+  const wss = new WebSocketServer({ server: httpServer });
+
+  wss.on('headers', (headers) => {
+    headers.push('Access-Control-Allow-Origin: *');
+    headers.push('Access-Control-Allow-Private-Network: true');
+  });
+  wss.on('error', (err) => { if (err.code !== 'EADDRINUSE') log(`WebSocket error: ${err.message}`); });
+
+  wss.on('connection', (socket, req) => {
+    const origin = req.headers.origin || '';
+
+    if (req.url === PEER_PATH) {
+      // Follower connections must be node-to-node and should not have a browser origin.
+      // Standard browsers will always send an Origin header for web-based requests.
+      if (origin) {
+        log(`Rejected peer connection from non-node origin: ${origin}`);
+        socket.close(4003, 'Forbidden origin');
+        return;
+      }
+      handlePeerConnection(socket);
+    } else {
+      // Extension connections must originate from a chrome-extension:// URI.
+      if (!origin.startsWith('chrome-extension://')) {
+        log(`Rejected extension connection from unauthorized origin: ${origin}`);
+        socket.close(4003, 'Unauthorized origin');
+        return;
+      }
+      handleExtensionConnection(socket);
+    }
+  });
+
+  httpServer.listen(WS_PORT, '127.0.0.1', () => {
+    bindInProgress = false;
+    role = 'owner';
+    peerSocket = null;        // shed any stale follower state from a prior life
+    log(`Bridge OWNER listening on ws://127.0.0.1:${WS_PORT}`);
+    log('Waiting for browser extension...');
+  });
+}
+
+function handleExtensionConnection(socket) {
+  extensionSocket = socket;
+  log('Extension connected');
+  flushReady();
+
+  socket.on('message', (raw) => {
+    let msg;
+    try { msg = JSON.parse(raw); } catch { return; }
+    const d = inflight.get(msg.id);
+    if (!d) return;
+    clearTimeout(d.timer);
+    inflight.delete(msg.id);
+    deliver(d, msg.result, msg.error);
+  });
+
+  socket.on('close', () => {
+    if (extensionSocket === socket) {
+      extensionSocket = null;
+      log('Extension disconnected');
+    }
+  });
+  socket.on('error', () => { /* close handles cleanup */ });
+}
+
+function handlePeerConnection(socket) {
+  peerClients.add(socket);
+  log(`Follower host connected (${peerClients.size} active)`);
+
+  socket.on('message', (raw) => {
+    let msg;
+    try { msg = JSON.parse(raw); } catch { return; }
+    if (msg.type !== 'call') return;
+    forwardToExtension(msg.action, msg.params, { kind: 'peer', socket, peerReqId: msg.peerReqId });
+  });
+
+  socket.on('close', () => { peerClients.delete(socket); });
+  socket.on('error', () => { /* close handles cleanup */ });
+}
+
+// Send one request to the extension on behalf of a local caller or a follower.
+function forwardToExtension(action, params, descriptor) {
+  if (!extensionSocket || extensionSocket.readyState !== WebSocket.OPEN) {
+    deliver(descriptor, undefined, EXT_NOT_CONNECTED_MSG);
+    return;
+  }
+  const id = ++wireId;
+  descriptor.timer = setTimeout(() => {
+    inflight.delete(id);
+    deliver(descriptor, undefined, 'Timed out waiting for browser extension response (10s).');
+  }, CALL_TIMEOUT_MS);
+  inflight.set(id, descriptor);
+  extensionSocket.send(JSON.stringify({ id, action, ...(params || {}) }));
+}
+
+// Deliver an extension result back to wherever the request came from.
+function deliver(descriptor, result, error) {
+  if (descriptor.kind === 'local') {
+    if (error) descriptor.reject(new Error(error));
+    else       descriptor.resolve(result);
+  } else { // 'peer'
+    if (descriptor.socket.readyState === WebSocket.OPEN) {
+      descriptor.socket.send(JSON.stringify({ type: 'reply', peerReqId: descriptor.peerReqId, result, error }));
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// FOLLOWER: proxy calls to the owner; re-elect if the owner vanishes.
+// ---------------------------------------------------------------------------
+
+function becomeFollower() {
+  role = 'follower';
+  if (peerSocket && peerSocket.readyState === WebSocket.OPEN) return;
+  connectPeer();
+}
+
+function connectPeer() {
+  let socket;
+  try {
+    socket = new WebSocket(`ws://127.0.0.1:${WS_PORT}${PEER_PATH}`);
+  } catch {
+    scheduleReElection();
+    return;
+  }
+  peerSocket = socket;
+
+  socket.on('open', () => {
+    log('Bridge FOLLOWER connected to owner');
+    flushReady();
+  });
+
+  socket.on('message', (raw) => {
+    let msg;
+    try { msg = JSON.parse(raw); } catch { return; }
+    if (msg.type !== 'reply') return;
+    const p = proxyPending.get(msg.peerReqId);
+    if (!p) return;
+    clearTimeout(p.timer);
+    proxyPending.delete(msg.peerReqId);
+    if (msg.error) p.reject(new Error(msg.error));
+    else           p.resolve(msg.result);
+  });
+
+  socket.on('close', () => {
+    if (peerSocket === socket) peerSocket = null;
+    failProxyPending();
+    scheduleReElection();   // owner may have died — try to take over
+  });
+  socket.on('error', () => { /* close follows */ });
+}
+
+// The owner connection dropped. After a little jitter (to avoid a thundering
+// herd of followers), try to become the owner. Whoever wins the port wins;
+// the rest will EADDRINUSE and fall back to following the new owner.
+function scheduleReElection() {
+  const delay = 200 + Math.floor(Math.random() * 300);
+  setTimeout(() => {
+    if (role === 'follower' && (!peerSocket || peerSocket.readyState !== WebSocket.OPEN)) {
+      attemptBind();
+    }
+  }, delay);
+}
+
+function followerCall(action, params) {
+  if (!peerSocket || peerSocket.readyState !== WebSocket.OPEN) {
+    return Promise.reject(new Error(EXT_NOT_CONNECTED_MSG));
+  }
+  const peerReqId = ++proxyId;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      proxyPending.delete(peerReqId);
+      reject(new Error('Timed out waiting for browser extension response (10s).'));
+    }, CALL_TIMEOUT_MS);
+    proxyPending.set(peerReqId, { resolve, reject, timer });
+    peerSocket.send(JSON.stringify({ type: 'call', peerReqId, action, params }));
+  });
+}
+
+function failProxyPending() {
+  for (const [, p] of proxyPending) {
+    clearTimeout(p.timer);
+    p.reject(new Error('Bridge owner connection lost; please retry.'));
+  }
+  proxyPending.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Routing readiness — a call needs a live route (owner+extension, or
+// follower+owner). In steady state this resolves instantly; during a cold
+// start or a brief failover it parks the call up to ROUTE_GRACE_MS.
+// ---------------------------------------------------------------------------
+
+function hasRoute() {
+  if (role === 'owner')    return !!extensionSocket && extensionSocket.readyState === WebSocket.OPEN;
+  if (role === 'follower') return !!peerSocket      && peerSocket.readyState      === WebSocket.OPEN;
+  return false;
+}
+
+function flushReady() {
+  if (!hasRoute()) return;
+  while (readyWaiters.length) readyWaiters.shift()();
+}
+
+function waitForRoute() {
+  if (hasRoute()) return Promise.resolve(role);
+  return new Promise((resolve, reject) => {
+    const onReady = () => {
+      clearTimeout(timer);
+      const i = readyWaiters.indexOf(onReady);
+      if (i >= 0) readyWaiters.splice(i, 1);
+      resolve(role);
+    };
+    const timer = setTimeout(() => {
+      const i = readyWaiters.indexOf(onReady);
+      if (i >= 0) readyWaiters.splice(i, 1);
+      reject(new Error(EXT_NOT_CONNECTED_MSG));
+    }, ROUTE_GRACE_MS);
+    readyWaiters.push(onReady);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Public primitive used by every tool.
+// ---------------------------------------------------------------------------
+
+export async function callExtension(action, params = {}) {
+  const activeRole = await waitForRoute();          // throws the clear error after the grace window
+  if (activeRole === 'owner') {
+    return new Promise((resolve, reject) => {
+      forwardToExtension(action, params, { kind: 'local', resolve, reject });
+    });
+  }
+  return followerCall(action, params);
+}
+
+export function isExtensionConnected() {
+  return hasRoute();
+}
+
+// Lightweight introspection for logging / a future status tool.
+export function bridgeStatus() {
+  return {
+    role,
+    extension_connected: !!extensionSocket && extensionSocket.readyState === WebSocket.OPEN,
+    followers: peerClients.size,
+    owner_reachable: role === 'follower' ? (!!peerSocket && peerSocket.readyState === WebSocket.OPEN) : undefined,
+  };
+}

package/host.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// 2ManyTabs MCP – Host (MCP server over stdio)
+//
+//   Hermes ─stdio(JSON-RPC)─▶ host.js ─ws/127.0.0.1:9876─▶ background.js ─▶ chrome.tabs
+//
+// Architecture mirrors gemini-mcp-tool's "unified tool" pattern: one self-contained
+// file per tool, collected in tools/index.js. The difference — and the point of this
+// rewrite — is that SDK 1.x's McpServer.registerTool() absorbs the hand-rolled
+// registry.ts (zod-to-json-schema, getToolDefinitions, executeTool, manual Zod parsing)
+// that the 0.5-era SDK forced us to write. We keep the modular philosophy; the SDK
+// keeps the boilerplate.
+
+import { McpServer }            from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { startBridge }          from './bridge.js';
+import { toolRegistry }         from './tools/index.js';
+
+const server = new McpServer({ name: '2manytabs-mcp', version: '2.0.0' });
+
+// Register every tool generically. Adding a tool requires zero changes here.
+for (const tool of toolRegistry) {
+  server.registerTool(
+    tool.name,
+    {
+      title:       tool.title,
+      description: tool.description,
+      inputSchema: tool.inputSchema,   // raw Zod shape — SDK derives JSON Schema + validates
+      annotations: tool.annotations,    // readOnly/destructive hints (new in modern MCP)
+    },
+    async (args) => {
+      try {
+        const text = await tool.execute(args);
+        return { content: [{ type: 'text', text }] };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `Error in ${tool.name}: ${err.message}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+}
+
+// Bring up the extension bridge, then connect MCP over stdio.
+startBridge();
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write(`[2manytabs-mcp] MCP server ready (${toolRegistry.length} tools) on stdio\n`);
+
+// Ensure clean exit when the parent process disconnects or terminates
+const cleanup = () => process.exit(0);
+process.stdin.on('close', cleanup);
+process.stdin.on('end', cleanup);
+process.on('SIGINT', cleanup);
+process.on('SIGTERM', cleanup);

package/lib/tabs.js

@@ -0,0 +1,94 @@
+// Pure tab-selection helpers — shared by the list_tabs and close_tabs tools.
+// Keeping these side-effect-free makes the tools easy to reason about and test.
+
+/** Extract a display domain from a tab URL, tolerating chrome://, file://, blank. */
+export function domainOf(tab) {
+  try {
+    const u = new URL(tab.url);
+    if (u.protocol === 'chrome:' || u.protocol === 'chrome-extension:') {
+      return `${u.protocol}//${u.hostname || u.pathname.split('/')[0] || ''}`.replace(/\/$/, '');
+    }
+    return u.hostname || '(local)';
+  } catch {
+    return '(unknown)';
+  }
+}
+
+/** Case-insensitive substring match against title OR url. */
+export function matchesQuery(tab, q) {
+  const needle = q.toLowerCase();
+  return (tab.title ?? '').toLowerCase().includes(needle) ||
+         (tab.url ?? '').toLowerCase().includes(needle);
+}
+
+/**
+ * Return the ids of duplicate tabs — every tab sharing a URL with an earlier
+ * tab. The first occurrence of each URL is kept; the rest are returned.
+ */
+export function findDuplicateIds(tabs) {
+  const seen = new Set();
+  const dupes = [];
+  for (const t of tabs) {
+    if (seen.has(t.url)) dupes.push(t.id);
+    else seen.add(t.url);
+  }
+  return dupes;
+}
+
+/** Build a { domain -> count } histogram, sorted by count descending. */
+export function domainHistogram(tabs, limit = 15) {
+  const counts = {};
+  for (const t of tabs) {
+    const d = domainOf(t);
+    counts[d] = (counts[d] ?? 0) + 1;
+  }
+  return Object.entries(counts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(([domain, count]) => ({ domain, count }));
+}
+
+/** Group tabs by domain → { domain: { count, tab_ids, sample_titles } }, sorted by count. */
+export function groupByDomain(tabs) {
+  const groups = {};
+  for (const t of tabs) {
+    const d = domainOf(t);
+    (groups[d] ??= []).push(t);
+  }
+  return Object.fromEntries(
+    Object.entries(groups)
+      .sort((a, b) => b[1].length - a[1].length)
+      .map(([domain, list]) => [domain, {
+        count: list.length,
+        tab_ids: list.map(t => t.id),
+        sample_titles: list.slice(0, 3).map(t => t.title || '(untitled)'),
+      }])
+  );
+}
+
+/** Group tabs by windowId → { windowId: { count, tab_ids } }. */
+export function groupByWindow(tabs) {
+  const groups = {};
+  for (const t of tabs) {
+    (groups[t.windowId] ??= []).push(t);
+  }
+  return Object.fromEntries(
+    Object.entries(groups).map(([win, list]) => [win, {
+      count: list.length,
+      tab_ids: list.map(t => t.id),
+    }])
+  );
+}
+
+/** Trim a tab to a compact shape for listing (keeps token cost sane at 1000 tabs). */
+export function compact(tab) {
+  const title = tab.title ?? '';
+  return {
+    id: tab.id,
+    window: tab.windowId,
+    title: title.length > 80 ? title.slice(0, 77) + '…' : title,
+    url: tab.url ?? '',
+    pinned: tab.pinned || undefined,
+    audible: tab.audible || undefined,
+  };
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "2manytabs-mcp-host",
+  "version": "2.0.0",
+  "description": "MCP server that exposes Chrome tabs via the 2ManyTabs MCP extension",
+  "type": "module",
+  "main": "host.js",
+  "bin": {
+    "2manytabs-mcp": "host.js"
+  },
+  "files": [
+    "host.js",
+    "bridge.js",
+    "lib/",
+    "tools/"
+  ],
+  "scripts": {
+    "start": "node host.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ws": "^8.18.0",
+    "zod": "^4.4.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/tools/close-tabs.tool.js

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { callExtension } from '../bridge.js';
+import { matchesQuery, findDuplicateIds, domainOf } from '../lib/tabs.js';
+
+// ACT tool. Absorbs the old close_tabs + close_tabs_matching + close_duplicate_tabs.
+// Exactly one selection mode must be supplied. `dry_run` previews without closing —
+// the safe way to verify a bulk close of hundreds of tabs before committing.
+export const closeTabsTool = {
+  name: 'close_tabs',
+  title: 'Close Tabs',
+  description:
+    'Close Chrome tabs by one selection mode: `tab_ids` (explicit), `match` (substring of ' +
+    'title/URL), or `duplicates` (every tab sharing a URL with an earlier one). Set `dry_run` ' +
+    'to preview the exact tabs that would close without touching them. Destructive — closed ' +
+    'tabs cannot be recovered through this tool.\n\n' +
+    'CRITICAL: You MUST explicitly ask the user for confirmation before running this tool with ' +
+    'dry_run=false, unless they already asked you to.\n\n' +
+    'Examples:\n' +
+    '- {"tab_ids": [123, 456], "dry_run": true}\n' +
+    '- {"match": "github.com", "dry_run": false}\n' +
+    '- {"duplicates": true, "dry_run": true}\n\n' +
+    'Returns:\n' +
+    '  JSON object containing:\n' +
+    '  - dry_run (boolean): Whether this was a preview\n' +
+    '  - reason (string): Description of selection criteria\n' +
+    '  - count/closed (int): Number of tabs matched/closed\n' +
+    '  - by_domain (object): Map of domain to count\n' +
+    '  - sample (array): First 10 tabs with {id, title}',
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  inputSchema: {
+    tab_ids: z.array(z.number().int()).optional()
+      .describe('Explicit tab IDs to close (from list_tabs).'),
+    match: z.string().optional()
+      .describe('Close every tab whose title or URL contains this substring (case-insensitive).'),
+    duplicates: z.boolean().default(false)
+      .describe('Close duplicate tabs, keeping the first occurrence of each URL.'),
+    dry_run: z.boolean().default(false)
+      .describe('Preview the tabs that would close — does not close anything. Recommended for bulk closes.'),
+  },
+
+  execute: async ({ tab_ids, match, duplicates, dry_run }) => {
+    // Enforce exactly one selection mode.
+    const modes = [tab_ids?.length ? 'tab_ids' : null, match ? 'match' : null, duplicates ? 'duplicates' : null]
+      .filter(Boolean);
+    if (modes.length === 0) {
+      throw new Error('Provide one selection mode: tab_ids, match, or duplicates:true.');
+    }
+    if (modes.length > 1) {
+      throw new Error(`Use only one selection mode at a time (got: ${modes.join(', ')}).`);
+    }
+
+    const all = await callExtension('query_tabs');
+    const byId = new Map(all.map((t) => [t.id, t]));
+
+    let targets, reason;
+    if (tab_ids?.length) {
+      targets = tab_ids.filter((id) => byId.has(id)).map((id) => byId.get(id));
+      reason = `${targets.length} tab(s) by id`;
+      const missing = tab_ids.filter((id) => !byId.has(id));
+      if (missing.length) reason += ` (${missing.length} id(s) no longer exist, skipped)`;
+    } else if (duplicates) {
+      const dupIds = new Set(findDuplicateIds(all));
+      targets = all.filter((t) => dupIds.has(t.id));
+      reason = 'duplicate tabs';
+    } else {
+      targets = all.filter((t) => matchesQuery(t, match));
+      reason = `tabs matching "${match}"`;
+    }
+
+    if (targets.length === 0) {
+      return `No tabs matched (${reason}). Nothing to close.`;
+    }
+
+    const preview = {
+      reason,
+      count: targets.length,
+      by_domain: targets.reduce((acc, t) => {
+        const d = domainOf(t);
+        acc[d] = (acc[d] ?? 0) + 1;
+        return acc;
+      }, {}),
+      sample: targets.slice(0, 10).map((t) => ({ id: t.id, title: t.title || '(untitled)' })),
+    };
+
+    if (dry_run) {
+      return JSON.stringify({ dry_run: true, ...preview }, null, 2);
+    }
+
+    const res = await callExtension('close_tabs', { tab_ids: targets.map((t) => t.id) });
+    return JSON.stringify({ dry_run: false, closed: res.closed, reason, by_domain: preview.by_domain, sample: preview.sample }, null, 2);
+  },
+};

package/tools/index.js

@@ -0,0 +1,13 @@
+// Tool registry — the single place that knows which tools exist.
+// To add a tool: create ./my-thing.tool.js exporting a tool object, then add it here.
+// host.js handles all SDK wiring (schema generation, validation, dispatch) generically.
+
+import { listTabsTool }  from './list-tabs.tool.js';
+import { closeTabsTool } from './close-tabs.tool.js';
+import { openTabsTool }  from './open-tabs.tool.js';
+
+export const toolRegistry = [
+  listTabsTool,
+  closeTabsTool,
+  openTabsTool,
+];

package/tools/list-tabs.tool.js

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+import { callExtension } from '../bridge.js';
+import {
+  matchesQuery, findDuplicateIds, domainHistogram,
+  groupByDomain, groupByWindow, compact,
+} from '../lib/tabs.js';
+
+// READ tool. Absorbs the old list_tabs + get_tab_groups.
+// Always returns a domain histogram up top so the agent gets an instant map of
+// 1000 tabs before deciding what to close.
+export const listTabsTool = {
+  name: 'list_tabs',
+  title: 'List Tabs',
+  description:
+    'Read open Chrome tabs. Returns a domain histogram (the fastest way to understand a large ' +
+    'tab set) plus a detailed view. When summarizing the results for the user, you should ' +
+    'include the histogram bar graph in your response. Filter with `query`, reshape with ' +
+    '`group_by`, or isolate redundant tabs with `duplicates_only`. Read-only — never closes anything.',
+  annotations: { readOnlyHint: true, openWorldHint: true },
+  inputSchema: {
+    query: z.string().optional()
+      .describe('Case-insensitive substring; keep only tabs whose title or URL contains it.'),
+    group_by: z.enum(['none', 'domain', 'window']).default('domain')
+      .describe("Shape of the detailed view. 'domain' (default) is best for triaging many tabs; " +
+        "'window' groups by browser window; 'none' returns a flat list."),
+    duplicates_only: z.boolean().default(false)
+      .describe('Only include tabs that are duplicates (share a URL with an earlier tab).'),
+  },
+
+  execute: async ({ query, group_by, duplicates_only }) => {
+    const all = await callExtension('query_tabs');
+
+    let tabs = all;
+    if (query) tabs = tabs.filter((t) => matchesQuery(t, query));
+    if (duplicates_only) {
+      const dupIds = new Set(findDuplicateIds(tabs));
+      tabs = tabs.filter((t) => dupIds.has(t.id));
+    }
+
+    const windows = new Set(tabs.map((t) => t.windowId)).size;
+    const dupCount = findDuplicateIds(tabs).length;
+
+    const histogram = domainHistogram(tabs);
+
+    // Build a human-readable grouped summary that naturally guides the agent
+    // to present tabs in a logical way.
+    const lines = [];
+
+    // Header line
+    lines.push(`📊 ${tabs.length} tab(s) across ${windows} window(s)` +
+      (query ? ` matching "${query}"` : '') +
+      (duplicates_only ? ' (duplicates only)' : '') +
+      (dupCount > 0 ? ` · ${dupCount} duplicate(s) found` : '') +
+      '\n');
+
+    // Domain summary bar
+    lines.push('Domains:');
+    for (const d of histogram) {
+      const bar = '▇'.repeat(Math.max(1, Math.round(d.count / Math.max(...histogram.map(x => x.count)) * 20)));
+      lines.push(`  ${bar}  ${d.domain.padEnd(28)} ${d.count} tab(s)`);
+    }
+    lines.push('');
+
+    // Detailed grouped view
+    if (group_by === 'domain') {
+      const groups = groupByDomain(tabs);
+      for (const [domain, info] of Object.entries(groups)) {
+        lines.push(`📁 ${domain} — ${info.count} tab(s)`);
+        for (const id of info.tab_ids) {
+          const tab = tabs.find(t => t.id === id);
+          if (!tab) continue;
+          const label = (tab.title || '(untitled)').length > 90
+            ? (tab.title || '(untitled)').slice(0, 87) + '…'
+            : (tab.title || '(untitled)');
+          const flags = [];
+          if (tab.pinned) flags.push('📌');
+          if (tab.audible) flags.push('🔊');
+          const flagStr = flags.length ? ' ' + flags.join('') : '';
+          lines.push(`    · ${label}${flagStr}`);
+        }
+        lines.push('');
+      }
+    } else if (group_by === 'window') {
+      const groups = groupByWindow(tabs);
+      for (const [winId, info] of Object.entries(groups)) {
+        lines.push(`🪟 Window ${winId} — ${info.count} tab(s)`);
+        for (const id of info.tab_ids) {
+          const tab = tabs.find(t => t.id === id);
+          if (!tab) continue;
+          const label = (tab.title || '(untitled)').length > 90
+            ? (tab.title || '(untitled)').slice(0, 87) + '…'
+            : (tab.title || '(untitled)');
+          lines.push(`    · ${label}`);
+        }
+        lines.push('');
+      }
+    } else {
+      for (const t of tabs) {
+        const c = compact(t);
+        const label = c.title.length > 90 ? c.title.slice(0, 87) + '…' : c.title;
+        const flags = [];
+        if (c.pinned) flags.push('📌');
+        if (c.audible) flags.push('🔊');
+        const flagStr = flags.length ? ' ' + flags.join('') : '';
+        lines.push(`  · ${label}${flagStr}`);
+      }
+    }
+
+    return lines.join('\n');
+  },
+};

package/tools/open-tabs.tool.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { callExtension } from '../bridge.js';
+
+export const openTabsTool = {
+  name: 'open_tabs',
+  title: 'Open Tabs',
+  description:
+    'Open one or more URLs in new Chrome tabs. This tool allows you to navigate the user to ' +
+    'specific web pages or search queries.\n\n' +
+    'Examples:\n' +
+    '- {"urls": ["https://github.com", "https://youtube.com"]}\n' +
+    '- {"urls": ["en.wikipedia.org/wiki/Palantir"]}\n\n' +
+    'Returns:\n' +
+    '  JSON object containing:\n' +
+    '  - opened (int): Number of tabs successfully opened',
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false, // opening tabs is non-destructive
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  inputSchema: {
+    urls: z.array(z.string()).min(1)
+      .describe('An array of URLs to open. If no protocol is provided, https:// will be prepended automatically.'),
+  },
+
+  execute: async ({ urls }) => {
+    if (!urls || urls.length === 0) {
+      throw new Error('Provide at least one URL to open.');
+    }
+
+    const res = await callExtension('open_tabs', { urls });
+    return JSON.stringify({ opened: res.opened }, null, 2);
+  },
+};