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

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

핵심 문제 및 해결책

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

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

MCP 호스트(WSL에서 실행되는 AI 어시스턴트와 유사)는 save_screenshot_to_host_workspace 도구를 호출하고 WSL 작업 공간 경로를 인수로 제공합니다.
이 서버(Windows에서 실행)는 화면을 캡처합니다.
서버는 수신된 WSL 경로를 Windows에서 액세스할 수 있는 UNC 경로(예: \\wsl$\Distro\path )로 변환합니다.
서버는 UNC 경로를 통해 호스트의 WSL 파일 시스템 내의 지정된 위치에 스크린샷을 저장합니다.
서버는 "success" 또는 "failed:..." 반환합니다.
MCP 호스트는 파일이 해당 작업 공간(경로 인수에 지정된 경우 하위 디렉토리)에 저장되어 있다는 것을 알고 있습니다.
그러면 MCP 호스트가 WSL 경로를 이미지 분석을 위해 다른 특수 MCP 서버(WSL에서 실행)로 전달할 수 있습니다.

대체 워크플로(일반):

MCP 호스트는 선택적으로 파일 이름을 지정하여 take_screenshot_and_return_path 호출합니다.
서버는 스크린샷을 로컬 images/ 디렉토리에 저장합니다.
서버는 저장된 파일의 절대 경로 (예: Windows 경로)를 반환합니다.
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 설정:

프로젝트 위치: 이 screenshot-server 프로젝트 폴더를 Windows 파일 시스템 (예: C:\Users\YourUser\projects\screenshot-server )에 놓습니다.
Windows 종속성: 프로젝트 폴더 내에서 Python, uv 및 프로젝트 종속성( uv sync ... )을 Windows 에 직접 설치합니다.
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)

AI Assistant는 현재 작업 공간 경로(예: /home/user/current_project )를 식별합니다.
AI Assistant는 use_mcp_tool 사용하여 Screenshot-server 에서 save_screenshot_to_host_workspace 호출하고, host_workspace_path="/home/user/current_project" 와 선택적으로 name 전달합니다.
"success" 받습니다.
AI Assistant는 스크린샷이 이제 /home/user/current_project/workspace_screenshot.jpg (또는 지정된 이름)에 있다는 것을 알고 있습니다.
AI Assistant는 use_mcp_tool 사용하여 이미지 분석 서버/도구(WSL에서 실행 중)를 호출하고 WSL 경로 /home/user/current_project/workspace_screenshot.jpg 전달합니다.
이미지 분석 서버는 파일을 읽고 작업을 수행합니다.

파일 구조

screenshot.py : MCP 서버 핵심 스크립트.
README.md : 이 문서 파일입니다.
pyproject.toml : uv 에 대한 프로젝트 정의 및 종속성.
uv.lock : 종속성 잠금 파일.
.gitignore : Git이 구성을 무시합니다.
.python-version : (선택 사항) Python 버전 지정자.
server.log : 서버에서 생성된 로그 파일.
images/ : take_screenshot_and_return_path 의 기본 디렉토리입니다.

Screenshot MCP Server

Integrations