Home
Login

Ferramenta de linha de comando poderosa para o Protocolo de Contexto de Modelo (MCP)

NOASSERTIONPython 1.4kchrishayukmcp-cli Last Updated: 2025-07-02

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.

Star History Chart