> ## Documentation Index
> Fetch the complete documentation index at: https://web2md.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Bridge
> Permite que agentes de IA conviertan por lotes Reddit y cualquier sitio web mediante tu extensión de Chrome
## Descripción general
Agent Bridge permite que agentes de IA (Claude Code, Cursor, Cowork, etc.) controlen de forma remota la extensión de Chrome de Web2MD para convertir URLs por lotes — especialmente Reddit y páginas renderizadas con JS o protegidas por login que bloquean el acceso vía API del lado del servidor.
En lugar de llamar a la API de Web2MD (que Reddit bloquea), el agente de IA envía comandos a tu extensión de Chrome local mediante [Native Messaging](https://developer.chrome.com/docs/extensions/develop/concepts/native-messaging). La extensión abre cada página en una pestaña en segundo plano usando **tu sesión real del navegador** — con tus cookies y tu estado de sesión — extrae el contenido, lo convierte a Markdown y devuelve el resultado.
Agent Bridge requiere un **plan PRO** y el **host de native messaging** instalado en tu máquina. La extensión debe estar abierta en Chrome.
## Arquitectura
```
AI Agent ←MCP/stdio→ MCP Server ←TCP:12315→ Native Host ←NM→ Chrome Extension → Any Website
```
| Componente | Rol |
| -------------------- | ----------------------------------------------------- |
| **AI Agent** | Claude Code, Cursor, Cowork — invoca herramientas MCP |
| **MCP Server** | Traduce llamadas a herramientas MCP en mensajes TCP |
| **Native Host** | Actúa de relevo entre TCP y Chrome Native Messaging |
| **Chrome Extension** | Abre pestañas, extrae HTML, convierte a Markdown |
Toda la comunicación es **local** — nada sale de tu máquina. El Native Host solo escucha en `localhost:12315`.
## Configuración
### Paso 1: Compila el servidor MCP
```bash theme={null}
cd packages/mcp-server
pnpm build
```
### Paso 2: Instala el host de Native Messaging
```bash theme={null}
cd packages/mcp-server
./install.sh
```
Encuentra tu ID de extensión en `chrome://extensions` con el Modo de desarrollador activado. Busca Web2MD y copia la cadena del ID (p. ej. `ijmgpkkfgpijifldbjafjiapehppcbcn`).
Después de la instalación, debes **cerrar Chrome por completo (Cmd+Q en Mac) y volver a abrirlo**. Chrome solo lee los manifiestos de Native Messaging al arrancar — recargar la extensión no es suficiente.
El script de instalación:
* Copia los archivos del host a `~/.web2md/` (evita las restricciones TCC de macOS en `~/Desktop`)
* Resuelve la ruta absoluta de `node` (Chrome se lanza con un PATH mínimo)
* Escribe el manifiesto NM en el directorio `NativeMessagingHosts` de Chrome
### Paso 3: Configura MCP
Añade a `~/.claude/settings.json`:
```json theme={null}
{
"mcpServers": {
"web2md-agent": {
"command": "node",
"args": ["/path/to/packages/mcp-server/dist/index.js"],
"env": {
"WEB2MD_API_KEY": "w2m_your_key_here"
}
}
}
}
```
Añade a `~/.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"web2md-agent": {
"command": "node",
"args": ["/path/to/packages/mcp-server/dist/index.js"],
"env": {
"WEB2MD_API_KEY": "w2m_your_key_here"
}
}
}
}
```
Añade a la configuración de Claude Desktop:
```json theme={null}
{
"mcpServers": {
"web2md-agent": {
"command": "node",
"args": ["/path/to/packages/mcp-server/dist/index.js"],
"env": {
"WEB2MD_API_KEY": "w2m_your_key_here"
}
}
}
}
```
### Paso 4: Verifica
En Chrome, abre `chrome://extensions` → haz clic en el enlace "Service Worker" de Web2MD → revisa la consola:
```
[Web2MD] Service worker started
[Web2MD] Connected to native host
[Web2MD] Native host TCP relay ready on port 12315
```
Si ves estas tres líneas, Agent Bridge está funcionando.
## Herramientas disponibles
Agent Bridge expone tres herramientas MCP — elige según el transporte y las necesidades de procesamiento por lotes. Las tres están documentadas en detalle en la página de [Servidor MCP](/docs/es/advanced/mcp-server); esta es la comparación rápida.
| Herramienta | Transporte | Procesamiento por lotes |
| --------------------- | ------------------------------------------------------------- | ------------------------------------- |
| `bridge_convert_url` | HTTP (la extensión obtiene el HTML, el servidor lo convierte) | URL única |
| `agent_convert` | Native messaging (arquitectura de esta página) | URL única, parámetro `skill` opcional |
| `agent_batch_convert` | Native messaging | Hasta 50 URLs, secuencial |
### agent\_convert
Convierte una única URL usando la extensión de Chrome vía native messaging.
| Parámetro | Tipo | Descripción |
| --------- | ----------------- | ----------------------------------------------------------------- |
| `url` | string | La URL a convertir |
| `skill` | string (opcional) | Id o nombre de Skill — su contenido se añade al Markdown devuelto |
**Devuelve:** Contenido Markdown con título, URL de origen, recuento de palabras y tiempo de lectura.
**Ideal para:** Hilos de Reddit, páginas protegidas por login, sitios renderizados con JS.
### agent\_batch\_convert
Convierte por lotes hasta 50 URLs. Las URLs se procesan secuencialmente — la extensión abre cada página en una pestaña en segundo plano, extrae el contenido, cierra la pestaña y pasa a la siguiente.
| Parámetro | Tipo | Descripción |
| --------- | --------- | ----------------------------------- |
| `urls` | string\[] | Array de URLs a convertir (máx. 50) |
**Devuelve:** Resultados por URL transmitidos a medida que se completan, más un resumen.
**Ideal para:** Flujos de investigación — convertir por lotes hilos de Reddit, discusiones de HN o páginas de la competencia para análisis con IA.
### bridge\_convert\_url
Convierte una única URL obteniendo su HTML a través de la extensión mediante un puente HTTP local (en lugar de native messaging), y luego lo convierte del lado del servidor. Funcionalmente similar a `agent_convert` para conversiones puntuales, pero no requiere el host de native messaging — solo necesita que la extensión esté instalada y en ejecución.
| Parámetro | Tipo | Descripción |
| ------------- | ----------------- | ------------------------------------------------------------------------------------------------------- |
| `url` | string | La URL a convertir |
| `extensionId` | string (opcional) | Sobrescribe el ID de la extensión (se descubre automáticamente a partir de tu clave de API si se omite) |
Todas las conversiones exitosas se guardan automáticamente en tu [Historial del Dashboard](https://web2md.org/dashboard/history), con resúmenes y etiquetas generados por IA.
## Ejemplos de uso
**Tú:** Convierte este hilo de Reddit a Markdown: [https://www.reddit.com/r/LangChain/comments/1siwh6q/](https://www.reddit.com/r/LangChain/comments/1siwh6q/)...
**Agente:** *(invoca `agent_convert`)* Aquí está el hilo convertido con 7 comentarios sobre la precisión de RAG para documentos legales...
**Tú:** Convierte por lotes estas 5 URLs de Reddit y resume las conclusiones clave:
* [https://reddit.com/r/MachineLearning/comments/](https://reddit.com/r/MachineLearning/comments/)...
* [https://reddit.com/r/LocalLLaMA/comments/](https://reddit.com/r/LocalLLaMA/comments/)...
* [https://reddit.com/r/LangChain/comments/](https://reddit.com/r/LangChain/comments/)...
* [https://reddit.com/r/artificial/comments/](https://reddit.com/r/artificial/comments/)...
* [https://reddit.com/r/ChatGPT/comments/](https://reddit.com/r/ChatGPT/comments/)...
**Agente:** *(invoca `agent_batch_convert`)* Se convirtieron 5/5 URLs correctamente. Aquí están las conclusiones clave...
**Tú:** Convierte la wiki interna de mi empresa en [https://wiki.internal.com/architecture](https://wiki.internal.com/architecture)
**Agente:** *(invoca `agent_convert`)* Como estás conectado a este sitio en Chrome, pude extraer el contenido completo...
## Sitios compatibles
Agent Bridge usa los mismos 27 extractores específicos de sitio que la extensión — cada uno sabe cómo extraer contenido limpio del DOM o la API de un sitio en lugar de recurrir al HTML crudo de la página.
Reddit · Hacker News · Twitter/X · Quora · Xiaohongshu (小红书) · Zhihu (知乎) · Instagram
Conversaciones de Claude · Otras plataformas de chat de IA (ChatGPT, Gemini, etc. mediante un extractor DOM compartido)
Wikipedia · arXiv · OpenAI Docs · Sitios de documentación basados en Mintlify · Notion · Google Docs
GitHub Issues/PRs · Stack Overflow · dev.to
Medium · Substack · Product Hunt
WeChat (微信公众号) · Bilibili (哔哩哔哩) · Feishu (飞书) — más Xiaohongshu y Zhihu mencionados arriba. El código marca esta categoría completa como su grupo de extractores de mayor diferenciación — pocos competidores manejan estas plataformas en absoluto.
YouTube (extracción de transcripciones)
Gmail · LinkedIn · Amazon (páginas de producto) · Canvas LMS · foros XenForo
Cualquier URL sin un extractor dedicado recurre a la extracción de HTML de página completa — sigue funcionando, solo que sin la limpieza específica del sitio (eliminación de barras de navegación, anuncios, widgets de comentarios, etc.) que aplican los extractores especializados. Los sitios que exponen una API pública (Reddit, Hacker News, GitHub, Stack Overflow) se obtienen a través de esa API cuando es posible — más rápido y más confiable que abrir una pestaña en segundo plano. Todo lo demás abre la página en una pestaña en segundo plano y extrae del DOM renderizado.
## Solución de problemas
Chrome no ha cargado el manifiesto NM. **Cierra Chrome por completo (Cmd+Q) y vuelve a abrirlo.** Simplemente recargar la extensión no es suficiente.
Chrome no puede ejecutar el script del host. Causas comunes:
* No se encuentra `node` — vuelve a ejecutar `./install.sh`, que usa la ruta absoluta de node
* El host está en un directorio protegido por TCC (`~/Desktop`, `~/Documents`) — vuelve a ejecutar la instalación para moverlo a `~/.web2md/`
El servidor TCP del Native Host no está en ejecución. Asegúrate de que:
1. Chrome esté abierto
2. La extensión de Web2MD esté cargada
3. La consola del Service Worker muestre "TCP relay ready on port 12315"
La extensión no tiene la sesión iniciada. Abre el popup de Web2MD en Chrome e inicia sesión en tu cuenta PRO.
La página de destino tarda demasiado en cargar. Esto es normal en sitios lentos. La extensión espera hasta 15 segundos por pestaña. Reddit usa el extractor de la API JSON y no necesita una pestaña, así que los timeouts en Reddit normalmente significan que la URL de la publicación no es válida (404).
Guardar en el historial requiere que la extensión tenga la sesión iniciada con una cuenta PRO. El guardado es de tipo fire-and-forget — si la llamada a la API falla silenciosamente, las conversiones no aparecerán. Verifica que tu token de autenticación sea válido.
## En qué se diferencia del servidor MCP
| Función | `convert_url` | `bridge_convert_url` | `agent_convert` / `agent_batch_convert` |
| ---------------------------- | ----------------------------------- | ------------------------------------------------------ | ----------------------------------------------- |
| Dónde se ejecuta | Llamada a API del lado del servidor | La extensión obtiene el HTML, el servidor lo convierte | Tu navegador Chrome local (native messaging) |
| Soporte de Reddit | ❌ Bloqueado por Reddit | ✅ Usa la sesión real del navegador | ✅ Usa la sesión real del navegador |
| Páginas protegidas por login | ❌ Sin acceso | ✅ Usa tus cookies | ✅ Usa tus cookies |
| Páginas renderizadas con JS | ❌ Sin JavaScript | ✅ Renderizado completo de Chrome | ✅ Renderizado completo de Chrome |
| Configuración requerida | Solo clave de API | Extensión instalada y en ejecución | Extensión + host de native messaging instalados |
| Procesamiento por lotes | — | Solo URL única | Hasta 50 URLs (`agent_batch_convert`) |
| Requiere Chrome abierto | No | Sí | Sí |
**Regla general:** Usa `convert_url` para páginas públicas. Usa `bridge_convert_url` cuando quieras la sesión del navegador de la extensión pero no quieras instalar el host de native messaging. Usa `agent_convert` / `agent_batch_convert` para Reddit, páginas autenticadas, sitios con mucho JS, o cuando necesites procesar por lotes — o quieras aplicar una Skill mediante el parámetro `skill` de `agent_convert`.