DeskSense

DeskSense ist ein leichtgewichtiger, schreibgeschützter Windows-MCP-Server, der KI-Assistenten den aktuellen PC-Zustand zugänglich macht.

Er stellt MCP Streamable HTTP über einen lokalen Server bereit, geschützt durch ein Bearer-Token. CORS ist für browserbasierte Clients konfigurierbar. Ein Cloudflare-Tunnel ist optional, wenn ein Knoten kontrollierten öffentlichen Zugriff benötigt.

Was ist DeskSense

Führen Sie einen unabhängigen DeskSense-Knoten auf jedem Windows-PC aus, den Sie beobachten möchten. Ein Knoten liest den Desktop- und Systemzustand; er führt keine Befehle aus und ändert den Computer nicht.

Related MCP server: procmon-mcp

Funktionen

• Windows-only, schreibgeschützte PC-Erfassung

• MCP Streamable HTTP-Endpunkt unter /mcp

• Bearer-Token-Authentifizierung

• Konfigurierbare CORS-Ursprünge

• Optionaler Cloudflare Named- oder Quick-Tunnel-Zugriff

• Interaktiver AtLogOn-Autostart über den Taskplaner

• Versteckter Serverstart via wscript.exe

• Lokaler Health-Endpunkt unter /healthz

MCP-Tools

Der Server stellt genau diese sieben schreibgeschützten Tools bereit:

• 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

Architektur

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

Jeder Computer hat sein eigenes Token, seine Konfiguration, Laufzeitdaten und optionalen Tunnel. SullyOS ist ein getesteter Beispielclient, kein erforderlicher oder exklusiver Client.

Voraussetzungen

• Windows 10 oder neuer

• Python 3.11 oder neuer

• cloudflared nur bei Verwendung eines Tunnels

• Ein kompatibler MCP-Client

Schnellstart

Aus dem Repository-Stammverzeichnis in 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

Für eine vollständige Knoteninstallation, einschließlich Token-Generierung, CORS, Tunnelkonfiguration und Autostart-Aufgaben:

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

Verwenden Sie -AllowedOrigin https://example-client.app, wenn ein Browser-Client einen zusätzlichen Ursprung benötigt. Das Installationsprogramm gibt die MCP-URL und den Token-Dateipfad aus, ohne das Token zu drucken.

Cloudflare-Tunnel

Cloudflare ist optional. Verwenden Sie einen Quick Tunnel für temporäre Tests:

.\scripts\start-quick-tunnel.ps1

Für einen stabilen Hostnamen authentifizieren Sie cloudflared, erstellen oder wählen Sie einen Named Tunnel und verwenden Sie nach der Installation start-named-tunnel.ps1. Richten Sie den Tunnel auf http://127.0.0.1:8765 und geben Sie nur den beabsichtigten Hostnamen frei.

Einen MCP-Client verbinden

Konfigurieren Sie den Client mit:

• MCP-URL: https://desksense.example.com/mcp (oder lokal http://127.0.0.1:8765/mcp)

• Authentifizierung: Bearer <token>

Das Token wird lokal in .secrets\API_KEY.txt gespeichert. SullyOS kann als Beispielclient verwendet werden; jeder MCP-Client, der Streamable HTTP und Bearer-Authentifizierung unterstützt, kann sich verbinden.

Mehrere PCs / Knoten

Installieren Sie einen DeskSense-Knoten pro Windows-PC. Geben Sie jedem Knoten einen eindeutigen Hostnamen, Tunnelnamen und Token, und konfigurieren Sie dann jeden MCP-Endpunkt separat im Client. Kopieren Sie die Laufzeitdatenbank oder Anmeldeinformationen eines Knotens nicht zwischen Computern, es sei denn, Sie verwenden den dokumentierten Migrationsworkflow.

Sicherheit & Datenschutz

DeskSense ist schreibgeschützt, aber seine Antworten können Anwendungsnamen, Fenstertitel, Prozessinformationen und Systemmetriken enthalten. Halten Sie das Bearer-Token privat, beschränken Sie AllowedOrigin auf vertrauenswürdige Clients und platzieren Sie den öffentlichen Zugriff hinter einem ordnungsgemäß konfigurierten Tunnel. Tokens werden nicht in Quellcode oder Logs geschrieben. Der Fokusverlauf wird lokal in data\pc_sense.db gespeichert; Logs werden unter logs\ geschrieben.

Autostart

Das Installationsprogramm registriert eine interaktive AtLogOn-Aufgabe namens DeskSense MCP. Sie startet wscript.exe, das run-desksense-hidden.vbs ausführt; das VBS-Skript ruft python.exe -m desksense.server auf, ohne ein sichtbares Konsolenfenster.

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

Das interaktive Anmelden ist beabsichtigt, da die Desktop-Erfassung die Windows-Sitzung des Benutzers erfordert.

Fehlerbehebung

• Überprüfen Sie die lokale Gesundheit: Invoke-WebRequest http://127.0.0.1:8765/healthz

• Überprüfen Sie den Port-8765-Listener und den lokalen Health-Endpunkt: .\.\scripts\status.ps1

• Überprüfen Sie Dateien unter logs\ (teilen Sie niemals .secrets\)

• Bestätigen Sie PYTHONPATH=src, wenn Sie direkt aus einem Checkout ausführen

• Bestätigen Sie, dass der Client Authorization: Bearer <token> sendet und /mcp verwendet

• Bei Tunnelproblemen überprüfen Sie die cloudflared-Anmeldung, das Hostname-Routing und dass nur ein Knoten einen Named Tunnel ausführt

Entwicklung

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

Der Quellcode befindet sich unter src/desksense; Tests unter tests. Der Server kann lokal mit PYTHONPATH=src wie oben gezeigt ausgeführt werden.

Lizenz

DeskSense wird unter der MIT-Lizenz veröffentlicht. Siehe LICENSE.