What is Coralogix Mcp

Coralogix MCP is a Model Context Protocol server that connects to Coralogix logs, providing tools for AI assistants to query and analyze log data efficiently.

Use cases

Use cases include debugging applications by analyzing error logs, visualizing system interactions through sequence diagrams, and monitoring user behavior for insights.

How to use

To use Coralogix MCP, clone the repository, install dependencies using npm, and set up your environment variables in a .env file with your Coralogix API details.

Key features

Key features include log querying and analysis with Lucene syntax, advanced visualization capabilities, user activity analysis, data validation with TypeScript, and RESTful API integration.

Where to use

Coralogix MCP can be used in software development, IT operations, and any environment where log data analysis and troubleshooting are essential.

Coralogix MCP Server

This is an MCP (Model Context Protocol) server that connects to Coralogix logs, providing tools for AI assistants (like Cursor or Claude Desktop) to query and analyze log data. The server enables powerful log analysis, visualization, and troubleshooting capabilities through a simple interface.

Features

Log Querying and Analysis

• Query logs using Lucene syntax (query_logs)
• Search for specific error messages (search_logs_by_error)
• Find logs related to specific functions (find_logs_by_function)
• Advanced filtering by application name and subsystem
• Customizable time ranges for queries
• Pagination and result limiting

Visualization

• Generate sequence diagrams from log flows (generate_sequence_diagram)
• Support for Mermaid diagram syntax
• Customizable diagram titles and timestamps
• Thread-based grouping options
• Visual representation of system interactions

User Analysis

• Extract user lists from logs (extract_users_list)
• Configurable user identifier fields
• Aggregation of user activities
• Pattern recognition in user behaviors

Data Validation and Type Safety

• Runtime validation using Zod schemas
• Strong TypeScript type checking
• Comprehensive error handling
• Input sanitization and validation

Integration Features

• RESTful API integration with Coralogix
• Environment-based configuration
• Flexible authentication handling
• Rate limiting and request optimization

Setup

1. Clone the repository (if you haven’t already).

2. Install dependencies:

   npm install
   

3. Set up environment variables:
   Create a .env file in the project root (copy from .env.template) and fill in your Coralogix details:

   # Coralogix API endpoint (Check documentation for your region)
   CORALOGIX_API_URL=https://api.coralogix.com/api/v2/dataprime/query
   # Your Coralogix API Key (Logs Query Key)
   CORALOGIX_API_KEY=your_api_key_here
   # Optional: Default application name to filter logs
   CORALOGIX_APP_NAME=
   # Optional: Default subsystem name to filter logs
   CORALOGIX_SUBSYSTEM_NAME=
   

4. Build the TypeScript code:

   npm run build
   

Available Tools

1. Query Logs

Query Coralogix logs using Lucene syntax:

{
  query: string;        // Lucene query string
  timeframe: string;    // e.g., "last 24h", "last 7d"
  applicationName?: string;
  subsystemName?: string;
  limit?: number;
  offset?: number;      // For pagination
  sortBy?: string;      // Field to sort by
  sortOrder?: 'asc' | 'desc';
}

2. Search Logs by Error

Search for specific error messages with context:

{
  errorMessage: string; // Error message to search for
  timeframe: string;    // e.g., "last 24h", "last 7d"
  includeStackTrace?: boolean;
  contextLines?: number; // Number of lines before/after error
  severity?: string;    // Error severity level
}

3. Find Logs by Function

Find logs related to specific functions with advanced filtering:

{
  functionName: string; // Function name to search for
  filePath?: string;   // Optional file path
  timeframe?: string;  // e.g., "last 24h", "last 7d"
  includeParams?: boolean; // Include function parameters
  includeReturns?: boolean; // Include return values
  stackDepth?: number; // Stack trace depth
}

4. Generate Sequence Diagram

Generate Mermaid sequence diagrams from log flows:

{
  query: string;       // Lucene query to filter logs
  timeframe: string;   // e.g., "last 24h", "last 7d"
  title?: string;      // Diagram title
  showTimestamps?: boolean;
  groupByThread?: boolean;
  excludePatterns?: string[]; // Patterns to exclude
  includePatterns?: string[]; // Patterns to include
  style?: {
    theme?: string;    // Diagram theme
    wrap?: boolean;    // Text wrapping
    boxed?: boolean;   // Box around participants
  }
}

5. Extract Users List

Extract and analyze user information from logs:

{
  timeframe: string;   // e.g., "last 24h", "last 7d"
  query: string;       // Lucene query to filter logs
  userIdentifierField?: string; // Field containing user ID
  aggregations?: {     // Optional aggregations
    byAction?: boolean;
    byTimestamp?: boolean;
    byStatus?: boolean;
  };
  includeMetadata?: boolean; // Include user metadata
}

Development

Running in Development Mode

npm run dev

Testing

# Run unit tests
npm test

# Run tests with coverage
npm run test:coverage

# Run integration tests
npm run test:integration

Debugging

The server supports various debug modes:

# Enable debug logging
DEBUG=coralogix-mcp:* npm run dev

# Debug specific components
DEBUG=coralogix-mcp:api npm run dev
DEBUG=coralogix-mcp:diagram npm run dev

Project Structure

src/
├── index.ts              # Main server entry point
├── coralogix-client.ts   # Coralogix API client
├── sequence-diagram.ts   # Sequence diagram generation
├── types.ts             # TypeScript interfaces and Zod schemas
├── utils/
│   ├── validation.ts    # Input validation utilities
│   ├── formatting.ts    # Output formatting utilities
│   └── errors.ts       # Error handling utilities
└── services/
    ├── log-service.ts   # Log querying service
    ├── diagram-service.ts # Diagram generation service
    └── user-service.ts  # User analysis service

Error Handling

The server implements comprehensive error handling:

• Input validation errors
• API connection errors
• Rate limiting errors
• Authentication errors
• Processing errors

Each error returns a structured response with:

• Error code
• Human-readable message
• Suggested resolution
• Request context (where applicable)

Performance Considerations

• Implements request caching
• Optimizes large result sets
• Supports streaming for large responses
• Implements connection pooling
• Handles rate limiting gracefully

License

MIT