2manytabs-mcp-host 3.0.0 → 3.1.1

package/tools/list-tabs.tool.js

@@ -10,10 +10,13 @@ export const listTabsTool = {
   name: 'list_tabs',
   title: 'List Tabs',
   description:
-    'Read open browser 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.',
+    'Read open browser tabs: a domain histogram plus one line per tab. Best for finding ' +
+    'specific tabs with `query`. To survey, sort or clean up many tabs, use cluster_tabs ' +
+    'instead: it summarises any number of tabs in a few lines, where this prints every tab. ' +
+    'Filter with `query`, reshape with ' +
+    '`group_by`, or isolate redundant tabs with `duplicates_only`. Shows at most ' +
+    `${MAX_TAB_LIST} tabs and says so when there are more; cluster_tabs summarises any number. ` +
+    'Read-only — never closes anything.',
   annotations: { readOnlyHint: true, openWorldHint: true },
   inputSchema: {
     query: z.string().optional()
@@ -25,9 +28,11 @@ export const listTabsTool = {
       .describe('Only include tabs that are duplicates (share a URL with an earlier tab).'),
     browser: z.string().optional()
       .describe('Filter tabs to a specific browser (e.g. "chrome", "firefox"). Omit to list tabs across all open browsers.'),
+    show_urls: z.boolean().default(false)
+      .describe('Print each tab\'s URL under its title. Long output for many tabs: narrow with `query` first.'),
   },
 
-  execute: async ({ query, group_by, duplicates_only, browser }) => {
+  execute: async ({ query, group_by, duplicates_only, browser, show_urls }) => {
     let all = await callExtension('query_tabs');
     if (browser) {
       all = all.filter((t) => (t.browser || '').toLowerCase() === browser.toLowerCase());
@@ -49,6 +54,7 @@ export const listTabsTool = {
       tabs = tabs.filter((t) => dupIds.has(t.id));
     }
 
+    const matched = tabs.length;
     if (tabs.length > MAX_TAB_LIST) {
       tabs = tabs.slice(0, MAX_TAB_LIST);
     }
@@ -66,6 +72,8 @@ export const listTabsTool = {
       duplicates_only,
       windows,
       dupCount,
+      matched,
+      show_urls,
     });
   },
 };

package/tools/live.js

@@ -0,0 +1,17 @@
+import { callExtension } from '../bridge.js';
+
+export async function liveTabs(browser) {
+  const all = await callExtension('query_tabs');
+  if (!browser) return all;
+  return all.filter((t) => (t.browser || '').toLowerCase() === browser.toLowerCase());
+}
+
+// Tab groups are optional: older Firefox has none, and a failure must not hide the tabs.
+export async function liveGroups() {
+  try {
+    const groups = await callExtension('query_groups');
+    return Array.isArray(groups) ? groups : [];
+  } catch {
+    return [];
+  }
+}

package/tools/present.js

@@ -27,7 +27,7 @@ function renderHistogram(histogram) {
   return lines;
 }
 
-function renderByDomain(tabs, groupMap) {
+function renderByDomain(tabs, groupMap, urlLine) {
   const grouped = {};
   for (const t of tabs) {
     const domain = t.url ? new URL(t.url).hostname : '(local)';
@@ -41,7 +41,7 @@ function renderByDomain(tabs, groupMap) {
       const label = tabLabel(t);
       const flags = buildFlags(t);
       const flagStr = formatFlags(flags);
-      lines.push(`    · ${formatIdPrefix(t)}${formatGroupPrefix(groupMap, t)}${label}${flagStr}`);
+      lines.push(`    · ${formatIdPrefix(t)}${formatGroupPrefix(groupMap, t)}${label}${flagStr}${urlLine(t)}`);
     }
     lines.push('');
   }
@@ -49,7 +49,7 @@ function renderByDomain(tabs, groupMap) {
   return lines;
 }
 
-function renderByWindow(tabs, groupMap) {
+function renderByWindow(tabs, groupMap, urlLine) {
   const grouped = {};
   for (const t of tabs) {
     const key = t.browser ? `${t.browser}:${t.windowId}` : `${t.windowId}`;
@@ -65,7 +65,7 @@ function renderByWindow(tabs, groupMap) {
       const label = tabLabel(t);
       const flags = buildFlags(t);
       const flagStr = formatFlags(flags);
-      lines.push(`    · ${formatIdPrefix(t)}${formatGroupPrefix(groupMap, t)}${label}${flagStr}`);
+      lines.push(`    · ${formatIdPrefix(t)}${formatGroupPrefix(groupMap, t)}${label}${flagStr}${urlLine(t)}`);
     }
     lines.push('');
   }
@@ -73,7 +73,7 @@ function renderByWindow(tabs, groupMap) {
   return lines;
 }
 
-function renderFlat(tabs, groupMap) {
+function renderFlat(tabs, groupMap, urlLine) {
   const lines = [];
   for (const t of tabs) {
     const c = compact(t);
@@ -83,7 +83,7 @@ function renderFlat(tabs, groupMap) {
         : c.title;
     const flags = buildFlags(c);
     const flagStr = formatFlags(flags);
-    lines.push(`  · ${formatIdPrefix(t)}${formatGroupPrefix(groupMap, t)}${label}${flagStr}`);
+    lines.push(`  · ${formatIdPrefix(t)}${formatGroupPrefix(groupMap, t)}${label}${flagStr}${urlLine(t)}`);
   }
 
   return lines;
@@ -99,9 +99,12 @@ export function formatTabData(data) {
     duplicates_only,
     windows,
     dupCount,
+    matched = tabs.length,
+    show_urls = false,
   } = data;
 
   const lines = [];
+  const urlLine = (t) => (show_urls ? `\n        ${t.url ?? ''}` : '');
 
   const browsers = [...new Set(tabs.map((t) => t.browser).filter(Boolean))];
   const browserSummary = browsers.length > 1
@@ -115,16 +118,22 @@ export function formatTabData(data) {
       (dupCount > 0 ? ` · ${dupCount} duplicate(s) found` : '') +
       '\n',
   );
+  if (matched > tabs.length) {
+    lines.push(
+      `⚠️ Showing the first ${tabs.length} of ${matched} tabs. Counts, histogram and duplicates above ` +
+      'cover only those shown. Narrow with `query` or `browser`, or use cluster_tabs for the whole set.\n',
+    );
+  }
 
   lines.push(...renderHistogram(histogram));
   lines.push('');
 
   if (group_by === 'domain') {
-    lines.push(...renderByDomain(tabs, groupMap));
+    lines.push(...renderByDomain(tabs, groupMap, urlLine));
   } else if (group_by === 'window') {
-    lines.push(...renderByWindow(tabs, groupMap));
+    lines.push(...renderByWindow(tabs, groupMap, urlLine));
   } else {
-    lines.push(...renderFlat(tabs, groupMap));
+    lines.push(...renderFlat(tabs, groupMap, urlLine));
   }
 
   return lines.join('\n');

package/tools/reopen-tabs.tool.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { callExtension } from '../bridge.js';
+import { checkExpectedCount, CONFIRM_COUNT_OVER } from '../lib/tabs.js';
+import { readRecord, reopenCandidates, snapshotDir } from '../lib/snapshots.js';
+import { liveTabs } from './live.js';
+
+const MAX_REOPEN = 100; // more at once can stall a browser; ask for a narrower match
+
+export const reopenTabsTool = {
+  name: 'reopen_tabs',
+  title: 'Reopen Tabs from a Record',
+  description:
+    'Reopen tabs saved by snapshot_tabs that are no longer open, in the browser they came ' +
+    'from. Narrow with `match` (substring of title or URL). Preview with `dry_run` first. ' +
+    `Reopening more than ${CONFIRM_COUNT_OVER} tabs needs \`expected_count\` from the preview, ` +
+    `and at most ${MAX_REOPEN} open per call. Only web and file links are reopened.\n\n` +
+    'Returns JSON: record, dry_run, count (or opened), sample of up to 10 {title, url}.',
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  inputSchema: {
+    record: z.string().optional()
+      .describe('Record name returned by snapshot_tabs, e.g. "tabs-20261012-141500.json". Omit for the newest.'),
+    match: z.string().optional()
+      .describe('Only reopen tabs whose title or URL contains this substring (case-insensitive).'),
+    dry_run: z.boolean().default(false)
+      .describe('Preview what would reopen without opening anything.'),
+    expected_count: z.number().int().min(1).optional()
+      .describe(`The number of tabs the user agreed to reopen, from the preview. Required above ${CONFIRM_COUNT_OVER}.`),
+  },
+
+  execute: async ({ record, match, dry_run, expected_count }) => {
+    const { name, record: rec } = readRecord(snapshotDir(), record);
+    const targets = reopenCandidates(rec, await liveTabs(), match);
+    const sample = targets.slice(0, 10).map(({ title, url }) => ({ title, url }));
+    if (targets.length === 0) {
+      return `Nothing to reopen from ${name}${match ? ` matching "${match}"` : ''}: every such tab is already open.`;
+    }
+    if (dry_run) return JSON.stringify({ record: name, dry_run: true, count: targets.length, sample }, null, 2);
+
+    checkExpectedCount(targets.length, expected_count, 'reopen');
+    if (targets.length > MAX_REOPEN) {
+      throw new Error(`That is ${targets.length} tabs; reopen at most ${MAX_REOPEN} at a time. Use a narrower match.`);
+    }
+
+    const byBrowser = new Map();
+    for (const t of targets) {
+      if (!byBrowser.has(t.browser)) byBrowser.set(t.browser, []);
+      byBrowser.get(t.browser).push(t.url);
+    }
+    let opened = 0;
+    for (const [browser, urls] of byBrowser) {
+      const res = await callExtension('open_tabs', browser ? { urls, browser } : { urls });
+      opened += res?.opened ?? 0;
+    }
+    return JSON.stringify({ record: name, dry_run: false, opened, sample }, null, 2);
+  },
+};

package/tools/snapshot-tabs.tool.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { buildRecord, snapshotDir, writeRecord } from '../lib/snapshots.js';
+import { liveTabs, liveGroups } from './live.js';
+
+export const snapshotTabsTool = {
+  name: 'snapshot_tabs',
+  title: 'Save a Record of Open Tabs',
+  description:
+    'Save a record of every open tab (title, link, window, tab group, pinned, last used) to a ' +
+    'file in this computer\'s app-data folder, before closing anything. Nothing leaves the ' +
+    'computer, and no cookies or typed form text are saved. Call it once at the start of a ' +
+    'clean-up; reopen_tabs can later reopen tabs from the record.\n\n' +
+    'Returns JSON: record (name to pass to reopen_tabs), path, tabs, windows, by_browser, pinned.',
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  inputSchema: {
+    browser: z.string().optional()
+      .describe('Only record this browser ("chrome", "firefox"). Omit to record every connected browser.'),
+  },
+
+  execute: async ({ browser }) => {
+    const tabs = await liveTabs(browser);
+    const record = buildRecord(tabs, await liveGroups());
+    const { name, path } = writeRecord(record, snapshotDir());
+    const byBrowser = {};
+    for (const t of tabs) byBrowser[t.browser ?? 'unknown'] = (byBrowser[t.browser ?? 'unknown'] ?? 0) + 1;
+    return JSON.stringify({
+      record: name,
+      path,
+      tabs: record.tab_count,
+      windows: record.windows.length,
+      by_browser: byBrowser,
+      pinned: tabs.filter((t) => t.pinned).length,
+      for_your_reply: 'Say once that a list of their open tabs was saved first. Give the name or path only if they ask.',
+    }, null, 2);
+  },
+};

package/tools/start-tab-cleanup.tool.js

@@ -0,0 +1,16 @@
+import { cleanupGuide } from '../lib/guide.js';
+
+export const startTabCleanupTool = {
+  name: 'start_tab_cleanup',
+  title: 'Start a Tab Clean-up',
+  description:
+    'Call this first when the user has too many tabs, wants to clean up, close, sort or dedupe ' +
+    'lots of tabs, or feels stuck or stressed about closing them. Returns the step-by-step ' +
+    'method to follow: save a record, sort tabs into clusters, close what the user confirms, ' +
+    'and park the few real to-dos with a next step and a when, in the user\'s own words. ' +
+    'Read-only; it does not touch any tab.',
+  annotations: { readOnlyHint: true, openWorldHint: false },
+  inputSchema: {},
+
+  execute: async () => cleanupGuide(),
+};

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { callExtension } from '../bridge.js';
+import { GROUP_TITLE_DESCRIBE, groupTitleNote } from '../lib/tabs.js';
 
 export const updateTabGroupTool = {
   name: 'update_tab_group',
@@ -17,7 +18,7 @@ export const updateTabGroupTool = {
     group_id: z.union([z.number().int(), z.string()])
       .describe('The ID (number or composite like "chrome:5") of the tab group to update (obtained from list_tab_groups or list_tabs).'),
     title: z.string().optional()
-      .describe('New title for the group.'),
+      .describe(GROUP_TITLE_DESCRIBE),
     color: z.enum(['grey', 'blue', 'red', 'yellow', 'green', 'pink', 'purple', 'cyan', 'orange']).optional()
       .describe('New color for the group.'),
     collapsed: z.boolean().optional()
@@ -31,6 +32,7 @@ export const updateTabGroupTool = {
     return JSON.stringify({
       message: `Successfully updated tab group ${group_id}.`,
       groupId: res.updated,
+      title_note: groupTitleNote(title),
     }, null, 2);
   },
 };