log-mcp-python

Сервис удалённого просмотра логов на основе MCP (Model Context Protocol), реализация на Python.

Этот проект является переработкой и реализацией открытого Log-MCP (Java-версии): наружу предоставляется полностью совместимый интерфейс MCP-инструментов (JSON-RPC 2.0, два режима передачи: STDIO / HTTP), внутри архитектура переработана в соответствии с Python-стилем, а «способ получения логов» абстрагирован в подключаемый канал выполнения — конкретные команды для получения логов всегда строит сервис, разнообразны только каналы выполнения команд.

Возможности

• Совместимость интерфейса: 5 MCP-инструментов, идентичных оригинальной Java-версии (search_logs / tail_logs / read_log_file / list_log_files / list_servers), контракты ввода-вывода согласованы.

• Подключаемые каналы выполнения:

  • ssh — прямое подключение по SSH-ключу (paramiko, с пулом соединений и автоматическим переподключением)

  • pyinfra — переиспользование существующих активов хостов pyinfra (поддержка спецификаций хостов, таких как @local, root@host:22)

  • local — локальное выполнение (разработка / тестирование)

• Единое построение команд: все операции с логами сводятся к одному фрагменту shell-команды, выполняемой на целевом хосте (grep -n -A -B / tail -n / sed -n / find), что развязывает с каналом выполнения — для нового канала достаточно реализовать CommandExecutor.execute().

• Безопасность: проверка параметров, проверка относительных путей, обнаружение опасных символов, экранирование одинарных кавычек в shell, как в оригинале.

• Нулевая тяжёлая зависимость: ядро зависит только от paramiko; pyinfra — опциональная зависимость, устанавливается только при использовании канала pyinfra.

Related MCP server: jakubs-mcp-tools

Архитектура

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）

Подробное проектирование см. в docs/DESIGN.md.

Установка

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

Конфигурация

См. config.example.json. Структура совместима с config.json оригинальной Java-версии, с расширениями:

• Для каждого сервера через поле connector независимо указывается канал выполнения: ssh (по умолчанию) / pyinfra / local

• Канал pyinfra поддерживает pyinfraHost (полная спецификация хоста, например root@192.168.5.20:22 или @local) и pyinfraData (данные хоста, передаваемые в pyinfra, например ssh_key)

• Строки поддерживают плейсхолдеры переменных окружения ${VAR} (если не определены, остаются как есть)

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

Описание ключевых полей:

Запуск

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

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

Также поддерживаются переменные окружения: LOG_CONFIG, TRANSPORT_MODE, SERVER_PORT.

Подключение к MCP-клиенту (на примере режима HTTP):

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

Подключение в режиме STDIO:

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

MCP-инструменты

Пример вызова (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"]}}}'

Тестирование

python -m pytest tests/ -q

Покрытие тестами: проверка параметров/путей, экранирование shell, построение команд, разбор вывода grep (включая детерминированный разбор известных файлов), обработка протокола JSON-RPC, а также сквозные интеграционные тесты для каналов local / pyinfra(@local) (всего 100 тестов).

Лицензия

Apache-2.0