log_analyzer_mcp - Analyze Log files via MCP

Log Analyzer MCP

概览：轻松分析日志

Log Analyzer MCP 是一款功能强大的 Python 工具包，旨在简化你与日志文件交互的方式。无论你是在调试复杂应用、监控测试运行，还是只是想弄清楚冗长的日志输出，这款工具都能提供命令行界面（CLI）和 Model-Context-Protocol（MCP）服务，帮助你快速、高效地找到所需信息。

为什么使用 Log Analyzer MCP？

• 简化日志分析： 通过灵活的解析、高级筛选（基于时间、内容和位置）以及可配置的上下文显示，去除无关信息。
• 融入你的工作流： 可将其用作独立的 loganalyzer CLI 工具进行脚本编写和直接分析，也可将 MCP 服务与 Cursor 等兼容客户端集成，获得 AI 辅助体验。
• 可扩展且可配置： 定义自定义日志来源、模式和搜索范围，以满足你的特定分析需求。

主要功能

• 核心日志分析引擎： 强大的后端，可解析和搜索各种日志格式。
• loganalyzer CLI： 直观的命令行工具，可直接与日志交互。
• MCP 服务： 向 MCP 客户端提供日志分析功能，包括：
  • 测试日志摘要（analyze_tests）。
  • 以不同详细程度执行测试运行。
  • 针对性地运行单元测试（run_unit_test）。
  • 按需生成代码覆盖率报告（create_coverage_report）。
  • 高级日志搜索：所有记录、按时间搜索、首尾 N 条记录。
• Hatch 集成： 便于开发、测试和依赖项管理。

安装

可从 PyPI 安装此软件包（发布后），也可直接从本地构建版本安装，以用于开发。

从 PyPI 安装（推荐用户使用）

软件包发布到 PyPI 后即可安装。

pip install log-analyzer-mcp

这将安装 loganalyzer CLI 工具，并提供 MCP 服务包供集成使用。

从本地构建版本安装（供开发者或测试使用）

如果你已克隆此代码库，并希望使用本地修改：

1. 确保已安装 Hatch。（参见开发者指南）

2. 构建软件包：

   hatch build
   

   这会在 dist/ 目录中生成 wheel 和 sdist 软件包。

3. 将本地构建版本安装到 Hatch 环境（或任何其他虚拟环境）中： 将 <version> 替换为生成的 wheel 文件中的实际版本号（例如，0.2.7）。

   # If using Hatch environment:
   hatch run pip uninstall log-analyzer-mcp -y && hatch run pip install dist/log_analyzer_mcp-<version>-py3-none-any.whl
   
   # For other virtual environments:
   # pip uninstall log-analyzer-mcp -y # (If previously installed)
   # pip install dist/log_analyzer_mcp-<version>-py3-none-any.whl
   

   对于 Cursor 等 IDE，要让其加载 MCP 服务的更改，你可能需要在 IDE 中手动重新加载服务。详情参见开发者指南。

入门：使用 Log Analyzer MCP

使用 Log Analyzer MCP 主要有两种方式：

1. 作为命令行工具（loganalyzer）：

   • 适合直接分析、编写脚本或快速检查。
   • 需要 Python 3.9+。
   • 安装方法请参阅上文的安装部分。
   • 详细用法请参阅 CLI 使用指南（即将推出）或 CLI 命令 API 参考。

2. 作为 MCP 服务（例如，与 Cursor 配合使用）：

   • 将日志分析功能直接集成到 AI 辅助开发环境中。
   • 安装方法请参阅安装部分。安装软件包时会一并安装 MCP 服务组件。
   • 有关如何配置 Cursor 等客户端以及运行服务的详细信息，请参阅下文的配置和运行 MCP 服务以及开发者指南。

配置和运行 MCP 服务

配置

Log Analyzer MCP（CLI 和服务）的配置主要通过环境变量或项目根目录中的 .env 文件完成。

• 环境变量： 在运行工具或服务的环境中设置 LOG_DIRECTORIES、LOG_PATTERNS_ERROR、LOG_CONTEXT_LINES_BEFORE、LOG_CONTEXT_LINES_AFTER 等变量。
• .env 文件： 复制 .env.template 创建 .env 文件（此模板文件需要创建并添加到代码库中），然后自定义其中的值。

有关所有配置选项及其用法的完整列表，请参阅**（即将推出的配置指南**。 （注意：应创建 .env.template 文件并将其添加到代码库中，为用户提供起点。）

运行 MCP 服务

MCP 服务可以通过多种方式启动：

1. 通过 MCP 客户端（例如 Cursor）： 配置客户端以启动 log-analyzer-mcp 可执行文件（通常使用 uvx 之类的辅助工具）。这是集成该服务的常见方式。

   客户端配置示例（例如，在 .cursor/mcp.json 中）：

   {
     "mcpServers": {
       "log_analyzer_mcp_server_prod": {
         "command": "uvx", // uvx is a tool to run python executables from venvs
         "args": [
           "log-analyzer-mcp" // Fetches and runs the latest version from PyPI
           // Or, for a specific version: "log-analyzer-mcp==0.2.0"
         ],
         "env": {
           "PYTHONUNBUFFERED": "1",
           "PYTHONIOENCODING": "utf-8",
           "MCP_LOG_LEVEL": "INFO", // Recommended for production
           // "MCP_LOG_FILE": "/path/to/your/logs/mcp/log_analyzer_mcp_server.log", // Optional
           // --- Configure Log Analyzer specific settings via environment variables ---
           // These are passed to the analysis engine used by the server.
           // Example: "LOG_DIRECTORIES": "[\"/path/to/your/app/logs\"]",
           // Example: "LOG_PATTERNS_ERROR": "[\"Exception:.*\"]"
           // (Refer to the (Upcoming) docs/configuration.md for all options)
         }
       }
       // You can add other MCP servers here
     }
   }
   

   说明：

   • 替换占位路径，并参阅 入门指南、（即将推出）配置指南 和 开发者指南，了解更多配置选项和环境变量信息。
   • PyPI 上的实际软件包名称为 log-analyzer-mcp。

2. 直接运行（用于开发/测试）： 如有需要，可以使用入口点直接运行服务。安装后可使用 log-analyzer-mcp 命令：

   log-analyzer-mcp --transport http --port 8080
   # 或使用 stdio 传输
   # log-analyzer-mcp --transport stdio
   

   如需了解更多选项，请参阅 log-analyzer-mcp --help。开发时，也常使用 pyproject.toml 中定义的 Hatch 脚本，或采用开发者指南中介绍的方法。

文档

• API 参考： MCP 服务工具和 CLI 命令的详细参考。
• 入门指南： 面向用户和集成者。本指南提供概述。
• 开发者指南： 面向贡献者，涵盖环境设置、构建、详细的测试流程（包括覆盖率检查）和发布指南。
• （即将推出）配置指南： 详细说明所有 .env 和环境变量设置。（此文档尚待创建。）
• （即将推出）CLI 使用指南： 全面介绍所有 loganalyzer 命令和选项。（此文档尚待创建。）
• .env.template： 用于配置环境变量的模板文件。（此文件尚待创建并添加到代码库。）
• 重构计划： 项目持续演进的技术细节。

测试

如需运行测试并生成覆盖率报告，请参阅开发者指南中的完整测试指南。本节介绍如何使用 hatch test、运行覆盖率测试、生成 HTML 报告，以及指定目标测试。

贡献

欢迎贡献！有关如何设置环境、测试和参与贡献的指南，请参阅 CONTRIBUTING.md 和开发者指南。

许可证

Log Analyzer MCP 根据附加 Commons Clause 的 MIT 许可证授权。详情请参阅 LICENSE.md。