Headless Terminal (ht) MCP

ht-mcp

Uma implementação em Rust de alto desempenho de um servidor Model Context Protocol (MCP) para terminal headless ht.

Recursos

• 🚀 Rust Puro: Servidor MCP em um único binário, sem dependências externas
• 🔗 Integração Direta: Incorpore a excelente biblioteca de terminal headless ht para desempenho ideal
• 🖥️ Multi-Sessão: Gerenciamento concorrente de sessões de terminal
• 🌐 Interface Web: Pré-visualização opcional de terminal ao vivo

Demonstração

ht-mcp no Memex

ht-mcp no Claude Code

Instalação

🍺 Homebrew (Recomendado)

brew tap memextech/tap
brew install ht-mcp

📦 Binários Pré-compilados

Baixe dos lançamentos:

# macOS Intel
curl -L https://github.com/memextech/ht-mcp/releases/latest/download/ht-mcp-x86_64-apple-darwin -o ht-mcp

# macOS Apple Silicon
curl -L https://github.com/memextech/ht-mcp/releases/latest/download/ht-mcp-aarch64-apple-darwin -o ht-mcp

# Linux
curl -L https://github.com/memextech/ht-mcp/releases/latest/download/ht-mcp-x86_64-unknown-linux-gnu -o ht-mcp

# Windows (PowerShell)
curl.exe -L https://github.com/memextech/ht-mcp/releases/latest/download/ht-mcp-x86_64-pc-windows-msvc -o ht-mcp.exe

# Make executable and install
chmod +x ht-mcp && sudo mv ht-mcp /usr/local/bin/

🦀 Cargo

# From crates.io (stable)
cargo install ht-mcp

# From git (latest)
cargo install --git https://github.com/memextech/ht-mcp

🔧 Compilar a partir do Código Fonte

git clone https://github.com/memextech/ht-mcp.git
cd ht-mcp
git submodule update --init --recursive
cargo install --path .

Consulte docs/INSTALLATION.md para opções detalhadas de instalação.

Ferramentas MCP

Ferramenta	Descrição	Parâmetros
ht_create_session	Criar nova sessão de terminal	command?, enableWebServer?
ht_send_keys	Enviar teclas para a sessão	sessionId, keys[]
ht_take_snapshot	Capturar estado do terminal	sessionId
ht_execute_command	Executar comando e obter saída	sessionId, command
ht_list_sessions	Listar todas as sessões ativas	Nenhum
ht_close_session	Fechar sessão de terminal	sessionId

Nota: Os parâmetros usam camelCase (por exemplo, sessionId, enableWebServer) para compatibilidade com MCP.

Configuração

Adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "ht-mcp": {
      "command": "ht-mcp",
      "args": ["--debug"]
    }
  }
}

Para caminhos de instalação personalizados:

{
  "mcpServers": {
    "ht-mcp": {
      "command": "/path/to/ht-mcp",
      "args": []
    }
  }
}

Exemplo de Uso

# Start the MCP server
ht-mcp

# With debug logging
ht-mcp --debug

Depois de configurado no seu cliente MCP:

1. Criar sessão: ht_create_session → Retorna o ID da sessão
2. Executar comandos: ht_execute_command com o ID da sessão e o comando
3. Entrada interativa: ht_send_keys para interações de múltiplas etapas
4. Verificar estado: ht_take_snapshot para ver o terminal atual
5. Limpar: ht_close_session quando terminar

Formato de Resposta

Este servidor retorna respostas de texto legíveis por humanos (não JSON), projetadas para interação em linguagem natural:

# Create session response
HT session created successfully!

Session ID: abc123-def456-789...

🌐 Web server enabled! View live terminal at: http://127.0.0.1:3618

# Terminal snapshot response
Terminal Snapshot (Session: abc123...)

bash-3.2$ ls -la
total 16
drwxr-xr-x  4 user staff  128 Jun 13 10:30 .
-rw-r--r--  1 user staff   45 Jun 13 10:30 file.txt
bash-3.2$

Requisitos

• Rust: 1.75+ (instale via rustup)
• SO suportado: Linux, macOS, Windows (experimental)

Desenvolvimento

# Clone with submodules
git clone --recursive https://github.com/memextech/ht-mcp.git
cd ht-mcp

# Build
cargo build

# Run
cargo run

# Test
cargo test

Solução de Problemas

Problemas de Instalação:

• Certifique-se de que o Rust 1.75+ esteja instalado
• Verifique a conexão com a internet para submódulos git
• Verifique se ~/.cargo/bin está no PATH

Problemas em Tempo de Execução:

• Use ht-mcp --debug para registro detalhado (verbose logging)
• Verifique a sintaxe da configuração do cliente MCP
• Verifique o caminho do binário: which ht-mcp

Desempenho

Comparado à implementação original em TypeScript:

• Inicialização 40x mais rápida (~50ms vs ~2s)
• 70% menos memória (~15MB vs ~50MB)
• Binário único (4.7MB vs ~200MB Node.js)
• Zero sobrecarga de subprocesso

Licença

Licença Apache 2.0

Copyright (c) 2025 Atlas Futures Inc.

Consulte LICENSE para detalhes.

Contribuindo

Contribuições são bem-vindas! Leia CONTRIBUTING.md para diretrizes.

---

Construído com Memex✨

Referência de commit fixa do submódulo