Json Logs MCP Server

🚀 JSON Logs MCP Server

Model Context Protocol (MCP)サーバーで、Claude Desktop（または任意のMCPクライアント）がJSON形式のログファイルを読み取り、分析できるようになります。このサーバーは、構造化されたログデータの検索、フィルタリング、集計、分析のためのツールを提供します。

✨ 主な機能

• 📁 ログファイルの閲覧 - JSON形式のログファイルを一覧表示し、読み取ります。
• 🔍 検索とフィルタリング - レベル、モジュール、関数、メッセージ内容、時間範囲でログをクエリします。
• 📊 データの集計 - さまざまな基準でログをグループ化し、分析します。
• 📈 統計情報 - ログデータに関する包括的な統計情報を取得します。
• 🚀 高速かつ効率的 - 大規模なログファイルの処理に最適化されています。

📦 インストール

1. このリポジトリをクローンします。

git clone https://github.com/mfreeman451/json-logs-mcp-server.git
cd json-logs-mcp-server

2. 仮想環境を作成します。

python3 -m venv .venv
source .venv/bin/activate  # Windowsの場合: .venv\Scripts\activate

3. パッケージをインストールします。

pip install -e .

4. ラッパースクリプトを作成します。

cat > run-json-logs-server.sh << 'EOF'
#!/bin/bash
cd "$(dirname "$0")"
source .venv/bin/activate
exec python json_logs_mcp_server.py
EOF
chmod +x run-json-logs-server.sh

📚 ドキュメント

ログディレクトリの設定

デフォルトでは、サーバーは実行場所を基準とした./logsディレクトリ内のログを探します。これは、環境変数を設定するか、コードを編集することで変更できます。

オプション1: 環境変数

export MCP_JSON_LOGS_DIR="/path/to/your/logs"

Claude Desktopの設定

サーバーをClaude Desktopの設定ファイルに追加します。

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "json-logs": {
      "command": "/absolute/path/to/run-json-logs-server.sh",
      "args": [],
      "env": {
        "MCP_JSON_LOGS_DIR": "/path/to/your/logs"
      }
    }
  }
}

重要: ラッパースクリプトの絶対パスを使用してください。

ログ形式

サーバーは、1行に1つのJSONオブジェクトが含まれるJSONログファイルを期待しています。各ログエントリには、以下のフィールドが含まれている必要があります。

{
  "timestamp": "2024-01-15T10:30:45.123456",
  "level": "INFO",
  "message": "User authentication successful",
  "module": "auth.handler",
  "function": "authenticate_user",
  "line": 42
}

必須フィールド

• timestamp - ISO形式のタイムスタンプ
• level - ログレベル (DEBUG, INFO, WARNING, ERROR, CRITICAL)
• message - ログメッセージ
• module - モジュール名
• function - 関数名
• line - 行番号

サンプルログファイル

サーバーをテストするために、以下の内容でexample.logという名前のファイルを作成します。

{"timestamp": "2024-01-15T10:30:45.123456", "level": "INFO", "message": "Application started successfully", "module": "main", "function": "startup", "line": 15}
{"timestamp": "2024-01-15T10:30:46.234567", "level": "DEBUG", "message": "Loading configuration from config.json", "module": "config.loader", "function": "load_config", "line": 42}
{"timestamp": "2024-01-15T10:30:47.345678", "level": "INFO", "message": "Database connection established", "module": "db.connection", "function": "connect", "line": 78}
{"timestamp": "2024-01-15T10:31:02.456789", "level": "WARNING", "message": "Rate limit approaching: 85% of quota used", "module": "api.ratelimit", "function": "check_limits", "line": 156}
{"timestamp": "2024-01-15T10:32:15.567890", "level": "ERROR", "message": "Failed to authenticate user: Invalid credentials", "module": "auth.handler", "function": "authenticate_user", "line": 203}
{"timestamp": "2024-01-15T10:32:16.678901", "level": "INFO", "message": "Retry attempt 1/3 for user authentication", "module": "auth.handler", "function": "retry_auth", "line": 215}
{"timestamp": "2024-01-15T10:33:45.789012", "level": "CRITICAL", "message": "Database connection lost: Connection timeout", "module": "db.connection", "function": "health_check", "line": 92}
{"timestamp": "2024-01-15T10:33:46.890123", "level": "INFO", "message": "Attempting database reconnection", "module": "db.connection", "function": "reconnect", "line": 105}
{"timestamp": "2024-01-15T10:33:48.901234", "level": "INFO", "message": "Database connection restored", "module": "db.connection", "function": "reconnect", "line": 112}
{"timestamp": "2024-01-15T10:35:22.012345", "level": "DEBUG", "message": "Cache hit for key: user_session_abc123", "module": "cache.manager", "function": "get", "line": 67}

Pythonロガーの設定例

必要な形式で出力するようにPythonロガーを設定する方法は次のとおりです。

import logging
import json
from datetime import datetime

class JSONFormatter(logging.Formatter):
    def format(self, record):
        log_obj = {
            "timestamp": datetime.fromtimestamp(record.created).isoformat(),
            "level": record.levelname,
            "message": record.getMessage(),
            "module": record.module,
            "function": record.funcName,
            "line": record.lineno
        }
        return json.dumps(log_obj)

# ロガーを設定
logger = logging.getLogger()
handler = logging.FileHandler('app.log')
handler.setFormatter(JSONFormatter())
logger.addHandler(handler)
logger.setLevel(logging.INFO)

# 例の使用方法
logger.info("Application started")
logger.error("Something went wrong")

利用可能なツール

1. list_log_files

すべての利用可能なログファイルとそのメタデータを一覧表示します。

Claudeでの使用例

• "List all log files"
• "Show me available logs"

2. query_logs

ログエントリを検索およびフィルタリングします。

パラメータ

• files - 検索するファイルのリスト（オプション、デフォルトはすべて）
• level - ログレベルでフィルタリング
• module - モジュール名でフィルタリング
• function - 関数名でフィルタリング
• message_contains - メッセージ内容で検索
• start_time - 開始時間フィルター（ISO形式）
• end_time - 終了時間フィルター（ISO形式）
• limit - 最大結果数（デフォルト: 100）

Claudeでの使用例

• "Show me all ERROR logs from today"
• "Find logs containing 'database connection'"
• "Show errors from the auth module in the last hour"
• "Search for authentication failures"

3. aggregate_logs

指定された基準でログデータを集計します。

パラメータ

• files - 分析するファイル（オプション）
• group_by - グループ化の基準: "level", "module", "function", または "hour"

Claudeでの使用例

• "Group logs by level"
• "Show me which modules generate the most logs"
• "Analyze log distribution by hour"
• "What's the breakdown of log levels?"

4. get_log_stats

ログファイルに関する包括的な統計情報を取得します。

Claudeでの使用例

• "Show me log statistics"
• "What's the overall summary of my logs?"
• "How many errors do I have total?"

💻 使用例

設定が完了すると、Claude Desktopを通じてログと対話できます。

例1: エラーの検索

You: "Show me all ERROR and CRITICAL logs from the last hour"
Claude: I'll search for ERROR and CRITICAL level logs from the last hour...
[Uses query_logs tool with level and time filters]

例2: パターンの分析

You: "Which module is generating the most warnings?"
Claude: Let me analyze the distribution of WARNING logs by module...
[Uses query_logs with level filter, then aggregate_logs grouped by module]

例3: 問題のデバッグ

You: "Find all database connection errors and show me what happened right before them"
Claude: I'll search for database connection errors and their context...
[Uses query_logs to find specific errors and surrounding log entries]

スタンドアロンでの実行

サーバーをスタンドアロンで実行してテストすることもできます（MCP Inspectorまたは他のMCPクライアント）。

# With stdio transport (default)
python json_logs_mcp_server.py

トラブルシューティング

サーバーが起動しない場合

• Python 3.8以上がインストールされていることを確認します: python3 --version
• すべての依存関係がインストールされていることを確認します: pip install -e .
• ログディレクトリが存在し、.logファイルが含まれていることを確認します。

"spawn python ENOENT"エラーの場合

• 設定でpythonの代わりにpython3を使用します。
• ラッパースクリプトの完全な絶対パスを使用します。
• ラッパースクリプトが実行可能であることを確認します: chmod +x run-json-logs-server.sh

"Module not found"エラーの場合

• 仮想環境をアクティブ化するラッパースクリプトを使用していることを確認します。
• 依存関係が仮想環境にインストールされていることを確認します: source .venv/bin/activate && pip list
• 依存関係を再インストールします: pip install -e .

ログが見つからない場合

• 設定されたディレクトリにログファイルが存在することを確認します。
• ログファイルが.log拡張子を持っていることを確認します（*.log*に一致するファイルが検索されます）。
• ログファイルが正しいJSON形式（1行に1つのJSONオブジェクト）であることを確認します。
• 上記のサンプルログファイルを使用して試してみます。

Claudeにツールが表示されない場合

• 設定を変更した後、Claude Desktopを再起動します。
• Claude Desktopの"Connect Apps"セクションを確認します。
• Claudeの開発者コンソールでエラーメッセージを探します。
• ClaudeのUIでサーバーが"Connected"と表示されていることを確認します。

デバッグのヒント

• サーバーを手動で実行して、エラーメッセージを確認します: ./run-json-logs-server.sh
• サーバーの出力を確認します: stdio経由で実行する場合、診断メッセージはstderrに表示されます。
• まず、上記のサンプルデータを使用して簡単なログファイルでテストします。
• JSON形式を確認します: 各行はすべての必須フィールドを持つ有効なJSONでなければなりません。

🔧 技術詳細

• サーバーはログファイルを必要に応じてロードし、一度にすべてをロードするわけではありません。
• 大規模なログファイル（>100MB）の処理には少し時間がかかる場合があります。
• クエリでlimitパラメータを使用して、結果のサイズを制御します。
• パフォーマンスを維持するために、ログファイルのローテーションを検討してください。

🤝 コントリビューション

コントリビューションは大歓迎です！ぜひプルリクエストを送信してください。

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。