log-mcp-python

Auf MCP (Model Context Protocol) basierender Remote-Logabfragedienst, implementiert in Python.

Dieses Projekt ist die Neugestaltung und Neuimplementierung des Open-Source-Projekts Log-MCP (Java-Version): Nach außen hin werden vollständig identische MCP-Tool-Schnittstellen bereitgestellt (JSON-RPC 2.0, STDIO / HTTP als zwei Übertragungsmodi), nach innen wurde die Gesamtarchitektur gemäß Python-Konventionen neu strukturiert, und die „Art der Logabfrage" wurde als steckbarer Ausführungskanal abstrahiert – die konkreten Befehle zum Abrufen von Logs werden einheitlich vom Dienst erstellt, nur die Kanäle zur Befehlsausführung sind vielfältig.

Eigenschaften

• Schnittstellenkompatibilität: Die 5 MCP-Tools der ursprünglichen Java-Version (search_logs / tail_logs / read_log_file / list_log_files / list_servers) mit übereinstimmenden Ein-/Ausgabe-Kontrakten.

• Steckbare Ausführungskanäle:

  • ssh — Direktverbindung per SSH-Private-Key (paramiko, mit Verbindungspool und automatischer Wiederverbindung)

  • pyinfra — Wiederverwendung vorhandener pyinfra-Host-Assets (unterstützt Host-Specs wie @local, root@host:22 usw.)

  • local — Lokale Ausführung (Entwicklung / Tests)

• Einheitliche Befehlserstellung: Alle Logoperationen werden auf ein Shell-Kommando normalisiert, das auf dem Zielrechner ausgeführt wird (grep -n -A -B / tail -n / sed -n / find), entkoppelt vom Ausführungskanal – ein neuer Kanal muss lediglich CommandExecutor.execute() implementieren.

• Sicherheit: Parameterprüfung, Prüfung relativer Pfade, Erkennung gefährlicher Zeichen, Shell-Single-Quote-Escaping wie in der Originalversion.

• Minimale Abhängigkeiten: Der Kern hängt nur von paramiko ab; pyinfra ist eine optionale Abhängigkeit und wird nur installiert, wenn der pyinfra-Kanal verwendet wird.

Related MCP server: jakubs-mcp-tools

Architektur

MCP 客户端（AI 助手 / IDE）
        │  JSON-RPC 2.0
        ▼
mcp/            传输与协议层（stdio_server / http_server / handler）
        ▼
tools.py        5 个工具的声明式定义（名称 + JSON Schema + 处理函数）
        ▼
service/        业务编排层（参数校验 → 文件推导 → 命令构建 → 解析）
        ▼
executors/      可插拔执行通道（ssh_key / pyinfra_exec / local + registry）
        ▼
目标服务器上的 shell 命令（grep / tail / sed / find）

Detailliertes Design siehe docs/DESIGN.md.

Installation

pip install .            # 核心功能（ssh + local 通道）
pip install .[pyinfra]   # 需要 pyinfra 通道时
pip install .[dev]       # 运行测试

Konfiguration

Siehe config.example.json. Die Struktur ist mit der config.json der ursprünglichen Java-Version kompatibel und wurde wie folgt erweitert:

• Jeder Server gibt über das Feld connector unabhängig seinen Ausführungskanal an: ssh (Standard) / pyinfra / local

• Der pyinfra-Kanal unterstützt pyinfraHost (vollständige Host-Spec, z. B. root@192.168.5.20:22 oder @local) und pyinfraData (Host-Daten, die an pyinfra durchgereicht werden, z. B. ssh_key)

• Zeichenketten unterstützen ${VAR}-Umgebungsvariablen-Platzhalter (bleiben unverändert, wenn nicht definiert)

{
  "servers": [
    {
      "name": "ssh-server",
      "connector": "ssh",
      "host": "192.168.5.169",
      "port": 22,
      "username": "root",
      "privateKeyPath": "${SSH_KEY_PATH}",
      "logRootPath": "/home/docker/logs/myapp/",
      "default": true
    },
    {
      "name": "pyinfra-server",
      "connector": "pyinfra",
      "pyinfraHost": "root@192.168.5.20:22",
      "pyinfraData": { "ssh_key": "/root/.ssh/id_rsa" },
      "logRootPath": "/var/logs/app/"
    },
    {
      "name": "dev-local",
      "connector": "local",
      "logRootPath": "/tmp/logs/"
    }
  ],
  "logLevels": ["info", "warn", "error", "debug"],
  "logFilePattern": "{level}/log-{level}-{date}.{seq}.log"
}

Erläuterung der wichtigsten Felder:

Ausführung

# STDIO 模式（MCP 客户端拉起，默认）
log-mcp --config config.json

# HTTP 模式（独立部署，端口默认 8892，路径 / 与 /mcp，健康检查 GET /health）
log-mcp --config config.json --transport http --port 8892

Es werden auch Umgebungsvariablen unterstützt: LOG_CONFIG, TRANSPORT_MODE, SERVER_PORT.

Anbindung an einen MCP-Client (am Beispiel des HTTP-Modus):

{
  "mcpServers": {
    "log-mcp": {
      "url": "http://your-host:8892/mcp"
    }
  }
}

Anbindung im STDIO-Modus:

{
  "mcpServers": {
    "log-mcp": {
      "command": "log-mcp",
      "args": ["--config", "/path/to/config.json"]
    }
  }
}

MCP-Tools

Aufrufbeispiel (HTTP):

curl -s -X POST http://127.0.0.1:8892/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"search_logs","arguments":{"keyword":"ERROR","levels":["error","info"]}}}'

Tests

python -m pytest tests/ -q

Die Tests decken ab: Parameter-/Pfadprüfung, Shell-Escaping, Befehlserstellung, grep-Ausgabe-Parsing (einschließlich deterministischem Parsing bekannter Dateien), JSON-RPC-Protokollverarbeitung sowie End-to-End-Integrationstests für die beiden Kanäle local / pyinfra(@local) (insgesamt 100 Testfälle).

Lizenz

Apache-2.0