@agimon-ai/log-sink-mcp weekly downloads statistics

log-sink-mcp

AI-powered log analysis MCP server with HTTP ingestion and SQLite storage.

Runtime requirement: Node.js 22.13 or newer. Log storage uses the built-in node:sqlite module, which is unavailable on Node.js 20. Other servers that use this package's /telemetry/node export may run on Node.js 20, but strict engine checks still apply to the installed log-sink package.

Agent integration: skill and CLI

Agent investigations use a log-sink skill and CLI commands, not a dedicated MCP connection. Run from the application's repository so configuration and instance resolution match the existing collector.

log-sink-mcp status
log-sink-mcp logs search 'timeout' --mode fts --limit 20
log-sink-mcp logs trace '<trace-id>'
log-sink-mcp logs agent-issues --global --workflow-run-id '<workflow-run-id>' --limit 20

Use the same local/global instance selector for every query. Query commands reuse stored telemetry without starting a per-agent server. Keep the HTTP/OTEL ingestion service running under its existing lifecycle owner. Never clear logs or restart a shared collector to inspect an incident. The MCP interface documented below remains available for compatibility and transport testing.

Overview

log-sink-mcp provides a complete log analysis solution for AI assistants like Claude. It combines:

• HTTP Server: REST endpoint for log ingestion from any application
• MCP Server: 5 application-focused tools for searching/filtering, tracing, and inspecting logs
• CLI Analysis Commands: Local shell commands for deeper error and agent-issue analysis
• Pi Extension: Ships a Pi extension that exports the agent's own session telemetry into the sink
• SQLite Database: Fast local storage with FTS5 full-text search plus cached local embeddings
• Real-time Analysis: Query logs, trace distributed requests, analyze error patterns

Perfect for debugging, monitoring, and understanding application behavior through AI-powered analysis.

Features

• ✅ HTTP Log Ingestion: POST logs from any application via REST API
• ✅ 5 MCP Tools: Search/filter, trace, agent-issue analysis, and inspect stats/services
• ✅ Agent Telemetry: Pi extension records prompts, turns, tool calls, token usage, and cost
• ✅ Hybrid Search: FTS5-powered search plus optional local semantic retrieval across messages and errors
• ✅ Distributed Tracing: Timeline view for trace IDs and span relationships
• ✅ Error Analysis: Pattern detection and error categorization
• ✅ Structured Logging: JSON metadata, trace IDs, span IDs
• ✅ Auto-Migration: Drizzle ORM with automatic schema migrations
• ✅ Type-Safe: Full TypeScript coverage with Drizzle schema inference

Architecture

┌─────────────┐        HTTP POST         ┌─────────────────┐
│ Application │ ───────────────────────> │  HTTP Server    │
│  (Pino,     │     /logs endpoint       │  (Hono)         │
│  Winston)   │                          │  Port 3100      │
└─────────────┘                          └────────┬────────┘
                                                  │
                                                  ▼
                                         ┌─────────────────┐
                                         │  LogStorage     │
                                         │  Service        │
                                         └────────┬────────┘
                                                  │
                                                  ▼
┌──────────────┐       MCP Protocol      ┌─────────────────┐
│   Claude /   │ <─────────────────────> │   MCP Server    │
│   AI Agent   │    5 App Log Tools      │   (stdio)       │
└──────────────┘                         └────────┬────────┘
                                                  │
                                                  ▼
                                         ┌─────────────────┐
                                         │ SQLite + FTS5 + │
                                         │  local vectors   │
                                         │  ./logs/        │
                                         │  session.db     │
                                         └─────────────────┘

Singleton HTTP Server Management

log-sink-mcp implements automatic singleton coordination to prevent port conflicts when multiple MCP servers run concurrently.

How It Works

1. Service Discovery: When an MCP server starts, it checks .agiflow/registry/log-sink-mcp-http_{env}.json for an existing HTTP server
2. Health Check: Pings /health endpoint to verify the registered server is alive
3. Reuse or Start: If healthy, reuses existing server; otherwise starts a new one
4. PID Tracking: Process IDs stored in .pids/ for lifecycle management
5. Auto-Cleanup: Registry and PID files removed on graceful shutdown

Service Registry Schema

{
  "name": "log-sink-mcp-http",
  "port": 3100,
  "host": "localhost",
  "environment": "development",
  "pid": 12345,
  "status": "running",
  "startedAt": "2026-01-15T10:00:00.000Z",
  "metadata": {
    "healthCheckUrl": "http://localhost:3100/health",
    "dbPath": "./logs/session.db"
  }
}

Management Commands

# Check status of HTTP server
bun run src/cli.ts status

# Stop HTTP server
bun run src/cli.ts stop

# Start with auto-coordination
bun run src/cli.ts start

Installation

# From monorepo root
pnpm install

# Optional: install local embedding support for semantic search
pnpm add ruvector-onnx-embeddings-wasm

# Or install globally
pnpm add -g log-sink-mcp

Semantic embeddings are disabled by default. Set LOG_SINK_ENABLE_EMBEDDINGS=true to enable local model loading and semantic indexing. If ruvector-onnx-embeddings-wasm is not installed, log-sink-mcp still starts and falls back to FTS5 search only.

Quick Start

1. Start the Servers…