@pokutuna/mcp-chrome-tabs 0.1.4 → 0.2.0

package/README.md

@@ -1,78 +1,121 @@
 # @pokutuna/mcp-chrome-tabs
 
-> [!NOTE]
-> **macOS only** - This MCP server uses AppleScript and only works on macOS.
+[![npm version](https://badge.fury.io/js/@pokutuna%2Fmcp-chrome-tabs.svg)](https://badge.fury.io/js/@pokutuna%2Fmcp-chrome-tabs)
 
 Model Context Protocol (MCP) server that provides direct access to your browser's open tabs content. No additional fetching or authentication required - simply access what you're already viewing.
 
-## Features
+## Key Features
+
+- **Direct browser tab access** - No web scraping needed, reads content from already open tabs
+- **Content optimized for AI** - Automatic readability processing and markdown conversion to reduce token usage
+- **Active tab shortcut** - Instant access to currently focused tab without specifying IDs
+- **MCP listChanged notifications** - Follows MCP protocol to notify tab changes (support is limited in most clients)
 
-- **Access browser tabs** - Direct access to content from tabs currently open in your browser
-- **Active tab shortcut** - Quick reference to currently active tab without specifying tab ID
-- **URL opening** - Open AI-provided URLs directly in new browser tabs
-- **Tools & Resources** - Dual interface supporting both MCP tools and resources with automatic refresh notifications when tab collection changes
+## Requirements
+
+> [!IMPORTANT]  
+> **macOS only** - This MCP server uses AppleScript and only works on macOS.
 
-## Installation
+- **Node.js** 20 or newer
+- **MCP Client** such as Claude Desktop, Claude Code, or any MCP-compatible client
+- **macOS** only (uses AppleScript for browser automation)
 
-> [!IMPORTANT]
-> **Requirements**: Enable "Allow JavaScript from Apple Events" in Chrome
-> - (en) **View** > **Developer** > **Allow JavaScript from Apple Events**
-> - (ja) **表示** > **開発 / 管理** > **Apple Events からのJavaScript を許可**
+## Getting Started
 
-### Manual Configuration
-Add to your MCP configuration file (e.g., `claude_desktop_config.json`):
+First, enable "Allow JavaScript from Apple Events" in Chrome:
+
+- (en) **View** > **Developer** > **Allow JavaScript from Apple Events**
+- (ja) **表示** > **開発 / 管理** > **Apple Events からのJavaScript を許可**
+
+Standard config works in most MCP clients (e.g., `.claude.json`, `.mcp.json`):
 
 ```json
 {
   "mcpServers": {
     "chrome-tabs": {
       "command": "npx",
-      "args": ["-y", "@pokutuna/mcp-chrome-tabs"]
+      "args": ["-y", "@pokutuna/mcp-chrome-tabs@latest"]
     }
   }
 }
 ```
 
-### For Claude Code
+Or for Claude Code:
+
 ```bash
-claude mcp add -s user chrome-tabs -- npx -y @pokutuna/mcp-chrome-tabs
+claude mcp add -s user chrome-tabs -- npx -y @pokutuna/mcp-chrome-tabs@latest
 ```
 
 ### Command Line Options
+
 The server accepts optional command line arguments for configuration:
 
 - `--application-name` - Application name to control (default: "Google Chrome")
 - `--exclude-hosts` - Comma-separated list of domains to exclude from tab listing and content access
 - `--check-interval` - Interval in milliseconds to check for tab changes and notify clients (default: 3000, set to 0 to disable)
 
+#### Experimental Safari Support
+
+Limited Safari support is available. Note that Safari lacks unique tab IDs, making it sensitive to tab order changes during execution:
+
+```bash
+npx @pokutuna/mcp-chrome-tabs --application-name=Safari --experimental-browser=safari
+```
+
+## MCP Features
+
+### Tools
 
-## Tools
+<details>
+<summary><code>list_tabs</code></summary>
 
-### `list_tabs`
 List all open tabs in the user's browser with their titles, URLs, and tab references.
+
 - Returns: Markdown formatted list of tabs with tab IDs for reference
 
-### `read_tab_content`
+</details>
+
+<details>
+<summary><code>read_tab_content</code></summary>
+
 Get readable content from a tab in the user's browser.
+
 - `id` (optional): Tab reference from `list_tabs` output (e.g., `ID:12345:67890`)
 - If `id` is omitted, uses the currently active tab
 - Returns: Clean, readable content extracted using Mozilla Readability
 
-### `open_in_new_tab`
+</details>
+
+<details>
+<summary><code>open_in_new_tab</code></summary>
+
 Open a URL in a new tab to present content or enable user interaction with webpages.
+
 - `url` (required): URL to open in the browser
 
-## Resources
+</details>
+
+### Resources
+
+<details>
+<summary><code>tab://current</code></summary>
 
-### `tab://current`
 Resource representing the content of the currently active tab.
+
 - **URI**: `tab://current`
 - **MIME type**: `text/markdown`
 - **Content**: Real-time content of the active browser tab
 
-### `tab://{windowId}/{tabId}`
+</details>
+
+<details>
+<summary><code>tab://{windowId}/{tabId}</code></summary>
+
 Resource template for accessing specific tabs.
+
 - **URI pattern**: `tab://{windowId}/{tabId}`
 - **MIME type**: `text/markdown`
 - **Content**: Content of the specified tab
 - Resources are dynamically generated based on currently open tabs
+
+</details>

package/dist/browser/browser.d.ts

@@ -0,0 +1,20 @@
+export type Browser = "chrome" | "safari";
+export type TabRef = {
+    windowId: string;
+    tabId: string;
+};
+export type Tab = TabRef & {
+    title: string;
+    url: string;
+};
+export type TabContent = {
+    title: string;
+    url: string;
+    content: string;
+};
+export type BrowserInterface = {
+    getTabList(applicationName: string): Promise<Tab[]>;
+    getPageContent(applicationName: string, tab?: TabRef | null): Promise<TabContent>;
+    openURL(applicationName: string, url: string): Promise<void>;
+};
+export declare function getInterface(browser: Browser): BrowserInterface;

package/dist/browser/browser.js

@@ -0,0 +1,8 @@
+import { chromeBrowser } from "./chrome.js";
+import { safariBrowser } from "./safari.js";
+export function getInterface(browser) {
+    if (browser === "safari") {
+        return safariBrowser;
+    }
+    return chromeBrowser;
+}

package/dist/browser/chrome.d.ts

@@ -0,0 +1,2 @@
+import type { BrowserInterface } from "./browser.js";
+export declare const chromeBrowser: BrowserInterface;

package/dist/{chrome.js → browser/chrome.js}

@@ -1,18 +1,9 @@
-import { execFile } from "child_process";
 import { JSDOM } from "jsdom";
 import { Readability } from "@mozilla/readability";
-import { promisify } from "util";
 import TurndownService from "turndown";
 import turndownPluginGfm from "turndown-plugin-gfm";
-const execFileAsync = promisify(execFile);
-function escapeAppleScript(str) {
-    return str
-        .replace(/\\/g, "\\\\")
-        .replace(/"/g, '\\"')
-        .replace(/\n/g, "\\n")
-        .replace(/\r/g, "\\r");
-}
-export async function getChromeTabList(applicationName) {
+import { escapeAppleScript, executeAppleScript, separator, } from "./osascript.js";
+async function getChromeTabList(applicationName) {
     const sep = separator();
     const appleScript = `
     tell application "${applicationName}"
@@ -45,7 +36,7 @@ export async function getChromeTabList(applicationName) {
     }
     return tabs;
 }
-export async function getPageContent(applicationName, tab) {
+async function getPageContent(applicationName, tab) {
     const sep = separator();
     const inner = `
     set tabTitle to title
@@ -114,7 +105,7 @@ export async function getPageContent(applicationName, tab) {
         content: md,
     };
 }
-export async function openURL(applicationName, url) {
+async function openURL(applicationName, url) {
     const escapedUrl = escapeAppleScript(url);
     const appleScript = `
     tell application "${applicationName}"
@@ -123,34 +114,8 @@ export async function openURL(applicationName, url) {
   `;
     await executeAppleScript(appleScript);
 }
-async function retry(fn, options) {
-    const { maxRetries = 2, retryDelay = 1000 } = options || {};
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        try {
-            return await fn();
-        }
-        catch (error) {
-            if (attempt === maxRetries) {
-                console.error("retry failed after maximum attempts:", error);
-                throw error;
-            }
-            await new Promise((resolve) => setTimeout(resolve, retryDelay * Math.pow(2, attempt)));
-        }
-    }
-    throw new Error("unreachable");
-}
-async function executeAppleScript(script) {
-    return retry(async () => {
-        const { stdout, stderr } = await execFileAsync("osascript", ["-e", script], {
-            timeout: 5 * 1000,
-            maxBuffer: 5 * 1024 * 1024, // 5MB
-        });
-        if (stderr)
-            console.error("AppleScript stderr:", stderr);
-        return stdout.trim();
-    });
-}
-function separator() {
-    const uniqueId = Math.random().toString(36).substring(2);
-    return `<|SEP:${uniqueId}|>`;
-}
+export const chromeBrowser = {
+    getTabList: getChromeTabList,
+    getPageContent,
+    openURL,
+};

package/dist/browser/osascript.d.ts

@@ -0,0 +1,7 @@
+export declare function escapeAppleScript(str: string): string;
+export declare function retry<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    retryDelay?: number;
+}): Promise<T>;
+export declare function executeAppleScript(script: string): Promise<string>;
+export declare function separator(): string;

package/dist/browser/osascript.js

@@ -0,0 +1,41 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+const execFileAsync = promisify(execFile);
+export function escapeAppleScript(str) {
+    return str
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r");
+}
+export async function retry(fn, options) {
+    const { maxRetries = 2, retryDelay = 1000 } = options || {};
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            if (attempt === maxRetries) {
+                console.error("retry failed after maximum attempts:", error);
+                throw error;
+            }
+            await new Promise((resolve) => setTimeout(resolve, retryDelay * Math.pow(2, attempt)));
+        }
+    }
+    throw new Error("unreachable");
+}
+export async function executeAppleScript(script) {
+    return retry(async () => {
+        const { stdout, stderr } = await execFileAsync("osascript", ["-e", script], {
+            timeout: 5 * 1000,
+            maxBuffer: 5 * 1024 * 1024, // 5MB
+        });
+        if (stderr)
+            console.error("AppleScript stderr:", stderr);
+        return stdout.trim();
+    });
+}
+export function separator() {
+    const uniqueId = Math.random().toString(36).substring(2);
+    return `<|SEP:${uniqueId}|>`;
+}

package/dist/browser/safari.d.ts

@@ -0,0 +1,2 @@
+import type { BrowserInterface } from "./browser.js";
+export declare const safariBrowser: BrowserInterface;

package/dist/browser/safari.js

@@ -0,0 +1,121 @@
+import { JSDOM } from "jsdom";
+import { Readability } from "@mozilla/readability";
+import TurndownService from "turndown";
+import turndownPluginGfm from "turndown-plugin-gfm";
+import { escapeAppleScript, executeAppleScript, separator, } from "./osascript.js";
+async function getSafariTabList(applicationName) {
+    const sep = separator();
+    const appleScript = `
+    tell application "${applicationName}"
+      set output to ""
+      repeat with aWindow in (every window)
+        set windowId to id of aWindow
+        repeat with aTab in (every tab of aWindow)
+          set tabIndex to index of aTab
+          set tabTitle to name of aTab
+          set tabURL to URL of aTab
+          set output to output & windowId & "${sep}" & tabIndex & "${sep}" & tabTitle & "${sep}" & tabURL & "\\n"
+        end repeat
+      end repeat
+      return output
+    end tell
+  `;
+    const result = await executeAppleScript(appleScript);
+    const lines = result.trim().split("\n");
+    const tabs = [];
+    for (const line of lines) {
+        const [wId, tId, title, url] = line.split(sep);
+        if (!/^https?:\/\//.test(url))
+            continue;
+        // Note: Safari tab IDs are volatile indices that change when tabs are closed
+        // Unlike Chrome, Safari doesn't provide stable unique tab identifiers
+        tabs.push({
+            windowId: wId,
+            tabId: tId,
+            title: title.trim(),
+            url: url.trim(),
+        });
+    }
+    return tabs;
+}
+async function getPageContent(applicationName, tab) {
+    const sep = separator();
+    const inner = `
+    set tabTitle to name
+    set tabURL to URL
+    set tabContent to do JavaScript "document.documentElement.outerHTML"
+    return tabTitle & "${sep}" & tabURL & "${sep}" & tabContent
+  `;
+    const appleScript = tab
+        ? `
+      try
+        tell application "${applicationName}"
+          tell window id "${tab.windowId}"
+            tell tab ${tab.tabId}
+              with timeout of 3 seconds
+                ${inner}
+              end timeout
+            end tell
+          end tell
+        end tell
+      on error errMsg
+        return "ERROR" & "${sep}" & errMsg
+      end try
+    `
+        : `
+      try
+        tell application "${applicationName}"
+          tell front window
+            set t to current tab
+            if URL of t is not "about:blank" then
+              tell t
+                with timeout of 3 seconds
+                  ${inner}
+                end timeout
+              end tell
+            else
+              error "No active tab found"
+            end if
+          end tell
+        end tell
+      on error errMsg
+        return "ERROR" & "${sep}" & errMsg
+      end try
+    `;
+    const result = await executeAppleScript(appleScript);
+    if (result.startsWith(`ERROR${sep}`))
+        throw new Error(result.split(sep)[1]);
+    const parts = result.split(sep).map((part) => part.trim());
+    if (parts.length < 3)
+        throw new Error("Failed to read the tab content");
+    const [title, url, content] = parts;
+    const dom = new JSDOM(content, { url });
+    const reader = new Readability(dom.window.document, {
+        charThreshold: 10,
+    });
+    const article = reader.parse();
+    if (!article?.content)
+        throw new Error("Failed to parse the page content");
+    const turndownService = new TurndownService();
+    turndownService.use(turndownPluginGfm.gfm);
+    const md = turndownService.turndown(article.content);
+    return {
+        title,
+        url,
+        content: md,
+    };
+}
+async function openURL(applicationName, url) {
+    const escapedUrl = escapeAppleScript(url);
+    const appleScript = `
+    tell application "${applicationName}"
+      open location "${escapedUrl}"
+    end tell
+  `;
+    await executeAppleScript(appleScript);
+}
+export const safariBrowser = {
+    getTabList: getSafariTabList,
+    getPageContent,
+    openURL,
+};

package/dist/cli.js

@@ -10,26 +10,31 @@ USAGE:
   mcp-chrome-tabs [OPTIONS]
 
 OPTIONS:
-  --application-name=<name>    Application name to control via AppleScript
-                               (default: "Google Chrome")
-                               Example: "Google Chrome Canary"
+  --application-name=<name>   Application name to control via AppleScript
+                              (default: "Google Chrome")
+                              Example: "Google Chrome Canary"
 
-  --exclude-hosts=<hosts>      Comma-separated list of hosts to exclude
-                               (default: "")
-                               Example: "github.com,example.com,test.com"
+  --exclude-hosts=<hosts>     Comma-separated list of hosts to exclude
+                              (default: "")
+                              Example: "github.com,example.com,test.com"
 
-  --check-interval=<ms>        Interval for checking browser tabs in milliseconds
-                               (default: 3000, set to 0 to disable)
-                               Example: 1000
+  --check-interval=<ms>       Interval for checking browser tabs in milliseconds
+                              (default: 3000, set to 0 to disable)
+                              Example: 1000
 
-  --help                       Show this help message
+  --experimental-browser=<b>  Browser implementation to use
+                              (default: "chrome")
+                              Options: "chrome", "safari"
+
+  --help                      Show this help message
 
 
 REQUIREMENTS:
-  Chrome must allow JavaScript from Apple Events:
-  1. Open Chrome
-  2. Go to View > Developer > Allow JavaScript from Apple Events
-  3. Enable the option
+  Chrome:
+    Chrome must allow JavaScript from Apple Events:
+    1. Open Chrome
+    2. Go to View > Developer > Allow JavaScript from Apple Events
+    3. Enable the option
 
 MCP CONFIGURATION EXAMPLE:
   {
@@ -58,6 +63,10 @@ function parseCliArgs(args) {
                 type: "string",
                 default: "3000",
             },
+            "experimental-browser": {
+                type: "string",
+                default: "",
+            },
             help: {
                 type: "boolean",
                 default: false,
@@ -66,8 +75,16 @@ function parseCliArgs(args) {
         allowPositionals: false,
         tokens: true,
     });
+    function parseBrowserOption(browser) {
+        if (browser === "" || browser === "chrome")
+            return "chrome";
+        if (browser === "safari")
+            return "safari";
+        throw new Error(`Invalid --experimental-browser option: "${browser}". Use "chrome" or "safari".`);
+    }
     const parsed = {
         applicationName: values["application-name"],
+        browser: parseBrowserOption(values["experimental-browser"]),
         excludeHosts: values["exclude-hosts"]
             .split(",")
             .map((d) => d.trim())

package/dist/mcp.d.ts

@@ -1,7 +1,9 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Browser } from "./browser/browser.js";
 export type McpServerOptions = {
     applicationName: string;
     excludeHosts: string[];
     checkInterval: number;
+    browser: Browser;
 };
 export declare function createMcpServer(options: McpServerOptions): Promise<McpServer>;

package/dist/mcp.js

@@ -1,6 +1,6 @@
 import { McpServer, ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import * as chrome from "./chrome.js";
+import { getInterface, } from "./browser/browser.js";
 import { readFile } from "fs/promises";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
@@ -11,11 +11,13 @@ function isExcludedHost(url, excludeHosts) {
     return excludeHosts.some((d) => u.hostname === d || u.hostname.endsWith("." + d));
 }
 async function listTabs(opts) {
-    const tabs = await chrome.getChromeTabList(opts.applicationName);
+    const browser = getInterface(opts.browser);
+    const tabs = await browser.getTabList(opts.applicationName);
     return tabs.filter((t) => !isExcludedHost(t.url, opts.excludeHosts));
 }
 async function getTab(tabRef, opts) {
-    const content = await chrome.getPageContent(opts.applicationName, tabRef);
+    const browser = getInterface(opts.browser);
+    const content = await browser.getPageContent(opts.applicationName, tabRef);
     if (isExcludedHost(content.url, opts.excludeHosts)) {
         throw new Error("Content not available for excluded host");
     }
@@ -44,6 +46,7 @@ export async function createMcpServer(options) {
         name: "chrome-tabs",
         version: await packageVersion(),
     }, {
+        instructions: "Use this server to access the user's open browser tabs.",
         capabilities: {
             resources: {
                 listChanged: true,
@@ -92,7 +95,8 @@ export async function createMcpServer(options) {
         },
     }, async (args) => {
         const { url } = args;
-        await chrome.openURL(options.applicationName, url);
+        const browser = getInterface(options.browser);
+        await browser.openURL(options.applicationName, url);
         return {
             content: [
                 {

package/dist/view.d.ts

@@ -1,4 +1,4 @@
-import { Tab, TabRef, TabContent } from "./chrome.js";
+import type { Tab, TabRef, TabContent } from "./browser/browser.js";
 export declare function formatTabRef(tab: Tab): string;
 export declare function parseTabRef(tabRef: string): TabRef | null;
 export declare function formatList(tabs: Tab[]): string;

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@pokutuna/mcp-chrome-tabs",
-  "version": "0.1.4",
-  "license": "MIT",
+  "version": "0.2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/pokutuna/mcp-chrome-tabs"
   },
+  "license": "MIT",
   "type": "module",
   "bin": {
     "mcp-chrome-tabs": "./dist/cli.js"
@@ -18,9 +18,11 @@
   "scripts": {
     "build": "tsc",
     "dev": "node --import tsx src/cli.ts",
+    "inspector": "npx @modelcontextprotocol/inspector",
+    "lint": "prettier --check .",
+    "lint:fix": "prettier --write .",
     "prepublishOnly": "npm run build",
     "start": "node dist/index.js",
-    "inspector": "npx @modelcontextprotocol/inspector",
     "test": "vitest",
     "test:run": "vitest run"
   },
@@ -36,6 +38,7 @@
     "@types/jsdom": "^21.1.7",
     "@types/node": "^20.11.17",
     "@types/turndown": "^5.0.5",
+    "prettier": "^3.6.2",
     "tsx": "^4.7.1",
     "typescript": "~5.8.3",
     "vitest": "^3.2.4"

package/dist/chrome.d.ts

@@ -1,16 +0,0 @@
-export type TabRef = {
-    windowId: string;
-    tabId: string;
-};
-export type Tab = TabRef & {
-    title: string;
-    url: string;
-};
-export type TabContent = {
-    title: string;
-    url: string;
-    content: string;
-};
-export declare function getChromeTabList(applicationName: string): Promise<Tab[]>;
-export declare function getPageContent(applicationName: string, tab?: TabRef | null): Promise<TabContent>;
-export declare function openURL(applicationName: string, url: string): Promise<void>;