browserhand-mcp 0.1.0

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,385 @@
+#!/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 { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+// ── Config ──────────────────────────────────────────────────────
+const RELAY_URL = process.env.BROWSERHAND_RELAY_URL || "http://127.0.0.1:29981";
+const RELAY_COMMAND_URL = `${RELAY_URL}/command`;
+const RELAY_STATUS_URL = `${RELAY_URL}/status`;
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const RELAY_INDEX = resolve(__dirname, "..", "..", "relay", "index.ts");
+// ── Relay helper ────────────────────────────────────────────────
+async function relay(action, params = {}) {
+    const res = await fetch(RELAY_COMMAND_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ action, params }),
+    });
+    return (await res.json());
+}
+function textResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+function screenshotResult(data) {
+    const content = [];
+    // Extract base64 from data URL (data:image/jpeg;base64,...)
+    const screenshot = data.screenshot;
+    if (screenshot) {
+        const base64 = screenshot.includes(",")
+            ? screenshot.split(",")[1]
+            : screenshot;
+        const mimeType = screenshot.startsWith("data:image/png")
+            ? "image/png"
+            : "image/jpeg";
+        content.push({ type: "image", data: base64, mimeType });
+    }
+    // Also include text metadata
+    const { screenshot: _, ...meta } = data;
+    if (Object.keys(meta).length > 0) {
+        content.push({ type: "text", text: JSON.stringify(meta, null, 2) });
+    }
+    return { content };
+}
+// ── Auto-start relay ────────────────────────────────────────────
+async function ensureRelay() {
+    try {
+        const res = await fetch(RELAY_STATUS_URL);
+        if (res.ok)
+            return;
+    }
+    catch {
+        // Not running, start it
+    }
+    try {
+        const child = spawn("npx", ["tsx", RELAY_INDEX], {
+            detached: true,
+            stdio: "ignore",
+            env: { ...process.env },
+        });
+        child.unref();
+        // Wait for relay to be ready (up to 5s)
+        for (let i = 0; i < 25; i++) {
+            await new Promise((r) => setTimeout(r, 200));
+            try {
+                const res = await fetch(RELAY_STATUS_URL);
+                if (res.ok)
+                    return;
+            }
+            catch {
+                // keep waiting
+            }
+        }
+    }
+    catch {
+        // If auto-start fails, tools will return relay connection errors
+    }
+}
+// ── MCP Server ──────────────────────────────────────────────────
+const server = new McpServer({
+    name: "browserhand",
+    version: "0.1.0",
+});
+// ── Core actions ────────────────────────────────────────────────
+server.registerTool("navigate", {
+    title: "Navigate",
+    description: "Open a URL in the user's real browser. Preserves login state and cookies.",
+    inputSchema: z.object({
+        url: z.string().describe("The URL to navigate to"),
+        groupLabel: z
+            .string()
+            .optional()
+            .describe("Tab group label for agent-operated tabs"),
+    }),
+}, async (params) => {
+    const result = await relay("navigate", params);
+    return textResult(result);
+});
+server.registerTool("extract", {
+    title: "Extract Elements",
+    description: "Get all interactive elements on the current page. Returns an array of elements with index, tag, text, type, and position. Use the index to click, type, or interact with elements.",
+    inputSchema: z.object({}),
+}, async () => {
+    const result = await relay("extract");
+    return textResult(result);
+});
+server.registerTool("click", {
+    title: "Click",
+    description: "Click an interactive element by its index (from extract). Returns updated page elements after click.",
+    inputSchema: z.object({
+        index: z.number().describe("Element index from extract results"),
+    }),
+}, async (params) => {
+    const result = await relay("click", params);
+    return textResult(result);
+});
+server.registerTool("type", {
+    title: "Type Text",
+    description: "Type text into an input element. Clicks the element first to focus it, then types each character.",
+    inputSchema: z.object({
+        index: z.number().describe("Element index from extract results"),
+        text: z.string().describe("Text to type"),
+    }),
+}, async (params) => {
+    const result = await relay("type", params);
+    return textResult(result);
+});
+server.registerTool("scroll", {
+    title: "Scroll",
+    description: "Scroll the page up or down.",
+    inputSchema: z.object({
+        direction: z.enum(["up", "down"]).describe("Scroll direction"),
+    }),
+}, async (params) => {
+    const result = await relay("scroll", params);
+    return textResult(result);
+});
+server.registerTool("screenshot", {
+    title: "Screenshot",
+    description: "Capture a screenshot of the visible viewport. Returns the image directly.",
+    inputSchema: z.object({}),
+}, async () => {
+    const result = await relay("screenshot");
+    if (result.success && result.data) {
+        return screenshotResult(result.data);
+    }
+    return textResult(result);
+});
+server.registerTool("wait", {
+    title: "Wait",
+    description: "Wait for a specified number of seconds.",
+    inputSchema: z.object({
+        seconds: z.number().optional().describe("Seconds to wait (default: 1)"),
+    }),
+}, async (params) => {
+    const result = await relay("wait", params);
+    return textResult(result);
+});
+// ── Navigation actions ──────────────────────────────────────────
+server.registerTool("goback", {
+    title: "Go Back",
+    description: "Navigate back in browser history.",
+    inputSchema: z.object({}),
+}, async () => {
+    const result = await relay("goback");
+    return textResult(result);
+});
+server.registerTool("goforward", {
+    title: "Go Forward",
+    description: "Navigate forward in browser history.",
+    inputSchema: z.object({}),
+}, async () => {
+    const result = await relay("goforward");
+    return textResult(result);
+});
+server.registerTool("refresh", {
+    title: "Refresh",
+    description: "Reload the current page.",
+    inputSchema: z.object({}),
+}, async () => {
+    const result = await relay("refresh");
+    return textResult(result);
+});
+server.registerTool("tab", {
+    title: "Manage Tabs",
+    description: "List, switch, close, or create browser tabs. Use tabAction to specify the operation.",
+    inputSchema: z.object({
+        tabAction: z
+            .enum(["list", "switch", "close", "create"])
+            .describe("Tab operation"),
+        tabId: z.number().optional().describe("Tab ID (for switch/close)"),
+        url: z
+            .string()
+            .optional()
+            .describe("URL to open (for create, default: about:blank)"),
+        groupLabel: z.string().optional().describe("Tab group label (for create)"),
+    }),
+}, async (params) => {
+    const result = await relay("tab", params);
+    return textResult(result);
+});
+// ── Interaction actions ─────────────────────────────────────────
+server.registerTool("select", {
+    title: "Select Option",
+    description: "Choose an option in a dropdown/select element.",
+    inputSchema: z.object({
+        index: z.number().describe("Element index from extract results"),
+        value: z.string().describe("Value to select"),
+    }),
+}, async (params) => {
+    const result = await relay("select", params);
+    return textResult(result);
+});
+server.registerTool("hover", {
+    title: "Hover",
+    description: "Move the mouse over an element (triggers hover effects, tooltips, etc).",
+    inputSchema: z.object({
+        index: z.number().describe("Element index from extract results"),
+    }),
+}, async (params) => {
+    const result = await relay("hover", params);
+    return textResult(result);
+});
+server.registerTool("keypress", {
+    title: "Key Press",
+    description: "Press a key or key combination. Supports special keys (Enter, Tab, Escape, ArrowDown, etc) and modifiers.",
+    inputSchema: z.object({
+        key: z.string().describe("Key to press (e.g. 'Enter', 'Tab', 'a')"),
+        modifiers: z
+            .array(z.enum(["alt", "ctrl", "meta", "cmd", "shift"]))
+            .optional()
+            .describe("Modifier keys to hold"),
+    }),
+}, async (params) => {
+    const result = await relay("keypress", params);
+    return textResult(result);
+});
+server.registerTool("clear", {
+    title: "Clear Input",
+    description: "Clear the text content of an input or textarea element.",
+    inputSchema: z.object({
+        index: z.number().describe("Element index from extract results"),
+    }),
+}, async (params) => {
+    const result = await relay("clear", params);
+    return textResult(result);
+});
+server.registerTool("upload", {
+    title: "Upload File",
+    description: "Upload a file to a file input element.",
+    inputSchema: z.object({
+        index: z.number().describe("Element index of the file input"),
+        filePath: z.string().describe("Absolute path to the file to upload"),
+    }),
+}, async (params) => {
+    const result = await relay("upload", params);
+    return textResult(result);
+});
+server.registerTool("dialog", {
+    title: "Handle Dialog",
+    description: "Accept or dismiss a browser dialog (alert, confirm, prompt).",
+    inputSchema: z.object({
+        dialogAction: z
+            .enum(["accept", "dismiss"])
+            .describe("Accept or dismiss the dialog"),
+        dialogText: z
+            .string()
+            .optional()
+            .describe("Text to enter in a prompt dialog"),
+    }),
+}, async (params) => {
+    const result = await relay("dialog", params);
+    return textResult(result);
+});
+// ── Data actions ────────────────────────────────────────────────
+server.registerTool("gettext", {
+    title: "Get Page Text",
+    description: "Extract the text content of the page (scripts and styles removed, max 10000 chars).",
+    inputSchema: z.object({}),
+}, async () => {
+    const result = await relay("gettext");
+    return textResult(result);
+});
+server.registerTool("exec", {
+    title: "Execute JavaScript",
+    description: "Run JavaScript code on the current page and return the result. Blocked on sensitive pages.",
+    inputSchema: z.object({
+        script: z.string().describe("JavaScript code to execute"),
+    }),
+}, async (params) => {
+    const result = await relay("exec", params);
+    return textResult(result);
+});
+server.registerTool("cookie", {
+    title: "Manage Cookies",
+    description: "Get, set, or delete cookies for the current page.",
+    inputSchema: z.object({
+        cookieAction: z
+            .enum(["get", "set", "delete"])
+            .describe("Cookie operation"),
+        cookieName: z.string().describe("Cookie name"),
+        cookieValue: z
+            .string()
+            .optional()
+            .describe("Cookie value (required for set)"),
+    }),
+}, async (params) => {
+    const result = await relay("cookie", params);
+    return textResult(result);
+});
+server.registerTool("network", {
+    title: "Network Monitor",
+    description: "Start, stop, or get captured network requests. Use 'start' to begin monitoring, 'get' to retrieve entries, 'stop' to finish.",
+    inputSchema: z.object({
+        networkAction: z
+            .enum(["start", "stop", "get"])
+            .describe("Network monitoring operation"),
+    }),
+}, async (params) => {
+    const result = await relay("network", params);
+    return textResult(result);
+});
+// ── Capture actions ─────────────────────────────────────────────
+server.registerTool("fullscreenshot", {
+    title: "Full Page Screenshot",
+    description: "Capture a screenshot of the entire page (including content below the fold).",
+    inputSchema: z.object({
+        format: z
+            .enum(["png", "jpeg"])
+            .optional()
+            .describe("Image format (default: jpeg)"),
+    }),
+}, async (params) => {
+    const result = await relay("fullscreenshot", params);
+    if (result.success && result.data) {
+        return screenshotResult(result.data);
+    }
+    return textResult(result);
+});
+server.registerTool("pdf", {
+    title: "Export PDF",
+    description: "Export the current page as a PDF document.",
+    inputSchema: z.object({}),
+}, async () => {
+    const result = await relay("pdf");
+    return textResult(result);
+});
+// ── Wait actions ────────────────────────────────────────────────
+server.registerTool("scrollto", {
+    title: "Scroll To Element",
+    description: "Scroll the page to bring a specific element into view.",
+    inputSchema: z.object({
+        index: z.number().describe("Element index from extract results"),
+    }),
+}, async (params) => {
+    const result = await relay("scrollto", params);
+    return textResult(result);
+});
+server.registerTool("waitfor", {
+    title: "Wait For Element",
+    description: "Wait for an element matching a CSS selector to appear on the page.",
+    inputSchema: z.object({
+        selector: z.string().describe("CSS selector to wait for"),
+        timeout: z
+            .number()
+            .optional()
+            .describe("Max wait time in ms (default: 10000)"),
+    }),
+}, async (params) => {
+    const result = await relay("waitfor", params);
+    return textResult(result);
+});
+// ── Start ───────────────────────────────────────────────────────
+async function main() {
+    await ensureRelay();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("BrowserHand MCP server failed to start:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "browserhand-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for BrowserHand — control your real browser from Claude Desktop, Cursor, and other MCP clients",
+  "type": "module",
+  "bin": {
+    "browserhand-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx index.ts"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "tsx": "^4.21.0",
+    "@types/node": "^22.0.0"
+  }
+}