Log Detective MCP

Log Detective MCP

他のエージェントが Log Detective の中核的なログ分析ツールを利用できるようにする MCP サーバーです。

このサーバーは Drain3 アルゴリズムを使用してログメッセージをテンプレートにクラスタリングし、代表的なスニペットを抽出します。これにより、大きなログを後続の分析で扱いやすいサイズに縮小できます。

インストール

Python 3.11 以降が必要です。

pip install .

または、uv を使用します。

uv pip install .

使用方法

サーバーの起動

logdetective-mcp

または、直接実行します。

python -m logdetective_mcp.main

MCP クライアントの設定

Claude Code

claude mcp add logdetective -- logdetective-mcp

Claude Desktop

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

{
  "mcpServers": {
    "logdetective": {
      "command": "logdetective-mcp"
    }
  }
}

ツール

extract_log_snippets

Drain3 によるクラスタリングを使用して、代表的なログスニペットを抽出します。このツールはログを論理的なメッセージに分割し、類似するメッセージをクラスタリングして、各クラスタから代表的なスニペットを1つ返します。

ログの内容は、次の3つの方法で指定できます（いずれか1つを必ず使用してください）。

パラメーター	型	説明
log_text	str	直接渡す生のログテキストです。
log_path	str	サーバーのファイルシステム上にあるログファイルのパスです。
log_url	str	ログの内容を取得する HTTP(S) URL です。

オプションのパラメーター：

パラメーター	型	デフォルト	説明
max_clusters	int	8	抽出するスニペットの最大数です。
max_snippet_len	int	2000	スニペットごとの最大文字数です。
skip_patterns	list[str]	null	正規表現パターンのリストです。いずれかのパターンに一致するチャンクは、クラスタリングの前に除外されます。
context	int	0	各スニペットの前後に含める行数です（0～50）。

それぞれ line_number（元のログ内の位置）と text（抽出したスニペットの内容）を持つ Snippet オブジェクトのリストを返します。

extract_python_tracebacks

連鎖した例外を含め、ログから Python のトレースバックを抽出します。

パラメーター	型	デフォルト	説明
max_traceback_len	int	2000	抽出するトレースバックごとの最大文字数です。
skip_patterns	list[str]	null	正規表現パターンのリストです。いずれかのパターンに一致するトレースバックは除外されます。
context	int	0	各トレースバックの前後に含める行数です（0～50）。

両方の抽出ツールで、context は grep の -C と同じ動作をします。指定した前後のログ行数が、取得可能な場合はそれぞれ含まれます。長さの上限は、抽出したスニペットまたはトレースバックに適用されます。コンテキスト行は追加されるため、返される text は上限を超える場合があります。コンテキストが有効な場合、line_number は返された最初の行を指します。0～50 の範囲外の値は拒否されます。

トレースバックが切り詰められる場合、max_traceback_len に余裕があれば、抽出ツールは先頭と末尾を残し、その間にマーカーを付けます。上限がそれより小さい場合は、先頭部分だけを残します。後続のコンテキストは元のトレースバックの後から始まり、省略された中間部分は復元されません。 ログ行が max_snippet_len によってチャンクに分割された場合、コンテキストを追加するときも、選択された各チャンクのテキストはそのまま保持されます。隣接する行が、分割前の長い行全体に置き換わることはありません。コンテキストの境界は、描画されるチャンクから省略された空行も含め、元のソース行に従います。

サイズ制限

ダウンロードしたすべての入力（log_url 経由）は、形式にかかわらず 100 MB に制限されます。ダウンロードはチャンク単位でストリーミングされ、制限を超えるとすぐに中止されます。

log_path 経由で読み込むアーカイブも、展開中に 100 MB の制限が適用されます。

圧縮ファイルのサポート

どちらのツールも、アーカイブされたログファイルを自動的に展開します。対応形式は次のとおりです。

• 単一ファイルの圧縮形式： .gz、.bz2、.xz、.lzma
• アーカイブ： .zip、.tar、.tar.gz、.tar.bz2、.tar.xz

形式はファイル拡張子（または URL のパス）から判定されます。アーカイブに含められるファイルは 1 つだけです。

Zip 爆弾対策として、次の制限を設けています。

• 展開後のサイズは最大 100 MB
• 圧縮率は最大 100:1
• zip／tar ヘッダーに記載されたサイズを事前に確認
• 再帰的な展開は行いません（入れ子のアーカイブは展開されません）

貢献

このリポジトリへのすべての変更は、pre-commit チェックとテストに合格する必要があります。

uv run pytest tests/