Ferramenta de linha de comando poderosa para o Protocolo de Contexto de Modelo (MCP)
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
ouollama
, 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:
- Faça um fork do repositório.
- Crie uma branch de recurso (
git checkout -b feature/amazing-feature
). - Faça suas alterações (
git commit -m 'Adiciona um recurso incrível'
). - Envie para a branch (
git push origin feature/amazing-feature
). - 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.