Nft Log Analyser

🔍 NFT 日志分析器

AI 驱动的日志分析，可自动创建 GitHub Issue——通过 Ollama 完全在本地运行，数据绝不离开你的设备。

---

功能

指定任意日志文件后，它会：

1. 扫描 使用 ripgrep 在数秒内处理 500MB 以上的文件
2. 解析 错误模式，并对重复事件去重
3. 分析 通过 CrewAI Agent 使用本地大模型（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	预览 Issue，但不提交到 GitHub

返回：

{
  "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 文件，用于让 Agent 了解你的技术栈中的错误模式。项目内置了三个 Skills：

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 后超时	将 OLLAMA_KEEP_ALIVE=-1 添加到 .env，然后重启 Ollama
crewai 安装失败	需要 Python 3.11——与 3.13/3.14 不兼容
/usr/local/bin 权限被拒绝	在 Apple Silicon 上改用 /opt/homebrew/bin/

---

路线图

v1（当前）

• 本地文件系统日志摄取
• ripgrep + mmap 流程
• CrewAI 单 Agent 分析
• 创建 GitHub Issues 并进行去重
• Claude Desktop + stdio MCP 传输

v2（计划中）

• Datadog MCP 集成
• Splunk MCP 集成
• HTTP+SSE 传输（Cursor、LangChain、n8n）
• 定时分析触发器
• 并行分块处理
• 作业历史网页面板

---

贡献

欢迎贡献，尤其是为不同技术栈编写新的技能文件。

1. Fork 此仓库
2. 创建 skills/your-stack-errors.skill.md
3. 使用真实日志文件进行测试
4. 提交包含示例输出的 PR

---

许可证

MIT——请参阅 LICENSE