2manytabs-mcp-host 2.0.0 → 2.1.0

package/bridge.js

@@ -32,6 +32,9 @@ const PEER_PATH       = '/peer';        // followers connect here; the extension
 const CALL_TIMEOUT_MS = 10_000;
 const ROUTE_GRACE_MS  = 3_500;          // absorb brief owner↔follower failover before erroring
 
+// chrome-extension:// for Chromium builds, moz-extension:// for Firefox.
+const ALLOWED_EXTENSION_ORIGIN_PREFIXES = ['chrome-extension://', 'moz-extension://'];
+
 const EXT_NOT_CONNECTED_MSG =
   'Chrome extension is not connected. Load the 2ManyTabs MCP extension in your browser ' +
   'and confirm its popup shows "Connected".';
@@ -127,8 +130,8 @@ function attemptBind() {
       }
       handlePeerConnection(socket);
     } else {
-      // Extension connections must originate from a chrome-extension:// URI.
-      if (!origin.startsWith('chrome-extension://')) {
+      // Extension connections must originate from a browser-extension URI.
+      if (!ALLOWED_EXTENSION_ORIGIN_PREFIXES.some(prefix => origin.startsWith(prefix))) {
         log(`Rejected extension connection from unauthorized origin: ${origin}`);
         socket.close(4003, 'Unauthorized origin');
         return;

package/host.js

@@ -1,31 +1,19 @@
 #!/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 { 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';
+import { startBridge } from './bridge.js';
+import { toolRegistry } from './tools/index.js';
 
-const server = new McpServer({ name: '2manytabs-mcp', version: '2.0.0' });
+const server = new McpServer({ name: '2manytabs-mcp', version: '2.1.0' });
 
-// Register every tool generically. Adding a tool requires zero changes here.
 for (const tool of toolRegistry) {
   server.registerTool(
     tool.name,
     {
-      title:       tool.title,
+      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)
+      inputSchema: tool.inputSchema,
+      annotations: tool.annotations,
     },
     async (args) => {
       try {
@@ -41,14 +29,12 @@ for (const tool of toolRegistry) {
   );
 }
 
-// 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);

package/lib/tabs.js

@@ -1,17 +1,30 @@
-// 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.
+// Utilities for filtering, grouping, and formatting tab data.
+// All functions are side-effect-free to simplify testing and reasoning.
 
-/** Extract a display domain from a tab URL, tolerating chrome://, file://, blank. */
+/** Maximum number of tabs to include in list operations. */
+export const MAX_TAB_LIST = 1000;
+
+/** Title truncation length for full tab descriptions. */
+export const TITLE_TRUNCATE_FULL = 80;
+
+/** Title truncation length for compact labels. */
+export const TITLE_TRUNCATE_LABEL = 90;
+
+/** Maximum width (in characters) of histogram bars. */
+export const HISTOGRAM_BAR_MAX = 20;
+
+/** Extract a display domain from a tab URL, tolerating chrome://, file://, blank.
+ * Throws on URL parse errors to preserve data integrity visibility. */
 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)';
+  if (!tab || tab.url == null) {
+    console.error('[domainOf] tab URL is missing or tab is null/undefined:', tab);
+    throw new Error('tab.url is missing or null');
+  }
+  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)';
 }
 
 /** Case-insensitive substring match against title OR url. */
@@ -80,13 +93,27 @@ export function groupByWindow(tabs) {
   );
 }
 
-/** Trim a tab to a compact shape for listing (keeps token cost sane at 1000 tabs). */
+/** Return the [Group: …] prefix string for a tab, or '' if ungrouped. */
+export function getGroupPrefix(tab, groupMap) {
+  if (tab.groupId === undefined || tab.groupId === -1) return '';
+  const g = groupMap.get(tab.groupId);
+  return g ? `[Group: ${g.title || 'Group ' + g.id}] ` : '';
+}
+
+/** Tab label truncation helper. */
+export function tabLabel(tab) {
+  const t = tab.title || '(untitled)';
+  return t.length > TITLE_TRUNCATE_LABEL ? t.slice(0, TITLE_TRUNCATE_LABEL - 3) + '…' : t;
+}
+
+/** Trim a tab to a compact shape for listing. */
 export function compact(tab) {
   const title = tab.title ?? '';
   return {
     id: tab.id,
     window: tab.windowId,
-    title: title.length > 80 ? title.slice(0, 77) + '…' : title,
+    group: (tab.groupId !== undefined && tab.groupId !== -1) ? tab.groupId : undefined,
+    title: title.length > TITLE_TRUNCATE_FULL ? title.slice(0, TITLE_TRUNCATE_FULL - 3) + '…' : title,
     url: tab.url ?? '',
     pinned: tab.pinned || undefined,
     audible: tab.audible || undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "2manytabs-mcp-host",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "MCP server that exposes Chrome tabs via the 2ManyTabs MCP extension",
   "type": "module",
   "main": "host.js",
@@ -10,11 +10,18 @@
   "files": [
     "host.js",
     "bridge.js",
-    "lib/",
+    "lib/tabs.js",
     "tools/"
   ],
   "scripts": {
-    "start": "node host.js"
+    "start": "node host.js",
+    "test":  "node --test lib/tabs.test.js lib/background.test.js",
+    "lint":  "eslint ."
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "eslint":     "^9.0.0",
+    "globals":    "^15.0.0"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/tools/activate-tab.tool.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { callExtension } from '../bridge.js';
+
+export const activateTabTool = {
+  name: 'activate_tab',
+  title: 'Activate Tab',
+  description:
+    'Bring a specific browser tab to the foreground. This activates the tab ' +
+    'and focuses its containing window so the user sees it immediately.',
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  inputSchema: {
+    tab_id: z.number().int()
+      .describe('The numeric ID of the tab to activate.'),
+  },
+
+  execute: async ({ tab_id }) => {
+    const res = await callExtension('activate_tab', { tab_id });
+    return JSON.stringify({
+      message: `Successfully activated tab ${tab_id}.`,
+      tabId: res.activated,
+    }, null, 2);
+  },
+};

package/tools/close-tabs.tool.js

@@ -2,9 +2,6 @@ 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',
@@ -54,7 +51,13 @@ export const closeTabsTool = {
       throw new Error(`Use only one selection mode at a time (got: ${modes.join(', ')}).`);
     }
 
-    const all = await callExtension('query_tabs');
+    let all;
+    try {
+      all = await callExtension('query_tabs');
+    } catch (err) {
+      console.error('Failed to fetch tabs:', err);
+      throw new Error('Failed to fetch open tabs from extension.');
+    }
     const byId = new Map(all.map((t) => [t.id, t]));
 
     let targets, reason;

package/tools/get-tab-text.tool.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { callExtension } from '../bridge.js';
+
+export const getTabTextTool = {
+  name: 'get_tab_text',
+  title: 'Get Tab Text',
+  description:
+    'Extract the plain body text content of a loaded browser tab using scripting. ' +
+    'This allows reading and analyzing tab contents (e.g. for summarization or classification). ' +
+    'Note: Fails on restricted internal browser pages (e.g., chrome://, edge://, or extensions) or if the tab is not loaded.',
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  inputSchema: {
+    tab_id: z.number().int()
+      .describe('The numeric ID of the tab whose body text to extract.'),
+  },
+
+  execute: async ({ tab_id }) => {
+    const res = await callExtension('get_tab_text', { tab_id });
+    if (!res.text) {
+      return `Tab ${tab_id} returned no text content (it might be empty, loading, or restricted).`;
+    }
+    return res.text;
+  },
+};

package/tools/group-tabs.tool.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { callExtension } from '../bridge.js';
+
+export const groupTabsTool = {
+  name: 'group_tabs',
+  title: 'Group Tabs',
+  description:
+    'Group open Chrome tabs into native Chrome Tab Groups. Can create a new group or ' +
+    'add tabs to an existing group. Optionally set a title and a color for the group.',
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  inputSchema: {
+    tab_ids: z.array(z.number().int()).min(1)
+      .describe('Array of tab IDs to add to the group.'),
+    group_id: z.number().int().optional()
+      .describe('Add to an existing group ID. If omitted, a new group is created.'),
+    title: z.string().optional()
+      .describe('Title to set on the group (new or existing).'),
+    color: z.enum(['grey', 'blue', 'red', 'yellow', 'green', 'pink', 'purple', 'cyan', 'orange']).optional()
+      .describe('Color to set on the group (new or existing).'),
+  },
+
+  execute: async ({ tab_ids, group_id, title, color }) => {
+    const res = await callExtension('group_tabs', { tab_ids, group_id, title, color });
+    return JSON.stringify({
+      message: `Successfully grouped ${tab_ids.length} tab(s).`,
+      groupId: res.groupId,
+    }, null, 2);
+  },
+};

package/tools/index.js

@@ -5,9 +5,23 @@
 import { listTabsTool }  from './list-tabs.tool.js';
 import { closeTabsTool } from './close-tabs.tool.js';
 import { openTabsTool }  from './open-tabs.tool.js';
+import { listTabGroupsTool } from './list-tab-groups.tool.js';
+import { groupTabsTool } from './group-tabs.tool.js';
+import { ungroupTabsTool } from './ungroup-tabs.tool.js';
+import { updateTabGroupTool } from './update-tab-group.tool.js';
+import { activateTabTool } from './activate-tab.tool.js';
+import { updateTabTool } from './update-tab.tool.js';
+import { getTabTextTool } from './get-tab-text.tool.js';
 
 export const toolRegistry = [
   listTabsTool,
   closeTabsTool,
   openTabsTool,
+  listTabGroupsTool,
+  groupTabsTool,
+  ungroupTabsTool,
+  updateTabGroupTool,
+  activateTabTool,
+  updateTabTool,
+  getTabTextTool,
 ];

package/tools/list-tab-groups.tool.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { callExtension } from '../bridge.js';
+
+export const listTabGroupsTool = {
+  name: 'list_tab_groups',
+  title: 'List Tab Groups',
+  description:
+    'List all existing native Chrome Tab Groups in the current browser session. ' +
+    'Returns their IDs, titles, colors, collapsed states, and parent window IDs.',
+  annotations: { readOnlyHint: true, openWorldHint: true },
+  inputSchema: {
+    title_query: z.string().optional()
+      .describe('Case-insensitive substring filter for group titles.'),
+  },
+
+  // fallow-ignore-next-line complexity
+  execute: async ({ title_query }) => {
+    let groups;
+    try {
+      groups = await callExtension('query_groups');
+    } catch (err) {
+      console.error('Failed to fetch tab groups:', err);
+      throw new Error('Failed to fetch tab groups from extension.');
+    }
+    let filtered = groups;
+    if (title_query) {
+      const q = title_query.toLowerCase();
+      filtered = groups.filter((g) => (g.title || '').toLowerCase().includes(q));
+    }
+
+    if (filtered.length === 0) {
+      return title_query
+        ? `No tab groups matched "${title_query}".`
+        : 'No tab groups found in the browser session.';
+    }
+
+    const lines = [`📁 ${filtered.length} tab group(s) found:`];
+    for (const g of filtered) {
+      const titleStr = g.title ? `"${g.title}"` : '(unnamed)';
+      const collapsedStr = g.collapsed ? ' ⏸ (collapsed)' : ' ▶ (expanded)';
+      lines.push(`  · [ID: ${g.id}] ${titleStr} [Color: ${g.color}] [Window: ${g.windowId}]${collapsedStr}`);
+    }
+
+    return lines.join('\n');
+  },
+};

package/tools/list-tabs.tool.js

@@ -2,12 +2,10 @@ import { z } from 'zod';
 import { callExtension } from '../bridge.js';
 import {
   matchesQuery, findDuplicateIds, domainHistogram,
-  groupByDomain, groupByWindow, compact,
+  MAX_TAB_LIST,
 } from '../lib/tabs.js';
+import { formatTabData } from './present.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',
@@ -30,6 +28,16 @@ export const listTabsTool = {
   execute: async ({ query, group_by, duplicates_only }) => {
     const all = await callExtension('query_tabs');
 
+    let groups;
+    try {
+      groups = await callExtension('query_groups');
+    } catch (err) {
+      console.error('Failed to fetch tab groups:', err);
+      throw new Error('Failed to fetch tab groups from extension.');
+    }
+
+    const groupMap = new Map(groups.map(g => [g.id, g]));
+
     let tabs = all;
     if (query) tabs = tabs.filter((t) => matchesQuery(t, query));
     if (duplicates_only) {
@@ -37,75 +45,24 @@ export const listTabsTool = {
       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)`);
+    // Apply MAX_TAB_LIST limit to prevent token overflow
+    if (tabs.length > MAX_TAB_LIST) {
+      tabs = tabs.slice(0, MAX_TAB_LIST);
     }
-    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}`);
-      }
-    }
+    const histogram = domainHistogram(tabs);
+    const windows = new Set(tabs.map((t) => t.windowId)).size;
+    const dupCount = findDuplicateIds(tabs).length;
 
-    return lines.join('\n');
+    return formatTabData({
+      tabs,
+      histogram,
+      groupMap,
+      group_by,
+      query,
+      duplicates_only,
+      windows,
+      dupCount,
+    });
   },
 };

package/tools/present.js

@@ -0,0 +1,123 @@
+import {
+  compact,
+  tabLabel,
+  TITLE_TRUNCATE_FULL,
+  HISTOGRAM_BAR_MAX,
+} from '../lib/tabs.js';
+import {
+  buildFlags,
+  formatFlags,
+  drawBar,
+  formatHistogramLine,
+  formatDomainHeader,
+  formatWindowHeader,
+  formatGroupPrefix,
+  formatIdPrefix,
+} from './rendering.js';
+
+function renderHistogram(histogram) {
+  const maxCount = Math.max(...histogram.map((x) => x.count));
+  const lines = ['Domains:'];
+
+  for (const { domain, count } of histogram) {
+    const bar = drawBar(count, maxCount, HISTOGRAM_BAR_MAX);
+    lines.push(formatHistogramLine(domain, count, bar));
+  }
+
+  return lines;
+}
+
+function renderByDomain(tabs, groupMap) {
+  const grouped = {};
+  for (const t of tabs) {
+    const domain = t.url ? new URL(t.url).hostname : '(local)';
+    (grouped[domain] ??= []).push(t);
+  }
+
+  const lines = [];
+  for (const [domain, tabsInDomain] of Object.entries(grouped)) {
+    lines.push(formatDomainHeader(domain, tabsInDomain.length));
+    for (const t of tabsInDomain) {
+      const label = tabLabel(t);
+      const flags = buildFlags(t);
+      const flagStr = formatFlags(flags);
+      lines.push(`    · ${formatIdPrefix(t)}${formatGroupPrefix(groupMap, t)}${label}${flagStr}`);
+    }
+    lines.push('');
+  }
+
+  return lines;
+}
+
+function renderByWindow(tabs, groupMap) {
+  const grouped = {};
+  for (const t of tabs) {
+    (grouped[t.windowId] ??= []).push(t);
+  }
+
+  const lines = [];
+  for (const [winId, tabsInWin] of Object.entries(grouped)) {
+    lines.push(formatWindowHeader(winId, tabsInWin.length));
+    for (const t of tabsInWin) {
+      const label = tabLabel(t);
+      const flags = buildFlags(t);
+      const flagStr = formatFlags(flags);
+      lines.push(`    · ${formatIdPrefix(t)}${formatGroupPrefix(groupMap, t)}${label}${flagStr}`);
+    }
+    lines.push('');
+  }
+
+  return lines;
+}
+
+function renderFlat(tabs, groupMap) {
+  const lines = [];
+  for (const t of tabs) {
+    const c = compact(t);
+    const label =
+      c.title.length > TITLE_TRUNCATE_FULL
+        ? c.title.slice(0, TITLE_TRUNCATE_FULL - 3) + '…'
+        : c.title;
+    const flags = buildFlags(c);
+    const flagStr = formatFlags(flags);
+    lines.push(`  · ${formatIdPrefix(t)}${formatGroupPrefix(groupMap, t)}${label}${flagStr}`);
+  }
+
+  return lines;
+}
+
+export function formatTabData(data) {
+  const {
+    tabs,
+    histogram,
+    groupMap,
+    group_by,
+    query,
+    duplicates_only,
+    windows,
+    dupCount,
+  } = data;
+
+  const lines = [];
+
+  lines.push(
+    `📊 ${tabs.length} tab(s) across ${windows} window(s)` +
+      (query ? ` matching "${query}"` : '') +
+      (duplicates_only ? ' (duplicates only)' : '') +
+      (dupCount > 0 ? ` · ${dupCount} duplicate(s) found` : '') +
+      '\n',
+  );
+
+  lines.push(...renderHistogram(histogram));
+  lines.push('');
+
+  if (group_by === 'domain') {
+    lines.push(...renderByDomain(tabs, groupMap));
+  } else if (group_by === 'window') {
+    lines.push(...renderByWindow(tabs, groupMap));
+  } else {
+    lines.push(...renderFlat(tabs, groupMap));
+  }
+
+  return lines.join('\n');
+}

package/tools/rendering.js

@@ -0,0 +1,48 @@
+/** Rendering adapters for tab display - delegates to dedicated formatters. */
+
+/** Build emoji flags for tab metadata attributes. */
+export function buildFlags(tab) {
+  const flags = [];
+  if (tab.pinned) flags.push('📌');
+  if (tab.audible) flags.push('🔊');
+  return flags;
+}
+
+/** Format emoji flags as display string. */
+export function formatFlags(flags) {
+  return flags.length ? ' ' + flags.join('') : '';
+}
+
+/** Draw ASCII histogram bar for a domain count. */
+export function drawBar(count, maxCount, maxWidth) {
+  return '▇'.repeat(Math.max(1, Math.round((count / maxCount) * maxWidth)));
+}
+
+/** Draw a single histogram line. */
+export function formatHistogramLine(domain, count, bar) {
+  return `  ${bar}  ${domain.padEnd(28)} ${count} tab(s)`;
+}
+
+/** Draw domain header. */
+export function formatDomainHeader(domain, count) {
+  return `📁 ${domain} — ${count} tab(s)`;
+}
+
+/** Draw window header. */
+export function formatWindowHeader(winId, count) {
+  return `🪟 Window ${winId} — ${count} tab(s)`;
+}
+
+/** Draw group prefix. */
+export function formatGroupPrefix(groupMap, tab) {
+  if (tab.groupId === undefined || tab.groupId === -1) return '';
+  const g = groupMap.get(tab.groupId);
+  return g ? `[Group: ${g.title || 'Group ' + g.id}] ` : '';
+}
+
+/** Draw the tab's numeric id - every id-based tool (activate_tab, update_tab,
+ * get_tab_text, group_tabs, ungroup_tabs, close_tabs' tab_ids mode) needs one,
+ * and this is the only place callers can read it from. */
+export function formatIdPrefix(tab) {
+  return `[id:${tab.id}] `;
+}

package/tools/ungroup-tabs.tool.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { callExtension } from '../bridge.js';
+
+export const ungroupTabsTool = {
+  name: 'ungroup_tabs',
+  title: 'Ungroup Tabs',
+  description: 'Remove one or more open Chrome tabs from their current native Tab Groups.',
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  inputSchema: {
+    tab_ids: z.array(z.number().int()).min(1)
+      .describe('Array of tab IDs to remove from any groups.'),
+  },
+
+  execute: async ({ tab_ids }) => {
+    const res = await callExtension('ungroup_tabs', { tab_ids });
+    return JSON.stringify({
+      message: `Successfully ungrouped ${res.ungrouped} tab(s).`,
+      ungrouped: res.ungrouped,
+    }, null, 2);
+  },
+};

package/tools/update-tab-group.tool.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { callExtension } from '../bridge.js';
+
+export const updateTabGroupTool = {
+  name: 'update_tab_group',
+  title: 'Update Tab Group',
+  description:
+    'Update properties of an existing native Chrome Tab Group, including ' +
+    'its title, color, or collapsed/expanded state.',
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  inputSchema: {
+    group_id: z.number().int()
+      .describe('The numeric ID of the tab group to update (obtained from list_tab_groups or list_tabs).'),
+    title: z.string().optional()
+      .describe('New title for the group.'),
+    color: z.enum(['grey', 'blue', 'red', 'yellow', 'green', 'pink', 'purple', 'cyan', 'orange']).optional()
+      .describe('New color for the group.'),
+    collapsed: z.boolean().optional()
+      .describe('Whether the group should be collapsed (true) or expanded (false).'),
+  },
+
+  execute: async ({ group_id, title, color, collapsed }) => {
+    const res = await callExtension('update_group', { group_id, title, color, collapsed });
+    return JSON.stringify({
+      message: `Successfully updated tab group ${group_id}.`,
+      groupId: res.updated,
+    }, null, 2);
+  },
+};

package/tools/update-tab.tool.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { callExtension } from '../bridge.js';
+
+export const updateTabTool = {
+  name: 'update_tab',
+  title: 'Update Tab',
+  description:
+    'Modify properties of an open browser tab, such as navigating it to a new URL, ' +
+    'pinning/unpinning it, or muting/unmuting its audio.',
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  inputSchema: {
+    tab_id: z.number().int()
+      .describe('The numeric ID of the tab to update.'),
+    url: z.string().optional()
+      .describe('A new URL to navigate the tab to. If no protocol is provided, https:// will be prepended.'),
+    pinned: z.boolean().optional()
+      .describe('Set to true to pin the tab, or false to unpin it.'),
+    muted: z.boolean().optional()
+      .describe('Set to true to mute the tab, or false to unmute it.'),
+  },
+
+  execute: async ({ tab_id, url, pinned, muted }) => {
+    const res = await callExtension('update_tab', { tab_id, url, pinned, muted });
+    return JSON.stringify({
+      message: `Successfully updated tab ${tab_id}.`,
+      tabId: res.updated,
+    }, null, 2);
+  },
+};