Agent Bridge

Visão geral

O Agent Bridge permite que agentes de IA (Claude Code, Cursor, Cowork, etc.) controlem remotamente a extensão do Chrome do Web2MD para converter URLs em lote — especialmente Reddit, páginas renderizadas por JS e páginas protegidas por login que bloqueiam o acesso via API no servidor. Em vez de chamar a API do Web2MD (que o Reddit bloqueia), o agente de IA envia comandos para a sua extensão local do Chrome via Native Messaging. A extensão abre cada página em uma aba em segundo plano usando sua sessão real do navegador — com seus cookies e estado de login — extrai o conteúdo, converte em Markdown e retorna o resultado.

O Agent Bridge requer um plano PRO e o host de native messaging instalado na sua máquina. A extensão precisa estar aberta no Chrome.

Arquitetura

AI Agent ←MCP/stdio→ MCP Server ←TCP:12315→ Native Host ←NM→ Chrome Extension → Any Website

Componente	Papel
AI Agent	Claude Code, Cursor, Cowork — chama as ferramentas MCP
MCP Server	Traduz chamadas de ferramentas MCP em mensagens TCP
Native Host	Faz o relay entre TCP e o Native Messaging do Chrome
Chrome Extension	Abre abas, extrai HTML, converte em Markdown

Toda a comunicação é local — nada sai da sua máquina. O Native Host escuta apenas em localhost:12315.

Configuração

Passo 1: Compilar o MCP Server

cd packages/mcp-server
pnpm build

Passo 2: Instalar o Native Messaging Host

cd packages/mcp-server
./install.sh <your-extension-id>

Encontre seu Extension ID em chrome://extensions com o Modo de Desenvolvedor ativado. Procure por Web2MD e copie a string do ID (ex.: ijmgpkkfgpijifldbjafjiapehppcbcn).

Depois da instalação, você precisa fechar completamente o Chrome (Cmd+Q no Mac) e reabri-lo. O Chrome só lê os manifestos de Native Messaging na inicialização — recarregar a extensão não é suficiente.

O script de instalação:

Copia os arquivos do host para ~/.web2md/ (evita restrições do TCC do macOS em ~/Desktop)
Resolve o caminho absoluto do node (o Chrome inicia com um PATH mínimo)
Escreve o manifesto NM no diretório NativeMessagingHosts do Chrome

Passo 3: Configurar o MCP

Claude Code
Cursor
Claude Desktop

Adicione a ~/.claude/settings.json:

{
  "mcpServers": {
    "web2md-agent": {
      "command": "node",
      "args": ["/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

Adicione a ~/.cursor/mcp.json:

{
  "mcpServers": {
    "web2md-agent": {
      "command": "node",
      "args": ["/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

Adicione à sua configuração do Claude Desktop:

{
  "mcpServers": {
    "web2md-agent": {
      "command": "node",
      "args": ["/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

Passo 4: Verificar

No Chrome, abra chrome://extensions → clique no link “Service Worker” do Web2MD → confira o Console:

[Web2MD] Service worker started
[Web2MD] Connected to native host
[Web2MD] Native host TCP relay ready on port 12315

Se você vir essas três linhas, o Agent Bridge está funcionando.

Ferramentas disponíveis

O Agent Bridge expõe três ferramentas MCP — escolha com base no transporte e na necessidade de processamento em lote. As três são documentadas por completo na página do MCP Server; aqui está a comparação rápida.

Ferramenta	Transporte	Lote
`bridge_convert_url`	HTTP (a extensão busca o HTML, o servidor converte)	URL única
`agent_convert`	Native messaging (a arquitetura desta página)	URL única, parâmetro `skill` opcional
`agent_batch_convert`	Native messaging	Até 50 URLs, sequencial

agent_convert

Converte uma única URL usando a extensão do Chrome via native messaging.

Parâmetro	Tipo	Descrição
`url`	string	A URL a converter
`skill`	string (opcional)	Id ou nome de Skill — seu corpo é anexado ao Markdown retornado

Retorna: Conteúdo em Markdown com título, URL de origem, contagem de palavras e tempo de leitura. Ideal para: Threads do Reddit, páginas protegidas por login, sites renderizados por JS.

agent_batch_convert

Converte em lote até 50 URLs. As URLs são processadas sequencialmente — a extensão abre cada página em uma aba em segundo plano, extrai o conteúdo, fecha a aba, e passa para a próxima.

Parâmetro	Tipo	Descrição
`urls`	string[]	Array de URLs a converter (máximo 50)

Retorna: Resultados por URL transmitidos conforme são concluídos, além de um resumo. Ideal para: Fluxos de pesquisa — converter em lote threads do Reddit, discussões do HN, ou páginas de concorrentes para análise por IA.

bridge_convert_url

Converte uma única URL buscando seu HTML através da extensão via uma ponte HTTP local (em vez de native messaging), depois convertendo no servidor. Funcionalmente similar a agent_convert para conversões pontuais, mas não requer o host de native messaging — apenas a extensão precisa estar instalada e em execução.

Parâmetro	Tipo	Descrição
`url`	string	A URL a converter
`extensionId`	string (opcional)	Sobrescreve o ID da extensão (descoberto automaticamente a partir da sua chave de API se omitido)

Todas as conversões bem-sucedidas são salvas automaticamente no Histórico do Dashboard, com resumos e tags gerados por IA.

Exemplos de uso

Converter uma thread do Reddit

Você: Convert this Reddit thread to Markdown: https://www.reddit.com/r/LangChain/comments/1siwh6q/…Agente: (chama agent_convert) Aqui está a thread convertida com 7 comentários discutindo a precisão de RAG para documentos jurídicos…

Converter em lote para pesquisa

Você: Batch convert these 5 Reddit URLs and summarize the key takeaways:

Agente: (chama agent_batch_convert) 5/5 URLs convertidas com sucesso. Aqui estão os principais destaques…

Sites suportados

O Agent Bridge usa os mesmos 27 extratores específicos por site que a extensão — cada um sabe como extrair conteúdo limpo do DOM ou da API de um site, em vez de recorrer ao HTML bruto da página.

Exportações de chat de IA (2)

Conversas do Claude · Outras plataformas de chat de IA (ChatGPT, Gemini, etc. via um extrator de DOM compartilhado)

Docs e bases de conhecimento (6)

Wikipedia · arXiv · OpenAI Docs · Sites de documentação baseados em Mintlify · Notion · Google Docs

Dev e código (3)

GitHub Issues/PRs · Stack Overflow · dev.to

Publicação (3)

Medium · Substack · Product Hunt

Plataformas CJK (4)

WeChat (微信公众号) · Bilibili (哔哩哔哩) · Feishu (飞书) — além de Xiaohongshu e Zhihu acima. O código marca essa categoria inteira como seu grupo de extratores de maior diferenciação — poucos concorrentes lidam com essas plataformas.

Vídeo e mídia (1)

YouTube (extração de transcrição)

Trabalho e produtividade (5)

Gmail · LinkedIn · Amazon (páginas de produto) · Canvas LMS · fóruns XenForo

Qualquer URL sem um extrator dedicado recorre à extração da página HTML completa — ainda funciona, apenas sem a limpeza específica do site (remoção de menus de navegação, anúncios, widgets de comentários, etc.) que os extratores especializados aplicam. Sites que expõem uma API pública (Reddit, Hacker News, GitHub, Stack Overflow) são buscados via essa API quando possível — mais rápido e confiável do que abrir uma aba em segundo plano. Todo o resto abre a página em uma aba em segundo plano e extrai do DOM renderizado.

Solução de problemas

'Native host not installed' ou 'not found'

O Chrome não carregou o manifesto NM. Feche completamente o Chrome (Cmd+Q) e reabra. Apenas recarregar a extensão não é suficiente.

'Native host has exited' imediatamente

O Chrome não consegue executar o script do host. Causas comuns:

node não encontrado — execute novamente ./install.sh, que usa o caminho absoluto do node
O host está em um diretório protegido pelo TCC (~/Desktop, ~/Documents) — execute a instalação novamente para mover para ~/.web2md/

'Agent connection error' do MCP

O servidor TCP do Native Host não está em execução. Verifique se:

O Chrome está aberto
A extensão do Web2MD está carregada
O console do Service Worker mostra “TCP relay ready on port 12315”

'Failed to extract content from the page'

A extensão não está logada. Abra o popup do Web2MD no Chrome e faça login na sua conta PRO.

'Tab load timeout'

A página de destino demora demais para carregar. Isso é normal em sites lentos. A extensão espera até 15 segundos por aba. O Reddit usa o extrator da API JSON e não precisa de uma aba, então timeouts no Reddit geralmente significam que a URL do post é inválida (404).

Conversões não aparecem no Histórico do Dashboard

Salvar no histórico requer que a extensão esteja logada com uma conta PRO. O salvamento é fire-and-forget — se a chamada de API falhar silenciosamente, as conversões não aparecerão. Verifique se seu token de autenticação é válido.

Diferenças em relação ao MCP Server

Recurso	`convert_url`	`bridge_convert_url`	`agent_convert` / `agent_batch_convert`
Onde executa	Chamada de API no servidor	A extensão busca o HTML, o servidor converte	Seu navegador Chrome local (native messaging)
Suporte a Reddit	❌ Bloqueado pelo Reddit	✅ Usa sessão real do navegador	✅ Usa sessão real do navegador
Páginas protegidas por login	❌ Sem acesso	✅ Usa seus cookies	✅ Usa seus cookies
Páginas renderizadas por JS	❌ Sem JavaScript	✅ Renderização completa do Chrome	✅ Renderização completa do Chrome
Configuração necessária	Apenas chave de API	Extensão instalada e em execução	Extensão + host de native messaging instalados
Processamento em lote	—	Apenas URL única	Até 50 URLs (`agent_batch_convert`)
Requer o Chrome aberto	Não	Sim	Sim

Regra prática: Use convert_url para páginas públicas. Use bridge_convert_url quando quiser a sessão do navegador da extensão, mas não quiser instalar o host de native messaging. Use agent_convert / agent_batch_convert para Reddit, páginas autenticadas, sites pesados em JS, ou quando precisar processar em lote — ou quiser aplicar uma Skill via o parâmetro skill de agent_convert.

Primeiros passos

Recursos principais

Avançado

Planos

Visão geral

Arquitetura

Configuração

Passo 1: Compilar o MCP Server

Passo 2: Instalar o Native Messaging Host

Passo 3: Configurar o MCP

Passo 4: Verificar

Ferramentas disponíveis

agent_convert

agent_batch_convert

bridge_convert_url

Exemplos de uso

Sites suportados

Solução de problemas

Diferenças em relação ao MCP Server

​Visão geral

​Arquitetura

​Configuração

​Passo 1: Compilar o MCP Server

​Passo 2: Instalar o Native Messaging Host

​Passo 3: Configurar o MCP

​Passo 4: Verificar

​Ferramentas disponíveis

​agent_convert

​agent_batch_convert

​bridge_convert_url

​Exemplos de uso

​Sites suportados

​Solução de problemas

​Diferenças em relação ao MCP Server

Visão geral

Arquitetura

Configuração

Passo 1: Compilar o MCP Server

Passo 2: Instalar o Native Messaging Host

Passo 3: Configurar o MCP

Passo 4: Verificar

Ferramentas disponíveis

agent_convert

agent_batch_convert

bridge_convert_url

Exemplos de uso

Sites suportados

Solução de problemas

Diferenças em relação ao MCP Server