MCP CLI

Uma interface de linha de comando para interagir com servidores do Model Context Protocol.

Documentação

MCP CLI - Interface de Linha de Comando do Model Context Protocol

Uma interface de linha de comando poderosa e rica em recursos para interagir com servidores Model Context Protocol. Este cliente permite comunicação perfeita com LLMs através da integração com o CHUK Tool Processor e CHUK-LLM, fornecendo uso de ferramentas, gerenciamento de conversas e múltiplos modos operacionais.

Configuração Padrão: O MCP CLI usa por padrão o Ollama com o modelo de raciocínio gpt-oss para operação local e focada em privacidade, sem exigir chaves de API.

🆕 Atualizações Recentes (v0.16)

Memória Virtual de IA (Experimental)

Flag --vm: Habilita memória virtual estilo SO para gerenciamento de contexto de conversas, alimentado por chuk-ai-session-manager
--vm-budget: Controla o orçamento de tokens para eventos de conversa (o prompt do sistema não tem limite máximo), forçando despejo antecipado e criação de páginas
--vm-mode: Escolha o modo de VM — passive (gerenciado em tempo de execução, padrão), relaxed (conversa ciente de VM) ou strict (paginação orientada por modelo com ferramentas)
Comando /memory: Visualize o estado da VM durante conversas — tabela de páginas, utilização do working set, métricas de despejo, estatísticas de TLB (aliases: /vm, /mem)
page_fault multimodal: Páginas de imagem retornam conteúdo de múltiplos blocos (texto + image_url) para que modelos multimodais possam reanalisar imagens recuperadas
/memory page <id> --download: Exporta o conteúdo das páginas para arquivos locais com extensões cientes de modalidade (.txt, .json, .png)

Planos de Execução (Nível 6)

Comando /plan: Crie, inspecione e execute grafos de chamadas de ferramentas reproduzíveis — create, list, show, run, delete, resume
Planejamento orientado por modelo (--plan-tools): O LLM cria e executa planos autonomamente durante a conversa — sem necessidade do comando /plan. Ele chama plan_create_and_execute quando uma orquestração de múltiplas etapas é necessária e usa ferramentas regulares para tarefas simples. Cada etapa é renderizada com progresso em tempo real no terminal
Execução paralela em lote: Etapas independentes do plano são executadas simultaneamente via agrupamento topológico (BFS de Kahn), com max_concurrency configurável
Resolução de variáveis: ${var}, acesso aninhado ${var.field} e strings de modelo como "https://${api.host}/users" — preservando tipos para referências únicas
Modo de simulação (dry-run): Trace chamadas de ferramentas planejadas sem executá-las — seguro para inspeção em produção
Checkpointing e retomada: O estado da execução é persistido após cada lote; retome planos interrompidos com /plan resume <id>
Integração de guardas: Os planos respeitam orçamentos existentes, limites por ferramenta e guardas de detecção de execução descontrolada
Visualização de DAG: Renderização ASCII com indicadores de status (○/◉/●/✗) e marcadores paralelos (∥)
Replanejamento: Replanejamento opcional baseado em LLM em caso de falha de etapa (enable_replan=True)
Alimentado por: chuk-ai-planner DSL de planos baseada em grafos

MCP Apps (SEP-1865)

UIs HTML interativas: Servidores MCP podem servir aplicações HTML interativas (gráficos, tabelas, mapas, visualizadores de markdown) que são renderizadas no seu navegador
Iframes em sandbox: Os aplicativos são executados em iframes seguros com proteção CSP
Ponte WebSocket: Comunicação bidirecional em tempo real entre aplicativos do navegador e servidores MCP
Lançamento automático: Ferramentas com anotações _meta.ui abrem automaticamente no navegador quando chamadas
Confiabilidade de sessão: Fila de mensagens, reconexão com backoff exponencial, entrega adiada de resultados de ferramentas

Endurecimento de Produção

Redação de segredos: Toda a saída de logs (console e arquivo) é automaticamente redigida para tokens Bearer, chaves de API, tokens OAuth e cabeçalhos Authorization
Logging estruturado em arquivo: A flag opcional --log-file habilita arquivos de log JSON rotativos (10MB, 3 backups) no nível DEBUG
Timeouts por servidor: As configurações de servidor suportam substituições de tool_timeout e init_timeout, resolvidas por servidor → global → padrão
OAuth seguro para threads: Fluxos OAuth concorrentes serializados com asyncio.Lock e mutação de cabeçalho copy-on-write
Monitoramento de saúde do servidor: Comando /health, diagnósticos de verificação de saúde em falhas, polling em segundo plano opcional --health-interval

Desempenho e Polimento

Consultas de ferramentas O(1): Consulta indexada de ferramentas substituindo varreduras lineares O(n)
Metadados de ferramentas LLM em cache: Cache por provedor com invalidação automática
Progresso de inicialização: Mensagens de progresso em tempo real durante a inicialização
Rastreamento de uso de tokens: Rastreamento por turno e cumulativo com o comando /usage (aliases: /tokens, /cost)
Persistência de sessão: Salvar/carregar/listar sessões de conversa com salvamento automático a cada 10 turnos (/sessions)
Exportação de conversas: Exporte conversas como Markdown ou JSON com metadados (/export)

Painel (UI de Navegador em Tempo Real)

Flag --dashboard: Inicie um painel de navegador em tempo real junto com o modo de chat
Terminal de agente: Visualização de conversa ao vivo com balões de mensagem, tokens em streaming e renderização de anexos
Fluxo de atividades: Pares de chamada/resultado de ferramentas, etapas de raciocínio e eventos de anexos do usuário
Visualizador de planos: Progresso visual do plano de execução com renderização de DAG
Registro de ferramentas: Navegue pelas ferramentas descobertas, acione a execução a partir do navegador
Painel de configuração: Visualize e alterne provedores, modelos e prompt do sistema
Anexos de arquivos: Botão "+" para upload de arquivos no navegador, arrastar e soltar e colar da área de transferência

Anexos Multimodais

Comando /attach: Prepare arquivos para a próxima mensagem — imagens, texto/código e áudio (aliases: /file, /image)
Flag CLI --attach: Anexe arquivos à primeira mensagem (repetível: --attach img.png --attach code.py)
Referências inline @file:: Mencione @file:path/to/file em qualquer lugar de uma mensagem para anexá-lo
Detecção de URL de imagem: URLs de imagem HTTP/HTTPS em mensagens são enviadas automaticamente como conteúdo de visão
Formatos suportados: PNG, JPEG, GIF, WebP, HEIC (imagens), MP3, WAV (áudio), além de mais de 25 extensões de texto/código
Renderização no painel: Miniaturas de imagens, pré-visualizações de texto expansíveis, players de áudio, selos de arquivos
Upload no navegador: Botão "+" na entrada de chat do painel com suporte a arrastar e soltar e colar da área de transferência

Qualidade de Código

Separação Core/UI: Módulos principais usam apenas logging — sem imports de UI
Mais de 4.300 testes: Suíte de testes abrangente com cobertura de ramos, testes de integração e limite mínimo de 60%
15 Princípios de Arquitetura: Documentados e aplicados (veja architecture.md)
Roadmap completo: Níveis 1-6 concluídos, Níveis 7-12 planejados (traces, escopos de memória, habilidades, agendamento, multi-agente)

🔄 Visão Geral da Arquitetura

O MCP CLI é construído sobre uma arquitetura modular com separação clara de responsabilidades:

CHUK Tool Processor: Execução de ferramentas assíncrona de nível de produção com middleware (retry, circuit breaker, limitação de taxa), múltiplas estratégias de execução e observabilidade
CHUK-LLM: Provedor LLM unificado com descoberta dinâmica de modelos, seleção baseada em capacidades e integração com llama.cpp (1,53x mais rápido que Ollama com reutilização automática de modelos)
CHUK-Term: UI de terminal aprimorada com temas, gerenciamento de terminal multiplataforma e formatação rica
MCP CLI: Camada de orquestração de comandos e integração (este projeto)

🌟 Recursos

Múltiplos Modos Operacionais

Modo Chat: Interface conversacional com respostas em streaming e uso automatizado de ferramentas (padrão: Ollama/gpt-oss)
Modo Interativo: Interface de shell orientada por comandos para operações diretas no servidor
Modo Comando: Modo amigável ao Unix para automação scriptável e pipelines
Comandos Diretos: Execute comandos individuais sem entrar no modo interativo

Interface de Chat Avançada

Respostas em Streaming: Geração de respostas em tempo real com atualizações de UI ao vivo
Visibilidade de Raciocínio: Veja o processo de pensamento da IA com modelos de raciocínio (gpt-oss, GPT-5, Claude 4.5)
Execução Concorrente de Ferramentas: Execute múltiplas ferramentas simultaneamente preservando a ordem da conversa
Interrupção Inteligente: Interrompa respostas em streaming ou execução de ferramentas com Ctrl+C
Métricas de Desempenho: Tempo de resposta, palavras/segundo e estatísticas de execução
Formatação Rica: Renderização de Markdown, realce de sintaxe e indicadores de progresso
Rastreamento de Uso de Tokens: Uso de tokens de API por turno e cumulativo com o comando /usage
Anexos Multimodais: Anexe imagens, arquivos de texto e áudio a mensagens via refs /attach, --attach, @file: ou upload no navegador
Persistência de Sessão: Salvamento automático e salvar/carregar manual de sessões de conversa
Exportação de Conversas: Exporte para Markdown ou JSON com metadados e uso de tokens

Suporte Abrangente a Provedores

O MCP CLI suporta todos os provedores e modelos do CHUK-LLM, incluindo modelos de raciocínio de ponta:

Provedor	Modelos Principais	Recursos Especiais
Ollama (Padrão)	🧠 gpt-oss, llama3.3, llama3.2, qwen3, qwen2.5-coder, deepseek-coder, granite3.3, mistral, gemma3, phi3, codellama	Modelos de raciocínio locais, foco em privacidade, sem necessidade de chave de API
OpenAI	🚀 Família GPT-5 (gpt-5, gpt-5-mini, gpt-5-nano), família GPT-4o, série O3 (o3, o3-mini)	Raciocínio avançado, chamada de funções, visão
Anthropic	🧠 Família Claude 4.5 (claude-4-5-opus, claude-4-5-sonnet), Claude 3.5 Sonnet	Raciocínio aprimorado, contexto longo
Azure OpenAI 🏢	Modelos empresariais GPT-5, GPT-4	Endpoints privados, conformidade, logs de auditoria
Google Gemini	Gemini 2.0 Flash, Gemini 1.5 Pro	Multimodal, inferência rápida
Groq ⚡	Modelos Llama 3.1, Mixtral	Inferência ultra-rápida (500+ tokens/seg)
Perplexity 🌐	Modelos Sonar	Busca web em tempo real com citações
IBM watsonx 🏢	Modelos Granite, Llama	Conformidade empresarial
Mistral AI 🇪🇺	Mistral Large, Medium	Modelos europeus, eficientes

Sistema Robusto de Ferramentas (Alimentado por CHUK Tool Processor v0.22+)

Descoberta Automática: Ferramentas fornecidas pelo servidor são detectadas e catalogadas automaticamente
Adaptação de Provedor: Nomes de ferramentas são sanitizados automaticamente para compatibilidade com provedores
Execução de Nível de Produção: Camadas de middleware com timeouts, retries, backoff exponencial, cache e circuit breakers
Múltiplas Estratégias de Execução: Em processo (rápido), subprocesso isolado (seguro) ou remoto via MCP
Execução Concorrente: Múltiplas ferramentas podem ser executadas simultaneamente com coordenação adequada
Exibição Rica de Progresso: Indicadores de progresso em tempo real e tempo de execução
Histórico de Ferramentas: Trilha de auditoria completa de todas as execuções de ferramentas
Middleware: Retry com backoff exponencial, circuit breakers e limitação de taxa via CTP
Chamadas de Ferramentas em Streaming: Suporte para ferramentas que retornam dados em streaming

MCP Apps (UIs Interativas)

UIs baseadas em navegador: Servidores MCP podem servir aplicações HTML interativas que são renderizadas no seu navegador
Detecção Automática: Ferramentas com anotações _meta.ui lançam automaticamente aplicativos de navegador na chamada da ferramenta
Execução em Sandbox: Os aplicativos são executados em iframes seguros com proteção de Política de Segurança de Conteúdo
Ponte WebSocket: Ponte JSON-RPC em tempo real entre aplicativos de navegador e servidores de ferramentas MCP
Persistência de Sessão: Fila de mensagens durante desconexões, reconexão automática, entrega adiada de resultados de ferramentas
Suporte a structuredContent: Conformidade total com a especificação MCP, incluindo extração e encaminhamento de conteúdo estruturado

Planos de Execução (Desenvolvidos com chuk-ai-planner)

Criação de Planos: Gere planos de execução a partir de descrições em linguagem natural usando agentes de planejamento baseados em LLM
Planejamento Orientado por Modelo: Com --plan-tools, o LLM decide autonomamente quando planejar — chama plan_create_and_execute para tarefas complexas de múltiplas etapas, usa ferramentas regulares para tarefas simples
Execução em DAG: Planos são grafos acíclicos direcionados — etapas independentes são executadas em lotes paralelos, etapas dependentes aguardam
Resolução de Variáveis: Saídas de etapas são vinculadas a variáveis (result_variable), referenciadas por etapas posteriores como ${var} ou ${var.field}
Modo de Simulação (Dry-Run): Trace o que um plano faria sem executar nenhuma ferramenta — seguro para produção
Checkpointing: O estado da execução é salvo após cada lote; retome planos interrompidos sem reexecutar etapas concluídas
Integração com Guards: Planos compartilham orçamento e limites por ferramenta com a conversa — sem bypass
Replanejamento: Em caso de falha em uma etapa, opcionalmente invoque o LLM para gerar um plano revisado para o trabalho restante
Visualização de DAG: Renderização ASCII mostra a estrutura de dependências, agrupamento em lotes e marcadores paralelos
Persistência: Planos armazenados como JSON em ~/.mcp-cli/plans/

Gerenciamento Avançado de Configuração

Integração com Ambiente: Chaves de API e configurações via variáveis de ambiente
Configuração Baseada em Arquivos: Arquivos de configuração YAML e JSON
Preferências do Usuário: Configurações persistentes para provedores e modelos ativos
Validação e Diagnóstico: Verificações de saúde do provedor e validação de configuração integradas

Experiência do Usuário Aprimorada

Suporte Multiplataforma: Windows, macOS e Linux com otimizações específicas por plataforma via chuk-term
Saída de Console Rica: Desenvolvida com chuk-term e 8 temas integrados (default, dark, light, minimal, terminal, monokai, dracula, solarized)
Gerenciamento Avançado de Terminal: Operações de terminal multiplataforma, incluindo limpeza, redimensionamento, detecção de cores e controle de cursor
Componentes de UI Interativos: Manipulação de entrada do usuário através do sistema de prompt do chuk-term (ask, confirm, select_from_list, select_multiple)
Conclusão de Comandos: Conclusão por tabulação sensível ao contexto para todas as interfaces
Ajuda Abrangente: Sistema de ajuda detalhado com exemplos e padrões de uso
Tratamento de Erros Elegante: Mensagens de erro amigáveis com dicas de solução de problemas

📚 Documentação

Documentação abrangente está disponível no diretório docs/:

Projeto

Arquitetura - 15 princípios de design, layout de módulos e convenções de codificação
Roadmap - Visão, níveis concluídos (1-5) e níveis planejados (6-12: planos, rastreamentos, habilidades, agendamento, multiagente, sessões remotas)

Documentação Principal

Sistema de Comandos - Guia completo do sistema de comandos unificado, padrões e uso em todos os modos
Gerenciamento de Tokens - Gerenciamento abrangente de tokens para provedores e servidores, incluindo OAuth, bearer tokens e chaves de API

Documentação Especializada

Planos de Execução - Criação de planos, execução paralela, resolução de variáveis, checkpointing, guards e replanejamento
Dashboard - UI de navegador em tempo real com terminal de agente, fluxo de atividades e uploads de arquivos
Anexos - Anexos de arquivos multimodais: imagens, texto, áudio e upload pelo navegador
Aplicativos MCP - UIs de navegador interativas servidas por servidores MCP (SEP-1865)
Autenticação OAuth - Fluxos OAuth, backends de armazenamento e integração com servidores MCP
Integração de Streaming - Arquitetura de streaming de respostas em tempo real
Gerenciamento de Pacotes - Organização de dependências e grupos de recursos

Documentação de UI

Temas - Sistema de temas e personalização
Sistema de Saída - Saída de console rica e formatação
Gerenciamento de Terminal - Operações de terminal multiplataforma

Documentação de Testes

Testes Unitários - Estrutura e padrões de teste
Cobertura de Testes - Requisitos de cobertura e relatórios

📋 Pré-requisitos

Python 3.11 ou superior
Para Operação Local (Padrão):
- Ollama: Instale a partir de ollama.ai
- Baixe o modelo de raciocínio padrão: ollama pull gpt-oss
Para Provedores em Nuvem (Opcional):
- OpenAI: variável de ambiente OPENAI_API_KEY (para modelos GPT-5, GPT-4, O3)
- Anthropic: variável de ambiente ANTHROPIC_API_KEY (para Claude 4.5, Claude 3.5)
- Azure: AZURE_OPENAI_API_KEY e AZURE_OPENAI_ENDPOINT (para GPT-5 empresarial)
- Google: GEMINI_API_KEY (para modelos Gemini)
- Groq: GROQ_API_KEY (para modelos Llama rápidos)
- Provedores personalizados: Configuração específica do provedor
Servidores MCP: Arquivo de configuração do servidor (padrão: server_config.json)

🚀 Instalação

Início Rápido com Ollama (Padrão)

Instale o Ollama (se ainda não estiver instalado):

# macOS/Linux
curl -fsSL https://ollama.ai/install.sh | sh

# Or visit https://ollama.ai for other installation methods

Baixe o modelo de raciocínio padrão:

ollama pull gpt-oss  # Open-source reasoning model with thinking visibility

Instale e execute o MCP CLI:

# Using uvx (recommended)
uvx mcp-cli --help

# Or install from source
git clone https://github.com/chrishayuk/mcp-cli
cd mcp-cli
pip install -e "."
mcp-cli --help

# Optional: Enable MCP Apps (interactive browser UIs)
pip install -e ".[apps]"

Usando Modelos Diferentes

# === LOCAL MODELS (No API Key Required) ===

# Use default reasoning model (gpt-oss)
mcp-cli --server sqlite

# Use other Ollama models
mcp-cli --model llama3.3              # Latest Llama
mcp-cli --model qwen2.5-coder         # Coding-focused
mcp-cli --model deepseek-coder        # Another coding model
mcp-cli --model granite3.3            # IBM Granite

# === CLOUD PROVIDERS (API Keys Required) ===

# GPT-5 Family (requires OpenAI API key)
mcp-cli --provider openai --model gpt-5          # Full GPT-5 with reasoning
mcp-cli --provider openai --model gpt-5-mini     # Efficient GPT-5 variant
mcp-cli --provider openai --model gpt-5-nano     # Ultra-lightweight GPT-5

# GPT-4 Family
mcp-cli --provider openai --model gpt-4o         # GPT-4 Optimized
mcp-cli --provider openai --model gpt-4o-mini    # Smaller GPT-4

# O3 Reasoning Models
mcp-cli --provider openai --model o3             # O3 reasoning
mcp-cli --provider openai --model o3-mini        # Efficient O3

# Claude 4.5 Family (requires Anthropic API key)
mcp-cli --provider anthropic --model claude-4-5-opus    # Most advanced Claude
mcp-cli --provider anthropic --model claude-4-5-sonnet  # Balanced Claude 4.5
mcp-cli --provider anthropic --model claude-3-5-sonnet  # Claude 3.5

# Enterprise Azure (requires Azure configuration)
mcp-cli --provider azure_openai --model gpt-5    # Enterprise GPT-5

# Other Providers
mcp-cli --provider gemini --model gemini-2.0-flash      # Google Gemini
mcp-cli --provider groq --model llama-3.1-70b          # Fast Llama via Groq

🧰 Configuração Global

Configuração Padrão

O MCP CLI usa por padrão:

Provedor: ollama (local, sem necessidade de chave de API)
Modelo: gpt-oss (modelo de raciocínio de código aberto com visibilidade de pensamento)

Argumentos de Linha de Comando

Opções globais disponíveis para todos os modos e comandos:

--server: Especifique o(s) servidor(es) para conectar (separados por vírgula)
--config-file: Caminho para o arquivo de configuração do servidor (padrão: server_config.json)
--provider: Provedor de LLM (padrão: ollama)
--model: Modelo específico a usar (padrão: gpt-oss para Ollama)
--disable-filesystem: Desativar acesso ao sistema de arquivos (padrão: ativado)
--api-base: Substituir URL do endpoint da API
--api-key: Substituir chave de API (não necessário para Ollama)
--token-backend: Substituir backend de armazenamento de tokens (auto, keychain, windows, secretservice, encrypted, vault)
--verbose: Ativar registro detalhado
--quiet: Suprimir saída não essencial
--log-file: Gravar logs de depuração em um arquivo rotativo (segredos com redação automática)
--vm: [Experimental] Ativar memória virtual de IA para gerenciamento de contexto
--vm-budget: Orçamento de tokens para eventos de conversa no modo VM (padrão: 128000, além do prompt do sistema)
--vm-mode: Modo VM — passive (padrão), relaxed ou strict
--dashboard: Iniciar uma UI de dashboard de navegador em tempo real junto com o modo de chat
--attach: Anexar arquivos à primeira mensagem (repetível: --attach img.png --attach code.py)
--plan-tools: Ativar planejamento orientado por modelo — o LLM cria e executa autonomamente planos de múltiplas etapas
--no-tools: Desativar completamente a chamada de ferramentas MCP — converse diretamente com o LLM sem conectar a nenhum servidor MCP

Variáveis de Ambiente

# Override defaults
export LLM_PROVIDER=ollama              # Default provider (already the default)
export LLM_MODEL=gpt-oss                # Default model (already the default)

# For cloud providers (optional)
export OPENAI_API_KEY=sk-...           # For GPT-5, GPT-4, O3 models
export ANTHROPIC_API_KEY=sk-ant-...    # For Claude 4.5, Claude 3.5
export AZURE_OPENAI_API_KEY=sk-...     # For enterprise GPT-5
export AZURE_OPENAI_ENDPOINT=https://...
export GEMINI_API_KEY=...              # For Gemini models
export GROQ_API_KEY=...                # For Groq fast inference

# Tool configuration
export MCP_TOOL_TIMEOUT=120            # Tool execution timeout (seconds)

🌐 Modos Disponíveis

1. Modo de Chat (Padrão)

Fornece uma interface de linguagem natural com respostas em streaming e uso automático de ferramentas:

# Default mode with Ollama/gpt-oss reasoning model (no API key needed)
mcp-cli --server sqlite

# See the AI's thinking process with reasoning models
mcp-cli --server sqlite --model gpt-oss     # Open-source reasoning
mcp-cli --server sqlite --provider openai --model gpt-5  # GPT-5 reasoning
mcp-cli --server sqlite --provider anthropic --model claude-4-5-opus  # Claude 4.5 reasoning

# Use different local models
mcp-cli --server sqlite --model llama3.3
mcp-cli --server sqlite --model qwen2.5-coder

# Switch to cloud providers (requires API keys)
mcp-cli chat --server sqlite --provider openai --model gpt-5
mcp-cli chat --server sqlite --provider anthropic --model claude-4-5-sonnet

# Launch with real-time browser dashboard
mcp-cli --server sqlite --dashboard

# Attach files to the first message
mcp-cli --server sqlite --attach image.png --attach data.csv

2. Modo Interativo

Interface de shell orientada por comandos para operações diretas no servidor:

mcp-cli interactive --server sqlite

# With specific models
mcp-cli interactive --server sqlite --model gpt-oss       # Local reasoning
mcp-cli interactive --server sqlite --provider openai --model gpt-5  # Cloud GPT-5

3. Modo de Comando

Interface amigável ao Unix para automação e scripts:

# Process text with reasoning models
mcp-cli cmd --server sqlite --model gpt-oss --prompt "Think through this step by step" --input data.txt

# Use GPT-5 for complex reasoning
mcp-cli cmd --server sqlite --provider openai --model gpt-5 --prompt "Analyze this data" --input data.txt

# Execute tools directly
mcp-cli cmd --server sqlite --tool list_tables --output tables.json

# Pipeline-friendly processing
echo "SELECT * FROM users LIMIT 5" | mcp-cli cmd --server sqlite --tool read_query --input -

4. Comandos Diretos

Execute comandos individuais sem entrar no modo interativo:

# List available tools
mcp-cli tools --server sqlite

# Show provider configuration
mcp-cli provider list

# Show available models for current provider
mcp-cli models

# Show models for specific provider
mcp-cli models openai    # Shows GPT-5, GPT-4, O3 models
mcp-cli models anthropic # Shows Claude 4.5, Claude 3.5 models
mcp-cli models ollama    # Shows gpt-oss, llama3.3, etc.

# Ping servers
mcp-cli ping --server sqlite

# List resources
mcp-cli resources --server sqlite

# UI Theme Management
mcp-cli theme                     # Show current theme and list available
mcp-cli theme dark                # Switch to dark theme
mcp-cli theme --select            # Interactive theme selector
mcp-cli theme --list              # List all available themes

# Token Storage Management
mcp-cli token backends            # Show available storage backends
mcp-cli --token-backend encrypted token list  # Use specific backend

🌐 Aplicativos MCP (UIs de Navegador Interativas)

Os Aplicativos MCP permitem que servidores de ferramentas forneçam UIs HTML interativas que são renderizadas no seu navegador. Quando uma ferramenta tem uma anotação _meta.ui apontando para um recurso de UI, o mcp-cli inicia automaticamente um servidor web local e abre o aplicativo no seu navegador.

Pré-requisitos

# Install the apps extra (adds websockets dependency)
pip install "mcp-cli[apps]"

Como Funciona

Conecte-se a um servidor MCP que forneça ferramentas habilitadas para aplicativos
Chame uma ferramenta que tenha metadados _meta.ui (por exemplo, show_chart, show_table)
O mcp-cli busca automaticamente o recurso de UI, inicia um servidor local e abre seu navegador
O aplicativo recebe resultados de ferramentas em tempo real via WebSocket

Exemplo

# Connect to a server with app-enabled tools
mcp-cli --server view_demo

# In chat, ask for something visual:
> Show me the sales data as a chart
# Browser opens automatically with an interactive chart

# The /tools command shows which tools have app UIs (APP column)
> /tools

Arquitetura

Página host serve um iframe com sandbox contendo o HTML do aplicativo
Ponte WebSocket faz proxy de JSON-RPC entre o navegador e os servidores MCP
Segurança: Sandbox de iframe, proteção CSP, prevenção de XSS, validação de esquema de URL
Confiabilidade: Fila de mensagens durante desconexões, reconexão com backoff exponencial, entrega adiada de resultados de ferramentas

Consulte Documentação de Aplicativos MCP para o guia completo.

🤖 Usando o Modo de Chat

O modo de chat fornece a interface mais avançada com respostas em streaming e uso inteligente de ferramentas.

Iniciando o Modo de Chat

# Simple startup with default reasoning model (gpt-oss)
mcp-cli --server sqlite

# Multiple servers
mcp-cli --server sqlite,filesystem

# With advanced reasoning models
mcp-cli --server sqlite --provider openai --model gpt-5
mcp-cli --server sqlite --provider anthropic --model claude-4-5-opus

Comandos de Chat (Comandos de Barra)

Gerenciamento de Provedores e Modelos

/provider                           # Show current configuration (default: ollama)
/provider list                      # List all providers
/provider config                    # Show detailed configuration
/provider diagnostic               # Test provider connectivity
/provider set ollama api_base http://localhost:11434  # Configure Ollama endpoint
/provider openai                   # Switch to OpenAI (requires API key)
/provider anthropic                # Switch to Anthropic (requires API key)
/provider openai gpt-5             # Switch to OpenAI GPT-5

# Custom Provider Management
/provider custom                   # List custom providers
/provider add localai http://localhost:8080/v1 gpt-4  # Add custom provider
/provider remove localai           # Remove custom provider

/model                             # Show current model (default: gpt-oss)
/model llama3.3                    # Switch to different Ollama model
/model gpt-5                       # Switch to GPT-5 (if using OpenAI)
/model claude-4-5-opus             # Switch to Claude 4.5 (if using Anthropic)
/models                            # List available models for current provider

Gerenciamento de Ferramentas

/tools                             # List available tools
/tools --all                       # Show detailed tool information
/tools --raw                       # Show raw JSON definitions
/tools call                        # Interactive tool execution

/toolhistory                       # Show tool execution history
/th -n 5                          # Last 5 tool calls
/th 3                             # Details for call #3
/th --json                        # Full history as JSON

Gerenciamento de Servidores (Configuração em Tempo de Execução)

/server                            # List all configured servers
/server list                       # List servers (alias)
/server list all                   # Include disabled servers

# Add servers at runtime (persists in ~/.mcp-cli/preferences.json)
/server add <name> stdio <command> [args...]
/server add sqlite stdio uvx mcp-server-sqlite --db-path test.db
/server add playwright stdio npx @playwright/mcp@latest
/server add time stdio uvx mcp-server-time
/server add fs stdio npx @modelcontextprotocol/server-filesystem /path/to/dir

# HTTP/SSE server examples with authentication
/server add github --transport http --header "Authorization: Bearer ghp_token" -- https://api.github.com/mcp
/server add myapi --transport http --env API_KEY=secret -- https://api.example.com/mcp
/server add events --transport sse -- https://events.example.com/sse

# Manage server state
/server enable <name>              # Enable a disabled server
/server disable <name>             # Disable without removing
/server remove <name>              # Remove user-added server
/server ping <name>                # Test server connectivity

# Server details
/server <name>                     # Show server configuration details

Nota: Servidores adicionados via /server add são armazenados em ~/.mcp-cli/preferences.json e persistem entre sessões. Os servidores do projeto permanecem em server_config.json.

Anexos Multimodais

/attach image.png                  # Stage an image for the next message
/attach code.py                    # Stage a text file
/attach list                       # Show currently staged files
/attach clear                      # Clear staged files
/file data.csv                     # Alias for /attach
/image screenshot.heic             # Alias for /attach

# Inline file references (in any message)
@file:screenshot.png describe what you see
@file:data.csv summarize this data

# Image URLs are auto-detected
https://example.com/photo.jpg what is in this image?

Gerenciamento de Conversas

/conversation                      # Show conversation history
/ch -n 10                         # Last 10 messages
/ch 5                             # Details for message #5
/ch --json                        # Full history as JSON

/save conversation.json            # Save conversation to file
/compact                          # Summarize conversation
/clear                            # Clear conversation history
/cls                              # Clear screen only

Personalização de UI

/theme                            # Interactive theme selector with preview
/theme dark                       # Switch to dark theme
/theme monokai                    # Switch to monokai theme

# Available themes: default, dark, light, minimal, terminal, monokai, dracula, solarized
# Themes are persisted across sessions

Gerenciamento de Tokens

/token                            # List all stored tokens
/token list                       # List all tokens explicitly
/token set <name>                 # Store a bearer token
/token get <name>                 # Get token details
/token delete <name>              # Delete a token
/token clear                      # Clear all tokens (with confirmation)
/token backends                   # Show available storage backends

# Examples
/token set my-api                 # Prompts for token value (secure)
/token get notion --oauth         # Get OAuth token for Notion server
/token list --api-keys            # List only provider API keys

Backends de Armazenamento de Tokens: O MCP CLI suporta múltiplos backends seguros de armazenamento de tokens:

Keychain (macOS) - Usa o Keychain do macOS (padrão no macOS)
Windows Credential Manager - Armazenamento nativo do Windows (padrão no Windows)
Secret Service - Keyring de desktop Linux (GNOME/KDE)
Arquivo Criptografado - Arquivos locais criptografados com AES-256 (fallback multiplataforma)
HashiCorp Vault - Gerenciamento de segredos empresarial

Substitua o backend padrão com --token-backend:

# Use encrypted file storage instead of keychain
mcp-cli --token-backend encrypted token list

# Use vault for enterprise environments
mcp-cli --token-backend vault token list

Consulte o Guia de Gerenciamento de Tokens para documentação abrangente.

Controle de Sessão

/verbose                          # Toggle verbose/compact display (Default: Enabled)
/confirm                          # Toggle tool call confirmation (Default: Enabled)
/interrupt                        # Stop running operations
/server                           # Manage MCP servers (see Server Management above)
/help                            # Show all commands
/help tools                       # Help for specific command
/exit                            # Exit chat mode

Para documentação completa de comandos, consulte o Guia do Sistema de Comandos.

Recursos do Chat

Respostas em Streaming com Visibilidade de Raciocínio

🧠 Modelos de Raciocínio: Veja o processo de pensamento da IA com gpt-oss, GPT-5, Claude 4
Geração em Tempo Real: Veja o texto aparecer token por token
Métricas de Desempenho: Palavras/segundo, tempo de resposta
Interrupção Elegante: Ctrl+C para parar o streaming
Renderização Progressiva: Markdown formatado durante o streaming

Execução de Ferramentas

Descoberta e uso automático de ferramentas
Execução concorrente com indicadores de progresso
Modos de exibição detalhado e compacto
Histórico completo de execução e tempo

Anexos Multimodais

Anexe imagens, arquivos de texto e áudio a qualquer mensagem
Comando /attach com staging, listagem e limpeza (aliases: /file, /image)
Referências inline @file:path em qualquer mensagem
Sinalizador CLI --attach para anexos na primeira mensagem
Botão "+" no navegador com arrastar e soltar e colar da área de transferência (com --dashboard)
O dashboard renderiza miniaturas, pré-visualizações de texto e players de áudio

Integração com Provedores

Alternância perfeita entre provedores
Otimizações específicas de modelo
Gerenciamento de chaves de API e endpoints
Monitoramento de saúde e diagnóstico

🖥️ Usando o Modo Interativo

O modo interativo fornece um shell de comandos para interação direta com o servidor.

Iniciando o Modo Interativo

mcp-cli interactive --server sqlite

Comandos Interativos

help                              # Show available commands
exit                              # Exit interactive mode
clear                             # Clear terminal

# Provider management
provider                          # Show current provider
provider list                     # List providers
provider anthropic                # Switch provider
provider openai gpt-5             # Switch to GPT-5

# Model management
model                             # Show current model
model gpt-oss                     # Switch to reasoning model
model claude-4-5-opus             # Switch to Claude 4.5
models                            # List available models

# Tool operations
tools                             # List tools
tools --all                       # Detailed tool info
tools call                        # Interactive tool execution

# Server operations
servers                           # List servers
ping                              # Ping all servers
resources                         # List resources
prompts                           # List prompts

📄 Usando o Modo de Comando

O modo de comando fornece capacidades de automação amigáveis ao Unix.

Opções do Modo de Comando

--input FILE                      # Input file (- for stdin)
--output FILE                     # Output file (- for stdout)
--prompt TEXT                     # Prompt template
--tool TOOL                       # Execute specific tool
--tool-args JSON                  # Tool arguments as JSON
--system-prompt TEXT              # Custom system prompt
--raw                             # Raw output without formatting
--single-turn                     # Disable multi-turn conversation
--max-turns N                     # Maximum conversation turns

Exemplos

# Text processing with reasoning models
echo "Analyze this data" | mcp-cli cmd --server sqlite --model gpt-oss --input - --output analysis.txt

# Use GPT-5 for complex analysis
mcp-cli cmd --server sqlite --provider openai --model gpt-5 --prompt "Provide strategic analysis" --input report.txt

# Tool execution
mcp-cli cmd --server sqlite --tool list_tables --raw

# Complex queries
mcp-cli cmd --server sqlite --tool read_query --tool-args '{"query": "SELECT COUNT(*) FROM users"}'

# Batch processing with GNU Parallel
ls *.txt | parallel mcp-cli cmd --server sqlite --input {} --output {}.summary --prompt "Summarize: {{input}}"

🔧 Configuração de Provedores

Configuração do Ollama (Padrão)

O Ollama é executado localmente por padrão em http://localhost:11434. O MCP CLI v0.11.1+ com CHUK-LLM v0.16+ inclui integração com llama.cpp que descobre e reutiliza automaticamente os modelos baixados do Ollama para inferência 1,53x mais rápida (311 vs 204 tokens/seg) sem baixar novamente.

Para usar modelos de raciocínio e outros:

# Pull reasoning and other models for Ollama
ollama pull gpt-oss          # Default reasoning model
ollama pull llama3.3         # Latest Llama
ollama pull llama3.2         # Llama 3.2
ollama pull qwen3            # Qwen 3
ollama pull qwen2.5-coder    # Coding-focused
ollama pull deepseek-coder   # DeepSeek coder
ollama pull granite3.3       # IBM Granite
ollama pull mistral          # Mistral
ollama pull gemma3           # Google Gemma
ollama pull phi3             # Microsoft Phi
ollama pull codellama        # Code Llama

# List available Ollama models
ollama list

# Configure remote Ollama server
mcp-cli provider set ollama api_base http://remote-server:11434

Configuração de Provedores em Nuvem

Para usar provedores de nuvem com modelos avançados, configure chaves de API:

# Configure OpenAI (for GPT-5, GPT-4, O3 models)
mcp-cli provider set openai api_key sk-your-key-here

# Configure Anthropic (for Claude 4.5, Claude 3.5)
mcp-cli provider set anthropic api_key sk-ant-your-key-here

# Configure Azure OpenAI (for enterprise GPT-5)
mcp-cli provider set azure_openai api_key sk-your-key-here
mcp-cli provider set azure_openai api_base https://your-resource.openai.azure.com

# Configure other providers
mcp-cli provider set gemini api_key your-gemini-key
mcp-cli provider set groq api_key your-groq-key

# Test configuration
mcp-cli provider diagnostic openai
mcp-cli provider diagnostic anthropic

Provedores Personalizados Compatíveis com OpenAI

O MCP CLI suporta adicionar provedores personalizados compatíveis com OpenAI (LocalAI, proxies personalizados, etc.):

# Add a custom provider (persisted across sessions)
mcp-cli provider add localai http://localhost:8080/v1 gpt-4 gpt-3.5-turbo
mcp-cli provider add myproxy https://proxy.example.com/v1 custom-model-1 custom-model-2

# Set API key via environment variable (never stored in config)
export LOCALAI_API_KEY=your-api-key
export MYPROXY_API_KEY=your-api-key

# List custom providers
mcp-cli provider custom

# Use custom provider
mcp-cli --provider localai --server sqlite
mcp-cli --provider myproxy --model custom-model-1 --server sqlite

# Remove custom provider
mcp-cli provider remove localai

# Runtime provider (session-only, not persisted)
mcp-cli --provider temp-ai --api-base https://api.temp.com/v1 --api-key test-key --server sqlite

Nota de Segurança: As chaves de API podem ser armazenadas com segurança em chaveiros nativos do sistema operacional (Keychain do macOS, Gerenciador de Credenciais do Windows, Secret Service do Linux) ou no HashiCorp Vault usando o sistema de gerenciamento de tokens. Alternativamente, use variáveis de ambiente seguindo o padrão {PROVIDER_NAME}_API_KEY ou passe via --api-key para uso apenas na sessão. Consulte Gerenciamento de Tokens para detalhes.

Configuração Manual

A configuração da biblioteca chuk_llm em ~/.chuk_llm/config.yaml:

ollama:
  api_base: http://localhost:11434
  default_model: gpt-oss

openai:
  api_base: https://api.openai.com/v1
  default_model: gpt-5

anthropic:
  api_base: https://api.anthropic.com
  default_model: claude-4-5-opus

azure_openai:
  api_base: https://your-resource.openai.azure.com
  default_model: gpt-5

gemini:
  api_base: https://generativelanguage.googleapis.com
  default_model: gemini-2.0-flash

groq:
  api_base: https://api.groq.com
  default_model: llama-3.1-70b

As chaves de API podem ser fornecidas via:

Armazenamento seguro de tokens (recomendado) - Armazenado no chaveiro do SO/Vault, consulte Gerenciamento de Tokens
Variáveis de ambiente - Exporte no seu shell ou adicione ao ~/.chuk_llm/.env:

OPENAI_API_KEY=sk-your-key-here
ANTHROPIC_API_KEY=sk-ant-your-key-here
AZURE_OPENAI_API_KEY=sk-your-azure-key-here
GEMINI_API_KEY=your-gemini-key
GROQ_API_KEY=your-groq-key

Linha de comando - Passe --api-key para uso apenas na sessão (não persistido)

📂 Configuração do Servidor

O MCP CLI suporta dois tipos de configurações de servidor:

Servidores do Projeto (server_config.json): Configurações compartilhadas no nível do projeto
Servidores do Usuário (~/.mcp-cli/preferences.json): Servidores adicionados em tempo de execução que persistem entre sessões

Descoberta de Arquivos de Configuração

O MCP CLI procura por server_config.json na seguinte ordem de prioridade:

Caminho explícito via opção --config-file:

mcp-cli --config-file /path/to/custom-config.json

Diretório atual - Detectado automaticamente ao executar a partir de um diretório de projeto:
```
cd /path/to/my-project
mcp-cli --server sqlite    # Uses ./server_config.json if it exists
```
Padrão integrado - Ao executar via uvx ou de qualquer diretório sem uma configuração local:
```
uvx mcp-cli --server cloudflare_workers    # Uses packaged server_config.json
```

Isso significa que você pode:

Substituir por projeto: Coloque um server_config.json no diretório do seu projeto com configurações de servidor específicas do projeto
Usar padrões globalmente: Execute uvx mcp-cli de qualquer lugar e obtenha os servidores padrão integrados
Personalizar explicitamente: Use --config-file para especificar qualquer local de arquivo de configuração

Servidores Padrão Integrados

O MCP CLI v0.11.1+ vem com um conjunto expandido de servidores pré-configurados no server_config.json integrado:

Servidor	Tipo	Descrição	Configuração
sqlite	STDIO	Operações de banco de dados SQLite	`uvx mcp-server-sqlite --db-path test.db`
echo	STDIO	Servidor de eco para testes	`uvx chuk-mcp-echo stdio`
math	STDIO	Computações matemáticas	`uvx chuk-mcp-math-server`
playwright	STDIO	Automação de navegador	`npx @playwright/mcp@latest`
brave_search	STDIO	Busca na web via API Brave	Requer token `BRAVE_API_KEY`
notion	HTTP	Integração com o espaço de trabalho Notion	`https://mcp.notion.com/mcp` (OAuth)
cloudflare_workers	HTTP	Bindings do Cloudflare Workers	`https://bindings.mcp.cloudflare.com/mcp` (OAuth)
monday	HTTP	Integração com Monday.com	`https://mcp.monday.com/mcp` (OAuth)
linkedin	HTTP	Integração com LinkedIn	`https://linkedin.chukai.io/mcp`
weather	HTTP	Serviço de dados meteorológicos	`https://weather.chukai.io/mcp`

Nota: Servidores HTTP e servidores baseados em API exigem autenticação. Use o sistema de Gerenciamento de Tokens para configurar tokens de acesso.

Para usar esses servidores:

# Use bundled servers from anywhere
uvx mcp-cli --server sqlite
uvx mcp-cli --server echo
uvx mcp-cli --server math
uvx mcp-cli --server playwright

# API-based servers require tokens
mcp-cli token set brave_search --type bearer
uvx mcp-cli --server brave_search

# HTTP/OAuth servers require OAuth authentication
uvx mcp-cli token set notion --oauth
uvx mcp-cli --server notion

# Use multiple servers simultaneously
uvx mcp-cli --server sqlite,math,playwright

Configuração do Projeto

Crie um arquivo server_config.json com suas configurações de servidor MCP:

{
  "mcpServers": {
    "sqlite": {
      "command": "python",
      "args": ["-m", "mcp_server.sqlite_server"],
      "env": {
        "DATABASE_PATH": "database.db"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"],
      "env": {}
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server"],
      "env": {
        "BRAVE_API_KEY": "${TOKEN:bearer:brave_search}"
      }
    },
    "notion": {
      "url": "https://mcp.notion.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TOKEN:bearer:notion}"
      }
    }
  }
}

Substituição Segura de Tokens

O MCP CLI suporta substituição automática de tokens a partir do armazenamento seguro usando a sintaxe ${TOKEN:namespace:name}:

Sintaxe: ${TOKEN:<namespace>:<token-name>}

Exemplos:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server"],
      "env": {
        "BRAVE_API_KEY": "${TOKEN:bearer:brave_search}"
      }
    },
    "api-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TOKEN:bearer:my_api}",
        "X-API-Key": "${TOKEN:api-key:my_service}"
      }
    }
  }
}

Armazenamento de Tokens:

# Store tokens securely (never in config files!)
mcp-cli token set brave_search --type bearer
# Enter token value when prompted (hidden input)

mcp-cli token set my_api --type bearer --value "your-token-here"

# Tokens are stored in OS-native secure storage:
# - macOS: Keychain
# - Windows: Credential Manager
# - Linux: Secret Service (GNOME Keyring/KWallet)

Locais Suportados:

env: Variáveis de ambiente para servidores STDIO
headers: Cabeçalhos HTTP para servidores HTTP/SSE

Namespaces:

bearer: Tokens Bearer (padrão para --type bearer)
api-key: Chaves de API (padrão para --type api-key)
oauth: Tokens OAuth (automático)
generic: Tokens personalizados

Benefícios:

✅ Nunca armazene chaves de API em arquivos de configuração
✅ Compartilhe server_config.json com segurança (sem segredos)
✅ Tokens criptografados no armazenamento seguro nativo do SO
✅ Funciona em todos os tipos de transporte (STDIO, HTTP, SSE)

Consulte o Guia de Gerenciamento de Tokens para documentação completa.

Gerenciamento de Servidores em Tempo de Execução

Adicione servidores dinamicamente durante a execução sem editar arquivos de configuração:

# Add STDIO servers (most common)
mcp-cli
> /server add sqlite stdio uvx mcp-server-sqlite --db-path mydata.db
> /server add playwright stdio npx @playwright/mcp@latest
> /server add time stdio uvx mcp-server-time

# Add HTTP servers with authentication
> /server add github --transport http --header "Authorization: Bearer ghp_token" -- https://api.github.com/mcp
> /server add myapi --transport http --env API_KEY=secret -- https://api.example.com/mcp

# Add SSE (Server-Sent Events) servers
> /server add events --transport sse -- https://events.example.com/sse

# Manage servers
> /server list                     # Show all servers
> /server disable sqlite           # Temporarily disable
> /server enable sqlite            # Re-enable
> /server remove myapi             # Remove user-added server

Pontos-chave:

Servidores adicionados pelo usuário persistem em ~/.mcp-cli/preferences.json
Sobrevivem a reinicializações do aplicativo
Podem ser habilitados/desabilitados sem remoção
Suportam transportes STDIO, HTTP e SSE
Variáveis de ambiente e cabeçalhos para autenticação

📈 Exemplos de Uso Avançado

Comparação de Modelos de Raciocínio

# Compare reasoning across different models
> /provider ollama
> /model gpt-oss
> Think through this problem step by step: If a train leaves New York at 3 PM...
[See the complete thinking process with gpt-oss]

> /provider openai
> /model gpt-5
> Think through this problem step by step: If a train leaves New York at 3 PM...
[See GPT-5's reasoning approach]

> /provider anthropic
> /model claude-4-5-opus
> Think through this problem step by step: If a train leaves New York at 3 PM...
[See Claude 4.5's analytical process]

Fluxo de Trabalho Local-Primeiro com Raciocínio

# Start with default Ollama/gpt-oss (no API key needed)
mcp-cli chat --server sqlite

# Use reasoning model for complex problems
> Think through this database optimization problem step by step
[gpt-oss shows its complete thinking process before answering]

# Try different local models for different tasks
> /model llama3.3              # General purpose
> /model qwen2.5-coder         # For coding tasks
> /model deepseek-coder        # Alternative coding model
> /model granite3.3            # IBM's model
> /model gpt-oss               # Back to reasoning model

# Switch to cloud when needed (requires API keys)
> /provider openai
> /model gpt-5
> Complex enterprise architecture design...

> /provider anthropic
> /model claude-4-5-opus
> Detailed strategic analysis...

> /provider ollama
> /model gpt-oss
> Continue with local processing...

Fluxo de Trabalho Multi-Provedor

# Start with local reasoning (default, no API key)
mcp-cli chat --server sqlite

# Compare responses across providers
> /provider ollama
> What's the best way to optimize this SQL query?

> /provider openai gpt-5        # Requires API key
> What's the best way to optimize this SQL query?

> /provider anthropic claude-4-5-sonnet  # Requires API key
> What's the best way to optimize this SQL query?

# Use each provider's strengths
> /provider ollama gpt-oss      # Local reasoning, privacy
> /provider openai gpt-5        # Advanced reasoning
> /provider anthropic claude-4-5-opus  # Deep analysis
> /provider groq llama-3.1-70b  # Ultra-fast responses

Fluxos de Trabalho Complexos com Ferramentas e Raciocínio

# Use reasoning model for complex database tasks
> /model gpt-oss
> I need to analyze our database performance. Think through what we should check first.
[gpt-oss shows thinking: "First, I should check the table structure, then indexes, then query patterns..."]
[Tool: list_tables] → products, customers, orders

> Now analyze the indexes and suggest optimizations
[gpt-oss thinks through index analysis]
[Tool: describe_table] → Shows current indexes
[Tool: read_query] → Analyzes query patterns

> Create an optimization plan based on your analysis
[Complete reasoning process followed by specific recommendations]

Automação e Scripts

# Batch processing with different models
for file in data/*.csv; do
  # Use reasoning model for analysis
  mcp-cli cmd --server sqlite \
    --model gpt-oss \
    --prompt "Analyze this data and think through patterns" \
    --input "$file" \
    --output "analysis/$(basename "$file" .csv)_reasoning.txt"
  
  # Use coding model for generating scripts
  mcp-cli cmd --server sqlite \
    --model qwen2.5-coder \
    --prompt "Generate Python code to process this data" \
    --input "$file" \
    --output "scripts/$(basename "$file" .csv)_script.py"
done

# Pipeline with reasoning
cat complex_problem.txt | \
  mcp-cli cmd --model gpt-oss --prompt "Think through this step by step" --input - | \
  mcp-cli cmd --model llama3.3 --prompt "Summarize the key points" --input - > solution.txt

Monitoramento de Desempenho

# Check provider and model performance
> /provider diagnostic
Provider Diagnostics
Provider      | Status      | Response Time | Features      | Models
ollama        | ✅ Ready    | 56ms         | 📡🔧         | gpt-oss, llama3.3, qwen3, ...
openai        | ✅ Ready    | 234ms        | 📡🔧👁️      | gpt-5, gpt-4o, o3, ...
anthropic     | ✅ Ready    | 187ms        | 📡🔧         | claude-4-5-opus, claude-4-5-sonnet, ...
azure_openai  | ✅ Ready    | 198ms        | 📡🔧👁️      | gpt-5, gpt-4o, ...
gemini        | ✅ Ready    | 156ms        | 📡🔧👁️      | gemini-2.0-flash, ...
groq          | ✅ Ready    | 45ms         | 📡🔧         | llama-3.1-70b, ...

# Check available models
> /models
Models for ollama (Current Provider)
Model                | Status
gpt-oss             | Current & Default (Reasoning)
llama3.3            | Available
llama3.2            | Available
qwen2.5-coder       | Available
deepseek-coder      | Available
granite3.3          | Available
... and 6 more

# Monitor tool execution with reasoning
> /verbose
> /model gpt-oss
> Analyze the database and optimize the slowest queries
[Shows complete thinking process]
[Tool execution with timing]

🔍 Solução de Problemas

Problemas Comuns

Ollama não está em execução (provedor padrão):

# Start Ollama service
ollama serve

# Or check if it's running
curl http://localhost:11434/api/tags

Modelo não encontrado:

# For Ollama (default), pull the model first
ollama pull gpt-oss      # Reasoning model
ollama pull llama3.3     # Latest Llama
ollama pull qwen2.5-coder # Coding model

# List available models
ollama list

# For cloud providers, check supported models
mcp-cli models openai     # Shows GPT-5, GPT-4, O3 models
mcp-cli models anthropic  # Shows Claude 4.5, Claude 3.5 models

Provedor não encontrado ou chave de API ausente:

# Check available providers
mcp-cli provider list

# For cloud providers, set API keys
mcp-cli provider set openai api_key sk-your-key
mcp-cli provider set anthropic api_key sk-ant-your-key

# Test connection
mcp-cli provider diagnostic openai

Problemas de conexão com o Ollama:

# Check Ollama is running
ollama list

# Test connection
mcp-cli provider diagnostic ollama

# Configure custom endpoint if needed
mcp-cli provider set ollama api_base http://localhost:11434

Modo de Depuração

Ative o registro detalhado para solução de problemas:

mcp-cli --verbose chat --server sqlite
mcp-cli --log-level DEBUG interactive --server sqlite

# Write debug logs to a rotating file (secrets are automatically redacted)
mcp-cli --log-file ~/.mcp-cli/logs/debug.log --server sqlite

🔒 Considerações de Segurança

Privacidade e Local-Primeiro

Local por Padrão: Ollama com gpt-oss executa localmente, mantendo seus dados privados
Sem Nuvem Necessária: Funcionalidade completa sem dependências externas de API

Segurança de Tokens e Autenticação

Armazenamento Seguro de Tokens: Tokens armazenados em armazenamentos de credenciais nativos do SO (Keychain do macOS, Gerenciador de Credenciais do Windows, Secret Service do Linux) sob o identificador de serviço "mcp-cli"
Múltiplos Backends de Armazenamento: Escolha entre chaveiro, arquivos criptografados ou HashiCorp Vault com base nos requisitos de segurança
Chaves de API: Necessárias apenas para provedores de nuvem (OpenAI, Anthropic, etc.), armazenadas com segurança usando o sistema de gerenciamento de tokens
Suporte OAuth 2.0: Autenticação segura para servidores MCP usando PKCE e indicadores de recurso (RFC 7636, RFC 8707)

Segurança de Logs

Redação de Segredos: Toda a saída de log (console e arquivo) é automaticamente redigida para tokens Bearer, chaves de API (sk-*), tokens de acesso OAuth e cabeçalhos Authorization
Logs Rotativos em Arquivo: --log-file opcional com formato JSON, rotação de 10MB e 3 arquivos de backup

Segurança de Execução

Validação de Ferramentas: Todas as chamadas de ferramentas são validadas antes da execução
Proteção de Timeout: Timeouts configuráveis evitam operações penduradas (v0.13+)
Disjuntores: Detecção automática de falhas e recuperação para evitar falhas em cascata (v0.13+)
Isolamento de Servidores: Cada servidor executa em seu próprio processo
Acesso a Arquivos: O acesso ao sistema de arquivos pode ser desabilitado com --disable-filesystem
Monitoramento de Transporte: Detecção automática de falhas de conexão com avisos (v0.11+)

Segurança de Apps MCP

Sandbox de Iframe: Apps executam em iframes com sandbox e permissões restritas
Política de Segurança de Conteúdo: Domínios CSP fornecidos pelo servidor são validados e sanitizados
Prevenção de XSS: Nomes de ferramentas e conteúdo fornecido pelo usuário são escapados em HTML antes da injeção em templates
Validação de Esquema de URL: ui/open-link permite apenas esquemas http:// e https://
Validação de Nomes de Ferramentas: A ponte rejeita nomes de ferramentas que não correspondem ao conjunto de caracteres da especificação MCP
Validação de Origem WebSocket (v0.20.1+): O servidor host local do app rejeita qualquer handshake WebSocket cujo cabeçalho Origin não corresponda à sua própria página host http://localhost:<port>, para que uma página da web não relacionada não possa se conectar à ponte de um app em execução
Aplicação de Permissões de Ferramentas (v0.20.1+): Quando um recurso declara uma lista de permissões de ferramentas que pode chamar, a ponte a aplica em cada tools/call — não apenas uma verificação de sintaxe de nome de ferramenta
Busca de Recursos Segura contra SSRF (v0.20.1+): Buscas diretas de recursos HTTP(S) são validadas contra faixas de endereços privados/loopback/link-local antes de conectar, e revalidadas em cada salto de redirecionamento

Segurança do Painel (v0.20.1+)

Validação de Origem WebSocket: O servidor WebSocket do painel aplica a mesma verificação de Origem que os Apps MCP
Renderização de Markdown Sanitizada: Mensagens de chat do assistente são renderizadas via DOMPurify em vez de um sanitizador feito à mão
Metadados de Visualização Escapados: Nomes de visualizações e ícones declarados pelo servidor são escapados em HTML antes de serem inseridos nos cabeçalhos dos painéis
Caminhos de Agente/Sessão Sanitizados: Identificadores de agente e sessão são sanitizados antes do uso como componentes de caminho do sistema de arquivos

Segurança de Execução de Planos (v0.20.1+)

Confirmação de Ferramentas Aplicada: A execução de planos (/plan, plan_create_and_execute) honra a mesma preferência de ferramentas de confirmação e política de domínio confiável que o caminho de chat interativo; se a confirmação for necessária e nenhum prompt estiver disponível, a chamada é recusada em vez de executada sem confirmação

🚀 Recursos de Desempenho

Desempenho do Provedor LLM (v0.16+)

Imports 52x Mais Rápidos: Reduzido de 735ms para 14ms através de carregamento preguiçoso
Criação de Cliente 112x Mais Rápida: Cache automático seguro para threads
Integração llama.cpp: Inferência 1.53x mais rápida (311 vs 204 tokens/seg) com reutilização automática de modelos Ollama
Descoberta Dinâmica de Modelos: Seleção de modelos baseada em capacidades com zero sobrecarga

Desempenho de Execução de Ferramentas (v0.13+)

Middleware de Produção: Timeouts, tentativas com backoff exponencial, disjuntores e cache de resultados
Execução Concorrente de Ferramentas: Múltiplas ferramentas podem executar simultaneamente com coordenação adequada
Monitoramento de Saúde da Conexão: Detecção automática e recuperação de falhas de transporte
Gerenciador de Ferramentas Otimizado: Reduzido de 2000+ para ~800 linhas mantendo toda a funcionalidade

Desempenho em Tempo de Execução

Processamento Local: O provedor Ollama padrão minimiza a latência
Visibilidade do Raciocínio: Veja o processo de pensamento da IA com gpt-oss, GPT-5, Claude 4
Respostas em Streaming: Geração de respostas em tempo real
Pooling de Conexões: Reutilização eficiente de conexões de clientes
Cache: Metadados de ferramentas e configurações de provedores são armazenados em cache
Arquitetura Assíncrona: Operações não bloqueantes em todo o sistema

📦 Dependências

As dependências principais são organizadas em grupos de recursos:

cli: Interface de terminal e framework de comandos (Rich, Typer, chuk-term)
dev: Ferramentas de desenvolvimento, utilitários de teste, linting
chuk-tool-processor v0.22+: Execução de ferramentas de nível de produção com middleware, múltiplas estratégias de execução e observabilidade
chuk-llm v0.17+: Provedor LLM unificado com descoberta dinâmica de modelos, seleção baseada em capacidades e integração llama.cpp
chuk-term: Interface de terminal aprimorada com temas, prompts e suporte multiplataforma

Instale com recursos específicos:

pip install "mcp-cli[cli]"        # Basic CLI features
pip install "mcp-cli[cli,dev]"    # CLI with development tools
pip install "mcp-cli[apps]"       # MCP Apps (interactive browser UIs)

🤝 Contribuindo

Aceitamos contribuições! Consulte nosso Guia de Contribuição para detalhes.

Configuração de Desenvolvimento

git clone https://github.com/chrishayuk/mcp-cli
cd mcp-cli
pip install -e ".[cli,dev]"
pre-commit install

Scripts de Demonstração

Explore as capacidades do MCP CLI:

# Command Mode Demos

# General cmd mode features (bash)
bash examples/cmd_mode_demo.sh

# LLM integration with cmd mode (bash)
bash examples/cmd_mode_llm_demo.sh

# Python integration example
uv run examples/cmd_mode_python_demo.py

# Custom Provider Management Demos

# Interactive walkthrough demo (educational)
uv run examples/custom_provider_demo.py

# Working demo with actual inference (requires OPENAI_API_KEY)
uv run examples/custom_provider_working_demo.py

# Simple shell script demo (requires OPENAI_API_KEY)
bash examples/custom_provider_simple_demo.sh

# Terminal management features (chuk-term)
uv run examples/ui_terminal_demo.py

# Output system with themes (chuk-term)
uv run examples/ui_output_demo.py

# Streaming UI capabilities (chuk-term)
uv run examples/ui_streaming_demo.py

Executando Testes

pytest
pytest --cov=mcp_cli --cov-report=html

📜 Licença

Este projeto é licenciado sob a Apache License 2.0 - consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

CHUK Tool Processor - Execução assíncrona de ferramentas de nível de produção com middleware e observabilidade
CHUK-LLM - Provedor LLM unificado com descoberta dinâmica de modelos, integração llama.cpp e suporte a GPT-5/Claude 4.5 (v0.17+)
CHUK-Term - Interface de terminal aprimorada com temas e suporte multiplataforma
Rich - Formatação de terminal bonita
Typer - Framework CLI
Prompt Toolkit - Entrada interativa

🔗 Projetos Relacionados

Model Context Protocol - Especificação central do protocolo
MCP Servers - Implementações oficiais de servidores MCP
CHUK Tool Processor - Execução de ferramentas em nível de produção com middleware e observabilidade
CHUK-LLM - Abstração de provedores de LLM com descoberta dinâmica de modelos, suporte a GPT-5, Claude 4.5, série O3 e integração com llama.cpp
CHUK-Term - Biblioteca de interface de terminal com temas e suporte multiplataforma