sulus-web-mcp

ライブWeb調査のためのステートレスなPlaywright MCPです。エージェントは3つのツールを利用できます — browse_page、extract_links、search_page — それぞれがURLを開き、テキストを抽出してブラウザコンテキストを閉じます。クリック・入力・ログインのツールはありません。

Sulus Agents（ai-phone-system MCPコネクタ）と、その他のエコシステム（Cursor、MCPConnect）向けに構築されています。Laravelはプロセス内でChromiumを実行できないため、このサービスが、それらのエージェントが呼び出すHTTP MCPになります。

ツール

各呼び出しは自己完結型です（ナビゲーション＋抽出）。これはai-phone-systemのコネクタクライアントに一致し、そのクライアントはMCPセッションなしでtools/list / tools/callをPOSTします。

要件

• 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（エージェント、チーム、本番環境）

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

ヘルスチェック: GET /health
MCP: POST /mcp (JSON-RPC, Streamable HTTP)

ログはブラウズごとにJSON 1行（urlのオリジン+パス、ステータス、ms）です。ページ本文がログに記録されることはありません。

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エージェントから接続

1. このサービスをHTTPSの背後にデプロイします。

2. MCP Connectorsでカスタムサーバーを追加します:

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

   • 認証: Bearer、トークン = MCP_SHARED_SECRET

3. エージェントでコネクタを有効にします。

HTTPハンドラーは、initialize / Mcp-Session-Id なしでtools/listとtools/callに応答します。これは、ExternalMcpClientServiceが送信する内容に一致します。セッション対応のStreamable HTTPは、Cursorでも引き続き機能します。

セキュリティ

• HTTPSのみ（ALLOW_INSECURE_HTTP=trueの場合を除く）

• localhost、RFC1918、リンクローカル、CGNAT、クラウドメタデータホストをブロック

• DNS解決を行い、プライベートな応答を拒否

• ページ内のブロック対象URLへのリクエストを中断

• 呼び出しごとに新しいブラウザコンテキスト — Cookieは共有されません

• フォーム入力 / クリック / ファイルアップロードのツールはありません

スクリプト

npm run typecheck
npm test
npm run build