Blueprint MCP Server

resmi

Otomatisasi peramban melalui MCP untuk Chrome dan Firefox

GitHub
84

Dokumentasi

Blueprint MCP

Kendalikan peramban nyata Anda dengan AI melalui Model Context Protocol

npm version License

Apa ini?

Sebuah server MCP (Model Context Protocol) yang memungkinkan asisten AI mengendalikan peramban nyata Anda (Chrome, Firefox, atau Opera) melalui ekstensi peramban. Tidak seperti alat otomatisasi headless, ini menggunakan profil peramban asli Anda dengan semua sesi yang masuk, cookie, dan ekstensi tetap utuh.

Sempurna untuk: Agen AI yang perlu berinteraksi dengan situs di mana Anda sudah masuk, atau yang perlu menghindari deteksi bot.

Mengapa menggunakan ini daripada Playwright/Puppeteer?

Blueprint MCPPlaywright/Puppeteer
✅ Peramban nyata (bukan headless)❌ Headless atau instans peramban baru
✅ Tetap masuk ke semua situs Anda❌ Harus otentikasi ulang setiap sesi
✅ Menghindari deteksi bot (menggunakan sidik jari asli)⚠️ Sering terdeteksi sebagai peramban otomatis
✅ Bekerja dengan ekstensi peramban yang ada❌ Tidak ada dukungan ekstensi
✅ Tanpa penyiapan - langsung berfungsi⚠️ Memerlukan instalasi peramban
✅ Dukungan Chrome, Firefox, Edge, Opera✅ Dukungan Chrome, Firefox, Safari

Instalasi

1. Instal Server MCP

npm install -g @railsblueprint/blueprint-mcp

2. Instal Ekstensi Peramban

Pilih peramban Anda:

Chrome / Edge / Opera

  • Chrome Web Store (berfungsi untuk semua peramban Chromium)
  • Manual: Unduh dari Releases, lalu muat tanpa paket di chrome://extensions/ (Chrome), edge://extensions/ (Edge), atau opera://extensions/ (Opera)

Firefox

3. Konfigurasikan klien MCP Anda

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

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

Claude Code (CLI bertenaga 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"]
    }
  }
}

Mulai Cepat

  1. Mulai klien MCP Anda (Claude Desktop, Cursor, dll.)
  2. Klik ikon ekstensi Blueprint MCP di peramban Anda
  3. Ekstensi otomatis terhubung ke server MCP
  4. Minta asisten AI Anda untuk menjelajah!

Contoh percakapan:

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*

Cara Kerja

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

Gratis vs PRO

Tingkat Gratis (Default)

  • ✅ Koneksi WebSocket lokal (port 5555)
  • ✅ Instans peramban tunggal
  • ✅ Semua fitur otomatisasi peramban
  • ✅ Tidak perlu akun
  • ❌ Terbatas pada mesin yang sama

Tingkat PRO

  • ✅ Relai cloud - terhubung dari mana saja
  • ✅ Beberapa peramban - kendalikan beberapa instans peramban
  • ✅ Akses bersama - beberapa klien AI dapat menggunakan peramban yang sama
  • ✅ Sambung ulang otomatis - mempertahankan koneksi melalui perubahan jaringan
  • ✅ Dukungan prioritas

Upgrade ke PRO

Alat yang Tersedia

Server MCP menyediakan alat-alat ini untuk asisten AI:

Manajemen Koneksi

  • enable - Aktifkan otomatisasi peramban (langkah pertama yang diperlukan)
  • disable - Nonaktifkan otomatisasi peramban
  • status - Periksa status koneksi
  • auth - Masuk ke akun PRO (untuk fitur relai cloud)

Manajemen Tab

  • browser_tabs - Daftar, buat, lampirkan ke, atau tutup tab peramban

Navigasi

  • browser_navigate - Navigasi ke URL
  • browser_navigate_back - Kembali dalam riwayat

Konten & Inspeksi

  • browser_snapshot - Dapatkan konten halaman yang dapat diakses (disarankan untuk membaca halaman)
  • browser_take_screenshot - Ambil tangkapan layar visual
  • browser_console_messages - Dapatkan log konsol peramban
  • browser_network_requests - Alat pemantauan dan pemutaran ulang jaringan yang kuat dengan beberapa tindakan:
    • Mode daftar (default): Ikhtisar ringan dengan penyaringan dan paginasi (default: 20 permintaan)
      • Filter: urlPattern (substring), method (GET/POST), status (200/404), resourceType (xhr/fetch/script)
      • Paginasi: limit (default: 20), offset (default: 0)
      • Contoh: action='list', urlPattern='api/users', method='GET', limit=10
    • Mode detail: Data permintaan/respons lengkap untuk permintaan tertentu termasuk header dan body
    • Penyaringan JSONPath: Kueri respons JSON besar menggunakan sintaks JSONPath (mis., $.data.items[0])
    • Mode pemutaran ulang: Jalankan kembali permintaan yang ditangkap dengan header dan otentikasi asli
    • Mode hapus: Hapus riwayat yang ditangkap untuk membebaskan memori
    • Contoh: action='details', requestId='12345.67', jsonPath='$.data.users[0]'
  • browser_extract_content - Ekstrak konten halaman sebagai markdown

Interaksi

  • browser_interact - Lakukan beberapa tindakan secara berurutan (klik, ketik, arahkan, tunggu, dll.)
  • browser_click - Klik pada elemen
  • browser_type - Ketik teks ke dalam input
  • browser_hover - Arahkan kursor ke elemen
  • browser_select_option - Pilih opsi dropdown
  • browser_fill_form - Isi beberapa bidang formulir sekaligus
  • browser_press_key - Tekan tombol keyboard
  • browser_drag - Seret dan lepas elemen

Lanjutan

  • browser_evaluate - Jalankan JavaScript dalam konteks halaman
  • browser_handle_dialog - Tangani dialog alert/confirm/prompt
  • browser_file_upload - Unggah file melalui input file
  • browser_window - Ubah ukuran, minimalkan, maksimalkan jendela peramban
  • browser_pdf_save - Simpan halaman saat ini sebagai PDF
  • browser_performance_metrics - Dapatkan metrik kinerja
  • browser_verify_text_visible - Verifikasi teks ada (untuk pengujian)
  • browser_verify_element_visible - Verifikasi elemen ada (untuk pengujian)

Manajemen Ekstensi

  • browser_list_extensions - Daftar ekstensi peramban yang terinstal
  • browser_reload_extensions - Muat ulang ekstensi tanpa paket (berguna selama pengembangan)

Pengembangan

Prasyarat

  • Node.js 18+
  • Peramban yang didukung (Chrome, Firefox, Edge, atau Opera)
  • npm atau yarn

Penyiapan

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

Menjalankan dalam Pengembangan

Terminal 1: Mulai server MCP dalam mode debug

cd server
node cli.js --debug

Terminal 2: Bangun ekstensi Chrome

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

Catatan: Ekstensi Firefox tidak memerlukan langkah build - ia menggunakan JavaScript vanilla dan dapat dimuat langsung dari extensions/firefox/

Muat ekstensi di peramban Anda:

Untuk peramban Chromium (Chrome, Edge, Opera):

  1. Buka chrome://extensions/ (Chrome), edge://extensions/ (Edge), atau opera://extensions/ (Opera)
  2. Aktifkan "Mode pengembang"
  3. Klik "Muat tanpa paket"
  4. Pilih folder extensions/chrome/dist

Untuk Firefox:

  1. Buka about:debugging#/runtime/this-firefox
  2. Klik "Muat Add-on Sementara"
  3. Pilih file apa pun dari folder extensions/firefox

Struktur Proyek

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/

Pengujian

# Run tests
npm test

# Run with coverage
npm run test:coverage

Dokumentasi:

Konfigurasi

Server berfungsi langsung dengan default yang masuk akal. Untuk konfigurasi lanjutan:

Variabel Lingkungan

Buat file .env di root proyek:

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

# Local WebSocket port (Free tier)
MCP_PORT=5555

# Debug mode
DEBUG=false

Opsi Baris Perintah

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

Catatan: Jika Anda mengubah port, Anda perlu memperbarui pengaturan ekstensi peramban Anda agar cocok.

Pemecahan Masalah

Ekstensi tidak dapat terhubung

  1. Periksa ekstensi terinstal dan diaktifkan
  2. Klik ikon ekstensi - seharusnya menunjukkan "Terhubung"
  3. Periksa server MCP berjalan (cari proses pada port 5555)
  4. Coba muat ulang ekstensi

"Port 5555 sudah digunakan"

Instans lain sedang berjalan. Anda dapat:

  1. Hentikan proses yang ada:
lsof -ti:5555 | xargs kill -9
  1. Gunakan port yang berbeda:
blueprint-mcp --port 8080

Alat peramban tidak berfungsi

  1. Pastikan Anda telah memanggil enable terlebih dahulu
  2. Periksa Anda telah melampirkan ke tab dengan browser_tabs
  3. Verifikasi tab masih ada (tidak ditutup)

Mendapatkan bantuan

Berkontribusi

Kami menyambut kontribusi! Lihat CONTRIBUTING.md untuk panduan.

Keamanan

Alat ini memberikan asisten AI kendali atas peramban Anda. Harap tinjau:

  • Server MCP hanya menerima koneksi lokal secara default (localhost:5555)
  • Koneksi relai PRO diautentikasi melalui OAuth
  • Ekstensi memerlukan tindakan pengguna eksplisit untuk terhubung
  • Semua tindakan peramban melalui sistem izin peramban

Menemukan masalah keamanan? Silakan email [email protected] alih-alih mengajukan isu publik.

Kredit

Proyek ini awalnya terinspirasi oleh implementasi Playwright MCP Microsoft tetapi telah sepenuhnya ditulis ulang untuk menggunakan otomatisasi berbasis ekstensi peramban alih-alih Playwright. Arsitektur, implementasi, dan pendekatannya secara fundamental berbeda.

Perbedaan utama:

  • Menggunakan ekstensi peramban dengan DevTools Protocol (bukan Playwright)
  • Bekerja dengan profil peramban nyata (bukan konteks terisolasi)
  • Komunikasi berbasis WebSocket (bukan relai CDP)
  • Opsi relai cloud untuk akses jarak jauh
  • Model tingkat Gratis dan PRO
  • Dukungan multi-peramban (Chrome, Firefox, Edge, Opera)

Kami berterima kasih kepada tim Playwright yang telah memelopori otomatisasi peramban melalui MCP.

Lisensi

Apache License 2.0 - lihat LICENSE

Hak Cipta (c) 2025 Rails Blueprint

Dibangun dengan ❤️ oleh Rails Blueprint

Situs Web • GitHub • NPM