Assistente AI inteligente para o terminal Linux/Mac
MCP Terminal Assistant transforma seu terminal em um assistente inteligente que entende contexto, executa múltiplos comandos automaticamente e aprende com seu uso diário. Não mais pesquisas no Google - tenha respostas precisas direto no terminal.
Interface principal: ipcom-chat - uma experiência rica e interativa no terminal com histórico persistente, markdown rendering e execução iterativa de comandos.
# 1. Instalar (uma linha, automático)
curl -sSL https://raw.githubusercontent.com/fabiotheo/mcp-devops/master/scripts/install.sh | bash
# 2. Configurar API key (interativo)
ipcom-chat --setup
# 3. Usar imediatamente
ipcom-chat "como ver portas abertas?"$ docker ps
Cannot connect to the Docker daemon. Is the docker daemon running?
$ ipcom-chat
🔍 Analisando erro do Docker...
✓ Detectado: Docker daemon não está rodando
📝 Executando diagnóstico:
1. Verificando status do serviço... [systemctl status docker]
2. Verificando permissões do usuário... [groups]
🛠️ Solução encontrada:
sudo systemctl start docker
sudo usermod -aG docker $USER
💡 Deseja executar os comandos? [Y/n]┌─────────────────────────────────────────────────────────┐
│ ipcom-chat v2.0.0 - Terminal Assistant │
├─────────────────────────────────────────────────────────┤
│ 👤 User: fabio | 📝 History: 42 messages | 🤖 Claude │
├─────────────────────────────────────────────────────────┤
│ │
│ You: como verificar quais portas estão abertas? │
│ │
│ Assistant: Vou mostrar várias formas de verificar │
│ portas abertas no seu sistema: │
│ │
│ 1. **Usando netstat** (tradicional): │
│ ```bash │
│ sudo netstat -tulpn │
│ ``` │
│ │
│ 2. **Usando ss** (moderno, mais rápido): │
│ ```bash │
│ sudo ss -tulpn │
│ ``` │
│ │
│ 3. **Usando lsof** (detalhado): │
│ ```bash │
│ sudo lsof -i -P -n | grep LISTEN │
│ ``` │
│ │
│ 💡 Executar comando 2 agora? [Y/n] │
└─────────────────────────────────────────────────────────┘
[Ctrl+C] Cancelar | [↑↓] Histórico | [Tab] Completar
Captura automática → Diagnóstico → Solução executável
# ERRO REAL
$ git push origin main
error: failed to push some refs to 'github.com:user/repo.git'
hint: Updates were rejected because the remote contains work...
# SOLUÇÃO COM ipcom-chat
$ ipcom-chat
📊 Analisando conflito no Git...
Executando diagnóstico:
git status → modified: README.md
git fetch origin → 2 commits ahead
git diff origin/main → conflicts detected
✅ Solução (3 opções):
1. git pull --rebase origin main [Recomendado]
2. git pull origin main [Merge commit]
3. git push --force [⚠️ Sobrescrever]
Escolha [1-3]: _Perguntas complexas → Múltiplos comandos → Resposta completa
$ ipcom-chat "quantos IPs estão bloqueados no fail2ban?"
🔄 Executando análise iterativa...
[1/4] fail2ban-client status
→ Jails ativos: sshd, apache, nginx
[2/4] fail2ban-client status sshd
→ 3 IPs bloqueados: 192.168.1.10, 10.0.0.5, 172.16.0.2
[3/4] fail2ban-client status apache
→ 2 IPs bloqueados: 203.0.113.0, 198.51.100.0
[4/4] fail2ban-client status nginx
→ 1 IP bloqueado: 192.0.2.0
📊 Resumo Final:
• Total: 6 IPs bloqueados
• sshd: 3 IPs (50%)
• apache: 2 IPs (33%)
• nginx: 1 IP (17%)UI rica no terminal com React + MCP Protocol
- ✅ Histórico Persistente: Conversas salvas por usuário em SQLite
- ✅ Syntax Highlighting: Colorização inteligente de código
- ✅ Markdown Rendering: Formatação rica com negrito, itálico, listas
- ✅ Execução Inline: Execute comandos direto da interface
- ✅ Multi-usuário: Cada usuário tem seu próprio contexto
- ✅ Atalhos:
Ctrl+Ccancelar,↑↓histórico,Tabautocompletar
# Modo interativo
$ ipcom-chat
# Abre interface Ink com histórico completo
# Pergunta direta
$ ipcom-chat "como criar backup incremental?"
# Resposta imediata com comandos prontos
# Pipeline com outros comandos
$ cat error.log | ipcom-chat analyze
# Analisa conteúdo e sugere soluçõesEscolha o melhor modelo para cada situação
| Provider | Modelo | Contexto | Velocidade | Custo | Melhor Para |
|---|---|---|---|---|---|
| Claude | Sonnet 3.5 | 200K tokens | ⚡⚡⚡ | $$ | Código complexo, análise profunda |
| GPT-4 | Turbo | 128K tokens | ⚡⚡ | $$$ | Conhecimento geral, criatividade |
| Gemini | Pro 1.5 | 2M tokens | ⚡⚡⚡⚡ | $ | Documentos grandes, análise rápida |
# Configurar provider padrão
ipcom-chat config set default_provider claude
# Usar provider específico
ipcom-chat --provider gemini "analyze this log file"
# Ver status dos providers
ipcom-chat --provider-statusBusca inteligente com cache e priorização
$ ipcom-chat "como configurar nginx com ssl lets encrypt ubuntu 24?"
🔍 Buscando informações atualizadas...
✓ Documentação oficial nginx
✓ Certbot para Ubuntu 24.04
✓ Stack Overflow (3 soluções recentes)
📚 Fontes consultadas:
• nginx.org/en/docs/http/configuring_https_servers.html
• certbot.eff.org/instructions?ws=nginx&os=ubuntu-24
• github.com/certbot/certbot/issues/recent
💾 Cache: Resultado salvo por 7 diasConfigurações de cache inteligente:
- Documentação: 7 dias
- Soluções de erro: 24 horas
- Info de pacotes: 1 hora
- Man pages: 30 dias
Respostas instantâneas sem usar API
# Base de padrões local para erros comuns
~/.mcp-terminal/patterns/
├── git_errors.json # 150+ padrões Git
├── npm_errors.json # 100+ erros NPM/Node
├── docker_errors.json # 80+ problemas Docker
├── linux_errors.json # 200+ erros sistema
└── custom_patterns.json # Seus padrões personalizadosExemplo de resposta instantânea:
$ npm install
ERROR: EACCES: permission denied
$ ipcom-chat
⚡ Solução local (sem API):
npm cache clean --force
sudo npm install -g --unsafe-perm
# Resposta em <100ms┌──────────────────────────────────────────────────────┐
│ MCP Terminal Assistant V2 │
├──────────────────────────────────────────────────────┤
│ │
│ User Input (ipcom-chat) │
│ ↓ │
│ ┌─────────────────────────────────┐ │
│ │ Interface Ink (React + MCP) │ │
│ │ • Rich UI Components │ │
│ │ • Markdown Rendering │ │
│ │ • Command Execution │ │
│ └─────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────┐ │
│ │ MCP Protocol Server │ │
│ │ • Message Handling │ │
│ │ • Tool Management │ │
│ │ • Session Control │ │
│ └─────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────┐ │
│ │ Pipeline de Processamento │ │
│ │ │ │
│ │ 1. Pattern Matcher │ │
│ │ ↓ │ │
│ │ 2. Command Executor │ │
│ │ ↓ │ │
│ │ 3. AI Orchestrator │ │
│ │ ↓ │ │
│ │ 4. Response Builder │ │
│ └─────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────┐ │
│ │ Camada de Persistência │ │
│ │ • SQLite (Histórico) │ │
│ │ • Cache (Responses) │ │
│ │ • Config (Settings) │ │
│ └─────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────┘
- Interface Ink baseada em React para terminal
- Suporte a Markdown e syntax highlighting
- Histórico persistente por usuário
- Execução de comandos inline
- Model Context Protocol para comunicação estruturada
- Gerenciamento de ferramentas e capacidades
- Streaming de respostas em tempo real
- Controle de sessão e contexto
- Sistema iterativo de refinamento (
ai_orchestrator.ts) - Executa múltiplos comandos até ter resposta completa
- Mantém contexto e objetivo da conversa
- Integração com múltiplos providers de AI
- Biblioteca local de padrões (
libs/pattern_matcher.ts) - Detecção de comandos comuns (fail2ban, docker, disk usage)
- Execução pré-definida de sequências
- Extração inteligente de dados
- SQLite: Histórico de conversas, contexto por usuário
- Cache: Respostas de AI, resultados de web search
- Config: API keys, preferências, personalizações
graph TD
A[User Query] --> B{Pattern Match?}
B -->|Yes| C[Local Pattern]
B -->|No| D[AI Analysis]
C --> E[Execute Commands]
D --> F[Generate Commands]
F --> E
E --> G{Complete?}
G -->|No| H[Next Command]
H --> E
G -->|Yes| I[Build Response]
I --> J[Display Result]
mcp-devops/
├── src/
│ ├── mcp-ink-cli.mjs # Interface Ink principal
│ ├── mcp-server.js # Servidor MCP
│ └── database.js # Gerenciamento SQLite
├── libs/
│ ├── pattern_matcher.ts # Sistema de padrões
│ └── command_executor.js # Executor de comandos
├── ai_models/
│ ├── base_model.ts # Interface base
│ ├── claude_model.ts # Provider Claude
│ ├── openai_model.js # Provider OpenAI
│ ├── gemini_model.ts # Provider Gemini
│ └── model_factory.ts # Factory pattern
├── patterns/
│ ├── git_errors.json # Padrões Git
│ ├── npm_errors.json # Padrões NPM
│ ├── docker_errors.json # Padrões Docker
│ └── linux_errors.json # Padrões Linux
├── web_search/
│ └── web_searcher.js # Busca web integrada
└── setup.js # Instalador principal
┌─────────────────────────────────────┐
│ Requisitos Mínimos │
├─────────────────────────────────────┤
│ • Sistema: Linux/Mac │
│ • Node.js: 18.0.0 ou superior │
│ • NPM/PNPM: Última versão │
│ • Shell: Bash ou Zsh │
│ • Espaço: ~100MB │
│ • RAM: 512MB livre │
└─────────────────────────────────────┘
# Uma linha - instala tudo automaticamente
curl -sSL https://raw.githubusercontent.com/fabiotheo/mcp-devops/master/scripts/install.sh | bash
# Ou com wget
wget -qO- https://raw.githubusercontent.com/fabiotheo/mcp-devops/master/scripts/install.sh | bash# 1. Clone o repositório
git clone https://github.com/fabiotheo/mcp-devops.git
cd mcp-devops
# 2. Instale dependências
pnpm install # ou npm install
# 3. Execute o setup interativo
node setup.js
# 4. Configure o PATH (escolha seu shell)
# Para Zsh:
echo 'export PATH="$HOME/.mcp-terminal/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# Para Bash:
echo 'export PATH="$HOME/.mcp-terminal/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc# Atualização automática preservando configurações
ipcom-chat --upgrade
# Ou manualmente
cd ~/mcp-devops
git pull origin master
pnpm install
node setup.js --upgrade --autoipcom-chat --setup
# O assistente irá perguntar:
# 1. Escolha do provider AI (Claude/GPT/Gemini)
# 2. API Key do provider escolhido
# 3. Configurações de cache
# 4. Integração com shell# Definir API Keys
ipcom-chat config set anthropic_api_key "sk-ant-..."
ipcom-chat config set openai_api_key "sk-..."
ipcom-chat config set gemini_api_key "..."
# Escolher provider padrão
ipcom-chat config set default_provider "claude"
# Configurar modelo
ipcom-chat config set claude_model "claude-3-sonnet-20240229"# Adicionar ao ~/.zshrc
source ~/.mcp-terminal/shell/zsh-integration.sh
# Ativa:
# - Captura automática de erros
# - Alias 'q' para perguntas rápidas
# - Histórico integrado# Adicionar ao ~/.bashrc
source ~/.mcp-terminal/shell/bash-integration.sh# Verificar versão
ipcom-chat --version
# Expected: ipcom-chat v2.0.0
# Testar funcionamento
ipcom-chat "hello world"
# Verificar configuração
ipcom-chat config list
# Testar providers
ipcom-chat --test-providers| Problema | Causa | Solução |
|---|---|---|
command not found: ipcom-chat |
PATH não configurado | export PATH="$HOME/.mcp-terminal/bin:$PATH" |
Permission denied |
Falta de permissão | chmod +x ~/.mcp-terminal/bin/ipcom-chat |
Node version too old |
Node < 18 | nvm install 18 && nvm use 18 |
Cannot find module |
Deps faltando | cd ~/.mcp-terminal && pnpm install |
API key not set |
Config incompleta | ipcom-chat --setup |
EACCES npm |
Permissões npm | npm config set prefix ~/.npm-global |
┌─────────────────────────────────────────────┐
│ ipcom-chat [query] [options] │
├─────────────────────────────────────────────┤
│ Opções Básicas: │
│ --help, -h Mostra ajuda completa │
│ --version, -v Exibe versão instalada │
│ --setup Configuração inicial │
│ --upgrade Atualiza para nova v. │
│ │
│ Histórico: │
│ --history Exibe conversações │
│ --clear-history Limpa histórico │
│ --export-history Exporta para JSON │
│ │
│ Providers AI: │
│ --provider NAME Escolhe provider │
│ --model NAME Escolhe modelo │
│ --test-providers Testa conexões │
│ │
│ Debug e Análise: │
│ --debug Modo verbose com log │
│ --dry-run Simula sem executar │
│ --explain Explica comando │
│ │
│ Formatação: │
│ --no-color Remove cores │
│ --json Output em JSON │
│ --quiet Mínimo output │
└─────────────────────────────────────────────┘
# Pergunta simples
ipcom-chat "como matar processo na porta 8080?"
# Com contexto de arquivo
ipcom-chat "analise este erro" < error.log
# Com provider específico
ipcom-chat --provider gemini "explique docker compose"# Abre interface Ink completa
ipcom-chat
# Features do modo interativo:
# - Histórico completo com setas ↑↓
# - Tab completion para comandos
# - Syntax highlighting automático
# - Execução inline de comandos
# - Markdown rendering# Pipe de saída de comando
docker logs container | ipcom-chat analyze
# Análise de arquivos
cat /var/log/nginx/error.log | ipcom-chat "find security issues"
# Combinação com grep
grep ERROR app.log | ipcom-chat summarize
# Geração de scripts
ipcom-chat "backup script for postgres" > backup.sh# Analisar últimos erros
ipcom-chat "analise os erros em /var/log/syslog"
# Encontrar padrões suspeitos
ipcom-chat "encontre tentativas de invasão no auth.log"
# Resumir logs do dia
ipcom-chat "resume os eventos importantes de hoje" < /var/log/messages
# Identificar gargalos
ipcom-chat "analyze performance issues" < app.log# Diagnosticar conectividade
ipcom-chat "por que não consigo acessar google.com?"
# Configurar firewall
ipcom-chat "como abrir porta 443 no ufw?"
# Análise de tráfego
ipcom-chat "explique este output do tcpdump" < capture.txt
# Debug de DNS
ipcom-chat "debug dns resolution problems"# Debug de containers
ipcom-chat "por que meu container está em restart loop?"
# Otimização de imagens
ipcom-chat "como reduzir tamanho da imagem node:18?"
# Docker Compose
ipcom-chat "crie um compose para wordpress com mysql"
# Kubernetes
ipcom-chat "debug este pod que não sobe" < pod-describe.yaml# Auditoria de segurança
ipcom-chat "verifique portas abertas e serviços expostos"
# SSH Hardening
ipcom-chat "melhore a segurança do meu sshd_config"
# Análise de permissões
ipcom-chat "find files with dangerous permissions"
# Firewall rules
ipcom-chat "configure iptables for web server"#!/bin/bash
# error-handler.sh
ERROR_MSG=$("$@" 2>&1)
if [ $? -ne 0 ]; then
SOLUTION=$(echo "$ERROR_MSG" | ipcom-chat --json)
echo "Erro detectado. Solução sugerida:"
echo "$SOLUTION" | jq -r '.solution'
fi# Configurar comportamento
ipcom-chat config set system_prompt "Be concise and technical"
ipcom-chat config set temperature 0.3 # Mais determinístico
# Criar aliases úteis (adicionar ao ~/.bashrc)
alias q='ipcom-chat' # Pergunta rápida
alias qerr='ipcom-chat analyze error'
alias qlog='ipcom-chat analyze log'Localização: ~/.mcp-terminal/config.json
{
"version": "2.0.0",
"user": {
"name": "fabio",
"shell": "zsh"
},
"ai": {
"default_provider": "claude",
"providers": {
"claude": {
"api_key": "sk-ant-...",
"model": "claude-3-sonnet-20240229",
"max_tokens": 4000,
"temperature": 0.7
}
}
},
"features": {
"web_search": {
"enabled": true,
"cache_duration_hours": 24
},
"pattern_matching": {
"enabled": true
},
"auto_execute": false,
"confirm_commands": true
}
}# Listar configurações
ipcom-chat config list
# Definir configuração
ipcom-chat config set features.auto_execute true
# Backup/Restore
ipcom-chat config backup > config.backup.json
ipcom-chat config restore < config.backup.jsonO modo debug fornece informações detalhadas para diagnóstico:
# Ativar modo debug
ipcom-chat --user fabio --debug
# Features do modo debug:
# - Mostra [DEBUG] no header do terminal
# - Grava log detalhado em /tmp/mcp-debug.log
# - Registra respostas brutas da IA
# - Rastreia processamento de formatação
# - Útil para diagnóstico de problemas
# Ver log em tempo real (em outro terminal)
tail -f /tmp/mcp-debug.log
# Estrutura do log:
# - Resposta bruta da IA (JSON completo)
# - Texto extraído
# - Processamento de formatação (entrada/saída)
# - Linhas modificadas (listas, bold, etc)Nota: O log só é criado quando --debug é usado. Em modo normal, nenhum log é gravado para máxima performance.
O sistema suporta múltiplos usuários, cada um com seu próprio histórico isolado no Turso DB.
# Criar usuário (campos obrigatórios: --username e --name)
# IMPORTANTE: Use aspas no nome se contiver espaços
ipcom-chat user create --username aristides --name "Aristides Silva"
# Criar usuário com informações completas (email é opcional)
ipcom-chat user create --username aristides --name "Aristides Silva" --email "aristides@example.com"# Iniciar chat como usuário específico
ipcom-chat --user aristides
# Combinar com modo debug
ipcom-chat --user aristides --debugipcom-chat user listPara deletar um usuário completamente:
# 1. Deletar do banco de dados
ipcom-chat user delete --username aristides
# 2. (Opcional) Se quiser deletar também o banco Turso
turso db destroy mcp-terminal-aristides --yes
# 3. (Opcional) Remover token de autenticação local
rm ~/.mcp-terminal/.turso-auth-aristidesNota: Todos os usuários compartilham o mesmo banco de dados Turso global, mas cada um tem histórico completamente isolado.
# Ask for command help in natural language
ask "how to find files modified in the last 24 hours"
# Short form for quick questions
q "how to find and kill a process by name"MCP Terminal Assistant automatically monitors commands in your terminal. When a command fails, it will analyze the error and suggest possible solutions.
# View system information detected by MCP
ask --system-info
# View command history
ask --history
# Enable or disable web search
ask --web-search on
ask --web-search off
# Check web search status and configuration
ask --web-status
# Configure Firecrawl API key
ask --firecrawl-key YOUR_API_KEY
# Scrape a website
ask --scrape https://example.com
# Crawl a website (with optional limit)
ask --crawl https://example.com --limit 20
# Clean the cache
mcp-clean
# See usage statistics
mcp-stats
# Manually monitor a specific command
mcp-run <command>MCP Terminal Assistant can be configured by editing ~/.mcp-terminal/config.json:
{
"anthropic_api_key": "YOUR_API_KEY",
"firecrawl_api_key": "YOUR_FIRECRAWL_API_KEY",
"model": "claude-3-5-sonnet-20240229",
"max_calls_per_hour": 100,
"enable_monitoring": true,
"enable_assistant": true,
"monitor_commands": ["npm", "yarn", "git", "docker", "make", "cargo", "go"],
"quick_fixes": true,
"auto_detect_fixes": false,
"log_level": "info",
"cache_duration_hours": 24,
"web_search": {
"enabled": true,
"cache_settings": {
"documentation": 7,
"error_solutions": 1,
"package_info": 0.04,
"man_pages": 30
},
"priority_sources": [
"man_pages",
"official_docs",
"github_issues",
"stackoverflow"
],
"rate_limit_per_hour": 50
}
}- Your commands are analyzed locally first using pattern matching
- Only failed commands are processed
- Personal information is not collected or stored
- API calls are made only when necessary to analyze complex errors
- All data is stored locally in
~/.mcp-terminal/
MCP Terminal Assistant é compatível com múltiplos provedores de IA:
- Modelos disponíveis: claude-3-7-sonnet, claude-3-5-sonnet, claude-3-haiku
- Requer uma chave de API Anthropic
- Precisa:
anthropic_api_key
- Modelos disponíveis: gpt-4o, gpt-4-turbo, gpt-3.5-turbo
- Requer uma chave de API OpenAI
- Precisa:
openai_api_key
- Modelos disponíveis: gemini-pro, gemini-pro-vision
- Requer uma chave de API Google AI
- Precisa:
gemini_api_key
Durante a instalação, você será solicitado a escolher o provedor de IA e fornecer a chave API correspondente.
MCP Terminal Assistant uses a combination of techniques:
- Command Capture: Zsh hooks capture commands and their exit status
- Local Pattern Analysis: Fast pattern matching identifies common errors
- System Detection: Identifies your specific Linux distribution for tailored solutions
- Web Search: When enabled, searches the internet for documentation, solutions, and other information
- Website Scraping: When configured with a Firecrawl API key, can extract content from websites in markdown format
- AI Analysis: For complex errors, Claude AI provides targeted solutions enhanced with web search results
- Hierarchical Caching: Common solutions, web search results, and scraped content are cached to reduce API usage and speed up responses
# Run the uninstaller (preserves configuration and data)
node setup.js --uninstall
# To completely remove all data and configuration
node setup.js --uninstall --remove-all-datamcp-terminal/
├── mcp-client.js # Command monitoring and analysis
├── mcp-assistant.js # Natural language command assistant
├── mcp-server.js # Optional API server for integration
├── system_detector.ts # System information detection
├── setup.js # Installation and configuration
├── patterns/ # Error patterns for different tools
│ ├── npm_errors.json
│ ├── git_errors.json
│ └── ...
├── web_search/ # Web search functionality
│ ├── index.js
│ └── web_searcher.js
├── web_scraper/ # Website scraping functionality
│ ├── index.js
│ └── firecrawl_wrapper.js
├── ai_models/ # AI model implementations
│ ├── base_model.ts
│ ├── claude_model.ts
│ ├── model_factory.ts
│ └── ...
├── zsh_integration.sh # Shell integration
└── config.json # Configuration file
You can add custom error patterns in the ~/.mcp-terminal/patterns/ directory. Each file should follow the format in the existing pattern files.
MIT License © 2023 Fabio Theodoro
- Powered by Anthropic's Claude
- Inspired by command-line tools like tldr, howdoi, and explainshell
If you found this tool helpful, please consider giving it a star! ⭐