scuttle-browser 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Axel Krantz
+
+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

@@ -0,0 +1,235 @@
+# Scuttle
+
+Browser bridge for LLMs. Lets AI agents browse the web by converting pages into compact, annotated accessibility trees — no screenshots or raw HTML required.
+
+Scuttle runs as an [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server. Any MCP-compatible client (Claude Code, Claude Desktop, Cursor, etc.) can use it to navigate, read, and interact with web pages.
+
+## How it works
+
+Instead of feeding raw HTML (too many tokens, too much noise) or screenshots (unreliable for spatial reasoning), Scuttle extracts the browser's **accessibility tree** — the same semantic structure used by screen readers. It then:
+
+1. **Prunes** invisible and decorative nodes
+2. **Assigns numeric IDs** to every interactable element (`[1] button "Submit"`, `[2] textbox "Search"`)
+3. **Labels unnamed elements** using a fallback chain: visible text → aria-label → placeholder → nearby heading → positional description
+4. **Accepts actions** by element ID — `click(1)`, `type(2, "hello")`
+
+The result is a compact, token-efficient representation that LLMs can reason about and act on.
+
+```
+Page: Hacker News
+URL: https://news.ycombinator.com/
+Interactable elements: 227
+────────────────────────────────────────────────────────────
+heading "Hacker News"
+  [1] link "Hacker News"
+  [2] link "new"
+  [3] link "past"
+  ...
+  row
+    cell "1."
+    [12] link "Show HN: Something cool"
+      "Show HN: Something cool"
+    cell "142 points by user 3 hours ago"
+      [14] link "user"
+      [15] link "85 comments"
+```
+
+## Installation
+
+```bash
+# Clone and install
+git clone https://github.com/axelkrantz/scuttle.git
+cd scuttle
+npm install   # installs dependencies + downloads Chromium
+npm run build
+```
+
+Or install globally:
+
+```bash
+npm install -g scuttle-browser
+```
+
+## Configuration
+
+### Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "scuttle": {
+      "command": "node",
+      "args": ["/path/to/scuttle/dist/index.js"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "scuttle": {
+      "command": "node",
+      "args": ["/path/to/scuttle/dist/index.js"]
+    }
+  }
+}
+```
+
+### With npx (no clone needed)
+
+```json
+{
+  "mcpServers": {
+    "scuttle": {
+      "command": "npx",
+      "args": ["-y", "scuttle-browser"]
+    }
+  }
+}
+```
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SCUTTLE_HEADLESS` | `true` | Set to `false` to show the browser window |
+| `SCUTTLE_VIEWPORT_WIDTH` | `1280` | Browser viewport width in pixels |
+| `SCUTTLE_VIEWPORT_HEIGHT` | `720` | Browser viewport height in pixels |
+| `SCUTTLE_TIMEOUT` | `30000` | Navigation timeout in milliseconds |
+| `SCUTTLE_SETTLE_TIME` | `500` | Post-navigation settle time in ms (for SPAs that hydrate after DOM ready) |
+
+Example with visible browser:
+
+```json
+{
+  "mcpServers": {
+    "scuttle": {
+      "command": "node",
+      "args": ["/path/to/scuttle/dist/index.js"],
+      "env": {
+        "SCUTTLE_HEADLESS": "false"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### `navigate`
+
+Go to a URL.
+
+```
+navigate({ url: "https://example.com" })
+→ "Navigated to: Example Domain\nURL: https://example.com/"
+```
+
+### `observe`
+
+Get the current page state as an annotated accessibility tree. Every interactable element gets a numeric ID in brackets.
+
+```
+observe()
+→ Page: Example Domain
+  URL: https://example.com/
+  Interactable elements: 1
+  ────────────────────────────────────────────────────────────
+  heading "Example Domain"
+  "This domain is for use in illustrative examples..."
+  [1] link "More information..."
+```
+
+### `act`
+
+Perform actions on the page using element IDs from `observe`.
+
+| Action | Parameters | Description |
+|--------|-----------|-------------|
+| `click` | `id` | Click an element |
+| `type` | `id`, `text` | Clear and type text into an input |
+| `select` | `id`, `text` | Select a dropdown option |
+| `hover` | `id` | Hover over an element |
+| `scroll` | `direction` (`"up"` or `"down"`) | Scroll the page |
+| `key` | `key` (e.g., `"Enter"`, `"Tab"`) | Press a keyboard key |
+| `wait` | `ms` (max 10000) | Wait for dynamic content |
+| `back` | — | Browser back |
+| `forward` | — | Browser forward |
+
+```
+act({ action: "click", id: 1 })
+→ "Clicked link 'More information...'"
+
+act({ action: "type", id: 5, text: "search query" })
+→ "Typed 'search query' into textbox 'Search'"
+
+act({ action: "scroll", direction: "down" })
+→ "Scrolled down"
+```
+
+### `screenshot`
+
+Take a PNG screenshot of the current viewport. Returns a base64-encoded image. Useful when the accessibility tree alone isn't enough to understand the layout.
+
+### `get_text`
+
+Extract all visible text from the page. Best for reading articles, docs, or any text-heavy content without the structural overhead of `observe`.
+
+## Usage pattern
+
+The typical agent loop is:
+
+```
+1. navigate(url)     → go to a page
+2. observe()         → read the page state
+3. act(...)          → interact with an element
+4. observe()         → read the updated state
+5. repeat 3-4        → until the task is done
+```
+
+## Architecture
+
+```
+┌─────────────┐     ┌──────────────┐     ┌─────────────┐
+│  LLM/Agent  │◄───►│   Scuttle    │◄───►│  Playwright  │
+│ (MCP client)│     │ (MCP server) │     │  (Chromium)  │
+└─────────────┘     └──────────────┘     └─────────────┘
+                          │
+                    ┌─────┴─────┐
+                    │           │
+              Accessibility  Action
+                Extractor   Executor
+```
+
+- **Browser Manager** — manages Playwright browser lifecycle, navigation, and screenshots
+- **Accessibility Extractor** — snapshots the accessibility tree via CDP, prunes it, assigns IDs, and handles element labeling
+- **Action Executor** — maps element IDs to Playwright locators, executes actions with fallbacks
+
+### Element labeling strategy
+
+When elements lack good names (looking at you, `<div class="css-1a2b3c">`), Scuttle applies a fallback chain:
+
+1. **Visible text** — `[5] button "Add to cart"`
+2. **Aria attributes** — `[6] textbox aria-label="Email address"`
+3. **Value** — `[7] combobox [value: "United States"]`
+4. **Context** — `[8] button (under "Account Settings")`
+5. **Role fallback** — `[9] [unnamed button]`
+
+## Development
+
+```bash
+npm run dev    # watch mode — recompiles on changes
+npm run build  # one-time build
+npm start      # run the MCP server
+```
+
+## License
+
+MIT

package/dist/accessibility.d.ts

@@ -0,0 +1,34 @@
+import { Page, Locator } from "playwright";
+export interface AnnotatedNode {
+    id: number | null;
+    role: string;
+    name: string;
+    description: string;
+    value: string;
+    children: AnnotatedNode[];
+}
+export interface ElementRef {
+    id: number;
+    role: string;
+    label: string;
+    locator: Locator;
+}
+export declare class AccessibilityExtractor {
+    private elementMap;
+    private nextId;
+    private cdp;
+    private cdpPage;
+    reset(): void;
+    getElementMap(): Map<number, ElementRef>;
+    private getCDP;
+    extract(page: Page): Promise<{
+        tree: string;
+        elementCount: number;
+    }>;
+    private cdpNodesToTree;
+    private processNode;
+    private processChildren;
+    private buildLabel;
+    private buildLocator;
+    private serialize;
+}

package/dist/accessibility.js

@@ -0,0 +1,240 @@
+const INTERACTABLE_ROLES = new Set([
+    "link",
+    "button",
+    "textbox",
+    "searchbox",
+    "combobox",
+    "listbox",
+    "option",
+    "checkbox",
+    "radio",
+    "switch",
+    "slider",
+    "spinbutton",
+    "tab",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "treeitem",
+]);
+const SKIP_ROLES = new Set([
+    "none",
+    "presentation",
+    "generic",
+    "LineBreak",
+    "InlineTextBox",
+]);
+const STRUCTURAL_ROLES = new Set([
+    "group",
+    "list",
+    "listitem",
+    "navigation",
+    "main",
+    "complementary",
+    "banner",
+    "contentinfo",
+    "region",
+    "form",
+    "article",
+    "section",
+    "toolbar",
+    "menu",
+    "menubar",
+    "tablist",
+    "tabpanel",
+    "tree",
+    "grid",
+    "row",
+    "rowgroup",
+    "cell",
+    "columnheader",
+    "rowheader",
+]);
+export class AccessibilityExtractor {
+    elementMap = new Map();
+    nextId = 1;
+    cdp = null;
+    cdpPage = null;
+    reset() {
+        this.elementMap.clear();
+        this.nextId = 1;
+    }
+    getElementMap() {
+        return this.elementMap;
+    }
+    async getCDP(page) {
+        // Reuse CDP session for the same page to avoid handshake overhead
+        if (this.cdp && this.cdpPage === page) {
+            return this.cdp;
+        }
+        if (this.cdp) {
+            await this.cdp.detach().catch(() => { });
+        }
+        this.cdp = await page.context().newCDPSession(page);
+        this.cdpPage = page;
+        return this.cdp;
+    }
+    async extract(page) {
+        this.reset();
+        const cdp = await this.getCDP(page);
+        const { nodes } = await cdp.send("Accessibility.getFullAXTree");
+        if (!nodes || nodes.length === 0) {
+            return { tree: "[Empty page — no accessibility tree available]", elementCount: 0 };
+        }
+        const snapshot = this.cdpNodesToTree(nodes);
+        if (!snapshot) {
+            return { tree: "[Empty page — no accessibility tree available]", elementCount: 0 };
+        }
+        const annotated = this.processNode(snapshot, page, []);
+        const text = this.serialize(annotated, 0);
+        return { tree: text, elementCount: this.elementMap.size };
+    }
+    cdpNodesToTree(nodes) {
+        if (nodes.length === 0)
+            return null;
+        const nodeMap = new Map();
+        const childIds = new Map();
+        for (const node of nodes) {
+            const axNode = {
+                nodeId: node.nodeId,
+                role: node.role?.value || "unknown",
+                name: node.name?.value || "",
+                description: node.description?.value || "",
+                value: node.value?.value || "",
+                children: [],
+            };
+            nodeMap.set(node.nodeId, axNode);
+            if (node.childIds) {
+                childIds.set(node.nodeId, node.childIds);
+            }
+        }
+        // Link children
+        for (const [parentId, kids] of childIds) {
+            const parent = nodeMap.get(parentId);
+            if (parent) {
+                for (const childId of kids) {
+                    const child = nodeMap.get(childId);
+                    if (child)
+                        parent.children.push(child);
+                }
+            }
+        }
+        // Root is the first node
+        return nodeMap.get(nodes[0].nodeId) || null;
+    }
+    processNode(node, page, ancestorNames) {
+        const role = node.role;
+        const name = node.name.trim();
+        if (SKIP_ROLES.has(role)) {
+            const children = this.processChildren(node.children || [], page, ancestorNames);
+            if (children.length === 1)
+                return children[0];
+            if (children.length === 0)
+                return null;
+            return { id: null, role: "group", name: "", description: "", value: "", children };
+        }
+        const isInteractable = INTERACTABLE_ROLES.has(role);
+        // Push/pop to avoid array spread per node
+        if (name)
+            ancestorNames.push(name);
+        const children = this.processChildren(node.children || [], page, ancestorNames);
+        if (name)
+            ancestorNames.pop();
+        if (!isInteractable && STRUCTURAL_ROLES.has(role) && !name) {
+            if (children.length === 0)
+                return null;
+            if (children.length === 1)
+                return children[0];
+        }
+        let id = null;
+        if (isInteractable) {
+            id = this.nextId++;
+            const label = this.buildLabel(node, role, ancestorNames);
+            const locator = this.buildLocator(page, node, role, name);
+            this.elementMap.set(id, { id, role, label, locator });
+        }
+        if (role === "text" && !name && children.length === 0) {
+            return null;
+        }
+        return {
+            id,
+            role,
+            name,
+            description: (node.description || "").trim(),
+            value: (node.value || "").trim(),
+            children,
+        };
+    }
+    processChildren(children, page, ancestorNames) {
+        const results = [];
+        for (const child of children) {
+            const processed = this.processNode(child, page, ancestorNames);
+            if (processed)
+                results.push(processed);
+        }
+        return results;
+    }
+    buildLabel(node, role, ancestorNames) {
+        const name = (node.name || "").trim();
+        const desc = (node.description || "").trim();
+        // Priority 1: visible name/text
+        if (name)
+            return name;
+        // Priority 2: description (often aria-label or title)
+        if (desc)
+            return desc;
+        // Priority 3: value (for inputs with pre-filled values)
+        const value = (node.value || "").trim();
+        if (value)
+            return `[value: ${value}]`;
+        // Priority 4: contextual — use nearest ancestor name
+        const nearestContext = ancestorNames[ancestorNames.length - 1];
+        if (nearestContext)
+            return `(under "${nearestContext}")`;
+        // Priority 5: positional/role fallback
+        return `[unnamed ${role}]`;
+    }
+    buildLocator(page, node, role, name) {
+        // Use Playwright's role-based locator for best reliability
+        if (name) {
+            return page.getByRole(role, { name, exact: false });
+        }
+        return page.getByRole(role);
+    }
+    serialize(node, depth) {
+        if (!node)
+            return "";
+        const indent = "  ".repeat(depth);
+        const parts = [];
+        // Build the line for this node
+        let line = indent;
+        if (node.id !== null) {
+            line += `[${node.id}] `;
+        }
+        const showRole = node.id !== null || STRUCTURAL_ROLES.has(node.role) || node.role === "heading";
+        if (showRole) {
+            line += node.role;
+        }
+        if (node.name) {
+            line += showRole ? ` "${node.name}"` : `"${node.name}"`;
+        }
+        if (node.description && node.description !== node.name) {
+            line += ` — ${node.description}`;
+        }
+        if (node.value) {
+            line += ` [value: "${node.value}"]`;
+        }
+        const trimmed = line.trim();
+        if (trimmed) {
+            parts.push(line);
+        }
+        // Serialize children
+        for (const child of node.children) {
+            const childStr = this.serialize(child, depth + (trimmed ? 1 : 0));
+            if (childStr)
+                parts.push(childStr);
+        }
+        return parts.join("\n");
+    }
+}
+//# sourceMappingURL=accessibility.js.map

package/dist/accessibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessibility.js","sourceRoot":"","sources":["../src/accessibility.ts"],"names":[],"mappings":"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"}

package/dist/actions.d.ts

@@ -0,0 +1,19 @@
+import { Page } from "playwright";
+import { ElementRef } from "./accessibility.js";
+export type ActionResult = {
+    success: boolean;
+    message: string;
+};
+export declare class ActionExecutor {
+    private page;
+    private elementMap;
+    constructor(page: Page, elementMap: Map<number, ElementRef>);
+    private getElement;
+    click(id: number): Promise<ActionResult>;
+    type(id: number, text: string): Promise<ActionResult>;
+    selectOption(id: number, value: string): Promise<ActionResult>;
+    hover(id: number): Promise<ActionResult>;
+    scroll(direction: "up" | "down"): Promise<ActionResult>;
+    pressKey(key: string): Promise<ActionResult>;
+    wait(ms?: number): Promise<ActionResult>;
+}

package/dist/actions.js

@@ -0,0 +1,120 @@
+export class ActionExecutor {
+    page;
+    elementMap;
+    constructor(page, elementMap) {
+        this.page = page;
+        this.elementMap = elementMap;
+    }
+    getElement(id) {
+        const el = this.elementMap.get(id);
+        if (!el) {
+            throw new Error(`Element [${id}] not found. Run observe first to get the current page state.`);
+        }
+        return el;
+    }
+    async click(id) {
+        const el = this.getElement(id);
+        const loc = el.locator.first();
+        try {
+            await loc.click({ timeout: 5000 });
+            await this.page.waitForTimeout(500);
+            return { success: true, message: `Clicked ${el.role} "${el.label}"` };
+        }
+        catch (err) {
+            // JS fallback for elements covered by overlays or intercepted by frameworks
+            try {
+                await loc.evaluate((node) => node.click());
+                await this.page.waitForTimeout(500);
+                return {
+                    success: true,
+                    message: `Clicked ${el.role} "${el.label}" (via JS fallback)`,
+                };
+            }
+            catch {
+                return {
+                    success: false,
+                    message: `Failed to click [${id}] ${el.role} "${el.label}": ${err}`,
+                };
+            }
+        }
+    }
+    async type(id, text) {
+        const el = this.getElement(id);
+        const loc = el.locator.first();
+        try {
+            await loc.click({ timeout: 5000 });
+            await loc.fill(text);
+            return {
+                success: true,
+                message: `Typed "${text}" into ${el.role} "${el.label}"`,
+            };
+        }
+        catch (err) {
+            // Keyboard fallback for React-controlled inputs that reject fill()
+            try {
+                await this.page.keyboard.press("Control+A");
+                await this.page.keyboard.press("Backspace");
+                await this.page.keyboard.type(text, { delay: 50 });
+                return {
+                    success: true,
+                    message: `Typed "${text}" into ${el.role} "${el.label}" (via keyboard fallback)`,
+                };
+            }
+            catch {
+                return {
+                    success: false,
+                    message: `Failed to type into [${id}] ${el.role} "${el.label}": ${err}`,
+                };
+            }
+        }
+    }
+    async selectOption(id, value) {
+        const el = this.getElement(id);
+        try {
+            await el.locator.first().selectOption(value, { timeout: 5000 });
+            return {
+                success: true,
+                message: `Selected "${value}" in ${el.role} "${el.label}"`,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                message: `Failed to select in [${id}] ${el.role} "${el.label}": ${err}`,
+            };
+        }
+    }
+    async hover(id) {
+        const el = this.getElement(id);
+        try {
+            await el.locator.first().hover({ timeout: 5000 });
+            return {
+                success: true,
+                message: `Hovered over ${el.role} "${el.label}"`,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                message: `Failed to hover [${id}] ${el.role} "${el.label}": ${err}`,
+            };
+        }
+    }
+    async scroll(direction) {
+        const delta = direction === "down" ? 500 : -500;
+        await this.page.mouse.wheel(0, delta);
+        await this.page.waitForTimeout(300);
+        return { success: true, message: `Scrolled ${direction}` };
+    }
+    async pressKey(key) {
+        await this.page.keyboard.press(key);
+        await this.page.waitForTimeout(300);
+        return { success: true, message: `Pressed key "${key}"` };
+    }
+    async wait(ms = 2000) {
+        const capped = Math.min(ms, 10000);
+        await this.page.waitForTimeout(capped);
+        return { success: true, message: `Waited ${capped}ms` };
+    }
+}
+//# sourceMappingURL=actions.js.map

package/dist/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAQA,MAAM,OAAO,cAAc;IACjB,IAAI,CAAO;IACX,UAAU,CAA0B;IAE5C,YAAY,IAAU,EAAE,UAAmC;QACzD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAEO,UAAU,CAAC,EAAU;QAC3B,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnC,IAAI,CAAC,EAAE,EAAE,CAAC;YACR,MAAM,IAAI,KAAK,CACb,YAAY,EAAE,+DAA+D,CAC9E,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,EAAU;QACpB,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAC/B,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACnC,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;YACpC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,KAAK,GAAG,EAAE,CAAC;QACxE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,4EAA4E;YAC5E,IAAI,CAAC;gBACH,MAAM,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAa,EAAE,EAAE,CAAE,IAAoB,CAAC,KAAK,EAAE,CAAC,CAAC;gBACrE,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;gBACpC,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE,WAAW,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,KAAK,qBAAqB;iBAC9D,CAAC;YACJ,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,OAAO,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,KAAK,MAAM,GAAG,EAAE;iBACpE,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,EAAU,EAAE,IAAY;QACjC,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAC/B,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACnC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrB,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,UAAU,IAAI,UAAU,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,KAAK,GAAG;aACzD,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,mEAAmE;YACnE,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;gBAC5C,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;gBAC5C,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;gBACnD,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE,UAAU,IAAI,UAAU,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,KAAK,2BAA2B;iBACjF,CAAC;YACJ,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,OAAO,EAAE,wBAAwB,EAAE,KAAK,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,KAAK,MAAM,GAAG,EAAE;iBACxE,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,EAAU,EAAE,KAAa;QAC1C,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAC/B,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YAChE,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,aAAa,KAAK,QAAQ,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,KAAK,GAAG;aAC3D,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,OAAO,EAAE,wBAAwB,EAAE,KAAK,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,KAAK,MAAM,GAAG,EAAE;aACxE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,EAAU;QACpB,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAC/B,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YAClD,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,gBAAgB,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,KAAK,GAAG;aACjD,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,OAAO,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,KAAK,MAAM,GAAG,EAAE;aACpE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,SAAwB;QACnC,MAAM,KAAK,GAAG,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAChD,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QACtC,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;QACpC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,SAAS,EAAE,EAAE,CAAC;IAC7D,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,GAAW;QACxB,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACpC,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;QACpC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,gBAAgB,GAAG,GAAG,EAAE,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAa,IAAI;QAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QACnC,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,MAAM,IAAI,EAAE,CAAC;IAC1D,CAAC;CACF"}

package/dist/browser.d.ts

@@ -0,0 +1,31 @@
+import { Page } from "playwright";
+export interface BrowserConfig {
+    headless: boolean;
+    viewportWidth: number;
+    viewportHeight: number;
+    timeout: number;
+    settleTime: number;
+}
+export declare class BrowserManager {
+    private browser;
+    private context;
+    private page;
+    private config;
+    constructor(config?: Partial<BrowserConfig>);
+    getPage(): Promise<Page>;
+    private pageState;
+    navigate(url: string): Promise<{
+        url: string;
+        title: string;
+    }>;
+    goBack(): Promise<{
+        url: string;
+        title: string;
+    }>;
+    goForward(): Promise<{
+        url: string;
+        title: string;
+    }>;
+    screenshot(): Promise<Buffer>;
+    close(): Promise<void>;
+}

package/dist/browser.js

@@ -0,0 +1,79 @@
+import { chromium } from "playwright";
+function loadConfig() {
+    return {
+        headless: process.env.SCUTTLE_HEADLESS !== "false",
+        viewportWidth: parseInt(process.env.SCUTTLE_VIEWPORT_WIDTH || "1280", 10),
+        viewportHeight: parseInt(process.env.SCUTTLE_VIEWPORT_HEIGHT || "720", 10),
+        timeout: parseInt(process.env.SCUTTLE_TIMEOUT || "30000", 10),
+        settleTime: parseInt(process.env.SCUTTLE_SETTLE_TIME || "500", 10),
+    };
+}
+export class BrowserManager {
+    browser = null;
+    context = null;
+    page = null;
+    config;
+    constructor(config) {
+        this.config = { ...loadConfig(), ...config };
+    }
+    async getPage() {
+        if (!this.browser || !this.browser.isConnected()) {
+            this.browser = await chromium.launch({ headless: this.config.headless });
+            this.context = await this.browser.newContext({
+                viewport: {
+                    width: this.config.viewportWidth,
+                    height: this.config.viewportHeight,
+                },
+                userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+            });
+            this.page = await this.context.newPage();
+        }
+        if (!this.page || this.page.isClosed()) {
+            this.page = await this.context.newPage();
+        }
+        return this.page;
+    }
+    async pageState(page) {
+        return { url: page.url(), title: await page.title() };
+    }
+    async navigate(url) {
+        const page = await this.getPage();
+        await page.goto(url, {
+            waitUntil: "domcontentloaded",
+            timeout: this.config.timeout,
+        });
+        if (this.config.settleTime > 0) {
+            await page.waitForTimeout(this.config.settleTime);
+        }
+        return this.pageState(page);
+    }
+    async goBack() {
+        const page = await this.getPage();
+        await page.goBack({
+            waitUntil: "domcontentloaded",
+            timeout: this.config.timeout,
+        });
+        return this.pageState(page);
+    }
+    async goForward() {
+        const page = await this.getPage();
+        await page.goForward({
+            waitUntil: "domcontentloaded",
+            timeout: this.config.timeout,
+        });
+        return this.pageState(page);
+    }
+    async screenshot() {
+        const page = await this.getPage();
+        return await page.screenshot({ type: "png" });
+    }
+    async close() {
+        if (this.browser) {
+            await this.browser.close();
+            this.browser = null;
+            this.context = null;
+            this.page = null;
+        }
+    }
+}
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { BrowserManager } from "./browser.js";
+import { AccessibilityExtractor } from "./accessibility.js";
+import { ActionExecutor } from "./actions.js";
+const browser = new BrowserManager();
+const extractor = new AccessibilityExtractor();
+const server = new McpServer({
+    name: "scuttle",
+    version: "0.1.0",
+});
+function formatPageHeader(title, url, extra) {
+    const lines = [`Page: ${title}`, `URL: ${url}`];
+    if (extra)
+        lines.push(extra);
+    lines.push("─".repeat(60));
+    return lines.join("\n") + "\n";
+}
+function toolError(msg) {
+    return {
+        content: [{ type: "text", text: msg }],
+        isError: true,
+    };
+}
+server.tool("navigate", "Navigate to a URL. Returns the page title and URL after loading.", { url: z.string().describe("The URL to navigate to") }, async ({ url }) => {
+    try {
+        const result = await browser.navigate(url);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Navigated to: ${result.title}\nURL: ${result.url}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return toolError(`Navigation failed: ${err}`);
+    }
+});
+server.tool("observe", `Get the current page state as an annotated accessibility tree. Each interactable element has a numeric ID in brackets like [1], [2], etc. Use these IDs with the "act" tool to interact with elements. The tree shows the semantic structure: headings, links, buttons, text inputs, etc. Call this after navigate and after every action to see the updated page state.`, {}, async () => {
+    try {
+        const page = await browser.getPage();
+        const url = page.url();
+        const [title, { tree, elementCount }] = await Promise.all([
+            page.title(),
+            extractor.extract(page),
+        ]);
+        const header = formatPageHeader(title, url, `Interactable elements: ${elementCount}`);
+        return { content: [{ type: "text", text: header + tree }] };
+    }
+    catch (err) {
+        return toolError(`Observe failed: ${err}`);
+    }
+});
+server.tool("act", `Perform an action on the current page. Available actions:
+- click(id): Click an element by its numeric ID from observe
+- type(id, text): Type text into an input field (clears existing text first)
+- select(id, value): Select an option in a dropdown
+- hover(id): Hover over an element to reveal tooltips or menus
+- scroll(direction): Scroll the page "up" or "down"
+- key(key): Press a keyboard key (e.g., "Enter", "Tab", "Escape", "ArrowDown")
+- wait(ms): Wait for a specified time in milliseconds (max 10000ms)
+- back(): Go back in browser history
+- forward(): Go forward in browser history
+
+Always call "observe" after acting to see the updated page state.`, {
+    action: z
+        .enum([
+        "click",
+        "type",
+        "select",
+        "hover",
+        "scroll",
+        "key",
+        "wait",
+        "back",
+        "forward",
+    ])
+        .describe("The action to perform"),
+    id: z
+        .number()
+        .optional()
+        .describe("Element ID from observe (required for click, type, select, hover)"),
+    text: z
+        .string()
+        .optional()
+        .describe("Text to type or option to select (required for type and select)"),
+    direction: z
+        .enum(["up", "down"])
+        .optional()
+        .describe('Scroll direction (required for scroll, default "down")'),
+    key: z
+        .string()
+        .optional()
+        .describe("Key to press (required for key action)"),
+    ms: z
+        .number()
+        .optional()
+        .describe("Milliseconds to wait (for wait action, default 2000)"),
+}, async ({ action, id, text, direction, key, ms }) => {
+    try {
+        const page = await browser.getPage();
+        const executor = new ActionExecutor(page, extractor.getElementMap());
+        let result;
+        switch (action) {
+            case "click":
+                if (id === undefined)
+                    return toolError("click requires an element id");
+                result = await executor.click(id);
+                break;
+            case "type":
+                if (id === undefined)
+                    return toolError("type requires an element id");
+                if (text === undefined)
+                    return toolError("type requires text");
+                result = await executor.type(id, text);
+                break;
+            case "select":
+                if (id === undefined)
+                    return toolError("select requires an element id");
+                if (!text)
+                    return toolError("select requires a value (pass in text param)");
+                result = await executor.selectOption(id, text);
+                break;
+            case "hover":
+                if (id === undefined)
+                    return toolError("hover requires an element id");
+                result = await executor.hover(id);
+                break;
+            case "scroll":
+                result = await executor.scroll(direction || "down");
+                break;
+            case "key":
+                if (!key)
+                    return toolError("key action requires a key name");
+                result = await executor.pressKey(key);
+                break;
+            case "wait":
+                result = await executor.wait(ms);
+                break;
+            case "back": {
+                const backResult = await browser.goBack();
+                result = {
+                    success: true,
+                    message: `Went back to: ${backResult.title} (${backResult.url})`,
+                };
+                break;
+            }
+            case "forward": {
+                const fwdResult = await browser.goForward();
+                result = {
+                    success: true,
+                    message: `Went forward to: ${fwdResult.title} (${fwdResult.url})`,
+                };
+                break;
+            }
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.message + (result.success ? "" : " [FAILED]"),
+                },
+            ],
+            isError: !result.success,
+        };
+    }
+    catch (err) {
+        return toolError(`Action failed: ${err}`);
+    }
+});
+server.tool("screenshot", "Take a screenshot of the current page viewport. Returns a PNG image. Use this when the accessibility tree alone is insufficient to understand the page layout or to verify visual state.", {}, async () => {
+    try {
+        const buf = await browser.screenshot();
+        return {
+            content: [
+                {
+                    type: "image",
+                    data: buf.toString("base64"),
+                    mimeType: "image/png",
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return toolError(`Screenshot failed: ${err}`);
+    }
+});
+server.tool("get_text", "Extract all visible text content from the current page. Useful for reading articles, documentation, or any text-heavy page without the structural markup of observe.", {}, async () => {
+    try {
+        const page = await browser.getPage();
+        const url = page.url();
+        const [title, text] = await Promise.all([
+            page.title(),
+            page.innerText("body"),
+        ]);
+        const trimmed = text.length > 50000
+            ? text.slice(0, 50000) + "\n\n[...truncated]"
+            : text;
+        return {
+            content: [
+                { type: "text", text: formatPageHeader(title, url) + trimmed },
+            ],
+        };
+    }
+    catch (err) {
+        return toolError(`get_text failed: ${err}`);
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const shutdown = async () => {
+        await browser.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+main().catch((err) => {
+    console.error("Scuttle failed to start:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "scuttle-browser",
+  "version": "0.1.0",
+  "description": "Browser bridge for LLMs — exposes web pages as annotated accessibility trees via MCP",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "scuttle": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "test": "node test-smoke.mjs",
+    "prepublishOnly": "npm run build",
+    "postinstall": "npx playwright install chromium || echo 'Run: npx playwright install chromium'"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "browser",
+    "web-browsing",
+    "llm",
+    "ai-agent",
+    "accessibility",
+    "playwright",
+    "automation"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/axelkrantz/scuttle"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "playwright": "^1.52.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3"
+  }
+}