mount-cli-template-mcp by mount-ai-in - MCP Server

CLI MCP Server - Generic Template

Ein vielseitiger MCP (Model Context Protocol) Server, der als Vorlage für CLI-basierte Tools dient. Dieser Server ermöglicht es, beliebige Shell-Befehle sicher und flexibel auszuführen, ohne komplexe API-Integrationen implementieren zu müssen.

🎯 Konzept

Anstatt komplizierte API-Integrationen zu entwickeln, nutzt dieser MCP Server einfache CLI-Tools:

Wetter: curl wttr.in/Berlin statt OpenWeather API
Todo Management: Textdateien im todo.txt Format
Bildbearbeitung: ImageMagick Kommandos
Web Scraping: curl, lynx, w3m für Webinhalte

🏗️ Architektur

├── Core System
│   ├── CommandRegistry     # Zentrale Command-Verwaltung
│   ├── ParameterMapper     # Template-Parameter-Substitution
│   ├── SecurityValidator   # Sicherheits- und Validierungssystem
│   └── CommandExecutor     # Robuste Command-Ausführung
├── Example Commands
│   ├── Weather Commands    # wttr.in Integration
│   ├── Todo Commands       # todo.txt Management
│   ├── Image Commands      # ImageMagick Tools
│   └── Web Commands        # curl/lynx Web-Tools
└── MCP Integration        # Standard MCP Server

🚀 Installation

1. Dependencies installieren

npm install

2. Server kompilieren

npm run build

3. MCP Server konfigurieren

Fügen Sie den Server zu Ihrer MCP-Konfiguration hinzu (~/Library/Application Support/Claude/claude_desktop_config.json oder VSCode MCP Settings):

{
  "mcpServers": {
    "cli-server": {
      "command": "node",
      "args": ["/path/to/cli-mcp-server/build/index.js"],
      "disabled": false,
      "alwaysAllow": [],
      "disabledTools": []
    }
  }
}

🛠️ Verfügbare Tools

MCP Tools

execute_cli_command - Führt registrierte CLI-Befehle aus
list_cli_commands - Listet verfügbare Befehle auf
get_cli_command_help - Zeigt detaillierte Hilfe für einen Befehl
validate_cli_command - Validiert Befehl vor Ausführung
get_cli_server_stats - Server-Statistiken

Beispiel Commands

Weather Commands (wttr.in)

# Aktuelles Wetter
execute_cli_command: get_weather mit city="Berlin"

# Detaillierte Wettervorhersage  
execute_cli_command: get_weather_detailed mit city="München" und format="2"

# Wettervorhersage mehrere Tage
execute_cli_command: get_weather_forecast mit city="Hamburg" und lang="de"

# Mondphasen
execute_cli_command: get_weather_moon mit city="Köln"

Todo Commands (todo.txt)

# Todo hinzufügen
execute_cli_command: todo_add mit task="Einkaufen gehen"

# Todos auflisten
execute_cli_command: todo_list

# Todo suchen
execute_cli_command: todo_search mit query="Arbeit"

# Priorisiertes Todo hinzufügen
execute_cli_command: todo_priority_add mit task="Kritischer Bug" und priority="A"

Image Commands (ImageMagick)

# Bildformat konvertieren
execute_cli_command: image_convert mit input="foto.jpg" und output="foto.png"

# Bild verkleinern
execute_cli_command: image_resize mit input="large.jpg" output="small.jpg" width=800 height=600

# Bildinfo anzeigen
execute_cli_command: image_info mit input="bild.jpg"

# Thumbnail erstellen
execute_cli_command: image_thumbnail mit input="foto.png" output="thumb.png" size=150

Web Commands (curl/lynx)

# Webseite fetchen
execute_cli_command: web_fetch mit url="https://httpbin.org/json"

# Text aus Webseite extrahieren
execute_cli_command: web_text mit url="https://example.com"

# HTTP Headers abrufen
execute_cli_command: web_headers mit url="https://github.com"

# Datei herunterladen
execute_cli_command: web_download mit url="https://via.placeholder.com/150" output="bild.png"

# JSON formatiert abrufen
execute_cli_command: web_json mit url="https://api.github.com/users/octocat"

🔧 Eigene Commands erstellen

1. Command Definition

import { CommandDefinition } from '../types/command.js';
import { DEFAULT_SECURITY_CONFIGS } from '../core/security.js';

export const myCommands: CommandDefinition[] = [
  {
    name: 'my_command',
    description: 'Beschreibung des Commands',
    command: 'echo "Hello {name}!"',
    parameters: {
      name: {
        type: 'string',
        required: true,
        description: 'Name für Begrüßung',
        minLength: 1,
        maxLength: 50,
      },
    },
    security: {
      ...DEFAULT_SECURITY_CONFIGS.MODERATE,
      timeoutMs: 5000,
    },
    examples: [
      'my_command with name="World"',
    ],
  },
];

2. Command registrieren

// In src/index.ts
import { myCommands } from './commands/my-commands.js';

// In registerExampleCommands()
this.commandRegistry.registerCommands(myCommands);

🛡️ Sicherheitsfeatures

Security Levels

STRICT: Minimale Berechtigungen, nur Lesen erlaubt
MODERATE: Ausgewogene Sicherheit (Standard)
PERMISSIVE: Maximale Flexibilität

Security Konfiguration

security: {
  allowedPaths: ['/safe/directory'],
  deniedPaths: ['/etc', '/usr/bin'],
  timeoutMs: 30000,
  maxRetries: 2,
  requireConfirmation: false,
  allowNetworkAccess: true,
  allowFileWrite: true,
  allowFileRead: true,
}

Automatische Validierung

Parameter-Validierung mit Zod
Shell-Injection-Schutz
Path-Traversal-Schutz
Command-Whitelist
Timeout-Protection

🔄 Parameter-System

Template-Substitution

Commands nutzen {parameter} Platzhalter:

command: 'curl "wttr.in/{city}?format={format}"'

Parameter-Typen

string: Text mit optionalen Constraints
number: Numerische Werte
boolean: true/false Werte
array: Komma-getrennte Listen

Parameter-Validierung

parameters: {
  city: {
    type: 'string',
    required: true,
    description: 'Stadtname',
    minLength: 2,
    maxLength: 50,
    pattern: /^[a-zA-Z\s]+$/,
  },
  format: {
    type: 'string',
    required: false,
    choices: ['1', '2', '3', '4'],
    default: '3',
  },
}

🔁 Fehlerbehandlung & Fallbacks

Automatische Retries

security: {
  maxRetries: 3,  // Automatisch wiederholen
  timeoutMs: 30000,
}

Fallback Commands

fallback: {
  command: 'curl "wttr.in/?format=3"',  // Alternative bei Fehler
  message: 'Using default location weather',
  skipOnError: false,
}

Error Types

VALIDATION_ERROR: Parameter-Validierung fehlgeschlagen
SECURITY_ERROR: Sicherheitsrichtlinien verletzt
EXECUTION_ERROR: Command-Ausführung fehlgeschlagen
TIMEOUT_ERROR: Command-Timeout erreicht
PERMISSION_ERROR: Fehlende Berechtigungen
NOT_FOUND_ERROR: Command nicht gefunden

📊 Beispiel-Verwendung

1. Wetter abrufen

# MCP Tool aufrufen
execute_cli_command:
  command: "get_weather"
  parameters:
    city: "Berlin"

# Ausgeführter Befehl: curl -s "wttr.in/Berlin?format=3"
# Ergebnis: "🌤️  +8°C"

2. Todo Management

# Todo hinzufügen
execute_cli_command:
  command: "todo_add"
  parameters:
    task: "Meeting um 14:00"
    file: "work-todos.txt"

# Todos auflisten
execute_cli_command:
  command: "todo_list"
  parameters:
    file: "work-todos.txt"

3. Bildbearbeitung

# Bild konvertieren und verkleinern
execute_cli_command:
  command: "image_resize"
  parameters:
    input: "holiday-photo.jpg"
    output: "holiday-thumb.jpg"
    width: 200
    height: 150

🧪 Testing

Server lokal testen

# Server direkt ausführen
node build/index.js

# Mit Input/Output Test
echo '{"method": "tools/list"}' | node build/index.js

Command validieren

execute_cli_command:
  command: "validate_cli_command"
  parameters:
    command: "get_weather"
    parameters:
      city: "Berlin"

🎨 Anpassung & Erweiterung

Neue Command-Kategorien

Datei erstellen: src/commands/new-category.ts
Commands implementieren mit CommandDefinition[]
In index.ts registrieren
Neu kompilieren: npm run build

Erweiterte Features

Streaming Commands: Lange laufende Prozesse
Interaktive Commands: Mit Benutzer-Feedback
Command-Pipelines: Verkettung mehrerer Commands
Custom Security Policies: Spezielle Sicherheitsregeln

📝 Entwicklung

Build & Development

npm run build    # Kompilieren
npm run dev      # Development Build
npm run clean    # Build-Ordner löschen
npm run lint     # Code-Linting

Projektstruktur

src/
├── types/
│   └── command.ts          # TypeScript Interfaces
├── core/
│   ├── command-registry.ts # Command Management
│   ├── parameter-mapper.ts # Parameter Processing
│   ├── security.ts         # Security System
│   └── executor.ts         # Command Execution
├── commands/
│   ├── weather.ts         # Weather Commands
│   ├── todo.ts           # Todo Commands
│   ├── image.ts          # Image Commands
│   └── web.ts            # Web Commands
└── index.ts              # MCP Server Entry Point

🤝 Beitrag & Lizenz

Dieses Projekt dient als Vorlage für eigene CLI-basierte MCP Server.

Lizenz: MIT

Beiträge: Willkommen! Erstellen Sie Issues oder Pull Requests für Verbesserungen.

🎉 Viel Erfolg mit Ihrem CLI MCP Server!

Dieser Server zeigt, wie einfach es ist, bestehende CLI-Tools über MCP verfügbar zu machen, ohne komplexe API-Integrationen entwickeln zu müssen.