@coofly/agent-browser-mcp 1.0.0

package/README.md

@@ -0,0 +1,191 @@
+# agent-browser-mcp
+
+**[English](README.md)** | [中文](README_ZH.md)
+
+MCP (Model Context Protocol) server for [agent-browser](https://github.com/vercel-labs/agent-browser) - headless browser automation for AI agents.
+
+## Features
+
+- **CDP Remote Connection**: Connect to remote Chrome/Edge browser via Chrome DevTools Protocol
+- **Multiple Transport Modes**: Support both stdio and SSE (Server-Sent Events) transport
+- **YAML Configuration**: Easy-to-read configuration with comments support
+- **Docker Support**: Ready-to-use Dockerfile for containerized deployment
+
+## Installation
+
+### Via npx (Recommended)
+
+```bash
+# Run directly without installation
+npx @coofly/agent-browser-mcp
+
+# SSE mode
+npx @coofly/agent-browser-mcp --sse --port 9223
+
+# With CDP endpoint
+npx @coofly/agent-browser-mcp --cdp "http://localhost:9222"
+```
+
+### From Source
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd agent-browser-mcp
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+```
+
+## Configuration
+
+Copy the example configuration file:
+
+```bash
+cp config.example.yaml config.yaml
+```
+
+### Configuration Options
+
+```yaml
+# CDP remote debugging configuration
+cdp:
+  enabled: false
+  endpoint: "http://10.0.0.20:9222"
+
+# MCP server configuration
+server:
+  transport: stdio  # stdio or sse
+  port: 9223
+  host: "0.0.0.0"
+
+# Browser operation configuration
+browser:
+  timeout: 30000
+```
+
+## Usage
+
+### Stdio Mode (Default)
+
+```bash
+npm start
+```
+
+### SSE Mode
+
+```bash
+# Via command line
+npm start -- --sse --port 9223
+
+# Via environment variables
+MCP_TRANSPORT=sse MCP_PORT=9223 npm start
+```
+
+### With CDP Remote Browser
+
+```bash
+# Start Chrome with remote debugging
+chrome --remote-debugging-port=9222
+
+# Start MCP server with CDP
+npm start -- --cdp "http://localhost:9222"
+```
+
+### MCP Client Configuration
+
+#### Claude Desktop
+
+Add to your Claude Desktop configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "agent-browser": {
+      "command": "npx",
+      "args": ["agent-browser-mcp"]
+    }
+  }
+}
+```
+
+With CDP endpoint:
+
+```json
+{
+  "mcpServers": {
+    "agent-browser": {
+      "command": "npx",
+      "args": ["agent-browser-mcp", "--cdp", "http://localhost:9222"]
+    }
+  }
+}
+```
+
+## Docker
+
+### Build Image
+
+```bash
+docker build -t agent-browser-mcp:latest .
+```
+
+### Run Container
+
+```bash
+# SSE mode
+docker run -p 9223:9223 -e MCP_TRANSPORT=sse agent-browser-mcp:latest
+
+# With CDP endpoint
+docker run -p 9223:9223 \
+  -e MCP_TRANSPORT=sse \
+  -e CDP_ENDPOINT=http://host.docker.internal:9222 \
+  agent-browser-mcp:latest
+
+# With custom config
+docker run -p 9223:9223 \
+  -v ./config.yaml:/app/config.yaml \
+  agent-browser-mcp:latest
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `browser_open` | Open a URL |
+| `browser_back` | Navigate back |
+| `browser_forward` | Navigate forward |
+| `browser_reload` | Reload current page |
+| `browser_get_url` | Get current URL |
+| `browser_get_title` | Get page title |
+| `browser_click` | Click an element |
+| `browser_type` | Type text (character by character) |
+| `browser_fill` | Fill input field |
+| `browser_hover` | Hover over element |
+| `browser_press` | Press keyboard key |
+| `browser_select` | Select dropdown option |
+| `browser_snapshot` | Get page accessibility snapshot |
+| `browser_get_text` | Get element text |
+| `browser_get_html` | Get element HTML |
+| `browser_screenshot` | Take screenshot |
+| `browser_scroll` | Scroll page |
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CDP_ENDPOINT` | CDP remote endpoint URL | - |
+| `MCP_TRANSPORT` | Transport mode (stdio/sse) | stdio |
+| `MCP_PORT` | SSE server port | 9223 |
+| `MCP_HOST` | SSE server host | 0.0.0.0 |
+| `BROWSER_TIMEOUT` | Command timeout (ms) | 30000 |
+
+## License
+
+GPL-3.0

package/README_ZH.md

@@ -0,0 +1,191 @@
+# agent-browser-mcp
+
+[English](README.md) | **[中文](README_ZH.md)**
+
+[agent-browser](https://github.com/vercel-labs/agent-browser) 的 MCP (Model Context Protocol) 服务器 - 为 AI 代理提供无头浏览器自动化能力。
+
+## 功能特性
+
+- **CDP 远程连接**：通过 Chrome DevTools Protocol 连接远程 Chrome/Edge 浏览器
+- **多传输模式**：支持 stdio 和 SSE (Server-Sent Events) 两种传输方式
+- **YAML 配置**：易读的配置文件格式，支持注释
+- **Docker 支持**：提供 Dockerfile，支持容器化部署
+
+## 安装
+
+### 通过 npx（推荐）
+
+```bash
+# 直接运行（无需安装）
+npx @coofly/agent-browser-mcp
+
+# SSE 模式
+npx @coofly/agent-browser-mcp --sse --port 9223
+
+# 连接 CDP
+npx @coofly/agent-browser-mcp --cdp "http://localhost:9222"
+```
+
+### 从源码安装
+
+```bash
+# 克隆仓库
+git clone <repository-url>
+cd agent-browser-mcp
+
+# 安装依赖
+npm install
+
+# 编译
+npm run build
+```
+
+## 配置
+
+复制示例配置文件：
+
+```bash
+cp config.example.yaml config.yaml
+```
+
+### 配置选项
+
+```yaml
+# CDP 远程调试配置
+cdp:
+  enabled: false
+  endpoint: "http://10.0.0.20:9222"
+
+# MCP 服务器配置
+server:
+  transport: stdio  # stdio 或 sse
+  port: 9223
+  host: "0.0.0.0"
+
+# 浏览器操作配置
+browser:
+  timeout: 30000
+```
+
+## 使用方法
+
+### Stdio 模式（默认）
+
+```bash
+npm start
+```
+
+### SSE 模式
+
+```bash
+# 命令行参数
+npm start -- --sse --port 9223
+
+# 环境变量
+MCP_TRANSPORT=sse MCP_PORT=9223 npm start
+```
+
+### 连接 CDP 远程浏览器
+
+```bash
+# 启动带远程调试的 Chrome
+chrome --remote-debugging-port=9222
+
+# 启动 MCP 服务器并连接 CDP
+npm start -- --cdp "http://localhost:9222"
+```
+
+### MCP 客户端配置
+
+#### Claude Desktop
+
+添加到 Claude Desktop 配置文件：
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "agent-browser": {
+      "command": "npx",
+      "args": ["agent-browser-mcp"]
+    }
+  }
+}
+```
+
+连接 CDP 端点：
+
+```json
+{
+  "mcpServers": {
+    "agent-browser": {
+      "command": "npx",
+      "args": ["agent-browser-mcp", "--cdp", "http://localhost:9222"]
+    }
+  }
+}
+```
+
+## Docker
+
+### 构建镜像
+
+```bash
+docker build -t agent-browser-mcp:latest .
+```
+
+### 运行容器
+
+```bash
+# SSE 模式
+docker run -p 9223:9223 -e MCP_TRANSPORT=sse agent-browser-mcp:latest
+
+# 指定 CDP 端点
+docker run -p 9223:9223 \
+  -e MCP_TRANSPORT=sse \
+  -e CDP_ENDPOINT=http://host.docker.internal:9222 \
+  agent-browser-mcp:latest
+
+# 挂载自定义配置
+docker run -p 9223:9223 \
+  -v ./config.yaml:/app/config.yaml \
+  agent-browser-mcp:latest
+```
+
+## 可用工具
+
+| 工具 | 描述 |
+|------|------|
+| `browser_open` | 打开 URL |
+| `browser_back` | 后退 |
+| `browser_forward` | 前进 |
+| `browser_reload` | 刷新页面 |
+| `browser_get_url` | 获取当前 URL |
+| `browser_get_title` | 获取页面标题 |
+| `browser_click` | 点击元素 |
+| `browser_type` | 输入文本（逐字符） |
+| `browser_fill` | 填充输入框 |
+| `browser_hover` | 悬停元素 |
+| `browser_press` | 按下键盘按键 |
+| `browser_select` | 选择下拉选项 |
+| `browser_snapshot` | 获取页面可访问性快照 |
+| `browser_get_text` | 获取元素文本 |
+| `browser_get_html` | 获取元素 HTML |
+| `browser_screenshot` | 截图 |
+| `browser_scroll` | 滚动页面 |
+
+## 环境变量
+
+| 变量 | 描述 | 默认值 |
+|------|------|--------|
+| `CDP_ENDPOINT` | CDP 远程端点 URL | - |
+| `MCP_TRANSPORT` | 传输模式 (stdio/sse) | stdio |
+| `MCP_PORT` | SSE 服务器端口 | 9223 |
+| `MCP_HOST` | SSE 服务器地址 | 0.0.0.0 |
+| `BROWSER_TIMEOUT` | 命令超时时间 (毫秒) | 30000 |
+
+## 许可证
+
+GPL-3.0

package/config.example.yaml

@@ -0,0 +1,44 @@
+# agent-browser-mcp 配置文件
+# 复制此文件为 config.yaml 并根据需要修改
+
+# ===================
+# CDP 远程调试配置
+# ===================
+cdp:
+  # 是否启用 CDP 远程连接
+  # 启用后将连接到远程 Chrome/Edge 浏览器实例
+  enabled: false
+
+  # CDP 远程端点地址
+  # 格式: http://<host>:<port>
+  # 示例: http://10.0.0.20:9222
+  #
+  # 如何启动支持 CDP 的浏览器:
+  #   Chrome: chrome --remote-debugging-port=9222
+  #   Edge:   msedge --remote-debugging-port=9222
+  endpoint: "http://10.0.0.20:9222"
+
+# ===================
+# MCP 服务器配置
+# ===================
+server:
+  # 传输模式
+  # - stdio: 标准输入输出模式（默认，用于 Claude Desktop 等）
+  # - sse:   HTTP/SSE 模式（用于 Web 客户端或远程访问）
+  transport: stdio
+
+  # SSE 模式下的监听端口
+  port: 9223
+
+  # SSE 模式下的监听地址
+  # - 0.0.0.0: 监听所有网络接口（允许远程访问）
+  # - 127.0.0.1: 仅本地访问
+  host: "0.0.0.0"
+
+# ===================
+# 浏览器操作配置
+# ===================
+browser:
+  # 命令执行超时时间（毫秒）
+  # 建议值: 30000-60000
+  timeout: 30000

package/dist/config.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 配置接口定义
+ */
+/**
+ * CDP 配置
+ */
+export interface CdpConfig {
+    /** 是否启用 CDP 远程连接 */
+    enabled: boolean;
+    /** CDP 远程端点地址，如 http://10.0.0.20:9222 */
+    endpoint: string;
+}
+/**
+ * 服务器配置
+ */
+export interface ServerConfig {
+    /** 传输模式: stdio 或 sse */
+    transport: 'stdio' | 'sse';
+    /** SSE 模式下的端口号 */
+    port: number;
+    /** SSE 模式下的监听地址 */
+    host: string;
+}
+/**
+ * 浏览器配置
+ */
+export interface BrowserConfig {
+    /** 命令执行超时时间（毫秒） */
+    timeout: number;
+}
+/**
+ * 完整配置接口
+ */
+export interface AppConfig {
+    cdp: CdpConfig;
+    server: ServerConfig;
+    browser: BrowserConfig;
+}
+/**
+ * 默认配置
+ */
+export declare const defaultConfig: AppConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,oBAAoB;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,SAAS,EAAE,OAAO,GAAG,KAAK,CAAC;IAC3B,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mBAAmB;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC;CACxB;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,SAa3B,CAAC"}

package/dist/config.js

@@ -0,0 +1,21 @@
+/**
+ * 配置接口定义
+ */
+/**
+ * 默认配置
+ */
+export const defaultConfig = {
+    cdp: {
+        enabled: false,
+        endpoint: '',
+    },
+    server: {
+        transport: 'stdio',
+        port: 9223,
+        host: '0.0.0.0',
+    },
+    browser: {
+        timeout: 30000,
+    },
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAyCH;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAc;IACtC,GAAG,EAAE;QACH,OAAO,EAAE,KAAK;QACd,QAAQ,EAAE,EAAE;KACb;IACD,MAAM,EAAE;QACN,SAAS,EAAE,OAAO;QAClB,IAAI,EAAE,IAAI;QACV,IAAI,EAAE,SAAS;KAChB;IACD,OAAO,EAAE;QACP,OAAO,EAAE,KAAK;KACf;CACF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { startServer } from './server.js';
+import { getConfig } from './utils/configLoader.js';
+// 加载配置并显示启动信息
+const config = getConfig();
+console.error('[agent-browser-mcp] 启动中...');
+console.error(`[配置] 传输模式: ${config.server.transport}`);
+if (config.cdp.enabled) {
+    console.error(`[配置] CDP 端点: ${config.cdp.endpoint}`);
+}
+startServer().catch((error) => {
+    console.error('服务器启动失败:', error);
+    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":";AACA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD,cAAc;AACd,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;AAC3B,OAAO,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;AAC5C,OAAO,CAAC,KAAK,CAAC,cAAc,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;AACvD,IAAI,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;IACvB,OAAO,CAAC,KAAK,CAAC,gBAAgB,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;AACvD,CAAC;AAED,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IAC5B,OAAO,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACjC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,43 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+/**
+ * 创建并启动 MCP 服务器
+ */
+export declare function createServer(): Promise<Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+        progressToken?: string | number | undefined;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        } | undefined;
+    } | undefined;
+}>>;
+/**
+ * 启动服务器
+ */
+export declare function startServer(): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAsPnE;;GAEG;AACH,wBAAsB,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAwBjC;AAED;;GAEG;AACH,wBAAsB,WAAW,kBAgBhC"}