sulus-web-mcp

Zustandsloser Playwright MCP für Live-Web-Recherche. Agents erhalten drei Tools — browse_page, extract_links, search_page — die jeweils eine URL öffnen, Text extrahieren und den Browserkontext schließen. Keine Klick-/Eingabe-/Login-Tools.

Entwickelt für Sulus Agents (ai-phone-system MCP-Connectors) und den Rest des Ökosystems (Cursor, MCPConnect). Laravel kann Chromium nicht prozessintern ausführen; dieser Dienst ist das HTTP-MCP, das diese Agents aufrufen.

Tools

Jeder Aufruf ist in sich abgeschlossen (navigieren + extrahieren). Das entspricht dem Connector-Client von ai-phone-system, der tools/list / tools/call ohne MCP-Session als POST sendet.

Voraussetzungen

• Node.js 20+

• Playwright Chromium (npx playwright install chromium nach npm install)

Einrichtung

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 (Agents, Team, Produktion)

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

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

Logs sind eine JSON-Zeile pro Seitenabruf (url-Origin+Pfad, Status, ms). Seiteninhalte werden nie protokolliert.

Docker

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

Verwendet das offizielle Playwright-Image (Chromium enthalten). shm_size: 1gb ist erforderlich.

stdio (lokaler Cursor)

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 von Cursor (nach dem Deployment):

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

Verbindung von ai-phone-system-Agents

1. Stellen Sie diesen Dienst hinter HTTPS bereit.

2. Fügen Sie in MCP Connectors einen eigenen Server hinzu:

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

   • Auth: Bearer, Token = MCP_SHARED_SECRET

3. Aktivieren Sie den Connector für den Agent.

Der HTTP-Handler beantwortet tools/list und tools/call ohne initialize / Mcp-Session-Id – genau das sendet der ExternalMcpClientService. Sessionful Streamable HTTP funktioniert weiterhin für Cursor.

Sicherheit

• HTTPS nur (außer ALLOW_INSECURE_HTTP=true)

• Blockiert localhost, RFC1918, link-local, CGNAT, privates

• Löst DNS auf und weist private Antworten zurück

• Bricht In-Page-Anfragen zu blockierten URLs ab

• Neuer Browserkontext pro Aufruf – keine Weitergabe von Cookies

• Keine Tools zum Formular-Ausfüllen, Klicken oder Datei-Upload

Skripte

npm run typecheck
npm test
npm run build