DeskSense

DeskSense — это легковесный MCP-сервер для Windows, работающий в режиме только для чтения, который предоставляет ИИ-ассистентам сведения о текущем состоянии ПК.

Он предоставляет MCP Streamable HTTP через локальный сервер, защищённый bearer-токеном. CORS настраивается для клиентов на базе браузера. Cloudflare Tunnel опционален, когда узлу требуется контролируемый публичный доступ.

Что такое DeskSense

Запустите один независимый узел DeskSense на каждом Windows-ПК, за которым хотите наблюдать. Узел считывает состояние рабочего стола и системы; он не выполняет команды и не изменяет компьютер.

Related MCP server: procmon-mcp

Возможности

• Мониторинг ПК только для Windows и только для чтения

• Конечная точка MCP Streamable HTTP по адресу /mcp

• Аутентификация по Bearer-токену

• Настраиваемые CORS-источники

• Опциональный доступ через Cloudflare Named или Quick Tunnel

• Интерактивный автозапуск AtLogOn через Планировщик заданий

• Скрытый запуск сервера через wscript.exe

• Локальная конечная точка проверки состояния по адресу /healthz

MCP-инструменты

Сервер предоставляет ровно эти семь инструментов только для чтения:

• 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, когда браузерному клиенту требуется дополнительный источник. Установщик выводит URL MCP и путь к файлу токена, не печатая сам токен.

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 можно использовать в качестве примера клиента; любой MCP-клиент, поддерживающий Streamable HTTP и аутентификацию по Bearer-токену, может подключиться.

Несколько ПК / узлов

Установите один узел DeskSense на каждый Windows-ПК. Задайте каждому узлу уникальные имя хоста, имя туннеля и токен, затем настройте каждую конечную точку MCP в клиенте отдельно. Не копируйте базу данных времени выполнения или учётные данные узла между компьютерами, если не используется документированный процесс миграции.

Безопасность и конфиденциальность

DeskSense работает в режиме только для чтения, но его ответы могут содержать имена приложений, заголовки окон, информацию о процессах и системные метрики. Держите bearer-токен в секрете, ограничьте AllowedOrigin доверенными клиентами и разместите публичный доступ за правильно настроенным туннелем. Токены не записываются в исходный код или журналы. История фокуса хранится локально в data\pc_sense.db; журналы записываются в logs\.

Автозапуск

Установщик регистрирует интерактивную задачу AtLogOn с именем DeskSense MCP. Она запускает 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.