Blueprint MCP Server

oficial

Automação de navegador via MCP para Chrome e Firefox

Documentação

Blueprint MCP

Controle seu navegador real com IA através do Model Context Protocol

O que é isso?

Um servidor MCP (Model Context Protocol) que permite que assistentes de IA controlem seu navegador real (Chrome, Firefox ou Opera) através de uma extensão de navegador. Diferente de ferramentas de automação headless, esta usa seu perfil de navegador real com todas as suas sessões logadas, cookies e extensões intactos.

Perfeito para: Agentes de IA que precisam interagir com sites onde você já está logado, ou que precisam evitar detecção de bots.

Por que usar isso em vez do Playwright/Puppeteer?

Blueprint MCP	Playwright/Puppeteer
✅ Navegador real (não headless)	❌ Headless ou nova instância do navegador
✅ Permanece logado em todos os seus sites	❌ Deve reautenticar a cada sessão
✅ Evita detecção de bots (usa impressão digital real)	⚠️ Frequentemente detectado como navegador automatizado
✅ Funciona com suas extensões de navegador existentes	❌ Sem suporte a extensões
✅ Configuração zero - funciona imediatamente	⚠️ Requer instalação do navegador
✅ Suporte a Chrome, Firefox, Edge, Opera	✅ Suporte a Chrome, Firefox, Safari

Instalação

1. Instale o Servidor MCP

npm install -g @railsblueprint/blueprint-mcp

2. Instale a Extensão do Navegador

Escolha seu navegador:

Chrome / Edge / Opera

Chrome Web Store (funciona para todos os navegadores Chromium)
Manual: Baixe de Releases, depois carregue descompactado em chrome://extensions/ (Chrome), edge://extensions/ (Edge) ou opera://extensions/ (Opera)

Firefox

Firefox Add-ons
Manual: Baixe de Releases, depois carregue em about:debugging#/runtime/this-firefox

3. Configure seu cliente MCP

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

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

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

Início Rápido

Inicie seu cliente MCP (Claude Desktop, Cursor, etc.)
Clique no ícone da extensão Blueprint MCP no seu navegador
A extensão conecta-se automaticamente ao servidor MCP
Peça ao seu assistente de IA para navegar!

Exemplos de conversas:

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*

Como funciona

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

Gratuito vs PRO

Plano Gratuito (Padrão)

✅ Conexão WebSocket local (porta 5555)
✅ Instância única de navegador
✅ Todos os recursos de automação do navegador
✅ Sem necessidade de conta
❌ Limitado à mesma máquina

Plano PRO

✅ Retransmissão em nuvem - conecte-se de qualquer lugar
✅ Múltiplos navegadores - controle múltiplas instâncias de navegador
✅ Acesso compartilhado - múltiplos clientes de IA podem usar o mesmo navegador
✅ Reconexão automática - mantém a conexão através de mudanças de rede
✅ Suporte prioritário

Atualizar para PRO

Ferramentas Disponíveis

O servidor MCP fornece estas ferramentas aos assistentes de IA:

Gerenciamento de Conexão

enable - Ativar automação do navegador (primeiro passo necessário)
disable - Desativar automação do navegador
status - Verificar status da conexão
auth - Fazer login na conta PRO (para recursos de retransmissão em nuvem)

Gerenciamento de Abas

browser_tabs - Listar, criar, anexar ou fechar abas do navegador

Navegação

browser_navigate - Navegar para uma URL
browser_navigate_back - Voltar no histórico

Conteúdo e Inspeção

browser_snapshot - Obter conteúdo acessível da página (recomendado para ler páginas)
browser_take_screenshot - Capturar captura de tela visual
browser_console_messages - Obter logs do console do navegador
browser_network_requests - Ferramenta poderosa de monitoramento e repetição de rede com múltiplas ações:
- Modo lista (padrão): Visão geral leve com filtragem e paginação (padrão: 20 requisições)
  - Filtros: urlPattern (substring), method (GET/POST), status (200/404), resourceType (xhr/fetch/script)
  - Paginação: limit (padrão: 20), offset (padrão: 0)
  - Exemplo: action='list', urlPattern='api/users', method='GET', limit=10
- Modo detalhes: Dados completos de requisição/resposta para requisição específica, incluindo cabeçalhos e corpos
- Filtragem JSONPath: Consultar grandes respostas JSON usando sintaxe JSONPath (ex., $.data.items[0])
- Modo repetição: Reexecutar requisições capturadas com cabeçalhos e autenticação originais
- Modo limpar: Limpar histórico capturado para liberar memória
- Exemplo: action='details', requestId='12345.67', jsonPath='$.data.users[0]'
browser_extract_content - Extrair conteúdo da página como markdown

Interação

browser_interact - Realizar múltiplas ações em sequência (clicar, digitar, passar o mouse, esperar, etc.)
browser_click - Clicar em elementos
browser_type - Digitar texto em campos de entrada
browser_hover - Passar o mouse sobre elementos
browser_select_option - Selecionar opções de dropdown
browser_fill_form - Preencher múltiplos campos de formulário de uma vez
browser_press_key - Pressionar teclas do teclado
browser_drag - Arrastar e soltar elementos

Avançado

browser_evaluate - Executar JavaScript no contexto da página
browser_handle_dialog - Lidar com diálogos de alerta/confirmação/prompt
browser_file_upload - Enviar arquivos através de campos de entrada de arquivo
browser_window - Redimensionar, minimizar, maximizar janela do navegador
browser_pdf_save - Salvar página atual como PDF
browser_performance_metrics - Obter métricas de desempenho
browser_verify_text_visible - Verificar se texto está presente (para testes)
browser_verify_element_visible - Verificar se elemento existe (para testes)

Gerenciamento de Extensões

browser_list_extensions - Listar extensões de navegador instaladas
browser_reload_extensions - Recarregar extensões descompactadas (útil durante o desenvolvimento)

Desenvolvimento

Pré-requisitos

Node.js 18+
Um navegador suportado (Chrome, Firefox, Edge ou Opera)
npm ou yarn

Configuração

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

Executando em Desenvolvimento

Terminal 1: Iniciar servidor MCP em modo debug

cd server
node cli.js --debug

Terminal 2: Construir extensão do Chrome

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

Nota: A extensão do Firefox não requer uma etapa de build - ela usa JavaScript vanilla e pode ser carregada diretamente de extensions/firefox/

Carregar extensão no seu navegador:

Para navegadores Chromium (Chrome, Edge, Opera):

Abra chrome://extensions/ (Chrome), edge://extensions/ (Edge) ou opera://extensions/ (Opera)
Ative "Modo desenvolvedor"
Clique em "Carregar sem compactação"
Selecione a pasta extensions/chrome/dist

Para Firefox:

Abra about:debugging#/runtime/this-firefox
Clique em "Carregar extensão temporária"
Selecione qualquer arquivo da pasta extensions/firefox

Estrutura do Projeto

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/

Testes

# Run tests
npm test

# Run with coverage
npm run test:coverage

Documentação:

Procedimentos de Teste Manual - Guia abrangente de testes manuais
Especificação de Funcionalidades - Documentação completa de funcionalidades
Progresso dos Testes - Status atual da cobertura de testes

Configuração

O servidor funciona imediatamente com padrões sensatos. Para configuração avançada:

Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

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

# Local WebSocket port (Free tier)
MCP_PORT=5555

# Debug mode
DEBUG=false

Opções de Linha de Comando

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

Nota: Se você alterar a porta, precisará atualizar as configurações da extensão do navegador para corresponder.

Solução de Problemas

Extensão não conecta

Verifique se a extensão está instalada e ativada
Clique no ícone da extensão - deve mostrar "Conectado"
Verifique se o servidor MCP está em execução (procure pelo processo na porta 5555)
Tente recarregar a extensão

"Porta 5555 já está em uso"

Outra instância está em execução. Você pode:

Finalizar o processo existente:

lsof -ti:5555 | xargs kill -9

Usar uma porta diferente:

blueprint-mcp --port 8080

Ferramentas do navegador não funcionam

Certifique-se de ter chamado enable primeiro
Verifique se você anexou a uma aba com browser_tabs
Verifique se a aba ainda existe (não foi fechada)

Obtendo ajuda

Contribuindo

Contribuições são bem-vindas! Veja CONTRIBUTING.md para diretrizes.

Segurança

Esta ferramenta dá aos assistentes de IA controle sobre seu navegador. Por favor, revise:

O servidor MCP aceita apenas conexões locais por padrão (localhost:5555)
Conexões de retransmissão PRO são autenticadas via OAuth
A extensão requer ação explícita do usuário para conectar
Todas as ações do navegador passam pelo sistema de permissões do navegador

Encontrou um problema de segurança? Envie um e-mail para [email protected] em vez de registrar um problema público.

Créditos

Este projeto foi originalmente inspirado pela implementação Playwright MCP da Microsoft, mas foi completamente reescrito para usar automação baseada em extensão de navegador em vez do Playwright. A arquitetura, implementação e abordagem são fundamentalmente diferentes.

Diferenças principais:

Usa extensões de navegador com DevTools Protocol (não Playwright)
Funciona com perfis de navegador reais (não contextos isolados)
Comunicação baseada em WebSocket (não retransmissão CDP)
Opção de retransmissão em nuvem para acesso remoto
Modelo de níveis Gratuito e PRO
Suporte a múltiplos navegadores (Chrome, Firefox, Edge, Opera)

Somos gratos à equipe do Playwright por ser pioneira na automação de navegador via MCP.

Licença

Apache License 2.0 - veja LICENSE

Construído com ❤️ por Rails Blueprint

Website • GitHub • NPM