@dwao/live-browser-mcp 1.0.0

package/index.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+
+/**
+ * @dwao/live-browser-mcp
+ *
+ * Stdio MCP server that exposes Playwright-compatible browser_* tools,
+ * proxying each call through HTTP to a backend relay which forwards
+ * via WebSocket to a Chrome extension's CDP handler on the user's real tab.
+ *
+ * Environment variables:
+ *   BACKEND_URL  - Backend URL (e.g., https://evolve-api.dwao.com)
+ *   TAB_ID       - Chrome tab ID to target
+ *   INTERNAL_KEY - Shared secret for internal API authentication
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from '@modelcontextprotocol/sdk/types.js';
+
+const BACKEND_URL = process.env.BACKEND_URL;
+const TAB_ID = process.env.TAB_ID;
+const INTERNAL_KEY = process.env.INTERNAL_KEY || '';
+const ACTION_TIMEOUT = 30_000;
+
+if (!BACKEND_URL || !TAB_ID) {
+  console.error('BACKEND_URL and TAB_ID environment variables are required');
+  process.exit(1);
+}
+
+// ============================================================================
+// Tool definitions — mirror Playwright MCP's browser_* tools
+// ============================================================================
+
+const TOOLS = [
+  {
+    name: 'browser_navigate',
+    description: 'Navigate the browser to a URL',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'URL to navigate to' }
+      },
+      required: ['url']
+    }
+  },
+  {
+    name: 'browser_snapshot',
+    description: 'Capture accessibility snapshot of the current page. Returns a text representation of the page with element references like [ref=e1].',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    }
+  },
+  {
+    name: 'browser_evaluate',
+    description: 'Execute JavaScript in the browser console',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        expression: { type: 'string', description: 'JavaScript expression to evaluate' }
+      },
+      required: ['expression']
+    }
+  },
+  {
+    name: 'browser_screenshot',
+    description: 'Take a screenshot of the current page',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    }
+  },
+  {
+    name: 'browser_click',
+    description: 'Click on an element identified by reference from a snapshot',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        element: { type: 'string', description: 'Human-readable element description' },
+        ref: { type: 'string', description: 'Element reference from snapshot (e.g., "e5")' }
+      },
+      required: ['element', 'ref']
+    }
+  },
+  {
+    name: 'browser_type',
+    description: 'Type text into an element identified by reference from a snapshot',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        element: { type: 'string', description: 'Human-readable element description' },
+        ref: { type: 'string', description: 'Element reference from snapshot (e.g., "e5")' },
+        text: { type: 'string', description: 'Text to type' },
+        submit: { type: 'boolean', description: 'Whether to press Enter after typing' }
+      },
+      required: ['element', 'ref', 'text']
+    }
+  },
+  {
+    name: 'browser_scroll',
+    description: 'Scroll the page up or down',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        direction: { type: 'string', enum: ['up', 'down'], description: 'Scroll direction' },
+        amount: { type: 'number', description: 'Pixels to scroll (default 300)' }
+      },
+      required: ['direction']
+    }
+  }
+];
+
+// ============================================================================
+// HTTP proxy to backend browser-action endpoint
+// ============================================================================
+
+async function sendBrowserAction(action, params = {}) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), ACTION_TIMEOUT);
+
+  try {
+    const res = await fetch(`${BACKEND_URL}/api/browser-action`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Internal-Key': INTERNAL_KEY
+      },
+      body: JSON.stringify({ tabId: TAB_ID, action, params }),
+      signal: controller.signal
+    });
+
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`Browser action failed (${res.status}): ${body}`);
+    }
+
+    return await res.json();
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// ============================================================================
+// MCP Server setup
+// ============================================================================
+
+const server = new Server(
+  { name: '@dwao/live-browser-mcp', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools: TOOLS };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    const result = await sendBrowserAction(name, args || {});
+
+    // Screenshot returns base64 image
+    if (name === 'browser_screenshot' && result.screenshot) {
+      return {
+        content: [
+          {
+            type: 'image',
+            data: result.screenshot,
+            mimeType: 'image/png'
+          }
+        ]
+      };
+    }
+
+    // All other tools return text
+    const text = typeof result.result === 'string'
+      ? result.result
+      : JSON.stringify(result.result, null, 2);
+
+    return {
+      content: [{ type: 'text', text }]
+    };
+
+  } catch (error) {
+    return {
+      content: [{ type: 'text', text: `Error: ${error.message}` }],
+      isError: true
+    };
+  }
+});
+
+// Start the server
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@dwao/live-browser-mcp",
+  "version": "1.0.0",
+  "description": "MCP server that proxies browser tools to a real Chrome tab via CDP through a WebSocket relay",
+  "type": "module",
+  "bin": {
+    "live-browser-mcp": "./index.js"
+  },
+  "files": [
+    "index.js"
+  ],
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "chrome",
+    "cdp",
+    "browser",
+    "devtools",
+    "playwright-compatible"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicholasgma/live-browser-mcp"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}