Webpage Screenshot MCP Server

웹페이지 스크린샷 MCP 서버

Puppeteer를 사용하여 웹 페이지의 스크린샷을 캡처하는 MCP(Model Context Protocol) 서버입니다. 이 서버를 통해 AI 에이전트는 웹 애플리케이션을 시각적으로 검증하고 웹 애플리케이션 생성 시 진행 상황을 확인할 수 있습니다.

특징

• 전체 페이지 스크린샷 : 전체 웹 페이지 또는 뷰포트만 캡처
• 요소 스크린샷 : CSS 선택기를 사용하여 특정 요소를 타겟팅합니다.
• 다양한 포맷 지원: PNG, JPEG, WebP 포맷 지원
• 사용자 정의 옵션 : 뷰포트 크기, 이미지 품질, 대기 조건 및 지연 설정
• Base64 인코딩 : 간편한 통합을 위해 Base64로 인코딩된 이미지로 스크린샷을 반환합니다.
• 인증 지원 : 수동 로그인 및 쿠키 지속성
• 기본 브라우저 통합 : 보다 자연스러운 경험을 위해 시스템의 기본 브라우저를 사용하세요
• 세션 지속성 : 여러 단계의 워크플로를 위해 브라우저 세션을 열어 둡니다.

설치

지엑스피1

용법

도구

이 MCP 서버는 여러 가지 도구를 제공합니다.

1. 로그인 후 대기

수동 로그인을 위해 눈에 보이는 브라우저 창에서 웹 페이지를 열고, 사용자가 로그인을 완료할 때까지 기다린 후 쿠키를 저장합니다.

• url (필수): 로그인 페이지의 URL
• waitMinutes (선택 사항): 로그인을 기다리는 최대 시간(분)(기본값: 5)
• successIndicator (선택 사항): 로그인 성공을 나타내는 CSS 선택기 또는 URL 패턴
• useDefaultBrowser (선택 사항): 시스템의 기본 브라우저를 사용할지 여부(기본값: true)

2. 스크린샷 페이지

주어진 URL의 스크린샷을 캡처하여 base64로 인코딩된 이미지로 반환합니다.

• url (필수): 스크린샷을 찍을 웹페이지의 URL
• fullPage (선택 사항): 전체 페이지를 캡처할지 아니면 뷰포트만 캡처할지(기본값: true)
• width (선택 사항): 픽셀 단위의 뷰포트 너비(기본값: 1920)
• height (선택 사항): 픽셀 단위의 뷰포트 높이(기본값: 1080)
• format (선택 사항): 이미지 형식 - "png", "jpeg" 또는 "webp"(기본값: "png")
• quality (선택 사항): 이미지 품질(0-100), jpeg 및 webp에만 적용 가능
• waitFor (선택 사항): 페이지가 로드된 것으로 간주할 시기 - "load", "domcontentloaded", "networkidle0" 또는 "networkidle2"(기본값: "networkidle2")
• delay (선택 사항): 페이지 로드 후 추가 지연 시간(밀리초)(기본값: 0)
• useSavedAuth (선택 사항): 이전 로그인에서 저장된 쿠키를 사용할지 여부(기본값: true)
• reuseAuthPage (선택 사항): 기존 인증된 페이지를 사용할지 여부(기본값: false)
• useDefaultBrowser (선택 사항): 시스템의 기본 브라우저를 사용할지 여부(기본값: false)
• visibleBrowser (선택 사항): 브라우저 창을 표시할지 여부(기본값: false)

3. 스크린샷 요소

CSS 선택기를 사용하여 웹페이지의 특정 요소의 스크린샷을 캡처합니다.

• url (필수): 웹페이지의 URL
• selector (필수): 스크린샷을 찍을 요소에 대한 CSS 선택기
• waitForSelector (선택 사항): 선택자가 나타날 때까지 기다릴지 여부(기본값: true)
• format (선택 사항): 이미지 형식 - "png", "jpeg" 또는 "webp"(기본값: "png")
• quality (선택 사항): 이미지 품질(0-100), jpeg 및 webp에만 적용 가능
• padding (선택 사항): 요소 주위의 픽셀 패딩(기본값: 0)
• useSavedAuth (선택 사항): 이전 로그인에서 저장된 쿠키를 사용할지 여부(기본값: true)
• useDefaultBrowser (선택 사항): 시스템의 기본 브라우저를 사용할지 여부(기본값: false)
• visibleBrowser (선택 사항): 브라우저 창을 표시할지 여부(기본값: false)

4. clear-auth-cookies

특정 도메인이나 모든 도메인에 대해 저장된 인증 쿠키를 지웁니다.

• url (선택 사항): 쿠키를 삭제할 도메인의 URL입니다. 지정하지 않으면 모든 쿠키가 삭제됩니다.

기본 브라우저 모드

기본 브라우저 모드를 사용하면 Puppeteer에 기본으로 제공되는 Chromium 대신 시스템의 일반 브라우저(Chrome, Edge 등)를 사용할 수 있습니다. 이 기능은 다음과 같은 경우에 유용합니다.

1. 기존 브라우저 세션 및 확장 프로그램 사용
2. 저장된 자격 증명을 사용하여 웹사이트에 수동으로 로그인
3. 여러 단계로 구성된 워크플로에 대해 보다 자연스러운 검색 환경을 제공합니다.
4. 사용자와 동일한 브라우저 환경에서 테스트

기본 브라우저 모드를 활성화하려면 도구 매개변수에서 useDefaultBrowser: true 및 visibleBrowser: true 설정합니다.

기본 브라우저 모드 작동 방식

기본 브라우저 모드를 활성화하는 경우:

1. 이 도구는 시스템의 기본 브라우저(Chrome, Edge 등)를 찾으려고 시도합니다.
2. 원격 디버깅이 활성화된 임의의 포트에서 브라우저를 시작합니다.
3. Puppeteer는 자체 인스턴스를 시작하는 대신 이 브라우저 인스턴스에 연결합니다.
4. 세션 중에 기존 프로필, 확장 프로그램 및 쿠키를 사용할 수 있습니다.
5. 브라우저 창은 계속 표시되므로 수동으로 상호 작용할 수 있습니다.

이 모드는 인증이나 복잡한 사용자 상호 작용이 필요한 워크플로에 특히 유용합니다.

브라우저 지속성

MCP 서버는 여러 도구 호출에 걸쳐 지속적인 브라우저 세션을 유지할 수 있습니다.

1. login-and-wait 사용하면 브라우저 세션이 계속 열려 있습니다.
2. reuseAuthPage: true 사용하여 screenshot-page 또는 screenshot-element 에 대한 후속 호출은 동일한 페이지를 사용합니다.
3. 이를 통해 재인증 없이도 여러 단계의 워크플로가 가능합니다.

쿠키 관리

방문하는 각 도메인에 대한 쿠키가 자동으로 저장됩니다.

1. login-and-wait 사용한 후 쿠키는 홈 폴더의 .mcp-screenshot-cookies 디렉토리에 저장됩니다.
2. 이 쿠키는 useSavedAuth: true 로 동일한 도메인을 다시 방문할 때 자동으로 로드됩니다.
3. clear-auth-cookies 도구를 사용하여 쿠키를 지울 수 있습니다.

워크플로 예시: 보호된 페이지 스크린샷

인증이 필요한 페이지의 스크린샷을 찍는 워크플로의 예는 다음과 같습니다.

1. 수동 로그인 단계

기본 브라우저에서 로그인 페이지가 열립니다. 수동으로 로그인할 수 있으며, 로그인이 완료되면(성공 표시기를 감지하거나 로그인 페이지에서 나가서) 세션 쿠키가 저장됩니다.

2. 저장된 세션을 사용하여 스크린샷 찍기

이렇게 하면 동일한 브라우저 창에 저장된 인증 쿠키를 사용하여 계정 페이지의 스크린샷이 만들어집니다.

3. 특정 요소의 스크린샷 찍기

4. 완료되면 쿠키 지우기

이 워크플로를 사용하면 일반 사용자처럼 보호된 페이지와 상호 작용하여 기본 브라우저에서 전체 인증 흐름을 완료할 수 있습니다.

헤드리스 모드 vs. 표시 모드

• 헤드리스 모드 ( visibleBrowser: false ): 사용자 상호 작용이 필요 없는 자동화된 워크플로에 더 적합하고 더 빠릅니다.
• 표시 모드 ( visibleBrowser: true ): 브라우저 창을 표시하여 사용자 상호 작용 및 수동 확인이 가능합니다. useDefaultBrowser: true 에 필수입니다.

플랫폼 지원

기본 브라우저 감지 기능은 다음에서 작동합니다.

• macOS : Chrome, Edge, Safari 감지
• Windows : 레지스트리 또는 일반 설치 경로를 통해 Chrome 및 Edge 감지
• Linux : 시스템 명령을 통해 Chrome 및 Chromium 감지

문제 해결

일반적인 문제

1. 기본 브라우저를 찾을 수 없음 : 시스템이 기본 브라우저를 찾을 수 없는 경우 Puppeteer의 기본 제공 Chromium을 사용합니다.
2. 연결 문제 : 브라우저의 디버깅 포트에 연결하는 데 문제가 있는 경우 다른 인스턴스가 이미 해당 포트를 사용하고 있는지 확인하세요.
3. 쿠키 문제 : 인증이 작동하지 않는 경우 clear-auth-cookies 도구를 사용하여 쿠키를 지워보세요.

디버깅

MCP 서버는 문제 발생 시 콘솔에 유용한 오류 메시지를 기록합니다. 문제 해결 정보는 이 메시지를 확인하세요.