marknguyen-myob/sumologic-mcp-server

Sumo Logic Investigation MCP Server

A Model Context Protocol (MCP) server that integrates with Sumo Logic's API to perform log searches and comprehensive error investigation. This server exposes a complete investigation toolkit with 10 tools for log analysis, error pattern detection, stack trace parsing, and user impact analysis.

Features

• Search Sumo Logic logs using custom queries with system presets
• Time range calculation - Parse human-readable time like "past 19 hours"
• Automatic log parsing - Extract structured fields from raw logs
• Stack trace analysis - Parse Ruby, Python, Java, and JavaScript errors
• Error pattern detection - Group similar errors to identify systemic issues
• User impact analysis - Determine blast radius of production issues
• Large result handling - Auto-saves 150+ logs to file with pagination
• Request context - Get complete timeline for any request_id

Prerequisites

• Node.js 18+ or later (required for native fetch API support)
• Sumo Logic account with API access
• Sumo Logic Access ID and Access Key

Installation

1. Clone or navigate to this directory:

cd sumologic-mcp-server

2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

Configuration

Environment Variables

Create a .env file in the project root with your Sumo Logic credentials:

SUMO_ACCESS_ID=your_access_id_here
SUMO_ACCESS_KEY=your_access_key_here
SUMO_ENDPOINT=https://api.sumologic.com/api

Available Tools

1. calculate_time_range

Parse human-readable time descriptions into ISO 8601 timestamps.

Parameters:

• description (required): Human-readable time (e.g., "past 19 hours", "last 7 days")

Example:

{
  "description": "past 19 hours"
}

2. list_systems

List all available systems that can be queried.

Parameters: None

3. search_logs

Enhanced log search with automatic parsing and summaries.

Parameters:

• system (required): System name (e.g., "msuper-bsd", "nebula-production")
• time_from (required): Start time in ISO 8601 format
• time_to (required): End time in ISO 8601 format
• query (optional): Search query (CFID, request_id, keyword)
• severity (optional): Filter by ERROR, WARN, INFO, or DEBUG

Returns:

• summary: Total logs, count by level, has_errors flag
• logs: Parsed logs with timestamp, level, message, request_id, etc.
• Auto-saves to file when 150+ logs returned

4. parse_log_file

Filter and paginate logs from saved files.

Parameters:

• file_path (required): Path to saved log file
• filter_level (optional): Filter by log level
• limit (optional): Max logs to return (default: 100)
• offset (optional): Skip N logs for pagination

5. get_error_context

Get complete timeline for a specific request_id.

Parameters:

• request_id (required): The request_id to track
• system (required): System name
• time_from (required): Start time
• time_to (required): End time
• context_window_minutes (optional): Expand time range (default: 5)

Returns:

• timeline: All logs chronologically sorted
• duration_ms: Request start to finish time
• summary: Error count, entry point, final status
• error_details: First error with full context

6. analyse_error_patterns

Group errors to identify distinct problems.

Parameters:

• logs (required): Array of parsed logs from search_logs
• group_by (optional): message_pattern, status_code, error_type, or path
• min_occurrences (optional): Minimum occurrences to include

Returns:

• groups: Grouped errors with counts and examples
• total_errors: Total error count
• unique_patterns: Number of distinct problems
• most_common: Most frequent error pattern

7. parse_error_stack_trace

Parse stack traces from Ruby, Python, Java, or JavaScript.

Parameters:

• message (required): Error message containing stack trace

Returns:

• error_type: TypeError, RuntimeError, etc.
• error_message: The error description
• root_cause: file, line, method, is_application_code
• stack_frames: Complete call chain
• language: Detected language
• summary: Human-readable summary

8. analyse_user_impact

Determine how many users were affected by errors.

Parameters:

• logs (required): Array of parsed logs
• identifier_field (optional): Field for user ID (default: "cfid")
• system (optional): System name for context

Returns:

• total_unique_users: Count of affected users
• severity_distribution: high/medium/low breakdown
• most_affected_users: Top 10 users with error counts
• impact_by_time: Errors by hour

9. get_next_batch

Get next page of results for pagination.

Parameters:

• job_id (required): Job ID from previous search
• offset (required): Number of records to skip
• limit (optional): Records to return (default: 100)

10. admin-sumologic (Legacy)

Direct Sumo Logic search for backward compatibility.

Parameters:

• query (required): Sumo Logic search query
• from (optional): Start time in ISO 8601
• to (optional): End time in ISO 8601

Quick Start: Error Investigation

Step 1: Get Time Range

calculate_time_range("past 19 hours")
→ Returns validated ISO 8601 timestamps

Step 2: Search for Errors

search_logs(
    system="msuper-bsd",
    time_from="...",
    time_to="...",
    query="cea37eb6-8aee-44ba-9b0e-ac36b7202e3e",
    severity="ERROR"
)

Step 3: Analyse Results

• Few errors? Check messages and status codes directly
• Many errors? Use analyse_error_patterns to group them
• Stack trace? Use parse_error_stack_trace for root cause
• Have request_id? Use get_error_context for timeline
• 150+ logs? Use parse_log_file to filter/paginate

Project Structure

sumologic-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server with tool handlers
│   ├── sumologic-client.ts   # Sumo Logic API client
│   ├── time-utils.ts         # Time parsing utilities
│   ├── systems-config.ts     # System name configuration
│   ├── log-parser.ts         # Log parsing and sanitization
│   ├── stack-trace-parser.ts # Multi-language stack trace parser
│   ├── analysis-utils.ts     # Pattern and impact analysis
│   └── file-storage.ts       # Large result file management
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Troubleshooting

"Unknown system"

Use list_systems to see available systems. Add new systems in systems-config.ts.

"Invalid time description"

Supported formats: "past X hours", "past X days", "past X minutes", "past X weeks"

"No stack trace found"

The parser supports Ruby, Python, Java, and JavaScript. Check the message contains a recognizable stack trace format.

"Search timeout"

Try narrowing your time range or adding more specific filters.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.