Headless Terminal (ht) MCP

ht-mcp

Una implementación en Rust de alto rendimiento de un servidor Model Context Protocol (MCP) para terminal headless ht.

Características

• 🚀 Rust puro: Servidor MCP de un solo binario, sin dependencias externas
• 🔗 Integración directa: Incorpora la excelente librería de terminal headless ht para un rendimiento óptimo
• 🖥️ Multi-sesión: Gestión concurrente de sesiones de terminal
• 🌐 Interfaz web: Vista previa de terminal en vivo opcional

Demo

ht-mcp en Memex

ht-mcp en Claude Code

Instalación

🍺 Homebrew (Recomendado)

brew tap memextech/tap
brew install ht-mcp

📦 Binarios precompilados

Descarga desde releases:

# 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 desde el código fuente

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

Consulta docs/INSTALLATION.md para opciones de instalación detalladas.

Herramientas MCP

Herramienta	Descripción	Parámetros
ht_create_session	Crear nueva sesión de terminal	command?, enableWebServer?
ht_send_keys	Enviar pulsaciones de teclas a la sesión	sessionId, keys[]
ht_take_snapshot	Capturar el estado de la terminal	sessionId
ht_execute_command	Ejecutar comando y obtener salida	sessionId, command
ht_list_sessions	Listar todas las sesiones activas	Ninguno
ht_close_session	Cerrar sesión de terminal	sessionId

Nota: Los parámetros usan camelCase (p. ej., sessionId, enableWebServer) para compatibilidad con MCP.

Configuración

Añade a la configuración de tu cliente MCP:

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

Para rutas de instalación personalizadas:

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

Ejemplo de uso

# Start the MCP server
ht-mcp

# With debug logging
ht-mcp --debug

Una vez configurado en tu cliente MCP:

1. Crear sesión: ht_create_session → Devuelve el ID de sesión
2. Ejecutar comandos: ht_execute_command con ID de sesión y comando
3. Entrada interactiva: ht_send_keys para interacciones de varios pasos
4. Verificar estado: ht_take_snapshot para ver la terminal actual
5. Limpiar: ht_close_session cuando termines

Formato de respuesta

Este servidor devuelve respuestas de texto legibles para humanos (no JSON), diseñadas para interacción en lenguaje 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+ (instalar vía rustup)
• SO compatibles: Linux, macOS, Windows (experimental)

Desarrollo

# 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

Solución de problemas

Problemas de instalación:

• Asegúrate de tener Rust 1.75+ instalado
• Verifica la conexión a internet para los submódulos de git
• Confirma que ~/.cargo/bin esté en el PATH

Problemas en tiempo de ejecución:

• Usa ht-mcp --debug para registro detallado
• Verifica la sintaxis de configuración del cliente MCP
• Confirma la ruta del binario: which ht-mcp

Rendimiento

Comparado con la implementación original en TypeScript:

• Inicio 40x más rápido (~50ms vs ~2s)
• 70% menos memoria (~15MB vs ~50MB)
• Un solo binario (4.7MB vs ~200MB Node.js)
• Cero sobrecarga de subprocesos

Licencia

Licencia Apache 2.0

Copyright (c) 2025 Atlas Futures Inc.

Consulta LICENSE para más detalles.

Contribuciones

¡Las contribuciones son bienvenidas! Lee CONTRIBUTING.md para las pautas.

---

Construido con Memex✨

Referencia de commit fijo del submódulo