Blueprint MCP Server

officiel

Automatisation de navigateur via MCP pour Chrome et Firefox

GitHub
85

Documentation

Blueprint MCP

Contrôlez votre véritable navigateur avec l'IA via le Model Context Protocol

npm version License

Qu'est-ce que c'est ?

Un serveur MCP (Model Context Protocol) qui permet aux assistants IA de contrôler votre navigateur réel (Chrome, Firefox ou Opera) via une extension de navigateur. Contrairement aux outils d'automatisation sans tête, il utilise votre véritable profil de navigateur avec toutes vos sessions connectées, cookies et extensions intacts.

Parfait pour : les agents IA qui ont besoin d'interagir avec des sites où vous êtes déjà connecté, ou qui doivent éviter la détection de bots.

Pourquoi utiliser ceci plutôt que Playwright/Puppeteer ?

Blueprint MCPPlaywright/Puppeteer
✅ Véritable navigateur (pas sans tête)❌ Sans tête ou nouvelle instance de navigateur
✅ Reste connecté à tous vos sites❌ Doit se ré-authentifier à chaque session
✅ Évite la détection de bots (utilise une empreinte réelle)⚠️ Souvent détecté comme navigateur automatisé
✅ Fonctionne avec vos extensions de navigateur existantes❌ Pas de support d'extension
✅ Zéro configuration - fonctionne immédiatement⚠️ Nécessite l'installation du navigateur
✅ Support Chrome, Firefox, Edge, Opera✅ Support Chrome, Firefox, Safari

Installation

1. Installer le serveur MCP

npm install -g @railsblueprint/blueprint-mcp

2. Installer l'extension de navigateur

Choisissez votre navigateur :

Chrome / Edge / Opera

  • Chrome Web Store (fonctionne pour tous les navigateurs Chromium)
  • Manuel : Télécharger depuis Releases, puis charger l'extension non empaquetée sur chrome://extensions/ (Chrome), edge://extensions/ (Edge), ou opera://extensions/ (Opera)

Firefox

3. Configurer votre client MCP

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

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

Claude Code (CLI alimentée par IA) :

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"]
    }
  }
}

Démarrage rapide

  1. Démarrez votre client MCP (Claude Desktop, Cursor, etc.)
  2. Cliquez sur l'icône de l'extension Blueprint MCP dans votre navigateur
  3. L'extension se connecte automatiquement au serveur MCP
  4. Demandez à votre assistant IA de naviguer !

Exemples de conversations :

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*

Comment ça fonctionne

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

Gratuit vs PRO

Niveau gratuit (par défaut)

  • ✅ Connexion WebSocket locale (port 5555)
  • ✅ Instance de navigateur unique
  • ✅ Toutes les fonctionnalités d'automatisation du navigateur
  • ✅ Aucun compte requis
  • ❌ Limité à la même machine

Niveau PRO

  • ✅ Relais cloud - connectez-vous de n'importe où
  • ✅ Navigateurs multiples - contrôlez plusieurs instances de navigateur
  • ✅ Accès partagé - plusieurs clients IA peuvent utiliser le même navigateur
  • ✅ Reconnexion automatique - maintient la connexion à travers les changements de réseau
  • ✅ Support prioritaire

Passer à PRO

Outils disponibles

Le serveur MCP fournit ces outils aux assistants IA :

Gestion de la connexion

  • enable - Activer l'automatisation du navigateur (première étape requise)
  • disable - Désactiver l'automatisation du navigateur
  • status - Vérifier l'état de la connexion
  • auth - Se connecter au compte PRO (pour les fonctionnalités de relais cloud)

Gestion des onglets

  • browser_tabs - Lister, créer, attacher ou fermer des onglets du navigateur

Navigation

  • browser_navigate - Naviguer vers une URL
  • browser_navigate_back - Reculer dans l'historique

Contenu et inspection

  • browser_snapshot - Obtenir le contenu accessible de la page (recommandé pour lire les pages)
  • browser_take_screenshot - Capturer une capture d'écran visuelle
  • browser_console_messages - Obtenir les journaux de la console du navigateur
  • browser_network_requests - Outil puissant de surveillance et de relecture réseau avec plusieurs actions :
    • Mode liste (par défaut) : Aperçu léger avec filtrage et pagination (par défaut : 20 requêtes)
      • Filtres : urlPattern (sous-chaîne), method (GET/POST), status (200/404), resourceType (xhr/fetch/script)
      • Pagination : limit (par défaut : 20), offset (par défaut : 0)
      • Exemple : action='list', urlPattern='api/users', method='GET', limit=10
    • Mode détails : Données complètes de requête/réponse pour une requête spécifique, y compris les en-têtes et les corps
    • Filtrage JSONPath : Interroger de grandes réponses JSON en utilisant la syntaxe JSONPath (par exemple, $.data.items[0])
    • Mode relecture : Ré-exécuter les requêtes capturées avec les en-têtes et l'authentification d'origine
    • Mode effacement : Effacer l'historique capturé pour libérer de la mémoire
    • Exemple : action='details', requestId='12345.67', jsonPath='$.data.users[0]'
  • browser_extract_content - Extraire le contenu de la page en markdown

Interaction

  • browser_interact - Effectuer plusieurs actions en séquence (clic, saisie, survol, attente, etc.)
  • browser_click - Cliquer sur des éléments
  • browser_type - Saisir du texte dans les champs
  • browser_hover - Survoler des éléments
  • browser_select_option - Sélectionner des options de liste déroulante
  • browser_fill_form - Remplir plusieurs champs de formulaire à la fois
  • browser_press_key - Appuyer sur des touches du clavier
  • browser_drag - Glisser-déposer des éléments

Avancé

  • browser_evaluate - Exécuter du JavaScript dans le contexte de la page
  • browser_handle_dialog - Gérer les boîtes de dialogue alert/confirm/prompt
  • browser_file_upload - Télécharger des fichiers via les champs de fichier
  • browser_window - Redimensionner, minimiser, maximiser la fenêtre du navigateur
  • browser_pdf_save - Enregistrer la page actuelle en PDF
  • browser_performance_metrics - Obtenir les métriques de performance
  • browser_verify_text_visible - Vérifier la présence de texte (pour les tests)
  • browser_verify_element_visible - Vérifier l'existence d'un élément (pour les tests)

Gestion des extensions

  • browser_list_extensions - Lister les extensions de navigateur installées
  • browser_reload_extensions - Recharger les extensions non empaquetées (utile pendant le développement)

Développement

Prérequis

  • Node.js 18+
  • Un navigateur supporté (Chrome, Firefox, Edge ou Opera)
  • npm ou yarn

Configuration

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

Exécution en développement

Terminal 1 : Démarrer le serveur MCP en mode débogage

cd server
node cli.js --debug

Terminal 2 : Construire l'extension Chrome

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

Remarque : L'extension Firefox ne nécessite pas d'étape de construction - elle utilise du JavaScript vanilla et peut être chargée directement depuis extensions/firefox/

Charger l'extension dans votre navigateur :

Pour les navigateurs Chromium (Chrome, Edge, Opera) :

  1. Ouvrir chrome://extensions/ (Chrome), edge://extensions/ (Edge), ou opera://extensions/ (Opera)
  2. Activer le "Mode développeur"
  3. Cliquer sur "Charger l'extension non empaquetée"
  4. Sélectionner le dossier extensions/chrome/dist

Pour Firefox :

  1. Ouvrir about:debugging#/runtime/this-firefox
  2. Cliquer sur "Charger un module complémentaire temporaire"
  3. Sélectionner n'importe quel fichier du dossier extensions/firefox

Structure du projet

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/

Tests

# Run tests
npm test

# Run with coverage
npm run test:coverage

Documentation :

Configuration

Le serveur fonctionne immédiatement avec des valeurs par défaut sensées. Pour une configuration avancée :

Variables d'environnement

Créez un fichier .env à la racine du projet :

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

# Local WebSocket port (Free tier)
MCP_PORT=5555

# Debug mode
DEBUG=false

Options de ligne de commande

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

Remarque : Si vous changez le port, vous devrez mettre à jour les paramètres de votre extension de navigateur en conséquence.

Dépannage

L'extension ne se connecte pas

  1. Vérifiez que l'extension est installée et activée
  2. Cliquez sur l'icône de l'extension - elle devrait afficher "Connecté"
  3. Vérifiez que le serveur MCP est en cours d'exécution (recherchez le processus sur le port 5555)
  4. Essayez de recharger l'extension

"Le port 5555 est déjà utilisé"

Une autre instance est en cours d'exécution. Vous pouvez soit :

  1. Tuer le processus existant :
lsof -ti:5555 | xargs kill -9
  1. Utiliser un port différent :
blueprint-mcp --port 8080

Les outils du navigateur ne fonctionnent pas

  1. Assurez-vous d'avoir d'abord appelé enable
  2. Vérifiez que vous êtes attaché à un onglet avec browser_tabs
  3. Vérifiez que l'onglet existe toujours (n'a pas été fermé)

Obtenir de l'aide

Contribuer

Nous accueillons les contributions ! Voir CONTRIBUTING.md pour les directives.

Sécurité

Cet outil donne aux assistants IA le contrôle de votre navigateur. Veuillez examiner :

  • Le serveur MCP n'accepte que les connexions locales par défaut (localhost:5555)
  • Les connexions relais PRO sont authentifiées via OAuth
  • L'extension nécessite une action explicite de l'utilisateur pour se connecter
  • Toutes les actions du navigateur passent par le système de permissions du navigateur

Vous avez trouvé un problème de sécurité ? Veuillez envoyer un e-mail à [email protected] au lieu de déposer un problème public.

Crédits

Ce projet a été initialement inspiré par l'implémentation Playwright MCP de Microsoft mais a été complètement réécrit pour utiliser l'automatisation basée sur les extensions de navigateur au lieu de Playwright. L'architecture, l'implémentation et l'approche sont fondamentalement différentes.

Différences clés :

  • Utilise les extensions de navigateur avec le protocole DevTools (pas Playwright)
  • Fonctionne avec de véritables profils de navigateur (pas des contextes isolés)
  • Communication basée sur WebSocket (pas de relais CDP)
  • Option de relais cloud pour l'accès à distance
  • Modèle gratuit et PRO
  • Support multi-navigateur (Chrome, Firefox, Edge, Opera)

Nous sommes reconnaissants à l'équipe Playwright d'avoir été les pionniers de l'automatisation du navigateur via MCP.

Licence

Licence Apache 2.0 - voir LICENSE

Copyright (c) 2025 Rails Blueprint

Construit avec ❤️ par Rails Blueprint

Site Web • GitHub • NPM