MCP-CLI: Kommandozeilen-Schnittstelle für das Modell-Kontext-Protokoll

Projektübersicht

MCP-CLI ist ein leistungsstarkes und funktionsreiches Kommandozeilen-Schnittstellen-Tool (CLI), das speziell für die Interaktion mit Servern entwickelt wurde, die das Modell-Kontext-Protokoll (Model Context Protocol, MCP) implementieren. Durch die Integration der CHUK-MCP-Protokollbibliothek bietet dieses Tool Benutzern eine nahtlose Kommunikationsfähigkeit mit großen Sprachmodellen (LLMs).

Dieser Client unterstützt die Werkzeugnutzung, Konversationsverwaltung und verschiedene Betriebsmodi. Die Kernprotokollimplementierung wurde in ein separates Paket ausgelagert, wodurch sich die CLI auf die Bereitstellung einer reichhaltigen Benutzererfahrung konzentrieren kann, während die Protokollbibliothek die Kommunikationsschicht übernimmt.

Kernfunktionen

🔄 Mehrere Betriebsmodi

• Chat-Modus (Chat Mode): Eine dialogorientierte Oberfläche, die direkte LLM-Interaktion und automatisierte Werkzeugnutzung unterstützt.
• Interaktiver Modus (Interactive Mode): Eine befehlsgesteuerte Oberfläche für direkte Serveroperationen.
• Befehlsmodus (Command Mode): Ein Unix-freundlicher Modus, der skriptbasierte Automatisierung und Pipeline-Operationen unterstützt.
• Direkte Befehle: Ausführung einzelner Befehle, ohne in den interaktiven Modus wechseln zu müssen.

🌐 Unterstützung mehrerer Anbieter

• OpenAI-Integration: Unterstützt Modelle wie gpt-4o-mini, gpt-4o, gpt-4-turbo und weitere.
• Ollama-Integration: Unterstützt lokale Modelle wie llama3.2, qwen2.5-coder und weitere.
• Erweiterbare Architektur: Ermöglicht das Hinzufügen weiterer Anbieter.

🛠️ Leistungsstarkes Werkzeugsystem

• Automatische Erkennung von vom Server bereitgestellten Werkzeugen.
• Server-bewusste Werkzeugausführung.
• Verfolgung und Analyse des Werkzeugaufrufverlaufs.
• Unterstützung komplexer mehrstufiger Werkzeugketten.

💬 Erweiterte Konversationsverwaltung

• Vollständige Verfolgung des Konversationsverlaufs.
• Unterstützung für das Filtern und Anzeigen spezifischer Nachrichtenbereiche.
• JSON-Exportfunktion für Debugging oder Analyse.
• Konversationskomprimierungsfunktion zur Reduzierung des Token-Verbrauchs.

🎨 Umfangreiche Benutzererfahrung

• Kontextsensitive Befehls-Autovervollständigung.
• Farbige formatierte Konsolenausgabe.
• Fortschrittsanzeige für langlaufende Operationen.
• Detaillierte Hilfe und Dokumentation.

🔧 Zuverlässiges Ressourcenmanagement

• Ordnungsgemäße Bereinigung asynchroner E/A-Ressourcen.
• Elegante Fehlerbehandlung.
• Saubere Terminalwiederherstellung.
• Unterstützung mehrerer gleichzeitiger Serververbindungen.

Systemanforderungen

• Python 3.11 oder höher.
• Für OpenAI: Ein gültiger API-Schlüssel muss in der Umgebungsvariable OPENAI_API_KEY gesetzt sein.
• Für Ollama: Eine lokale Ollama-Installation ist erforderlich.
• Server-Konfigurationsdatei (Standard: server_config.json).
• CHUK-MCP Protokollbibliothek.

Installationsmethoden

Standardinstallation

# Repository klonen
git clone https://github.com/chrishayuk/mcp-cli
cd mcp-cli

# Paket und Entwicklungsabhängigkeiten installieren
pip install -e ".[cli,dev]"

# CLI ausführen
mcp-cli --help

Verwendung von UV zur Abhängigkeitsverwaltung

# UV installieren (falls nicht bereits installiert)
pip install uv

# Abhängigkeiten installieren
uv sync --reinstall

# Mit UV ausführen
uv run mcp-cli --help

Benutzerhandbuch

Globale Optionen

Alle Befehle unterstützen die folgenden globalen Optionen:

• --server: Gibt den/die zu verbindenden Server an (mehrere Server durch Kommas getrennt).
• --config-file: Pfad zur Server-Konfigurationsdatei (Standard: server_config.json).
• --provider: Der zu verwendende LLM-Anbieter (openai oder ollama, Standard: openai).
• --model: Das zu verwendende spezifische Modell (abhängig von den Standardwerten des Anbieters).
• --disable-filesystem: Deaktiviert den Dateisystemzugriff (Standard: true).

Chat-Modus

Der Chat-Modus bietet eine dialogorientierte Oberfläche für LLMs, die bei Bedarf automatisch verfügbare Werkzeuge verwendet:

# Basis-Chat-Modus
mcp-cli chat --server sqlite

# Anbieter und Modell angeben
mcp-cli chat --server sqlite --provider openai --model gpt-4o
mcp-cli chat --server sqlite --provider ollama --model llama3.2

Chat-Modus Slash-Befehle

Im Chat-Modus können die folgenden Slash-Befehle verwendet werden:

Hilfebefehle:

• /help: Zeigt verfügbare Befehle an.
• /help <command>: Zeigt detaillierte Hilfe für einen bestimmten Befehl an.
• /quickhelp oder /qh: Zeigt eine schnelle Referenz für häufig verwendete Befehle an.

Werkzeugbezogen:

• /tools: Zeigt alle verfügbaren Werkzeuge und deren Serverinformationen an.
• /tools --all: Zeigt detaillierte Werkzeuginformationen einschließlich Parameter an.
• /tools --raw: Zeigt die Rohdefinitionen der Werkzeuge an.
• /toolhistory oder /th: Zeigt den Werkzeugaufrufverlauf in der aktuellen Sitzung an.

Konversationsverwaltung:

• /conversation oder /ch: Zeigt den Konversationsverlauf an.
• /save <filename>: Speichert den Konversationsverlauf in einer JSON-Datei.
• /compact: Komprimiert den Konversationsverlauf zu einer Zusammenfassung.

Oberflächensteuerung:

• /cls: Löscht den Bildschirm, behält aber den Konversationsverlauf bei.
• /clear: Löscht den Bildschirm und den Konversationsverlauf.
• /verbose oder /v: Schaltet zwischen detailliertem und prägnantem Werkzeuganzeigemodus um.

Interaktiver Modus

Der interaktive Modus bietet eine Kommandozeilen-Schnittstelle, die Slash-Befehle für die direkte Serverinteraktion verwendet:

mcp-cli interactive --server sqlite

Interaktiver Modus Befehle

• /ping: Überprüft, ob der Server antwortet.
• /prompts: Listet verfügbare Prompts auf.
• /tools: Listet verfügbare Werkzeuge auf.
• /resources: Listet verfügbare Ressourcen auf.
• /chat: Wechselt in den Chat-Modus.
• /exit oder /quit: Beendet das Programm.

Befehlsmodus

Der Befehlsmodus bietet eine Unix-freundliche Schnittstelle für Automatisierung und Pipeline-Integration:

mcp-cli cmd --server sqlite [options]

Befehlsmodus Optionen

• --input: Pfad zur Eingabedatei (verwenden Sie - für stdin).
• --output: Pfad zur Ausgabedatei (verwenden Sie - für stdout, Standard).
• --prompt: Prompt-Vorlage (verwenden Sie {{input}} als Eingabeplatzhalter).
• --raw: Gibt den Rohtext ohne Formatierung aus.
• --tool: Ruft ein bestimmtes Werkzeug direkt auf.
• --tool-args: JSON-Parameter für den Werkzeugaufruf.
• --system-prompt: Benutzerdefinierter System-Prompt.

Befehlsmodus Beispiele

# Dokument zusammenfassen
mcp-cli cmd --server sqlite --input document.md --prompt "Fasse dies zusammen: {{input}}" --output summary.md

# stdin verarbeiten und nach stdout ausgeben
cat document.md | mcp-cli cmd --server sqlite --input - --prompt "Extrahiere Schlüsselpunkte: {{input}}"

# Werkzeug direkt aufrufen
mcp-cli cmd --server sqlite --tool list_tables --raw
mcp-cli cmd --server sqlite --tool read_query --tool-args '{"query": "SELECT COUNT(*) FROM users"}'

# Stapelverarbeitung
ls *.md | parallel mcp-cli cmd --server sqlite --input {} --output {}.summary.md --prompt "Fasse zusammen: {{input}}"

Direkte Befehle

Führen Sie einzelne Befehle aus, ohne in den interaktiven Modus zu wechseln:

# Verfügbare Werkzeuge auflisten
mcp-cli tools list --server sqlite

# Bestimmtes Werkzeug aufrufen
mcp-cli tools call --server sqlite

# Verfügbare Prompts auflisten
mcp-cli prompts list --server sqlite

# Serververbindung prüfen
mcp-cli ping --server sqlite

# Verfügbare Ressourcen auflisten
mcp-cli resources list --server sqlite

Konfigurationsdatei

Erstellen Sie die Datei server_config.json, um Server zu konfigurieren:

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

Projektstruktur

src/
├── mcp_cli/
│   ├── chat/                    # Implementierung des Chat-Modus
│   │   ├── commands/            # Chat-Slash-Befehle
│   │   │   ├── __init__.py      # Befehlsregistrierungssystem
│   │   │   ├── conversation.py  # Konversationsverwaltung
│   │   │   ├── help.py          # Hilfebefehle
│   │   │   ├── tools.py         # Werkzeugbefehle
│   │   │   └── ...
│   │   ├── chat_context.py      # Verwaltung des Chat-Sitzungsstatus
│   │   ├── chat_handler.py      # Haupt-Chat-Loop-Handler
│   │   ├── command_completer.py # Befehls-Autovervollständigung
│   │   └── ui_manager.py        # Benutzeroberfläche
│   ├── commands/                # CLI-Befehle
│   │   ├── chat.py              # Chat-Befehl
│   │   ├── cmd.py               # Befehlsmodus
│   │   ├── interactive.py       # Interaktiver Modus
│   │   └── ...
│   ├── llm/                     # LLM-Client-Implementierung
│   │   ├── providers/           # Anbieterspezifische Clients
│   │   │   ├── base.py          # Basis-LLM-Client
│   │   │   └── openai_client.py # OpenAI-Implementierung
│   │   └── llm_client.py        # Client-Fabrik
│   ├── ui/                      # Benutzeroberflächenkomponenten
│   │   ├── colors.py            # Farbdefinitionen
│   │   └── ui_helpers.py        # UI-Werkzeuge
│   ├── main.py                  # Haupteinstiegspunkt
│   └── config.py                # Konfigurationslader

Anwendungsbeispiele

Automatische Werkzeugausführung

Im Chat-Modus kann MCP CLI vom Server bereitgestellte Werkzeuge automatisch ausführen:

You: Welche Tabellen sind in der Datenbank verfügbar?
Assistant: Lassen Sie mich das überprüfen.
[Werkzeugaufruf: list_tables]
Ich habe die folgenden Tabellen in der Datenbank gefunden:
- users
- products  
- orders
- categories

You: Wie viele Benutzer haben wir?
Assistant: Ich werde die Datenbank nach dieser Information abfragen.
[Werkzeugaufruf: read_query]
Es gibt 873 Benutzer in der Datenbank.

Automatisierte Skripterstellung

Der Befehlsmodus unterstützt leistungsstarke automatisierte Skripte:

#!/bin/bash
# Beispielskript zur Analyse mehrerer Dokumente

# Alle Markdown-Dateien im aktuellen Verzeichnis verarbeiten
for file in *.md; do
    echo "Verarbeite $file..."
    
    # Zusammenfassung generieren
    mcp-cli cmd --server sqlite --input "$file" \
        --prompt "Fasse dieses Dokument zusammen: {{input}}" \
        --output "${file%.md}.summary.md"
    
    # Entitäten extrahieren
    mcp-cli cmd --server sqlite --input "$file" \
        --prompt "Extrahiere alle Firmennamen, Personen und Orte aus diesem Text: {{input}}" \
        --output "${file%.md}.entities.txt" --raw
done

# Umfassenden Bericht erstellen
echo "Erstelle finalen Bericht..."
cat *.entities.txt | mcp-cli cmd --server sqlite --input - \
    --prompt "Analysiere diese Entitäten und identifiziere die am häufigsten genannten:" \
    --output report.md

Verwaltung des Konversationsverlaufs

Verfolgen und verwalten Sie den Konversationsverlauf:

> /conversation
Konversationsverlauf (12 Nachrichten)
# | Rolle | Inhalt
1 | system | Sie sind ein intelligenter Assistent, der in der Lage ist, ...
2 | user | Welche Tabellen sind in der Datenbank verfügbar?
3 | assistant | Lassen Sie mich das überprüfen.
4 | assistant | [Werkzeugaufruf: list_tables]
...

> /conversation 4
Nachricht #4 (Rolle: assistant)
[Werkzeugaufruf: list_tables]
Werkzeugaufrufe:
1. ID: call_list_tables_12345678, Typ: function, Name: list_tables
Argumente: {}

> /save conversation.json
Konversation gespeichert unter conversation.json

> /compact
Konversationsverlauf mit Zusammenfassung komprimiert.
Zusammenfassung:
Der Benutzer fragte nach Datenbanktabellen, und ich listete die verfügbaren Tabellen auf (users, products, orders, categories). Der Benutzer fragte dann nach der Anzahl der Benutzer, und ich fragte die Datenbank ab, um festzustellen, dass es 873 Benutzer gibt.

Abhängigkeitsverwaltung

Die CLI verwendet optionale Abhängigkeitsgruppen zur Organisation:

• cli: Umfangreiche Terminal-Benutzeroberfläche, Befehls-Autovervollständigung und Anbieterintegration.
• dev: Entwicklungswerkzeuge und Testwerkzeuge.
• wasm: (Für zukünftige WebAssembly-Unterstützung reserviert).
• chuk-mcp: Protokollimplementierungsbibliothek (Kernabhängigkeit).

Installation spezifischer Extras:

pip install "mcp-cli[cli]"        # Basis-CLI-Funktionen
pip install "mcp-cli[cli,dev]"    # CLI + Entwicklungswerkzeuge

Leitfaden für Beiträge

Beiträge sind willkommen! Bitte befolgen Sie diese Schritte:

1. Forken Sie das Repository.
2. Erstellen Sie einen Feature-Branch (git checkout -b feature/amazing-feature).
3. Committen Sie Ihre Änderungen (git commit -m 'Add some amazing feature').
4. Pushen Sie auf den Branch (git push origin feature/amazing-feature).
5. Öffnen Sie einen Pull Request.

Über das Modell-Kontext-Protokoll (MCP)

MCP ist ein offenes Protokoll, das standardisiert, wie Anwendungen LLMs Kontext bereitstellen. Man kann MCP mit einem USB-C-Anschluss für KI-Anwendungen vergleichen. So wie USB-C eine standardisierte Möglichkeit bietet, Geräte mit verschiedenen Peripheriegeräten und Zubehör zu verbinden, bietet MCP eine standardisierte Möglichkeit, KI-Modelle mit verschiedenen Datenquellen und Werkzeugen zu verbinden.