NFT Log Analyser

🔍 NFT Log Analyzer

Análisis de logs impulsado por IA que archiva automáticamente Issues de GitHub — 100% local vía Ollama, cero datos salen de tu máquina.

---

Qué Hace

Apúntalo a cualquier archivo de log y:

1. Escanea archivos de más de 500MB en segundos usando ripgrep
2. Analiza patrones de error, deduplica eventos repetidos
3. Examina usando LLM local (Ollama + deepseek-r1:14b) vía agentes CrewAI
4. Redacta Issues de GitHub estructurados con causa raíz y correcciones sugeridas
5. Archiva Issues automáticamente en tu repositorio — omitiendo duplicados

Todo el procesamiento ocurre localmente en tu máquina. El contenido crudo del log nunca sale de tu sistema.

---

Arquitectura

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

---

Requisitos

Requisito	Versión	Notas
Python	3.11+	3.14 no soportado
Ollama	Última	brew install ollama
deepseek-r1:14b	—	~9GB de descarga
ripgrep	Última	brew install ripgrep
RAM	16GB mínimo	32GB recomendado
macOS	Ventura 13+	Apple Silicon recomendado

---

Inicio Rápido

1. Instalar dependencias del sistema

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

2. Clonar y configurar el entorno 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. Configurar el entorno

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. Crear un PAT de GitHub

Ve a: github.com → Settings → Developer settings → Personal access tokens → Tokens (classic)

Habilita el alcance: repo (completo)

5. Registrar con Claude Desktop

Añade a ~/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"
      }
    }
  }
}

Reinicia Claude Desktop. Deberías ver aparecer el icono de herramientas 🔨.

---

Uso

Vía Claude Desktop (lenguaje natural)

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

Vía CLI de Python

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)
"

---

Referencia de Herramientas MCP

ping

Verificación de estado — verifica que el servidor y Ollama estén ejecutándose.

{}

Devuelve: "mcp-log-analyzer online — Ollama: deepseek-r1:14b"

---

analyze_log_file

Inicia análisis de logs asíncrono. Devuelve un ID de trabajo inmediatamente — el pipeline se ejecuta en segundo plano.

Parámetro	Tipo	Requerido	Predeterminado	Descripción
path	string	✅	—	Ruta absoluta al archivo de log
severity	string	—	ERROR	Severidad mínima: WARN, ERROR, CRITICAL
dry_run	boolean	—	false	Vista previa de issues sin archivar en GitHub

Devuelve:

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

---

get_job_status

Verifica el estado de un trabajo de análisis en ejecución.

Parámetro	Tipo	Requerido	Descripción
job_id	string	✅	ID de trabajo devuelto por analyze_log_file

Devuelve (en ejecución):

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

Devuelve (completado):

{
  "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
    }
  ]
}

---

Clientes MCP Compatibles

Cliente	Transporte	Configuración
Claude Desktop	stdio	claude_desktop_config.json
Claude Code CLI	stdio	.mcp.json en la raíz del proyecto
Cursor	stdio o HTTP+SSE	.cursor/mcp.json
LangChain	HTTP+SSE	url: http://localhost:8000/sse
n8n	HTTP+SSE	Nodo HTTP Request → SSE

Transporte HTTP+SSE (para Cursor, LangChain, n8n)

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

---

Personalización con Skills

Los Skills son archivos .md en inglés sencillo que enseñan a los agentes los patrones de error de tu stack. Tres skills integrados vienen con el proyecto:

Skill	Propósito
skills/nft-app-errors.skill.md	Clasificación de errores NFT/blockchain
skills/infrastructure-errors.skill.md	Clasificación de errores de infraestructura
skills/bug-composition.skill.md	Reglas de formato de Issues de GitHub

Escribir tu propio skill

Crea 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

Luego cárgalo en agents/crew.py:

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

---

Internals del Pipeline

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

---

Rendimiento

Probado en Apple Silicon (M2, 32GB):

Tamaño de archivo	Tiempo de filtrado	Tiempo de análisis	Total
10MB	<1s	3-5 min	~5 min
100MB	1-2s	3-5 min	~7 min
500MB	3-5s	5-10 min	~15 min

El tiempo de análisis depende del número de patrones de error únicos encontrados (no del tamaño del archivo).

---

Solución de Problemas

Síntoma	Solución
ollama ps muestra vacío	Ejecuta ollama run deepseek-r1:14b y luego /bye para calentar el modelo
Servidor MCP desconectado en Claude Desktop	Verifica ~/Library/Logs/Claude/mcp-server-*.log para errores de Python
Issues filed: 0	Verifica que GITHUB_PAT en claude_desktop_config.json sea un token real, no un marcador de posición
Tiempo de espera agotado después de 600s	Añade OLLAMA_KEEP_ALIVE=-1 a .env y reinicia Ollama
La instalación de crewai falla	Requiere Python 3.11 — no compatible con 3.13/3.14
Permiso denegado en /usr/local/bin	Usa /opt/homebrew/bin/ en su lugar en Apple Silicon

---

Hoja de Ruta

v1 (actual)

• Ingestión de logs del sistema de archivos local
• Pipeline ripgrep + mmap
• Análisis CrewAI de agente único
• Archivado de Issues de GitHub con deduplicación
• Claude Desktop + transporte MCP stdio

v2 (planificada)

• Integración MCP de Datadog
• Integración MCP de Splunk
• Transporte HTTP+SSE (Cursor, LangChain, n8n)
• Disparadores de análisis programados
• Procesamiento paralelo de fragmentos
• Panel web para historial de trabajos

---

Contribuciones

Las contribuciones son bienvenidas — especialmente nuevos archivos de skill para diferentes stacks.

1. Haz un fork del repositorio
2. Crea skills/your-stack-errors.skill.md
3. Pruébalo contra un archivo de log real
4. Abre un PR con salida de ejemplo

---

Licencia

MIT — ver LICENSE