sulus-web-mcp

실시간 웹 조사를 위한 무상태 Playwright MCP 서버입니다. 에이전트는 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 (Agents, 팀, 프로덕션)

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

상태 확인: GET /health
MCP: POST /mcp (JSON-RPC, Streamable HTTP)

로그는 브라우즈(browse)마다 JSON 한 줄로 기록됩니다(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 Agents에서 연결

1. 이 서비스를 HTTPS 뒤에 배포합니다.

2. MCP Connectors에서 커스텀 서버를 추가합니다:

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

   • 인증: Bearer, 토큰 = MCP_SHARED_SECRET

3. 에이전트에서 커넥터를 활성화합니다.

HTTP 핸들러는 tools/list 및 tools/call에 initialize / Mcp-Session-Id 없이 응답하며, 이는 ExternalMcpClientService가 보내는 형식입니다. 세션 기반 Streamable HTTP는 Cursor에서도 여전히 작동합니다.

안전

• HTTPS 전용 (ALLOW_INSECURE_HTTP=true인 경우 제외)

• localhost, RFC1918, link-local, CGNAT, 클라우드 메타데이터 호스트 차단

• DNS를 확인하고 사설 주소 응답을 거부합니다

• 차단된 URL로의 페이지 내 요청을 중단합니다

• 호출마다 새 브라우저 컨텍스트 — 쿠키 공유 없음

• 폼 작성 / 클릭 / 파일 업로드 도구 없음

스크립트

npm run typecheck
npm test
npm run build