sulus-web-mcp

Stateless Playwright MCP for live-web research. Agents get three tools — browse_page, extract_links, search_page — each of which opens a URL, extracts text, and closes the browser context. No click/type/login tools.

Built for Sulus Agents (ai-phone-system MCP connectors) and the rest of the ecosystem (Cursor, MCPConnect). Laravel cannot run Chromium in-process; this service is the HTTP MCP those agents call.

Tools

Each call is self-contained (navigate + extract). That matches ai-phone-system's connector client, which POSTs tools/list / tools/call with no MCP session.

Requirements

• Node.js 20+

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

Setup

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, production)

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

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

Logs are one JSON line per browse (url origin+path, status, ms). Page bodies are never logged.

Docker

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

Uses the official Playwright image (Chromium included). shm_size: 1gb is required.

stdio (local 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 from Cursor (after deploy):

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

Connect from ai-phone-system Agents

1. Deploy this service behind HTTPS.

2. In MCP Connectors, add a custom server:

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

   • Auth: Bearer, token = MCP_SHARED_SECRET

3. Enable the connector on the agent.

The HTTP handler answers tools/list and tools/call without initialize / Mcp-Session-Id, which is what ExternalMcpClientService sends. Sessionful Streamable HTTP still works for Cursor.

Safety

• HTTPS only (unless ALLOW_INSECURE_HTTP=true)

• Blocks localhost, RFC1918, link-local, CGNAT, cloud metadata hosts

• Resolves DNS and rejects private answers

• Aborts in-page requests to blocked URLs

• New browser context per call — no cookie sharing

• No form-fill / click / file-upload tools

Scripts

npm run typecheck
npm test
npm run build