@just-every/mcp-screenshot-website-fast

CLI 코딩 도구에 최적화된 빠르고 효율적인 웹 페이지 스크린샷 캡처 도구입니다. 전체 페이지를 최적의 처리를 위해 자동으로 1072x1072 청크로 타일링합니다.

개요

AI 비전 워크플로우를 위해 특별히 제작된 이 도구는 Claude Vision API 및 기타 AI 모델에서 최적으로 처리할 수 있도록 자동 해상도 제한 및 타일링 기능을 갖춘 고품질 스크린샷을 캡처합니다. 최대 호환성을 위해 스크린샷 크기를 1072x1072 픽셀(1.15 메가픽셀)로 완벽하게 조정합니다.

Related MCP server: ScreenshotOne MCP Server

주요 기능

• 📸 빠른 스크린샷 캡처: Puppeteer 헤드리스 브라우저 사용

• 🎯 Claude Vision 최적화: 자동 해상도 제한 (최적의 1.15 메가픽셀을 위한 1072x1072)

• 🔲 자동 타일링: 전체 페이지를 1072x1072 타일로 자동 분할

• 🎬 스크린캐스트 캡처: 구성 가능한 간격으로 일련의 스크린샷 기록

• 🔄 항상 최신 콘텐츠: 캐싱을 사용하지 않아 항상 최신 스크린샷 보장

• 📱 구성 가능한 뷰포트: 반응형 테스트 지원

• ⏱️ 대기 전략: 동적 콘텐츠를 위한 대기 전략 (networkidle, 사용자 지정 지연)

• 📄 전체 페이지 캡처: 기본적으로 전체 페이지 스크린샷 캡처

• 🎥 애니메이션 WebP 내보내기: 스크린캐스트를 고품질 애니메이션 WebP 파일로 저장

• 💉 JavaScript 주입: 스크린캐스트 캡처 전 사용자 지정 JS 실행

• 📦 최소한의 의존성: 빠른 npm 설치

• 🔌 MCP 통합: 원활한 AI 워크플로우 지원

• 🪟 Windows 호환 런처: npm 설치 MCP 사용 지원

• 🔋 리소스 효율성: 60초 동안 활동이 없으면 브라우저 자동 정리

• 🧹 메모리 관리: 누수 방지를 위해 각 스크린샷 후 페이지 닫기

설치

Claude Code

claude mcp add screenshot-website-fast -s user -- npx -y @just-every/mcp-screenshot-website-fast

VS Code

code --add-mcp '{"name":"screenshot-website-fast","command":"npx","args":["-y","@just-every/mcp-screenshot-website-fast"]}'

Cursor

cursor://anysphere.cursor-deeplink/mcp/install?name=screenshot-website-fast&config=eyJzY3JlZW5zaG90LXdlYnNpdGUtZmFzdCI6eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqdXN0LWV2ZXJ5L21jcC1zY3JlZW5zaG90LXdlYnNpdGUtZmFzdCJdfX0=

JetBrains IDEs

설정 → 도구 → AI Assistant → Model Context Protocol (MCP) → 추가

"JSON으로"를 선택하고 다음을 붙여넣으세요:

{"command":"npx","args":["-y","@just-every/mcp-screenshot-website-fast"]}

Raw JSON (모든 MCP 클라이언트에서 작동)

{
  "mcpServers": {
    "screenshot-website-fast": {
      "command": "npx",
      "args": ["-y", "@just-every/mcp-screenshot-website-fast"]
    }
  }
}

이 내용을 클라이언트의 mcp.json(예: .vscode/mcp.json, ~/.cursor/mcp.json 또는 Claude의 경우 .mcp.json)에 추가하세요.

사전 요구 사항

• Node.js 20.x 이상

• npm 또는 npx

• Chrome/Chromium (Puppeteer가 자동으로 다운로드)

빠른 시작

MCP 서버 사용

IDE에 설치되면 다음 도구를 사용할 수 있습니다:

사용 가능한 도구

• take_screenshot - 웹 페이지의 고품질 스크린샷을 캡처합니다.

  • 매개변수:

    • url (필수): 캡처할 HTTP/HTTPS URL

    • width (선택): 뷰포트 너비(픽셀 단위, 최대 1072, 기본값: 1072)

    • height (선택): 뷰포트 높이(픽셀 단위, 최대 1072, 기본값: 1072)

    • fullPage (선택): 타일링을 포함한 전체 페이지 스크린샷 캡처 (기본값: true)

    • waitUntil (선택): 대기 이벤트: load, domcontentloaded, networkidle0, networkidle2 (기본값: domcontentloaded)

    • waitFor (선택): 추가 대기 시간(밀리초 단위)

    • directory (선택): 스크린샷을 저장할 디렉토리 - base64 이미지 대신 파일 경로 반환

• capture_selector - CSS 선택자로 일치하는 특정 DOM 요소의 스크린샷을 캡처합니다.

  • 매개변수:

    • url (필수): 캡처할 HTTP/HTTPS URL

    • selector (필수): 캡처할 요소의 CSS 선택자

    • width (선택): 뷰포트 너비(픽셀 단위, 최대 1072, 기본값: 1072)

    • height (선택): 뷰포트 높이(픽셀 단위, 최대 1072, 기본값: 1072)

    • waitUntil (선택): 대기 이벤트: load, domcontentloaded, networkidle0, networkidle2 (기본값: domcontentloaded)

    • waitForMS (선택): 추가 대기 시간(밀리초 단위)

    • selectorTimeoutMS (선택): 선택자가 나타날 때까지 기다리는 시간(기본값: 5000)

사용 예시

기본 사용법 (base64 이미지 반환):

take_screenshot(url="https://example.com")

디렉토리에 저장 (파일 경로 반환):

take_screenshot(url="https://example.com", directory="/path/to/screenshots")

특정 요소 캡처:

capture_selector(url="https://example.com", selector="#main")

directory 매개변수 사용 시:

• 스크린샷은 타임스탬프가 포함된 PNG 파일로 저장됩니다.

• base64 데이터 대신 파일 경로가 반환됩니다.

• 타일링된 스크린샷의 경우 각 타일이 별도의 파일로 저장됩니다.

• 디렉토리가 없으면 자동으로 생성됩니다.

take_screencast

시간에 따른 일련의 스크린샷을 캡처하여 스크린캐스트를 만듭니다. 뷰포트의 상단 타일(1072x1072)만 캡처합니다.

매개변수

• url (필수): 캡처할 URL

• duration (선택): 전체 지속 시간(초 단위, 기본값: 10)

• interval (선택): 스크린샷 간격(초 단위, 기본값: 2)

• jsEvaluate (선택): 시작 시 실행할 JavaScript 코드

• waitUntil (선택): 대기 전략: 'load', 'domcontentloaded', 'networkidle0', 'networkidle2'

• waitForMS (선택): 시작 전 추가 대기 시간

• directory (선택): 애니메이션 WebP로 디렉토리에 저장 (1초마다 캡처)

사용 예시

기본 스크린캐스트 (10초 동안 5프레임):

take_screencast(url="https://example.com")

사용자 지정 타이밍:

take_screencast(url="https://example.com", duration=15, interval=3)

JavaScript 실행 포함:

take_screencast(
  url="https://example.com",
  jsEvaluate="document.body.style.backgroundColor = 'red';"
)

애니메이션 WebP로 저장:

take_screencast(url="https://example.com", directory="/path/to/output")

directory 매개변수 사용 시:

• 1초 간격으로 애니메이션 WebP가 생성됩니다.

• 개별 프레임도 PNG 파일로 저장됩니다.

• 애니메이션은 기본적으로 무한 반복됩니다.

• WebP는 뛰어난 품질을 제공합니다:

  • 전체 색상 지원 (256색 제한 없음)

  • 웹 애니메이션을 위한 효율적인 압축

  • 그라데이션 배경 및 부드러운 애니메이션에 최적

  • GIF 대비 더 나은 품질과 작은 파일 크기

개발 사용법

설치

npm install
npm run build

스크린샷 캡처

# Full page with automatic tiling (default)
npm run dev capture https://example.com -o screenshot.png

# Viewport-only screenshot  
npm run dev capture https://example.com --no-full-page -o screenshot.png

# Wait for specific conditions
npm run dev capture https://example.com --wait-until networkidle0 --wait-for 2000 -o screenshot.png

CLI 옵션

• -w, --width <pixels> - 뷰포트 너비 (최대 1072, 기본값: 1072)

• -h, --height <pixels> - 뷰포트 높이 (최대 1072, 기본값: 1072)

• --no-full-page - 전체 페이지 캡처 및 타일링 비활성화

• --wait-until <event> - 대기 이벤트: load, domcontentloaded, networkidle0, networkidle2

• --wait-for <ms> - 추가 대기 시간(밀리초 단위)

• -o, --output <path> - 출력 파일 경로 (타일링 출력 시 필수)

자동 재시작 기능

MCP 서버는 신뢰성 향상을 위해 기본적으로 자동 재시작 기능을 포함합니다:

• 충돌 시 서버 자동 재시작

• 처리되지 않은 예외 및 프로미스 거부 처리

• 지수 백오프 구현 (1분 내 최대 10회 시도)

• 모니터링을 위한 모든 재시작 시도 기록

• 종료 신호(SIGINT, SIGTERM)를 정상적으로 처리

자동 재시작 없이 개발/디버깅하려면:

# Run directly without restart wrapper
npm run serve:dev

아키텍처

mcp-screenshot-website-fast/
├── src/
│   ├── internal/       # Core screenshot capture logic
│   ├── utils/          # Logger and utilities
│   ├── index.ts        # CLI entry point
│   ├── serve.ts        # MCP server entry point
│   └── serve-restart.ts # Auto-restart wrapper

개발

# Run in development mode
npm run dev capture https://example.com -o screenshot.png

# Build for production
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

# Linting
npm run lint

왜 이 도구인가?

AI 비전 워크플로우를 위해 특별히 제작되었습니다:

1. Claude Vision API 최적화 - 1072x1072 픽셀(1.15 메가픽셀)로 자동 해상도 제한

2. 자동 타일링 - AI 처리를 위해 전체 페이지를 완벽한 청크로 분할

3. 항상 최신 상태 - 캐싱을 사용하지 않아 최신 콘텐츠 보장

4. MCP 네이티브 - AI 개발 도구와 일류 통합

5. 간단한 API - 스크린샷 캡처를 위한 깔끔하고 직관적인 인터페이스

기여

기여를 환영합니다! 다음 단계를 따라주세요:

1. 저장소 포크

2. 기능 브랜치 생성

3. 새로운 기능에 대한 테스트 추가

4. 풀 리퀘스트 제출

문제 해결

Puppeteer 문제

• Chrome/Chromium이 다운로드 가능한지 확인

• 방화벽 설정 확인

• PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true를 설정하고 사용자 지정 실행 파일을 제공해 보세요.

스크린샷 품질

• 뷰포트 크기 조정

• 적절한 대기 전략 사용

• 사이트 인증 필요 여부 확인

시간 초과 오류

• --wait-for 플래그로 대기 시간 증가

• 다른 --wait-until 전략 사용

• 사이트 접속 가능 여부 확인

라이선스

MIT