Servidor MCP TUIKit | Awesome MCP Servers

mcp-tuikit

Servidor Model Context Protocol para automação de Interface de Texto (TUI) e terminal headless

Um servidor Model Context Protocol (MCP) que permite que agentes de IA (Claude Code, Cursor, Windsurf, OpenCode) iniciem, interajam e observem qualquer aplicativo de terminal em sessões isoladas. mcp-tuikit usa tmux e vários backends de terminal nativos para permitir que a IA interaja com TUIs complexos como nvim, btop, lazygit, ou shells padrão, fornecendo capturas de texto e visuais (PNG) dos estados do terminal.

🚀 Totalmente Compatível com Todos os Sistemas Operacionais: Funciona perfeitamente em macOS, Linux e Windows.

Por que mcp-tuikit?

Sessões Isoladas: Cada sessão roda em um ambiente tmux isolado. As interações da IA não vazam nem interrompem o terminal do host.
Headless e Visual: Capture o estado textual preciso da tela e capturas de tela PNG visuais de aplicativos TUI em execução, mesmo em ambientes CI headless como Xvfb, Sway, ou kwin.
Mecanismo de Execução de Fluxos: Execute fluxos predefinidos (YAML) contra instâncias de terminal. Ótimo para testes de integração ou para orientar tarefas autônomas de agentes.
Multiplataforma: Construído para suportar macOS, Linux e Windows nativamente. Funciona com terminais padrão (Terminal.app, iTerm2, Gnome Terminal, Windows Terminal) e emuladores modernos acelerados por GPU (Alacritty, WezTerm, Ghostty, Kitty).

Casos de Uso

Testes Automatizados de CLI/TUI

Execute testes de ponta a ponta para suas ferramentas CLI ou aplicativos TUI. mcp-tuikit inicia cada aplicativo em sua própria sessão, interage por meio de teclas emuladas e verifica os resultados por meio de capturas de tela de texto ou PNG visuais.

Automação de Terminal Orientada por IA

Permita que agentes de IA como Claude Code operem autonomamente ambientes de terminal complexos. O agente pode iniciar vim, enviar teclas j, k, aguardar atualizações da interface e ler o estado da tela, criando um ciclo de feedback completo.

Integração CI Headless

Integre testes de GUI de terminal em pipelines de CI/CD. mcp-tuikit suporta xterm.js via Playwright, ou servidores headless nativos Linux (Sway, kwin, Xvfb), tornando-o perfeito para GitHub Actions ou GitLab CI.

Início Rápido

1. Instalação

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

2. Configure o Claude Code

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

3. Configure o Cursor (~/.cursor/mcp.json)

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

4. Use

Pergunte ao seu agente de IA:

"Crie uma nova sessão de terminal, execute btop, tire uma captura visual da saída e feche a sessão."

Ferramentas Disponíveis

Ferramenta	Parâmetros	Descrição
`create_session`	`command`, `cols?`, `rows?`	Cria uma nova sessão de terminal executando um comando específico.
`close_session`	`session_id`	Fecha uma sessão de terminal ativa.
`create_snapshot`	`session_id`, `format` (txt/png/both), `intent?`	Captura um snapshot txt e/ou png de uma sessão ativa.
`send_keys`	`session_id`, `keys`, `submit?` (bool)	Envia teclas para uma sessão ativa usando o formato tmux.
`wait_for_text`	`session_id`, `pattern`, `timeout_ms?`	Aguarda um padrão regex aparecer na saída do terminal.
`run_flow`	`yaml_path?`, `yaml_string?`, `cols?`, `rows?`	Executa um fluxo TUI YAML e captura artefatos autonomamente.
`list_sessions`	(nenhum)	Lista todas as sessões de terminal ativas e seus estados.
`check_system_dependencies`	(nenhum)	Verifica se o sistema host possui todas as dependências necessárias.

Recursos:

terminal://session/{id}/screen.txt?maxLines={limit}: Leia o buffer de texto bruto da sessão de terminal ativa.

Como 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 do Sistema e Instalação

mcp-tuikit depende de utilitários de nível de sistema operacional para gerenciar pseudo-terminais e capturar telas.

Dependência Principal: `tmux`

tmux (v3.3a+, fortemente recomendado v3.5a+) é absolutamente necessário em todas as plataformas.

macOS: brew install tmux
Linux: sudo apt install tmux ou sudo dnf install tmux
Windows: winget install arndawg.tmux-windows (Não use MSYS2 ou WSL tmux se estiver executando nativamente).

Dependências Específicas da Plataforma

macOS: Usa ferramentas integradas (osascript, screencapture). Nenhuma dependência extra necessária.
Linux (Headless Nativo): Requer um compositor virtual (Xvfb para X11, sway ou kwin para Wayland).
Windows: Usa APIs de processo padrão nativas (cmd, powershell).

Problemas Conhecidos e Limitações

Consulte a Documentação de Solução de Problemas para obter detalhes completos. Limitações notáveis incluem:

Sem Modo Headless Nativo no Windows/macOS: Iniciar um terminal nativo (como Alacritty) no Mac/Windows abrirá uma janela física na sua tela. A renderização nativa verdadeiramente headless requer Linux (Xvfb/Sway/kwin). Para execução invisível no Mac/Windows, você deve usar o backend xterm.js (via Playwright).
WezTerm + Sway: Snapshots do WezTerm resultam em tela preta sob Sway headless porque ele exige estritamente contextos de GPU acelerados por hardware (Vulkan/OpenGL).
Instabilidade de Snapshots no macOS: Capturas de tela baseadas em tempo no macOS (usando CGWindowList) podem ser instáveis sob carga pesada de CPU, às vezes capturando quadros em branco.
Dependência do Tmux: Todas as operações de terminal são encapsuladas em tmux para garantir alocação estável de pseudo-terminal (PTY) e extração confiável de texto ANSI.
Sem Suporte a Mouse: Atualmente, não há suporte para interação com mouse. Operar um terminal puramente por teclas padrão é necessário. A automação de mouse em modo com janela apresenta desafios técnicos significativos em vários ambientes de sistema operacional.
Sem Gravação de Vídeo: O kit de ferramentas atualmente captura apenas snapshots estáticos de texto e PNG. A gravação de vídeo de sessões de terminal está planejada para uma versão futura.

Contribuindo

Consulte CONTRIBUTING.md para diretrizes de arquitetura, regras rigorosas de formatação/lint e o processo de PR. O desenvolvimento orientado a testes é aplicado via vitest.

Licença

MIT

MCP TUIKit

Documentação