npc-agent 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Freya Zou
+
+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,119 @@
+
+
+# NPC
+
+*Your browser's NPC. Handles the side quests.*  
+*Control your real browser from any IDE - no context switching.*
+
+
+
+```bash
+npm i -g npc-agent
+```
+
+---
+
+## What it does
+
+Your IDE agent says what to do ("message Anna on Slack"). NPC does it in your real, logged-in browser. No API keys per service, no OAuth, no bot accounts. Works with any MCP IDE - Cursor, VS Code, Windsurf.
+
+
+| You want to              | Your IDE says                                                |
+| ------------------------ | ------------------------------------------------------------ |
+| Message someone on Slack | "go to slack and message #general: deploy is done"           |
+| Reply on Messenger       | "open messenger and reply to Tim: sounds good"               |
+| Check Gmail              | "take a screenshot of my gmail inbox"                        |
+| Fill out a form          | "find the email field, click it, type my address, press Tab" |
+| Do it all in one shot    | use `npc_batch` with an array of actions                     |
+
+
+---
+
+## Setup
+
+1. Install: `npm i -g npc-agent`
+2. Load the extension: `chrome://extensions` > Developer mode > Load unpacked > select `extension/`
+3. Add to `.cursor/mcp.json` or `.vscode/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "npc": {
+      "command": "node",
+      "args": ["/path/to/npc/dist/index.js"]
+    }
+  }
+}
+```
+
+Click the NPC icon on any tab. Green badge means connected.
+
+---
+
+## How it works
+
+
+
+```
+IDE (Cursor / VS Code)       NPC Server              Browser
+ |                            |                       |
+ |--- MCP stdio ------------->|                       |
+ |    "click Send button"     |--- WebSocket :7221 -->|
+ |                            |                       |--- CDP (chrome.debugger)
+ |                            |                       |--- clicks in real tab
+ |                            |<-- result ------------|
+ |<-- tool response ----------|                       |
+```
+
+The IDE handles reasoning. NPC just executes browser actions via Chrome DevTools Protocol. No LLM inside NPC.
+
+---
+
+## MCP tools
+
+
+| Tool               | What it does                                                |
+| ------------------ | ----------------------------------------------------------- |
+| `npc_screenshot`   | Capture tab as PNG                                          |
+| `npc_navigate`     | Go to a URL                                                 |
+| `npc_click`        | Click at (x, y)                                             |
+| `npc_type`         | Type text into focused element                              |
+| `npc_press_key`    | Press Enter, Tab, Escape, arrows                            |
+| `npc_scroll`       | Scroll up/down/left/right                                   |
+| `npc_find`         | Find element by CSS selector or text, returns (x, y) center |
+| `npc_batch`        | Run multiple actions in one call                            |
+| `npc_evaluate`     | Run JavaScript in page context                              |
+| `npc_extract_text` | Get all text from the page                                  |
+| `npc_extract_html` | Get full page HTML                                          |
+| `npc_current_url`  | Get current tab URL                                         |
+| `npc_page_title`   | Get current tab title                                       |
+
+
+### Batch example
+
+One MCP call instead of four:
+
+```json
+[
+  {"action": "find", "selector": "Message Tim"},
+  {"action": "click", "x": 450, "y": 320},
+  {"action": "type", "text": "hey, deploy is done"},
+  {"action": "key", "key": "Enter"}
+]
+```
+
+---
+
+## Limitations
+
+Chrome and Brave only (uses `chrome.debugger` API). One active tab at a time per extension instance. Cannot attach to `chrome://`, `brave://`, or extension pages. Screenshot coordinates are at device pixel ratio - divide by DPR before clicking on HiDPI displays.
+
+Requires Node.js >= 18.
+
+---
+
+## Contact
+
+      
+  
+    

package/dist/cdp.d.ts

@@ -0,0 +1,53 @@
+import type { NPCRelay } from './relay.js';
+export interface BatchAction {
+    action: 'click' | 'type' | 'key' | 'scroll' | 'navigate' | 'screenshot' | 'wait' | 'evaluate' | 'find';
+    x?: number;
+    y?: number;
+    text?: string;
+    key?: string;
+    direction?: 'up' | 'down';
+    amount?: number;
+    url?: string;
+    expression?: string;
+    selector?: string;
+    ms?: number;
+}
+export interface BatchResult {
+    action: string;
+    ok: boolean;
+    result?: any;
+    error?: string;
+}
+export declare class CDP {
+    private relay;
+    private sessionId;
+    constructor(relay: NPCRelay, sessionId: string);
+    screenshot(): Promise<{
+        data: string;
+        dpr: number;
+    }>;
+    getDevicePixelRatio(): Promise<number>;
+    navigate(url: string): Promise<void>;
+    waitForLoad(timeoutMs?: number): Promise<void>;
+    click(x: number, y: number): Promise<void>;
+    type(text: string): Promise<void>;
+    pressKey(key: string): Promise<void>;
+    pressEnter(): Promise<void>;
+    scroll(direction: 'up' | 'down', amount?: number): Promise<void>;
+    findElement(selector: string): Promise<{
+        found: boolean;
+        x: number;
+        y: number;
+        text: string;
+    }>;
+    executeBatch(actions: BatchAction[]): Promise<BatchResult[]>;
+    evaluate<T = any>(expression: string): Promise<T>;
+    extractText(): Promise<string>;
+    extractHTML(): Promise<string>;
+    currentUrl(): Promise<string>;
+    pageTitle(): Promise<string>;
+    viewportSize(): Promise<{
+        width: number;
+        height: number;
+    }>;
+}

package/dist/cdp.js

@@ -0,0 +1,231 @@
+export class CDP {
+    relay;
+    sessionId;
+    constructor(relay, sessionId) {
+        this.relay = relay;
+        this.sessionId = sessionId;
+    }
+    // ─── Page ───────────────────────────────────────────────────────────────────
+    async screenshot() {
+        const [{ data }, dpr] = await Promise.all([
+            this.relay.cdp('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false }, this.sessionId),
+            this.getDevicePixelRatio()
+        ]);
+        return { data: data, dpr };
+    }
+    async getDevicePixelRatio() {
+        try {
+            return await this.evaluate('window.devicePixelRatio') || 1;
+        }
+        catch {
+            return 1;
+        }
+    }
+    async navigate(url) {
+        await this.relay.cdp('Page.navigate', { url }, this.sessionId);
+        await this.waitForLoad();
+    }
+    async waitForLoad(timeoutMs = 10_000) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.relay.removeListener('cdpEvent', onEvent);
+                resolve();
+            }, timeoutMs);
+            const onEvent = (evt) => {
+                if (evt.method === 'Page.loadEventFired') {
+                    clearTimeout(timer);
+                    this.relay.removeListener('cdpEvent', onEvent);
+                    resolve();
+                }
+            };
+            this.relay.on('cdpEvent', onEvent);
+        });
+    }
+    // ─── Input (no artificial sleeps) ──────────────────────────────────────────
+    async click(x, y) {
+        const base = { x, y, button: 'left', clickCount: 1, modifiers: 0 };
+        await this.relay.cdp('Input.dispatchMouseEvent', { ...base, type: 'mousePressed' }, this.sessionId);
+        await this.relay.cdp('Input.dispatchMouseEvent', { ...base, type: 'mouseReleased' }, this.sessionId);
+    }
+    async type(text) {
+        await this.relay.cdp('Input.insertText', { text }, this.sessionId);
+    }
+    async pressKey(key) {
+        const mapped = resolveKey(key);
+        await this.relay.cdp('Input.dispatchKeyEvent', { ...mapped, type: 'keyDown' }, this.sessionId);
+        await this.relay.cdp('Input.dispatchKeyEvent', { ...mapped, type: 'keyUp' }, this.sessionId);
+    }
+    async pressEnter() {
+        await this.pressKey('Enter');
+    }
+    async scroll(direction, amount = 500) {
+        await this.relay.cdp('Input.dispatchMouseEvent', {
+            type: 'mouseWheel',
+            x: 640,
+            y: 400,
+            deltaX: 0,
+            deltaY: direction === 'down' ? amount : -amount
+        }, this.sessionId);
+    }
+    // ─── Semantic element finding ──────────────────────────────────────────────
+    async findElement(selector) {
+        const result = await this.evaluate(`
+      (() => {
+        // Try CSS selector first
+        let el = document.querySelector(${JSON.stringify(selector)});
+
+        // If no CSS match, search by text content
+        if (!el) {
+          const walk = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT);
+          const target = ${JSON.stringify(selector.toLowerCase())};
+          while (walk.nextNode()) {
+            const node = walk.currentNode;
+            const txt = (node.textContent || '').trim().toLowerCase();
+            const aria = (node.getAttribute('aria-label') || '').toLowerCase();
+            const placeholder = (node.getAttribute('placeholder') || '').toLowerCase();
+            if (txt === target || txt.includes(target) || aria.includes(target) || placeholder.includes(target)) {
+              el = node;
+              break;
+            }
+          }
+        }
+
+        if (!el) return { found: false, x: 0, y: 0, text: '' };
+        const rect = el.getBoundingClientRect();
+        return {
+          found: true,
+          x: Math.round(rect.x + rect.width / 2),
+          y: Math.round(rect.y + rect.height / 2),
+          text: (el.textContent || '').trim().slice(0, 200)
+        };
+      })()
+    `);
+        return result;
+    }
+    // ─── Batch execution ───────────────────────────────────────────────────────
+    async executeBatch(actions) {
+        const results = [];
+        for (const act of actions) {
+            try {
+                let result = null;
+                switch (act.action) {
+                    case 'click':
+                        await this.click(act.x ?? 0, act.y ?? 0);
+                        result = `Clicked (${act.x}, ${act.y})`;
+                        break;
+                    case 'type':
+                        await this.type(act.text ?? '');
+                        result = `Typed "${act.text}"`;
+                        break;
+                    case 'key':
+                        if ((act.key ?? '').toLowerCase() === 'enter' || (act.key ?? '').toLowerCase() === 'return') {
+                            await this.pressEnter();
+                        }
+                        else {
+                            await this.pressKey(act.key ?? '');
+                        }
+                        result = `Pressed ${act.key}`;
+                        break;
+                    case 'scroll':
+                        await this.scroll(act.direction ?? 'down', act.amount ?? 500);
+                        result = `Scrolled ${act.direction} ${act.amount ?? 500}px`;
+                        break;
+                    case 'navigate':
+                        await this.navigate(act.url ?? '');
+                        result = `Navigated to ${act.url}`;
+                        break;
+                    case 'screenshot': {
+                        const shot = await this.screenshot();
+                        result = { data: shot.data, dpr: shot.dpr };
+                        break;
+                    }
+                    case 'wait':
+                        await new Promise(r => setTimeout(r, act.ms ?? 100));
+                        result = `Waited ${act.ms ?? 100}ms`;
+                        break;
+                    case 'evaluate':
+                        result = await this.evaluate(act.expression ?? '');
+                        break;
+                    case 'find': {
+                        const found = await this.findElement(act.selector ?? act.text ?? '');
+                        result = found;
+                        break;
+                    }
+                    default:
+                        throw new Error(`Unknown action: ${act.action}`);
+                }
+                results.push({ action: act.action, ok: true, result });
+            }
+            catch (e) {
+                results.push({ action: act.action, ok: false, error: e.message });
+                break; // stop batch on first error
+            }
+        }
+        return results;
+    }
+    // ─── Runtime ────────────────────────────────────────────────────────────────
+    async evaluate(expression) {
+        const { result, exceptionDetails } = await this.relay.cdp('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true }, this.sessionId);
+        if (exceptionDetails) {
+            throw new Error(`JS eval error: ${exceptionDetails.text}`);
+        }
+        return result?.value;
+    }
+    async extractText() {
+        return this.evaluate('document.body.innerText');
+    }
+    async extractHTML() {
+        return this.evaluate('document.documentElement.outerHTML');
+    }
+    async currentUrl() {
+        return this.evaluate('window.location.href');
+    }
+    async pageTitle() {
+        return this.evaluate('document.title');
+    }
+    async viewportSize() {
+        return this.evaluate('({ width: window.innerWidth, height: window.innerHeight })');
+    }
+}
+const KEY_MAP = {
+    enter: { key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13 },
+    return: { key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13 },
+    tab: { key: 'Tab', code: 'Tab', windowsVirtualKeyCode: 9 },
+    escape: { key: 'Escape', code: 'Escape', windowsVirtualKeyCode: 27 },
+    backspace: { key: 'Backspace', code: 'Backspace', windowsVirtualKeyCode: 8 },
+    delete: { key: 'Delete', code: 'Delete', windowsVirtualKeyCode: 46 },
+    space: { key: ' ', code: 'Space', windowsVirtualKeyCode: 32 },
+    arrowup: { key: 'ArrowUp', code: 'ArrowUp', windowsVirtualKeyCode: 38 },
+    arrowdown: { key: 'ArrowDown', code: 'ArrowDown', windowsVirtualKeyCode: 40 },
+    arrowleft: { key: 'ArrowLeft', code: 'ArrowLeft', windowsVirtualKeyCode: 37 },
+    arrowright: { key: 'ArrowRight', code: 'ArrowRight', windowsVirtualKeyCode: 39 },
+    home: { key: 'Home', code: 'Home', windowsVirtualKeyCode: 36 },
+    end: { key: 'End', code: 'End', windowsVirtualKeyCode: 35 },
+    pageup: { key: 'PageUp', code: 'PageUp', windowsVirtualKeyCode: 33 },
+    pagedown: { key: 'PageDown', code: 'PageDown', windowsVirtualKeyCode: 34 },
+};
+function resolveKey(key) {
+    const lower = key.toLowerCase();
+    // Check named keys
+    const mapped = KEY_MAP[lower];
+    if (mapped)
+        return mapped;
+    // Single letter a-z
+    if (lower.length === 1 && lower >= 'a' && lower <= 'z') {
+        return { key: lower, code: `Key${lower.toUpperCase()}`, windowsVirtualKeyCode: lower.toUpperCase().charCodeAt(0) };
+    }
+    // Single digit 0-9
+    if (lower.length === 1 && lower >= '0' && lower <= '9') {
+        return { key: lower, code: `Digit${lower}`, windowsVirtualKeyCode: lower.charCodeAt(0) };
+    }
+    // F1-F12
+    const fMatch = lower.match(/^f(\d{1,2})$/);
+    if (fMatch) {
+        const n = parseInt(fMatch[1]);
+        if (n >= 1 && n <= 12) {
+            return { key: `F${n}`, code: `F${n}`, windowsVirtualKeyCode: 111 + n };
+        }
+    }
+    // Fallback - pass through, let Chrome infer
+    return { key, code: key, windowsVirtualKeyCode: 0 };
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { NPCRelay } from './relay.js';
+import { createMCPServer } from './mcp.js';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    process.stderr.write(`NPC - Your browser's NPC. Handles the side quests.
+
+Usage:
+  npc                   Start MCP server (IDE connects via stdio)
+  npc --relay-only      Extension bridge without MCP
+  npc --help            Show this help
+  npc --version         Show version
+
+Configure your IDE:
+  Add to .cursor/mcp.json or .vscode/mcp.json:
+  {
+    "mcpServers": {
+      "npc": { "command": "npc", "args": [] }
+    }
+  }
+
+Environment:
+  NPC_PORT    Override relay port (default: 7221)
+
+Docs: https://github.com/freyzo/npc
+`);
+    process.exit(0);
+}
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+    try {
+        const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'));
+        process.stdout.write(pkg.version + '\n');
+    }
+    catch {
+        process.stdout.write('unknown\n');
+    }
+    process.exit(0);
+}
+const PORT = parseInt(process.env.NPC_PORT || '7221', 10);
+const relayOnly = process.argv.includes('--relay-only');
+const relay = new NPCRelay(PORT);
+relay.on('extensionConnected', () => {
+    process.stderr.write('[npc] browser extension connected\n');
+});
+relay.on('sessionReady', (sid) => {
+    process.stderr.write(`[npc] tab session ready (${sid})\n`);
+});
+relay.on('extensionDisconnected', () => {
+    process.stderr.write('[npc] browser extension disconnected\n');
+});
+process.on('SIGINT', () => { relay.close(); process.exit(0); });
+process.on('SIGTERM', () => { relay.close(); process.exit(0); });
+process.stderr.write(`[npc] relay listening on ws://localhost:${PORT}\n`);
+if (relayOnly) {
+    process.stderr.write('[npc] relay-only mode - load NPC extension in Brave, click icon on a tab\n');
+}
+else {
+    const mcpServer = createMCPServer(relay);
+    const transport = new StdioServerTransport();
+    await mcpServer.connect(transport);
+    process.stderr.write('[npc] MCP server ready - waiting for Brave extension\n');
+}

package/dist/mcp.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { NPCRelay } from './relay.js';
+export declare function createMCPServer(relay: NPCRelay): McpServer;

package/dist/mcp.js

@@ -0,0 +1,173 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { CDP } from './cdp.js';
+import { writeFile } from 'fs/promises';
+import { resolve, dirname } from 'path';
+import { mkdirSync } from 'fs';
+export function createMCPServer(relay) {
+    const server = new McpServer({
+        name: 'npc',
+        version: '0.2.0'
+    });
+    function getCDP() {
+        const sid = relay.activeSession;
+        if (!sid)
+            throw new Error('No active browser session. Is the Chrome extension connected?');
+        return new CDP(relay, sid);
+    }
+    // ── npc_screenshot ──────────────────────────────────────────────────────────
+    server.tool('npc_screenshot', 'Take a screenshot of the real Chrome browser tab (via NPC Chrome extension + CDP). Returns base64 PNG.', {
+        savePath: z.string().optional().describe('Optional absolute file path to save the PNG to disk')
+    }, async ({ savePath }) => {
+        const cdp = getCDP();
+        const { data, dpr } = await cdp.screenshot();
+        if (savePath) {
+            const abs = resolve(savePath);
+            try {
+                mkdirSync(dirname(abs), { recursive: true });
+            }
+            catch { }
+            await writeFile(abs, Buffer.from(data, 'base64'));
+        }
+        return {
+            content: [
+                { type: 'image', data, mimeType: 'image/png' },
+                { type: 'text', text: `Device pixel ratio: ${dpr}. Divide image coords by ${dpr} before passing to click/scroll.${savePath ? ` Saved to ${savePath}` : ''}` }
+            ]
+        };
+    });
+    // ── npc_navigate ────────────────────────────────────────────────────────────
+    server.tool('npc_navigate', 'Navigate the real Chrome browser to a URL (via NPC Chrome extension + CDP)', { url: z.string().describe('The URL to navigate to') }, async ({ url }) => {
+        try {
+            const parsed = new URL(url);
+            if (!['http:', 'https:'].includes(parsed.protocol)) {
+                throw new Error(`Blocked navigation to ${parsed.protocol} URL - only http: and https: are allowed`);
+            }
+        }
+        catch (e) {
+            if (e instanceof Error && e.message.startsWith('Blocked'))
+                throw e;
+            throw new Error(`Invalid URL: ${url}`);
+        }
+        const cdp = getCDP();
+        await cdp.navigate(url);
+        const title = await cdp.pageTitle().catch(() => '');
+        return { content: [{ type: 'text', text: `Navigated to ${url} - "${title}"` }] };
+    });
+    // ── npc_click ───────────────────────────────────────────────────────────────
+    server.tool('npc_click', 'Click at pixel coordinates in the real Chrome browser viewport', {
+        x: z.number().describe('X coordinate (pixels from left)'),
+        y: z.number().describe('Y coordinate (pixels from top)')
+    }, async ({ x, y }) => {
+        const cdp = getCDP();
+        await cdp.click(x, y);
+        return { content: [{ type: 'text', text: `Clicked at (${x}, ${y})` }] };
+    });
+    // ── npc_type ────────────────────────────────────────────────────────────────
+    server.tool('npc_type', 'Type text into the focused element in the real Chrome browser', { text: z.string().describe('Text to type') }, async ({ text }) => {
+        const cdp = getCDP();
+        await cdp.type(text);
+        return { content: [{ type: 'text', text: `Typed "${text}"` }] };
+    });
+    // ── npc_press_key ───────────────────────────────────────────────────────────
+    server.tool('npc_press_key', 'Press a keyboard key in the real Chrome browser (Enter, Tab, Escape, ArrowDown, etc.)', { key: z.string().describe('Key name, e.g. "Return", "Tab", "Escape"') }, async ({ key }) => {
+        const cdp = getCDP();
+        await cdp.pressKey(key);
+        return { content: [{ type: 'text', text: `Pressed ${key}` }] };
+    });
+    // ── npc_scroll ──────────────────────────────────────────────────────────────
+    server.tool('npc_scroll', 'Scroll the page in the real Chrome browser', {
+        direction: z.enum(['up', 'down']).describe('Scroll direction'),
+        amount: z.number().optional().default(500).describe('Pixels to scroll (default 500)')
+    }, async ({ direction, amount }) => {
+        const cdp = getCDP();
+        await cdp.scroll(direction, amount);
+        return { content: [{ type: 'text', text: `Scrolled ${direction} ${amount}px` }] };
+    });
+    // ── npc_find ────────────────────────────────────────────────────────────────
+    server.tool('npc_find', 'Find an element on the page by CSS selector or text content. Returns center coordinates for clicking. Searches text content, aria-label, and placeholder attributes.', {
+        selector: z.string().describe('CSS selector (e.g. "button.submit") or text to find (e.g. "Send message")')
+    }, async ({ selector }) => {
+        const cdp = getCDP();
+        const result = await cdp.findElement(selector);
+        if (!result.found) {
+            return { content: [{ type: 'text', text: `Element not found: "${selector}"` }] };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Found at (${result.x}, ${result.y}) - text: "${result.text}"`
+                }]
+        };
+    });
+    // ── npc_batch ───────────────────────────────────────────────────────────────
+    server.tool('npc_batch', `Execute multiple browser actions in a single call. Cuts MCP round-trip overhead.
+Each action is an object with an "action" field and relevant params.
+Actions: click(x,y), type(text), key(key), scroll(direction,amount), navigate(url), screenshot(), wait(ms), evaluate(expression), find(selector).
+Stops on first error. Example: [{"action":"find","selector":"Message Tim"},{"action":"click","x":100,"y":200},{"action":"type","text":"hello"},{"action":"key","key":"Enter"}]`, {
+        actions: z.array(z.object({
+            action: z.enum(['click', 'type', 'key', 'scroll', 'navigate', 'screenshot', 'wait', 'evaluate', 'find']),
+            x: z.number().optional(),
+            y: z.number().optional(),
+            text: z.string().optional(),
+            key: z.string().optional(),
+            direction: z.enum(['up', 'down']).optional(),
+            amount: z.number().optional(),
+            url: z.string().optional(),
+            expression: z.string().optional(),
+            selector: z.string().optional(),
+            ms: z.number().optional()
+        })).describe('Array of actions to execute sequentially')
+    }, async ({ actions }) => {
+        const cdp = getCDP();
+        const results = await cdp.executeBatch(actions);
+        // If any action was a screenshot, include it as image content
+        const content = [];
+        const summary = [];
+        for (const r of results) {
+            if (r.ok && r.action === 'screenshot' && r.result?.data) {
+                content.push({ type: 'image', data: r.result.data, mimeType: 'image/png' });
+                summary.push(`screenshot (dpr: ${r.result.dpr})`);
+            }
+            else if (r.ok) {
+                summary.push(`${r.action}: ${typeof r.result === 'object' ? JSON.stringify(r.result) : r.result}`);
+            }
+            else {
+                summary.push(`${r.action}: FAILED - ${r.error}`);
+            }
+        }
+        content.push({ type: 'text', text: `Batch: ${results.length}/${actions.length} actions\n${summary.join('\n')}` });
+        return { content };
+    });
+    // ── npc_extract_text ────────────────────────────────────────────────────────
+    server.tool('npc_extract_text', 'Get full text content from the real Chrome browser page', {}, async () => {
+        const cdp = getCDP();
+        const text = await cdp.extractText();
+        return { content: [{ type: 'text', text }] };
+    });
+    // ── npc_extract_html ────────────────────────────────────────────────────────
+    server.tool('npc_extract_html', 'Get full HTML from the real Chrome browser page', {}, async () => {
+        const cdp = getCDP();
+        const html = await cdp.extractHTML();
+        return { content: [{ type: 'text', text: html }] };
+    });
+    // ── npc_evaluate ────────────────────────────────────────────────────────────
+    server.tool('npc_evaluate', 'Run JavaScript in the real Chrome browser page context and return the result', { expression: z.string().describe('JavaScript expression to evaluate') }, async ({ expression }) => {
+        const cdp = getCDP();
+        const result = await cdp.evaluate(expression);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    // ── npc_current_url ─────────────────────────────────────────────────────────
+    server.tool('npc_current_url', 'Get the URL of the current tab in the real Chrome browser', {}, async () => {
+        const cdp = getCDP();
+        const url = await cdp.currentUrl();
+        return { content: [{ type: 'text', text: url }] };
+    });
+    // ── npc_page_title ──────────────────────────────────────────────────────────
+    server.tool('npc_page_title', 'Get the title of the current tab in the real Chrome browser', {}, async () => {
+        const cdp = getCDP();
+        const title = await cdp.pageTitle();
+        return { content: [{ type: 'text', text: title }] };
+    });
+    return server;
+}