MCP CLI

Una interfaz de línea de comandos para interactuar con servidores del Protocolo de Contexto de Modelo.

Documentación

MCP CLI - Interfaz de Línea de Comandos del Protocolo de Contexto de Modelo

Una interfaz de línea de comandos potente y rica en funciones para interactuar con servidores del Protocolo de Contexto de Modelo. Este cliente permite una comunicación fluida con LLMs mediante la integración con el CHUK Tool Processor y CHUK-LLM, proporcionando uso de herramientas, gestión de conversaciones y múltiples modos operativos.

Configuración predeterminada: MCP CLI usa Ollama por defecto con el modelo de razonamiento gpt-oss para una operación local centrada en la privacidad, sin necesidad de claves API.

🆕 Actualizaciones recientes (v0.16)

Memoria Virtual de IA (Experimental)

Indicador --vm: Habilita memoria virtual estilo SO para la gestión del contexto de conversación, impulsada por chuk-ai-session-manager
--vm-budget: Controla el presupuesto de tokens para los eventos de conversación (el prompt del sistema no tiene límite superior), forzando una expulsión más temprana y la creación de páginas
--vm-mode: Elige el modo de VM — passive (gestionado en tiempo de ejecución, predeterminado), relaxed (conversación consciente de VM) o strict (paginación dirigida por modelo con herramientas)
Comando /memory: Visualiza el estado de la VM durante las conversaciones — tabla de páginas, utilización del conjunto de trabajo, métricas de expulsión, estadísticas de TLB (alias: /vm, /mem)
page_fault multimodal: Las páginas de imagen devuelven contenido de múltiples bloques (texto + image_url) para que los modelos multimodales puedan reanalizar imágenes recuperadas
/memory page <id> --download: Exporta el contenido de las páginas a archivos locales con extensiones según la modalidad (.txt, .json, .png)

Planes de Ejecución (Nivel 6)

Comando /plan: Crea, inspecciona y ejecuta grafos de llamadas a herramientas reproducibles — create, list, show, run, delete, resume
Planificación dirigida por modelo (--plan-tools): El LLM crea y ejecuta planes de forma autónoma durante la conversación — no se necesita el comando /plan. Llama a plan_create_and_execute cuando se requiere orquestación de múltiples pasos, y usa herramientas regulares para tareas simples. Cada paso se muestra con progreso en tiempo real en la terminal
Ejecución por lotes en paralelo: Los pasos independientes del plan se ejecutan concurrentemente mediante agrupación topológica (BFS de Kahn), con max_concurrency configurable
Resolución de variables: ${var}, acceso anidado ${var.field} y cadenas de plantilla como "https://${api.host}/users" — con preservación de tipos para referencias simples
Modo de ejecución simulada: Traza las llamadas a herramientas planificadas sin ejecutarlas — seguro para inspección en producción
Puntos de control y reanudación: El estado de ejecución se persiste después de cada lote; reanuda planes interrumpidos con /plan resume <id>
Integración de guardas: Los planes respetan el presupuesto existente, los límites por herramienta y las guardas de detección de ejecución descontrolada
Visualización de DAG: Renderizado ASCII con indicadores de estado (○/◉/●/✗) y marcadores de paralelismo (∥)
Replanificación: Replanificación opcional basada en LLM ante fallos de pasos (enable_replan=True)
Impulsado por: chuk-ai-planner DSL de planes basado en grafos

Aplicaciones MCP (SEP-1865)

UIs HTML interactivas: Los servidores MCP pueden servir aplicaciones HTML interactivas (gráficos, tablas, mapas, visores de Markdown) que se renderizan en tu navegador
iframes en sandbox: Las aplicaciones se ejecutan en iframes seguros con protección CSP
Puente WebSocket: Comunicación bidireccional en tiempo real entre aplicaciones del navegador y servidores MCP
Lanzamiento automático: Las herramientas con anotaciones _meta.ui se abren automáticamente en el navegador al ser llamadas
Fiabilidad de sesión: Cola de mensajes, reconexión con retroceso exponencial, entrega diferida de resultados de herramientas

Endurecimiento de Producción

Redacción de secretos: Toda la salida de registros (consola y archivo) se redacta automáticamente para tokens Bearer, claves API, tokens OAuth y cabeceras de Autorización
Registro estructurado en archivos: El indicador opcional --log-file habilita archivos JSON rotativos (10MB, 3 copias de seguridad) a nivel DEBUG
Tiempos de espera por servidor: Las configuraciones de servidor admiten anulaciones de tool_timeout y init_timeout, resueltas por servidor → global → predeterminado
OAuth seguro para subprocesos: Los flujos OAuth concurrentes se serializan con asyncio.Lock y mutación de cabeceras con copia en escritura
Monitoreo de salud del servidor: Comando /health, diagnósticos de verificación de salud ante fallos, sondeo en segundo plano opcional --health-interval

Rendimiento y Pulido

Búsquedas de herramientas O(1): Búsqueda de herramientas indexada que reemplaza los escaneos lineales O(n)
Metadatos de herramientas LLM en caché: Caché por proveedor con invalidación automática
Progreso de inicio: Mensajes de progreso en tiempo real durante la inicialización
Seguimiento de uso de tokens: Seguimiento por turno y acumulativo con el comando /usage (alias: /tokens, /cost)
Persistencia de sesiones: Guardar/cargar/listar sesiones de conversación con guardado automático cada 10 turnos (/sessions)
Exportación de conversaciones: Exporta conversaciones como Markdown o JSON con metadatos (/export)

Panel de Control (UI de Navegador en Tiempo Real)

Indicador --dashboard: Lanza un panel de control en el navegador en tiempo real junto al modo de chat
Terminal de agente: Vista de conversación en vivo con burbujas de mensajes, tokens en streaming y renderizado de adjuntos
Flujo de actividad: Pares de llamada/resultado de herramientas, pasos de razonamiento y eventos de adjuntos del usuario
Visor de planes: Progreso visual de planes de ejecución con renderizado de DAG
Registro de herramientas: Explora las herramientas descubiertas, dispara ejecuciones desde el navegador
Panel de configuración: Ve y cambia proveedores, modelos y prompt del sistema
Adjuntos de archivos: Botón "+" para subir archivos desde el navegador, arrastrar y soltar, y pegar desde el portapapeles

Adjuntos Multimodales

Comando /attach: Prepara archivos para el siguiente mensaje — imágenes, texto/código y audio (alias: /file, /image)
Indicador CLI --attach: Adjunta archivos al primer mensaje (repetible: --attach img.png --attach code.py)
Referencias @file: en línea: Menciona @file:path/to/file en cualquier parte de un mensaje para adjuntarlo
Detección de URLs de imágenes: Las URLs de imágenes HTTP/HTTPS en los mensajes se envían automáticamente como contenido de visión
Formatos admitidos: PNG, JPEG, GIF, WebP, HEIC (imágenes), MP3, WAV (audio), más de 25 extensiones de texto/código
Renderizado en el panel: Miniaturas de imágenes, vistas previas de texto expandibles, reproductores de audio, insignias de archivos
Subida desde el navegador: Botón "+" en la entrada de chat del panel con soporte de arrastrar y soltar y pegado desde el portapapeles

Calidad de Código

Separación núcleo/UI: Los módulos del núcleo usan solo logging — sin importaciones de UI
Más de 4.300 pruebas: Suite de pruebas integral con cobertura de ramas, pruebas de integración y umbral mínimo del 60%
15 Principios de Arquitectura: Documentados y aplicados (ver architecture.md)
Hoja de ruta completa: Niveles 1-6 completados, niveles 7-12 planificados (trazas, ámbitos de memoria, habilidades, programación, multiagente)

🔄 Descripción General de la Arquitectura

MCP CLI está construido sobre una arquitectura modular con una separación clara de responsabilidades:

CHUK Tool Processor: Ejecución de herramientas asíncrona de grado de producción con middleware (reintentos, interruptor de circuito, limitación de velocidad), múltiples estrategias de ejecución y observabilidad
CHUK-LLM: Proveedor LLM unificado con descubrimiento dinámico de modelos, selección basada en capacidades e integración con llama.cpp (1,53 veces más rápido que Ollama con reutilización automática de modelos)
CHUK-Term: UI de terminal mejorada con temas, gestión de terminal multiplataforma y formato enriquecido
MCP CLI: Capa de orquestación de comandos e integración (este proyecto)

🌟 Características

Múltiples Modos Operativos

Modo Chat: Interfaz conversacional con respuestas en streaming y uso automatizado de herramientas (predeterminado: Ollama/gpt-oss)
Modo Interactivo: Interfaz de shell basada en comandos para operaciones directas con el servidor
Modo Comando: Modo amigable con Unix para automatización mediante scripts y pipelines
Comandos Directos: Ejecuta comandos individuales sin entrar en modo interactivo

Interfaz de Chat Avanzada

Respuestas en Streaming: Generación de respuestas en tiempo real con actualizaciones de UI en vivo
Visibilidad del Razonamiento: Ve el proceso de pensamiento de la IA con modelos de razonamiento (gpt-oss, GPT-5, Claude 4.5)
Ejecución Concurrente de Herramientas: Ejecuta múltiples herramientas simultáneamente preservando el orden de la conversación
Interrupción Inteligente: Interrumpe respuestas en streaming o ejecución de herramientas con Ctrl+C
Métricas de Rendimiento: Tiempo de respuesta, palabras por segundo y estadísticas de ejecución
Formato Enriquecido: Renderizado de Markdown, resaltado de sintaxis e indicadores de progreso
Seguimiento de Uso de Tokens: Uso de tokens de API por turno y acumulativo con el comando /usage
Adjuntos Multimodales: Adjunta imágenes, archivos de texto y audio a los mensajes mediante referencias /attach, --attach, @file: o subida desde el navegador
Persistencia de Sesiones: Guardado automático y guardado/carga manual de sesiones de conversación
Exportación de Conversaciones: Exporta a Markdown o JSON con metadatos y uso de tokens

Soporte Integral de Proveedores

MCP CLI admite todos los proveedores y modelos de CHUK-LLM, incluidos modelos de razonamiento de vanguardia:

Proveedor	Modelos Clave	Características Especiales
Ollama (Predeterminado)	🧠 gpt-oss, llama3.3, llama3.2, qwen3, qwen2.5-coder, deepseek-coder, granite3.3, mistral, gemma3, phi3, codellama	Modelos de razonamiento locales, centrados en la privacidad, sin necesidad de clave API
OpenAI	🚀 Familia GPT-5 (gpt-5, gpt-5-mini, gpt-5-nano), familia GPT-4o, serie O3 (o3, o3-mini)	Razonamiento avanzado, llamada de funciones, visión
Anthropic	🧠 Familia Claude 4.5 (claude-4-5-opus, claude-4-5-sonnet), Claude 3.5 Sonnet	Razonamiento mejorado, contexto largo
Azure OpenAI 🏢	Modelos empresariales GPT-5, GPT-4	Endpoints privados, cumplimiento, registros de auditoría
Google Gemini	Gemini 2.0 Flash, Gemini 1.5 Pro	Multimodal, inferencia rápida
Groq ⚡	Modelos Llama 3.1, Mixtral	Inferencia ultrarrápida (más de 500 tokens/seg)
Perplexity 🌐	Modelos Sonar	Búsqueda web en tiempo real con citas
IBM watsonx 🏢	Modelos Granite, Llama	Cumplimiento empresarial
Mistral AI 🇪🇺	Mistral Large, Medium	Modelos europeos, eficientes

Sistema Robusto de Herramientas (Impulsado por CHUK Tool Processor v0.22+)

Descubrimiento Automático: Las herramientas proporcionadas por el servidor se detectan y catalogan automáticamente
Adaptación de Proveedores: Los nombres de las herramientas se sanean automáticamente para la compatibilidad con el proveedor
Ejecución de Grado de Producción: Capas de middleware con tiempos de espera, reintentos, retroceso exponencial, caché e interruptores de circuito
Múltiples Estrategias de Ejecución: En proceso (rápida), subproceso aislado (segura) o remota mediante MCP
Ejecución Concurrente: Múltiples herramientas pueden ejecutarse simultáneamente con la coordinación adecuada
Visualización de Progreso Enriquecida: Indicadores de progreso en tiempo real y tiempos de ejecución
Historial de Herramientas: Registro de auditoría completo de todas las ejecuciones de herramientas
Middleware: Reintentos con retroceso exponencial, interruptores de circuito y limitación de velocidad mediante CTP
Llamadas a Herramientas en Streaming: Soporte para herramientas que devuelven datos en streaming

Aplicaciones MCP (UIs Interactivas)

UIs basadas en navegador: Los servidores MCP pueden servir aplicaciones HTML interactivas que se renderizan en tu navegador
Detección Automática: Las herramientas con anotaciones _meta.ui lanzan automáticamente aplicaciones de navegador al llamar a la herramienta
Ejecución en Sandbox: Las aplicaciones se ejecutan en iframes seguros con protección de Política de Seguridad de Contenido
Puente WebSocket: Puente JSON-RPC en tiempo real entre aplicaciones de navegador y servidores de herramientas MCP
Persistencia de Sesión: Cola de mensajes durante desconexiones, reconexión automática, entrega diferida de resultados de herramientas
Soporte de structuredContent: Cumplimiento completo de la especificación MCP, incluida la extracción y reenvío de contenido estructurado

Planes de Ejecución (Impulsados por chuk-ai-planner)

Creación de Planes: Genera planes de ejecución a partir de descripciones en lenguaje natural utilizando agentes de planificación basados en LLM
Planificación Impulsada por Modelos: Con --plan-tools, el LLM decide autónomamente cuándo planificar — llama a plan_create_and_execute para tareas complejas de múltiples pasos, usa herramientas regulares para tareas simples
Ejecución DAG: Los planes son grafos acíclicos dirigidos — los pasos independientes se ejecutan en lotes paralelos, los pasos dependientes esperan
Resolución de Variables: Las salidas de los pasos se vinculan a variables (result_variable), referenciadas por pasos posteriores como ${var} o ${var.field}
Modo de Simulación: Traza lo que un plan haría sin ejecutar ninguna herramienta — seguro para producción
Puntos de Control: El estado de ejecución se guarda después de cada lote; reanuda planes interrumpidos sin volver a ejecutar pasos completados
Integración de Guardas: Los planes comparten presupuesto y límites por herramienta con la conversación — sin omisiones
Replanificación: Ante un fallo de paso, opcionalmente invoca al LLM para generar un plan revisado para el trabajo restante
Visualización DAG: La representación ASCII muestra la estructura de dependencias, agrupación de lotes y marcadores paralelos
Persistencia: Los planes se almacenan como JSON en ~/.mcp-cli/plans/

Gestión Avanzada de Configuración

Integración de Entorno: Claves API y ajustes mediante variables de entorno
Configuración Basada en Archivos: Archivos de configuración YAML y JSON
Preferencias de Usuario: Ajustes persistentes para proveedores y modelos activos
Validación y Diagnósticos: Verificaciones de salud de proveedores integradas y validación de configuración

Experiencia de Usuario Mejorada

Soporte Multiplataforma: Windows, macOS y Linux con optimizaciones específicas de plataforma mediante chuk-term
Salida de Consola Enriquecida: Impulsada por chuk-term con 8 temas integrados (default, dark, light, minimal, terminal, monokai, dracula, solarized)
Gestión Avanzada de Terminal: Operaciones de terminal multiplataforma que incluyen limpieza, redimensionamiento, detección de color y control de cursor
Componentes de UI Interactivos: Manejo de entrada de usuario a través del sistema de prompts de chuk-term (ask, confirm, select_from_list, select_multiple)
Completado de Comandos: Completado con tabulación sensible al contexto para todas las interfaces
Ayuda Integral: Sistema de ayuda detallado con ejemplos y patrones de uso
Manejo Elegante de Errores: Mensajes de error amigables con sugerencias de solución de problemas

📚 Documentación

Documentación completa disponible en el directorio docs/:

Proyecto

Arquitectura - 15 principios de diseño, estructura de módulos y convenciones de codificación
Hoja de Ruta - Visión, niveles completados (1-5) y niveles planificados (6-12: planes, trazas, habilidades, programación, multiagente, sesiones remotas)

Documentación Principal

Sistema de Comandos - Guía completa del sistema de comandos unificado, patrones y uso en todos los modos
Gestión de Tokens - Gestión integral de tokens para proveedores y servidores, incluyendo OAuth, tokens de portador y claves API

Documentación Especializada

Planes de Ejecución - Creación de planes, ejecución paralela, resolución de variables, puntos de control, guardas y replanificación
Panel de Control - UI de navegador en tiempo real con terminal de agente, flujo de actividad y carga de archivos
Adjuntos - Adjuntos de archivos multimodales: imágenes, texto, audio y carga desde navegador
Aplicaciones MCP - UIs de navegador interactivas servidas por servidores MCP (SEP-1865)
Autenticación OAuth - Flujos OAuth, backends de almacenamiento e integración con servidores MCP
Integración de Streaming - Arquitectura de streaming de respuestas en tiempo real
Gestión de Paquetes - Organización de dependencias y grupos de características

Documentación de UI

Temas - Sistema de temas y personalización
Sistema de Salida - Salida de consola enriquecida y formato
Gestión de Terminal - Operaciones de terminal multiplataforma

Documentación de Pruebas

Pruebas Unitarias - Estructura y patrones de pruebas
Cobertura de Pruebas - Requisitos de cobertura e informes

📋 Requisitos Previos

Python 3.11 o superior
Para Operación Local (Predeterminado):
- Ollama: Instalar desde ollama.ai
- Descargar el modelo de razonamiento predeterminado: ollama pull gpt-oss
Para Proveedores en la Nube (Opcional):
- OpenAI: variable de entorno OPENAI_API_KEY (para modelos GPT-5, GPT-4, O3)
- Anthropic: variable de entorno ANTHROPIC_API_KEY (para Claude 4.5, Claude 3.5)
- Azure: AZURE_OPENAI_API_KEY y AZURE_OPENAI_ENDPOINT (para GPT-5 empresarial)
- Google: GEMINI_API_KEY (para modelos Gemini)
- Groq: GROQ_API_KEY (para modelos Llama rápidos)
- Proveedores personalizados: Configuración específica del proveedor
Servidores MCP: Archivo de configuración de servidores (predeterminado: server_config.json)

🚀 Instalación

Inicio Rápido con Ollama (Predeterminado)

Instalar Ollama (si aún no está instalado):

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

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

Descargar el modelo de razonamiento predeterminado:

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

Instalar y ejecutar 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 Diferentes Modelos

# === 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

🧰 Configuración Global

Configuración Predeterminada

MCP CLI usa por defecto:

Proveedor: ollama (local, sin necesidad de clave API)
Modelo: gpt-oss (modelo de razonamiento de código abierto con visibilidad de pensamiento)

Argumentos de Línea de Comandos

Opciones globales disponibles para todos los modos y comandos:

--server: Especificar servidor(es) a los que conectarse (separados por comas)
--config-file: Ruta al archivo de configuración de servidores (predeterminado: server_config.json)
--provider: Proveedor LLM (predeterminado: ollama)
--model: Modelo específico a usar (predeterminado: gpt-oss para Ollama)
--disable-filesystem: Deshabilitar acceso al sistema de archivos (predeterminado: habilitado)
--api-base: Sobrescribir URL del endpoint de API
--api-key: Sobrescribir clave API (no necesaria para Ollama)
--token-backend: Sobrescribir backend de almacenamiento de tokens (auto, keychain, windows, secretservice, encrypted, vault)
--verbose: Habilitar registro detallado
--quiet: Suprimir salida no esencial
--log-file: Escribir registros de depuración en un archivo rotativo (secretos redactados automáticamente)
--vm: [Experimental] Habilitar memoria virtual de IA para gestión de contexto
--vm-budget: Presupuesto de tokens para eventos de conversación en modo VM (predeterminado: 128000, además del prompt del sistema)
--vm-mode: Modo VM — passive (predeterminado), relaxed o strict
--dashboard: Lanzar una UI de panel de control en navegador en tiempo real junto con el modo chat
--attach: Adjuntar archivos al primer mensaje (repetible: --attach img.png --attach code.py)
--plan-tools: Habilitar planificación impulsada por modelos — el LLM crea y ejecuta autónomamente planes de múltiples pasos
--no-tools: Deshabilitar completamente la llamada a herramientas MCP — chatear directamente con el LLM sin conectarse a ningún servidor MCP

Variables de Entorno

# 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 Disponibles

1. Modo Chat (Predeterminado)

Proporciona una interfaz de lenguaje natural con respuestas en streaming y uso automático de herramientas:

# 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 Interactivo

Interfaz de shell basada en comandos para operaciones directas del 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 Comando

Interfaz amigable con Unix para automatización y scripting:

# 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 Directos

Ejecutar comandos individuales sin entrar en modo interactivo:

# 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

🌐 Aplicaciones MCP (UIs de Navegador Interactivas)

Las Aplicaciones MCP permiten que los servidores de herramientas proporcionen UIs HTML interactivas que se renderizan en tu navegador. Cuando una herramienta tiene una anotación _meta.ui que apunta a un recurso de UI, mcp-cli lanza automáticamente un servidor web local y abre la aplicación en tu navegador.

Requisitos Previos

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

Cómo Funciona

Conéctate a un servidor MCP que proporcione herramientas habilitadas para aplicaciones
Llama a una herramienta que tenga metadatos _meta.ui (por ejemplo, show_chart, show_table)
mcp-cli obtiene automáticamente el recurso de UI, inicia un servidor local y abre tu navegador
La aplicación recibe resultados de herramientas en tiempo real vía WebSocket

Ejemplo

# 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

Arquitectura

Página anfitriona sirve un iframe sandboxed con el HTML de la aplicación
Puente WebSocket hace proxy de JSON-RPC entre el navegador y los servidores MCP
Seguridad: Sandbox de iframe, protección CSP, prevención de XSS, validación de esquemas de URL
Fiabilidad: Cola de mensajes durante desconexiones, reconexión con retroceso exponencial, entrega diferida de resultados de herramientas

Consulta la Documentación de Aplicaciones MCP para la guía completa.

🤖 Usando el Modo Chat

El modo chat proporciona la interfaz más avanzada con respuestas en streaming y uso inteligente de herramientas.

Iniciando el Modo 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)

Gestión de Proveedores y 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

Gestión de Herramientas

/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

Gestión de Servidores (Configuración en Tiempo de Ejecución)

/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: Los servidores añadidos vía /server add se almacenan en ~/.mcp-cli/preferences.json y persisten entre sesiones. Los servidores de proyecto permanecen en server_config.json.

Adjuntos Multimodales

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

Gestión de Conversaciones

/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

Personalización 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

Gestión 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 Almacenamiento de Tokens: MCP CLI soporta múltiples backends seguros de almacenamiento de tokens:

Keychain (macOS) - Usa el Llavero de macOS (predeterminado en macOS)
Administrador de Credenciales de Windows - Almacenamiento nativo de Windows (predeterminado en Windows)
Servicio Secreto - Llavero de escritorio Linux (GNOME/KDE)
Archivo Cifrado - Archivos locales cifrados AES-256 (respaldo multiplataforma)
HashiCorp Vault - Gestión de secretos empresarial

Sobrescribe el backend predeterminado con --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

Consulta la Guía de Gestión de Tokens para documentación completa.

Control de Sesión

/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 documentación completa de comandos, consulta la Guía del Sistema de Comandos.

Características del Chat

Respuestas en Streaming con Visibilidad de Razonamiento

🧠 Modelos de Razonamiento: Ve el proceso de pensamiento de la IA con gpt-oss, GPT-5, Claude 4
Generación en Tiempo Real: Observa cómo aparece el texto token por token
Métricas de Rendimiento: Palabras/segundo, tiempo de respuesta
Interrupción Elegante: Ctrl+C para detener el streaming
Renderizado Progresivo: Markdown formateado mientras se transmite

Ejecución de Herramientas

Descubrimiento y uso automático de herramientas
Ejecución concurrente con indicadores de progreso
Modos de visualización detallado y compacto
Historial completo de ejecución y tiempos

Adjuntos Multimodales

Adjunta imágenes, archivos de texto y audio a cualquier mensaje
Comando /attach con preparación, listado y limpieza (alias: /file, /image)
Referencias @file:path en línea en cualquier mensaje
Indicador CLI --attach para adjuntos en el primer mensaje
Botón "+" del navegador con arrastrar y soltar y pegado desde portapapeles (con --dashboard)
El panel de control renderiza miniaturas, vistas previas de texto y reproductores de audio

Integración de Proveedores

Cambio fluido entre proveedores
Optimizaciones específicas de modelo
Gestión de claves API y endpoints
Monitoreo de salud y diagnósticos

🖥️ Usando el Modo Interactivo

El modo interactivo proporciona un shell de comandos para interacción directa con el servidor.

Iniciando el Modo Interactivo

mcp-cli interactive --server sqlite

Comandos Interactivos

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 el Modo Comando

El modo comando proporciona capacidades de automatización amigables con Unix.

Opciones del Modo 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

Ejemplos

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

🔧 Configuración de Proveedores

Configuración de Ollama (Predeterminado)

Ollama se ejecuta localmente por defecto en http://localhost:11434. MCP CLI v0.11.1+ con CHUK-LLM v0.16+ incluye integración con llama.cpp que descubre y reutiliza automáticamente los modelos descargados de Ollama para una inferencia 1.53x más rápida (311 vs 204 tokens/seg) sin volver a descargarlos.

Para usar modelos de razonamiento y otros:

# 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

Configuración de Proveedores en la Nube

Para usar proveedores de nube con modelos avanzados, configura las claves 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

Proveedores personalizados compatibles con OpenAI

MCP CLI admite agregar proveedores personalizados compatibles con 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 seguridad: Las claves API se pueden almacenar de forma segura en llaveros nativos del sistema operativo (Llavero de macOS, Administrador de credenciales de Windows, Servicio de secretos de Linux) o en HashiCorp Vault mediante el sistema de gestión de tokens. Alternativamente, usa variables de entorno siguiendo el patrón {PROVIDER_NAME}_API_KEY o pásalas mediante --api-key para uso solo en la sesión. Consulta Gestión de tokens para más detalles.

Configuración manual

La configuración de la biblioteca chuk_llm en ~/.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

Las claves API se pueden proporcionar mediante:

Almacenamiento seguro de tokens (recomendado): almacenadas en el llavero del sistema operativo/Vault, consulta Gestión de tokens
Variables de entorno: expórtalas en tu shell o agrégalas a ~/.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

Línea de comandos: pasa --api-key para uso solo en la sesión (no persistente)

📂 Configuración del servidor

MCP CLI admite dos tipos de configuraciones de servidor:

Servidores de proyecto (server_config.json): configuraciones compartidas a nivel de proyecto
Servidores de usuario (~/.mcp-cli/preferences.json): servidores personales agregados en tiempo de ejecución que persisten entre sesiones

Descubrimiento de archivos de configuración

MCP CLI busca server_config.json en el siguiente orden de prioridad:

Ruta explícita mediante la opción --config-file:

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

Directorio actual: se detecta automáticamente al ejecutarse desde un directorio de proyecto:
```
cd /path/to/my-project
mcp-cli --server sqlite    # Uses ./server_config.json if it exists
```
Predeterminado incluido: al ejecutarse mediante uvx o desde cualquier directorio sin una configuración local:
```
uvx mcp-cli --server cloudflare_workers    # Uses packaged server_config.json
```

Esto significa que puedes:

Anular por proyecto: coloca un server_config.json en el directorio de tu proyecto con configuraciones de servidor específicas del proyecto
Usar valores predeterminados globalmente: ejecuta uvx mcp-cli desde cualquier lugar y obtén los servidores predeterminados incluidos
Personalizar explícitamente: usa --config-file para especificar cualquier ubicación de archivo de configuración

Servidores predeterminados incluidos

MCP CLI v0.11.1+ incluye un conjunto ampliado de servidores preconfigurados en el server_config.json incluido:

Servidor	Tipo	Descripción	Configuración
sqlite	STDIO	Operaciones de base de datos SQLite	`uvx mcp-server-sqlite --db-path test.db`
echo	STDIO	Servidor de eco para pruebas	`uvx chuk-mcp-echo stdio`
math	STDIO	Cálculos matemáticos	`uvx chuk-mcp-math-server`
playwright	STDIO	Automatización de navegador	`npx @playwright/mcp@latest`
brave_search	STDIO	Búsqueda web mediante la API de Brave	Requiere token `BRAVE_API_KEY`
notion	HTTP	Integración con el espacio de trabajo de Notion	`https://mcp.notion.com/mcp` (OAuth)
cloudflare_workers	HTTP	Enlaces de Cloudflare Workers	`https://bindings.mcp.cloudflare.com/mcp` (OAuth)
monday	HTTP	Integración con Monday.com	`https://mcp.monday.com/mcp` (OAuth)
linkedin	HTTP	Integración con LinkedIn	`https://linkedin.chukai.io/mcp`
weather	HTTP	Servicio de datos meteorológicos	`https://weather.chukai.io/mcp`

Nota: Los servidores HTTP y los servidores basados en API requieren autenticación. Usa el sistema de Gestión de tokens para configurar los tokens de acceso.

Para usar estos 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

Configuración del proyecto

Crea un archivo server_config.json con las configuraciones de tus servidores 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}"
      }
    }
  }
}

Reemplazo seguro de tokens

MCP CLI admite el reemplazo automático de tokens desde almacenamiento seguro mediante la sintaxis ${TOKEN:namespace:name}:

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

Ejemplos:

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

Almacenamiento 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)

Ubicaciones admitidas:

env: variables de entorno para servidores STDIO
headers: encabezados HTTP para servidores HTTP/SSE

Espacios de nombres:

bearer: tokens Bearer (predeterminado para --type bearer)
api-key: claves API (predeterminado para --type api-key)
oauth: tokens OAuth (automático)
generic: tokens personalizados

Beneficios:

✅ Nunca almacenes claves API en archivos de configuración
✅ Comparte server_config.json de forma segura (sin secretos)
✅ Tokens cifrados en almacenamiento seguro nativo del sistema operativo
✅ Funciona en todos los tipos de transporte (STDIO, HTTP, SSE)

Consulta la Guía de gestión de tokens para obtener documentación completa.

Gestión de servidores en tiempo de ejecución

Agrega servidores dinámicamente durante el tiempo de ejecución sin editar archivos de configuración:

# 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

Puntos clave:

Los servidores agregados por el usuario persisten en ~/.mcp-cli/preferences.json
Sobreviven a los reinicios de la aplicación
Se pueden habilitar/deshabilitar sin eliminarlos
Admiten transportes STDIO, HTTP y SSE
Variables de entorno y encabezados para autenticación

📈 Ejemplos de uso avanzado

Comparación de modelos de razonamiento

# 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]

Flujo de trabajo local primero con razonamiento

# 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...

Flujo de trabajo con múltiples proveedores

# 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

Flujos de trabajo complejos con herramientas y razonamiento

# 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]

Automatización y scripting

# 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

Monitoreo de rendimiento

# 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]

🔍 Solución de problemas

Problemas comunes

Ollama no se está ejecutando (proveedor predeterminado):

# Start Ollama service
ollama serve

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

Modelo no 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

Proveedor no encontrado o falta la clave API:

# 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 conexión con 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 depuración

Habilita el registro detallado para solucionar 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

🔒 Consideraciones de seguridad

Privacidad y local primero

Local por defecto: Ollama con gpt-oss se ejecuta localmente, manteniendo tus datos privados
Sin necesidad de nube: funcionalidad completa sin dependencias de API externas

Seguridad de tokens y autenticación

Almacenamiento seguro de tokens: los tokens se almacenan en almacenes de credenciales nativos del sistema operativo (Llavero de macOS, Administrador de credenciales de Windows, Servicio de secretos de Linux) bajo el identificador de servicio "mcp-cli"
Múltiples backends de almacenamiento: elige entre llavero, archivos cifrados o HashiCorp Vault según los requisitos de seguridad
Claves API: solo se necesitan para proveedores de nube (OpenAI, Anthropic, etc.), almacenadas de forma segura mediante el sistema de gestión de tokens
Soporte OAuth 2.0: autenticación segura para servidores MCP mediante PKCE e indicadores de recursos (RFC 7636, RFC 8707)

Seguridad de registros

Redacción de secretos: toda la salida de registros (consola y archivo) se redacta automáticamente para tokens Bearer, claves API (sk-*), tokens de acceso OAuth y encabezados de autorización
Registros rotativos: --log-file opcional con formato JSON, rotación de 10 MB y 3 archivos de respaldo

Seguridad de ejecución

Validación de herramientas: todas las llamadas a herramientas se validan antes de la ejecución
Protección de tiempo de espera: los tiempos de espera configurables evitan operaciones colgadas (v0.13+)
Interruptores de circuito: detección y recuperación automática de fallos para evitar fallos en cascada (v0.13+)
Aislamiento de servidores: cada servidor se ejecuta en su propio proceso
Acceso a archivos: el acceso al sistema de archivos se puede deshabilitar con --disable-filesystem
Monitoreo de transporte: detección automática de fallos de conexión con advertencias (v0.11+)

Seguridad de aplicaciones MCP

Sandbox de iframes: las aplicaciones se ejecutan en iframes con sandbox y permisos restringidos
Política de seguridad de contenido: los dominios CSP proporcionados por el servidor se validan y sanean
Prevención de XSS: los nombres de herramientas y el contenido proporcionado por el usuario se escapan en HTML antes de la inyección en plantillas
Validación de esquemas de URL: ui/open-link solo permite esquemas http:// y https://
Validación de nombres de herramientas: el puente rechaza nombres de herramientas que no coinciden con el conjunto de caracteres de la especificación MCP
Validación de origen de WebSocket (v0.20.1+): el servidor local de host de aplicaciones rechaza cualquier protocolo de enlace WebSocket cuyo encabezado Origin no coincida con su propia página host http://localhost:<port>, por lo que una página web no relacionada no puede conectarse al puente de una aplicación en ejecución
Aplicación de permisos de herramientas (v0.20.1+): cuando un recurso declara una lista de permitidos de herramientas que puede llamar, el puente la aplica en cada tools/call, no solo una verificación de sintaxis de nombres de herramientas
Obtención de recursos segura contra SSRF (v0.20.1+): las obtenciones directas de recursos HTTP(S) se validan contra rangos de direcciones privadas/de bucle local/enlace local antes de conectarse, y se revalidan en cada salto de redirección

Seguridad del panel de control (v0.20.1+)

Validación de origen de WebSocket: el servidor WebSocket del panel aplica la misma verificación de origen que las aplicaciones MCP
Renderizado de Markdown saneado: los mensajes de chat del asistente se renderizan mediante DOMPurify en lugar de un saneador hecho a mano
Metadatos de vista escapados: los nombres de vista e iconos declarados por el servidor se escapan en HTML antes de insertarse en los encabezados de panel
Rutas de agente/sesión saneadas: los identificadores de agente y sesión se sanean antes de usarse como componentes de ruta del sistema de archivos

Seguridad de ejecución de planes (v0.20.1+)

Confirmación de herramientas aplicada: la ejecución de planes (/plan, plan_create_and_execute) respeta la misma preferencia de confirmación de herramientas y la política de dominios de confianza que la ruta de chat interactivo; si se requiere confirmación y no hay un mensaje disponible, la llamada se rechaza en lugar de ejecutarse sin confirmación

🚀 Características de rendimiento

Rendimiento del proveedor LLM (v0.16+)

Importaciones 52 veces más rápidas: reducidas de 735 ms a 14 ms mediante carga diferida
Creación de cliente 112 veces más rápida: almacenamiento en caché automático seguro para subprocesos
Integración con llama.cpp: inferencia 1.53 veces más rápida (311 frente a 204 tokens/segundo) con reutilización automática de modelos de Ollama
Descubrimiento dinámico de modelos: selección de modelos basada en capacidades con cero sobrecarga

Rendimiento de ejecución de herramientas (v0.13+)

Middleware de producción: tiempos de espera, reintentos con retroceso exponencial, interruptores de circuito y almacenamiento en caché de resultados
Ejecución concurrente de herramientas: múltiples herramientas pueden ejecutarse simultáneamente con la coordinación adecuada
Monitoreo de salud de conexiones: detección y recuperación automáticas de fallos de transporte
Gestor de herramientas optimizado: reducido de más de 2000 a aproximadamente 800 líneas manteniendo toda la funcionalidad

Rendimiento en tiempo de ejecución

Procesamiento local: el proveedor Ollama predeterminado minimiza la latencia
Visibilidad del razonamiento: ve el proceso de pensamiento de la IA con gpt-oss, GPT-5, Claude 4
Respuestas en streaming: generación de respuestas en tiempo real
Agrupación de conexiones: reutilización eficiente de conexiones de clientes
Almacenamiento en caché: los metadatos de herramientas y las configuraciones de proveedores se almacenan en caché
Arquitectura asíncrona: operaciones sin bloqueo en todo el sistema

📦 Dependencias

Las dependencias principales están organizadas en grupos de características:

cli: interfaz de terminal y marco de comandos (Rich, Typer, chuk-term)
dev: herramientas de desarrollo, utilidades de prueba, linting
chuk-tool-processor v0.22+: ejecución de herramientas de grado de producción con middleware, múltiples estrategias de ejecución y observabilidad
chuk-llm v0.17+: proveedor LLM unificado con descubrimiento dinámico de modelos, selección basada en capacidades e integración con llama.cpp
chuk-term: interfaz de terminal mejorada con temas, mensajes y soporte multiplataforma

Instala con características específicas:

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)

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Consulta nuestra Guía de contribuciones para más detalles.

Configuración de desarrollo

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

Scripts de demostración

Explora las capacidades de 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

Ejecución de pruebas

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

📜 Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0; consulta el archivo LICENCIA para más detalles.

🙏 Agradecimientos

CHUK Tool Processor - Ejecución de herramientas asíncronas de grado de producción con middleware y observabilidad
CHUK-LLM - Proveedor LLM unificado con descubrimiento dinámico de modelos, integración con llama.cpp y soporte para GPT-5/Claude 4.5 (v0.17+)
CHUK-Term - Interfaz de terminal mejorada con temas y soporte multiplataforma
Rich - Formato de terminal hermoso
Typer - Marco de CLI
Prompt Toolkit - Entrada interactiva

🔗 Proyectos relacionados

Model Context Protocol - Especificación del protocolo central
MCP Servers - Implementaciones oficiales de servidores MCP
CHUK Tool Processor - Ejecución de herramientas de nivel de producción con middleware y observabilidad
CHUK-LLM - Abstracción de proveedores de LLM con descubrimiento dinámico de modelos, soporte para GPT-5, Claude 4.5, serie O3 e integración con llama.cpp
CHUK-Term - Biblioteca de interfaz de terminal con temas y soporte multiplataforma