DeskSense

DeskSense es un servidor MCP ligero y de solo lectura para Windows que proporciona a los asistentes de IA información sobre el estado actual del PC.

Expone HTTP Streamable de MCP a través de un servidor local, protegido por un token de portador. CORS es configurable para clientes basados en navegador. Un túnel de Cloudflare es opcional cuando un nodo necesita acceso público controlado.

¿Qué es DeskSense?

Ejecute un nodo independiente de DeskSense en cada PC con Windows que desee observar. Un nodo lee el estado del escritorio y del sistema; no ejecuta comandos ni modifica el ordenador.

Related MCP server: procmon-mcp

Características

• Detección de PC solo para Windows, solo lectura

• Punto final HTTP Streamable de MCP en /mcp

• Autenticación mediante token de portador

• Orígenes CORS configurables

• Acceso opcional a través de túnel con nombre o rápido de Cloudflare

• Inicio automático interactivo en el inicio de sesión mediante el Programador de tareas

• Inicio oculto del servidor mediante wscript.exe

• Punto final de salud local en /healthz

Herramientas MCP

El servidor proporciona exactamente estas siete herramientas de solo lectura:

• 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

Arquitectura

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

Cada ordenador tiene su propio token, configuración, datos de ejecución y túnel opcional. SullyOS es un cliente de ejemplo probado, no un cliente obligatorio ni exclusivo.

Requisitos

• Windows 10 o superior

• Python 3.11 o superior

• cloudflared solo cuando se usa un túnel

• Un cliente MCP compatible

Inicio rápido

Desde la raíz del repositorio en 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

Para una instalación completa del nodo, que incluye generación de token, CORS, configuración del túnel y tareas de inicio automático:

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

Use -AllowedOrigin https://example-client.app cuando un cliente de navegador necesite un origen adicional. El instalador imprime la URL de MCP y la ruta del archivo de token sin mostrar el token.

Túnel de Cloudflare

Cloudflare es opcional. Use un túnel rápido para pruebas temporales:

.\scripts\start-quick-tunnel.ps1

Para un nombre de host estable, autentique cloudflared, cree o seleccione un túnel con nombre y use start-named-tunnel.ps1 después de la instalación. Apunte el túnel a http://127.0.0.1:8765 y exponga solo el nombre de host deseado.

Conectar un cliente MCP

Configure el cliente con:

• URL MCP: https://desksense.example.com/mcp (o http://127.0.0.1:8765/mcp localmente)

• Autenticación: Bearer <token>

El token se almacena localmente en .secrets\API_KEY.txt. SullyOS se puede usar como cliente de ejemplo; cualquier cliente MCP que admita HTTP Streamable y autenticación de portador puede conectarse.

Múltiples PC / Nodos

Instale un nodo de DeskSense por cada PC con Windows. Asigne a cada nodo un nombre de host, un nombre de túnel y un token distintos, luego configure cada punto final MCP por separado en el cliente. No copie la base de datos de ejecución ni las credenciales de un nodo entre ordenadores a menos que utilice el flujo de trabajo de migración documentado.

Seguridad y privacidad

DeskSense es de solo lectura, pero sus respuestas pueden contener nombres de aplicaciones, títulos de ventanas, información de procesos y métricas del sistema. Mantenga privado el token de portador, restrinja AllowedOrigin a clientes de confianza y coloque el acceso público detrás de un túnel configurado correctamente. Los tokens no se escriben en el código fuente ni en los registros. El historial de enfoque se almacena localmente en data\pc_sense.db; los registros se escriben bajo logs\.

Inicio automático

El instalador registra una tarea interactiva en el inicio de sesión llamada DeskSense MCP. Inicia wscript.exe, que a su vez ejecuta run-desksense-hidden.vbs; el script VBS invoca python.exe -m desksense.server sin ninguna ventana de consola visible.

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

El inicio de sesión interactivo es intencional porque la detección del escritorio requiere la sesión de Windows del usuario.

Solución de problemas

• Verifique la salud local: Invoke-WebRequest http://127.0.0.1:8765/healthz

• Verifique el escucha en el puerto 8765 y el punto final de salud local: .\.scripts\status.ps1

• Revise los archivos en logs\ (nunca comparta .secrets\)

• Confirme que PYTHONPATH=src cuando se ejecute directamente desde un clon del repositorio

• Confirme que el cliente envía Authorization: Bearer <token> y usa /mcp

• Para problemas con el túnel, verifique el inicio de sesión de cloudflared, el enrutamiento del nombre de host y que solo un nodo ejecute un túnel con nombre

Desarrollo

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

El código fuente está en src/desksense; las pruebas están en tests. El servidor se puede ejecutar localmente con PYTHONPATH=src como se indicó anteriormente.

Licencia

DeskSense se publica bajo la Licencia MIT. Consulte LICENSE.