# Log Analyzer MCP Server

A Model Context Protocol (MCP) server that connects to the Log Collector API to query and analyze logs from multiple remote Unix hosts.

## Features

- MCP server implementation for Claude Desktop and other MCP clients
- Query logs from multiple hosts via REST API
- Advanced log analysis (errors, warnings, patterns)
- Search across multiple hosts and processes
- Statistical analysis of log content
- Summary generation

## Installation

1. Create a virtual environment:
```bash
cd log-analyzer-mcp
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

2. Install dependencies:
```bash
pip install -r requirements.txt
```

3. Configure environment variables:
```bash
cp .env.example .env
# Edit .env with your Log Collector API URL
```

## Configuration

### Environment Variables (.env)

```env
LOG_API_BASE_URL=http://localhost:8000
LOG_API_TIMEOUT=30
```

## Running the MCP Server

### Standalone Mode

```bash
python -m log_analyzer_mcp.server
```

### As an MCP Server (for Claude Desktop)

Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "log-analyzer": {
      "command": "python",
      "args": ["-m", "log_analyzer_mcp.server"],
      "env": {
        "LOG_API_BASE_URL": "http://localhost:8000",
        "LOG_API_TIMEOUT": "30"
      }
    }
  }
}
```

Or if installed as a package:

```json
{
  "mcpServers": {
    "log-analyzer": {
      "command": "log-analyzer-mcp"
    }
  }
}
```

## Available MCP Tools

### 1. list_hosts

Lists all configured hosts and their processes.

**Parameters**: None

**Usage in Claude**:
```
List all available hosts
```

### 2. get_logs

Get logs from a specific host with optional process filtering.

**Parameters**:
- `host_name` (required): Name of the host
- `process` (optional): Filter by process name
- `lines` (optional): Number of lines to retrieve (default: 100)
- `tail` (optional): Get last N lines (default: true)

**Usage in Claude**:
```
Get the last 200 lines from app-server-1
Show logs from app-server-1 for the app1 process
```

### 3. get_all_logs

Get logs from all configured hosts.

**Parameters**:
- `lines` (optional): Number of lines per file (default: 100)
- `tail` (optional): Get last N lines (default: true)

**Usage in Claude**:
```
Get logs from all hosts
Show recent logs from all servers
```

### 4. search_logs

Search for a pattern across logs.

**Parameters**:
- `pattern` (required): Search pattern (case-insensitive)
- `host` (optional): Filter by host name
- `process` (optional): Filter by process name
- `lines` (optional): Number of lines to search (default: 1000)

**Usage in Claude**:
```
Search for "ERROR" in all logs
Find "connection timeout" in app-server-1
Search for "failed" in the database process
```

### 5. analyze_logs

Analyze logs and get detailed statistics.

**Parameters**:
- `host_name` (required): Name of the host
- `process` (optional): Filter by process name
- `lines` (optional): Number of lines to analyze (default: 500)

**Usage in Claude**:
```
Analyze logs from app-server-1
Give me statistics on the app1 process logs
```

### 6. find_errors

Find all error messages in logs.

**Parameters**:
- `host_name` (required): Name of the host
- `process` (optional): Filter by process name
- `lines` (optional): Number of lines to search (default: 1000)

**Usage in Claude**:
```
Find all errors in app-server-1
Show me errors from the database process
```

### 7. get_log_summary

Get a summary of logs including error/warning counts.

**Parameters**:
- `host_name` (required): Name of the host
- `process` (optional): Filter by process name
- `lines` (optional): Number of lines to analyze (default: 500)

**Usage in Claude**:
```
Summarize logs from app-server-1
Give me a summary of the app1 process
```

### 8. search_and_summarize

Search for a pattern across logs and get comprehensive summary in one operation.

**Parameters**:
- `pattern` (required): Search pattern (case-insensitive)
- `host` (optional): Filter by host name
- `process` (optional): Filter by process name
- `lines` (optional): Number of lines to search (default: 1000)

**Returns**:
- Match statistics (total matches, files searched, hosts with matches)
- Error/warning counts in matched results
- Time range analysis (first/last timestamp, duration)
- Process timing breakdown (A-Z duration per process)
- Sample matched lines (preview of first 10 matches)
- Hosts breakdown (match count per host)

**Usage in Claude**:
```
Search for "ERROR" and give me a summary
Find "connection timeout" and analyze the results
Search for "OutOfMemory" and show me process timing
Search for "database" in app-server-1 and summarize
```

**Example Output**:
```
Search and Summary for pattern: 'ERROR'
================================================================================

MATCH STATISTICS
--------------------------------------------------------------------------------
Total matches: 45
Files searched: 8
Hosts with matches: app-server-1, app-server-2
Errors in matches: 45
Warnings in matches: 3

HOSTS BREAKDOWN
--------------------------------------------------------------------------------
  app-server-1: 32 matches
  app-server-2: 13 matches

TIME RANGE ANALYSIS
--------------------------------------------------------------------------------
First: 2024-02-13 10:30:00
Last: 2024-02-13 15:45:30
Span: 5h 15m 30s

PROCESS TIMING (A-Z)
--------------------------------------------------------------------------------

app1:
  Start: 2024-02-13 10:30:00
  End: 2024-02-13 15:45:30
  Duration: 5h 15m 30s
  Entries: 32

web:
  Start: 2024-02-13 11:00:00
  End: 2024-02-13 14:20:15
  Duration: 3h 20m 15s
  Entries: 13

SAMPLE MATCHED LINES
--------------------------------------------------------------------------------
1. 2024-02-13 10:30:00 ERROR: Connection timeout
2. 2024-02-13 10:35:15 ERROR: Retry failed
...
```

## Usage Examples with Claude

### Example 1: Check for Errors Across All Servers

```
User: Are there any errors in our application servers?

Claude: I'll check for errors across all servers.
[Uses find_errors and analyze_logs tools]

Based on the log analysis:
- app-server-1: 5 errors found in the last 1000 lines
- app-server-2: 2 errors found
Most common error: "Database connection timeout"
```

### Example 2: Investigate a Specific Issue

```
User: Search for "OutOfMemory" errors in the app1 process

Claude: [Uses search_logs with pattern="OutOfMemory" and process="app1"]

Found 3 occurrences of OutOfMemory in app1:
- 2026-02-13 10:15:23 - OutOfMemoryError: Java heap space
- 2026-02-13 10:16:45 - OutOfMemoryError: Java heap space
- 2026-02-13 10:18:12 - OutOfMemoryError: Java heap space
```

### Example 3: Get Overview of All Systems

```
User: Give me an overview of all our systems

Claude: [Uses list_hosts and get_log_summary for each host]

System Overview:
1. app-server-1 (192.168.1.10)
   - Processes: app1, app2
   - Last 500 lines: 12 errors, 45 warnings

2. app-server-2 (192.168.1.11)
   - Processes: service
   - Last 500 lines: 2 errors, 8 warnings
```

## Log Analysis Features

The analyzer automatically detects:

### Error Patterns
- ERROR level messages
- Exception stack traces
- FATAL/CRITICAL messages
- "Failed" operations

### Warning Patterns
- WARN/WARNING messages
- Deprecated features
- Potential issues

### Statistics
- Total line count
- Error/warning counts
- Timestamp extraction
- Common message patterns
- Time range analysis

## Architecture

```
┌─────────────────┐
│  Claude Desktop │
│   (MCP Client)  │
└────────┬────────┘
         │
         │ MCP Protocol
         │
┌────────▼────────────┐
│  Log Analyzer MCP   │
│      Server         │
└────────┬────────────┘
         │
         │ HTTP/REST
         │
┌────────▼────────────┐
│  Log Collector API  │
└────────┬────────────┘
         │
         │ SSH (via Jump Server)
         │
┌────────▼────────────┐
│  Unix Hosts         │
│  (Log Files)        │
└─────────────────────┘
```

## Development

### Project Structure

```
log-analyzer-mcp/
├── log_analyzer_mcp/
│   ├── __init__.py
│   ├── server.py           # MCP server implementation
│   ├── api_client.py       # REST API client
│   └── analyzer.py         # Log analysis utilities
├── pyproject.toml          # Package configuration
├── requirements.txt        # Dependencies
├── .env.example           # Environment template
└── README.md
```

### Adding New Tools

1. Add tool definition in `list_tools()` function
2. Implement handler in `call_tool()` function
3. Update documentation

### Testing

```bash
# Test the API client
python -c "from log_analyzer_mcp.api_client import LogCollectorAPIClient; import asyncio; client = LogCollectorAPIClient('http://localhost:8000'); print(asyncio.run(client.get_hosts()))"
```

## Troubleshooting

### MCP Server Not Starting
- Check that the Log Collector API is running
- Verify `LOG_API_BASE_URL` in .env
- Check Python version (>=3.10 required)

### Connection Refused
- Ensure Log Collector API is accessible
- Check firewall settings
- Verify API URL and port

### No Results Returned
- Verify hosts are configured in Log Collector API
- Check SSH connectivity in Log Collector API
- Review API logs for errors

## Integration with Claude Desktop

Once configured, you can use natural language with Claude:

- "Show me recent errors from production"
- "Analyze logs from app-server-1"
- "Search for database connection issues"
- "What's happening on all servers?"
- "Find OutOfMemory errors in the last hour"

Claude will automatically select and use the appropriate MCP tools to fulfill your requests.

## Security Considerations

- The MCP server connects to the REST API (not directly to hosts)
- All SSH security is handled by the Log Collector API
- Use localhost or secure networks for API communication
- Implement authentication on the REST API in production
- Limit log line counts to prevent excessive data transfer

## Prerequisites

1. Log Collector API must be running and accessible
2. Hosts must be configured in the API's `config/hosts.yaml`
3. SSH connectivity must be working (test via API first)
4. Python 3.10 or higher

## License

MIT