Blueprint MCP Server

chính thức

Tự động hóa trình duyệt qua MCP cho Chrome và Firefox

Tài liệu

Blueprint MCP

Điều khiển trình duyệt thực của bạn bằng AI thông qua Model Context Protocol

Đây là gì?

Một máy chủ MCP (Model Context Protocol) cho phép trợ lý AI điều khiển trình duyệt thực của bạn (Chrome, Firefox hoặc Opera) thông qua tiện ích mở rộng trình duyệt. Không giống như các công cụ tự động hóa không giao diện, công cụ này sử dụng hồ sơ trình duyệt thực của bạn với tất cả các phiên đăng nhập, cookie và tiện ích mở rộng còn nguyên vẹn.

Hoàn hảo cho: Các tác nhân AI cần tương tác với các trang web mà bạn đã đăng nhập hoặc cần tránh bị phát hiện là bot.

Tại sao nên dùng công cụ này thay vì Playwright/Puppeteer?

Blueprint MCP	Playwright/Puppeteer
✅ Trình duyệt thực (không phải không giao diện)	❌ Không giao diện hoặc phiên bản trình duyệt mới
✅ Luôn đăng nhập vào tất cả các trang web của bạn	❌ Phải xác thực lại mỗi phiên
✅ Tránh bị phát hiện là bot (sử dụng dấu vân tay thực)	⚠️ Thường bị phát hiện là trình duyệt tự động
✅ Hoạt động với các tiện ích mở rộng trình duyệt hiện có của bạn	❌ Không hỗ trợ tiện ích mở rộng
✅ Không cần thiết lập - hoạt động ngay lập tức	⚠️ Yêu cầu cài đặt trình duyệt
✅ Hỗ trợ Chrome, Firefox, Edge, Opera	✅ Hỗ trợ Chrome, Firefox, Safari

Cài đặt

1. Cài đặt Máy chủ MCP

npm install -g @railsblueprint/blueprint-mcp

2. Cài đặt Tiện ích mở rộng Trình duyệt

Chọn trình duyệt của bạn:

Chrome / Edge / Opera

Cửa hàng Chrome trực tuyến (hoạt động cho tất cả các trình duyệt Chromium)
Thủ công: Tải xuống từ Bản phát hành, sau đó tải tiện ích chưa đóng gói tại chrome://extensions/ (Chrome), edge://extensions/ (Edge) hoặc opera://extensions/ (Opera)

Firefox

Tiện ích bổ sung Firefox
Thủ công: Tải xuống từ Bản phát hành, sau đó tải tại about:debugging#/runtime/this-firefox

3. Cấu hình máy khách MCP của bạn

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Claude Code (CLI hỗ trợ 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"]
    }
  }
}

Bắt đầu nhanh

Khởi động máy khách MCP của bạn (Claude Desktop, Cursor, v.v.)
Nhấp vào biểu tượng tiện ích mở rộng Blueprint MCP trong trình duyệt của bạn
Tiện ích mở rộng tự động kết nối với máy chủ MCP
Yêu cầu trợ lý AI của bạn duyệt web!

Các cuộc hội thoại ví dụ:

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*

Cách thức hoạt động

┌─────────────────────────┐
│   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)        │
└─────────────────────────┘

Miễn phí vs PRO

Bậc Miễn phí (Mặc định)

✅ Kết nối WebSocket cục bộ (cổng 5555)
✅ Phiên bản trình duyệt đơn
✅ Tất cả các tính năng tự động hóa trình duyệt
✅ Không yêu cầu tài khoản
❌ Giới hạn trong cùng một máy

Bậc PRO

✅ Chuyển tiếp đám mây - kết nối từ bất cứ đâu
✅ Nhiều trình duyệt - điều khiển nhiều phiên bản trình duyệt
✅ Truy cập chia sẻ - nhiều máy khách AI có thể sử dụng cùng một trình duyệt
✅ Tự động kết nối lại - duy trì kết nối qua các thay đổi mạng
✅ Hỗ trợ ưu tiên

Nâng cấp lên PRO

Công cụ có sẵn

Máy chủ MCP cung cấp các công cụ này cho trợ lý AI:

Quản lý Kết nối

enable - Kích hoạt tự động hóa trình duyệt (bước đầu tiên bắt buộc)
disable - Hủy kích hoạt tự động hóa trình duyệt
status - Kiểm tra trạng thái kết nối
auth - Đăng nhập vào tài khoản PRO (cho các tính năng chuyển tiếp đám mây)

Quản lý Tab

browser_tabs - Liệt kê, tạo, gắn vào hoặc đóng các tab trình duyệt

Điều hướng

browser_navigate - Điều hướng đến một URL
browser_navigate_back - Quay lại trong lịch sử

Nội dung & Kiểm tra

browser_snapshot - Lấy nội dung trang có thể truy cập (khuyến nghị để đọc trang)
browser_take_screenshot - Chụp ảnh màn hình trực quan
browser_console_messages - Lấy nhật ký bảng điều khiển trình duyệt
browser_network_requests - Công cụ giám sát và phát lại mạng mạnh mẽ với nhiều hành động:
- Chế độ danh sách (mặc định): Tổng quan nhẹ với lọc và phân trang (mặc định: 20 yêu cầu)
  - Bộ lọc: urlPattern (chuỗi con), method (GET/POST), status (200/404), resourceType (xhr/fetch/script)
  - Phân trang: limit (mặc định: 20), offset (mặc định: 0)
  - Ví dụ: action='list', urlPattern='api/users', method='GET', limit=10
- Chế độ chi tiết: Dữ liệu yêu cầu/phản hồi đầy đủ cho yêu cầu cụ thể bao gồm tiêu đề và nội dung
- Lọc JSONPath: Truy vấn các phản hồi JSON lớn bằng cú pháp JSONPath (ví dụ: $.data.items[0])
- Chế độ phát lại: Thực thi lại các yêu cầu đã chụp với tiêu đề và xác thực gốc
- Chế độ xóa: Xóa lịch sử đã chụp để giải phóng bộ nhớ
- Ví dụ: action='details', requestId='12345.67', jsonPath='$.data.users[0]'
browser_extract_content - Trích xuất nội dung trang dưới dạng markdown

Tương tác

browser_interact - Thực hiện nhiều hành động theo trình tự (nhấp, nhập, di chuột, chờ, v.v.)
browser_click - Nhấp vào các phần tử
browser_type - Nhập văn bản vào các ô nhập liệu
browser_hover - Di chuột qua các phần tử
browser_select_option - Chọn các tùy chọn thả xuống
browser_fill_form - Điền nhiều trường biểu mẫu cùng một lúc
browser_press_key - Nhấn các phím bàn phím
browser_drag - Kéo và thả các phần tử

Nâng cao

browser_evaluate - Thực thi JavaScript trong ngữ cảnh trang
browser_handle_dialog - Xử lý các hộp thoại cảnh báo/xác nhận/nhắc nhở
browser_file_upload - Tải tệp lên thông qua các ô nhập tệp
browser_window - Thay đổi kích thước, thu nhỏ, phóng to cửa sổ trình duyệt
browser_pdf_save - Lưu trang hiện tại dưới dạng PDF
browser_performance_metrics - Lấy các chỉ số hiệu suất
browser_verify_text_visible - Xác minh văn bản có mặt (để kiểm thử)
browser_verify_element_visible - Xác minh phần tử tồn tại (để kiểm thử)

Quản lý Tiện ích mở rộng

browser_list_extensions - Liệt kê các tiện ích mở rộng trình duyệt đã cài đặt
browser_reload_extensions - Tải lại các tiện ích mở rộng chưa đóng gói (hữu ích trong quá trình phát triển)

Phát triển

Điều kiện tiên quyết

Node.js 18+
Một trình duyệt được hỗ trợ (Chrome, Firefox, Edge hoặc Opera)
npm hoặc yarn

Thiết lập

# 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 ../..

Chạy trong quá trình Phát triển

Terminal 1: Khởi động máy chủ MCP ở chế độ gỡ lỗi

cd server
node cli.js --debug

Terminal 2: Xây dựng tiện ích mở rộng Chrome

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

Lưu ý: Tiện ích mở rộng Firefox không yêu cầu bước xây dựng - nó sử dụng JavaScript thuần và có thể được tải trực tiếp từ extensions/firefox/

Tải tiện ích mở rộng trong trình duyệt của bạn:

Đối với trình duyệt Chromium (Chrome, Edge, Opera):

Mở chrome://extensions/ (Chrome), edge://extensions/ (Edge) hoặc opera://extensions/ (Opera)
Bật "Chế độ nhà phát triển"
Nhấp vào "Tải tiện ích chưa đóng gói"
Chọn thư mục extensions/chrome/dist

Đối với Firefox:

Mở about:debugging#/runtime/this-firefox
Nhấp vào "Tải Tiện ích bổ sung Tạm thời"
Chọn bất kỳ tệp nào từ thư mục extensions/firefox

Cấu trúc Dự án

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/

Kiểm thử

# Run tests
npm test

# Run with coverage
npm run test:coverage

Tài liệu:

Quy trình Kiểm thử Thủ công - Hướng dẫn kiểm thử thủ công toàn diện
Đặc tả Tính năng - Tài liệu tính năng đầy đủ
Tiến độ Kiểm thử - Trạng thái bao phủ kiểm thử hiện tại

Cấu hình

Máy chủ hoạt động ngay lập tức với các mặc định hợp lý. Đối với cấu hình nâng cao:

Biến Môi trường

Tạo một tệp .env trong thư mục gốc của dự án:

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

# Local WebSocket port (Free tier)
MCP_PORT=5555

# Debug mode
DEBUG=false

Tùy chọn Dòng lệnh

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

Lưu ý: Nếu bạn thay đổi cổng, bạn sẽ cần cập nhật cài đặt tiện ích mở rộng trình duyệt của mình để khớp.

Khắc phục sự cố

Tiện ích mở rộng không kết nối được

Kiểm tra tiện ích mở rộng đã được cài đặt và kích hoạt chưa
Nhấp vào biểu tượng tiện ích mở rộng - nó sẽ hiển thị "Đã kết nối"
Kiểm tra máy chủ MCP đang chạy (tìm tiến trình trên cổng 5555)
Thử tải lại tiện ích mở rộng

"Cổng 5555 đã được sử dụng"

Một phiên bản khác đang chạy. Bạn có thể:

Kết thúc tiến trình hiện có:

lsof -ti:5555 | xargs kill -9

Sử dụng một cổng khác:

blueprint-mcp --port 8080

Công cụ trình duyệt không hoạt động

Đảm bảo bạn đã gọi enable trước
Kiểm tra bạn đã gắn vào một tab với browser_tabs
Xác minh tab vẫn tồn tại (không bị đóng)

Nhận trợ giúp

Đóng góp

Chúng tôi hoan nghênh các đóng góp! Xem CONTRIBUTING.md để biết hướng dẫn.

Bảo mật

Công cụ này cấp cho trợ lý AI quyền kiểm soát trình duyệt của bạn. Vui lòng xem xét:

Máy chủ MCP chỉ chấp nhận kết nối cục bộ theo mặc định (localhost:5555)
Kết nối chuyển tiếp PRO được xác thực qua OAuth
Tiện ích mở rộng yêu cầu hành động rõ ràng của người dùng để kết nối
Tất cả các hành động trình duyệt đều thông qua hệ thống quyền của trình duyệt

Phát hiện vấn đề bảo mật? Vui lòng gửi email đến [email protected] thay vì nộp một vấn đề công khai.

Tín dụng

Dự án này ban đầu được truyền cảm hứng từ việc triển khai Playwright MCP của Microsoft nhưng đã được viết lại hoàn toàn để sử dụng tự động hóa dựa trên tiện ích mở rộng trình duyệt thay vì Playwright. Kiến trúc, cách triển khai và cách tiếp cận về cơ bản là khác nhau.

Sự khác biệt chính:

Sử dụng tiện ích mở rộng trình duyệt với Giao thức DevTools (không phải Playwright)
Hoạt động với hồ sơ trình duyệt thực (không phải ngữ cảnh cô lập)
Giao tiếp dựa trên WebSocket (không phải chuyển tiếp CDP)
Tùy chọn chuyển tiếp đám mây để truy cập từ xa
Mô hình bậc Miễn phí và PRO
Hỗ trợ đa trình duyệt (Chrome, Firefox, Edge, Opera)

Chúng tôi biết ơn nhóm Playwright đã tiên phong trong tự động hóa trình duyệt qua MCP.

Giấy phép

Giấy phép Apache 2.0 - xem LICENSE

Được xây dựng với ❤️ bởi Rails Blueprint

Trang web • GitHub • NPM