MCP-CLI: Herramienta de Interfaz de Línea de Comandos para el Protocolo de Contexto de Modelo

Resumen del Proyecto

MCP-CLI es una herramienta de interfaz de línea de comandos potente y rica en características, diseñada específicamente para interactuar con servidores del Protocolo de Contexto de Modelo (Model Context Protocol, MCP). Esta herramienta, al integrar la librería de protocolo CHUK-MCP, proporciona a los usuarios una capacidad de comunicación fluida con Modelos de Lenguaje Grandes (LLM).

Este cliente soporta el uso de herramientas, la gestión de conversaciones y múltiples modos de operación. La implementación del protocolo central se ha migrado a un paquete independiente, lo que permite que la CLI se centre en proporcionar una experiencia de usuario enriquecida, mientras que la librería del protocolo se encarga de la capa de comunicación.

Características Principales

🔄 Múltiples Modos de Operación

• Modo de Chat (Chat Mode): Interfaz conversacional que soporta la interacción directa con LLM y el uso automatizado de herramientas.
• Modo Interactivo (Interactive Mode): Interfaz basada en comandos para operaciones directas del servidor.
• Modo de Comando (Command Mode): Modo amigable con Unix, que soporta automatización mediante scripts y operaciones de tuberías (pipes).
• Comandos Directos: Permite ejecutar un solo comando sin necesidad de entrar en modo interactivo.

🌐 Soporte para Múltiples Proveedores

• Integración con OpenAI: Soporta modelos como gpt-4o-mini, gpt-4o, gpt-4-turbo, entre otros.
• Integración con Ollama: Soporta modelos locales como llama3.2, qwen2.5-coder, entre otros.
• Arquitectura Extensible: Permite añadir otros proveedores.

🛠️ Potente Sistema de Herramientas

• Descubrimiento automático de herramientas proporcionadas por el servidor.
• Ejecución de herramientas consciente del servidor.
• Seguimiento y análisis del historial de llamadas a herramientas.
• Soporte para cadenas de herramientas complejas de varios pasos.

💬 Gestión Avanzada de Conversaciones

• Seguimiento completo del historial de conversaciones.
• Soporte para filtrar y ver rangos de mensajes específicos.
• Funcionalidad de exportación JSON para depuración o análisis.
• Función de compresión de conversaciones para reducir el uso de tokens.

🎨 Experiencia de Usuario Enriquecida

• Autocompletado de comandos sensible al contexto.
• Salida de consola con formato de color.
• Indicadores de progreso para operaciones de larga duración.
• Ayuda y documentación detalladas.

🔧 Gestión Fiable de Recursos

• Limpieza adecuada de recursos de E/S asíncronos.
• Manejo elegante de errores.
• Restauración limpia del terminal.
• Soporte para múltiples conexiones simultáneas al servidor.

Requisitos del Sistema

• Python 3.11 o superior.
• Para OpenAI: Se requiere una clave API válida configurada en la variable de entorno OPENAI_API_KEY.
• Para Ollama: Se requiere una instalación local de Ollama.
• Archivo de configuración del servidor (por defecto: server_config.json).
• Librería de protocolo CHUK-MCP.

Métodos de Instalación

Instalación Estándar

# Clonar el repositorio
git clone https://github.com/chrishayuk/mcp-cli
cd mcp-cli

# Instalar el paquete y las dependencias de desarrollo
pip install -e ".[cli,dev]"

# Ejecutar la CLI
mcp-cli --help

Usando UV para la Gestión de Dependencias

# Instalar UV (si no está instalado)
pip install uv

# Instalar dependencias
uv sync --reinstall

# Ejecutar con UV
uv run mcp-cli --help

Guía de Uso

Opciones Globales

Todos los comandos soportan las siguientes opciones globales:

• --server: Especifica el servidor al que conectarse (múltiples servidores separados por comas).
• --config-file: Ruta del archivo de configuración del servidor (por defecto: server_config.json).
• --provider: Proveedor de LLM a usar (openai u ollama, por defecto: openai).
• --model: Modelo específico a usar (depende de los valores por defecto del proveedor).
• --disable-filesystem: Deshabilita el acceso al sistema de archivos (por defecto: true).

Modo de Chat

El modo de chat proporciona una interfaz conversacional con el LLM, utilizando automáticamente las herramientas disponibles cuando sea necesario:

# Modo de chat básico
mcp-cli chat --server sqlite

# Especificar proveedor y modelo
mcp-cli chat --server sqlite --provider openai --model gpt-4o
mcp-cli chat --server sqlite --provider ollama --model llama3.2

Comandos de Barra en Modo Chat

En el modo de chat, se pueden usar los siguientes comandos de barra:

Comandos de ayuda:

• /help: Muestra los comandos disponibles.
• /help <command>: Muestra ayuda detallada para un comando específico.
• /quickhelp o /qh: Muestra una referencia rápida para comandos comunes.

Relacionado con herramientas:

• /tools: Muestra todas las herramientas disponibles y su información de servidor.
• /tools --all: Muestra información detallada de la herramienta, incluyendo parámetros.
• /tools --raw: Muestra las definiciones de herramientas en bruto.
• /toolhistory o /th: Muestra el historial de llamadas a herramientas para la sesión actual.

Gestión de conversaciones:

• /conversation o /ch: Muestra el historial de conversaciones.
• /save <filename>: Guarda el historial de conversaciones en un archivo JSON.
• /compact: Compacta el historial de conversaciones a un resumen.

Control de interfaz:

• /cls: Limpia la pantalla pero conserva el historial de conversaciones.
• /clear: Limpia la pantalla y el historial de conversaciones.
• /verbose o /v: Alterna entre los modos de visualización de herramientas detallado y conciso.

Modo Interactivo

El modo interactivo proporciona una interfaz de línea de comandos, utilizando comandos de barra para la interacción directa con el servidor:

mcp-cli interactive --server sqlite

Comandos del Modo Interactivo

• /ping: Comprueba si el servidor responde.
• /prompts: Lista los prompts disponibles.
• /tools: Lista las herramientas disponibles.
• /resources: Lista los recursos disponibles.
• /chat: Entra en modo de chat.
• /exit o /quit: Sale del programa.

Modo de Comando

El modo de comando proporciona una interfaz amigable con Unix, para automatización e integración de tuberías:

mcp-cli cmd --server sqlite [options]

Opciones del Modo de Comando

• --input: Ruta del archivo de entrada (use - para stdin).
• --output: Ruta del archivo de salida (use - para stdout, por defecto).
• --prompt: Plantilla de prompt (use {{input}} como marcador de posición para la entrada).
• --raw: Salida de texto sin formato.
• --tool: Llama directamente a una herramienta específica.
• --tool-args: Parámetros JSON para la llamada a la herramienta.
• --system-prompt: Prompt de sistema personalizado.

Ejemplos del Modo de Comando

# Resumir documento
mcp-cli cmd --server sqlite --input document.md --prompt "Summarize this: {{input}}" --output summary.md

# Procesar stdin y salida a stdout
cat document.md | mcp-cli cmd --server sqlite --input - --prompt "Extract key points: {{input}}"

# Llamar directamente a una herramienta
mcp-cli cmd --server sqlite --tool list_tables --raw
mcp-cli cmd --server sqlite --tool read_query --tool-args '{"query": "SELECT COUNT(*) FROM users"}'

# Procesamiento por lotes
ls *.md | parallel mcp-cli cmd --server sqlite --input {} --output {}.summary.md --prompt "Summarize: {{input}}"

Comandos Directos

Ejecuta un solo comando sin necesidad de entrar en modo interactivo:

# Listar herramientas disponibles
mcp-cli tools list --server sqlite

# Llamar a una herramienta específica
mcp-cli tools call --server sqlite

# Listar prompts disponibles
mcp-cli prompts list --server sqlite

# Comprobar conexión del servidor
mcp-cli ping --server sqlite

# Listar recursos disponibles
mcp-cli resources list --server sqlite

Archivo de Configuración

Cree el archivo server_config.json para configurar los servidores:

{
  "mcpServers": {
    "sqlite": {
      "command": "python",
      "args": ["-m", "mcp_server.sqlite_server"],
      "env": {
        "DATABASE_PATH": "your_database.db"
      }
    },
    "another-server": {
      "command": "python",
      "args": ["-m", "another_server_module"],
      "env": {}
    }
  }
}

Estructura del Proyecto

src/
├── mcp_cli/
│   ├── chat/                    # Implementación del modo de chat
│   │   ├── commands/            # Comandos de barra de chat
│   │   │   ├── __init__.py      # Sistema de registro de comandos
│   │   │   ├── conversation.py  # Gestión de conversaciones
│   │   │   ├── help.py          # Comandos de ayuda
│   │   │   ├── tools.py         # Comandos de herramientas
│   │   │   └── ...
│   │   ├── chat_context.py      # Gestión del estado de la sesión de chat
│   │   ├── chat_handler.py      # Manejador principal del bucle de chat
│   │   ├── command_completer.py # Autocompletado de comandos
│   │   └── ui_manager.py        # Interfaz de usuario
│   ├── commands/                # Comandos CLI
│   │   ├── chat.py              # Comando de chat
│   │   ├── cmd.py               # Modo de comando
│   │   ├── interactive.py       # Modo interactivo
│   │   └── ...
│   ├── llm/                     # Implementación del cliente LLM
│   │   ├── providers/           # Clientes específicos del proveedor
│   │   │   ├── base.py          # Cliente LLM base
│   │   │   └── openai_client.py # Implementación de OpenAI
│   │   └── llm_client.py        # Fábrica de clientes
│   ├── ui/                      # Componentes de la interfaz de usuario
│   │   ├── colors.py            # Definiciones de color
│   │   └── ui_helpers.py        # Utilidades de UI
│   ├── main.py                  # Punto de entrada principal
│   └── config.py                # Cargador de configuración

Ejemplos de Uso

Ejecución Automática de Herramientas

En el modo de chat, MCP CLI puede ejecutar automáticamente las herramientas proporcionadas por el servidor:

You: What tables are available in the database?
Assistant: Let me check for you.
[Tool Call: list_tables]
I found the following tables in the database:
- users
- products  
- orders
- categories

You: How many users do we have?
Assistant: I'll query the database for that information.
[Tool Call: read_query]
There are 873 users in the database.

Traducción:

Tú: ¿Qué tablas están disponibles en la base de datos?
Asistente: Permítame comprobarlo.
[Llamada a Herramienta: list_tables]
Encontré las siguientes tablas en la base de datos:
- users
- products  
- orders
- categories

Tú: ¿Cuántos usuarios tenemos?
Asistente: Consultaré la base de datos para esa información.
[Llamada a Herramienta: read_query]
Hay 873 usuarios en la base de datos.

Scripting Automatizado

El modo de comando soporta potentes scripts de automatización:

#!/bin/bash
# Script de ejemplo para analizar múltiples documentos

# Procesar todos los archivos markdown en el directorio actual
for file in *.md; do
    echo "Processing $file..."
    
    # Generar resumen
    mcp-cli cmd --server sqlite --input "$file" \
        --prompt "Summarize this document: {{input}}" \
        --output "${file%.md}.summary.md"
    
    # Extraer entidades
    mcp-cli cmd --server sqlite --input "$file" \
        --prompt "Extract all company names, people, and locations from this text: {{input}}" \
        --output "${file%.md}.entities.txt" --raw
done

# Crear informe completo
echo "Creating final report..."
cat *.entities.txt | mcp-cli cmd --server sqlite --input - \
    --prompt "Analyze these entities and identify the most frequently mentioned:" \
    --output report.md

Gestión del Historial de Conversaciones

Seguimiento y gestión del historial de conversaciones:

> /conversation
Conversation History (12 messages)
# | Role | Content
1 | system | You are an intelligent assistant capable of using t...
2 | user | What tables are available in the database?
3 | assistant | Let me check for you.
4 | assistant | [Tool call: list_tables]
...

> /conversation 4
Message #4 (Role: assistant)
[Tool call: list_tables]
Tool Calls:
1. ID: call_list_tables_12345678, Type: function, Name: list_tables
Arguments: {}

> /save conversation.json
Conversation saved to conversation.json

> /compact
Conversation history compacted with summary.
Summary:
The user asked about database tables, and I listed the available tables (users, products, orders, categories). The user then asked about the number of users, and I queried the database to find there are 873 users.

Traducción:

> /conversation
Historial de Conversación (12 mensajes)
# | Rol | Contenido
1 | system | Eres un asistente inteligente capaz de usar t...
2 | user | ¿Qué tablas están disponibles en la base de datos?
3 | assistant | Permítame comprobarlo.
4 | assistant | [Llamada a herramienta: list_tables]
...

> /conversation 4
Mensaje #4 (Rol: assistant)
[Llamada a herramienta: list_tables]
Llamadas a Herramientas:
1. ID: call_list_tables_12345678, Tipo: function, Nombre: list_tables
Argumentos: {}

> /save conversation.json
Conversación guardada en conversation.json

> /compact
Historial de conversación compactado con resumen.
Resumen:
El usuario preguntó sobre las tablas de la base de datos, y listé las tablas disponibles (users, products, orders, categories). Luego, el usuario preguntó sobre el número de usuarios, y consulté la base de datos para encontrar que hay 873 usuarios.

Gestión de Dependencias

La CLI utiliza grupos de dependencias opcionales para su organización:

• cli: UI de terminal enriquecida, autocompletado de comandos e integraciones de proveedores.
• dev: Herramientas de desarrollo y utilidades de prueba.
• wasm: (Reservado para futuro soporte de WebAssembly).
• chuk-mcp: Librería de implementación del protocolo (dependencia central).

Instalar extras específicos:

pip install "mcp-cli[cli]"        # Funcionalidad CLI básica
pip install "mcp-cli[cli,dev]"    # CLI + Herramientas de desarrollo

Guía de Contribución

¡Se aceptan contribuciones! Siga estos pasos:

1. Bifurque el repositorio (Fork the repository).
2. Cree su rama de características (git checkout -b feature/amazing-feature).
3. Confirme sus cambios (git commit -m 'Add some amazing feature').
4. Empuje a la rama (git push origin feature/amazing-feature).
5. Abra una Solicitud de Extracción (Open a Pull Request).

Sobre el Protocolo de Contexto de Modelo (MCP)

MCP es un protocolo abierto que estandariza la forma en que las aplicaciones proporcionan contexto a los LLM. Se puede comparar MCP con el puerto USB-C para aplicaciones de IA. Así como USB-C proporciona una forma estandarizada de conectar dispositivos a varios periféricos y accesorios, MCP proporciona una forma estandarizada de conectar modelos de IA a diversas fuentes de datos y herramientas.