MCP Logs Assistant

Centralized logging and monitoring for the MCP ecosystem.

Overview

The Logs Assistant provides comprehensive logging and aggregation capabilities for all MCP services with integrated analytics.

Features

• Log Collection: Aggregate logs from all services with in-memory indexing
• Real-time Tail: Follow logs in real-time
• Advanced Search: Query logs by service, level, time, correlation ID, or content
• Time Aggregation: Aggregate logs by minute, hour, or day with statistics
• Error Analysis: Analyze error patterns and trends across services
• Service Health: Monitor service health based on log metrics
• Anomaly Detection: Detect unusual patterns or spikes in log activity
• Correlation Tracking: Trace requests across services with correlation IDs
• Export: Export logs to JSON, CSV, or text formats
• Rotation & Cleanup: Automatic log rotation and retention management

Installation

npm install

Usage

As MCP Server (Claude Desktop)

Configure in Claude Desktop settings:

{
  "mcpServers": {
    "logs": {
      "command": "node",
      "args": ["/path/to/mcp-logs-assistant/index.js"]
    }
  }
}

As HTTP Service

npm start

The service will be available at http://localhost:9103

Available Tools

tail_logs

Follow logs in real-time from specified services.

await client.callTool({
  name: 'tail_logs',
  arguments: {
    service: 'mcp-gateway-assistant', // optional: specific service
    lines: 50 // number of recent lines to show
  }
});

search_logs

Search through logs with advanced filtering.

await client.callTool({
  name: 'search_logs',
  arguments: {
    query: 'error',
    service: 'mcp-gateway-assistant', // optional
    level: 'error', // optional: debug, info, warn, error
    correlationId: 'req-123', // optional: trace specific request
    startTime: '2024-01-01T00:00:00Z', // optional
    endTime: '2024-01-02T00:00:00Z', // optional
    limit: 100
  }
});

get_log_stats

Get statistics about logs.

await client.callTool({
  name: 'get_log_stats', 
  arguments: {
    service: 'mcp-gateway-assistant', // optional
    period: '1h' // 1h, 24h, 7d, 30d
  }
});

rotate_logs

Manually trigger log rotation.

await client.callTool({
  name: 'rotate_logs',
  arguments: {
    service: 'mcp-gateway-assistant' // optional: rotate specific service
  }
});

get_errors

Get recent errors across services.

await client.callTool({
  name: 'get_errors',
  arguments: {
    limit: 50,
    include_stack: true
  }
});

clear_logs

Clear old logs based on retention policy.

await client.callTool({
  name: 'clear_logs',
  arguments: {
    older_than_days: 30,
    dry_run: true // preview what would be deleted
  }
});

Aggregation Tools

aggregate_logs

Aggregate logs by time period with statistics.

await client.callTool({
  name: 'aggregate_logs',
  arguments: {
    period: 'hour', // minute, hour, day
    startTime: '2024-01-01T00:00:00Z',
    endTime: '2024-01-02T00:00:00Z',
    service: 'mcp-gateway-assistant' // optional
  }
});

analyze_errors

Analyze error patterns and trends.

await client.callTool({
  name: 'analyze_errors',
  arguments: {
    service: 'mcp-gateway-assistant', // optional
    timeRange: 86400000, // 24 hours in ms
    minOccurrences: 2 // minimum occurrences to report
  }
});

get_log_statistics

Get comprehensive log statistics.

await client.callTool({
  name: 'get_log_statistics',
  arguments: {
    service: 'mcp-gateway-assistant' // optional
  }
});

find_correlated_logs

Find all logs with a specific correlation ID.

await client.callTool({
  name: 'find_correlated_logs',
  arguments: {
    correlationId: 'req-123-abc'
  }
});

export_logs

Export filtered logs to file.

await client.callTool({
  name: 'export_logs',
  arguments: {
    format: 'json', // json, csv, text
    query: 'error',
    service: 'mcp-gateway-assistant',
    level: 'error',
    startTime: '2024-01-01T00:00:00Z',
    endTime: '2024-01-02T00:00:00Z',
    limit: 1000
  }
});

get_service_health

Analyze service health based on logs.

await client.callTool({
  name: 'get_service_health',
  arguments: {
    service: 'mcp-gateway-assistant',
    timeRange: 3600000 // 1 hour in ms
  }
});

detect_anomalies

Detect anomalies in log patterns.

await client.callTool({
  name: 'detect_anomalies',
  arguments: {
    service: 'mcp-gateway-assistant', // optional
    sensitivity: 5 // 1-10, higher = more sensitive
  }
});

cleanup_old_logs

Clean up logs older than retention period.

await client.callTool({
  name: 'cleanup_old_logs',
  arguments: {
    dryRun: true // preview without deleting
  }
});

Configuration

Aggregator Options

const aggregator = new LogAggregator({
  logsDir: '/path/to/logs',
  aggregateDir: '/path/to/aggregated',
  maxMemoryLogs: 10000, // Max logs to keep in memory
  indexInterval: 60000, // Re-index every minute
  retentionDays: 30 // Keep logs for 30 days
});

Environment Variables

LOG_DIR=~/Documents/mcp-assistant/logs
RETENTION_DAYS=30
INDEX_INTERVAL=60000
MAX_MEMORY_LOGS=10000

Log Format

All services should use structured logging:

{
  "timestamp": "2024-01-01T12:00:00Z",
  "level": "info",
  "service": "mcp-gateway-assistant",
  "message": "Request processed",
  "metadata": {
    "requestId": "abc123",
    "duration": 45,
    "statusCode": 200
  }
}

Data Storage

• Service logs: ~/Documents/mcp-assistant/logs/[service-name]/
• Aggregated data: ~/Documents/mcp-assistant/data/logs-assistant/aggregated/
• Exported logs: ~/Documents/mcp-assistant/data/logs-assistant/aggregated/export-*.{json,csv,text}
• In-memory indices: Service, Correlation ID, Error Type

Development

# Run tests
npm test

# Development mode
npm run dev

# CLI usage
npm run tail -- --service gateway
npm run search -- --query "error" --level error
npm run stats -- --period 24h

Performance Features

Indexing

• Builds indices on startup for fast queries
• Updates indices incrementally every minute
• Maintains separate indices for services, correlations, and errors
• Limits in-memory cache to prevent memory issues

Query Optimization

• Uses indexed lookups for common queries
• Supports time-range filtering
• Implements result pagination
• Caches frequently accessed data

Use Cases

Troubleshooting Service Issues

// Find all errors for a service
const errors = await analyze_errors({
  service: 'mcp-gateway-assistant',
  timeRange: 3600000 // last hour
});

// Check service health
const health = await get_service_health({
  service: 'mcp-gateway-assistant'
});

Request Tracing

// Trace a request across services
const trace = await find_correlated_logs({
  correlationId: 'req-123'
});

Performance Monitoring

// Get hourly aggregations
const metrics = await aggregate_logs({
  period: 'hour',
  startTime: '2024-01-01T00:00:00Z'
});

// Detect anomalies
const anomalies = await detect_anomalies({
  sensitivity: 5
});

Troubleshooting

Slow Queries

• Reduce time range
• Add more specific filters
• Increase cache size if memory allows

Missing Logs

• Check if logs are in expected format
• Verify log directory paths
• Ensure services are writing logs correctly

High Memory Usage

• Reduce maxMemoryLogs setting
• Implement more aggressive retention policies
• Use export and cleanup features regularly