enhanced-terminal

Un ejecutor de comandos de shell / terminal con soporte asíncrono

Documentación

Servidor MCP de Terminal Mejorado

Un servidor independiente de Protocolo de Contexto de Modelo (MCP) que proporciona capacidades de ejecución de terminal, detección de binarios y detección de shell.

Características

Herramientas

enhanced_terminal - Ejecuta comandos de shell con cambio asíncrono inteligente
- Salida en Streaming: Notificaciones de salida en tiempo real en modo síncrono
- Cambia automáticamente a segundo plano después de 50 segundos (configurable)
- Soporte PTY con emulación de terminal adecuada
- Directorio de trabajo, shell, tiempo de espera y límites de vista previa de tokens configurables
- Lista de denegación de seguridad bloquea comandos peligrosos
- Devuelve ID de trabajo para rastrear tareas en segundo plano
enhanced_terminal_job_status - Obtiene estado y salida de trabajos en segundo plano
- Verifica el progreso de comandos de larga duración
- Recupera la salida completa cuando termina
- Ve códigos de salida y duración
enhanced_terminal_job_list - Lista todos los trabajos (en ejecución y completados)
- Ve el historial reciente de comandos
- Filtra y limita resultados
- Vista rápida de estados de trabajos
enhanced_terminal_job_cancel - Cancela trabajos en segundo plano en ejecución (solo Unix)
- Envía SIGTERM a procesos en ejecución
- Terminación elegante de comandos de larga duración
enhanced_terminal_job_stdin - Envía entrada a trabajos en segundo plano en ejecución
- Escribe texto UTF-8 exacto en el stdin PTY de un trabajo
- Incluye \n en input para enviar una línea
- Útil para indicadores después de que los comandos cambian a segundo plano
detect_binaries - Detecta herramientas de desarrollo con 16 verificaciones concurrentes
- Escanea PATH en busca de 190+ herramientas de desarrollo comunes en 26 categorías
- Detección rápida de versiones en paralelo
- Soporta filtrado por categoría (rust_tools, python_tools, etc.)
- Las categorías incluyen: gestores de paquetes, sistemas de compilación, herramientas de lenguajes de programación, editores, contenedores y más

Nota: La información del shell se detecta automáticamente al iniciar el servidor y se incluye en las instrucciones del servidor, por lo que no se necesita una llamada de herramienta separada para descubrir los shells disponibles.

Características Clave

Notificaciones en Streaming: Emite notificaciones de registro MCP a medida que llega la salida del comando (el soporte del cliente varía)
Cambio Asíncrono Inteligente: Los comandos se mueven automáticamente a segundo plano después de 50 segundos (configurable)
Lista de Denegación de Seguridad: Bloquea comandos peligrosos como rm -rf /, shutdown, bombas fork, etc.
Gestión de Trabajos: Rastrea, monitorea, envía stdin y cancela trabajos en segundo plano con metadatos enriquecidos
Filtrado de Trabajos: Filtra trabajos por estado, etiquetas o directorio de trabajo
Paginación de Salida: Busca en rangos de bytes específicos de registros muy largos
Etiquetas de Trabajos: Categoriza trabajos con etiquetas personalizadas para filtrado fácil
Registro de Llamadas: Agrega cada solicitud de ejecución de shell enhanced_terminal a enhanced_terminal_calls.jsonl
16 Verificaciones Concurrentes: Detección rápida de binarios en paralelo
Soporte PTY: Emulación de terminal completa para comandos interactivos

Instalación

Requisitos Previos

Rust con soporte de edición 2024 (Rust 1.85+ recomendado)
Cargo

Compilar desde el Código Fuente

git clone <repository-url>
cd enhanced-terminal-mcp
cargo build --release

El binario se ubicará en target/release/enhanced-terminal-mcp.

Flujo de Trabajo Sudo (Recomendado)

Este servidor maneja comandos sudo automáticamente para evitar indicaciones de contraseña durante la ejecución de herramientas:

Primer comando sudo: Activa un diálogo askpass (a través de sudo -A -v) para autenticarse una vez
Comandos sudo subsiguientes: Se reescriben a sudo -n (no interactivo) y usan la marca de tiempo sudo almacenada en caché
Keepalive: La tarea en segundo plano actualiza la marca de tiempo cada 5 minutos para mantenerla válida

Todo esto está habilitado por defecto. El campo sudo_wrapper_applied en los resultados muestra cuándo se agregó la bandera -n.

Configuración Recomendada: Compartición de Marca de Tiempo Sudoers

Para la mejor experiencia, configure sudo para compartir marcas de tiempo en todas sus sesiones (no solo por TTY):

Cree /etc/sudoers.d/enhanced-terminal-mcp usando visudo:

sudo visudo -f /etc/sudoers.d/enhanced-terminal-mcp

Agregue estas líneas:

Defaults !tty_tickets
Defaults timestamp_timeout=10
Defaults use_pty

Beneficios:
- Active sudo una vez en cualquier terminal: sudo -v
- El servidor MCP reutilizará esa marca de tiempo automáticamente
- No se necesita diálogo askpass (a menos que la marca de tiempo expire)
- Funciona en todas sus sesiones de terminal y el servidor MCP
Nota de seguridad: !tty_tickets significa que cualquier proceso que se ejecute como su usuario puede reutilizar su marca de tiempo sudo mientras esté válida. Mantenga timestamp_timeout razonable (por ejemplo, 10 minutos).

Alternativa: Flujo de Trabajo Basado en Askpass (Comportamiento Predeterminado)

Si prefiere no cambiar sudoers, los valores predeterminados del servidor funcionarán:

Ruta askpass predeterminada: ~/scripts/askpass-zenity.sh
Primer comando sudo → diálogo askpass
El servidor mantiene la marca de tiempo viva → sin más indicaciones

El servidor pasará automáticamente estas variables de entorno para askpass de GUI:

DISPLAY (predeterminado a :0)
WAYLAND_DISPLAY (predeterminado a wayland-0)
XDG_RUNTIME_DIR
DBUS_SESSION_BUS_ADDRESS

Configuración (Opcional)

Estas variables de entorno controlan el comportamiento de sudo (todas predeterminadas a ON):

# Enable/disable sudo wrapping and keepalive (default: 1)
ENHANCED_TERMINAL_SUDO_WRAP=1
ENHANCED_TERMINAL_SUDO_KEEPALIVE=1
ENHANCED_TERMINAL_SUDO_KEEPALIVE_PRIME=1

# Custom askpass path (default: ~/scripts/askpass-zenity.sh)
ENHANCED_TERMINAL_SUDO_ASKPASS=/path/to/your/askpass.sh

# Keepalive refresh interval in seconds (default: 300, min: 30)
ENHANCED_TERMINAL_SUDO_KEEPALIVE_REFRESH_SECS=300

Depuración

Habilite el registro detallado para ver el comportamiento de preparación/envoltura de sudo:

RUST_LOG=debug enhanced-terminal-mcp

Busque líneas de registro sobre sudo -A -v (preparación) y sudo -n (envoltura).

Uso

Ejecutar el Servidor

El servidor usa transporte stdio para la comunicación MCP:

./enhanced-terminal-mcp

Configuración

Agregue a la configuración de su cliente MCP:

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

Registro de Llamadas

Cada llamada de herramienta enhanced_terminal se agrega como un objeto JSON por línea a enhanced_terminal_calls.jsonl en la raíz del repositorio. Cada entrada incluye un datetime RFC3339 UTC, el nombre de la herramienta y los parámetros completos enviados. Las escrituras usan un mutex en proceso y, en Unix, un bloqueo de archivo exclusivo para que las llamadas de herramientas concurrentes y los procesos de servidor de prueba no intercalen registros JSON.

Anule la ruta del registro con ENHANCED_TERMINAL_CALL_LOG_PATH si es necesario.

Valores Predeterminados del Directorio de Trabajo

Si se omite cwd, se predetermina a .. Ese . se resuelve en relación con el directorio de trabajo del proceso del servidor MCP proporcionado por el llamador/cliente. En la práctica, cuando Codex inicia este servidor MCP desde un proyecto, el cwd omitido usa ese directorio de lanzamiento del proyecto/servidor. Pase cwd explícitamente cuando necesite un repositorio o subdirectorio específico.

Ejemplos de Herramientas

enhanced_terminal

Ejecución síncrona básica (se completa rápidamente). cwd es opcional; omitirlo usa el directorio de trabajo del proceso del servidor MCP proporcionado por el llamador/cliente:

{
  "command": "ls -la",
  "cwd": ".",
  "shell": "bash"
}

Comando de larga duración (cambia automáticamente a segundo plano después de 50 segundos por defecto):

{
  "command": "npm install",
  "cwd": "./my-project",
  "shell": "bash"
}

Forzar ejecución asíncrona inmediata (útil para comandos interactivos que necesitan stdin):

{
  "command": "read -p 'stdin> ' value; echo received=$value",
  "force_async": true
}

Con variables de entorno:

{
  "command": "npm run build",
  "env_vars": {
    "NODE_ENV": "production",
    "API_KEY": "secret123"
  }
}

Forzar ejecución síncrona (esperar finalización):

{
  "command": "cargo build --release",
  "force_sync": true
}

Con lista de denegación personalizada:

{
  "command": "docker run myimage",
  "custom_denylist": ["docker rm", "docker system prune"]
}

Con etiquetas para categorización de trabajos:

{
  "command": "cargo build --release",
  "tags": ["build", "release"]
}

Vista previa limitada por tokens (tokenizador GPT-5/o200k_base):

{
  "command": "cargo test",
  "preview_tokens": 4000
}

preview_tokens predeterminado a 4096. Establézcalo en 0 para deshabilitar la truncación de tokens para el búfer de vista previa en memoria limitado.

Los IDs de trabajos son identificadores legibles de adjetivo-sustantivo-número como brave-river-1, lo que los hace más fáciles de copiar y discutir que los IDs numéricos.

enhanced_terminal_job_status

Obtener salida completa. job_status devuelve el resumen del comando por defecto; pase full_command: true solo cuando necesite el texto completo del comando:

{
  "job_id": "brave-river-1",
  "incremental": false,
  "full_command": true
}

Obtener salida incremental (solo nueva desde la última verificación):

{
  "job_id": "brave-river-1",
  "incremental": true
}

Obtener salida paginada (primeros 1000 bytes):

{
  "job_id": "brave-river-1",
  "offset_bytes": 0,
  "limit_bytes": 1000
}

Obtener salida paginada (siguientes 1000 bytes):

{
  "job_id": "brave-river-1",
  "offset_bytes": 1000,
  "limit_bytes": 1000
}

enhanced_terminal_job_list

Listar todos los trabajos:

{
  "max_jobs": 50
}

Filtrar por estado:

{
  "max_jobs": 50,
  "status_filter": ["Running", "Completed"]
}

Filtrar por etiqueta:

{
  "max_jobs": 50,
  "tag_filter": "build"
}

Filtrar por directorio de trabajo:

{
  "max_jobs": 50,
  "cwd_filter": "/home/user/project"
}

Filtros combinados con orden de clasificación:

{
  "max_jobs": 50,
  "status_filter": ["Completed"],
  "tag_filter": "test",
  "sort_order": "oldest"
}

enhanced_terminal_job_cancel

{
  "job_id": "brave-river-1"
}

enhanced_terminal_job_stdin

Escribir entrada a un trabajo asíncrono en ejecución. Las nuevas líneas no se agregan automáticamente, así que incluya \n cuando quiera enviar una línea:

{
  "job_id": "brave-river-1",
  "input": "yes\n"
}

detect_binaries

{
  "filter_categories": ["rust_tools", "python_tools"],
  "max_concurrency": 16,
  "version_timeout_ms": 1500,
  "include_missing": false
}

Categorías de Binarios

La herramienta detect_binaries admite filtrado por estas categorías:

package_managers - npm, pip, cargo, dnf, apt, snap, flatpak, brew, pnpm, uv, poetry, pipx
rust_tools - cargo, rustc, rustfmt, clippy-driver
python_tools - python, python3, pip, pytest, black, ruff, mypy, uv, poetry, pipenv, pipx, pyright, pylint, flake8, isort, ipython
build_systems - make, cmake, ninja, gradle, maven, mvn
c_cpp_tools - gcc, g++, clang, gdb, lldb
java_jvm_tools - java, javac, javadoc, jar, jarsigner, jconsole, jdeps, jlink, jshell, kotlin, kotlinc, scala, scalac, groovy, groovyc
maven_tools - mvn, mvnw, mvnd
node_js_tools - node, deno, bun, npm, yarn, pnpm, tsx, tsc, biome, prettier, eslint
go_tools - go, gofmt
editors_dev - vim, nvim, emacs, code, hx, nano, micro
search_productivity - rg, fd, fzf, jq, bat, tree, exa, sd, zoxide, lsd, dust, btm, broot, choose
system_perf - htop, ps, top, df, du
containers - docker, podman, kubectl, helm, docker-compose, kind, minikube, skopeo, buildah, nerdctl, k9s
networking - curl, wget, dig, traceroute, http, nc, nmap, ss, ping, mtr, socat
security - openssl, gpg, ssh-keygen, age, sops, vault, pass
auth_helpers - zenity, ssh-askpass, sshaskpass, ksshaskpass, lxqt-openssh-askpass, gnome-ssh-askpass, x11-ssh-askpass, variantes de pinentry
databases - sqlite3, psql, mysql, redis-cli, mongosh, duckdb, clickhouse-client, redis-server
vcs - git, gh, lazygit, tig, gitui, hg, svn
cloud_cli - aws, gcloud, az, doctl, fly, vercel, wrangler
iac_tools - terraform, tofu, pulumi, ansible, ansible-playbook, vagrant, packer
media_tools - ffmpeg, ffprobe, convert, magick, exiftool, yt-dlp, sox
ai_ml_tools - ollama, huggingface-cli, nvidia-smi, nvcc, rocm-smi, dvc, mlflow
docs_tools - pandoc, sphinx-build, mkdocs, doxygen, asciidoctor, mdbook
ruby_tools - ruby, gem, bundle, rake, irb, rails
dotnet_tools - dotnet, nuget, msbuild
cad_utils - ODAFileConverter, dwg2svg, dwg2SVG, dwg2bmp, dwg2pdf, qcad, librecad, freecad, freecadcmd, openscad, dxf2gcode

Desarrollo

Compilación

cargo build

Pruebas

cargo test

Ejecutar Pruebas para la Lista de Denegación

cargo test denylist

Ejecutar Localmente

cargo run

Seguridad

Lista de Denegación de Comandos

El servidor incluye una lista de denegación integral que bloquea comandos peligrosos:

Operaciones Destructivas:

rm -rf /, rm -rf /*, rm --no-preserve-root
mkfs, dd if=/dev/zero, formateo de sistemas de archivos
Escrituras a /dev/sda, /dev/hda

Manipulación del Sistema:

shutdown, reboot, halt, poweroff
init 0, init 6, comandos de energía de systemctl

Bombas Fork:

:(){:|:&};: y variantes

Cambios de Permisos Peligrosos:

chmod 777 /, chmod -R 777 /
chown -R root, chown root /

Riesgos del Gestor de Paquetes:

Comandos de desinstalación forzada en apt, yum, dnf, pacman

Otros Riesgos:

Manipulación de módulos del kernel
Eliminación de cron (crontab -r)
Mover directorios del sistema

Lista de Denegación Personalizada

Puede agregar patrones personalizados a través del parámetro custom_denylist:

{
  "command": "docker run myimage",
  "custom_denylist": ["docker rm -f", "kubectl delete"]
}

Umbral Asíncrono

Los comandos que exceden el umbral asíncrono del servidor (predeterminado: 50 segundos, configurable con ENHANCED_TERMINAL_ASYNC_THRESHOLD_SECS) cambian automáticamente a ejecución en segundo plano. Esto evita:

Que los comandos de larga duración bloqueen el servidor MCP
Problemas de tiempo de espera con instalaciones de paquetes
Procesos de compilación lentos que cuelguen la interfaz

Establezca force_sync: true para deshabilitar este comportamiento para comandos específicos. Establezca force_async: true para devolver un ID de trabajo inmediatamente sin esperar el umbral, que es el flujo recomendado antes de usar enhanced_terminal_job_stdin.

Salida Incremental

Usa enhanced_terminal_job_status con incremental: true para un sondeo eficiente de trabajos de larga duración:

La primera llamada devuelve toda la salida acumulada hasta el momento
Las llamadas posteriores devuelven solo la salida nueva desde la última comprobación
La posición de lectura se rastrea por job_id
Se restablece llamando con incremental: false

Esto permite un comportamiento similar al streaming sin infraestructura de streaming real.

Entrada Interactiva de Trabajos

Usa enhanced_terminal_job_stdin para escribir en la entrada estándar PTY de un trabajo en ejecución después de que haya pasado a segundo plano. Para comandos que esperan entrada, inícialos con force_async: true para que la primera llamada devuelva un ID de trabajo inmediatamente. La herramienta de stdin escribe exactamente la cadena input proporcionada y no añade una nueva línea automáticamente.

Paginación de Salida

Para salidas muy largas, usa el modo de paginación en enhanced_terminal_job_status:

Establece offset_bytes en la posición inicial de bytes
Establece limit_bytes en el número de bytes a seleccionar (0 = todo lo restante)
Devuelve el indicador has_more y total_length
Permite buscar en segmentos específicos sin recuperar la salida completa

Flujo de trabajo de ejemplo:

// Get first 1000 bytes
{"job_id": "brave-river-1", "offset_bytes": 0, "limit_bytes": 1000}
// Get next 1000 bytes
{"job_id": "brave-river-1", "offset_bytes": 1000, "limit_bytes": 1000}
// Get all remaining
{"job_id": "brave-river-1", "offset_bytes": 2000, "limit_bytes": 0}

Etiquetas y Filtrado de Trabajos

Etiqueta los trabajos al crearlos para una organización más fácil:

{
  "command": "cargo test",
  "tags": ["test", "ci"]
}

Filtra trabajos por varios criterios en enhanced_terminal_job_list:

status_filter: Coincide con estados específicos (p. ej., ["Running", "Completed"])
tag_filter: Muestra solo trabajos con una etiqueta específica
cwd_filter: Muestra solo trabajos de un directorio específico
sort_order: "newest" (predeterminado) u "oldest"

Todos los filtros se pueden combinar para consultas potentes.

Arquitectura

Este servidor usa una estructura modular con la edición Rust 2024:

src/main.rs - Punto de entrada e inicialización del servidor
src/server.rs - Implementación del servidor MCP con manejadores de herramientas
src/detection/ - Lógica de detección de binarios y shells
src/tools/ - Ejecución de terminal, gestión de trabajos, lista de denegación de seguridad

Dependencias

rmcp 0.8 - SDK oficial de Rust para Model Context Protocol
tokio 1.x - Runtime asíncrono
portable-pty 0.8 - Soporte PTY multiplataforma para emulación de terminal
serde/serde_json 1.x - Serialización
schemars 1.0 - Generación de esquemas JSON para entradas de herramientas
anyhow 1.x - Manejo de errores
nix 0.29 - Manejo de señales Unix (solo Unix)
tiktoken-rs 0.11 - Conteo de tokens compatible con GPT-5/o200k_base para vistas previas
chrono 0.4 - Marcas de tiempo UTC para registro de llamadas
tracing/tracing-subscriber 0.1/0.3 - Registro estructurado del servidor

Rendimiento

16 comprobaciones de binarios concurrentes - Detección rápida y paralela de herramientas (configurable)
Cambio asíncrono inteligente - Segundo plano automático después de 50s (configurable)
Monitoreo en segundo plano de Tokio - Los trabajos continúan ejecutándose después del cambio asíncrono inteligente
Captura incremental de salida - Sondea nueva salida con seguimiento de posición de lectura; la paginación por bytes está disponible para registros largos
Sin tiempo de espera por defecto - Establece la variable de entorno ENHANCED_TERMINAL_TIMEOUT_SECS para habilitarlo

Configuración

Valores Predeterminados

Shell: bash
Directorio de Trabajo: . resuelto desde el directorio de trabajo del proceso del servidor MCP proporcionado por el llamador/cliente
Tokens de Vista Previa: 4096 tokens GPT-5/o200k_base (0 desactiva la truncación de tokens)
Umbral Asíncrono: 50 segundos (ENHANCED_TERMINAL_ASYNC_THRESHOLD_SECS)
Tiempo de Espera: None por defecto (ENHANCED_TERMINAL_TIMEOUT_SECS habilita un tiempo de espera)
IDs de Trabajo: identificadores adjective-noun-number legibles
Registro de Llamadas: JSONL seguro para concurrencia en enhanced_terminal_calls.jsonl en la raíz del repositorio (ENHANCED_TERMINAL_CALL_LOG_PATH lo anula)
Máxima Concurrencia de Detección de Binarios: 16
Tiempo de Espera de Sonda de Versión: 1500 ms

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles