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.
Related MCP server: MCP Log Reader
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
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
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
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
