Screen Observer MCP

Claude Code 및 기타 MCP 클라이언트를 위간 로컬, 읽기 전용 Windows 11 화면 관찰 서비스역입니다. 제한된, 프라이버시 필터링 방식의 인메모리 프레임 모델을 진단 CLI 명령과 8개의 MCP stdio 도구로 노출합니다. 관찰은 에이전트가 명시적으로 결정합니다: 클라이언트가 수집 이 시작하고 중지할 지를는 결정합니다.

Requirements / 요구 사항

• 실제 화면 캡터와 UI 자동화를 위한 Windows 11.

• Python 3.12.

Related MCP server: blade-computer-use

개발 환경 구성

*Windows 11 및 실제 capture -

설치 후 해석된 의존성 export를 생성합니다.

py -3.12 -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"

생성된 export에는 이 체크아우트에 대는 야시한 editable인 절대 Windows 경로가 포함될 있습니다. 다른 체크아웃에서 제3자 버전을 재현하려는, 그 editable 행을 필터링하고 하여 현재 체크아웃를 별도로 설치하세요.

.venv\Scripts\python -m pip freeze --local > requirements.lock.txt

CLI

설치된 엔트리 포인트와 모듈 엔트리 포인트는 동일한 프로덕션 StateService를 사용합니다.

.venv\Scripts\screen-observer --help
.venv\Scripts\python -m screen_observer.main --help
.venv\Scripts\screen-observer status

status는 기계가 읽을 수 있는 JSON 문서 하나를 출력합니다. start와 stop 같은, 해당 명령 프로세스. 내에 생성된 수집기만 affect합니다. 이 버전에는 데몬이나 프로세스 간 IPC가 없으므로, 모델이 제어하는 장기 실행 확인해야 할 MCP 생명주기 도구를 통해 진행합니다. 읽기 측 하위 명령(snapshot, ui-tree, watch)은 MCP 도구와 1:1 중복이 되었고 제거되었습니다. 같은 페이로드가 필요하면 MCP 도구에 사용하세요.

MCP stdio 서버

.venv\Scripts\screen-observer mcp

MCP 전송을 다음을 지정하여 시작합니다.

정확히 10개의 도구를 등록합니다.

• screen_observe_start — 작가가 제어하는 관찰 세션을 시작합니다, 동기적으로 첫 번째 마스킹된 프레임을 게시한 후 백그라운드 수집을 시작합니다. 응답에는 ready: true 신호와 capabilities, 있는 게시되며, firstFrame 요약이 포함되어 에이전트가 추가 왕복 없이-준비가 되었는지 확인 할 수 있습니다.

• screen_observe_stop — 세션을 종료합니다; 수집기를 조--하고, 현재 상태, 원시-윈도 컨텍스트, 메모리 링에 남아 있는 모든 프레임을 지웁니다. 응답에는 요약 블록(경과 시간, 캡처된 프레임, 활성 창 변겅, 마지막 활성 창)이 있어 에이전트가 종료 전에 관찰 창구간을 검특할 수 있니다.

• screen_get_state

• screen_wait_for_change

• screen_wait_for_title — 활성 창 제목에 부분 문자열이 포함되거나, 대기 시한이 지날 때까지 차단합니다. "빌르드 미널에 Build successful이 표시로 대기" 등에 유용합니다.

• screen_wait_for_idle — 게시된 리비전이 N ms 동인 변겹 없시 or 기한이 지날 때까지 차단합니다. "화면이 업데이터를 멈추었 이니 작업이 끝단" 상항을 감지하는 데 유용합니다.

• screen_get_ui_tree

• screen_get_region

• screen_get_frame_history — 인메모리 라에서 최신 마스킹된 프레임 N개까지 가저옵니다.

• screen_get_frame — 특정 revision의 마스킹된 프레임 하나를 가져옵니다.

MCP 서버는 초기화만으로 화면 수집을 시자하지 않습니다. 에이전트는 screen_observe_start를 호출하여 관찰 창구를 정하고, 필요한 시간성(초, 몇 분, 작업이 끝날 때까시) 동안 읽기 도구로 읽은 다움 screen_observe_stop를 호출합니다. 시작 전과 정지 후 모든 읽기 도구는 구조화된 observer_not_started 오류를 반환합니다. Stop은 인메모리 데이터의 경계입니다: 지 -간 상 and 등 frame/state pipe line 접sible_ and not write to disk.,

기본적으로 상태는 JSON뿐입니다. screen_get_state는 include_image=true인 경우에만 이미지 데이터를 반환합니다. screen_get_region은 명시적 로컬 지역 이미지 도구입니다. 두 게시 도구도 include_image=true와 선택적인 제한 region를 지원됩니다. 이미지는 소스 영역 좌표에서 개인정보 필터가 적용되고, 인메모리 Base64 PNG로 인코딩되고, 바이너리-이미지와 전체음답 제한에 의해 바운딩됩니다. 프레임은 제한된 인메모리 링 버퍼(디스크 기록 없음)에서 가져옵니다. 이는 src/screen_observer/domain/limits.py의 RING_DEFAULT_FRAMES, MAX_RING_FRAMES, MAX_RING_BYTES를 참조하세요.

검증된 onedir 아티팩트에 대한 Claude Code MCP 구성 예시는 다음과 같습니다:

{
  "mcpServers": {
    "screen-observer": {
      "command": "C:\\project\\screen-observer-mcp\\dist\\screen-observer\\screen-observer.exe",
      "args": ["mcp"]
    }
  }
}

onedir 디렉터리가 다른 위치에 복사되면 절대 명령 경로를 교체하세요. onefile 아티팩트는 빌드되거나 검득되지 않았습니다.

Build/test observation 에이전트 플레이북

생명주기는 완전에 에이전트가 명시적으로 주도합니다. 아에 세 워크플로우 중 하나를 고를세요. 에이전트가 작업이 끝이났지 판단하는 방식만 다릅니다. 추정할 "관찰 시간"은 없습니다. 작업이 시자하면 시작하고, 조건이 발동되면 곧 바로 중지합니다.

1. 명시적 폴링 (screen_wait_for_change)

가장 익명한 반복 패턴입니다. 에이전트가 매 단계를 직접 실행합니다.

screen_observe_start         # response.ready == true, firstRevision, capabilities, firstFrame
…loop:
  screen_wait_for_change(since_revision, timeout_ms = 5000)
  inspect the result.state to decide whether the task is done
screen_observe_stop          # response.summary carries the session counters

에이전트가 정확히 어떤 UI 요소를 봐야 하는지 알고 있을 때 적합한 형태입니다.

2. 주제 부분 문자열 대기 (screen_wait_for_title)

MCP passer to block until the active window标题 matches.

screen_observe_start
screen_wait_for_title(
    title_contains = "Build successful",
    since_revision = <firstRevision>,
    timeout_ms    = 120000)
# response.matched == true => matchedAtRevision, observedTitle
screen_observe_stop

개인정보 보호 마스킹 정책에 따라 최신 창 제목이 마스킹되었을 때, 오류를 내지 않고 observedRedacted: true를 반환합니다. 따라서 주변 환경이 자주 변하더라도 에이전트가 멈추지 않습니다.

3. 화면 유휴 대기 (screen_wait_for_idle)

변경이 사라지는 것을 기준으로 완료를 판단합니다. 명백한 마커가 없이 끝나는 작업에 적합합니다.

screen_observe_start
screen_wait_for_idle(idle_ms = 3000, since_revision = <firstRevision>, timeout_ms = 120000)
# response.idleReached == true => idleMs, lastObservedRevision
screen_observe_stop

idle_ms는 최대 60,000ms까지 설정할 수 있습니다. 타임아웃은 호출당 공통 30,000ms 제한에 묶여 있습니다. 더 긴 전체 시간이 필요하면 여러 호출을 연결하세요.

PowerShell 래퍼

사람과 일회성 셸 사용자를 위해, scripts/observe-until.ps1은 두 전략 중 하나를 단일 명령으로 요약하고, 에이전트 대신 MCP 서버를 종료합니다:

# Block until a build/test terminal shows "Build successful":
scripts/observe-until.ps1 -WaitForTitle 'Build successful' -TimeoutSec 180

# Block until the screen stops changing for 3 s:
scripts/observe-until.ps1 -WaitForIdleMs 3000 -TimeoutSec 60

이 스크립트는 시작/종료 요약을 로직 파이프라인에 쓰고, 기한 내에 일치하는 결과를 마지 못하면 0이 아닌 코드로 종료합니다.

screen_get_state와 두 히스토리 도구는 기본적으로 JSON을 반환합니다. screen_get_region, screen_get_frame, 그리고 어떤 도구의 include_image=true 옵션도 Base64 PNG를 반환합니다.

• JSON 경로는 텍스트 전용 클라이언트가 필요한 모든 것을 담습니다. 리비전, 화면 지오메트리, 활성 창, UI 트리, 변경 요약. 이 API를 사용하는 데 비전 기능은 필요하지 않습니다.

• PNG 경로는 렌더링된 화면을 해석할 multimodal / vision-capable client (예: 비전을 갖춘 Claude)가 필요합니다. 그렇지 않으면 base64 페이로드는 그저 불투명한 바이트입니다.

클라이언트가 텍스트만 지원하면 include_image=false(기본값)를 지켜 JSON 계약으로 작업을 수행하세요.

Windows onedir 패키지

프로젝트 가상 환경에서 재현 가능한 PyInstaller onedir 아티팩트를 빌드합니다:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_windows.ps1

기대되는 실행 파일은:

dist\screen-observer\screen-observer.exe

빌드 후, 패키지된 CLI/MCP 스모크 테스트 실행:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\smoke_packaged.ps1

스모크 테스트는 --help, status, MCP initialize/list/call 시퀀스를 pytest 임시작업 디렉토리에서 실행합니다 (SCREEN_OBSERVER_PACKAGED_TEST=1 및 gated). 또 그 디렉터리에서 흔한 화면 이미지나 비디오 파일이 만들어지지 않는지 확인합니다. 이 검사는 현재 Windows 호스트에서 onedir 아티팩트를 검증하는 것이며, 독립적이고 깨끗한 Windows 머신에서의 검증을 대체하지는 않습니다.

애플리케이션을 이동할 때는 dist\screen-observer 디렉토리 전체를 복사하세요. 실행 파일은 _internal 디렉토리에 의존합니다. onefile 패키지는 빌드되거나 검증되지 않았습니다.

MCP stdout은 프로토콜 메시지 전용입니다. 진단 메시지는 stderr로 보내지며, 도구 처리기는 파이썬 traceback 없이 구조화된 안전 오류를 반환합니다.

개인정보 및 데이터 수명주기

• 화면 상태와 가장 최신의 공개된 프레임은 제한된 링 버퍼로 메모리에만 유지됩니다. 응용프로그램은 스크린샷, 비디오 또는 화면 데이터 기록을 의도적으로 영구 저장하지 않습니다.

• 이미지 응답은 선택적이며 JSON 상태와 동일한 공개 프레임/리비전/개인정보 컨텍스트를 사용합니다.

• 비밀번호 요소 이름과 값은 공개 전에 제거됩니다.

• 구성된 프로세스, 제목, 물리적 픽셀 부분에 대한 redaction(마스킹)은 리사이즈와 PNG 인코딩 전에 적용됩니다.

• Base64 이미지 데이터와 전체 UI 텍스트 덤프는 진단 로그에 기록되지 않습니다.

• 응용 프로그램 제한이 Windows가 프로세스 메모리를 디스크에 페이징하지 않도록 보장할 수는 없습니다.

캡처 백엔드

DXGI Desktop Duplication (dxcam)이 프로덕션 캡처 경로입니다; 예약 테스트에 사용되는 mss도 주입 가능하도록 유지됩니다. PyInstaller onedir 빌드는 collect_all("dxcam")를 포함해야 하므로 frozen 실행 파일이 번들된 DXGI/D3D11 네이티브 라이브러리를 Windows 11에서 올바르게 해석합니다.

검증

.venv\Scripts\python -m pytest -q
.venv\Scripts\python -m ruff check src tests
.venv\Scripts\python -m mypy
.venv\Scripts\python -m pip check

Windows adapter, stdio protocol, packaged artifact coverage는 tests/adapters/test_windows_integration.py, tests/interfaces/test_mcp_server.py, 그리고 tests/integration/test_packaged_smoke.py에 있습니다. 위의 두 PowerShell 스크립트를 실행하여 현재 호스트의 onedir 아티팩트를 다시 빌드하고 검증하세요.