mcp-windows-debug

{"type": "text"}# mcp-windows-debug

Un servidor MCP de TypeScript/Node.js que se conecta a OpenCode a través de stdio y le da al modelo ojos y manos en una máquina Windows: lee archivos del proyecto, captura capturas de pantalla, mueve el ratón y pulsa teclas, y ejecuta un bucle de depuración automática contra una aplicación objetivo.

La seguridad es el objetivo de todo el diseño. Un proceso de vigilancia (watchdog) nativo en C++ independiente instala hooks globales de bajo nivel de teclado y ratón para que un humano siempre pueda pulsar un botón de aborto protegido, incluso mientras el modelo está inyectando entrada. El servidor MCP de Node y el watchdog son dos procesos independientes, por lo que un bucle de eventos de Node bloqueado no puede congelar tu entrada ni eliminar silenciosamente la capa de seguridad. Cada acción pasa por tres compuertas: un gobernador, una comprobación de frescura y una guardia de ámbito de ventana. Los detalles están en la sección Modelo de seguridad más abajo.

Esto es solo para Windows v1. Los backends de macOS y Linux se conectan más adelante detrás de las mismas interfaces de proveedor; no están implementados todavía.

Inicio rápido

git clone https://github.com/wgm66/mcp-windows-debug.git
cd mcp-windows-debug
npm install && npm run build
cd src\watchdog && build.bat   # build the C++ watchdog (MSVC required)
node dist\index.js --validate-config  # verify your OpenCode config

Related MCP server: Desktop Commander MCP Server

Instalación

Requisitos previos:

• Node.js 20 o superior, además de npm

• Windows 10 u 11

• Acceso de administrador, necesario solo para ejecutar el watchdog (ver más abajo)

Instala las dependencias y compila el TypeScript:

npm install
npm run build

npm run build ejecuta tsc y produce dist/index.js, que es el punto de entrada que lanza OpenCode.

A continuación, compila el watchdog. Es una aplicación de consola Win32 en C++ compilada con MSVC, sin CMake, MSBuild ni MinGW:

cd src\watchdog
build.bat

build.bat requiere las Build Tools de VS2019 (MSVC 14.29) y el Windows SDK. Las rutas del toolchain están codificadas en el script, por lo que espera que estén en sus ubicaciones de instalación predeterminadas. La salida es src\watchdog\watchdog.exe, que el servidor de Node localiza en relación con la raíz del proyecto en tiempo de ejecución.

El watchdog debe ejecutarse con privilegios elevados. Los hooks globales de bajo nivel se niegan a instalarse desde un proceso no elevado. Hay dos formas de cumplir esto:

1. Iniciar OpenCode desde una terminal elevada, para que el watchdog generado herede la elevación.

2. Pre-iniciar el watchdog como administrador tú mismo antes de comenzar una sesión de depuración.

El servidor no puede solicitar la elevación de UAC por sí solo en esta compilación. Una sesión de depuración que no pueda alcanzar un watchdog elevado falla con ELEVATION_REQUIRED, y una ejecución del watchdog no elevada imprime ERROR_ACCESS_DENIED y sale con el código 1 en lugar de no hacer nada silenciosamente.

Configuración de OpenCode

Añade una entrada windows-debug bajo la clave mcp en tu configuración de OpenCode (opencode.json). Ten en cuenta que la clave es mcp, no mcpServers:

{
  "mcp": {
    "windows-debug": {
      "type": "local",
      "command": ["node", "<abs-path>/dist/index.js"],
      "environment": {}
    }
  }
}

Reemplaza <abs-path> con la ruta absoluta a este proyecto, usando barras diagonales para que el JSON no necesite escapes. Por ejemplo, si el proyecto está en G:\工程开发\AI全场景图形化调试, el comando se convierte en:

"command": ["node", "G:/工程开发/AI全场景图形化调试/dist/index.js"]

El command es un array de tokens argv. El mapa environment está vacío por defecto; el token del watchdog por sesión lo genera el propio servidor y se pasa al watchdog a través del entorno del proceso, por lo que no necesitas configurar nada aquí.

Uso

Una sesión de depuración tiene una forma fija: registrar botones de aborto protegidos, iniciar la sesión, dejar que el modelo trabaje a través del bucle de depuración automática y luego finalizar la sesión.

Registrar botones de aborto. Una sesión no puede comenzar con cero regiones protegidas. Pasa uno o más rectángulos de pantalla a start_debug_session como regions ({ x, y, w, h, id }, píxeles físicos). La entrada inyectada dirigida dentro de cualquier región registrada es bloqueada por el watchdog. La entrada humana siempre pasa, por lo que la región es un área de aborto físico garantizada a la que el modelo no puede llegar. Las regiones son de solo añadidura durante la vida de la sesión; deliberadamente no hay forma de eliminar o mover una después de iniciarla.

Iniciar la sesión. start_debug_session genera o adjunta el watchdog, registra cada región e inicia el latido. El orquestador comienza a monitorear la ventana de primer plano actual como objetivo de depuración. Pasa sandbox: 'desktop' para ejecutar la inyección en un escritorio Win32 privado (basado en PostMessage, el ratón/teclado real del usuario no se toca) en lugar de SendInput (que mueve el cursor real). sandbox: 'rdp' está reservado pero no implementado en v1.

El bucle de depuración automática. Mientras la sesión está activa, el orquestador sondea la ventana objetivo en busca de cambios: título, rectángulo, estado de primer plano y opcionalmente un diff de firma de captura de pantalla. Cuando se dispara un desencadenante, captura una captura de pantalla fresca y la expone como el recurso debug://context. El cliente (OpenCode) sondea debug://context, decide qué hacer y llama a execute_action con esa decisión. El orquestador nunca decide acciones por su cuenta; solo ejecuta decisiones del cliente, y solo después de que el gobernador, la frescura y las compuertas de seguridad pasen todas.

Finalizar la sesión. end_debug_session envía SHUTDOWN, mata al watchdog si no responde en un segundo, libera cualquier tecla modificadora mantenida y vuelve a IDLE. Si el proceso MCP muere sin un apagado limpio, el interruptor de hombre muerto del watchdog elimina los hooks por sí solo (ver la sección Modelo de seguridad).

Herramientas

Hay diez herramientas registradas.

Las cuatro herramientas de entrada (mouse_click, mouse_move, key_press, type_text) pasan todas por la compuerta injectGuarded de la capa de seguridad. Llamarlas sin sesión activa devuelve NO_ACTIVE_SESSION. Llamarlas mientras el cursor o el foco de teclado está fuera de la ventana objetivo devuelve WINDOW_SCOPE_VIOLATION.

Recursos

Hay tres recursos registrados.

Límites del gobernador

El orquestador impone una limitación fija en las intervenciones:

• 5 segundos de enfriamiento entre acciones

• 6 intervenciones por minuto

• pausa automática después de 3 fallos consecutivos

• límite duro de sesión de 30 minutos, después del cual la sesión se auto-finaliza

Los rechazos por enfriamiento, límite de velocidad o pausa son limitación, no fallos. Solo una negativa por estado obsoleto o un error de inyección cuenta para la pausa de 3 fallos.

Modelo de seguridad

Lo que este diseño garantiza, y lo que no.

Aislamiento de doble proceso. El servidor MCP de Node y el watchdog nativo son procesos separados. Un bucle de eventos de Node atascado no puede bloquear los hooks ni eliminar la capa de seguridad, porque el watchdog ejecuta su propio bucle de mensajes.

Interruptor de hombre muerto. El watchdog escucha en una tubería con nombre y trata cualquier byte como un latido. Si no llega ningún latido durante más de 2 segundos, llama a UnhookWindowsHookEx en ambos hooks y sale limpiamente. Combinado con el período de gracia de eliminación, los hooks se retiran en menos de 3 segundos tras la muerte del MCP, por lo que un servidor bloqueado o eliminado nunca deja la entrada bloqueada. Este es el contrato a prueba de fallos; no es una garantía de sub-segundo.

Ámbito de ventana. Cada inyección se rechaza a menos que haya una sesión activa y el cursor y el foco de teclado estén dentro de la ventana objetivo de la sesión.

Manejo de escritorio seguro. Si el SO cambia al escritorio seguro (aviso de UAC o pantalla de bloqueo), el orquestador se pausa y rechaza la inyección sin intentar ninguna entrada.

Auditoría de solo añadidura. Cada lectura de archivo, acción inyectada, solicitud de captura de pantalla y decisión de intervención se registra en un registro de auditoría de solo añadidura. El contenido de las pulsaciones de teclas y el contenido de los archivos nunca se escriben en él.

Lo que NO garantiza. Lee esta parte con atención, porque estos son los riesgos residuales honestos.

• El filtrado de entrada inyectada no es un bloqueo absoluto. El watchdog bloquea la entrada que lleva las banderas LLKHF_INJECTED / LLMHF_INJECTED cuando el destino cae dentro de una región protegida. Eso detiene la entrada inyectada por máquina, que es lo que produce SendInput. No detiene todas las fuentes posibles de entrada. Otro proceso podría teóricamente sintetizar entrada sin banderas por otros medios, y esa entrada pasaría el filtro. Esta herramienta no afirma un bloqueo físico absoluto. Trata el botón de aborto como una red de seguridad fuerte y de mejor esfuerzo, no como una garantía matemática.

• Es una primitiva de control remoto en el peor de los casos. La superficie completa de la herramienta es lectura de archivos más captura de pantalla más inyección de teclado y ratón. Si un atacante o un modelo con mal comportamiento la controla, esa es la capacidad que obtienen. Úsala en una máquina y contra ventanas a las que estés dispuesto a que esa superficie apunte.

• El antivirus y el EDR pueden marcarla. Los hooks globales de bajo nivel y la inyección de SendInput son exactamente las técnicas que usan las herramientas de acceso remoto y los keyloggers. Espera falsos positivos de productos AV/EDR, incluido el watchdog siendo puesto en cuarentena o eliminado a mitad de sesión. El interruptor de hombre muerto hace que eso sea seguro (los hooks se retiran), pero interrumpirá las sesiones. Ver Solución de problemas.

• La elevación amplía la superficie. El watchdog necesita administrador para instalar hooks globales, por lo que una sesión se ejecuta con un proceso elevado en juego. No lo ejecutes en una máquina donde esa exposición sea inaceptable.

Ningún contenido de pulsaciones de teclas o botones es leído o registrado jamás por el watchdog; solo se inspeccionan la bandera de inyección y el destino del cursor. El transporte es solo la tubería con nombre local. No hay TCP, ni listener de red, ni control remoto.

Solución de problemas

El antivirus o EDR marca el watchdog. Añade una exclusión para src\watchdog\watchdog.exe (o el directorio del proyecto) en tu consola de antivirus/EDR. La solución duradera es la firma de código: un binario firmado tiene muchas menos probabilidades de ser puesto en cuarentena. Si el watchdog se elimina a mitad de sesión, la sesión pasa a IDLE y se rechazan todas las herramientas de entrada hasta un nuevo start_debug_session.

Windows desmonta el hook (LowLevelHooksTimeout). Los procedimientos de hook de bajo nivel tienen un presupuesto de ejecución estricto, controlado por HKCU\Control Panel\Desktop\LowLevelHooksTimeout (por defecto 300 ms). Si el proc del hook se ejecuta durante demasiado tiempo, Windows lo elimina silenciosamente. El watchdog mantiene su proc de hook muy por debajo de 100 ms, por lo que esto no debería activarse en uso normal. Si ves que los hooks se eliminan en una máquina muy cargada, el problema es la carga del sistema o la interferencia de otro hook de bajo nivel, no esta herramienta.

Los clics caen en el lugar equivocado en una configuración de varios monitores o DPI mixto. Las coordenadas se mapean entre píxeles lógicos y físicos usando DPI por monitor. En configuraciones de varios monitores con DPI mixto hay una limitación conocida: la conversión de lógico a físico pasa coordenadas lógicas a una llamada que espera píxeles físicos. Es inofensivo a 96 DPI pero puede desviarse en monitores escalados. Si un clic falla, toma una captura de pantalla primero, lee las coordenadas objetivo de ella y prefiere trabajar en el monitor principal.

Aparece un aviso de UAC, o la inyección falla silenciosamente. El watchdog se ejecuta elevado, por lo que generarlo puede mostrar un aviso de UAC. Si lo cancelas, la sesión falla con ELEVATION_REQUIRED. El servidor no puede volver a solicitar elevación por sí solo en esta compilación, así que inicia el watchdog como administrador antes de comenzar la sesión, o lanza OpenCode desde una terminal elevada.

ERROR_ACCESS_DENIED al ejecutar el watchdog manualmente. Este es el comportamiento esperado para un shell no elevado. El watchdog se niega a ejecutarse sin administrador e imprime ERROR_ACCESS_DENIED con código de salida 1, por lo que no hay una operación nula silenciosa. Ejecútalo desde un PowerShell elevado en su lugar.

Grabación de sesión

Las sesiones se pueden grabar como transcripciones JSON para reproducirlas más tarde. El grabador se engancha al registro de auditoría y captura cada llamada de herramienta (nombre, argumentos, resultado, marca de tiempo) sin contenido de pulsaciones de teclas (minimización de datos). Las transcripciones se guardan en .omo/recordings/session-<id>.json.

# A session transcript can be replayed programmatically:
node -e "const { SessionRecorder } = require('./dist/recording'); SessionRecorder.replay('.omo/recordings/session-xxx.json', async (call) => { console.log(call.toolName, call.args); })"

UIAutomation (API de accesibilidad)

La herramienta inspect_element enumera los elementos de interfaz visibles mediante el recorredor de árbol de UIAutomation (paridad con los competidores terminator-mcp-agent y Windows MCP Inspector). En v1, esto es un stub que devuelve elementos desde la costura de dependencias inyectadas; la interoperabilidad COM completa requiere un addon nativo N-API (trabajo futuro). La clase UIAutomationProvider implementa InputProvider pero lanza UIAutomationError para los métodos de inyección en v1 — usa las rutas SendInput o PostMessage para la inyección real.