DeskSense

DeskSense는 현재 PC 상태를 AI 어시스턴트에 알려주는 경량의 읽기 전용 Windows MCP 서버입니다.

로컬 서버를 통해 MCP Streamable HTTP를 노출하며, Bearer 토큰으로 보호됩니다. CORS는 브라우저 기반 클라이언트를 위해 구성 가능합니다. Cloudflare Tunnel은 노드가 제어된 공용 액세스를 필요로 할 때 선택 사항입니다.

DeskSense란?

관찰하려는 각 Windows PC에서 하나의 독립적인 DeskSense Node를 실행합니다. 노드는 데스크톱 및 시스템 상태를 읽습니다. 명령을 실행하거나 컴퓨터를 수정하지 않습니다.

Related MCP server: procmon-mcp

기능

• Windows 전용, 읽기 전용 PC 감지

• /mcp에서 MCP Streamable HTTP 엔드포인트

• Bearer Token 인증

• 구성 가능한 CORS 출처

• 선택적 Cloudflare Named 또는 Quick Tunnel 액세스

• 작업 스케줄러를 통한 대화형 AtLogOn 자동 시작

• wscript.exe를 통한 숨겨진 서버 시작

• /healthz에서 로컬 상태 엔드포인트

MCP 도구

서버는 정확히 다음 7개의 읽기 전용 도구를 제공합니다:

• pc_get_context

• pc_get_focus

• pc_list_open_apps

• pc_get_idle_status

• pc_get_pc_status

• pc_get_top_processes

• pc_get_recent_focus

아키텍처

AI assistant / MCP client
          |
          | HTTPS + Bearer Token (optional public tunnel)
          v
Cloudflare Tunnel (optional)
          |
          v
127.0.0.1:8765  ->  python -m desksense.server
          |
          +--> Windows APIs, psutil, and local focus history

각 컴퓨터는 자체 토큰, 구성, 런타임 데이터 및 선택적 터널을 가지고 있습니다. SullyOS는 테스트된 예제 클라이언트이지만 필수 또는 독점 클라이언트는 아닙니다.

요구 사항

• Windows 10 이상

• Python 3.11 이상

• 터널을 사용하는 경우에만 cloudflared

• 호환되는 MCP 클라이언트

빠른 시작

PowerShell에서 리포지토리 루트에서:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
$env:PYTHONPATH = "src"
.\.venv\Scripts\python.exe -m desksense.server

토큰 생성, CORS, 터널 구성 및 자동 시작 작업을 포함한 전체 노드 설치:

.\scripts\install.ps1 `
  -Hostname desksense.example.com `
  -TunnelName desksense

브라우저 클라이언트가 추가 출처를 필요로 하는 경우 -AllowedOrigin https://example-client.app을 사용하십시오. 설치 프로그램은 MCP URL과 토큰 파일 경로를 출력하지만 토큰은 출력하지 않습니다.

Cloudflare Tunnel

Cloudflare는 선택 사항입니다. 임시 테스트에는 Quick Tunnel을 사용하십시오:

.\scripts\start-quick-tunnel.ps1

안정적인 호스트 이름을 위해 cloudflared를 인증하고, Named Tunnel을 생성하거나 선택한 후 설치 후 start-named-tunnel.ps1을 사용하십시오. 터널을 http://127.0.0.1:8765로 지정하고 의도한 호스트 이름만 노출하십시오.

MCP 클라이언트 연결

다음으로 클라이언트를 구성하십시오:

• MCP URL: https://desksense.example.com/mcp (로컬에서는 http://127.0.0.1:8765/mcp)

• 인증: Bearer <token>

토큰은 로컬의 .secrets\API_KEY.txt에 저장됩니다. SullyOS를 예제 클라이언트로 사용할 수 있습니다. Streamable HTTP 및 Bearer 인증을 지원하는 모든 MCP 클라이언트가 연결할 수 있습니다.

여러 PC / 노드

Windows PC당 하나의 DeskSense Node를 설치하십시오. 각 노드에 고유한 호스트 이름, 터널 이름 및 토큰을 지정한 다음 클라이언트에서 각 MCP 엔드포인트를 별도로 구성하십시오. 문서화된 마이그레이션 워크플로우를 사용하지 않는 한 노드의 런타임 데이터베이스나 자격 증명을 컴퓨터 간에 복사하지 마십시오.

보안 및 개인정보

DeskSense는 읽기 전용이지만 응답에는 애플리케이션 이름, 창 제목, 프로세스 정보 및 시스템 메트릭이 포함될 수 있습니다. Bearer 토큰을 비공개로 유지하고, AllowedOrigin을 신뢰할 수 있는 클라이언트로 제한하며, 공용 액세스는 적절히 구성된 터널 뒤에 두십시오. 토큰은 소스 코드나 로그에 기록되지 않습니다. 포커스 기록은 data\pc_sense.db에 로컬로 저장됩니다. 로그는 logs\ 아래에 기록됩니다.

자동 시작

설치 프로그램은 DeskSense MCP라는 대화형 AtLogOn 작업을 등록합니다. wscript.exe를 실행하고, 이는 run-desksense-hidden.vbs를 시작합니다. VBS 스크립트는 python.exe -m desksense.server를 호출하며, 보이는 콘솔 창이 없습니다.

.\scripts\install-autostart.ps1
.\scripts\status.ps1
.\scripts\uninstall-autostart.ps1

대화형 로그온은 의도적입니다. 데스크톱 감지에는 사용자의 Windows 세션이 필요하기 때문입니다.

문제 해결

• 로컬 상태 확인: Invoke-WebRequest http://127.0.0.1:8765/healthz

• 포트 8765 리스너 및 로컬 상태 엔드포인트 확인: .\.\scripts\status.ps1

• logs\ 아래 파일 검토 (.secrets\는 절대 공유하지 마십시오)

• 체크아웃에서 직접 실행할 때 PYTHONPATH=src 확인

• 클라이언트가 Authorization: Bearer <token>을 보내고 /mcp를 사용하는지 확인

• 터널 문제의 경우 cloudflared 로그인, 호스트 이름 라우팅 및 하나의 노드만 Named Tunnel을 실행하는지 확인

개발

.\.venv\Scripts\python.exe -m pytest -q

소스는 src/desksense 아래에 있고, 테스트는 tests 아래에 있습니다. 서버는 위와 같이 PYTHONPATH=src로 로컬에서 실행할 수 있습니다.

라이선스

DeskSense는 MIT 라이선스에 따라 배포됩니다. LICENSE를 참조하십시오.