Blueprint MCP Server

resmi

Chrome ve Firefox için MCP üzerinden tarayıcı otomasyonu

GitHub
85

Dokümantasyon

Blueprint MCP

Model Context Protocol aracılığıyla gerçek tarayıcınızı yapay zeka ile kontrol edin

npm version License

Bu nedir?

Yapay zeka asistanlarının bir tarayıcı uzantısı aracılığıyla gerçek tarayıcınızı (Chrome, Firefox veya Opera) kontrol etmesini sağlayan bir MCP (Model Context Protocol) sunucusu. Headless otomasyon araçlarının aksine, bu araç tüm oturum açmış oturumlarınız, çerezleriniz ve uzantılarınızla birlikte gerçek tarayıcı profilinizi kullanır.

Şunlar için mükemmel: Zaten oturum açmış olduğunuz sitelerle etkileşime girmesi gereken veya bot tespitinden kaçınması gereken yapay zeka ajanları.

Neden Playwright/Puppeteer yerine bunu kullanmalısınız?

Blueprint MCPPlaywright/Puppeteer
✅ Gerçek tarayıcı (headless değil)❌ Headless veya yeni tarayıcı örneği
✅ Tüm sitelerinizde oturum açık kalır❌ Her oturumda yeniden kimlik doğrulaması gerekir
✅ Bot tespitinden kaçınır (gerçek parmak izi kullanır)⚠️ Genellikle otomatik tarayıcı olarak algılanır
✅ Mevcut tarayıcı uzantılarınızla çalışır❌ Uzantı desteği yok
✅ Sıfır kurulum - kutudan çıktığı gibi çalışır⚠️ Tarayıcı kurulumu gerektirir
✅ Chrome, Firefox, Edge, Opera desteği✅ Chrome, Firefox, Safari desteği

Kurulum

1. MCP Sunucusunu Kurun

npm install -g @railsblueprint/blueprint-mcp

2. Tarayıcı Uzantısını Kurun

Tarayıcınızı seçin:

Chrome / Edge / Opera

  • Chrome Web Mağazası (tüm Chromium tarayıcıları için çalışır)
  • Manuel: Sürümler sayfasından indirin, ardından chrome://extensions/ (Chrome), edge://extensions/ (Edge) veya opera://extensions/ (Opera) adresinde paketlenmemiş olarak yükleyin

Firefox

3. MCP istemcinizi yapılandırın

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

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

Claude Code (Yapay zeka destekli 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"]
    }
  }
}

Hızlı Başlangıç

  1. MCP istemcinizi başlatın (Claude Desktop, Cursor, vb.)
  2. Tarayıcınızda Blueprint MCP uzantı simgesine tıklayın
  3. Uzantı, MCP sunucusuna otomatik olarak bağlanır
  4. Yapay zeka asistanınızdan göz atmasını isteyin!

Örnek konuşmalar:

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*

Nasıl çalışır

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

Ücretsiz vs PRO

Ücretsiz Katman (Varsayılan)

  • ✅ Yerel WebSocket bağlantısı (port 5555)
  • ✅ Tek tarayıcı örneği
  • ✅ Tüm tarayıcı otomasyon özellikleri
  • ✅ Hesap gerekmez
  • ❌ Aynı makineyle sınırlıdır

PRO Katman

  • ✅ Bulut geçişi - her yerden bağlanın
  • ✅ Çoklu tarayıcı - birden fazla tarayıcı örneğini kontrol edin
  • ✅ Paylaşımlı erişim - birden fazla yapay zeka istemcisi aynı tarayıcıyı kullanabilir
  • ✅ Otomatik yeniden bağlanma - ağ değişikliklerinde bağlantıyı korur
  • ✅ Öncelikli destek

PRO'ya yükseltin

Mevcut Araçlar

MCP sunucusu, yapay zeka asistanlarına şu araçları sağlar:

Bağlantı Yönetimi

  • enable - Tarayıcı otomasyonunu etkinleştir (gerekli ilk adım)
  • disable - Tarayıcı otomasyonunu devre dışı bırak
  • status - Bağlantı durumunu kontrol et
  • auth - PRO hesabına giriş yap (bulut geçişi özellikleri için)

Sekme Yönetimi

  • browser_tabs - Tarayıcı sekmelerini listele, oluştur, ekle veya kapat

Navigasyon

  • browser_navigate - Bir URL'ye git
  • browser_navigate_back - Geçmişte geri git

İçerik ve İnceleme

  • browser_snapshot - Erişilebilir sayfa içeriğini al (sayfaları okumak için önerilir)
  • browser_take_screenshot - Görsel ekran görüntüsü yakala
  • browser_console_messages - Tarayıcı konsol günlüklerini al
  • browser_network_requests - Birden fazla eylem içeren güçlü ağ izleme ve tekrar oynatma aracı:
    • Liste modu (varsayılan): Filtreleme ve sayfalama ile hafif genel bakış (varsayılan: 20 istek)
      • Filtreler: urlPattern (alt dize), method (GET/POST), status (200/404), resourceType (xhr/fetch/script)
      • Sayfalama: limit (varsayılan: 20), offset (varsayılan: 0)
      • Örnek: action='list', urlPattern='api/users', method='GET', limit=10
    • Detay modu: Başlıklar ve gövdeler dahil olmak üzere belirli istek için tam istek/yanıt verileri
    • JSONPath filtreleme: JSONPath sözdizimini kullanarak büyük JSON yanıtlarını sorgulayın (örn. $.data.items[0])
    • Tekrar oynatma modu: Orijinal başlıklar ve kimlik doğrulama ile yakalanan istekleri yeniden yürütün
    • Temizleme modu: Belleği boşaltmak için yakalanan geçmişi temizleyin
    • Örnek: action='details', requestId='12345.67', jsonPath='$.data.users[0]'
  • browser_extract_content - Sayfa içeriğini markdown olarak çıkar

Etkileşim

  • browser_interact - Sırayla birden fazla eylem gerçekleştir (tıklama, yazma, üzerine gelme, bekleme, vb.)
  • browser_click - Öğelere tıkla
  • browser_type - Giriş alanlarına metin yaz
  • browser_hover - Öğelerin üzerine gel
  • browser_select_option - Açılır menü seçeneklerini seç
  • browser_fill_form - Birden fazla form alanını aynı anda doldur
  • browser_press_key - Klavye tuşlarına bas
  • browser_drag - Öğeleri sürükle ve bırak

Gelişmiş

  • browser_evaluate - Sayfa bağlamında JavaScript çalıştır
  • browser_handle_dialog - Uyarı/onayla/bilgi istemi diyaloglarını yönet
  • browser_file_upload - Dosya girişleri aracılığıyla dosya yükle
  • browser_window - Tarayıcı penceresini yeniden boyutlandır, küçült, büyüt
  • browser_pdf_save - Geçerli sayfayı PDF olarak kaydet
  • browser_performance_metrics - Performans metriklerini al
  • browser_verify_text_visible - Metnin mevcut olduğunu doğrula (test için)
  • browser_verify_element_visible - Öğenin var olduğunu doğrula (test için)

Uzantı Yönetimi

  • browser_list_extensions - Yüklü tarayıcı uzantılarını listele
  • browser_reload_extensions - Paketlenmemiş uzantıları yeniden yükle (geliştirme sırasında kullanışlıdır)

Geliştirme

Ön Koşullar

  • Node.js 18+
  • Desteklenen bir tarayıcı (Chrome, Firefox, Edge veya Opera)
  • npm veya yarn

Kurulum

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

Geliştirme Modunda Çalıştırma

Terminal 1: MCP sunucusunu hata ayıklama modunda başlat

cd server
node cli.js --debug

Terminal 2: Chrome uzantısını oluştur

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

Not: Firefox uzantısı bir derleme adımı gerektirmez - vanilla JavaScript kullanır ve doğrudan extensions/firefox/ konumundan yüklenebilir

Uzantıyı tarayıcınıza yükleyin:

Chromium tarayıcıları için (Chrome, Edge, Opera):

  1. chrome://extensions/ (Chrome), edge://extensions/ (Edge) veya opera://extensions/ (Opera) adresini açın
  2. "Geliştirici modu"nu etkinleştirin
  3. "Paketlenmemiş öğe yükle"ye tıklayın
  4. extensions/chrome/dist klasörünü seçin

Firefox için:

  1. about:debugging#/runtime/this-firefox adresini açın
  2. "Geçici Eklenti Yükle"ye tıklayın
  3. extensions/firefox klasöründen herhangi bir dosya seçin

Proje Yapısı

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/

Test

# Run tests
npm test

# Run with coverage
npm run test:coverage

Dokümantasyon:

Yapılandırma

Sunucu, makul varsayılanlarla kutudan çıktığı gibi çalışır. Gelişmiş yapılandırma için:

Ortam Değişkenleri

Proje kökünde bir .env dosyası oluşturun:

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

# Local WebSocket port (Free tier)
MCP_PORT=5555

# Debug mode
DEBUG=false

Komut Satırı Seçenekleri

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

Not: Portu değiştirirseniz, eşleşmesi için tarayıcı uzantı ayarlarınızı güncellemeniz gerekir.

Sorun Giderme

Uzantı bağlanmıyor

  1. Uzantının yüklü ve etkin olduğunu kontrol edin
  2. Uzantı simgesine tıklayın - "Bağlandı" göstermelidir
  3. MCP sunucusunun çalıştığını kontrol edin (port 5555'te işlem arayın)
  4. Uzantıyı yeniden yüklemeyi deneyin

"Port 5555 zaten kullanımda"

Başka bir örnek çalışıyor. Şunları yapabilirsiniz:

  1. Mevcut işlemi sonlandırın:
lsof -ti:5555 | xargs kill -9
  1. Farklı bir port kullanın:
blueprint-mcp --port 8080

Tarayıcı araçları çalışmıyor

  1. Önce enable çağırdığınızdan emin olun
  2. browser_tabs ile bir sekmeye bağlandığınızı kontrol edin
  3. Sekmenin hala var olduğunu doğrulayın (kapatılmadı)

Yardım alma

Katkıda Bulunma

Katkıları memnuniyetle karşılıyoruz! Yönergeler için CONTRIBUTING.md dosyasına bakın.

Güvenlik

Bu araç, yapay zeka asistanlarına tarayıcınız üzerinde kontrol verir. Lütfen inceleyin:

  • MCP sunucusu varsayılan olarak yalnızca yerel bağlantıları kabul eder (localhost:5555)
  • PRO geçiş bağlantıları OAuth ile doğrulanır
  • Uzantı, bağlanmak için açık kullanıcı eylemi gerektirir
  • Tüm tarayıcı eylemleri tarayıcının izin sisteminden geçer

Bir güvenlik sorunu mu buldunuz? Lütfen herkese açık bir sorun bildirmek yerine [email protected] adresine e-posta gönderin.

Katkıda Bulunanlar

Bu proje orijinal olarak Microsoft'un Playwright MCP uygulamasından ilham almıştır ancak Playwright yerine tarayıcı uzantısı tabanlı otomasyon kullanmak için tamamen yeniden yazılmıştır. Mimari, uygulama ve yaklaşım temelde farklıdır.

Temel farklar:

  • Playwright değil, DevTools Protokolü ile tarayıcı uzantıları kullanır
  • Yalıtılmış bağlamlar değil, gerçek tarayıcı profilleriyle çalışır
  • CDP geçişi değil, WebSocket tabanlı iletişim
  • Uzaktan erişim için bulut geçişi seçeneği
  • Ücretsiz ve PRO katman modeli
  • Çoklu tarayıcı desteği (Chrome, Firefox, Edge, Opera)

MCP aracılığıyla tarayıcı otomasyonuna öncülük ettikleri için Playwright ekibine minnettarız.

Lisans

Apache License 2.0 - bkz. LICENSE

Telif Hakkı (c) 2025 Rails Blueprint

❤️ ile Rails Blueprint tarafından geliştirildi

Web Sitesi • GitHub • NPM