# SumoLogic MCP Server

> **Transform SumoLogic interactions with natural language** - A Model Context Protocol (MCP) server that makes SumoLogic operations as simple as asking questions in plain English.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)

## 🚀 What Makes This Special

This isn't just another API wrapper. With **contextual awareness** powered by `sumologic-context.json`, you can interact with SumoLogic using natural language that understands your specific environment, resources, and common queries.

### Before vs After

**Before (Traditional API):**
```bash
# Complex API calls with exact syntax
curl -X POST "https://api.sumologic.com/api/v1/search/jobs" \
  -H "Authorization: Basic <encoded>" \
  -d '{"query":"_sourceCategory=webapp | count by _sourceHost", "from":"2024-01-01T00:00:00", "to":"2024-01-01T23:59:59"}'
```

**After (Natural Language with Context):**
```
"Show me error counts from our production web servers yesterday"
"Which collectors are having ingestion issues?"
"Create a dashboard for our new microservice deployment"
```

## 🎯 Key Features

### 🧠 **Contextual Intelligence**
The `sumologic-context.json` configuration transforms basic API access into an intelligent assistant that knows:
- Your specific collectors and their purposes
- Common queries and their business meaning
- Resource relationships and dependencies
- Team-specific terminology and workflows

### 🔧 **Complete SumoLogic Operations**
- **Connection Management**: Verify connectivity and health
- **Collectors & Sources**: Create, manage, and monitor data ingestion
- **Search & Analytics**: Execute complex queries with natural language
- **Monitors & Alerts**: Manage monitoring configurations
- **Dashboards**: Create and update visualizations

### 💬 **Natural Language Interface**
Ask questions like:
- *"What's the error rate for our payment service this week?"*
- *"Show me slow database queries from the last hour"*
- *"Create a collector for our new Kubernetes cluster"*
- *"Are there any critical alerts I should know about?"*

## 🌟 The Power of sumologic-context.json

### What is Contextual Awareness?

The `sumologic-context.json` file is your secret weapon. It teaches the MCP server about **your specific SumoLogic environment**, enabling incredibly intuitive interactions.

### Real-World Context Configuration

```json
{
  "version": "1.0",
  "organization": "acme-corp",
  "environments": {
    "production": {
      "applications": {
        "web-frontend": {
          "sourceCategory": "prod/web/frontend",
          "sourceName": "nginx-*",
          "description": "Production web frontend servers (Nginx)",
          "commonFilters": ["_sourceHost=web-prod-*"],
          "sampleQueries": [
            "_sourceCategory=\"prod/web/frontend\" | where status_code >= 400",
            "_sourceCategory=\"prod/web/frontend\" | timeslice 1m | count by status_code",
            "_sourceCategory=\"prod/web/frontend\" | json field=response_time | avg(response_time)"
          ]
        },
        "api-backend": {
          "sourceCategory": "prod/api/backend", 
          "sourceName": "api-server-*",
          "description": "Production API backend services",
          "commonFilters": ["_sourceHost=api-prod-*"],
          "sampleQueries": [
            "_sourceCategory=\"prod/api/backend\" error OR exception",
            "_sourceCategory=\"prod/api/backend\" | json field=response_time | avg(response_time) by endpoint",
            "_sourceCategory=\"prod/api/backend\" | where status_code = 500"
          ]
        },
        "mobile-app": {
          "sourceCategory": "prod/mobile/app",
          "sourceName": "mobile-api-*",
          "description": "Production mobile application backend",
          "commonFilters": ["_sourceHost=mobile-prod-*"],
          "sampleQueries": [
            "_sourceCategory=\"prod/mobile/app\" crash OR exception",
            "_sourceCategory=\"prod/mobile/app\" | json field=user_id | count by user_id"
          ]
        }
      },
      "infrastructure": {
        "database": {
          "sourceCategory": "prod/database/postgresql",
          "sourceName": "postgres-*",
          "description": "Production PostgreSQL database logs",
          "commonFilters": ["_sourceHost=db-prod-*"],
          "sampleQueries": [
            "_sourceCategory=\"prod/database/postgresql\" slow query",
            "_sourceCategory=\"prod/database/postgresql\" | where duration > 1000"
          ]
        },
        "kubernetes": {
          "sourceCategory": "prod/k8s/containers",
          "sourceName": "k8s-*",
          "description": "Production Kubernetes cluster logs",
          "commonFilters": ["_sourceHost=k8s-*"],
          "namespaces": ["default", "production", "monitoring", "ingress-nginx"]
        }
      }
    },
    "staging": {
      "applications": {
        "web-frontend": {
          "sourceCategory": "staging/web/frontend",
          "sourceName": "nginx-staging-*",
          "description": "Staging web frontend servers"
        },
        "api-backend": {
          "sourceCategory": "staging/api/backend", 
          "sourceName": "api-staging-*",
          "description": "Staging API backend services"
        }
      }
    }
  },
  "shortcuts": {
    "errors": {
      "description": "Find error messages and exceptions",
      "queryTemplate": "error OR exception OR fatal OR \"stack trace\" OR \"internal server error\"",
      "timeRange": "-15m"
    },
    "performance": {
      "description": "Performance monitoring with configurable threshold",
      "queryTemplate": "response_time OR duration OR latency | where ${metric} > ${threshold}",
      "defaultParams": {
        "metric": "response_time", 
        "threshold": "1000"
      },
      "timeRange": "-1h"
    },
    "security": {
      "description": "Security-related events and authentication failures",
      "queryTemplate": "authentication OR authorization OR \"access denied\" OR \"unauthorized\"",
      "timeRange": "-1h"
    },
    "database-slow": {
      "description": "Slow database queries",
      "queryTemplate": "\"slow query\" OR (duration > ${threshold}) OR \"query timeout\"",
      "defaultParams": {
        "threshold": "5000"
      },
      "timeRange": "-30m"
    }
  },
  "commonFields": {
    "timestamp_field": "@timestamp",
    "host_field": "_sourceHost",
    "service_field": "service_name",
    "environment_field": "environment",
    "log_level_field": "level"
  }
}
```

### Contextual Examples in Action

With this sophisticated context configuration, see how natural and powerful these interactions become:

#### Example 1: Multi-Environment Error Analysis
**You ask:** *"Compare error rates between production and staging web frontend"*

**AI intelligently:**
1. Identifies `web-frontend` in both `production` and `staging` environments
2. Uses context-aware queries:
   - Production: `_sourceCategory="prod/web/frontend" | where status_code >= 400`
   - Staging: `_sourceCategory="staging/web/frontend" | where status_code >= 400`  
3. Applies appropriate time ranges and provides comparative analysis
4. Reports: *"Production web frontend: 0.2% error rate (normal), Staging: 1.1% error rate (elevated - likely from recent deployment testing)"*

#### Example 2: Infrastructure Health Check
**You ask:** *"How is our Kubernetes cluster performing?"*

**AI automatically:**
1. Maps "Kubernetes cluster" to `prod/k8s/containers` source category
2. Checks across configured namespaces: `default`, `production`, `monitoring`, `ingress-nginx`
3. Applies infrastructure-specific filters: `_sourceHost=k8s-*`
4. Uses sample queries for container health and resource usage
5. Responds: *"K8s cluster healthy: 247 running pods across 4 namespaces. No resource constraints detected in production namespace."*

#### Example 3: Smart Shortcut Usage  
**You ask:** *"Show me slow database queries from the last hour"*

**AI leverages shortcuts:**
1. Recognizes "slow database queries" maps to `database-slow` shortcut
2. Applies the template: `"slow query" OR (duration > 5000) OR "query timeout"`
3. Targets PostgreSQL logs: `_sourceCategory="prod/database/postgresql"`
4. Uses default threshold (5000ms) and custom time range (-1h)
5. Results: *"Found 12 slow queries in the last hour. Average duration: 7.2s. Most frequent: user authentication queries."*

#### Example 4: Cross-Service Performance Analysis
**You ask:** *"What's causing the mobile app performance issues?"*

**AI performs comprehensive analysis:**
1. Identifies `mobile-app` application context
2. Runs mobile-specific queries: `_sourceCategory="prod/mobile/app" crash OR exception`  
3. Cross-references with `api-backend` performance: `avg(response_time) by endpoint`
4. Checks `database` logs for related slow queries
5. Synthesizes findings: *"Mobile app shows 15% increase in crash rate. Root cause: API endpoint /user/profile averaging 3.2s response time due to database connection pool exhaustion."*

#### Example 5: Security Incident Response
**You ask:** *"Check for any security issues in the last hour"*

**AI uses security shortcut:**
1. Applies `security` shortcut template across all production applications
2. Searches: `authentication OR authorization OR "access denied" OR "unauthorized"`
3. Scans web-frontend, api-backend, and mobile-app simultaneously
4. Correlates findings across services
5. Reports: *"Security alert: 47 unauthorized access attempts detected on API backend from IP 192.168.1.100. Web frontend shows corresponding 403 responses."*

## 📋 Prerequisites

- **Node.js 20+** (LTS recommended)
- **SumoLogic account** with API access
- **API credentials** (Access ID and Key)
- **Docker** (optional, for containerized deployment)

## ⚡ Quick Start

### 1. Installation

```bash
git clone https://github.com/greyaperez/mcp-sumologic.git
cd mcp-sumologic
npm install
```

### 2. Configuration

```bash
# Copy environment template
cp .env.example .env
```

Edit `.env` with your SumoLogic credentials:

```env
SUMOLOGIC_ACCESS_ID=your_access_id
SUMOLOGIC_ACCESS_KEY=your_access_key
SUMOLOGIC_API_ENDPOINT=https://api.us2.sumologic.com/api
SUMOLOGIC_CONTEXT_CONFIG=./sumologic-context.json
SUMOLOGIC_DEFAULT_TIMEZONE=UTC
```

### 3. Create Your Context File

Create `sumologic-context.json` with your environment details:

```json
{
  "version": "1.0",
  "organization": "your-org",
  "environments": {
    "production": {
      "applications": {
        "web-frontend": {
          "sourceCategory": "prod/web/frontend",
          "sourceName": "nginx-*",
          "description": "Production web frontend servers",
          "commonFilters": ["_sourceHost=web-prod-*"],
          "sampleQueries": [
            "_sourceCategory=\"prod/web/frontend\" | where status_code >= 400"
          ]
        }
      },
      "infrastructure": {
        "database": {
          "sourceCategory": "prod/database/postgresql",
          "sourceName": "postgres-*", 
          "description": "Production PostgreSQL database logs",
          "commonFilters": ["_sourceHost=db-prod-*"]
        }
      }
    }
  },
  "shortcuts": {
    "errors": {
      "description": "Find error messages and exceptions",
      "queryTemplate": "error OR exception OR fatal",
      "timeRange": "-15m"
    }
  },
  "commonFields": {
    "timestamp_field": "@timestamp",
    "host_field": "_sourceHost",
    "service_field": "service_name"
  }
}
```

### 4. Run the Server

```bash
# Development mode
npm run dev

# Production mode
npm run build && npm start
```

## 🐳 Docker Deployment

### Build and Run

```bash
# Build image
docker build -t mcp/sumologic .

# Run with environment variables
docker run -i --rm \
  -e SUMOLOGIC_ACCESS_ID="your_access_id" \
  -e SUMOLOGIC_ACCESS_KEY="your_access_key" \
  -e SUMOLOGIC_API_ENDPOINT="https://api.us2.sumologic.com/api" \
  -e SUMOLOGIC_CONTEXT_CONFIG="./sumologic-context.json" \
  -e SUMOLOGIC_DEFAULT_TIMEZONE="UTC" \
  mcp/sumologic
```

## 🔧 Claude Desktop Integration

Add to your Claude Desktop configuration:

### Option 1: Direct Node.js

```json
{
  "mcpServers": {
    "sumologic": {
      "command": "node",
      "args": ["/path/to/mcp-sumologic/dist/index.js"],
      "env": {
        "SUMOLOGIC_ACCESS_ID": "your_access_id",
        "SUMOLOGIC_ACCESS_KEY": "your_access_key",
        "SUMOLOGIC_API_ENDPOINT": "https://api.us2.sumologic.com/api",
        "SUMOLOGIC_CONTEXT_CONFIG": "./sumologic-context.json",
        "SUMOLOGIC_DEFAULT_TIMEZONE": "UTC"
      }
    }
  }
}
```

### Option 2: Docker

```json
{
  "mcpServers": {
    "sumologic": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SUMOLOGIC_ACCESS_ID",
        "-e", "SUMOLOGIC_ACCESS_KEY",
        "-e", "SUMOLOGIC_API_ENDPOINT",
        "-e", "SUMOLOGIC_CONTEXT_CONFIG",
        "-e", "SUMOLOGIC_DEFAULT_TIMEZONE",
        "mcp/sumologic"
      ],
      "env": {
        "SUMOLOGIC_ACCESS_ID": "your_access_id",
        "SUMOLOGIC_ACCESS_KEY": "your_access_key",
        "SUMOLOGIC_API_ENDPOINT": "https://api.us2.sumologic.com/api",
        "SUMOLOGIC_CONTEXT_CONFIG": "./sumologic-context.json",
        "SUMOLOGIC_DEFAULT_TIMEZONE": "UTC"
      }
    }
  }
}
```

## 🛠️ Available Tools

| Tool | Description | Context-Aware |
|------|-------------|---------------|
| `check_connection` | Verify API connectivity | ✅ |
| `list_collectors` | List all collectors with business context | ✅ |
| `get_collector` | Get collector details with relationship info | ✅ |
| `create_hosted_collector` | Create collector with smart defaults | ✅ |
| `update_collector` | Update collector properties | ✅ |
| `delete_collector` | Delete collector with impact analysis | ✅ |
| `list_sources` | List sources with purpose descriptions | ✅ |
| `get_source` | Get source details with context | ✅ |
| `create_http_source` | Create HTTP source with templates | ✅ |
| `start_search_job` | Execute searches with query suggestions | ✅ |
| `check_search_job_status` | Check search status | ✅ |
| `get_search_job_results` | Get results with business interpretation | ✅ |
| `list_monitors` | List monitors with business impact | ✅ |
| `get_monitor` | Get monitor details with context | ✅ |

## 💡 Best Practices for Context Configuration

### 1. **Organize by Environment and Service Type**
```json
{
  "environments": {
    "production": {
      "applications": {
        "web-frontend": {
          "sourceCategory": "prod/web/frontend",
          "description": "Production web frontend servers (Nginx)",
          "commonFilters": ["_sourceHost=web-prod-*"]
        }
      },
      "infrastructure": {
        "database": {
          "sourceCategory": "prod/database/postgresql", 
          "description": "Production PostgreSQL database logs"
        }
      }
    }
  }
}
```

### 2. **Include Real SumoLogic Queries**
```json
{
  "sampleQueries": [
    "_sourceCategory=\"prod/web/frontend\" | where status_code >= 400",
    "_sourceCategory=\"prod/api/backend\" | json field=response_time | avg(response_time) by endpoint"
  ]
}
```

### 3. **Create Reusable Query Shortcuts**
```json
{
  "shortcuts": {
    "performance": {
      "description": "Performance monitoring with configurable threshold",
      "queryTemplate": "response_time OR duration OR latency | where ${metric} > ${threshold}",
      "defaultParams": {
        "metric": "response_time", 
        "threshold": "1000"
      },
      "timeRange": "-1h"
    }
  }
}
```

### 4. **Standardize Field Mappings**
```json
{
  "commonFields": {
    "timestamp_field": "@timestamp",
    "host_field": "_sourceHost", 
    "service_field": "service_name",
    "environment_field": "environment",
    "log_level_field": "level"
  }
}
```

### 5. **Use Consistent Naming Patterns**
- **Source Categories**: `{env}/{service-type}/{service-name}`
- **Source Names**: `{service}-{env}-*` (e.g., `nginx-prod-*`)
- **Host Filters**: `_sourceHost={service}-{env}-*`

## 🔍 Usage Examples

### Environment-Aware Queries
```
"Show me errors in production web frontend"
"Compare API performance between staging and production"  
"Check database health in all environments"
```

### Shortcut-Powered Analysis
```
"Run security check for the last hour"
"Find slow database queries with default threshold"
"Show performance issues with response time over 2000ms"
```

### Infrastructure Intelligence
```
"How is our Kubernetes cluster doing?"
"Check Redis cache hit rates in production"
"Show load balancer health across all environments"
```

### Cross-Service Correlation  
```
"Is the mobile app backend causing the database slowdown?"
"Compare error rates between web frontend and API backend"
"Show the full request flow from load balancer to database"
```

### Proactive Management
```
"Create a monitor for API response times over 1 second"
"Set up alerting for Kubernetes pod crashes"
"Monitor database connection pool exhaustion"
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

**Ready to transform your SumoLogic experience?** Start with a simple context file and watch as complex operations become as easy as asking questions! 🚀