enhanced-terminal

Um executor de comandos shell / terminal com suporte a async

Documentação

Servidor MCP de Terminal Avançado

Um servidor autônomo de Model Context Protocol (MCP) que fornece execução de terminal, detecção de binários e recursos de detecção de shell.

Recursos

Ferramentas

enhanced_terminal - Executa comandos de shell com alternância assíncrona inteligente
- Saída em Fluxo Contínuo: Notificações de saída em tempo real no modo síncrono
- Alterna automaticamente para segundo plano após 50 segundos (configurável)
- Suporte a PTY com emulação de terminal adequada
- Diretório de trabalho, shell, tempo limite e limites de pré-visualização de tokens configuráveis
- Lista de bloqueio de segurança impede comandos perigosos
- Retorna ID do trabalho para rastrear tarefas em segundo plano
enhanced_terminal_job_status - Obtém status e saída de trabalhos em segundo plano
- Verifica o progresso de comandos de longa duração
- Recupera a saída completa quando concluída
- Visualiza códigos de saída e duração
enhanced_terminal_job_list - Lista todos os trabalhos (em execução e concluídos)
- Visualiza histórico recente de comandos
- Filtra e limita resultados
- Visão geral rápida dos status dos trabalhos
enhanced_terminal_job_cancel - Cancela trabalhos em segundo plano em execução (somente Unix)
- Envia SIGTERM para processos em execução
- Encerramento gracioso de comandos de longa duração
enhanced_terminal_job_stdin - Envia entrada para trabalhos em segundo plano em execução
- Escreve texto UTF-8 exato no stdin do PTY de um trabalho
- Inclua \n em input para submeter uma linha
- Útil para prompts após comandos alternarem para segundo plano
detect_binaries - Detecta ferramentas de desenvolvimento com 16 verificações simultâneas
- Verifica o PATH em busca de 190+ ferramentas de desenvolvimento comuns em 26 categorias
- Detecção rápida de versões em paralelo
- Suporta filtragem por categoria (rust_tools, python_tools, etc.)
- Categorias incluem: gerenciadores de pacotes, sistemas de build, ferramentas de linguagens de programação, editores, contêineres e mais

Observação: As informações de shell são detectadas automaticamente na inicialização do servidor e incluídas nas instruções do servidor, portanto não é necessária nenhuma chamada de ferramenta separada para descobrir shells disponíveis.

Principais Recursos

Notificações em Fluxo Contínuo: Emite notificações de registro MCP conforme a saída do comando chega (o suporte do cliente varia)
Alternância Assíncrona Inteligente: Comandos passam automaticamente para segundo plano após 50 segundos (configurável)
Lista de Bloqueio de Segurança: Bloqueia comandos perigosos como rm -rf /, shutdown, bombas de fork, etc.
Gerenciamento de Trabalhos: Rastreia, monitora, envia entrada para stdin e cancela trabalhos em segundo plano com metadados ricos
Filtragem de Trabalhos: Filtra trabalhos por status, tags ou diretório de trabalho
Paginação de Saída: Busca intervalos específicos de bytes em registros muito longos
Tags de Trabalhos: Categoriza trabalhos com tags personalizadas para facilitar a filtragem
Registro de Chamadas: Acrescenta toda solicitação de execução de shell enhanced_terminal a enhanced_terminal_calls.jsonl
16 Verificações Simultâneas: Detecção rápida e paralela de binários
Suporte a PTY: Emulação completa de terminal para comandos interativos

Instalação

Pré-requisitos

Rust com suporte à edição 2024 (Rust 1.85+ recomendado)
Cargo

Compilar a partir do Código-Fonte

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

O binário estará localizado em target/release/enhanced-terminal-mcp.

Fluxo de Trabalho com Sudo (Recomendado)

Este servidor lida com comandos sudo automaticamente para evitar prompts de senha durante a execução de ferramentas:

Primeiro comando sudo: Dispara um diálogo askpass (via sudo -A -v) para autenticar uma vez
Comandos sudo subsequentes: Reescritos para sudo -n (não interativo) e usam o timestamp sudo em cache
Keepalive: Tarefa em segundo plano renova o timestamp a cada 5 minutos para mantê-lo válido

Tudo isso está habilitado por padrão. O campo sudo_wrapper_applied nos resultados mostra quando o sinalizador -n foi adicionado.

Configuração Recomendada: Compartilhamento de Timestamp do Sudoers

Para a melhor experiência, configure o sudo para compartilhar timestamps em todas as suas sessões (não apenas por TTY):

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

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

Adicione estas linhas:

Defaults !tty_tickets
Defaults timestamp_timeout=10
Defaults use_pty

Benefícios:
- Ative o sudo uma vez em qualquer terminal: sudo -v
- O servidor MCP reutilizará esse timestamp automaticamente
- Nenhum diálogo askpass necessário (a menos que o timestamp expire)
- Funciona em todas as suas sessões de terminal e no servidor MCP
Nota de segurança: !tty_tickets significa que qualquer processo executado com seu usuário pode reutilizar seu timestamp sudo enquanto ele estiver válido. Mantenha timestamp_timeout razoável (por exemplo, 10 minutos).

Alternativa: Fluxo de Trabalho Baseado em Askpass (Comportamento Padrão)

Se você preferir não alterar o sudoers, os padrões do servidor funcionarão:

Caminho padrão do askpass: ~/scripts/askpass-zenity.sh
Primeiro comando sudo → diálogo askpass
Servidor mantém o timestamp ativo → sem mais prompts

O servidor repassará automaticamente estas variáveis de ambiente para o askpass gráfico:

DISPLAY (padrão: :0)
WAYLAND_DISPLAY (padrão: wayland-0)
XDG_RUNTIME_DIR
DBUS_SESSION_BUS_ADDRESS

Configuração (Opcional)

Estas variáveis de ambiente controlam o comportamento do sudo (todas com padrão LIGADO):

# 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

Depuração

Habilite o registro detalhado para ver o comportamento de preparação/encapsulamento do sudo:

RUST_LOG=debug enhanced-terminal-mcp

Procure linhas de registro sobre sudo -A -v (preparação) e sudo -n (encapsulamento).

Uso

Executando o Servidor

O servidor usa transporte stdio para comunicação MCP:

./enhanced-terminal-mcp

Configuração

Adicione à configuração do seu cliente MCP:

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

Registro de Chamadas

Cada chamada de ferramenta enhanced_terminal é acrescentada como um objeto JSON por linha em enhanced_terminal_calls.jsonl na raiz do repositório. Cada entrada inclui um datetime RFC3339 UTC, o nome da ferramenta e os parâmetros completos enviados. As gravações usam um mutex de processo e, em Unix, um bloqueio exclusivo de arquivo para que chamadas de ferramentas concorrentes e processos de servidor de teste não intercalem registros JSON.

Substitua o caminho do registro com ENHANCED_TERMINAL_CALL_LOG_PATH se necessário.

Padrões do Diretório de Trabalho

Se cwd for omitido, o padrão será .. Esse . é resolvido em relação ao diretório de trabalho do processo do servidor MCP fornecido pelo chamador/cliente. Na prática, quando o Codex inicia este servidor MCP a partir de um projeto, a omissão de cwd usa o diretório de inicialização do projeto/servidor. Passe cwd explicitamente quando precisar de um repositório ou subdiretório específico.

Exemplos de Ferramentas

enhanced_terminal

Execução síncrona básica (conclui rapidamente). cwd é opcional; omiti-lo usa o diretório de trabalho do processo do servidor MCP fornecido pelo chamador/cliente:

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

Comando de longa duração (alterna automaticamente para segundo plano após 50 segundos por padrão):

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

Força execução assíncrona imediata (útil para comandos interativos que precisam de stdin):

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

Com variáveis de ambiente:

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

Força execução síncrona (aguarda a conclusão):

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

Com lista de bloqueio personalizada:

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

Com tags para categorização de trabalhos:

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

Pré-visualização limitada por tokens (tokenizador GPT-5/o200k_base):

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

preview_tokens tem padrão de 4096. Defina como 0 para desativar o truncamento de tokens para o buffer de pré-visualização limitado em memória.

Os IDs de trabalhos são identificadores legíveis do tipo adjetivo-substantivo-número, como brave-river-1, facilitando a cópia e a discussão em comparação com IDs numéricos.

enhanced_terminal_job_status

Obter saída completa. job_status retorna o resumo do comando por padrão; passe full_command: true apenas quando precisar do texto completo do comando:

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

Obter saída incremental (apenas o que é novo desde a última verificação):

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

Obter saída paginada (primeiros 1000 bytes):

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

Obter saída paginada (próximos 1000 bytes):

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

enhanced_terminal_job_list

Listar todos os trabalhos:

{
  "max_jobs": 50
}

Filtrar por status:

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

Filtrar por tag:

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

Filtrar por diretório de trabalho:

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

Filtros combinados com ordem de classificação:

{
  "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

Escrever entrada em um trabalho assíncrono em execução. Novas linhas não são acrescentadas automaticamente, portanto inclua \n quando quiser submeter uma linha:

{
  "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
}

Categorias de Binários

A ferramenta detect_binaries suporta filtragem por estas categorias:

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

Desenvolvimento

Compilação

cargo build

Testes

cargo test

Executando Testes para Lista de Bloqueio

cargo test denylist

Executando Localmente

cargo run

Segurança

Lista de Bloqueio de Comandos

O servidor inclui uma lista de bloqueio abrangente que impede comandos perigosos:

Operações Destrutivas:

rm -rf /, rm -rf /*, rm --no-preserve-root
mkfs, dd if=/dev/zero, formatação de sistema de arquivos
Gravações em /dev/sda, /dev/hda

Manipulação do Sistema:

shutdown, reboot, halt, poweroff
init 0, init 6, comandos de energia do systemctl

Bombas de Fork:

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

Alterações Perigosas de Permissões:

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

Riscos de Gerenciadores de Pacotes:

Comandos de desinstalação forçada em apt, yum, dnf, pacman

Outros Riscos:

Manipulação de módulos do kernel
Exclusão de cron (crontab -r)
Movimentação de diretórios do sistema

Lista de Bloqueio Personalizada

Você pode adicionar padrões personalizados por meio do parâmetro custom_denylist:

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

Limite Assíncrono

Comandos que excedem o limite assíncrono do servidor (padrão: 50 segundos, configurável com ENHANCED_TERMINAL_ASYNC_THRESHOLD_SECS) alternam automaticamente para execução em segundo plano. Isso evita:

Comandos de longa duração bloqueando o servidor MCP
Problemas de tempo limite com instalações de pacotes
Processos de build lentos travando a interface

Defina force_sync: true para desativar esse comportamento para comandos específicos. Defina force_async: true para retornar um ID de trabalho imediatamente sem aguardar o limite, que é o fluxo recomendado antes de usar enhanced_terminal_job_stdin.

Saída Incremental

Use enhanced_terminal_job_status com incremental: true para polling eficiente de tarefas de longa duração:

A primeira chamada retorna toda a saída acumulada até o momento
Chamadas subsequentes retornam apenas a nova saída desde a última verificação
A posição de leitura é rastreada por job_id
Redefina chamando com incremental: false

Isso permite um comportamento semelhante a streaming sem infraestrutura real de streaming.

Entrada Interativa de Tarefas

Use enhanced_terminal_job_stdin para gravar no stdin do PTY de uma tarefa em execução depois que ela tiver sido movida para segundo plano. Para comandos que aguardam entrada, inicie-os com force_async: true para que a primeira chamada retorne um ID de tarefa imediatamente. A ferramenta de stdin grava exatamente a string input fornecida e não acrescenta uma nova linha automaticamente.

Paginação de Saída

Para saídas muito longas, use o modo de paginação em enhanced_terminal_job_status:

Defina offset_bytes como a posição inicial em bytes
Defina limit_bytes como o número de bytes a selecionar (0 = todo o restante)
Retorna o sinalizador has_more e total_length
Permite buscar em segmentos específicos sem recuperar a saída completa

Fluxo de trabalho de exemplo:

// 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}

Tags e Filtros de Tarefas

Marque as tarefas com tags ao criá-las para uma organização mais fácil:

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

Filtre tarefas por vários critérios em enhanced_terminal_job_list:

status_filter: Corresponder a status específicos (ex.: ["Running", "Completed"])
tag_filter: Mostrar apenas tarefas com uma tag específica
cwd_filter: Mostrar apenas tarefas de um diretório específico
sort_order: "newest" (padrão) ou "oldest"

Todos os filtros podem ser combinados para consultas poderosas.

Arquitetura

Este servidor usa uma estrutura modular com a edição Rust 2024:

src/main.rs - Ponto de entrada e inicialização do servidor
src/server.rs - Implementação do servidor MCP com manipuladores de ferramentas
src/detection/ - Lógica de detecção de binários e shell
src/tools/ - Execução de terminal, gerenciamento de tarefas, lista de bloqueio de segurança

Dependências

rmcp 0.8 - SDK oficial em Rust para o Model Context Protocol
tokio 1.x - Runtime assíncrono
portable-pty 0.8 - Suporte a PTY multiplataforma para emulação de terminal
serde/serde_json 1.x - Serialização
schemars 1.0 - Geração de esquemas JSON para entradas de ferramentas
anyhow 1.x - Tratamento de erros
nix 0.29 - Tratamento de sinais Unix (somente Unix)
tiktoken-rs 0.11 - Contagem de tokens compatível com GPT-5/o200k_base para visualizações
chrono 0.4 - Carimbos de data/hora UTC para registro de chamadas
tracing/tracing-subscriber 0.1/0.3 - Registro estruturado do servidor

Desempenho

16 verificações de binários concorrentes - Detecção rápida de ferramentas em paralelo (configurável)
Alternância assíncrona inteligente - Segundo plano automático após 50s (configurável)
Monitoramento em segundo plano com Tokio - As tarefas continuam em execução após a alternância assíncrona inteligente
Captura incremental de saída - Consulte a nova saída com rastreamento de posição de leitura; paginação por bytes está disponível para logs longos
Sem timeout por padrão - Defina a variável de ambiente ENHANCED_TERMINAL_TIMEOUT_SECS para habilitar

Configuração

Valores Padrão

Shell: bash
Diretório de Trabalho: . resolvido a partir do diretório de trabalho do processo do servidor MCP fornecido pelo chamador/cliente
Tokens de Visualização: 4096 tokens GPT-5/o200k_base (0 desativa a truncagem de tokens)
Limite Assíncrono: 50 segundos (ENHANCED_TERMINAL_ASYNC_THRESHOLD_SECS)
Timeout: None por padrão (ENHANCED_TERMINAL_TIMEOUT_SECS habilita um timeout)
IDs de Tarefas: identificadores legíveis adjective-noun-number
Registro de Chamadas: JSONL seguro para concorrência em enhanced_terminal_calls.jsonl na raiz do repositório (ENHANCED_TERMINAL_CALL_LOG_PATH substitui)
Concorrência Máxima de Detecção de Binários: 16
Timeout de Sondagem de Versão: 1500 ms

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes