WinKit

Observabilidad y diagnóstico local de Windows para agentes de IA, expuestos a través del Model Context Protocol (MCP).

WinKit es un servidor MCP local-primero y de solo lectura por defecto que ofrece a los agentes de codificación una vista estructurada y con permisos de la máquina Windows en la que se ejecutan: procesos, red, almacenamiento, servicios, registros de eventos, ventanas y — a través del primer adaptador de aplicación profundo — inspección en vivo de pestañas de Chrome, además de un navegador gestionado aislado propiedad de WinKit para diagnosticar aplicaciones web locales. Detrás de las herramientas se encuentra un motor de diagnóstico determinista que separa lo que fue medido de lo que es interpretado, de modo que un agente pueda responder preguntas reales sin adivinar. Sin telemetría, sin nube; la única superficie de salida es un lanzamiento de navegador gestionado, restringido y verificado por permisos.

v1 es de solo lectura por defecto. Cada herramienta de inspección devuelve evidencia y nada puede modificar tu sistema. Las únicas acciones que WinKit puede realizar — lanzar o cerrar sus propias sesiones de Chrome gestionadas y aisladas — están deshabilitadas a menos que se establezca [chrome.managed] enabled = true, están limitadas por un permiso separado application.browser.* que los modos safe/read_only nunca otorgan, y solo tocan recursos que el propio WinKit creó.

Lo que responde WinKit

WinKit se construye en torno a tres preguntas, cada una respondida por una herramienta:

Juntas cuentan toda la historia en menos de un minuto: primero la máquina, luego la pestaña más pesada y, finalmente, si está empeorando.

Related MCP server: DivLens MCP

Aspectos destacados

• 69 herramientas MCP en los dominios de sistema, proceso, red, almacenamiento, hardware, energía, servicio, evento, ventana, entorno de desarrollo, aplicación, Chrome, navegador gestionado y salud de la máquina, organizadas en perfiles de herramientas (core, developer [predeterminado], browser, full) para que un agente solo vea lo que necesita.

• Herramientas de flujo de trabajo para desarrolladores — diagnose_workspace, diagnose_local_webapp, list_dev_servers, herramientas acotadas wait_for_*, correlate_recent_failures y system_health_trend resuelven problemas completos (puerto obsoleto, puerto incorrecto, HTTP 500, página en blanco) en lugar de exponer mediciones sin procesar.

• Diagnósticos que priorizan la evidencia — cada informe de alto nivel es una estructura estable con hallazgos clasificados, IDs de hallazgo/evidencia estables y un lenguaje de confianza confirmed/observed/likely/possible/unknown que nunca afirma causalidad a partir de la proximidad temporal. Lógica de umbral pura: sin LLM, sin aleatoriedad, sin afirmaciones inventadas.

• Completitud honesta — system_diagnose informa evidence_completeness: "full" | "limited" cuando una dimensión no pudo medirse, y las dimensiones fallidas se excluyen del conjunto saludable. WinKit te dice lo que no pudo ver.

• Inspección profunda de Chrome mediante CDP — pestañas, rendimiento, memoria, red, consola de ejecución, un informe de diagnóstico combinado y una tendencia muestreada. Las cabeceras, las cookies y los cuerpos de las solicitudes nunca se capturan.

• Navegador gestionado aislado — chrome_start_managed_session lanza un Chrome propiedad de WinKit con un perfil desechable y un endpoint de DevTools solo de bucle local, inspecciona la página (chrome_get_page_summary, chrome_capture_screenshot) y chrome_stop_managed_session lo cierra y elimina el perfil. Solo Windows x64; Chrome nunca se descarga. Con ventana por defecto: se abre una ventana real y visible de Chrome (sin la opción --headless, sin soluciones de GPU solo headless, ventana de 1280x900). Si el lanzamiento con ventana predeterminado falla durante el arranque (un fallo del proceso de GPU), una alternativa verificada de renderización por software con ventana (headed-software) abre la misma ventana visible — nunca se vuelve oculta ni headless. El modo headless es opcional (headless: true) y no abre ninguna ventana por diseño; renderiza mediante la ruta de software con argumentos fijos seguros (headless-software: --disable-gpu --disable-gpu-compositing --use-angle=swiftshader --disable-gpu-program-cache --disable-gpu-shader-disk-cache; una alternativa de GPU en proceso se ejecuta si el modo de software falla al inicio). El modo seleccionado siempre se informa (headless, window_mode, launch_mode) y nunca se cambia en silencio. Una sesión solo se declara ready después de que el navegador supere una breve verificación de inactividad — DevTools puede volverse accesible momentos antes de que Chrome muera (p. ej., un fallo del proceso de GPU), por lo que nunca se devuelve ready solo porque /json/version responda una vez. La salida estándar (stdout) del navegador se redirige para que nunca pueda corromper el flujo de MCP, su salida de error (stderr) se captura en una cola limitada y redactada para diagnóstico (incluido el código de salida del proceso de GPU cuando Chrome lo reporta), y una salida inesperada recolecta el árbol de procesos propiedad del navegador (crashpad/GPU/utility/renderer, identificado por la ruta exacta del perfil propiedad de WinKit) y elimina el perfil propiedad de WinKit — nunca el Chrome del usuario. Limitado por características, limitado por permisos, sin Playwright, sin opciones de depuración manuales.

• Modelo de permisos en capas — cuatro modos (safe, read_only, approval, unrestricted) sobre 14 capacidades de lectura v1 más las capacidades de acción application.browser.launch/navigate/close restringidas por separado. Las denegaciones explican exactamente qué se requeriría.

• Arquitectura de proveedores — todo se encuentra detrás de los traits WindowsBackend / ApplicationProvider; la capa Win32 real es totalmente separable, y un backend simulado junto con fixtures deterministas impulsan una suite de 381 pruebas (cargo test --features mocks) sin dependencia de máquina.

• Endurecido por construcción — resultados acotados, tiempos de espera por herramienta, límites de carga útil, un límite de trama de transporte de 8 MiB, validación estricta de esquema JSON y una salida estándar (stdout) mantenida limpia de protocolo (todos los diagnósticos van a stderr).

• Distribución npm — dos paquetes, @winkit/mcp (launcher) y @winkit/win32-x64-msvc (runtime nativo de Windows x64), instalados con npx --yes @winkit/mcp@latest. Sin scripts de instalación, sin dependencias de automatización de navegador; el ejecutable nativo es un detalle de implementación.

• Habilidad para agentes — skills/winkit-developer-debugging/SKILL.md enseña a los agentes de codificación el enrutamiento pregunta→herramienta, la selección de permisos y perfiles, y los límites de safe/read-only.

• Suite de evaluación — tests/eval/ es una suite determinista de 18 escenarios respaldada por fixtures que verifica estado, evidencia, IDs de hallazgos, evidencia de apoyo/contradictoria, redacción, salida acotada, comportamiento de permisos y ausencia de afirmaciones falsas de causa raíz para los modos de fallo que WinKit está diseñado para diagnosticar.

Inicio rápido

Requisitos: Windows 10/11 x64 y Node.js >= 18 (ruta npm) o Rust 1.75+ (desde el código fuente).

npx --yes @winkit/mcp@latest doctor   # verify the install

O compilar desde el código fuente:

cargo build --release
.\target\release\winkit --help

WinKit es lanzado por un cliente MCP como un subproceso stdio, ya sea a través del lanzador npx o directamente desde el binario compilado (consulta docs/mcp-integration.md):

• OpenCode — examples/mcp/opencode.json

• Claude Code — examples/mcp/claude-code.json

• Cualquier cliente MCP — examples/mcp/generic.json

Sin un archivo de configuración, WinKit se ejecuta con valores predeterminados seguros: modo de permiso read_only, ambos proveedores integrados habilitados y límites documentados. Consulta config/example.toml para conocer toda la superficie y docs/installation.md para el proceso de configuración completo.

Inspección de Chrome y el navegador gestionado

La inspección profunda de Chrome necesita que Chrome exponga su endpoint de DevTools. WinKit puede hacerlo por ti: con [chrome.managed] enabled = true y el permiso application.browser.launch, chrome_start_managed_session genera su propia instancia aislada de Chrome (perfil desechable, endpoint de DevTools solo de bucle local), por lo que no se necesitan opciones de depuración manuales ni un proceso de navegador separado. De forma predeterminada, se abre una ventana real y visible de Chrome en el escritorio; pasa headless: true solo cuando se desee una sesión de automatización/CI no visible (ese modo no abre ninguna ventana por diseño):

chrome_start_managed_session(url="http://localhost:3000")  # opens a visible Chrome window
  -> chrome_get_page_summary(session_id)     # runtime errors, failed requests, headings
  -> chrome_capture_screenshot(session_id)   # optional visual check
  -> chrome_stop_managed_session(session_id) # closes Chrome, removes the profile

Para inspeccionar un Chrome ya en ejecución (por ejemplo, uno que el desarrollador inició con --remote-debugging-port), WinKit descubre el endpoint probando fallback_port (por defecto 9222) y conectándose a través de CDP. Consulta docs/chrome.md para conocer el ciclo de vida completo, los estados y las reglas de seguridad.

Rendimiento

Latencia mediana de extremo a extremo, medida en un escritorio con Windows 10 (8 núcleos, 16 GB de RAM) con una compilación de distribución y un proceso de servidor nuevo por llamada — por lo que los números incluyen el inicio del proceso y el handshake de initialize de MCP:

Las herramientas con ventana de observación escalan con su ventana configurada, no con el tamaño del sistema; cualquier otra herramienta se mantiene por debajo de 100 ms sin importar cuántos procesos, puertos o pestañas existan. Tabla completa y metodología: docs/performance.md.

La superficie de herramientas

Referencia completa con esquemas de argumentos: docs/tools.md.

Arquitectura

El pipeline de WinKit es una separación de responsabilidades en tres capas — WinKit mide, WinKit interpreta señales, WinKit clasifica hallazgos respaldados por evidencia; el LLM los explica:

                 WinKit
                   │
      ┌────────────┼────────────┐
      │            │            │
  Observation  Correlation  Diagnosis
      │            │            │
      ↓            ↓            ↓
  Windows/App   Evidence    Findings
    metrics      linking     ranking

server (MCP over stdio, JSON-RPC 2.0, session lifecycle)
  ├── tools        (59 tool definitions + argument handling + registry)
  │     ├── providers (WindowsBackend / ApplicationProvider traits)
  │     │     └── chrome::managed (isolated WinKit-owned sessions)
  │     └── platform::windows (real Win32 implementations, windows-sys 0.59)
  ├── permissions  (modes, capabilities, policy, approval surface)
  ├── config       (winkit.toml, strict, deny-unknown-keys)
  ├── models       (unified data models shared by providers/tools/diagnostics)
  └── diagnostics  (measurements → signals → ranked findings)

Las reglas de capas son estrictas: la superficie MCP nunca toca Win32 directamente, y la capa de Windows es comprobable a través de un backend simulado (cargo test --features mocks). Inmersión profunda: docs/architecture.md.

Modelo de seguridad

• Solo lectura por defecto — cada herramienta de inspección es de solo lectura; las únicas acciones (iniciar/navegar/cerrar navegador gestionado) están controladas por características [chrome.managed] enabled y denegadas en modos safe/read_only.

• Los modos de permiso controlan cada llamada de herramienta antes del envío, con una compuerta de acción separada para las herramientas del ciclo de vida del navegador gestionado.

• El navegador gestionado está aislado y se autolimpia — un perfil desechable bajo la raíz gestionada, DevTools solo de bucle de retorno, limpieza que rechaza cualquier ruta fuera de la raíz gestionada, y nunca se adjunta al perfil normal de Chrome.

• No se capturan secretos — la inspección de red/tiempo de ejecución de Chrome trunca la salida y excluye explícitamente encabezados, cookies y cuerpos; las URL se redactan (cadenas de consulta eliminadas).

• Trabajo acotado en todas partes — límites de resultados, tiempos de espera, límites de carga útil, límites de fotogramas.

• Detalles completos: SECURITY.md y docs/security.md.

Limitaciones conocidas

WinKit trata los límites como salida de primera clase, no como errores:

• El porcentaje de CPU por proceso es una muestra en vivo, no una medida acumulativa. El cálculo ingenuo de relación de sistema es engañoso en máquinas multinúcleo, por lo que list_processes (una instantánea completa económica) informa cpu_percent: null. Para detectar un proceso descontrolado, get_process toma una muestra en vivo de porcentaje de CPU de dos muestras durante una ventana de 300 ms con una base explícita (system_capacity_all_cores); la vista agregada (ApplicationGroupInfo) hace lo mismo con una muestra de 1 s.

• Chrome no siempre puede asignar una pestaña a un PID — el adaptador informa process_mapping: "none" y continúa con evidencia pura de CDP en lugar de fallar o adivinar.

• Algunos procesos de Windows deniegan el acceso de lectura — aún se enumeran con null para los campos que no se pudieron leer, nunca se eliminan en silencio.

• Los diagnósticos distinguen lo medido de lo no medido — system_diagnose lleva evidence_completeness, y los informes pueden incluir entradas de limitations para que los agentes no sobreinterpreten una vista parcial.

• La inspección de un Chrome ya en ejecución requiere un puerto de depuración remota. El flujo de trabajo del navegador gestionado elimina ese requisito para el diagnóstico de aplicaciones locales: WinKit inicia su propio Chrome aislado cuando la característica y el permiso están habilitados; los perfiles de navegación normales siempre permanecen intactos.

Desarrollo

cargo check                 # compile checks
cargo build                 # debug build
cargo test --features mocks # full test suite (381 tests)
cargo clippy --all-targets  # lint

# evaluation suite (fixture-backed failure scenarios)
cargo test --features mocks --test eval

# npm launcher + package validation (after cargo build --release)
powershell -ExecutionPolicy Bypass -File npm/scripts/copy-native.ps1
node --test npm/test/launcher.test.js npm/test/package.test.js
powershell -ExecutionPolicy Bypass -File npm/scripts/test-packed.ps1

# opt-in live tests (need a real Windows machine / Chrome install)
$env:WINKIT_LIVE_WINDOWS = "1"; cargo test --features live-windows
# live managed-Chrome lifecycle, both modes (requires an installed Google
# Chrome on an interactive desktop; run ten consecutive isolated runs per
# mode before any release-ready claim)
$env:WINKIT_LIVE_CHROME = "1"; cargo test --features live-chrome --lib live_managed_chrome_headed_start_inspect_stop -- --nocapture
$env:WINKIT_LIVE_CHROME = "1"; cargo test --features live-chrome --lib live_managed_chrome_headless_start_inspect_stop -- --nocapture

Las pruebas en vivo de Chrome gestionado imprimen una razón de omisión explícita cuando WINKIT_LIVE_CHROME no es 1; la prueba con interfaz también se omite (marcando el comportamiento con interfaz como no verificado) cuando no hay un escritorio interactivo. Una prueba en vivo omitida nunca es un aprobado, y sin que ambos modos pasen en una instalación real de Chrome, el proyecto no está "listo para lanzamiento" (ver docs/release.md).

Las pruebas de integración ejercitan el protocolo MCP, el envío de herramientas, la aplicación de permisos y los proveedores simulados respaldados por accesorios sin tocar la máquina real; la suite de evaluación (tests/eval/) cubre 18 escenarios de fallo deterministas. Ver docs/development.md y CONTRIBUTING.md.

Documentación

• docs/installation.md — construir, configurar, conectar a un cliente MCP

• docs/architecture.md — capas, flujo de datos, modelo de proveedor

• docs/diagnostics.md — la forma del informe basado en evidencia y las fórmulas de puntuación

• docs/security.md — modelo de amenazas y mitigaciones

• docs/permissions.md — modos, capacidades, tabla de políticas

• docs/tools.md — referencia de herramientas con argumentos

• docs/configuration.md — cada clave de configuración y valor predeterminado

• docs/application-adapters.md — cómo se conectan los adaptadores

• docs/chrome.md — descubrimiento de Chrome, CDP, sesiones gestionadas y advertencias

• docs/performance.md — metodología de referencia y tabla completa

• docs/demos.md — el guion de tres demostraciones y guía de grabación

• docs/mcp-integration.md — ejemplos de configuración de cliente

• docs/development.md — construir, probar, contribuir

• docs/release.md — proceso de lanzamiento y lista de verificación

• tests/eval/README.md — cómo ejecutar la suite de evaluación

• skills/winkit-developer-debugging/SKILL.md — la habilidad del agente

Licencia

MIT — ver LICENSE. WinKit es local-primero y de código abierto; no contiene telemetría y no realiza llamadas de red excepto la sonda de bucle de retorno de Chrome DevTools.