Nft Log Analyser

🔍 NFT Log Analyzer

Ollama による 100％ローカルの AI 搭載ログ分析。GitHub Issue を自動作成し、データがマシンの外に出ることはありません。

---

できること

任意のログファイルを指定すると、次の処理を行います。

1. ripgrep を使って、500MB 以上のファイルを数秒でスキャン
2. エラーパターンを解析し、繰り返されるイベントを重複排除
3. CrewAI エージェントを介し、ローカル LLM（Ollama + deepseek-r1:14b）で分析
4. 根本原因と修正案を含む、構造化された GitHub Issue を作成
5. 重複をスキップして、リポジトリに Issue を自動で登録

すべての処理はお使いのマシン上でローカルに実行されます。ログの生データがシステムの外に出ることはありません。

---

アーキテクチャ

Claude Desktop / Cursor / LangChain
         ↓  MCP (stdio or HTTP+SSE)
   MCP Log Analyzer Server
         ↓
   ripgrep pre-filter (2-4s on 500MB)
         ↓
   mmap streaming parser + deduplicator
         ↓
   CrewAI agents → Ollama (local LLM)
         ↓
   GitHub Issues API

---

必要条件

要件	バージョン	備考
Python	3.11+	3.14 は未対応
Ollama	最新	brew install ollama
deepseek-r1:14b	—	約 9GB のダウンロード
ripgrep	最新	brew install ripgrep
RAM	最低 16GB	32GB を推奨
macOS	Ventura 13+	Apple Silicon を推奨

---

クイックスタート

1. システム依存関係をインストールする

brew install ollama ripgrep
brew services start ollama
ollama pull deepseek-r1:14b   # ~9GB — start this first

2. クローンして Python 環境をセットアップする

git clone https://github.com/YOUR_ORG/mcp-log-analyzer
cd mcp-log-analyzer

/opt/homebrew/bin/python3.11 -m venv .venv
source .venv/bin/activate

pip install --upgrade pip
pip install mcp "crewai>=0.80.0" crewai-tools langchain-ollama \
    litellm fastapi uvicorn httpx httpx-sse \
    structlog loguru pydantic python-dotenv \
    tenacity rich typer

3. 環境を設定する

cp .env.example .env
nano .env   # fill in your values

GITHUB_PAT=ghp_your_token_here
GITHUB_REPO_OWNER=your-username
GITHUB_REPO_NAME=your-repo
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=deepseek-r1:14b
CREWAI_TELEMETRY_OPT_OUT=true
OTEL_SDK_DISABLED=true
OLLAMA_KEEP_ALIVE=-1

4. GitHub PAT を作成する

次に移動します：github.com → Settings → Developer settings → Personal access tokens → Tokens (classic)

スコープで repo（フルアクセス）を有効にします

5. Claude Desktop に登録する

~/Library/Application Support/Claude/claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "mcp-log-analyzer": {
      "command": "/path/to/mcp-log-analyzer/.venv/bin/python",
      "args": ["/path/to/mcp-log-analyzer/mcp_server/server.py"],
      "env": {
        "GITHUB_PAT": "ghp_your_token",
        "GITHUB_REPO_OWNER": "your-username",
        "GITHUB_REPO_NAME": "your-repo",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "OLLAMA_MODEL": "deepseek-r1:14b"
      }
    }
  }
}

Claude Desktop を再起動します。🔨 ツールアイコンが表示されます。

---

使い方

Claude Desktop 経由（自然言語）

analyze the log file at /var/log/app.log and file GitHub issues for any errors

use analyze_log_file with path="/var/log/app.log" dry_run=true

check status of job abc12345

Python CLI 経由

source .venv/bin/activate

python3 -c "
from dotenv import load_dotenv
load_dotenv()
from mcp_server.tools.analyze_tool import analyze_log_file
import asyncio, json

result = asyncio.run(analyze_log_file({
    'path': '/var/log/app.log',
    'severity': 'ERROR',
    'dry_run': False
}))
print(result[0].text)
"

---

MCP ツールのリファレンス

ping

ヘルスチェックを行い、サーバーと Ollama が実行中であることを確認します。

{}

戻り値： "mcp-log-analyzer online — Ollama: deepseek-r1:14b"

---

analyze_log_file

ログ分析を非同期で開始します。ジョブ ID をすぐに返し、パイプラインはバックグラウンドで実行されます。

パラメーター	型	必須	デフォルト	説明
path	string	✅	—	ログファイルの絶対パス
severity	string	—	ERROR	最低重大度：WARN、ERROR、CRITICAL
dry_run	boolean	—	false	GitHub に登録せずに Issue をプレビュー

戻り値：

{
  "job_id": "abc12345",
  "status": "started",
  "message": "Analysis started. Check progress with get_job_status('abc12345')."
}

---

get_job_status

実行中の分析ジョブのステータスを確認します。

パラメーター	型	必須	説明
job_id	string	✅	analyze_log_file が返したジョブ ID

戻り値（実行中）：

{
  "status": "running",
  "job_id": "abc12345",
  "lines_filtered": 487,
  "chunks": 1
}

戻り値（完了）：

{
  "status": "done",
  "job_id": "abc12345",
  "lines_filtered": 487,
  "unique_events": 4,
  "chunks": 1,
  "issues_filed": 2,
  "github_issues": [
    {
      "title": "[CRITICAL][minting-service] DB connection pool exhausted (x117)",
      "url": "https://github.com/your-org/your-repo/issues/42",
      "number": 42
    }
  ]
}

---

互換性のある MCP クライアント

クライアント	トランスポート	設定
Claude Desktop	stdio	claude_desktop_config.json
Claude Code CLI	stdio	プロジェクトルートの .mcp.json
Cursor	stdio または HTTP+SSE	.cursor/mcp.json
LangChain	HTTP+SSE	url: http://localhost:8000/sse
n8n	HTTP+SSE	HTTP Request ノード → SSE

HTTP+SSE トランスポート（Cursor、LangChain、n8n 用）

python mcp_server/server.py --transport sse --port 8000

---

Skills によるカスタマイズ

Skills は、スタック固有のエラーパターンをエージェントに教える、プレーンな英語で書かれた .md ファイルです。このプロジェクトには、次の 3 つの組み込み Skill が含まれています。

Skill	用途
skills/nft-app-errors.skill.md	NFT／ブロックチェーンのエラー分類
skills/infrastructure-errors.skill.md	インフラストラクチャエラーの分類
skills/bug-composition.skill.md	GitHub Issue の形式ルール

独自の Skill を作成する

skills/my-stack-errors.skill.md を作成します：

# My Stack Error Classification

## CRITICAL — file bug immediately
- "FATAL: database connection refused" = service down
- "out of memory" = process crash imminent

## HIGH — file bug, non-urgent  
- "connection timeout" on external API = degraded performance

## IGNORE — known false positives
- "reconnecting..." during deploys = expected

次に、agents/crew.py で読み込みます：

_load_skill("my-stack-errors.skill.md")

---

パイプラインの内部構造

500MB log file
    ↓  ripgrep (2-4 seconds)
    ↓  Filters: ERROR|FATAL|CRITICAL|WARN|Exception|Traceback
~5MB of error lines
    ↓  mmap streaming parser
    ↓  LogEvent objects with timestamp, level, component, message
    ↓  Deduplicator (fingerprints strip req_id, numbers, hex)
4-20 unique error patterns
    ↓  Chunker (10 events per chunk, CRITICAL first)
1-3 chunks
    ↓  Single CrewAI agent → Ollama (local)
    ↓  Structured bug reports in markdown
    ↓  Title extractor + label classifier
    ↓  Duplicate check via GitHub search API
GitHub Issues filed

---

パフォーマンス

Apple Silicon（M2、32GB）でテスト済み：

ファイルサイズ	フィルタリング時間	分析時間	合計
10MB	<1s	3-5 min	~5 min
100MB	1-2s	3-5 min	~7 min
500MB	3-5s	5-10 min	~15 min

分析時間はファイルサイズではなく、検出されたエラーパターンの種類数によって異なります。

---

トラブルシューティング

症状	対処法
ollama ps の結果が空	ollama run deepseek-r1:14b を実行してから /bye を入力し、モデルをウォームアップします
Claude Desktop で MCP サーバーが切断される	~/Library/Logs/Claude/mcp-server-*.log を確認して、Python エラーを調べます
Issues filed: 0	claude_desktop_config.json の GITHUB_PAT がプレースホルダーではなく、有効なトークンであることを確認します
600s 経過後にタイムアウトする	.env に OLLAMA_KEEP_ALIVE=-1 を追加し、Ollama を再起動します
crewai のインストールに失敗する	Python 3.11 が必要です。3.13/3.14 には対応していません
/usr/local/bin でアクセスが拒否される	Apple Silicon では代わりに /opt/homebrew/bin/ を使用します

---

ロードマップ

v1（現在）

• ローカルファイルシステムからのログ取り込み
• ripgrep + mmap パイプライン
• 単一エージェントによる CrewAI 分析
• 重複排除付き GitHub Issues 登録
• Claude Desktop + stdio MCP トランスポート

v2（予定）

• Datadog MCP 統合
• Splunk MCP 統合
• HTTP+SSE トランスポート（Cursor、LangChain、n8n）
• 分析の定期実行トリガー
• 並列チャンク処理
• ジョブ履歴用ウェブダッシュボード

---

コントリビューション

コントリビューションを歓迎します。特に、さまざまなスタック向けの新しいスキルファイルをお待ちしています。

1. リポジトリをフォークします
2. skills/your-stack-errors.skill.md を作成します
3. 実際のログファイルでテストします
4. 出力例を添えて PR を作成します

---

ライセンス

MIT — LICENSE を参照