Name: 浏览器AI控制协议
Author: railsblueprint

使用说明

MCP蓝图

通过模型上下文协议使用AI控制您的真实浏览器

这是什么？

MCP（模型上下文协议）服务器，允许AI助手通过浏览器扩展程序控制您的实际浏览器（Chrome、Firefox或Opera）。与无头自动化工具不同，它使用您的真实浏览器配置文件，所有登录的会话、Cookie和扩展都完好无损。

非常适合： 需要与您已经登录的网站进行交互的AI代理，或者需要避免机器人检测的AI代理。

为什么用这个而不是剧作家/木偶师？

蓝图MCP	剧作家/木偶师
✅ 真实浏览器（非无头）	❌ 无头或新浏览器实例
✅ 保持登录到您的所有网站	❌ 必须重新验证每个会话
✅ 避免机器人检测（使用真实指纹）	⚠️ 经常被检测为自动浏览器
✅ 适用于您现有的浏览器扩展程序	❌ 无扩展支持
✅ 零设置-开箱即用	⚠️ 需要安装浏览器
✅ Chrome、Firefox、Edge、Opera支持	✅ Chrome、Firefox、Safari支持

安装

1.安装MCP服务器

npm install -g @railsblueprint/blueprint-mcp

2.安装浏览器扩展

选择您的浏览器：

Chrome浏览器/Edge浏览器/Opera浏览器

Chrome网络商店（适用于所有Chromium浏览器）
手册：从下载发布，然后在未包装的情况下装载 chrome://extensions/ （Chrome）， edge://extensions/ （边缘），或 opera://extensions/ （歌剧）

火狐

附加元件
手册：从下载发布，然后加载 about:debugging#/runtime/this-firefox

3.配置您的MCP客户端

克劳德桌面 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["@railsblueprint/blueprint-mcp@latest"]
    }
  }
}

克劳德代码 （AI驱动的CLI）：

claude mcp add browser npx @railsblueprint/blueprint-mcp@latest

VS代码/光标 (.vscode/settings.json):

{
  "mcp.servers": {
    "browser": {
      "command": "npx",
      "args": ["@railsblueprint/blueprint-mcp@latest"]
    }
  }
}

快速开始

启动您的MCP客户端 （克劳德桌面、光标等）
单击蓝图MCP扩展图标 在浏览器中
扩展自动连接到MCP服务器
让你的AI助手浏览！

对话示例：

You: "Go to GitHub and check my notifications"
AI: *navigates to github.com, clicks notifications, reads content*

You: "Fill out this form with my info"
AI: *reads form fields, fills them in, submits*

You: "Take a screenshot of this page"
AI: *captures screenshot and shows you*

运作原理

┌─────────────────────────┐
│   AI Assistant          │
│   (Claude, GPT, etc)    │
└───────────┬─────────────┘
            │
            │ MCP Protocol
            ↓
┌─────────────────────────┐
│   MCP Client            │
│   (Claude Desktop, etc) │
└───────────┬─────────────┘
            │
            │ stdio/JSON-RPC
            ↓
┌─────────────────────────┐
│   blueprint-mcp         │
│   (this package)        │
└───────────┬─────────────┘
            │
            │ WebSocket (localhost:5555 or cloud relay)
            ↓
┌─────────────────────────┐
│   Browser Extension     │
└───────────┬─────────────┘
            │
            │ Browser Extension APIs
            ↓
┌─────────────────────────┐
│   Your Browser          │
│   (real profile)        │
└─────────────────────────┘

免费vs专业

免费等级（默认）

✅ 本地WebSocket连接（端口5555）
✅ 单个浏览器实例
✅ 所有浏览器自动化功能
✅ 无需帐户
❌ 仅限于同一台机器

PRO等级

✅ 云中继 -从任何地方连接
✅ 多个浏览器 -控制多个浏览器实例
✅ 共享访问 -多个AI客户端可以使用同一浏览器
✅ 自动重新连接 -通过网络更改保持连接
✅ 优先支持

升级到PRO

可用工具

MCP服务器为AI助手提供以下工具：

连接管理

enable -激活浏览器自动化（必需的第一步）
disable -停用浏览器自动化
status -检查连接状态
auth -登录PRO帐户（用于云中继功能）

选项卡管理

browser_tabs -列出、创建、附加或关闭浏览器选项卡

内容与检查

browser_snapshot -获取可访问的页面内容（建议用于阅读页面）
browser_take_screenshot -捕获可视屏幕截图
browser_console_messages -获取浏览器控制台日志
browser_network_requests -强大的网络监控和回放工具，具有多种操作：
- 列表模式 （默认）：具有过滤和分页功能的轻量级概述（默认：20个请求）
  - 过滤器： urlPattern （子字符串）， method （获取/发布）， status (200/404), resourceType （xhr/fetch/script）
  - 分页： limit （默认值：20）， offset （默认值：0）
  - 例子： action='list', urlPattern='api/users', method='GET', limit=10
- 详细信息模式：特定请求的完整请求/响应数据，包括标头和正文
- JSONPath过滤：使用JSONPath语法查询大型JSON响应（例如。， $.data.items[0])
- 回放模式：使用原始标头和身份验证重新执行捕获的请求
- 清除模式：清除捕获的历史记录以释放内存
- 例子： action='details', requestId='12345.67', jsonPath='$.data.users[0]'
browser_extract_content -提取页面内容作为标记

交互

browser_interact -按顺序执行多个操作（单击、键入、悬停、等待等）
browser_click -点击元素
browser_type -在输入中键入文本
browser_hover -将鼠标悬停在元素上
browser_select_option -选择下拉选项
browser_fill_form -一次填写多个表单字段
browser_press_key -按键盘键
browser_drag -拖放元素

高级

browser_evaluate -在页面上下文中执行JavaScript
browser_handle_dialog -处理警报/确认/提示对话框
browser_file_upload -通过文件输入上传文件
browser_window -调整浏览器窗口大小、最小化、最大化
browser_pdf_save -将当前页面另存为PDF
browser_performance_metrics -获取性能指标
browser_verify_text_visible -验证文本是否存在（用于测试）
browser_verify_element_visible -验证元素是否存在（用于测试）

扩展管理

browser_list_extensions -列出已安装的浏览器扩展
browser_reload_extensions -重新加载解压缩的扩展（在开发过程中很有用）

发展

先决条件

Node.js 18+
支持的浏览器（Chrome、Firefox、Edge或Opera）
npm或纱线

设置

# Clone the repository
git clone https://github.com/railsblueprint/blueprint-mcp.git
cd blueprint-mcp

# Install server dependencies
cd server
npm install
cd ..

# Install Chrome extension dependencies
cd extensions/chrome
npm install
cd ../..

在发展中奔跑

终端1：以调试模式启动MCP服务器

cd server
node cli.js --debug

终端2：构建Chrome扩展程序

cd extensions/chrome
npm run build
# or for watch mode:
npm run dev

注： Firefox扩展不需要构建步骤，它使用vanilla JavaScript，可以直接从 extensions/firefox/

在浏览器中加载扩展：

对于Chromium浏览器（Chrome、Edge、Opera）：

打开 chrome://extensions/ （Chrome）， edge://extensions/ （边缘），或 opera://extensions/ （歌剧）
启用“开发人员模式”
点击“加载解包”
选择 extensions/chrome/dist 文件夹

对于Firefox：

打开 about:debugging#/runtime/this-firefox
点击“加载临时加载项”
从中选择任何文件 extensions/firefox 文件夹

项目结构

blueprint-mcp/
├── server/                     # MCP Server
│   ├── cli.js                  # Server entry point
│   ├── src/
│   │   ├── statefulBackend.js  # Connection state management
│   │   ├── unifiedBackend.js   # MCP tool implementations
│   │   ├── extensionServer.js  # WebSocket server for extension
│   │   ├── mcpConnection.js    # Proxy/relay connection handling
│   │   ├── transport.js        # Transport abstraction layer
│   │   ├── oauth.js            # OAuth2 client for PRO features
│   │   └── fileLogger.js       # Debug logging
│   └── tests/                  # Server test suites
├── extensions/                 # Browser Extensions
│   ├── chrome/                 # Chrome extension (TypeScript + Vite)
│   │   └── src/
│   │       ├── background.ts   # Extension service worker
│   │       ├── content-script.ts # Page content injection
│   │       └── utils/          # Utility functions
│   ├── firefox/                # Firefox extension (Vanilla JS)
│   │   └── src/
│   │       ├── background.js   # Service worker
│   │       └── content-script.js # Page injection
│   ├── shared/                 # Shared code between extensions
│   └── build-*.js              # Build scripts for each browser
├── docs/                       # Documentation
│   ├── testing/                # Test documentation
│   ├── architecture/           # Architecture docs
│   └── stores/                 # Browser store assets
└── releases/                   # Built extensions for distribution
    ├── chrome/
    ├── firefox/
    ├── edge/
    └── opera/

测试

# Run tests
npm test

# Run with coverage
npm run test:coverage

文档：

手动测试程序 -全面的手动测试指南
特性规范 -完整的功能文档
测试进度 -当前测试覆盖率状态

配置

服务器使用合理的默认值即可开箱即用。对于高级配置：

环境变量

创建一个 .env 项目根目录中的文件：

# Authentication server (PRO features)
AUTH_BASE_URL=https://blueprint-mcp.railsblueprint.com

# Local WebSocket port (Free tier)
MCP_PORT=5555

# Debug mode
DEBUG=false

命令行选项

blueprint-mcp --debug              # Enable verbose logging
blueprint-mcp --port 8080          # Use custom WebSocket port (default: 5555)
blueprint-mcp --debug --port 8080  # Combine options

注：如果更改端口，则需要更新浏览器扩展设置以匹配。

故障排除

扩展无法连接

检查扩展是否已安装并启用
点击扩展图标-它应该显示“已连接”
检查MCP服务器是否正在运行（在端口5555上查找进程）
尝试重新加载扩展名

“端口5555已在使用中”

另一个实例正在运行。您可以：

终止现有进程：

lsof -ti:5555 | xargs kill -9

使用其他端口：

blueprint-mcp --port 8080

浏览器工具不工作

确保你打过电话 enable 第一
检查您是否已附加到标签页 browser_tabs
验证选项卡是否仍然存在（未关闭）

获得帮助

贡献

我们欢迎捐款！看贡献.md 作为指导方针。

安全

该工具使AI助手能够控制您的浏览器。请审阅：

默认情况下，MCP服务器只接受本地连接（localhost:5555）
PRO中继连接通过OAuth进行身份验证
该扩展需要明确的用户操作才能连接
所有浏览器操作都要经过浏览器的权限系统

发现安全问题？请发送电子邮件至security@railsblueprint.com而不是公开发行。

鸣谢

该项目最初受到微软Playwright MCP实现的启发，但已完全重写为使用基于浏览器扩展的自动化，而不是Playwright。架构、实现和方法根本不同。

主要区别：

使用带有DevTools协议的浏览器扩展（不是Playwright）
适用于真实的浏览器配置文件（不是孤立的上下文）
基于WebSocket的通信（非CDP中继）
远程访问的云中继选项
免费和PRO层模型
支持多浏览器（Chrome、Firefox、Edge、Opera）

我们感谢Playwright团队通过MCP开创了浏览器自动化的先河。

许可证

Apache许可证2.0-请参阅许可证

内置于❤️ 靠近 Rails蓝图

网站 • GitHub • NPM