星战科技xingzhan.cloud
返回市场
蓝图-mcp

蓝图-mcp

作者：railsblueprint21 星标更新：2025-11-19
安装使用来源：spider==github.com

项目介绍

蓝图 MCP

通过模型上下文协议（Model Context Protocol）用AI控制您的真实浏览器

npm 版本 许可证

这是什么？

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

适用于： 需要与您已经登录的网站进行交互的AI代理，或者需要避免被检测为机器人的场景。

为什么选择这个而不是Playwright/Puppeteer？

蓝图 MCPPlaywright/Puppeteer
✅ 实际浏览器（非无头模式）❌ 无头模式或新浏览器实例
✅ 保持登录到所有站点❌ 每个会话都需要重新认证
✅ 避免被检测为机器人（使用真实指纹）⚠️ 经常被检测为自动化的浏览器
✅ 支持现有的浏览器扩展程序❌ 不支持扩展程序
✅ 零配置 - 开箱即用⚠️ 需要安装浏览器
✅ 支持Chrome、Firefox、Edge、Opera✅ 支持Chrome、Firefox、Safari

安装

1. 安装MCP服务器

npm install -g @railsblueprint/blueprint-mcp

2. 安装浏览器扩展程序

选择您的浏览器：

Chrome / Edge / Opera

  • Chrome Web Store（适用于所有基于Chromium的浏览器）
  • 手动安装：从发布页面下载，然后在chrome://extensions/（Chrome）、edge://extensions/（Edge）或opera://extensions/（Opera）中加载未打包的扩展程序

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驱动的CLI）：

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. 点击浏览器中的蓝图MCP扩展图标
  3. 扩展程序会自动连接到MCP服务器
  4. 让您的AI助手浏览！

示例对话：

您："去GitHub查看我的通知"
AI：*导航到github.com，点击通知，阅读内容*

您："用我的信息填写这个表单"
AI：*读取表单字段，填写并提交*

您："截取这个页面的屏幕截图"
AI：*捕获屏幕截图并显示给您*

工作原理

┌─────────────────────────┐
│   AI 助手              │
│   （Claude，GPT等）    │
└───────────┬─────────────┘
            │
            │ MCP 协议
            ↓
┌─────────────────────────┐
│   MCP 客户端            │
│   （Claude Desktop等）  │
└───────────┬─────────────┘
            │
            │ 标准输入输出/JSON-RPC
            ↓
┌─────────────────────────┐
│   blueprint-mcp         │
│   （此包）              │
└───────────┬─────────────┘
            │
            │ WebSocket（本地5555端口或云中继）
            ↓
┌─────────────────────────┐
│   浏览器扩展程序        │
└───────────┬─────────────┘
            │
            │ 浏览器扩展程序API
            ↓
┌─────────────────────────┐
│   您的浏览器            │
│   （真实配置文件）      │
└─────────────────────────┘

免费版 vs 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 - 处理警告/确认/提示对话框
  • 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

设置

# 克隆仓库
git clone https://github.com/railsblueprint/blueprint-mcp.git
cd blueprint-mcp

# 安装服务器依赖
cd server
npm install
cd ..

# 安装Chrome扩展程序依赖
cd extensions/chrome
npm install
cd ../..

开发环境运行

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

cd server
node cli.js --debug

终端2：构建Chrome扩展程序

cd extensions/chrome
npm run build
# 或者启用监视模式：
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 服务器
│   ├── cli.js                  # 服务器入口点
│   ├── src/
│   │   ├── statefulBackend.js  # 连接状态管理
│   │   ├── unifiedBackend.js   # MCP 工具实现
│   │   ├── extensionServer.js  # 扩展程序WebSocket服务器
│   │   ├── mcpConnection.js    # 代理/中继连接处理
│   │   ├── transport.js        # 传输抽象层
│   │   ├── oauth.js            # OAuth2客户端（用于PRO功能）
│   │   └── fileLogger.js       # 调试日志
│   └── tests/                  # 服务器测试套件
├── extensions/                 # 浏览器扩展程序
│   ├── chrome/                 # Chrome扩展程序（TypeScript + Vite）
│   │   └── src/
│   │       ├── background.ts   # 扩展程序服务工作者
│   │       ├── content-script.ts # 页面内容注入
│   │       └── utils/          # 工具函数
│   ├── firefox/                # Firefox扩展程序（纯JavaScript）
│   │   └── src/
│   │       ├── background.js   # 服务工作者
│   │       └── content-script.js # 页面注入
│   ├── shared/                 # 扩展程序之间的共享代码
│   └── build-*.js              # 每个浏览器的构建脚本
├── docs/                       # 文档
│   ├── testing/                # 测试文档
│   ├── architecture/           # 架构文档
│   └── stores/                 # 浏览器存储资产
└── releases/                   # 发布的扩展程序
    ├── chrome/
    ├── firefox/
    ├── edge/
    └── opera/

测试

# 运行测试
npm test

# 运行带覆盖率的测试
npm run test:coverage

文档：

配置

服务器开箱即用，具有合理的默认设置。对于高级配置：

环境变量

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

# 认证服务器（PRO功能）
AUTH_BASE_URL=https://blueprint-mcp.railsblueprint.com

# 本地WebSocket端口（免费版）
MCP_PORT=5555

# 调试模式
DEBUG=false

命令行选项

blueprint-mcp --debug              # 启用详细日志
blueprint-mcp --port 8080          # 使用自定义WebSocket端口（默认：5555）
blueprint-mcp --debug --port  8080 # 结合选项

注意：如果您更改了端口，请确保更新浏览器扩展程序设置以匹配。

故障排除

扩展程序无法连接

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

“端口5555已被占用”

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

  1. 杀死现有进程：
lsof -ti:5555 | xargs kill -9
  1. 使用不同的端口：
blueprint-mcp --port 8080

浏览器工具不起作用

  1. 确保您首先调用了enable
  2. 检查您是否已通过browser_tabs附加到一个标签
  3. 验证标签仍然存在（没有被关闭）

获取帮助

贡献

我们欢迎贡献！请参阅CONTRIBUTING.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 - 详见LICENSE

版权所有 (c) 2025 Rails Blueprint

由Rails Blueprint倾心打造

官网 • GitHub • NPM