스크린샷 서버(파일 경로 중심)

이 프로젝트는 스크린샷을 캡처하고 다른 프로세스나 AI 어시스턴트가 이를 사용할 수 있도록 돕기 위해 설계된 MCP(모듈형 통신 프로토콜) 서버를 제공합니다. 주로 클라이언트(호스트)가 지정한 파일 경로에 스크린샷을 저장합니다 .

핵심 문제 및 해결책

AI 비서가 MCP를 통해 전송한 스크린샷 이미지 데이터를 직접 해석하는 방식은 테스트에서 신뢰할 수 없는 것으로 나타났습니다. 이 서버는 파일 경로에 초점을 맞춘 더욱 강력한 워크플로를 채택했습니다.

권장 워크플로(WSL 호스트 -> Windows Server):

1. MCP 호스트(WSL에서 실행되는 AI 어시스턴트와 유사)는 save_screenshot_to_host_workspace 도구를 호출하고 WSL 작업 공간 경로를 인수로 제공합니다.

2. 이 서버(Windows에서 실행)는 화면을 캡처합니다.

3. 서버는 수신된 WSL 경로를 Windows에서 액세스할 수 있는 UNC 경로(예: \\wsl$\Distro\path )로 변환합니다.

4. 서버는 UNC 경로를 통해 호스트의 WSL 파일 시스템 내의 지정된 위치에 스크린샷을 저장합니다.

5. 서버는 "success" 또는 "failed:..." 반환합니다.

6. MCP 호스트는 파일이 해당 작업 공간(경로 인수에 지정된 경우 하위 디렉토리)에 저장되어 있다는 것을 알고 있습니다.

7. 그러면 MCP 호스트가 WSL 경로를 이미지 분석을 위해 다른 특수 MCP 서버(WSL에서 실행)로 전달할 수 있습니다.

대체 워크플로(일반):

1. MCP 호스트는 선택적으로 파일 이름을 지정하여 take_screenshot_and_return_path 호출합니다.

2. 서버는 스크린샷을 로컬 images/ 디렉토리에 저장합니다.

3. 서버는 저장된 파일의 절대 경로 (예: Windows 경로)를 반환합니다.

4. MCP 호스트는 경로를 수신하여 분석 서버로 전달합니다(변환 가능성 포함).

사용 가능한 도구

이 서버는 권장 사용법에 따라 정렬된 다음 도구를 제공합니다.

• save_screenshot_to_host_workspace(host_workspace_path: str, name: str = "workspace_screenshot.jpg")

  • 권장 사용 방법: AI Assistant(호스트)의 현재 WSL 작업 공간에 스크린샷을 직접 저장합니다. 원활한 통합을 위해 권장되는 방법입니다.

  • 작업: 스크린샷을 찍고, 제공된 WSL 경로를 UNC 경로로 변환하여 호스트의 작업 공간에 파일을 저장합니다. WSL 배포판 이름을 자동으로 감지합니다.

  • 인수:

    • host_workspace_path (str): 호스트 작업 공간의 절대 WSL 경로(예: /home/user/project ).

    • name (str, 선택 사항): 파일 이름. 기본값은 workspace_screenshot.jpg 입니다.

  • 반환값: str - "success" 또는 "failed: [error message]" .

• take_screenshot_and_return_path(name: str = "latest_screenshot.jpg")

  • 사용 사례: 서버 위치를 기준으로 고정된 images/ 디렉터리에 스크린샷을 저장하고 절대 경로(일반적으로 Windows 경로)를 반환합니다. 호출자가 외부 처리를 위해 경로가 필요한 경우 유용합니다.

  • 인수:

    • name (str, 선택 사항): 파일 이름. 기본값은 latest_screenshot.jpg 입니다.

  • 반환값: str - 절대 경로 또는 "failed: [error message]" .

• take_screenshot_path(path: str = "./", name: str = "screenshot.jpg")

  • 사용 사례: Windows 경로 또는 UNC 경로로 지정된 임의의 위치에 스크린샷을 저장합니다(예: 호스트 작업 영역 외부에 저장하는 경우). 호출자가 신중하게 경로를 지정해야 합니다.

  • 인수:

    • path (str, 선택 사항): 대상 디렉터리(Windows 또는 UNC 경로). 기본값은 서버의 작업 디렉터리입니다.

    • name (str, 선택 사항): 파일 이름. 기본값은 screenshot.jpg 입니다.

  • 반환값: str - "success" 또는 "failed: [error message]" .

설정 및 사용

1. 필수 조건

• Python 3.x: 서버가 실행되는 컴퓨터에 필요합니다.

• 종속성: uv 사용하여 설치:

  지엑스피1

  필수 라이브러리에는 mcp[cli]>=1.4.1 , pyautogui 및 Pillow 포함됩니다.

2. 서버 실행

이 서버는 일반적으로 구성에 따라 MCP 호스트 에 의해 실행됩니다.

3. 환경 고려 사항(특히 WSL2)

중요 사항: Windows 화면을 캡처하려면 이 screenshot.py 서버가 Windows에서 직접 실행되어야 합니다 .

권장 WSL2 호스트 -> Windows Server 설정:

1. 프로젝트 위치: 이 screenshot-server 프로젝트 폴더를 Windows 파일 시스템 (예: C:\Users\YourUser\projects\screenshot-server )에 놓습니다.

2. Windows 종속성: 프로젝트 폴더 내에서 Python, uv 및 프로젝트 종속성( uv sync ... )을 Windows 에 직접 설치합니다.

3. MCP 호스트 구성(WSL): PowerShell을 사용하여 Windows에서 서버를 실행하도록 MCP 호스트(WSL에서 실행)를 구성합니다. mcp_settings.json (또는 이와 동등한 파일)을 업데이트합니다.

   { "mcpServers": { "Screenshot-server": { "command": "powershell.exe", "args": [ "-Command", "Invoke-Command -ScriptBlock { cd '<YOUR_WINDOWS_PROJECT_PATH>'; & '<YOUR_WINDOWS_UV_PATH>' run screenshot.py }" ] } // ... other servers ... } }

   • 경로를 실제 Windows 경로로 바꾸세요.

4. 워크플로우 예시(WSL의 AI Assistant)

1. AI Assistant는 현재 작업 공간 경로(예: /home/user/current_project )를 식별합니다.

2. AI Assistant는 use_mcp_tool 사용하여 Screenshot-server 에서 save_screenshot_to_host_workspace 호출하고, host_workspace_path="/home/user/current_project" 와 선택적으로 name 전달합니다.

3. "success" 받습니다.

4. AI Assistant는 스크린샷이 이제 /home/user/current_project/workspace_screenshot.jpg (또는 지정된 이름)에 있다는 것을 알고 있습니다.

5. AI Assistant는 use_mcp_tool 사용하여 이미지 분석 서버/도구(WSL에서 실행 중)를 호출하고 WSL 경로 /home/user/current_project/workspace_screenshot.jpg 전달합니다.

6. 이미지 분석 서버는 파일을 읽고 작업을 수행합니다.

파일 구조

• screenshot.py : MCP 서버 핵심 스크립트.

• README.md : 이 문서 파일입니다.

• pyproject.toml : uv 에 대한 프로젝트 정의 및 종속성.

• uv.lock : 종속성 잠금 파일.

• .gitignore : Git이 구성을 무시합니다.

• .python-version : (선택 사항) Python 버전 지정자.

• server.log : 서버에서 생성된 로그 파일.

• images/ : take_screenshot_and_return_path 의 기본 디렉토리입니다.