Blueprint Mcp For Chrome

Blueprint MCP

通过 Model Context Protocol 使用 AI 控制真实浏览器

这是什么？

一个 MCP（Model Context Protocol）服务，可通过浏览器扩展让 AI 助手控制你的真实浏览器（Chrome、Firefox 或 Opera）。与无头自动化工具不同，它使用你的真实浏览器配置文件，保留所有已登录会话、Cookie 和扩展。

适用场景： 需要与已登录网站交互，或需要避免机器人检测的 AI Agent。

为什么选择它，而不是 Playwright/Puppeteer？

Blueprint MCP	Playwright/Puppeteer
✅ 真实浏览器（非无头模式）	❌ 无头模式或新的浏览器实例
✅ 在所有网站上保持登录状态	❌ 每个会话都必须重新进行身份验证
✅ 避免机器人检测（使用真实指纹）	⚠️ 常被检测为自动化浏览器
✅ 可与现有浏览器扩展配合使用	❌ 不支持扩展
✅ 零配置——开箱即用	⚠️ 需要安装浏览器
✅ 支持 Chrome、Firefox、Edge、Opera	✅ 支持 Chrome、Firefox、Safari

安装

1. 安装 MCP 服务

npm install -g @railsblueprint/blueprint-mcp

2. 安装浏览器扩展

选择你的浏览器：

Chrome / Edge / Opera

• Chrome Web Store（适用于所有 Chromium 浏览器）
• 手动安装：从 Releases 下载，然后在 chrome://extensions/（Chrome）、edge://extensions/（Edge）或 opera://extensions/（Opera）中加载已解压的扩展程序

Firefox

• Firefox Add-ons
• 手动安装：从 Releases 下载，然后在 about:debugging#/runtime/this-firefox 中加载

3. 配置 MCP 客户端

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）：

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

Claude Code（AI 驱动的命令行工具）：

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

VS Code / Cursor（.vscode/settings.json）：

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

快速开始

1. 启动 MCP 客户端（Claude Desktop、Cursor 等）
2. 点击浏览器中的 Blueprint MCP 扩展图标
3. 扩展会自动连接到 MCP 服务
4. 让 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)        │
└─────────────────────────┘

免费版与 PRO 版

免费版（默认）

• ✅ 本地 WebSocket 连接（端口 5555）
• ✅ 单个浏览器实例
• ✅ 所有浏览器自动化功能
• ✅ 无需账户
• ❌ 仅限同一台设备使用

PRO 版

• ✅ 云中继——可从任何地方连接
• ✅ 多个浏览器——控制多个浏览器实例
• ✅ 共享访问——多个 AI 客户端可使用同一个浏览器
• ✅ 自动重连——网络发生变化时保持连接
• ✅ 优先支持

升级到 PRO

可用工具

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

连接管理

• enable - 启用浏览器自动化（必须首先执行）
• disable - 停用浏览器自动化
• status - 检查连接状态
• auth - 登录 PRO 账户（用于云中继功能）

标签页管理

• browser_tabs - 列出、创建、连接或关闭浏览器标签页

导航

• browser_navigate - 导航至 URL
• browser_navigate_back - 返回上一页

内容与检查

• browser_snapshot - 获取可访问的页面内容（推荐用于阅读页面）
• browser_take_screenshot - 捕获页面截图
• browser_console_messages - 获取浏览器控制台日志
• browser_network_requests - 强大的网络监控与重放工具，支持多种操作：
  • 列表模式（默认）：提供轻量级概览，支持筛选和分页（默认：20 个请求）
    • 筛选条件：urlPattern（子字符串）、method（GET/POST）、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 - 将页面内容提取为 Markdown

交互

• 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 - 处理 alert/confirm/prompt 对话框
• 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 或 yarn

设置

# 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 扩展无需构建步骤——它使用原生 JavaScript，可直接从 extensions/firefox/ 加载

在浏览器中加载扩展：

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

1. 打开 chrome://extensions/（Chrome）、edge://extensions/（Edge）或 opera://extensions/（Opera）
2. 启用“开发者模式”
3. 点击“加载已解压的扩展程序”
4. 选择 extensions/chrome/dist 文件夹

对于 Firefox：

1. 打开 about:debugging#/runtime/this-firefox
2. 点击“临时加载附加组件”
3. 从 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

**注意：**如果更改端口，需要更新浏览器扩展设置，使其与之匹配。

故障排除

扩展无法连接

1. 检查扩展是否已安装并启用
2. 点击扩展图标——应显示“已连接”
3. 检查 MCP 服务是否正在运行（查找端口 5555 上的进程）
4. 尝试重新加载扩展

“端口 5555 已被占用”

另一个实例正在运行。你可以选择：

1. 终止现有进程：

lsof -ti:5555 | xargs kill -9

2. 使用其他端口：

blueprint-mcp --port 8080

浏览器工具无法正常工作

1. 确保已先调用 enable
2. 检查是否已通过 browser_tabs 附加到某个标签页
3. 确认该标签页仍然存在（未关闭）

获取帮助

• GitHub 问题
• 文档

参与贡献

欢迎参与贡献！请参阅 CONTRIBUTING.md 了解相关指南。

安全

此工具允许 AI 助手控制你的浏览器。请注意：

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

发现安全问题？请发送邮件至 [email protected]，而不要提交公开问题。

致谢

本项目最初受 Microsoft 的 Playwright MCP 实现启发，但后来经过彻底重写，改用基于浏览器扩展的自动化方式，而非 Playwright。其架构、实现和方法有着根本性的不同。

主要区别：

• 使用带有 DevTools Protocol 的浏览器扩展（而非 Playwright）
• 使用真实的浏览器配置文件（而非隔离的上下文）
• 基于 WebSocket 的通信（而非 CDP 中继）
• 提供用于远程访问的云中继选项
• 提供免费和 PRO 两种版本
• 支持多种浏览器（Chrome、Firefox、Edge、Opera）

感谢 Playwright 团队率先通过 MCP 实现浏览器自动化。

许可证

Apache License 2.0——请参阅 LICENSE

版权所有 (c) 2025 Rails Blueprint

---

由 Rails Blueprint 倾心打造 ❤️

网站 • GitHub • NPM