@pokutuna/mcp-chrome-tabs 0.2.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 pokutuna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,7 +7,7 @@ Model Context Protocol (MCP) server that provides direct access to your browser'
 ## 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
+- **Content optimized for AI** - Automatic content extraction 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)
 
@@ -53,6 +53,7 @@ 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)
+- `--max-content-chars` - Truncates tab content to a maximum number of characters (default: 20000)
 
 #### Experimental Safari Support
 

package/dist/browser/chrome.js

@@ -1,7 +1,3 @@
-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 getChromeTabList(applicationName) {
     const sep = separator();
@@ -82,27 +78,19 @@ async function getPageContent(applicationName, tab) {
         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)
+    const scriptResult = await executeAppleScript(appleScript);
+    if (scriptResult.startsWith(`ERROR${sep}`)) {
+        throw new Error(scriptResult.split(sep)[1]);
+    }
+    const parts = scriptResult.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,
+        content, // Return raw HTML content
     };
 }
 async function openURL(applicationName, url) {

package/dist/browser/osascript.js

@@ -2,6 +2,7 @@ import { execFile } from "child_process";
 import { promisify } from "util";
 const execFileAsync = promisify(execFile);
 export function escapeAppleScript(str) {
+    // https://discussions.apple.com/thread/4247426?sortBy=rank
     return str
         .replace(/\\/g, "\\\\")
         .replace(/"/g, '\\"')
@@ -9,7 +10,7 @@ export function escapeAppleScript(str) {
         .replace(/\r/g, "\\r");
 }
 export async function retry(fn, options) {
-    const { maxRetries = 2, retryDelay = 1000 } = options || {};
+    const { maxRetries = 1, retryDelay = 1000 } = options || {};
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
             return await fn();

package/dist/browser/safari.js

@@ -1,7 +1,3 @@
-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();
@@ -82,27 +78,19 @@ async function getPageContent(applicationName, tab) {
         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)
+    const scriptResult = await executeAppleScript(appleScript);
+    if (scriptResult.startsWith(`ERROR${sep}`)) {
+        throw new Error(scriptResult.split(sep)[1]);
+    }
+    const parts = scriptResult.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,
+        content, // Return raw HTML content
     };
 }
 async function openURL(applicationName, url) {

package/dist/cli.js

@@ -26,6 +26,9 @@ OPTIONS:
                               (default: "chrome")
                               Options: "chrome", "safari"
 
+  --max-content-chars=<chars> Maximum content characters per single read
+                              (default: 20000)
+
   --help                      Show this help message
 
 
@@ -67,6 +70,10 @@ function parseCliArgs(args) {
                 type: "string",
                 default: "",
             },
+            "max-content-chars": {
+                type: "string",
+                default: "20000",
+            },
             help: {
                 type: "boolean",
                 default: false,
@@ -82,6 +89,12 @@ function parseCliArgs(args) {
             return "safari";
         throw new Error(`Invalid --experimental-browser option: "${browser}". Use "chrome" or "safari".`);
     }
+    function parseIntWithDefault(value, defaultValue, minValue = 0) {
+        const parsed = parseInt(value, 10);
+        if (isNaN(parsed) || parsed < minValue)
+            return defaultValue;
+        return parsed;
+    }
     const parsed = {
         applicationName: values["application-name"],
         browser: parseBrowserOption(values["experimental-browser"]),
@@ -89,16 +102,27 @@ function parseCliArgs(args) {
             .split(",")
             .map((d) => d.trim())
             .filter(Boolean),
-        checkInterval: parseInt(values["check-interval"], 10),
+        checkInterval: parseIntWithDefault(values["check-interval"], 3000, 0),
+        maxContentChars: parseIntWithDefault(values["max-content-chars"], 20000, 1),
         help: values.help,
     };
     return parsed;
 }
-const options = parseCliArgs(process.argv.slice(2));
-if (options.help) {
-    showHelp();
-    process.exit(0);
+async function main() {
+    const options = parseCliArgs(process.argv.slice(2));
+    if (options.help) {
+        showHelp();
+        process.exit(0);
+    }
+    const server = await createMcpServer(options);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const shutdown = async () => {
+        await transport.close();
+        await server.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
 }
-const server = await createMcpServer(options);
-const transport = new StdioServerTransport();
-await server.connect(transport);
+await main().catch(console.error);

package/dist/mcp.d.ts

@@ -5,5 +5,6 @@ export type McpServerOptions = {
     excludeHosts: string[];
     checkInterval: number;
     browser: Browser;
+    maxContentChars: number;
 };
 export declare function createMcpServer(options: McpServerOptions): Promise<McpServer>;

package/dist/mcp.js

@@ -6,6 +6,8 @@ import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { createHash } from "crypto";
 import * as view from "./view.js";
+import { Defuddle } from "defuddle/node";
+import { withMockConsole } from "./util.js";
 function isExcludedHost(url, excludeHosts) {
     const u = new URL(url);
     return excludeHosts.some((d) => u.hostname === d || u.hostname.endsWith("." + d));
@@ -17,11 +19,21 @@ async function listTabs(opts) {
 }
 async function getTab(tabRef, opts) {
     const browser = getInterface(opts.browser);
-    const content = await browser.getPageContent(opts.applicationName, tabRef);
-    if (isExcludedHost(content.url, opts.excludeHosts)) {
+    const raw = await browser.getPageContent(opts.applicationName, tabRef);
+    if (isExcludedHost(raw.url, opts.excludeHosts)) {
         throw new Error("Content not available for excluded host");
     }
-    return content;
+    const { result } = await withMockConsole(() => Defuddle(raw.content, raw.url, {
+        markdown: true,
+    }));
+    if (!result?.content) {
+        throw new Error("Failed to parse the page content");
+    }
+    return {
+        title: raw.title,
+        url: raw.url,
+        content: result.content,
+    };
 }
 async function packageVersion() {
     const packageJsonText = await readFile(join(dirname(fileURLToPath(import.meta.url)), "../package.json"), "utf8");
@@ -55,15 +67,22 @@ export async function createMcpServer(options) {
         debouncedNotificationMethods: ["notifications/resources/list_changed"],
     });
     server.registerTool("list_tabs", {
-        description: "List all open tabs in the user's browser with their titles, URLs, and tab references",
-        inputSchema: {},
-    }, async () => {
+        description: "List all open tabs in the user's browser with their titles and tab references.",
+        inputSchema: {
+            includeUrl: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Include URLs in the output. Enable only when you need to reference specific URLs. (default: false, hostnames always included)"),
+        },
+    }, async (args) => {
+        const { includeUrl } = args;
         const tabs = await listTabs(options);
         return {
             content: [
                 {
                     type: "text",
-                    text: view.formatList(tabs),
+                    text: view.formatList(tabs, includeUrl),
                 },
             ],
         };
@@ -75,15 +94,22 @@ export async function createMcpServer(options) {
                 .string()
                 .optional()
                 .describe("Tab reference from list_tabs output (e.g: ID:12345:67890). If omitted, uses the currently active tab."),
+            startIndex: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .default(0)
+                .describe("Starting character position for content extraction (default: 0)"),
         },
     }, async (args) => {
-        const { id } = args;
+        const { id, startIndex } = args;
         const tab = await getTab(id ? view.parseTabRef(id) : null, options);
         return {
             content: [
                 {
                     type: "text",
-                    text: view.formatTabContent(tab),
+                    text: view.formatTabContent(tab, startIndex, options.maxContentChars),
                 },
             ],
         };
@@ -112,12 +138,13 @@ export async function createMcpServer(options) {
         mimeType: "text/markdown",
     }, async (uri) => {
         const tab = await getTab(null, options);
-        const text = view.formatTabContent(tab);
+        // TODO: Add pagination support for resources (startIndex parameter)
+        const text = view.formatTabContent(tab, 0, undefined);
         return {
             contents: [
                 {
                     uri: uri.href,
-                    name: tab.title,
+                    name: view.formatTabName(tab),
                     text,
                     mimeType: "text/markdown",
                     size: new Blob([text]).size,
@@ -131,7 +158,7 @@ export async function createMcpServer(options) {
             return {
                 resources: tabs.map((tab) => ({
                     uri: view.formatUri(tab),
-                    name: tab.title,
+                    name: view.formatTabName(tab),
                     mimeType: "text/markdown",
                 })),
             };
@@ -146,12 +173,13 @@ export async function createMcpServer(options) {
             tabId: String(tabId),
         };
         const tab = await getTab(tabRef, options);
-        const text = view.formatTabContent(tab);
+        // TODO: Add pagination support for resources (startIndex parameter)
+        const text = view.formatTabContent(tab, 0, undefined);
         return {
             contents: [
                 {
                     uri: uri.href,
-                    name: tab.title,
+                    name: view.formatTabName(tab),
                     mimeType: "text/markdown",
                     text,
                     size: new Blob([text]).size,

package/dist/util.d.ts

@@ -0,0 +1,4 @@
+export declare function withMockConsole<T>(fn: () => Promise<T>): Promise<{
+    result: T;
+    logs: unknown[][];
+}>;

package/dist/util.js

@@ -0,0 +1,14 @@
+export async function withMockConsole(fn) {
+    const originalConsoleLog = console.log;
+    const logs = [];
+    console.log = (...args) => {
+        logs.push(args);
+    };
+    try {
+        const result = await fn();
+        return { result, logs };
+    }
+    finally {
+        console.log = originalConsoleLog;
+    }
+}

package/dist/view.d.ts

@@ -1,8 +1,12 @@
 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;
-export declare function formatListItem(tab: Tab): string;
-export declare function formatTabContent(tab: TabContent): string;
+export declare function formatTabName(tab: {
+    title: string;
+    url: string;
+}): string;
+export declare function formatList(tabs: Tab[], includeUrl?: boolean): string;
+export declare function formatListItem(tab: Tab, includeUrl?: boolean): string;
+export declare function formatTabContent(tab: TabContent, startIndex?: number, maxContentChars?: number): string;
 export declare const uriTemplate = "tab://{windowId}/{tabId}";
 export declare function formatUri(ref: TabRef): string;

package/dist/view.js

@@ -9,30 +9,54 @@ export function parseTabRef(tabRef) {
     const tabId = match[2];
     return { windowId, tabId };
 }
-function truncateUrl(tab, over = 120) {
-    const url = tab.url;
-    if (url.length <= over)
+function getDomain(url) {
+    try {
+        const u = new URL(url);
+        return u.port ? `${u.hostname}:${u.port}` : u.hostname;
+    }
+    catch {
         return url;
-    return url.slice(0, over) + "...";
+    }
 }
-export function formatList(tabs) {
-    const list = tabs.map(formatListItem).join("\n");
+export function formatTabName(tab) {
+    return `${tab.title} (${getDomain(tab.url)})`;
+}
+export function formatList(tabs, includeUrl = false) {
+    const list = tabs.map((tab) => formatListItem(tab, includeUrl)).join("\n");
     const header = `### Current Tabs (${tabs.length} tabs exists)\n`;
     return header + list;
 }
-export function formatListItem(tab) {
-    return `- ${formatTabRef(tab)} [${tab.title}](${truncateUrl(tab)})`;
+export function formatListItem(tab, includeUrl = false) {
+    if (includeUrl) {
+        return `- ${formatTabRef(tab)} [${tab.title}](${tab.url})`;
+    }
+    else {
+        return `- ${formatTabRef(tab)} ${formatTabName(tab)}`;
+    }
 }
-export function formatTabContent(tab) {
-    return `
----
-title: ${tab.title}
----
-${tab.content}
-`.trimStart();
+export function formatTabContent(tab, startIndex = 0, maxContentChars) {
+    const frontMatters = [
+        { key: "url", value: tab.url },
+        { key: "title", value: tab.title },
+    ];
+    let content = tab.content;
+    if (startIndex > 0) {
+        content = content.slice(startIndex);
+        frontMatters.push({ key: "startIndex", value: startIndex });
+    }
+    const truncation = maxContentChars !== undefined && content.length > maxContentChars;
+    if (truncation) {
+        content = content.slice(0, maxContentChars);
+        const nextStart = startIndex + maxContentChars;
+        content += `\n\n<ERROR>Content truncated. Read with startIndex of ${nextStart} to get more content.</ERROR>`;
+        frontMatters.push({ key: "truncated", value: truncation });
+    }
+    const frontMatterText = frontMatters
+        .map(({ key, value }) => `${key}: ${value}`)
+        .join("\n");
+    return ["---", frontMatterText, "---", content].join("\n");
 }
 export const uriTemplate = "tab://{windowId}/{tabId}";
 export function formatUri(ref) {
-    // TODO give domain & title for incremental search
     return `tab://${ref.windowId}/${ref.tabId}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pokutuna/mcp-chrome-tabs",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/pokutuna/mcp-chrome-tabs"
@@ -23,21 +23,20 @@
     "lint:fix": "prettier --write .",
     "prepublishOnly": "npm run build",
     "start": "node dist/index.js",
-    "test": "vitest",
-    "test:run": "vitest run"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.16.0",
-    "@mozilla/readability": "^0.6.0",
-    "jsdom": "^26.1.0",
-    "turndown": "^7.2.0",
-    "turndown-plugin-gfm": "^1.0.2",
+    "defuddle": "^0.6.4",
+    "jsdom": "^24.0.0",
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@types/jsdom": "^21.1.7",
+    "@playwright/test": "^1.54.1",
     "@types/node": "^20.11.17",
-    "@types/turndown": "^5.0.5",
+    "playwright": "^1.54.1",
     "prettier": "^3.6.2",
     "tsx": "^4.7.1",
     "typescript": "~5.8.3",