sulus-web-mcp

用于实时网页研究的无状态 Playwright MCP。Agents 可拥有三个工具：browse_page、extract_links、search_page。每个工具会打开一个 URL、提取文本，然后关闭浏览器上下文。不提供 click/type/login 等工具。

为 Sulus Agents（ai-phone-system MCP 连接器）以及生态中的其他客户端（Cursor、MCPConnect）而构建。Laravel 无法在自身进程内运行 Chromium，因此本服务就是这些 Agents 所调用的 HTTP MCP。

工具

每次调用都是独立的（导航 + 提取）。这与 ai-phone-system 的连接器客户端一致：它会以 无 MCP 会话 的方式发送 tools/list / tools/call。

环境要求

• Node.js 20+

• Playwright Chromium（在 npm install 之后运行 npx playwright install chromium）

设置

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、团队、生产环境）

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

健康检查：GET /health
MCP：POST /mcp（JSON-RPC，Streamable HTTP）

每次浏览都会输出一行 JSON 日志（url 的来源+路径、状态、耗时）。页面的正文内容永远不会被记录。

Docker

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

使用官方 Playwright 镜像（内置 Chromium）。必须设置 shm_size: 1gb。

stdio（本地 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"
    }
  }
}

Cursor 通过 HTTP 连接（部署后）：

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

从 ai-phone-system Agents 连接

1. 将该服务部署到 HTTPS 后面。

2. 在 MCP Connectors 中添加自定义服务器：

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

   • Auth：Bearer，token = MCP_SHARED_SECRET

3. 在该 Agent 上启用连接器。

HTTP 处理器在 没有 initialize / Mcp-Session-Id 的情况下响应 tools/list 和 tools/call，这正是 ExternalMcpClientService 的发送方式。Sessionable Streamable HTTP 对 Cursor 仍然可用。

Safety

• 仅支持 HTTPS（除非 ALLOW_INSECURE_HTTP=true）

• 阻止 localhost、RFC1918、link-local、CGNAT、云 metadata 主机

• 解析 DNS 并拒绝私有回包

• 中止向被阻止的 URL 发出的页面内请求

• 每次调用使用新的浏览器上下文——不共享 cookie

• 不提供表单填充 / 点击 / 文件上传工具

Scripts

npm run typecheck
npm test
npm run build