MCP-CLI: Ferramenta de Interface de Linha de Comando do Protocolo de Contexto de Modelo

Visão Geral do Projeto

MCP-CLI é uma ferramenta de interface de linha de comando poderosa e rica em recursos, projetada especificamente para interagir com servidores do Protocolo de Contexto de Modelo (Model Context Protocol, MCP). Ao integrar a biblioteca de protocolo CHUK-MCP, esta ferramenta oferece aos usuários capacidades de comunicação contínuas com Modelos de Linguagem Grandes (LLMs).

Este cliente suporta uso de ferramentas, gerenciamento de conversas e múltiplos modos de operação. A implementação do protocolo central foi migrada para um pacote independente, permitindo que a CLI se concentre em fornecer uma experiência de usuário rica, enquanto a biblioteca de protocolo lida com a camada de comunicação.

Recursos Principais

🔄 Múltiplos Modos de Operação

• Modo de Chat (Chat Mode): Interface conversacional que suporta interação direta com LLM e uso automatizado de ferramentas.
• Modo Interativo (Interactive Mode): Interface orientada por comandos para operações diretas no servidor.
• Modo de Comando (Command Mode): Modo amigável ao Unix, suportando automação via script e operações de pipeline.
• Comando Direto (Direct Command): Executa um único comando sem entrar no modo interativo.

🌐 Suporte a Múltiplos Provedores

• Integração OpenAI: Suporta modelos como gpt-4o-mini, gpt-4o, gpt-4-turbo, etc.
• Integração Ollama: Suporta modelos locais como llama3.2, qwen2.5-coder, etc.
• Arquitetura Extensível: Suporte para adicionar outros provedores.

🛠️ Poderoso Sistema de Ferramentas

• Descoberta automática de ferramentas fornecidas pelo servidor.
• Execução de ferramentas ciente do servidor.
• Rastreamento e análise do histórico de chamadas de ferramentas.
• Suporte a cadeias de ferramentas complexas e multi-etapas.

💬 Gerenciamento Avançado de Conversas

• Rastreamento completo do histórico de conversas.
• Suporte para filtrar e visualizar intervalos específicos de mensagens.
• Funcionalidade de exportação JSON para depuração ou análise.
• Funcionalidade de compressão de conversas para reduzir o uso de tokens.

🎨 Experiência de Usuário Rica

• Preenchimento automático de comandos sensível ao contexto.
• Saída de console formatada com cores.
• Indicadores de progresso para operações de longa duração.
• Ajuda e documentação detalhadas.

🔧 Gerenciamento Confiável de Recursos

• Limpeza adequada de recursos de E/S assíncronos.
• Tratamento de erros elegante.
• Restauração limpa do terminal.
• Suporte a múltiplas conexões simultâneas com o servidor.

Requisitos do Sistema

• Python 3.11 ou superior
• Para OpenAI: É necessária uma chave de API válida definida na variável de ambiente OPENAI_API_KEY.
• Para Ollama: É necessária uma instalação local do Ollama.
• Arquivo de configuração do servidor (padrão: server_config.json)
• Biblioteca de protocolo CHUK-MCP

Método de Instalação

Instalação Padrão

# Clonar o repositório
git clone https://github.com/chrishayuk/mcp-cli
cd mcp-cli

# Instalar o pacote e as dependências de desenvolvimento
pip install -e ".[cli,dev]"

# Executar a CLI
mcp-cli --help

Usando UV para Gerenciar Dependências

# Instalar UV (se não estiver instalado)
pip install uv

# Instalar dependências
uv sync --reinstall

# Executar com UV
uv run mcp-cli --help

Guia de Uso

Opções Globais

Todos os comandos suportam as seguintes opções globais:

• --server: Especifica o servidor ao qual se conectar (múltiplos servidores separados por vírgula).
• --config-file: Caminho para o arquivo de configuração do servidor (padrão: server_config.json).
• --provider: Provedor de LLM a ser usado (openai ou ollama, padrão: openai).
• --model: Modelo específico a ser usado (depende dos valores padrão do provedor).
• --disable-filesystem: Desabilita o acesso ao sistema de arquivos (padrão: true).

Modo de Chat

O modo de chat oferece uma interface conversacional com o LLM, usando automaticamente as ferramentas disponíveis quando necessário:

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

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

Comandos de Barra do Modo de Chat

No modo de chat, os seguintes comandos de barra podem ser usados:

Comandos de Ajuda:

• /help: Exibe os comandos disponíveis.
• /help <command>: Exibe ajuda detalhada para um comando específico.
• /quickhelp ou /qh: Exibe uma referência rápida para comandos comuns.

Relacionados a Ferramentas:

• /tools: Exibe todas as ferramentas disponíveis e suas informações de servidor.
• /tools --all: Exibe informações detalhadas da ferramenta, incluindo parâmetros.
• /tools --raw: Exibe a definição bruta da ferramenta.
• /toolhistory ou /th: Exibe o histórico de chamadas de ferramentas na sessão atual.

Gerenciamento de Conversas:

• /conversation ou /ch: Exibe o histórico da conversa.
• /save <filename>: Salva o histórico da conversa em um arquivo JSON.
• /compact: Compacta o histórico da conversa em um resumo.

Controle de Interface:

• /cls: Limpa a tela, mas mantém o histórico da conversa.
• /clear: Limpa a tela e o histórico da conversa.
• /verbose ou /v: Alterna entre os modos de exibição de ferramentas detalhado e conciso.

Modo Interativo

O modo interativo fornece uma interface de linha de comando, usando comandos de barra para interação direta com o servidor:

mcp-cli interactive --server sqlite

Comandos do Modo Interativo

• /ping: Verifica se o servidor está respondendo.
• /prompts: Lista os prompts disponíveis.
• /tools: Lista as ferramentas disponíveis.
• /resources: Lista os recursos disponíveis.
• /chat: Entra no modo de chat.
• /exit ou /quit: Sai do programa.

Modo de Comando

O modo de comando oferece uma interface amigável ao Unix para automação e integração de pipeline:

mcp-cli cmd --server sqlite [options]

Opções do Modo de Comando

• --input: Caminho do arquivo de entrada (use - para stdin).
• --output: Caminho do arquivo de saída (use - para stdout, padrão).
• --prompt: Modelo de prompt (use {{input}} como espaço reservado para a entrada).
• --raw: Saída de texto bruto sem formatação.
• --tool: Chama diretamente uma ferramenta específica.
• --tool-args: Parâmetros JSON para a chamada da ferramenta.
• --system-prompt: Prompt de sistema personalizado.

Exemplos do Modo de Comando

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

# Processar stdin e enviar para stdout
cat document.md | mcp-cli cmd --server sqlite --input - --prompt "Extraia os pontos-chave: {{input}}"

# Chamar uma ferramenta diretamente
mcp-cli cmd --server sqlite --tool list_tables --raw
mcp-cli cmd --server sqlite --tool read_query --tool-args '{"query": "SELECT COUNT(*) FROM users"}'

# Processamento em lote
ls *.md | parallel mcp-cli cmd --server sqlite --input {} --output {}.summary.md --prompt "Resuma: {{input}}"

Comandos Diretos

Execute um único comando sem entrar no modo interativo:

# Listar ferramentas disponíveis
mcp-cli tools list --server sqlite

# Chamar uma ferramenta específica
mcp-cli tools call --server sqlite

# Listar prompts disponíveis
mcp-cli prompts list --server sqlite

# Verificar conexão com o servidor
mcp-cli ping --server sqlite

# Listar recursos disponíveis
mcp-cli resources list --server sqlite

Arquivo de Configuração

Crie um arquivo server_config.json para configurar os 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": {}
    }
  }
}

Estrutura do Projeto

src/
├── mcp_cli/
│   ├── chat/                    # Implementação do modo de chat
│   │   ├── commands/            # Comandos de barra do chat
│   │   │   ├── __init__.py      # Sistema de registro de comandos
│   │   │   ├── conversation.py  # Gerenciamento de conversas
│   │   │   ├── help.py          # Comandos de ajuda
│   │   │   ├── tools.py         # Comandos de ferramentas
│   │   │   └── ...
│   │   ├── chat_context.py      # Gerenciamento de estado da sessão de chat
│   │   ├── chat_handler.py      # Processador principal do loop de chat
│   │   ├── command_completer.py # Preenchimento automático de comandos
│   │   └── ui_manager.py        # Interface de usuário
│   ├── commands/                # Comandos da CLI
│   │   ├── chat.py              # Comando de chat
│   │   ├── cmd.py               # Modo de comando
│   │   ├── interactive.py       # Modo interativo
│   │   └── ...
│   ├── llm/                     # Implementação do cliente LLM
│   │   ├── providers/           # Clientes específicos do provedor
│   │   │   ├── base.py          # Cliente LLM base
│   │   │   └── openai_client.py # Implementação OpenAI
│   │   └── llm_client.py        # Fábrica de clientes
│   ├── ui/                      # Componentes da interface de usuário
│   │   ├── colors.py            # Definições de cores
│   │   └── ui_helpers.py        # Utilitários de UI
│   ├── main.py                  # Ponto de entrada principal
│   └── config.py                # Carregador de configuração

Exemplos de Uso

Execução Automática de Ferramentas

No modo de chat, o MCP CLI pode executar automaticamente as ferramentas fornecidas pelo 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.

Scripts de Automação

O modo de comando suporta poderosos scripts de automação:

#!/bin/bash
# Script de exemplo para analisar múltiplos documentos

# Processar todos os arquivos markdown no diretório atual
for file in *.md; do
    echo "Processando $file..."
    
    # Gerar resumo
    mcp-cli cmd --server sqlite --input "$file" \
        --prompt "Resuma este documento: {{input}}" \
        --output "${file%.md}.summary.md"
    
    # Extrair entidades
    mcp-cli cmd --server sqlite --input "$file" \
        --prompt "Extraia todos os nomes de empresas, pessoas e locais deste texto: {{input}}" \
        --output "${file%.md}.entities.txt" --raw
done

# Criar relatório abrangente
echo "Criando relatório final..."
cat *.entities.txt | mcp-cli cmd --server sqlite --input - \
    --prompt "Analise estas entidades e identifique as mais frequentemente mencionadas:" \
    --output report.md

Gerenciamento do Histórico de Conversas

Rastreie e gerencie o histórico de conversas:

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

Gerenciamento de Dependências

A CLI usa grupos de dependências opcionais para organização:

• cli: UI de terminal rica, preenchimento automático de comandos e integração de provedores.
• dev: Ferramentas de desenvolvimento e teste.
• wasm: (Reservado para futuro suporte a WebAssembly).
• chuk-mcp: Biblioteca de implementação do protocolo (dependência central).

Instalar extras específicos:

pip install "mcp-cli[cli]"        # Funcionalidades básicas da CLI
pip install "mcp-cli[cli,dev]"    # CLI + ferramentas de desenvolvimento

Guia de Contribuição

Contribuições são bem-vindas! Por favor, siga os seguintes passos:

1. Faça um fork do repositório.
2. Crie uma branch de recurso (git checkout -b feature/amazing-feature).
3. Faça suas alterações (git commit -m 'Adiciona um recurso incrível').
4. Envie para a branch (git push origin feature/amazing-feature).
5. Abra um Pull Request.

Sobre o Protocolo de Contexto de Modelo (MCP)

MCP é um protocolo aberto que padroniza a forma como as aplicações fornecem contexto aos LLMs. O MCP pode ser comparado a uma porta USB-C para aplicações de IA. Assim como o USB-C oferece uma maneira padronizada de conectar dispositivos a uma variedade de periféricos e acessórios, o MCP oferece uma maneira padronizada de conectar modelos de IA a uma variedade de fontes de dados e ferramentas.