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 ツールとして使用することも、Cursor などの互換性のあるクライアントに MCP サーバーを統合し、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）に置き換えてください。

   # Hatch 環境を使用する場合：
   hatch run pip uninstall log-analyzer-mcp -y && hatch run pip install dist/log_analyzer_mcp-<version>-py3-none-any.whl
   
   # その他の仮想環境の場合：
   # pip uninstall log-analyzer-mcp -y # （以前にインストールしている場合）
   # pip install dist/log_analyzer_mcp-<version>-py3-none-any.whl
   

   Cursor などの IDE で MCP サーバーの変更を反映するには、IDE でサーバーを手動で再読み込みする必要がある場合があります。詳しくは開発者ガイドを参照してください。

はじめに：Log Analyzer MCP の使用

Log Analyzer MCP の使用方法は、主に次の 2 通りです。

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 は venv 内の Python 実行ファイルを実行するツールです
         "args": [
           "log-analyzer-mcp" // PyPI から最新バージョンを取得して実行します
           // または、特定のバージョンを指定する場合："log-analyzer-mcp==0.2.0"
         ],
         "env": {
           "PYTHONUNBUFFERED": "1",
           "PYTHONIOENCODING": "utf-8",
           "MCP_LOG_LEVEL": "INFO", // 本番環境での使用を推奨します
           // "MCP_LOG_FILE": "/path/to/your/logs/mcp/log_analyzer_mcp_server.log", // 任意
           // --- 環境変数で Log Analyzer 固有の設定を行います ---
           // これらはサーバーが使用する分析エンジンに渡されます。
           // 例："LOG_DIRECTORIES": "[\"/path/to/your/app/logs\"]",
           // 例："LOG_PATTERNS_ERROR": "[\"Exception:.*\"]"
           // （すべてのオプションについては（近日公開予定の）docs/configuration.md を参照してください）
         }
       }
       // ここに他の MCP サーバーを追加できます
     }
   }
   

   注意：

   • プレースホルダーのパスを置き換え、設定オプションと環境変数の詳細については、はじめに、（近日公開予定の）設定ガイド、および開発者ガイドを参照してください。
   • 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 のもとでライセンスされています。詳細は LICENSE.md をご覧ください。