퍼펫티어 MCP 서버

이 MCP 서버는 Puppeteer를 통해 브라우저 자동화 기능을 제공하여 새로운 브라우저 인스턴스와 기존 Chrome 창 모두와의 상호 작용을 허용합니다.

승인

이 프로젝트는 @modelcontextprotocol/server-puppeteer 에서 영감을 받아 실험적으로 구현한 것입니다. 유사한 목표와 개념을 공유하지만, Model Context Protocol을 통해 브라우저 자동화에 대한 대안적인 접근 방식을 모색합니다.

특징

• 웹 페이지 탐색
• 스크린샷 찍기
• 클릭 요소
• 양식 작성
• 옵션 선택
• 호버 요소
• JavaScript 실행
• 스마트한 Chrome 탭 관리:
  • 활성 Chrome 탭에 연결
  • 기존 Chrome 인스턴스 보존
  • 지능형 연결 처리

프로젝트 구조

지엑스피1

설치

옵션 1: npm에서 설치

npx를 사용하면 설치 없이 바로 실행할 수도 있습니다.

옵션 2: 소스에서 설치

1. 이 저장소를 복제하거나 소스 코드를 다운로드하세요
2. 종속성 설치:

3. 프로젝트를 빌드하세요:

4. 서버를 실행합니다:

MCP 서버 구성

Claude와 함께 이 도구를 사용하려면 MCP 설정 구성 파일에 추가해야 합니다.

Claude 데스크톱 앱용

Claude Desktop 구성 파일(Windows에서는 %APPDATA%\Claude\claude_desktop_config.json , macOS에서는 ~/Library/Application Support/Claude/claude_desktop_config.json )에 다음을 추가합니다.

npm을 통해 전역적으로 설치하는 경우:

npx 사용(설치 없이):

소스에서 설치한 경우:

Claude VSCode 확장 프로그램용

Claude VSCode 확장 MCP 설정 파일에 다음을 추가합니다(Windows에서는 %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json 에 있고, macOS에서는 ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json 에 있음).

npm을 통해 전역적으로 설치하는 경우:

npx 사용(설치 없이):

소스에서 설치한 경우:

소스 설치의 경우, path/to/puppeteer-mcp-server 이 도구를 설치한 실제 경로로 바꾸세요.

용법

표준 모드

서버는 기본적으로 새로운 브라우저 인스턴스를 시작합니다.

활성 탭 모드

기존 Chrome 창에 연결하려면:

1. 기존 Chrome 인스턴스를 완전히 닫습니다.
2. 원격 디버깅을 활성화하여 Chrome을 실행합니다.
   # Windows "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 # macOS /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 # Linux google-chrome --remote-debugging-port=9222
3. Chrome에서 원하는 웹 페이지로 이동합니다.
4. puppeteer_connect_active_tab 도구를 사용하여 연결합니다.
   { "targetUrl": "https://example.com", // Optional: specific tab URL "debugPort": 9222 // Optional: defaults to 9222 }

서버는 다음을 수행합니다.

• 원격 디버깅이 활성화된 Chrome 인스턴스를 감지하고 연결합니다.
• Chrome 인스턴스를 보존합니다(닫지 않음)
• 확장 기능이 없는 탭을 찾아 연결
• 연결에 실패하면 명확한 오류 메시지를 제공합니다.

사용 가능한 도구

퍼펫티어_커넥트_액티브_탭

원격 디버깅이 활성화된 기존 Chrome 인스턴스에 연결합니다.

• 선택 과목:
  • targetUrl - 연결할 특정 탭의 URL
  • debugPort - Chrome 디버깅 포트(기본값: 9222)

꼭두각시 조종자_탐색

URL로 이동합니다.

• 필수: url - 이동할 URL

인형 조종사 스크린샷

현재 페이지나 특정 요소의 스크린샷을 찍습니다.

• 필수: name - 스크린샷의 이름
• 선택 과목:
  • selector - 스크린샷을 찍을 요소에 대한 CSS 선택기
  • width - 픽셀 단위 너비(기본값: 800)
  • height - 픽셀 단위 높이(기본값: 600)

꼭두각시_클릭

페이지에서 요소를 클릭합니다.

• 필수: selector - 클릭할 요소에 대한 CSS 선택기

인형극_채우기

입력 필드를 작성하세요.

• 필수의:
  • selector - 입력 필드용 CSS 선택기
  • value - 입력할 텍스트

꼭두각시 선택

드롭다운 메뉴를 사용하세요.

• 필수의:
  • selector - 선택 요소에 대한 CSS 선택기
  • value - 선택할 옵션 값

인형극 배우기_호버

요소 위에 마우스를 올려놓으세요.

• 필수: selector - 마우스를 올려놓을 요소에 대한 CSS 선택기

인형극 평가자

브라우저 콘솔에서 JavaScript를 실행합니다.

• 필수: script - 실행할 JavaScript 코드

보안 고려 사항

원격 디버깅을 사용하는 경우:

• 신뢰할 수 있는 네트워크에서만 활성화
• 고유한 디버깅 포트를 사용하세요
• 사용하지 않을 때 디버깅 포트를 닫습니다.
• 디버깅 포트를 공개 네트워크에 노출하지 마십시오.

로깅 및 디버깅

파일 기반 로깅

서버는 Winston을 사용하여 포괄적인 로깅을 구현합니다.

• 위치: logs/ 디렉토리
• 파일 패턴: mcp-puppeteer-YYYY-MM-DD.log
• 로그 회전:
  • 매일 회전
  • 최대 크기: 파일당 20MB
  • 보관 기간: 14일
  • 오래된 로그의 자동 압축

로그 수준

• DEBUG: 자세한 디버깅 정보
• INFO: 일반 운영 정보
• WARN: 경고 메시지
• 오류: 오류 이벤트 및 예외

기록된 정보

• 서버 시작/종료 이벤트
• 브라우저 작업(시작, 연결, 닫기)
• 탐색 시도 및 결과
• 도구 실행 및 결과
• 스택 추적을 포함한 오류 세부 정보
• 브라우저 콘솔 출력
• 리소스 사용량(스크린샷, 콘솔 로그)

오류 처리

서버는 다음에 대한 자세한 오류 메시지를 제공합니다.

• 연결 실패
• 누락된 요소
• 잘못된 선택자
• JavaScript 실행 오류
• 스크린샷 실패

각 도구 호출은 다음을 반환합니다.

• 성공/실패 상태
• 실패 시 자세한 오류 메시지
• 성공 시 작업 결과 데이터

모든 오류는 다음과 같은 로그 파일에 기록됩니다.

• 타임스탬프
• 오류 메시지
• 스택 추적(사용 가능한 경우)
• 컨텍스트 정보

기여하다

기여를 환영합니다! 풀 리퀘스트 제출, 문제 보고, 프로젝트 참여 방법에 대한 자세한 내용은 기여 가이드라인을 참조하세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.