MCP TUIKit

Un servidor de interacción con terminal y tmux sin interfaz gráfica para el Protocolo de Contexto de Modelo.

Documentación

mcp-tuikit

Servidor de Protocolo de Contexto de Modelo para automatización de interfaz de usuario de texto (TUI) y terminal sin interfaz gráfica

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite a agentes de IA (Claude Code, Cursor, Windsurf, OpenCode) lanzar, interactuar y observar cualquier aplicación de terminal en sesiones aisladas. mcp-tuikit utiliza tmux y varios backends de terminal nativos para permitir que la IA interactúe con TUI complejas como nvim, btop, lazygit, o shells estándar, proporcionando capturas de estado de terminal tanto en texto como visuales (PNG).

🚀 Totalmente Compatible Multiplataforma: Funciona sin problemas en macOS, Linux y Windows.

¿Por qué mcp-tuikit?

Sesiones Aisladas: Cada sesión se ejecuta en un entorno tmux aislado. Las interacciones de IA no se filtran ni interrumpen tu terminal anfitrión.
Sin Interfaz Gráfica y Visual: Captura el estado textual preciso de la pantalla y capturas de pantalla PNG visuales de aplicaciones TUI en ejecución, incluso en entornos CI sin interfaz gráfica como Xvfb, Sway o kwin.
Motor de Ejecución de Flujos: Ejecuta flujos predefinidos (YAML) contra instancias de terminal. Ideal para pruebas de integración o para guiar tareas de agentes autónomos.
Multiplataforma: Diseñado para soportar macOS, Linux y Windows de forma nativa. Funciona con terminales estándar (Terminal.app, iTerm2, Gnome Terminal, Windows Terminal) y emuladores modernos acelerados por GPU (Alacritty, WezTerm, Ghostty, Kitty).

Casos de Uso

Pruebas Automatizadas de CLI/TUI

Ejecuta pruebas de extremo a extremo para tus herramientas CLI o aplicaciones TUI. mcp-tuikit lanza cada aplicación en su propia sesión, interactúa mediante pulsaciones de teclas emuladas y verifica los resultados a través de capturas de texto o PNG visuales.

Automatización de Terminal Impulsada por IA

Permite que agentes de IA como Claude Code operen de forma autónoma entornos de terminal complejos. El agente puede generar vim, enviar pulsaciones de teclas j, k, esperar actualizaciones de la interfaz y leer el estado de la pantalla, creando un bucle de retroalimentación completo.

Integración CI Sin Interfaz Gráfica

Integra pruebas de GUI de terminal en pipelines de CI/CD. mcp-tuikit soporta xterm.js mediante Playwright, o servidores nativos sin interfaz gráfica de Linux (Sway, kwin, Xvfb), lo que lo hace perfecto para GitHub Actions o GitLab CI.

Inicio Rápido

1. Instalar

# Install globally via npm
npm install -g @dragoscirjan/mcp-tuikit

2. Configurar Claude Code

claude mcp add mcp-tuikit -- npx -y @dragoscirjan/mcp-tuikit

3. Configurar Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "mcp-tuikit": {
      "command": "npx",
      "args": ["-y", "@dragoscirjan/mcp-tuikit"]
    }
  }
}

4. Usarlo

Pregunta a tu agente de IA:

"Crea una nueva sesión de terminal, ejecuta btop, toma una captura visual de la salida y luego cierra la sesión."

Herramientas Disponibles

Herramienta	Parámetros	Descripción
`create_session`	`command`, `cols?`, `rows?`	Crea una nueva sesión de terminal ejecutando un comando específico.
`close_session`	`session_id`	Cierra una sesión de terminal activa.
`create_snapshot`	`session_id`, `format` (txt/png/both), `intent?`	Captura una instantánea txt y/o png de una sesión activa.
`send_keys`	`session_id`, `keys`, `submit?` (bool)	Envía pulsaciones de teclas a una sesión activa usando formato tmux.
`wait_for_text`	`session_id`, `pattern`, `timeout_ms?`	Espera a que aparezca un patrón regex en la salida de la terminal.
`run_flow`	`yaml_path?`, `yaml_string?`, `cols?`, `rows?`	Ejecuta un flujo TUI YAML y captura artefactos de forma autónoma.
`list_sessions`	(ninguno)	Lista todas las sesiones de terminal activas y sus estados.
`check_system_dependencies`	(ninguno)	Verifica si el sistema anfitrión tiene todas las dependencias requeridas.

Recursos:

terminal://session/{id}/screen.txt?maxLines={limit}: Lee el búfer de texto plano sin procesar de la sesión de terminal activa.

Cómo Funciona

flowchart TD
    Agent["AI Agent (Claude, Cursor)"] <-->|MCP Protocol| Server["mcp-tuikit Server"]

    Server --> |create_session| TMUX["tmux Session"]
    Server --> |send_keys| TMUX
    Server --> |create_snapshot (txt)| TMUX

    TMUX --> |Spawns via Backend| Emulator["Terminal Emulator / Headless Engine"]

    Emulator --> |Alacritty/WezTerm/etc| Native["Native OS Window"]
    Emulator --> |xterm.js| Playwright["Headless Browser"]
    Emulator --> |Xvfb/Sway/kwin| LinuxHeadless["Linux Headless Compositor"]

    Server --> |create_snapshot (png)| ScreenCapture["Sharp / osascript / grim / Playwright"]

Requisitos del Sistema e Instalación

mcp-tuikit depende de utilidades a nivel de sistema operativo para gestionar pseudo-terminales y capturar pantallas.

Dependencia Principal: `tmux`

tmux (v3.3a+, muy recomendado v3.5a+) es absolutamente necesario en todas las plataformas.

macOS: brew install tmux
Linux: sudo apt install tmux o sudo dnf install tmux
Windows: winget install arndawg.tmux-windows (No uses MSYS2 o WSL tmux si ejecutas de forma nativa).

Dependencias Específicas de Plataforma

macOS: Utiliza herramientas integradas (osascript, screencapture). No se necesitan dependencias adicionales.
Linux (Nativo Sin Interfaz Gráfica): Requiere un compositor virtual (Xvfb para X11, sway o kwin para Wayland).
Windows: Utiliza APIs de procesos estándar nativas (cmd, powershell).

Problemas Conocidos y Limitaciones

Consulta la Documentación de Solución de Problemas para obtener detalles completos. Las limitaciones notables incluyen:

Sin Modo Nativo Sin Interfaz Gráfica en Windows/macOS: Generar una terminal nativa (como Alacritty) en Mac/Windows abrirá una ventana física en tu pantalla. El renderizado nativo verdaderamente sin interfaz gráfica requiere Linux (Xvfb/Sway/kwin). Para ejecución invisible en Mac/Windows, debes usar el backend xterm.js (mediante Playwright).
WezTerm + Sway: Las capturas de WezTerm resultan en una pantalla negra bajo Sway sin interfaz gráfica porque requiere estrictamente contextos GPU acelerados por hardware (Vulkan/OpenGL).
Inestabilidad de Capturas en macOS: Las capturas de pantalla basadas en tiempo de macOS (usando CGWindowList) pueden ser inestables bajo carga pesada de CPU, a veces capturando fotogramas en blanco.
Dependencia de Tmux: Todas las operaciones de terminal están envueltas en tmux para garantizar una asignación estable de pseudo-terminal (PTY) y una extracción confiable de texto ANSI.
Sin Soporte de Ratón: Actualmente, no hay soporte de interacción con ratón. Se requiere operar una terminal puramente mediante pulsaciones de teclas estándar. La automatización de ratón en modo con interfaz gráfica presenta desafíos técnicos significativos en múltiples entornos de sistema operativo.
Sin Grabación de Video: El kit de herramientas actualmente solo captura instantáneas estáticas de texto y PNG. La grabación de video de sesiones de terminal está planificada para una versión futura.

Contribuciones

Consulta CONTRIBUTING.md para obtener pautas arquitectónicas, reglas estrictas de formato/linting y el proceso de PR. El desarrollo impulsado por pruebas se aplica mediante vitest.

Licencia

MIT