sulus-web-mcp

MCP de Playwright sin estado para investigación web en vivo. Los agentes obtienen tres herramientas — browse_page, extract_links, search_page — cada una abre una URL, extrae texto y cierra el contexto del navegador. No hay herramientas de clic, escritura o inicio de sesión.

Construido para Sulus Agents (conectores MCP de ai-phone-system) y el resto del ecosistema (Cursor, MCPConnect). Laravel no puede ejecutar Chromium en el mismo proceso; este servicio es el MCP HTTP al que llaman esos agentes.

Tools

Cada llamada es autocontenida (navegar + extraer). Eso coincide con el cliente conector de ai-phone-system, que envía tools/list / tools/call con sin sesión MCP.

Requisitos

• Node.js 20+

• Playwright Chromium (npx playwright install chromium después de npm install)

Configuración

cd /Users/macbook/Workshop/Sulus.ai/sulus-web-mcp
npm install
npx playwright install chromium
cp .env.example .env
# set MCP_SHARED_SECRET
npm run build

HTTP (Agentes, equipo, producción)

npm run start:http
# or: npm run dev:http

Salud: GET /health
MCP: POST /mcp (JSON-RPC, Streamable HTTP)

Los registros son una línea JSON por navegación (origen+ruta de url, estado, ms). Los cuerpos de las páginas nunca se registran.

Docker

cp .env.example .env
docker compose up -d --build

Usa la imagen oficial de Playwright (incluye Chromium). Se requiere shm_size: 1gb.

stdio (Cursor local)

npm run start

.cursor/mcp.json:

{
  "mcpServers": {
    "sulus-web": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/Users/macbook/Workshop/Sulus.ai/sulus-web-mcp"
    }
  }
}

HTTP desde Cursor (después del despliegue):

{
  "mcpServers": {
    "sulus-web": {
      "url": "https://browse.sulus.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SHARED_SECRET"
      }
    }
  }
}

Conectar desde agentes de ai-phone-system

1. Despliega este servicio detrás de HTTPS.

2. En MCP Connectors, agrega un servidor personalizado:

   • URL: https://browse.sulus.ai/mcp

   • Autenticación: Bearer, token = MCP_SHARED_SECRET

3. Habilita el conector en el agente.

El manejador HTTP responde a tools/list y tools/call sin initialize / Mcp-Session-Id, que es lo que envía ExternalMcpClientService. El HTTP Streamable con sesión aún funciona para Cursor.

Seguridad

• Solo HTTPS (a menos que ALLOW_INSECURE_HTTP=true)

• Bloquea localhost, RFC1918, enlace local, CGNAT, hosts de metadatos de nube

• Resuelve DNS y rechaza respuestas privadas

• Aborta solicitudes en la página a URLs bloqueadas

• Nuevo contexto de navegador por llamada — sin compartir cookies

• Sin herramientas de relleno de formularios / clic / carga de archivos

Scripts

npm run typecheck
npm test
npm run build