log-mcp-python

Servicio de consulta de logs remotos basado en MCP (Model Context Protocol), implementado en Python.

Este proyecto es un rediseño e implementación del Log-MCP de código abierto (versión Java): expone una interfaz de herramientas MCP completamente idéntica (JSON-RPC 2.0, modos de transporte STDIO / HTTP), mientras que internamente se ha reestructurado la arquitectura siguiendo las convenciones de Python, y se ha abstraído la «forma de obtener logs» como canales de ejecución enchufables — los comandos específicos para obtener logs son construidos uniformemente por el servicio, solo los canales que ejecutan los comandos son variados.

Características

• Compatibilidad de interfaz: las mismas 5 herramientas MCP que la versión Java original (search_logs / tail_logs / read_log_file / list_log_files / list_servers), con contratos de entrada y salida alineados.

• Canales de ejecución enchufables:

  • ssh — conexión directa con clave privada SSH (paramiko, con pool de conexiones y reconexión automática)

  • pyinfra — reutiliza los activos de hosts pyinfra existentes (soporta especificaciones de host como @local, root@host:22)

  • local — ejecución local (desarrollo / pruebas)

• Construcción unificada de comandos: todas las operaciones de logs se normalizan en un comando shell que se ejecuta en la máquina de destino (grep -n -A -B / tail -n / sed -n / find), desacoplado del canal de ejecución — para añadir un nuevo canal solo hay que implementar CommandExecutor.execute().

• Seguridad: validación de parámetros, validación de rutas relativas, detección de caracteres peligrosos, y escape de comillas simples en shell consistente con la versión original.

• Dependencias ligeras: el núcleo solo depende de paramiko; pyinfra es una dependencia opcional, que solo se instala cuando se usa el canal pyinfra.

Related MCP server: jakubs-mcp-tools

Arquitectura

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）

El diseño detallado se encuentra en docs/DESIGN.md.

Instalación

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

Configuración

Consulta config.example.json. Es compatible con la estructura del config.json de la versión Java original, con las siguientes extensiones:

• Cada servidor especifica de forma independiente su canal de ejecución mediante el campo connector: ssh (predeterminado) / pyinfra / local

• El canal pyinfra admite pyinfraHost (especificación completa del host, como root@192.168.5.20:22 o @local) y pyinfraData (datos del host que se pasan a pyinfra, como ssh_key)

• Las cadenas admiten marcadores de posición de variables de entorno ${VAR} (si no están definidas, se conservan tal cual)

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

Descripción de los campos clave:

Ejecución

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

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

También se admiten variables de entorno: LOG_CONFIG, TRANSPORT_MODE, SERVER_PORT.

Conexión con un cliente MCP (ejemplo con modo HTTP):

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

Conexión en modo STDIO:

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

Herramientas MCP

Ejemplo de llamada (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"]}}}'

Pruebas

python -m pytest tests/ -q

Cobertura de pruebas: validación de parámetros/rutas, escape de shell, construcción de comandos, análisis de salida de grep (incluido análisis determinista de archivos conocidos), manejo del protocolo JSON-RPC, y pruebas de integración de extremo a extremo para los canales local / pyinfra(@local) (100 casos en total).

Licencia

Apache-2.0